super3ben/agent-feedback-loop

Agent 反馈循环

面向 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/ 下的每个 profile（node_modules 符号链接、link: 依赖、dsh.profile.bundles 注册）——不涉及桥接包。该插件将每个提示送入 core-hook.sh
并将编译后的规则上下文注入回 harness。该 harness
不暴露任何 transcript，因此来自无法提供 transcript 的方言的 prompt 会
交给分类器，而不是被静默丢弃；在能够携带 transcript 但尚无指涉对象的
会话中的 prompt（首轮）则保持跳过。dsh 来源任务的 reviewer 和分类器
子进程运行在宿主 CLI 上（先是 claude，然后是 codex，再是 gemini）。

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

发布不等于交付。有三条渠道将教训传递下去：

- reviewer 契约将用户对事实的明确陈述视为事实性主张，agent 在质疑之前
必须先核实；并将范围越界视为 agent 的过错，即使 agent 后来纠正了它。
- 达到 Major+3 / Critical+2 / Blocker+1 次出现次数的家族会被编译
进 .agent/rules/feedback-loop.md 的受管块中。
- prompt 钩子会将该受管块注入每个 prompt 的上下文中（上限为 6 KB），
因此一条反复出现足够多次的规则会在每一轮被机械地看到，而不是依赖模型
主动选择打开该文件。

规则块是投影，而非累积日志

受管块在每次发布时都从存储状态重建，并受固定字节预算约束，因此它不会
无限制增长，也无需任何人修剪。有三个特性使这一点自动实现：

- 合并。 当家族渲染后的正文完全相同时，它们会被合并。家族 id 会将
reviewer 的自由文本 family_key 与其方法类别一起哈希，因此每当
reviewer 用不同的措辞表达该键时，同一条教训就会以新的 id 出现。一个
实际项目中有七个这样的重复项，占其块的 36.6%。
- 排序。 保留下来的区块按严重程度、出现次数、最近复发时间排序。
如果没有第三项，一个几个月前被命中 39 次、此后从未再出现的家族会排在
本周被命中五次的家族之前。
- 降级，绝不删除。 不符合预算的家族会保留一行仅含标题的行，标明其
名称并携带其计数。它绝不会被删除：它保持已发布、保持被计数，并在它
再次出现且排名超过其他项时自动恢复为完整文本。

写入器保证该块能够容纳，这取代了读取器过去在注入时应用的字节切片。该
切片会在字符中间截断，并静默丢弃了一个实际块的 44%——包括五个已经合格
的家族。现在，超出预算的块意味着该文件是由旧版本写入的或被手工编辑过；
读取器随后会裁剪整个区块，并记录丢弃了多少个。

doctor 在 status.rulesBlock 下报告该块，并带有两个独立的标志：
saturated（投影达到了其上限——按设计正常工作）和 overBudget（文件
不再与写入器生成的内容匹配）。两者都不要求你清理任何东西。

Reviewer provider 环境

分离的 reviewer 在宿主 CLI（codex、claude 或 gemini）中运行一个
已清理的环境。只有 PATH、HOME、TMPDIR、LANG、LC_ALL、LC_CTYPE、
和 TZ，以及任何 AFL_REVIEW_* 变量，能够到达审查器进程。一个从自身持久化凭据
进行身份验证的 CLI（例如 ~/.codex/auth.json
或 ~/.claude/settings.json 中的令牌）无需额外配置即可工作，因为
该状态由 CLI 自身加载，而不是从 shell 继承。只有
纯粹通过 shell 环境变量进行身份验证的提供方——例如
导出到 shell 而非存储在 CLI 自身配置中的
ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN 对——才需要将这些名称通过
AGENT_FEEDBACK_LOOP_REVIEWER_ENV_ALLOWLIST 传递（一个逗号分隔的允许列表，其值
还必须列出 AGENT_FEEDBACK_LOOP_REVIEWER_ENV_ALLOWLIST 和
AGENT_FEEDBACK_LOOP_REVIEWER_TIMEOUT_MS 本身，以便它们留存到分离的
进程中）。每次审查的超时默认为 300000 毫秒，认领租约随之
缩放，因此一次合理运行数分钟的大证据审查不会被
在生成中途切断，也不会因租约丢失而被丢弃；当真实提供方需要更长时间时，
可通过 AGENT_FEEDBACK_LOOP_REVIEWER_TIMEOUT_MS 进一步调高。

收敛控制

收敛探针与反馈审查器相互独立。审查器决定
真实的用户不满是否足以证明一个可复用的 Markdown 方法。探针是
在确定性收敛断路器触发之后的有界语义顾问；其
建议不能更改契约、提高重要性、重置历史、创建硬性
门禁，或发放继续授权。

断路器评估已验证的外部事实，例如未变基准的重复
变更、针对同一不变量的无证据工作、振荡、显式排除
违规、无正当理由的架构扩展、验收后的范围增长，以及
重复的正式审查失败。routine 任务在第一个已验证的
无证据扩展处暂停。important 任务可获得一次可证伪的探索
预算。critical 任务要求每一代都有新的已验证风险证据；
它们不会获得无限探索。

强制执行受限于适配器的真实接缝：

- SDD 在审查/修复分派边界提供 workflow_gate。
- 已批准的 OpenSpec 和 Comet 修订在任务之间提供 checkpoint_gate。
- 通用提示观察为 audit_only，警告是其最大程度。

这些都不声称对任意工具进行通用实时阻断；不存在
工具级防护。不存在 Stop/AfterAgent 收敛钩子、用户可见的授权
或回执、常驻服务、调度器、数据库课程正文，或学习/RAG
读取器。

独立于收敛有效性到 Markdown 发布的流程被推迟。它
需要一个具名工作流生产者、一个有界证据信封，以及一个独立
批准的学习作业权限和结果契约。目前，真实不满
反馈审查器仍是唯一的自动 Markdown 生产者。

执行防护（已停用）
一个 PreToolUse 执行守卫——一个按工件计数的重写计数器，带有先警告后阻止的升级机制以及后台方向审查——已于 2026-08-31 退役。它是为 GPT 时代的运行而构建的，那些运行会在审查-改进循环中打转；在实时会话上测量时，其误阻止的代价超过了它所捕获的打转。PreToolUse 钩子已从两个宿主上卸载，运行时调度在 src/cli.mjs 中被注释掉，因此即使重新安装钩子，也会让每次调用都通过。存储、钩子逻辑及其测试仍保留在代码树中；要恢复它，需要恢复该调度并重新安装钩子。

安装与诊断

需要 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 钩子、导入 Guard 状态、激活 Guard 权限、切换仓库、启动服务或创建学习读取器。

DeepSeek Harness（dsh）

dsh 插件列在 awesome-dsh-plugin
市场中（memory 类别）：条目。

如果存在 dsh home（~/.dsh/profiles/），agent-feedback-loop install 还会
将独立的原生插件接入每个 harness 配置文件：它会将插件复制到 /dsh-plugin/，将其链接到配置文件的 node_modules 中，
添加一个 link: 依赖，并在 dsh.profile.bundles 中注册它——与 dsh plugin add 的最终状态相同，并且在重新安装时保持幂等。该插件由其自带的补丁层激活；install 绝不会写入配置文件的 cordis.patch.yml（在那里手动添加一行会与 bundle 层在加载器条目 id 上发生冲突，导致 harness 拒绝启动）。在 bundle 注册之前的安装会被自动迁移：它们写入的受管补丁行会被移除。

安装后请重启 harness，以便正在运行的实例能够加载该插件。dsh home 遵循安装 home（真实用户为 ~/.dsh）；传入 --home 并指定一个一次性目录，即可在不触碰真实配置文件的情况下尝试该接线。

doctor 返回 { version, status }。status.ready 仍然是提示/Markdown
流水线门禁。status.convergence 单独报告：

- 代码/包可用性；
- 所选的已安装运行时、schema、提供程序、Probe 资源以及当前平台
支持；
- audit_only、checkpoint_gate 和 workflow_gate 适配器能力；
- 仓库权威状态为 unknown，除非有单独的、显式的仓库绑定检查证明其权威性。

包的存在和静态 doctor 结果并不能证明实时提供方成功、原生 Linux 验收、真实切换、通用实时阻断或生产有效性。

Guard 迁移与回滚

仓库身份初始化是一个单独的、显式授权的步骤。它仅在 Git 公共目录中创建或复用所有者私有的 afl-lineage-id；它不接受遗留状态或 HOME 输入，也不会创建 AFL 控制存储、导入状态、更改权威或修改钩子。然后在不写入 AFL 或遗留状态的情况下检查遗留 Guard 状态：

agent-feedback-loop lineage-init --repo-root "$PWD" --apply
agent-feedback-loop guard --repo-root "$PWD" import \
--state-file .superpowers/sdd/review-loop-state.json --dry-run

受控序列为：显式身份初始化、只读 dry-run、显式授权的导入、有界影子对等验证、显式授权的逐仓库切换，以及精确快照回滚。
导入、影子、切换和回滚都是显式的机器可读命令；不使用长期双写。真实导入或切换、全局 SDD Skill 更改以及运行时金丝雀各自需要单独的用户授权。安装过程绝不会自动执行这些操作。

反馈数据的遗留导出保持显式且源只读：

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。它会禁用钩子，同时保留持久控制数据和密钥，除非操作员单独移除它们。

证据状态

代码测试、包清单、临时安装的运行时、仓库 Guard dry-run、经授权的切换金丝雀以及生产有效性是彼此独立的证据状态。通过较早状态不得报告为通过较晚状态。

结构化日志仅包含固定事件名称、有界原因码、计数器以及不透明标识符或哈希。它们不包含原始提示、差异、审查者或 Probe 正文、状态正文、令牌、授权工件内容或绝对项目路径。