别再让 Agent 忘记项目术语

agent-workflowcodex-skillterm-keeper

如果你在一个项目里长期使用 Agent，应该很容易遇到这种情况：同一个 模块名、指标名、角色边界，明明前面已经解释过，换一轮对话之后又要重新确认一遍。

有时是 上下文压缩 之后，Agent 忘了关键定义；有时是不同 Agent 对同一个词的理解不一致；有时是 临时运行状态 被误当成 长期概念。更麻烦的是，每次纠正都不只是多说两句话，它会打断当前任务，把时间重新花在“我们刚才说的这个词到底是什么意思”上。

我最近整理的 Agent 词典管家 term-keeper，就是为了解决这个问题。它不试图让 Agent 变得更聪明，而是给项目加一层稳定的 词义记忆：把 长期术语 沉淀到项目文件里，并且让 Agent 在写入前先向用户确认。

问题不是没有记忆，而是记忆没有边界

使用 Agent 做长期项目时，最容易漂移的通常不是代码本身，而是项目里的 语义。

比如：

• 某个模块名到底代表一个页面、一个服务，还是一个处理阶段。
• 某个 Agent 角色负责什么，不负责什么。
• 某个报表字段使用哪个数据源，展示口径是什么。
• 某个流水线状态是业务状态、技术状态，还是临时运行状态。
• 某个旧说法是否已经废弃，后续是否还能继续使用。

这些信息不一定适合写进 README，因为 README 面向的是项目入口；也不一定适合留在聊天记录里，因为聊天记录会被压缩、切换和遗忘。它们更像是一层项目级的 语义索引。

如果没有这层索引，Agent 很容易犯两类错误：

1. 把自己的 推断 当成 用户定义。
2. 把 当前运行状态 当成 长期项目概念。

前者会让术语越来越抽象，后者会让词典越来越像流水账。term-keeper 的设计目标，就是把这两件事挡在写入之前。

term-keeper 的核心规则

term-keeper 是一个可复用的 Codex Skill。它的职责只有一个：维护项目里的 长期术语表 / 概念词典。

它关心的是这些内容：

• 业务术语 和 领域概念。
• 模块名称 及其含义。
• Agent、角色、岗位或流程边界。
• 驾驶舱、报表、指标展示口径。
• 流水线状态、交接语义、产物定义。
• 已废弃或已改名的旧口径。

它不应该记录这些内容：

• 今天某个任务跑失败了。
• 当前批次还没完成。
• 某个临时测试结果。
• Agent 自己推断出来的架构理解。
• 还没有被用户确认的命名偏好。

这听起来像文档规范，但对 Agent 来说，它更像是一条操作边界：不确定就不要写，定义类写入先确认。

写入前先确认

term-keeper 最重要的流程是 确认表。

当用户明确提出 定义、修正、改名、废弃或边界说明 时，Agent 不应该直接更新词典，而是先整理成一张表，让用户确认。

这张表通常会包含：

• 术语 是什么。
• 属于哪类 定义。
• 准备写入的 定义 是什么。
• 有哪些 边界、反例或废弃含义。
• 这条定义来自用户哪句话。
• 是否影响 角色、流程、报表或数据源。
• 本次动作是 新增、更新还是废弃。

确认表的意义不是形式感，而是防止 Agent 把“听起来合理”的理解写成 长期事实。尤其是当一个定义会影响 角色职责、流水线顺序、外部报表口径或数据源 时，写入前必须显式确认。

Markdown 给 Agent 读，HTML 给人审

term-keeper 默认维护两份文件：

docs/glossary.md
docs/glossary.html

Markdown 是 Agent 友好的版本。它适合在后续会话中被快速读取，用来判断某个术语是否已有定义、是否有废弃说法、是否存在边界限制。

HTML 是给人审阅的版本。它不承担复杂交互，只做一件事：把词条清楚地摆成表格。

HTML 表格里会展示 术语、类型、定义、来源、维护规则、边界、最后修改时间、触发频率和确认状态。这样用户不用读 Markdown 结构，也能快速检查词典有没有写偏。

这里有一个小取舍：term-keeper 允许 Agent 直接维护 Markdown 和 HTML。脚本存在，但它们只是 辅助工具，用于发布前校验、CI 或批量生成。日常维护时，核心责任仍然在 Agent：写入后要确保 两个版本同步。

触发频率不是热度统计

我给词条加了一个字段：触发频率。

但它不是全量统计，也不是从历史记录里重新计算出来的热度。它只是一个 增量元数据：

• 用户在当前项目语境里提到已有词条时，加 1。
• Agent 明确使用已有词条来解释、路由、验证或更新项目工作时，加 1。

这条规则很克制。它 不扫描整个聊天历史，不扫描整个仓库，也不去网上找出现次数。原因很简单：这不是做数据分析，而是给未来 Agent 一个轻量信号，告诉它哪些词在最近的协作中经常被用到。

如果一个字段会迫使 Agent 做昂贵、模糊、不可复现的统计，它就不适合作为日常维护规则。

为什么做成 Skill，而不是普通提示词

普通提示词当然也能写“请维护术语表”。但长期项目里，问题不在于写一次规则，而在于这套规则能不能被 稳定复用。

做成 Skill 之后，它可以把几个东西固定下来：

• 触发条件：什么时候应该启用词典维护。
• 写入边界：什么能写，什么不能写。
• 确认流程：定义类写入必须先给确认表。
• 默认路径：没有项目配置时，默认使用 docs/glossary.md 和 docs/glossary.html。
• 校验方式：写完后检查 Markdown 和 HTML 是否同步。
• 反例：当前运行状态、临时错误、测试批次不应该进入长期词典。

这让它更像一个小型工作协议，而不是一段会被遗忘的提醒。

一个典型使用方式

如果项目里还没有词典，用户可以这样说：

请使用 term-keeper，把下面这个定义记录到项目词典：
"Agent Router" 指识别请求类型并转交给对应 Agent 的组件。它不是调度器。

理想行为不是马上写文件，而是先给出 确认表：

Term: Agent Router
Type: Agent or role boundary
Proposed definition: 识别请求类型并转交给对应 Agent 的组件
Boundary / deprecated meaning: 不是调度器
Impact: roles / workflow
Action: add

用户确认后，Agent 再更新 Markdown 和 HTML。下一次别的会话再遇到 Agent Router，就可以先读词典，而不是重新猜。

它适合哪些项目

term-keeper 适合那些 项目语义会持续积累 的地方。

比如：

• 多 Agent 协作项目。
• 长期维护的产品或系统。
• 有大量 模块名、状态名、指标名 的项目。
• 需要保持 报表口径一致 的项目。
• 有明确 角色边界和流水线阶段 的工作流。
• 写作、研究、实验、工程混在一起推进的项目。

它不适合替代 任务管理，也不应该变成 运行日志。任务进度、失败记录、当天状态应该进入 issue、看板、日志或日报，而不是进入术语词典。

当前状态

现在这个项目已经整理成一个可以公开分享的仓库结构：

term-keeper/
  README.md
  README.zh-CN.md
  INSTALLATION.md
  EXAMPLES.md
  TESTING.md
  AUDIT.md
  skill/
    term-keeper/
      SKILL.md
      references/
      scripts/
      examples/

真正可安装的是：

skill/term-keeper/

把这个目录复制到 Codex 的 skills 目录后，就可以在项目里通过 term-keeper 维护 词典。

仓库里也放了两个可选脚本：

• render_glossary_html.py：把默认 Markdown 结构渲染成 HTML 表格。
• check_dictionary_sync.py：检查 Markdown 和 HTML 里的 词条是否同步。

我还补了 最小测试和 CI，用来防止后续修改脚本时破坏渲染和同步检查。

后续想改进什么

现在的版本更像一个清晰可用的 最小闭环。后续如果继续打磨，我会优先考虑三件事。

第一，给更多真实项目跑 压力测试。特别是那些同时涉及 角色边界、报表口径和数据源 的项目，因为这类定义最容易影响后续决策。

第二，让 HTML 审阅页 更适合长期维护。现在它已经能展示核心字段，但还可以继续优化筛选、搜索和移动端阅读体验。

第三，整理更多 示例。一个 Skill 好不好用，很大程度取决于它能不能通过 反例 教会 Agent 边界在哪里。比如“今天跑失败了”不该写入，“以后这个状态名表示人工复核中”才应该进入词典。

结语

我越来越觉得，长期使用 Agent 做项目时，真正重要的不只是 上下文长度，而是哪些信息应该沉淀成 稳定文件。

聊天记录 适合讨论，任务系统 适合追踪进度，代码仓库 适合保存实现。项目里的 长期语义，也应该有自己的位置。

term-keeper 想做的就是这件小事：让 Agent 少猜一点，让项目术语 少漂移一点。