人工智能AI AgentAgent 记忆RAG后端MCP 服务【免费下载链接】honchoMemory library for building stateful agents项目地址https://gitcode.com/gh_mirrors/hon/honcho点击查看免费下载导读本文围绕harness-plugin-core的 CHANGELOG 中记录的 0.1.1 版本变更展开深入剖析该共享运行时的两大修复其一发布产物从“直接指向 TypeScript 源码”改为“编译后的dist/ESM JavaScript .d.ts”解决纯 Node 运行时与tsc nodenext解析失败的问题其二公开的env参数类型从NodeJS.Dictstring改为Env消除消费者对types/node的隐式依赖。在还原变更背景的同时本文结合仓库源码与测试完整讲解其配置文件解析、优先级合并、v0 迁移与遥测头机制帮助读者在自己的 Honcho 宿主插件harness plugin中正确使用loadConfig、resolveConfig与telemetryHeaders。honcho-ai/harness-plugin-core是 Honcho 插件体系host harness → 插件 → Honcho API中的共享运行时层提供“身份 连接 开关”的统一配置解析与遥测头生成能力仓库源码位于 harness-plugin-core仓库内已有实际宿主插件示例 hermes-plugin-honcho 可以对照参考。一、CHANGELOG 与版本策略概览1.1 遵循 Keep a Changelog 与 SemVerharness-plugin-core/CHANGELOG.md 明确声明变更记录遵循 Keep a Changelog 格式版本号遵循 Semantic Versioning该包独立于Honcho API、honcho-ai/sdk以及各宿主插件单独做版本管理。这意味着harness-plugin-core的发布节奏不跟随 Honcho 服务端或 SDK 的版本号宿主插件升级时需单独关注该包的变更记录。当前 CHANGELOG 收录了两个条目[Unreleased]尚无内容[0.1.1] - 2026-09-10包含两项Fixed修复即本文重点剖析的打包策略修复与类型依赖修复。1.2 0.1.1 两项修复速览修复项变更前0.1.0变更后0.1.1影响面发布产物main/exports直接指向 TS 源码指向编译后的dist/index.js与dist/index.d.ts纯 Node、tsc消费者环境参数类型NodeJS.DictstringEnvRecordstring, string \| undefined所有引入.d.ts的消费者二、修复一发布编译产物 dist/让包在任何运行时都能加载2.1 0.1.0 的问题为什么只有“能现场转译 TS”的运行时能用0.1.0 的main/exports直接指向 TypeScript 源码。CHANGELOG 描述其后果0.1.0 only loaded under runtimes that transpile TypeScript on the fly (bun, jiti, esbuild); plain Node refused to strip types undernode_modules, andtscconsumers usingnodenextresolution failed inside this packages source.即bun、jiti、esbuild这类自带 TypeScript 转译能力的运行时可以顺利加载纯 Nodenode直接require/import无法在node_modules内剥离类型注解加载即报错使用moduleResolution: nodenext的tsc消费者在解析包内源码时也会失败。这正是包发布前最常见的坑源码可以跑、测试可以过但一旦被下游以“黑盒依赖”的方式安装进node_modules问题就集中爆发。2.2 0.1.1 的修复ESM .d.ts .js 后缀的相对导入0.1.1 的修复包含三个要点可对照 package.json 与 tsconfig.json 验证构建产物进入dist/package.json 中main指向dist/index.jstypes指向dist/index.d.tsexports也分别给出types/default两条路径并声明type: module确保发布的是标准 ESM相对导入统一携带.js扩展名如 src/index.ts 中export { configPath, loadConfig, ... } from ./config.js、from ./telemetry.js。在 ESM 与nodenext解析规则下这是必须的否则 Node ESM 无法解析相对导入tsc nodenext同样会失败.d.ts声明文件随之生成tsconfig.json中declaration: true、outDir: dist、rootDir: srcbun run build即tsc产出 JS 与类型声明。2.3 用测试验证发布形态dist.test.ts 全链路复现仓库的 harness-plugin-core/tests/dist.test.ts 是这段修复的“真实验收试验”它在临时目录中执行bun run build→npm pack→ 解包 tarball → 分别用纯 Node 直接运行main.mjs与tsc --module nodenext编译消费断言两者都成功纯 Node 场景下期望输出test/1.0.0 (linux)对应hostHeaderValue的遥测头格式tsc场景下期望无任何编译错误输出。这个测试精确复现了 0.1.1 修复的目标——“npm 发布出的 tarball 在纯 Node 与 tsc nodenext 下都能正常工作”是理解本次打包修复的最佳入口。构建脚本由 package.json 的prepublishOnly: bun run build保证发布前必然执行编译。三、修复二Env 类型替代 NodeJS.Dict剥离 types/node 依赖3.1 为什么 NodeJS.Dict 是个问题0.1.0 公开 API 中涉及环境变量的参数使用了NodeJS.Dictstring。NodeJS命名空间由types/node提供因此消费者若未安装types/node引入该包.d.ts时会出现无法解析NodeJS.Dict的编译错误这相当于给消费者施加了一个隐式的、文档外的依赖。3.2 0.1.1 的类型方案自足的类型定义0.1.1 将公开的env参数类型改为Env/** Environment map shape; structurally identical to process.env, without depending on types/node in consumers. */ export type Env Recordstring, string | undefined该定义位于 src/config.ts结构上与process.env完全一致但不依赖任何types/node命名空间消费者只需 TypeScript 标准库即可完成类型检查。所有使用Env的公开 APIconfigPath、loadConfig、resolveConfig的env可选参数在 src/index.ts 中被统一导出为类型而process.env赋值给Env天然类型兼容。类型自足是发布 TypeScript 库的重要最佳实践公开声明文件只应依赖消费者必然具备的依赖否则就要显式列入peerDependencies。四、配置解析机制从 README 到源码的完整链路CHANGELOG 修复的是“包的加载与类型”而包本身承载的核心能力是配置解析与遥测头。这一节从 README 的用法出发落到源码逐层展开。4.1 最小用法loadConfig 与 resolveConfigimport { loadConfig, resolveConfig } from honcho-ai/harness-plugin-core const cfg loadConfig({ host: harness }) // 宿主可把自身插件配置作为同六键的 overlay 覆盖 const cfg resolveConfig(file, { host: harness, overlay: { workspace: harness, auth: { apiKey } } })loadConfig从默认路径读取配置文件后调用resolveConfig见 src/config.tsresolveConfig直接接受“读入的 JSON 对象”与解析选项便于宿主注入自己的配置来源。4.2 配置文件形状与六个核心字段配置文件为 JSON支持以下结构README 原文{ schemaVersion: 1, peerName: user, workspace: honcho, baseUrl: https://api.honcho.dev, timeoutMs: 30000, auth: { apiKey: ${HONCHO_API_KEY} }, enabled: true, hosts: { test: { workspace: test } } }对照 src/config.ts 的类型定义六个核心字段为字段类型含义peerNamestring身份标识名默认取$USERworkspacestringHoncho 工作区名baseUrlstringAPI 服务地址仅 origin版本由 SDK 固定为/v3timeoutMsnumber请求超时毫秒authAuthConfig认证信息apiKey或oauthaccessToken / refreshToken / expiresAtenabledboolean总开关hosts表允许按宿主名如test覆盖同一组六个字段。4.3 v0 旧键自动迁移内存级重映射README 明确缺失schemaVersion视为 0读取时把 v0 键environmentUrl、workspaceId、顶层apiKey在内存中重映射为 v1 键不回写文件。实现位于 src/config.ts 的migrate()environmentUrl/endpoint.baseUrl→baseUrlworkspaceId→workspace顶层apiKey→auth.apiKey顶层oauth→auth.oauth迁移后的对象统一写入schemaVersion 1。迁移同时作用于根块与每个hosts.host块。测试 tests/config.test.ts 验证了两条关键语义根级apiKey/workspaceId别名仍能正确解析已是 v1 的配置中残留的environmentUrl会被忽略以baseUrl为准。4.4 解析优先级env → overlay → hosts. → root → built-inREADME 用一句话概括优先级HONCHO_*环境变量 → overlay →hosts.host→ 根块 → 内置默认值最高优先级胜出。对应 resolveConfig 的实现顺序内置默认值baseUrl https://api.honcho.dev、timeoutMs 30000、enabled true、peerName $USER、workspace回退到宿主名见DEFAULT_BASE_URL/DEFAULT_TIMEOUT_MS常量与CONFIG_SCHEMA_VERSION 1src/config.ts根块pickRoot只取六键忽略宿主自定义的注入、观测等扩展键src/config.ts宿主块hosts.host的同名覆盖src/config.tsoverlay宿主运行时注入的覆盖opts.overlay环境变量HONCHO_API_KEY、HONCHO_BASE_URL/HONCHO_URL/HONCHO_ENDPOINT值local映射为http://localhost:8000、HONCHO_WORKSPACE/HONCHO_WORKSPACE_ID、HONCHO_PEER_NAME、HONCHO_TIMEOUT_MS、HONCHO_ENABLED false关闭。测试 tests/config.test.ts 覆盖了“宿主块胜过根块、环境变量胜过宿主块”“overlay 位于 env 之下”“空文件使用内置值且宿主名不被改写”等核心断言。整个合并过程结束后还会对全部字符串做${VAR}插值未设置的变量会记入warningssrc/config.ts对baseUrl做标准化normalizeBaseUrl补协议、小写化主机名、去掉尾部斜杠localhost/127.0.0.1/::1使用http其余默认https保留/v3路径不动因为版本归 SDK 管src/config.ts。4.5 配置路径解析configPath()src/config.ts按以下顺序定位配置文件HONCHO_CONFIG_PATH原样返回$HOME/.honcho/config.json$USERPROFILE/.honcho/config.jsonWindowsos.homedir()下的.honcho/config.json。实现细节值得注意代码先查env.HOME再查os.homedir()注释说明这是因为 Bun 的homedir()会忽略进程内对process.env.HOME的修改测试需要重定向 HOME 时依赖此顺序。五、遥测头机制把宿主与插件身份带给 Honcho API除配置外该包的另一个核心职责是生成遥测头。README 建议将telemetryHeaders()的结果作为 SDK 的defaultHeaders传入三个自定义头如下Header含义示例X-Honcho-Host宿主 harnessname/version (platform)harness/2.1.3 (darwin)X-Honcho-PluginHoncho 集成插件name/versionharness-honcho/0.2.11X-Honcho-Agent-ModelAgent 的补全模型不是 Honcho 模型claude-sonnet-4-5实现位于 src/telemetry.ts头名常量HEADER_HOST/HEADER_PLUGIN/HEADER_AGENT_MODELsrc/telemetry.tshostHeaderValue把host/version (platform)拼成X-Honcho-Host的值platform缺省用process.platformsrc/telemetry.tstoken函数会对名字/版本做净化把换行、空白、括号、分号等会破坏解析的字符替换为-src/telemetry.tstelemetryHeaders缺省省略未知字段——只传host时也只会产生X-Honcho-Host一个头任何字段缺失都不会影响其他头src/telemetry.tssetTelemetryHeaders在已有头映射如honcho.http.defaultHeaders上原地合并适合 SDK 构造之后再更新模型名等字段src/telemetry.ts。README 中的完整接线示例import { Honcho } from honcho-ai/sdk import { loadConfig, setTelemetryHeaders, telemetryHeaders } from honcho-ai/harness-plugin-core const cfg loadConfig({ host: harness }) const honcho new Honcho({ apiKey: cfg.apiKey, baseURL: cfg.baseUrl, workspaceId: cfg.workspace, timeout: cfg.timeoutMs, defaultHeaders: telemetryHeaders({ host: harness, hostVersion: 1.3.13, plugin: harness-honcho, pluginVersion: 0.1.3, model: claude-sonnet-4-5, }), }) setTelemetryHeaders(honcho.http.defaultHeaders, { model: claude-opus-4 })行为要点测试 tests/telemetry.test.ts 均有覆盖三个头可精确映射为harness/2.1.3 (darwin)、harness-honcho/0.2.11、claude-sonnet-4-5未知名段被省略platform 缺省为当前平台会破坏解析的字符换行、空格、括号等被替换为-extra头可覆盖同名头空白值被丢弃setTelemetryHeaders原地修改同一对象并只更新命名字段。六、安装、构建与本地开发按 README 的说明安装bun add honcho-ai/harness-plugin-core或npm install honcho-ai/harness-plugin-core该包自带编译后的 ESM 与类型声明dist/纯 Node 与tsc均可直接加载本地联调在消费者package.json中写入honcho-ai/harness-plugin-core: file:../harness-plugin-core并先在包目录执行bun run build生成dist/开发脚本见 package.jsonbun test测试、bun run typechecktsc --noEmit、bun run buildtsc产出dist/、prepublishOnly保证发布前构建。结语harness-plugin-core的 0.1.1 版本虽然只记录了两条Fixed但背后是 TypeScript 库发布的两条普适工程原则发布物必须是不依赖现场转译的编译产物ESM .d.ts公开声明文件必须类型自足。配套的 dist.test.ts 以“打包→解包→纯 Node 运行→tsc nodenext 编译”的端到端方式锁定了这一行为。在此基础上配置解析的优先级模型、v0 旧键的内存迁移、以及三枚遥测头X-Honcho-Host/X-Honcho-Plugin/X-Honcho-Agent-Model共同构成了宿主插件接入 Honcho 的最小且完整的运行时契约值得所有基于 Honcho 构建状态化 Agent 插件的开发者直接复用。赞分享人工智能AI AgentAgent 记忆RAG后端MCP 服务【免费下载链接】honchoMemory library for building stateful agents项目地址https://gitcode.com/gh_mirrors/hon/honcho点击查看免费下载相关推荐honcho-ai/harness-plugin-core 解析为 Honcho Harness 插件提供统一配置加载与遥测上报的共享运行时honcho ai/harness plugin core 解析为 Honcho Harness 插件提供统一配置加载与遥测上报的共享运行时 honcho人工智能AI AgentAgent 记忆RAG后端MCP 服务Hermes Agent 接入 Honcho 记忆提供方hermes-plugin-honcho完整配置与架构指南Hermes Agent 接入 Honcho 记忆提供方hermes plugin honcho完整配置与架构指南 导读 本文围绕开源仓库 hermes人工智能AI AgentAgent 记忆RAG后端MCP 服务Halo ESM UI 插件运行时规范深度解析Provider Manifest、宿主运行时快照与 Import Map 共享依赖Halo ESM UI 插件运行时规范深度解析Provider Manifest、宿主运行时快照与 Import Map 共享依赖 Halo 的 Consol后端前端CMS上一篇3步免费备份QQ空间完整导出十年历史说说、评论与高清图片的指南下一篇kOps kops toolbox addons list 命令完全指南查看集群已安装的托管 Addons创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考