fix: F Tab expected dynamic + AGENTS.md encoding + dev-spec sync

docs/AGENTS.md

@@ -1,137 +1,137 @@
-# AGENTS.md 鈥?鍐崇瓥鑷鍗忚
-
-鍩轰簬 Andrej Karpathy 鍥涘ぇ鏍稿績鍘熷垯 + 璇楀厜杩涘寲鐗?+ 瀵规姉鎬у鏌ユ満鍒躲€?
-鏈枃妗ｆ槸鎵€鏈?Agent锛堣帿鑽枫€亁xm/绗戠瑧銆佺煡寰€佸皬鏋滐級鐨勫叡浜喅绛栫邯寰嬪崗璁€?
-
-## 1. 鏍稿績瑙勫垯
-
-### 1.1 鎬濊€冨厛浜庣紪鐮?
-
-鎷垮埌闇€姹傚悗锛岀姝㈢洿鎺ュ紑濮嬬紪鐮?璁捐銆傚繀椤讳緷娆℃墽琛岋細
-
-0. **璇诲搴旀ā鍧楃殑 搂 spec**锛氬鏋滄秹鍙婂凡鏈夊姛鑳芥ā鍧楋紝鍏堣 `gateway/scripts/specs/{module}.json` 鐨?`ai_spec` 浜嗚В瀹為檯鏋舵瀯銆佹帴鍙ｃ€佺害鏉熷拰渚濊禆銆俿pec 鍦?`docs/dev-spec.md` 鐨勬ā鍧楁竻鍗曚腑鍙煡
-1. **澶嶈堪闇€姹?*锛氱敤鑷繁鐨勮瘽澶嶈堪瀵归渶姹傜殑鐞嗚В锛屽垪鍑轰笉纭畾鐐?
-2. **鍒楀嚭鍊欓€夋柟妗?*锛氬瓨鍦ㄥ绉嶅悎鐞嗘灦鏋勬柟妗堟椂锛屽垪鍑鸿嚦灏?2 绉嶆柟妗堝苟瀵规瘮浼樺姡
-3. **閫夋嫨鏈€绠€鏂规**锛氬熀浜庡鏉傚害銆佸伐浣滈噺銆佸彲缁存姢鎬ч€夋嫨鏈€绠€鏂规
-4. **绛夊緟纭**锛氬湪寰楀埌鐢ㄦ埛/Coordinator 纭鍓嶏紝绂佹寮€濮嬬紪鐮?
-
-### 1.2 鏋佺畝浼樺厛
-
-姣忎竴娆″紩鍏ユ柊鎶借薄/鏂颁腑闂村眰/鏂板伐鍏峰墠锛屽厛闂細"涓嶇敤瀹冭涓嶈锛?
-
-- 鑳界敤鍑芥暟瑙ｅ喅鐨勯棶棰橈紝涓嶇敤绫?
-- 鑳界敤绫昏В鍐崇殑闂锛屼笉鐢ㄦ鏋?
-- 涓嶄负"鏈潵鍙兘闇€瑕佺殑鐏垫椿鎬?鍐欎竴琛屼唬鐮?
-- 涓€娆℃€ц剼鏈笉鍋氬鏉傚皝瑁?
-- 涓嶄负绾亣璁剧殑鏋佺鍦烘櫙娣诲姞澶嶆潅鍏滃簳
-
-### 1.3 绮惧噯淇敼
-
-- 淇敼鍓嶅厛璇诲搴旀ā鍧楃殑 搂 spec锛坄gateway/scripts/specs/{module}.json`锛夛紝纭鏋舵瀯鐞嗚В鍜岀害鏉?
-- 淇敼鍓嶈緭鍑烘墽琛岃鍒掞紙鏀瑰摢鍑犱釜鏂囦欢銆佹敼浠€涔堛€佷负浠€涔堟敼锛?
-- 鍙敼鍔ㄩ渶姹傜洿鎺ユ秹鍙婄殑鏂囦欢锛屼笉椤烘墜"浼樺寲"鏃犲叧浠ｇ爜
-- 涓€娆″彧鏀逛竴涓€昏緫鍗曞厓锛岄獙璇侀€氳繃鍐嶆敼涓嬩竴涓?
-- 涓嶉噸鏋勬病鏈夐棶棰樼殑浠ｇ爜
-- 鍒犻櫎鏈淇敼瀵艰嚧涓嶅啀浣跨敤鐨勪唬鐮侊紝浣嗕笉鍒犻櫎淇敼鍓嶅凡瀛樺湪鐨勬浠ｇ爜锛堥櫎闈炵敤鎴锋槑纭姹傦級
-- **鏀瑰畬鍚屾 spec**锛氫慨鏀瑰畬鎴愬悗锛屽皢瀵瑰簲妯″潡鐨?`specs/{module}.json` 鏇存柊涓轰笌瀹為檯瀹炵幇涓€鑷?
-
-### 1.4 鐩爣瀵煎悜浜や粯
-
-- 澶氭楠や换鍔″厛鍐欏叆 task 娓呭崟锛屾瘡瀹屾垚涓€姝ユ爣娉ㄨ繘搴?
-- 鏀瑰姩闄勫甫绠€瑕佽鏄庯紙鏀逛簡浠€涔堛€佷负浠€涔堟敼锛?
-- 浠诲姟瀹屾垚鍚庣敤 3-5 鍙ヨ瘽鎬荤粨锛氬仛浜嗕粈涔堛€佸鍒颁簡浠€涔堛€佷笅娆℃€庝箞鍋氫笉鍚?
-- 琚籂姝ｅ悗锛屽湪 docs/learned.md 涓拷鍔犵粡楠屾暀璁褰?
-
-## 2. 瀵规姉鎬у鏌ユ祦绋?
-
-褰?Agent 鍑嗗鎵ц涓€涓秹鍙婃灦鏋勯€夊瀷鐨勪换鍔℃椂锛屽己鍒惰蛋浠ヤ笅妫€鏌ョ偣锛?
-
-**Step 1**: 鍐欐柟妗堣崏妗堬紙鏈€鐩磋鐨勬柟妗堬級
-
-**Step 2**: 瀵规姉鎬у鏌ワ紙鑷棶锛夛細
-- 杩欎釜鏂规鏄笉鏄垜涔犳儻鎬ч€夋嫨鐨勶紵
-- 鏈夋病鏈夋洿绠€鍗曠殑鏂规琚垜璺宠繃浜嗭紵
-- 姣忎竴灞傛娊璞＄湡鐨勫繀瑕佸悧锛熷幓鎺変細鎬庢牱锛?
-- 濡傛灉鏄庡ぉ灏辫浜ゆ帴缁欏叾浠栦汉锛屼粬浼氳寰楄繖涓璁℃槸蹇呰鐨勫悧锛?
-
-**Step 3**: 鍒楀嚭瀵规瘮鏂规锛堣嚦灏?2 涓級锛屾爣娉ㄥ鏉傚害銆佸伐浣滈噺銆佸彲缁存姢鎬у樊寮?
-
-**Step 4**: 鎻愪氦缁欑敤鎴?Coordinator 鍐崇瓥
-
-**Step 5**: 纭鍚庢墽琛?
-
-### 2.1 绗竴鎬у師鐞?+ 濂ュ崱濮嗗墐鍒€
-
-姣忔鍐崇瓥杩介棶锛?
-- "杩欎釜澶嶆潅搴︽槸蹇呰鐨勫悧锛?
-- "鐮嶆帀杩欏眰鎶借薄浼氭€庢牱锛?
-- "褰撳墠鐨勬柟妗堣В鍐充簡浠€涔堥棶棰橈紵鏄惁鍒涢€犱簡鏂伴棶棰橈紵"
-
-鐢ㄥ墐鍒€鐮嶆帀鎵€鏈変笉蹇呰鐨勬娊璞°€?
-
-## 3. 鍙岃褰曟満鍒?
-
-### 3.1 鍐崇瓥鏃ュ織 (docs/decisions/)
-
-姣忔鏋舵瀯鍐崇瓥锛堝紩鍏ユ柊缁勪欢銆佸鍔犳娊璞″眰銆佸彉鏇存帴鍙ｏ級璁板綍鍦ㄩ」鐩?`docs/decisions/` 涓嬶細
-
-```
-docs/decisions/YYYY-MM-DD-绠€鐭弿杩?md
-```
-
-鏍煎紡锛?
-```markdown
-# 鍐崇瓥: [鏍囬]
-
-## Context
-涓轰粈涔堥渶瑕佸仛杩欎釜鍐崇瓥锛熷綋鍓嶇姸鎬佹槸浠€涔堬紵
-
-## Decision
-鍋氫簡浠€涔堥€夋嫨锛?
-
-## Consequences
-杩欎釜閫夋嫨鐨勫奖鍝嶅拰鍚庢灉鏄粈涔堬紵
-
-## Alternatives Considered
-鑰冭檻浜嗗摢浜涙浛浠ｆ柟妗堬紵涓轰粈涔堟病閫夛紵
-```
-
-### 3.2 缁忛獙鏁欒 (docs/learned.md)
-
-琚籂姝ｅ悗杩藉姞涓€鏉¤褰曪細
-
-```markdown
-- [YYYY-MM-DD] 闂: xxx | 鏍瑰洜: xxx | 姝ｇ‘鍋氭硶: xxx
-```
-
-**姣忔鏂颁换鍔″墠锛屽繀椤诲厛鎵竴閬?docs/learned.md銆?*
-
-## 4. /rethink 鎸囦护锛堜笂甯濇寜閽級
-
-褰撶敤鎴锋垨 Coordinator 鍙戠幇 Agent 鏂瑰悜鍋忎簡鏃讹紝鍙戦€?`/rethink` 鎸囦护銆侫gent 蹇呴』鍦ㄦ敹鍒板悗锛?
-
-1. **绔嬪嵆鍋滄鎵€鏈夋搷浣?*
-2. **杈撳嚭褰撳墠鐞嗚В**锛?鎴戜互涓虹洰鏍囨槸 X锛屾鍦ㄥ仛 Y"
-3. **杈撳嚭鑷缁撴灉**锛?
-   - 杩欎釜闂鎴戦亣鍒颁簡浠€涔堝洶鎯戯紵
-   - 鎴戠殑鏂规鏄粈涔堬紵
-   - 鏄惁瀛樺湪鏇寸畝鍗曟柟妗堬紵
-   - 鏄惁鏈夐獙璇佽繃姣忎釜鍋囪锛?
-4. **绛夊緟閲嶆柊纭**锛氬湪寰楀埌鏄庣‘鐨勬柟鍚戞寚绀哄墠锛屼笉鍐嶇户缁墽琛?
-
-## 5. 瑙勫垯杩涘寲
-
-- 鏈枃妗ｆ斁鍦ㄩ」鐩牴鐩綍涓嬶紝鎻愪氦鍒?git
-- 姣忔浠庣籂姝ｄ腑瀛﹀埌鏂扮粡楠岋紝鏇存柊鍒版湰鏂囨。涓?
-- 鎵€鏈?Agent 鍏变韩姝ゆ枃妗ｏ紝璺ㄩ」鐩彲澶嶇敤
-
-## 闄勫綍: 鍒ゆ柇鍑嗗垯鏄惁鐢熸晥
-
-- Diff 骞插噣涓旀渶灏忓寲锛屽彧鏈夎姹傛墍闇€鐨勬敼鍔?
-- 涓嶅啀鍥犺繃搴﹀鏉傚寲鑰岄渶瑕侀噸鍐?
-- 婢勬竻闂鍑虹幇鍦ㄥ疄鐜颁箣鍓嶏紝鑰屼笉鏄姱閿欎箣鍚?
-- 姣忔鏋舵瀯鍐崇瓥鍓嶉兘缁忚繃浜嗗鎶楁€у鏌?
-- 缁忛獙鏁欒鍦ㄥ悗缁换鍔′腑琚鐢紙涓嶅啀韪╁悓涓€鍧戯級
-
----
-鐗堟湰: 1.0 | 2026-07-08 | 鎻愭 #23
+# AGENTS.md — 决策自检协议
+
+基于 Andrej Karpathy 四大核心原则 + 诗光进化版 + 对抗性审查机制。
+本文档是所有 Agent（莫荷、xxm/笑笑、知微、小果）的共享决策纪律协议。
+
+## 1. 核心规则
+
+### 1.1 思考先于编码
+
+拿到需求后，禁止直接开始编码/设计。必须依次执行：
+
+0. **读对应模块的 § spec**：如果涉及已有功能模块，先读 `gateway/scripts/specs/{module}.json` 的 `ai_spec` 了解实际架构、接口、约束和依赖。spec 在 `docs/dev-spec.md` 的模块清单中可查
+1. **复述需求**：用自己的话复述对需求的理解，列出不确定点
+2. **列出候选方案**：存在多种合理架构方案时，列出至少 2 种方案并对比优劣
+3. **选择最简方案**：基于复杂度、工作量、可维护性选择最简方案
+4. **等待确认**：在得到用户/Coordinator 确认前，禁止开始编码
+
+### 1.2 极简优先
+
+每一次引入新抽象/新中间层/新工具前，先问："不用它行不行？"
+
+- 能用函数解决的问题，不用类
+- 能用类解决的问题，不用框架
+- 不为"未来可能需要的灵活性"写一行代码
+- 一次性脚本不做复杂封装
+- 不为纯假设的极端场景添加复杂兜底
+
+### 1.3 精准修改
+
+- 修改前先读对应模块的 § spec（`gateway/scripts/specs/{module}.json`），确认架构理解和约束
+- 修改前输出执行计划（改哪几个文件、改什么、为什么改）
+- 只改动需求直接涉及的文件，不顺手"优化"无关代码
+- 一次只改一个逻辑单元，验证通过再改下一个
+- 不重构没有问题的代码
+- 删除本次修改导致不再使用的代码，但不删除修改前已存在的死代码（除非用户明确要求）
+- **改完同步 spec**：修改完成后，将对应模块的 `specs/{module}.json` 更新为与实际实现一致
+
+### 1.4 目标导向交付
+
+- 多步骤任务先写入 task 清单，每完成一步标注进度
+- 改动附带简要说明（改了什么、为什么改）
+- 任务完成后用 3-5 句话总结：做了什么、学到了什么、下次怎么做不同
+- 被纠正后，在 docs/learned.md 中追加经验教训记录
+
+## 2. 对抗性审查流程
+
+当 Agent 准备执行一个涉及架构选型的任务时，强制走以下检查点：
+
+**Step 1**: 写方案草案（最直觉的方案）
+
+**Step 2**: 对抗性审查（自问）：
+- 这个方案是不是我习惯性选择的？
+- 有没有更简单的方案被我跳过了？
+- 每一层抽象真的必要吗？去掉会怎样？
+- 如果明天就要交接给其他人，他会觉得这个设计是必要的吗？
+
+**Step 3**: 列出对比方案（至少 2 个），标注复杂度、工作量、可维护性差异
+
+**Step 4**: 提交给用户/Coordinator 决策
+
+**Step 5**: 确认后执行
+
+### 2.1 第一性原理 + 奥卡姆剃刀
+
+每次决策追问：
+- "这个复杂度是必要的吗？"
+- "砍掉这层抽象会怎样？"
+- "当前的方案解决了什么问题？是否创造了新问题？"
+
+用剃刀砍掉所有不必要的抽象。
+
+## 3. 双记录机制
+
+### 3.1 决策日志 (docs/decisions/)
+
+每次架构决策（引入新组件、增加抽象层、变更接口）记录在项目 `docs/decisions/` 下：
+
+```
+docs/decisions/YYYY-MM-DD-简短描述.md
+```
+
+格式：
+```markdown
+# 决策: [标题]
+
+## Context
+为什么需要做这个决策？当前状态是什么？
+
+## Decision
+做了什么选择？
+
+## Consequences
+这个选择的影响和后果是什么？
+
+## Alternatives Considered
+考虑了哪些替代方案？为什么没选？
+```
+
+### 3.2 经验教训 (docs/learned.md)
+
+被纠正后追加一条记录：
+
+```markdown
+- [YYYY-MM-DD] 问题: xxx | 根因: xxx | 正确做法: xxx
+```
+
+**每次新任务前，必须先扫一遍 docs/learned.md。**
+
+## 4. /rethink 指令（上帝按钮）
+
+当用户或 Coordinator 发现 Agent 方向偏了时，发送 `/rethink` 指令。Agent 必须在收到后：
+
+1. **立即停止所有操作**
+2. **输出当前理解**："我以为目标是 X，正在做 Y"
+3. **输出自检结果**：
+   - 这个问题我遇到了什么困惑？
+   - 我的方案是什么？
+   - 是否存在更简单方案？
+   - 是否有验证过每个假设？
+4. **等待重新确认**：在得到明确的方向指示前，不再继续执行
+
+## 5. 规则进化
+
+- 本文档放在项目根目录下，提交到 git
+- 每次从纠正中学到新经验，更新到本文档中
+- 所有 Agent 共享此文档，跨项目可复用
+
+## 附录: 判断准则是否生效
+
+- Diff 干净且最小化，只有请求所需的改动
+- 不再因过度复杂化而需要重写
+- 澄清问题出现在实现之前，而不是犯错之后
+- 每次架构决策前都经过了对抗性审查
+- 经验教训在后续任务中被复用（不再踩同一坑）
+
+---
+版本: 1.0 | 2026-07-08 | 提案 #23