From 0f0b8d8fe13bfacc8f808acc6743137a98843287 Mon Sep 17 00:00:00 2001 From: bboonnee Date: Sat, 8 Aug 2026 16:48:15 +0800 Subject: [PATCH] docs: record the core self-evolution methodology - Reflection -> Fix-Skill -> Re-loop --- docs/todo/org-graph-unification-and-universal-self-planning-requirements.md | 17 ++++++++++++++++- docs/todo/org-graph-unification-phase2-universal-self-planning-design.md | 3 +++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/docs/todo/org-graph-unification-and-universal-self-planning-requirements.md b/docs/todo/org-graph-unification-and-universal-self-planning-requirements.md index 680a31a..7ba62b1 100644 --- a/docs/todo/org-graph-unification-and-universal-self-planning-requirements.md +++ b/docs/todo/org-graph-unification-and-universal-self-planning-requirements.md @@ -59,10 +59,25 @@ | FR-1 | Org Graph 固定流程改为 `Planner → Validator(复核 Planner 产出) → Coder → Validator(终审实现)`：新增 `task.status` 枚举值（schema 迁移）+ `org_node_lifecycle._PRE_STATE`/`_POST_STATE` 扩展 + `run_task_lifecycle()`/`run_or_resume_task_lifecycle()` 新分支。**该分支落地时一并修复 `task-execution-resume-assumes-planner-artifacts-exist.md` 记录的 resume 假设 artifact 存在的 bug**（同一段代码路径，不分两次改）。 | 1 | | FR-2 | Coder（`implement_code()`）、Validator（`validate_implementation_with_own_graph()`）两处调用点，把硬编码 manifest 换成真实调用 `plan_work_graph(conn, "coder"/"validator", ...)`——函数本身已通用，只需替换调用点。 | 2 | | FR-3 | `graph_manifest` 节点 schema 扩展显式的"实现绑定"字段：这个节点由哪个 subagent + 哪个 skill + 哪些 tools + 输入输出 data 实现。今天的 `judgment`/`on_fail` 已覆盖"怎么判断成功/失败、失败去哪"，但"用什么实现"这一半目前只是 `_GENERIC_PROMPT_TEMPLATE` 给的一段自由文本 `task_prompt`，不是结构化字段——这是本次真正的新增 schema 工作。 | 2 | -| FR-4 | 新增一个 org-agent-无关的"节点级验证"skill（可被任意角色的 `role.json` 引用），作为 `judgment.kind="llm"` 的标准实现：验证节点输出、判断根因、精确 `loop_back` 到需要修复的节点。用它统一/取代 `org_level_loop.py` 今天的粗粒度 `fast_lane`/`full_replan` 路由——这是 `org-graph-as-work-graph-unified-loop-requirements.md` 的核心诉求，按 §4 已拍板的方案 A（合图）落地：`loop_back` 目标节点和触发验证的节点在同一个 `work_graph_run` 内，不需要跨图寻址。 | 4 | +| FR-4 | 新增一个 org-agent-无关的"节点级验证"skill（可被任意角色的 `role.json` 引用），作为 `judgment.kind="llm"` 的标准实现：验证节点输出、判断根因、精确 `loop_back` 到需要修复的节点，且当根因是**系统性 skill 缺陷**时先修 Skill 本身再重试——完整方法论见 §3.1，不是单纯"跳回某个节点重试"。用它统一/取代 `org_level_loop.py` 今天的粗粒度 `fast_lane`/`full_replan` 路由——这是 `org-graph-as-work-graph-unified-loop-requirements.md` 的核心诉求，按 §4 已拍板的方案 A（合图）落地：`loop_back` 目标节点和触发验证的节点在同一个 `work_graph_run` 内，不需要跨图寻址。 | 4 | | FR-5a | 前端新增 Org 级元图：把 Planner/复核 Validator/Coder/终审 Validator 四段渲染成一张顶层图，每段可展开成该 Org Agent 自己的 Work Graph 详情（复用现有 `renderGraphVisualizerPanel`，不重写渲染器）。 | 3 | | FR-5b | 前端新增同一个 `work_graph_run` 内按 `attempt_number` 的历史回放时间轴/scrubber，复用已经在拉取但未渲染的 `loop_back_events[].feedback`。 | 3 | +### 3.1 核心方法论（用户 2026-08-08 拍板，作为本项目开发的目标写在这里）：失败即进化——Reflection → Fix-Skill → Re-loop + +**这是 Work Graph"自我进化"能力的精髓，FR-4 必须按这个方法论实现，不能退化成"判断失败→跳回某个节点重试"这么简单。** 用户原话的核心洞察：一个节点判断失败后，我们要的不只是"把这一次的错误修好"（fix-bug，只解决这一次），而是"让这一类错误以后不会再发生"（fix-skill，永久解决）——否则下一个类似任务撞上同一个坑，还是要重新踩一遍、重新修一遍。 + +**四步链路**（不是一个笼统的"loop_back"，是四个明确的阶段/节点）： + +1. **判断分支**：节点产出被判定 `false`/`error`/`wrong`（`judgment.kind` 不管是 `mechanical` 还是 `llm`，只要 `ok=False`）——不是简单重试，跳转到分支 B。 +2. **分支 B 第一个节点：Reflection-review**——对整条链路做复盘，不只是"这个节点自己错在哪"，而是**全链路根因定位**：到底是哪一个更早的环节（可能是这个节点自己的 Skill 有缺陷，也可能是更早某个上游节点的产出本身就有问题）真正导致了这次失败。判断结论要落到两种性质里的一种： + - **一次性内容错误**（这次具体的产出恰好没写好，Skill/方法论本身没问题）——走现有的精确 `loop_back`（Phase 2 SDD §5 的 `dynamic_loop_back`）即可，跳回真正的根因节点重新生成。 + - **系统性 skill 缺陷**（这个 org_node 用来产出这类内容的 Skill 本身有方法论层面的问题，同类任务会反复踩同一个坑）——进入第 3 步。 +3. **Fix-skill 节点**：不是修这一次的输出，是**修 Skill 本身**——真实调用已经存在的 Skill 迭代机制（`src/skill_update.py::update_skill()` + `src/bug_record.py::create_bug_record(root_cause_category='skill_defect')`），产出一次真实的、Git 版本化、可回滚的 Skill 内容更新（`skill_iteration` 表，`before_git_commit_sha`/`after_git_commit_sha` 都是真实 commit，不是模拟）。**这套机制在代码库里早就存在**（U-015/U-016 时期就建好了），但至今只在 `org_level_loop.py` 的 Org 级粗粒度路径上被触发过——FR-4 要把它真正接进 Work Graph 内部的判断/回路循环，让它成为节点级失败恢复的常规路径之一，不是只有跨 Org Agent 的大失败才配触发。 +4. **跳回执行**：Skill 更新落地后，跳回"用这个 Skill 的节点"重新执行——这次用的是刚修好的新 Skill，不是拿旧 Skill 再赌一次运气。跟 `_loop_history_prompt_suffix`（现有机制，把历史反馈拼进 prompt）的本质区别：prompt 里的反馈是**这一次任务专属、跑完就忘**的临时纠偏；Skill 更新是**持久化、跨任务复用**的真正修复——两者不互斥（可以同时生效：这次重试既带着历史反馈，也带着已经更新的 Skill），但 FR-4 的核心价值在后者。 + +**跟 Phase 2 SDD 的关系**：`docs/todo/org-graph-unification-phase2-universal-self-planning-design.md` §5 设计的 `on_fail.action="dynamic_loop_back"` 是这个方法论第 1/2/4 步（判断失败 → 动态诊断根因节点 → 跳回执行）的**已完成设计**，但**第 3 步（Fix-skill）还没有设计**——目前的 `dynamic_loop_back` 只处理"一次性内容错误"这一种诊断结果，没有覆盖"系统性 skill 缺陷"这条分支。这是 Phase 2 设计文档需要补齐的部分，不是另开一个 Phase——具体设计（Reflection-review 节点判断"一次性 vs 系统性"的标准、Fix-skill 节点的 graph_manifest 形状、"用哪个 Skill 文件"跟"节点声明的 skill_ref"字段（FR-3）怎么对应上）留给该文档的下一次修订。 + --- ## 4. 关键架构决策：方案 A（合图）——已确认，2026-08-08 diff --git a/docs/todo/org-graph-unification-phase2-universal-self-planning-design.md b/docs/todo/org-graph-unification-phase2-universal-self-planning-design.md index 4ba3a00..c031d03 100644 --- a/docs/todo/org-graph-unification-phase2-universal-self-planning-design.md +++ b/docs/todo/org-graph-unification-phase2-universal-self-planning-design.md @@ -222,6 +222,8 @@ def _run_one_node(conn, run_id, org_node, skill_id, target_folder_path, node, ou ## 5. 新增 `on_fail.action = "dynamic_loop_back"`（对应 §1.3，FR-4 的核心） +**2026-08-08 范围说明**：需求文档新增 §3.1（"失败即进化：Reflection → Fix-Skill → Re-loop"）把 FR-4 的完整方法论定为四步——判断失败→Reflection-review 动态诊断根因→**如果根因是系统性 Skill 缺陷,先修 Skill 本身（真实调用 `skill_update.py::update_skill()`,产出 Git 版本化的 Skill 迭代)**→跳回执行。本节设计的 `dynamic_loop_back` 只覆盖第 1/2/4 步（诊断根因节点 + 跳回执行），对应"一次性内容错误"这一种诊断结果；**"系统性 skill 缺陷"分支（第 3 步 Fix-skill 节点）还没有设计**，是本文档已知的缺口，不是遗漏——留给下一次修订，具体要解决：Reflection-review 怎么判断"一次性 vs 系统性"、Fix-skill 节点的 graph_manifest 形状、`skill_update.update_skill()` 需要的 `skill_id`/`repo_path` 跟 §4 节点级 `skill_ref` 字段怎么对应。 + ### 5.1 语义 跟现有 `loop_back`（跳回一个规划阶段就写死的固定目标）不同，`dynamic_loop_back` 表示"这个节点失败时，由一次专门的根因判断调用，从这个节点的全部上游祖先节点里动态选出真正该回退的目标"——只用于合适放在**图末端的终审性判断节点**（比如 Phase 1 引入的终审 Validator 节点），不要求每个节点都用这个更贵的机制。 @@ -391,6 +393,7 @@ Phase 1 阶段"复核失败先用现有 `org_level_loop.py` 粗粒度路由兜 2. **`promotes_to_artifact`（§2.3）依赖 Coder/Validator 老实遵守"只有最终交付物才声明"这条约束**——是 prompt 层面的软约束,不是机械强制,理论上 LLM 可能给每个节点都声明 `promotes_to_artifact`（虽然 artifact_type 枚举本身会挡住不合法值,但不会挡住"过度声明"这种滥用）,需要在真实运行中观察是否需要加机械检查。 3. **`dynamic_loop_back` 的"同一 source 总次数上限"（§5.5 第 3 点）需要新的 `work_graph_loop_limit_config` key 形状**——`"{org_node}:{source_node_id}:total"` 这个具体格式没有先例,实施时需要重新过一遍 `settings_config.py` 的查询/写入接口是否兼容这种三段式 key,还是需要专门扩展。 4. **`org_level_loop.py` 新旧流程共存期的判断依据**（§7.2 结尾）还没有定论,是留给实施阶段解决的开放问题,不是本文档的疏漏——但这个问题不解决,Phase 2 上线当天就会有"旧任务卡在新代码路径里"的真实风险,实施顺序上应该早排。 +5. **需求文档 §3.1 方法论的第 3 步（Fix-skill）完全没有设计**（本节 §5 开头已标注）——`dynamic_loop_back` 目前只实现"诊断根因节点 + 跳回"，"根因是系统性 Skill 缺陷时先修 Skill 本身"这条分支是 FR-4 方法论里明确要求、但本文档还没给出具体设计的部分，是当前最大的范围缺口，不是细节问题——建议作为 Phase 2c（或独立的 Phase 2d）优先设计，而不是留到实施中间即兴决定。 --- -- libgit2 0.21.4