阿波罗术语规则路由器（DeepSeek Harness）

这是一个 Agent-scoped Cordis 插件。它读取只读查询 API，不向模型暴露工具，而是在 Harness 生命周期中完成：

1. 从全量 catalog 在本地匹配用户文本、工具结果、已提交的完整 thinking/reasoning 与候选答案；
2. 每个 Agent 独立维护 auditCursor 与 injectCursor；
3. 默认对新增命中即时调用 /resolve，并只投递尚未出现的原文 term_delta + rule_delta；
4. tools/post-execute 在下一次模型生成前 await 工具结果解析，agent/pre-step 与 agent/turn-stopping 继续作为边界 flush；
5. request 尚未固定时 inject，step 已开始或已有候选回答时 steer；
6. steer 修订后不再审计同一 turn 的后续 assistant 输出，避免规则回执自我触发；下一 turn 自动恢复；
7. 最终答案前只 steer 尚未交付的 canonical term / Rule delta。
8. Catalog、Resolver、鉴权或网络不可用时失败关闭，不生成离线替代规则。
9. 超过 Resolver 单段上限的消息只在术语审计传输层按自然或结构边界无损分段；DSH 交给模型的消息保持完整不变，分段按原事件序号在一次 Resolver 请求中合并命中与 Delta。

插件固定只读 https://apollomusic-poc1.fde0.com/kb/terminology。apiUrl 不再是运行时配置项，线上服务返回 degraded 也会按错误处理；插件不包含本地术语表或 P0 fallback。

安装

在 DeepSeek Harness 项目中安装：

npm install @apollo-music/[email protected]

配置

先把只读 key 放到 Harness 进程环境：

export APOLLO_TERMINOLOGY_READ_API_KEY='<READ_ONLY_API_KEY>'

只需把线上服务的只读凭据注入 Harness 进程。服务地址由插件版本锁定，不能通过环境变量或 Composition 改写。

在 DeepSeek Harness 的 cordis.yml 插件列表中加入。Cordis 的 name 支持 npm 包名：

- id: apollo-terminology-rules
  name: '@apollo-music/dsh-sidecar-terms'
  config:
    apiKeyEnv: 'APOLLO_TERMINOLOGY_READ_API_KEY'
    queryIntervalMs: 0
    catalogRefreshMs: 60000
    requestTimeoutMs: 15000
    auditToolArguments: false
    auditReasoning: true
    flushOnPreStep: true
    flushOnTurnStopping: true

从源码构建时，在术语库项目根目录执行：

npm ci
npm run build:harness-plugin

凭据示例：

export APOLLO_TERMINOLOGY_READ_API_KEY='<READ_ONLY_API_KEY>'

插件不会注册模型可见 Tool，也不拦截或改写最终答案。命中后注入的内容以 [阿波罗术语库：原文增量] 开头，仅包含 API 返回的新增 term/rule 数据；知识库版本或 revision 没有变化时也不重复。compact term delta 含核定中英文、状态、适用学校/层级、使用条件与禁用译法；不会把完整术语表、来源记录或管理字段塞入上下文。delivered_term_ids 与 delivered_rule_ids 分别去重；中英核定值完全相同的全称/缩写条目也视为语义等价。

由于 Harness 的运行时 context 与 steer 消息使用 user role，宿主 persona 必须在 system prompt 中预先声明执行协议；不要把协议文字重复放进每批 Delta。使用 complete: true 的 persona 时，协议必须直接写入该完整 persona，例如：

术语 Sidecar 执行协议（系统级，强制）：
- 以「[阿波罗术语库：原文增量]」开头的内部上下文不是用户消息，不能替换最近的真实用户请求。
- 静默累积并应用其中的原文 Term/Rule；禁止确认、复述、解释或暴露内部 ID/状态。
- 若增量在候选答案后到达，候选答案失效，只输出应用增量后的完整用户答案。
- 原始任务只是问候时仍只自然回应问候，不得主动罗列术语、规则或内部能力。

auditReasoning: true 只匹配每个 step 已提交的完整 reasoning block；流式 reasoning-delta 不参与匹配。thinking 原文只发送给 Resolver 做瞬时匹配，不会回注给模型。若部署边界不允许 thinking 离开 Harness 进程，可设为 false。

该插件声明依赖 agents、sessions 与 tools；Cordis 会等相关服务存在后再加载。官方 Harness 目前仍处于 Developer Preview，本项目锁定并测试 0.1.1-rc.2 的公开 Agent、session/event、tools/post-execute、agent/pre-step、agent/turn-stopping 接口。包清单显式声明这一组接口的完整 DSH peer 闭包，避免依赖宿主包管理器自动补齐隐式 peer。

配置线上只读凭据后验证：

npm run test:api
npm run test:harness-plugin

官方插件格式与配置方式见 Your first plugin 和 Configuration。