智能体反馈循环 super3ben/agent-feedback-loop

智能体反馈回路

面向 Codex、Claude Code 和 Gemini CLI 的本地提示词时反馈学习。中文说明

运行时版本：0.9.0

反馈学习

1. 提示词钩子捕获符合条件的用户不满，立即返回宿主。
2. 独立的反馈审查器稍后可以检查有界的本地证据。
3. 审查器给出有效结果后，写入 .agent/reflections/ 下的项目 Markdown，不可更改。
4. 后续匹配的提示词读取一小组适用的 Markdown 文档。

当前提示词从不等待反馈审查器。发布截止时间固定在提示词处理时刻，因此处理期间发布的文档只能影响后续匹配的提示词。控制用 SQLite 数据库保存生命周期状态，不保存经验正文。这是直接选取 Markdown，不是 RAG。

自然语言不满覆盖

识别不满不再依赖固定的负面关键词，比如「做错了」或「不合理」。词表与判断之间的空白由三层覆盖：

1. 扩展词表路由。 自然语言抱怨——被要求复述已知信息、对反复出现的问题感到沮丧、反问式追责（「怎么又不知道？」）——直接进入独立完整审查器。
2. LLM 兜底分类器。 词表漏掉、但带有助手指代的消息，交给独立的二分类器（classify-feedback）。它先给理由，再输出 {"dissatisfied": true/false}。是，就把任务交给审查器；否，就丢弃。分类器会被告知：智能体自己的借口不能算作用户满意的证据——推脱（「连不通」）不能左右判定。纯操作轮次（「继续」「好的」「等等」）完全跳过调用。分类器按带指代的提示词逐条运行，因此 codex 调用会注入审查器所用的同一套网关路由；没有它，每次 codex 分类都会卡到超时。
3. 确定性升级。 审查器反复拒绝同一类反复出现的问题——每次换一个新借口（事后纠正、「还没部署」、前瞻性请求）——不再拥有最终决定权：同一类问题在 14 天窗口内被拒绝 3 次以上后，下一次拒绝会被替换为一条合成的 Major 经验，由累积的拒绝摘要构建并直接发布。已有发布经验的类别交给正常的复发机制处理，不再堆积重复的元经验。

DeepSeek Harness（dsh）覆盖： install 会附带一个独立原生 harness 插件（dsh-plugin/），并按 dsh plugin add 的方式接入 ~/.dsh/profiles/ 下的每个配置档（node_modules 符号链接、link: 依赖、dsh.profile.bundles 注册）——不涉及桥接包。插件把每条提示词送入 core-hook.sh 再把编译好的规则上下文注入回 harness。harness 不暴露任何对话记录，所以来自无法提供对话记录的方言的提示词会交给分类器处理，而不是被悄悄丢弃；会话能携带对话记录、但还没有指代对象的提示词（首轮）仍然跳过。dsh 来源任务的评审器和分类器子进程跑在宿主命令行上（先 claude，再 codex，再 gemini）。

从已发布的教训到后续会话

发布不等于送达。有三条通道把教训传递下去：

- 评审器契约把用户明确陈述的事实当作事实主张，智能体必须先核实才能反驳；同时把范围越界算作智能体的过错，即使智能体后来纠正了也一样。
- 出现次数达到 Major+3 / Critical+2 / Blocker+1 的族会被编译进 .agent/rules/feedback-loop.md 的托管块。
- 提示词钩子把该托管块注入每条提示词的上下文（上限 6 KB），这样一条反复出现的规则每轮都会被机械地看到，而不依赖模型主动去打开文件。

规则块是投影，不是不断累积的日志

托管块在每次发布时都从存储状态重建，并受固定字节预算约束，所以它不会无限增长，也无需任何人手动清理。三个特性让这一切自动完成：

- 合并。 渲染后正文完全相同的族会被合并。族 id 会把评审器的自由文本 family_key 连同其方法类别一起哈希，所以只要评审器换个说法描述 key，同一条教训就会以新 id 出现。一个实际项目里就有七个这样的重复项，占其规则块的 36.6%。
- 排序。 存活的段落按严重程度、出现次数、最近复发时间排序。没有第三项的话，一个几个月前命中 39 次、之后再没出现过的族，会排在某个本周命中五次的族前面。
- 降级，绝不删除。 放不进预算的族保留一行仅标题的行，写明名称并带上计数。它永远不会被删除：它保持已发布、保持计数，一旦再次复发并排到别的族前面，就自动恢复全文。

写入方保证规则块放得下，这取代了读取方过去在注入时做的字节切片。那个切片会从字符中间截断，悄悄丢掉一个实际规则块的 44%——包括五个已经达标的族。现在规则块超预算，只说明文件是旧版本写的或被手工改过；读取方随后会按整段裁剪，并记录裁掉了多少段。

doctor 在 status.rulesBlock 下报告规则块，带两个独立标志：saturated（投影达到上限——按设计正常工作）和 overBudget（文件已与写入方产出的内容不一致）。两者都不要求你清理任何东西。

评审器服务商环境

分离运行的评审器在宿主命令行（codex、claude 或 gemini）里运行，环境为清理过的环境。只有 PATH、HOME、TMPDIR、LANG、LC_ALL、LC_CTYPE、TZ，以及任何 AFL_REVIEW_* 变量能进入审查进程。命令行工具如果用自己的持久化凭据认证（例如 ~/.codex/auth.json，或 ~/.claude/settings.json 里的 token），无需额外配置就能工作，因为这份状态由命令行工具自己加载，不从 shell 继承。只有纯粹靠 shell 环境变量认证的服务商才需要把这些变量名传进去——比如 ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN 这一对，是导出到 shell 里而不是存在命令行工具自己的配置里——这时要通过 AGENT_FEEDBACK_LOOP_REVIEWER_ENV_ALLOWLIST 传入（逗号分隔的允许列表，其值里还必须列出 AGENT_FEEDBACK_LOOP_REVIEWER_ENV_ALLOWLIST 和 AGENT_FEEDBACK_LOOP_REVIEWER_TIMEOUT_MS 本身，这样它们才能活到分离出去的进程里）。单次审查超时默认 300000 ms，认领租约按它缩放，所以一次证据量很大、合法跑上几分钟的审查，不会在生成中途被切断，也不会因租约丢失被丢弃；真实服务商需要更长时间时，用 AGENT_FEEDBACK_LOOP_REVIEWER_TIMEOUT_MS 再调大。

安装与诊断

需要 Node.js 24.15 或更新版本。真正做全局安装、或改动真实 HOME 配置之前，先申请授权。

npm install -g agent-feedback-loop
agent-feedback-loop install --dry-run

先用一个临时 HOME；这样会装一套一次性运行时和 schema，不动真实用户配置：

tmp_home="$(mktemp -d)"
agent-feedback-loop install --home "$tmp_home"
agent-feedback-loop doctor --home "$tmp_home" --live
agent-feedback-loop uninstall --home "$tmp_home"
rm -rf "$tmp_home"

安装会复制包内资源、选定运行时、迁移选定的控制 schema，并配置提示词钩子。它不注册 Stop/AfterAgent 钩子，不启动服务，也不创建学习读取器。

DeepSeek Harness（dsh）

dsh 插件已列入 awesome-dsh-plugin 市场（memory 分类）：条目。

如果 dsh home 存在（~/.dsh/profiles/），agent-feedback-loop install 还会把独立原生插件接入每个 harness 配置档：把插件复制到 <packRoot>/dsh-plugin/，链接进配置档的 node_modules，加一条 link: 依赖，并在 dsh.profile.bundles 里注册——最终状态和 dsh plugin add 一样，重复安装也保持幂等。插件由自带的补丁层激活；install 从不写入配置档的 cordis.patch.yml（在那里手写一行会和 bundle 层在 loader 条目 id 上冲突，harness 会拒绝启动）。早于 bundle 注册会自动迁移：它们写入的受管补丁行会被删除。

安装后重启 harness，运行中的实例才能加载插件。dsh home 跟随安装 home（真实用户为 ~/.dsh）；传入 --home 并指定一个临时目录，就能在不碰真实配置档的情况下试跑接线。

doctor 返回 { version, status }。status.ready 仍是提示词/Markdown 管线的闸门。

包存在、doctor 静态结果正常，都不等于服务商实际可用，也不等于生产环境有效。

反思清理

两个以读为主的命令管理已发布的 reflections 目录：

agent-feedback-loop reflections effectiveness --project /abs/project
agent-feedback-loop reflections archive --project /abs/project # dry run
agent-feedback-loop reflections archive --project /abs/project --apply # move files

effectiveness 依据投递日志和评审历史回答「这条经验有没有起作用」，并把每个 family 报告为 never_delivered、recurred_after_delivery、too_early_to_tell 或 quiet_since_delivery。它的输出标注为 causality: correlation_only：某个 family 安静，可能是经验生效了，也可能是同类工作再没出现过。不要把它当成有效的证据。

archive 会退役同时满足两个条件的文档：早于 --after-days（默认 30），且从未投递到任何会话；退役即移到 reflections/archive/。已投递的文档无论多旧都不动。这是移动，不是删除，默认只做 dry run。

旧数据导出

反馈数据的旧版导出仍然需要显式触发，且对源只读：

agent-feedback-loop legacy-export --source-db /absolute/legacy.sqlite3 \
--output-dir /absolute/export --dry-run
agent-feedback-loop legacy-export --source-db /absolute/legacy.sqlite3 \
--output-dir /absolute/export --apply

要回滚提示词钩子，先查看 agent-feedback-loop uninstall --dry-run，获得批准后再运行 uninstall。它会禁用钩子，同时保留持久控制数据和密钥，除非操作者另行删除。

证据状态

代码测试、包清单、临时安装的运行时、生产有效性，是四种彼此独立的证据状态。前一种状态通过，不能当成后一种状态来汇报。

结构化日志只包含固定事件名、有界原因码、计数器，以及不透明标识符或哈希。日志里没有原始提示词、diff、评审正文、token，也没有绝对项目路径。