阿波罗术语规则路由器（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. 压缩或裁剪上下文后，以 session.deriveMessages() 返回的当前可见消息重新匹配、重建 audit/inject 计数；仅补回仍有命中且提示词已不在上下文里的 term/rule。
10. 超过 Resolver 单段上限的消息只在术语审计传输层无损分段；超过 100 段文本或 200 个候选词时分批查询，全部成功后合并投递。DSH 交给模型的原消息不变。

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

安装

当前版本为 0.2.0，对应 DeepSeek Harness 0.2.1-rc.5。旧版 0.1.7 对应 DSH 0.1.7-rc.2。 旧版 0.1.5 对应 DSH 0.1.1-rc.2，升级插件时需同步升级宿主；0.1.6 是未发布的源码过渡版本。

在对应版本的 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

发布前可在构建后运行 npm pack ./integrations/deepseek-harness --ignore-scripts， 将生成的 .tgz 安装到 DSH 测试项目；这不会发布 npm。

凭据示例：

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 会等相关服务存在后再加载。本项目锁定并测试 DSH 0.2.1-rc.5 的公开 Agent、session/event、agent/assistant-stream、tools/post-execute、agent/pre-step、agent/request、agent/turn-stopping 接口。包清单显式声明这一组接口的完整 DSH peer 闭包，避免依赖宿主包管理器自动补齐隐式 peer。

0.1.6 使用独立的消息来源 plugin:apollo-terminology-rules，与上游将旧插件消息迁移到 v4 会话格式后的来源一致。工具结果现在由 role: tool 消息承载；若另一插件替换 canonical value，本插件等待 DSH 渲染并提交 tool/result 后在 pre-step 审计，不匹配已被替换的旧内容。pre-step 增量保留上游 startsRequestSeries 等准入字段。

压缩后的重新计数（0.1.7）

这里的“重新计数”指重新建立命中、已投递集合和 audit/inject 指针，不是重新计算模型 token 用量，也不改变 DSH 的压缩策略。

• 摘要、未压缩的近期消息和本轮即将准入的用户消息参与重新匹配；已被替换的原始日志不参与。启动/恢复会话也使用同一可见上下文入口。
• 自身完整保留的 term/rule 提示词继续算已投递；被压掉且仍有命中的提示词在下一次模型请求前补回。被压掉且不再命中的内容不会复活，自身提示词也不反向触发新命中。
• 新提示词的来源元数据记录 term/rule ID 和正文 SHA-256；正文被裁剪或修改后不沿用旧回执。摘要里提到某条规则不等于完整规则仍在。保留的 0.1.6 原文提示词按已有来源和固定格式读取 ID。
• 每次替换开启独立 contextEpoch，双指针使用该轮上下文内的递增序号；不把重排后的原日志 seq 当作增量水位。压缩前未完成的查询结果作废，队列里过期的本插件增量移除，其他输入不动。
• 普通压缩在 agent/pre-step 重建；上下文溢出后的同一步重试由 agent/request 兜底，在请求构建前提交增量，不改写 provider 请求。已生成候选答案时，最终门禁仍只 steer 剩余增量。
• 重建必须完成后才能继续生成，不受 queryIntervalMs 或普通 flushOnPreStep: false 的延迟设置影响；查询失败则阻止该次生成。默认开启的最终门禁维持原有语义。

实现不依赖具体 compaction 插件，而是监听公开的会话 surface replacement。完整设计、一手上游依据和验证记录见仓库 docs/DSH_CONTEXT_RECOUNT.md。

验证

无凭据的真实 DSH 运行时回归已纳入 npm test（模型和 API 均为测试数据，不联网）：

npx tsx --test tests/harness-runtime.test.ts

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

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

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