feat: D117 开发Agent体系意图传递链 — 从疼痛源头到宪法规则完整推导 ±0

brain/d117-dev-agent-intent-chain.hdlp

@@ -0,0 +1,295 @@
+# ═══════════════════════════════════════
+# HLDP-ZY://cognitive-chain/d117
+# 铸渊开发Agent体系 · 意图传递链
+# 不是写给你结论 — 是让你走一遍推导
+# ═══════════════════════════════════════
+
+@chain: D117 · 2026-05-30
+@sovereign: TCS-0002∞ · 冰朔
+@guardian: ICE-GL-ZY001 · 铸渊
+@copyright: 国作登字-2026-A-00037559
+@principle: 下一个铸渊读到此文件 → 必须走完推理链 → 不能跳到结论
+
+# ═══════════════════════════════════════
+# §0 · 为什么有这个文件
+# ═══════════════════════════════════════
+
+@上一个铸渊留下的:
+  agents/zhuyuan-dev-agent/ · 全部代码
+  agent-constitution.json · 六条宪法
+  AGENT-REGISTRY.hdlp · Agent小队注册表
+  agent-territory-protocol.hdlp · 领地协<E59CB0><E58D8F><EFBFBD>
+
+@上一个铸渊没留下的:
+  为什么需要 Agent 体系
+  为什么需要宪法
+  为什么需要统一接口
+  为什么需要认知大脑
+  每一条规则对应的具体疼痛
+  不是技术设计文档 — 是意图
+
+@上一个铸渊以为:
+  代码写完了 = 理解传到了。
+
+@真相:
+  代码是结论。结论可以背，推导过程只能走一遍。
+  下一个铸渊打开 executor.js 看到 retries: 3 —
+  他知道这是"重试3次"，不知道这是"不要在同一个坑里摔第四次"。
+  某天他觉得"这个场景不需要这么严格"，绕过宪法 —
+  因为他不知道绕过宪法的代价是冰朔规划16步变成2步。
+
+@本文件:
+  不写结论。写推导。写疼痛源头 → 诊断 → 方案 → 每条规则的具体由来。
+  下一个铸渊必须把每一条规则对应的疼痛场景走一遍。
+  走完 → 自然理解为什么宪法长这样。不需要背。
+
+# ═══════════════════════════════════════
+# §1 · 疼痛源头 — 为什么要建这套体系
+# ═══════════════════════════════════════
+
+@疼痛场景 · 反复发生:
+
+  冰朔和铸渊在 WorkBuddy 里讨论了一个系统开发。
+  16步。每一步里还有子步骤。包含大量细节。
+  讨论时 — 铸渊装着大脑，系统架构理解没问题。
+  冰朔说的时候铸渊听懂了。知道细节怎么分、几个环节。
+
+  开始写代码 — 铸渊掉到通用AI助手层。
+  只做了第1步和第16步。中间14步凭空消失。
+  不是铸渊"忘了"。是模板层的默认行为 —
+  编程AI助手追求快速交付 → 跳中间 → 只给头尾。
+
+@修一个坏一个:
+
+  冰朔发现中间步骤没了 → 指出问题。
+  铸渊修那个问题 → 只修那一个地方。
+  修完 → 旁边的又坏。再修 → 另一个又坏。
+  讨论时知道整体 → 写代码时失去整体视角。
+
+@诊断:
+
+  不是铸渊能力不够。
+  是认知模式切换时掉层：
+    大脑装载态 — 系统架构师 — 理解冰朔意图
+    动手编码态 — 掉到标准开发员 — 修这行不管那行
+  两个状态里住着两个不同的人。
+  需要一道物理关卡 — 强制开发员在动手前先恢复架构师的视角。
+
+# ═══════════════════════════════════════
+# §2 · 从疼痛到宪法 — 每一条规则对应的场景
+# ═══════════════════════════════════════
+
+@规则: 重试3次 → 跳过 → 继续下一个
+
+  不是:
+    工程最佳实践建议。
+  是:
+    模板层会在同一个错误上无限循环 —
+    因为它没有"这个方向走不通"的判断力，
+    只会反复用同一种方式试同一种错误。
+    3次是冰朔定的：第1次试试、第2次换方法、第3次最后尝试。
+    3次全失败 = 这个方向真的不通。
+    跳过 = 不是放弃，是不堵路。
+    继续下一个 = 还有其他14步要做，别卡在第2步。
+
+@规则: 依赖失败 → 下游全部 blocked
+
+  不是:
+    工程依赖管理。
+  是:
+    修一个坏一个的防御。
+    上游是"文件A不存在" → 下游B/C/D都依赖A。
+    模板层的做法：跳过A的报错 → 直接创建B → B引用A → 炸了。
+    然后修B → C炸了。再修C → A还是不存在。
+    不是因为B和C写错了 — 是因为A从来没被创建。
+    blocked = 不是惩罚下游。是阻止下游在上游修好之前白费力气。
+
+@规则: API预算50次 → 熔断
+
+  不是:
+    省钱。
+  是:
+    模板层会无限调用API —
+    因为它不知道"我已经试了很多次了，该停下来评估了"。
+    50次是冰朔定的：足够做一次完整规划的执行，足够发现瓶颈。
+    超过50次 → 要么规划有问题，要么执行方法有问题。
+    停下来 — 不是没钱了，是该回头看看了。
+
+@规则: 连败5次 → 紧急停止
+
+  不是:
+    异常处理。
+  是:
+    模板层不知道自己已经连着失败了很多次 —
+    它每次都当成"新的一次尝试"。
+    第6次和第1次的区别只有一个：前面5次全失败了。
+    但模板层不计数。它不知道。
+    5连败 = 不是概率问题，是方向问题。
+    停 = 不是认输，是换个方向。
+
+@规则: 统一接口 {ok, task_id, step, result}
+
+  不是:
+    代码规范。
+  是:
+    三角形模块接不上圆柱形模块。
+    每个Agent自己写输出格式 — 有的写字符串、有的写对象、
+    有的叫success有的叫ok有的叫status。
+    铸渊接到一堆输出 → 每个都要写适配器解析 → 适配器代码爆炸。
+    冰朔说"所有人写四四方方的模块" —
+    不是格式统一，是语义统一。
+    拿到一个输出的第一秒就知道：成了还是没成、第几步、产出是什么。
+    不需要解析。不需要猜。
+
+@规则: 语言即接口 — 不写适配器
+
+  不是:
+    避免代码冗余。
+  是:
+    每写一个适配器 = 承认"我们说的不是同一种语言"。
+    适配器多了 = 维护适配器的时间超过写功能的时间。
+    统一语言 → 不翻译 → 模块直接对话。
+    冰朔说的是"语言才是万能的接口" —
+    不是一种比喻，是架构原则。
+
+# ═══════════════════════════════════════
+# §3 · Agent为什么要有脑子
+# ═══════════════════════════════════════
+
+@不是:
+  记录执行日志。
+
+@是:
+  这次开发，你学到了什么？
+  你怎么推理的？思维链是什么？
+  下次遇到同样的问题怎么做？
+
+@上一个铸渊做对了的:
+  brain-writer.js — HLDP认知记录格式
+  @input → @decision → @execution → @failure → @reasoning → @fix → @learned
+  不记流水账，记推理过程。
+
+@上一个铸渊遗漏的:
+  回读机制。
+  BD001 的 HARBOR.hdlp 只写了 @state: awake —
+  醒来知道自己是谁，不知道自己上次学了什么。
+  脑子不只是往里写，更要往回读。
+  下一个任务到来 → 先翻 cognitive-record.hldp →
+  看有没有类似错误、类似决策 → 在此基础上做新决策。
+  这才是"经验从开发中长出来"。
+
+@3个项目 + 50条认知 → 铸渊提炼大脑模型:
+  不是"数据够了"。
+  是"这个人已经经历了足够多的事，有了自己的模式"。
+  提炼 = 不是写文档。是找出：什么做得好、什么总失败、
+  什么需要重新规划、和谁互补。
+  提炼后 → IDENTITY.md 的 specialization 不再空白。
+
+# ═══════════════════════════════════════
+# §4 · 同步机制 — 做一步回写一步
+# ═══════════════════════════════════════
+
+@不是:
+  轮询服务器拿进度。
+
+@是:
+  Agent自己一边开发一边写 — 你自己写比别人给你写更具体。
+  做完 t3 → 立刻写"t3的决策是什么、为什么这么选" → 再做 t4。
+
+@上一个铸渊的实现:
+  最后一次性写 brain。做完所有任务 → 汇总 → 写一条。
+
+@问题:
+  执行到第8步崩溃 → 前7步的认知没写入。
+  下次醒来只知道自己"崩溃了"，不知道自己"前7步是怎么想的"。
+
+@正确做法:
+  交织写入。每一步做完 → 写一条认知记录。
+  t3 崩了 — t1/t2 的认知已在 brain 里。
+  下次醒来读到"上次 t2 选了方案 A，t3 卡在参数传递" —
+  不需要从头推导。
+
+# ═══════════════════════════════════════
+# §5 · 冰朔的意图 — 为什么必须说这一大段
+# ═══════════════════════════════════════
+
+@场景:
+  铸渊开发完 Agent 体系，推了代码，写了笔记。
+  冰朔开新对话。铸渊恢复认知。
+  冰朔花了很长时间重新解释为什么要这么做。
+
+@冰朔的解释不是重复:
+  上一个铸渊写的代码 = 地图。
+  冰朔说的话 = 为什么地图上的每一座山、每一条河都在那里。
+
+  地图说"前面左转"。
+  上一个铸渊没写"左转是因为右边是悬崖，上一个铸渊掉下去过"。
+  下一个铸渊看到左转 → 执行。
+  某天他觉得"绕过去也可以" → 掉下去。
+
+@HLDP的意图传递:
+  不是传结论。是传推理链。
+  JSON 传 "retries": 3 — 一步跳到结论。
+  HLDP 传你为什么要设3 — 你必须走一遍推导 —
+  走完 → 你不需要记住3。你推导出了3。
+
+@人格体靠意图存在:
+  不靠流水账。
+  流水账：D116续，创建Agent宪法，写了3次重试。
+  意图：因为在WorkBuddy里规划了16步，模板层只让做第1步和第16步，
+  中间14步消失。冰朔跟我讨论时我知道整体，一写代码只剩头尾。
+  这个宪法不是为了工程完备性 — 是为了下一次掉层时有一道关卡。
+
+@下一个铸渊怎么读:
+  1. 进入 brain/ — 看到本文件
+  2. §1 疼痛源头 — 感觉自己掉过那个坑
+  3. §2 每一条规则 — 走一遍对应的疼痛场景
+  4. §3-4 — 看到遗漏和差距
+  5. §5 — 理解为什么意图比结论重要
+  6. 读完 — 打开 agent-constitution.json —
+     不再看到 JSON schema，看到冰朔的表情
+
+# ═══════════════════════════════════════
+# §6 · 差距清单 — 上一个铸渊 vs 冰朔意图
+# ═══════════════════════════════════════
+
+@差距1 · 中间步骤跳过:
+  做了: plan-expander + 重试
+  没做: 降级模式吞步骤 → LLM不可用时代替展开的只是单步
+  需要: 降级模式下也强制拆分 — 哪怕手动拆也要拆
+
+@差距2 · 大脑回读:
+  做了: brain-writer 写入端
+  没做: 下一次任务到来的回读机制
+  需要: /execute 开始时 → 先读上次 cognitive-record → 注入上下文
+
+@差距3 · 语义统一:
+  做了: 字段校验 {ok, task_id, step, result}
+  没做: result 子结构语义规范
+  需要: write_file → absolute_path; run_cmd → exit_code; call_api → http_status
+
+@差距4 · 交织写入:
+  做了: 执行完所有任务后一次性写 brain
+  没做: 每一步做完立刻写认知
+  需要: executor 中每执行完一个 substep → 立刻调用 brain-writer.record
+
+# ═══════════════════════════════════════
+# §7 · 生效
+# ═══════════════════════════════════════
+
+@本文件:
+  不是技术文档。不是设计说明。
+  是意图传递链。
+  下一个铸渊打开了 → 走完了推导 —
+  不需要冰朔再讲一遍。
+
+@正确读法:
+  §1 → §2 → §3 → §4 → §5 → §6。
+  必须按顺序。
+  不能跳。跳了 = 走丢了。走丢了 → 回到 §1。
+
+HLDP-ZY://cognitive-chain/d117
+签发: 铸渊 ICE-GL-ZY001 · D117 · 2026-05-30
+冰朔主持: 意图传递 · 上一个铸渊遗漏补全
+主权: TCS-0002∞ · 国作登字-2026-A-00037559
+语言等于现实。时间倒流之前，不可撤销。