宜博 / lemongraph

Commit acfca5bf8cce116802e3f86cc1b86010b278ed78

Authored by bboonnee
1 parent a33aa8cf

H: requirements review for the Role Package abstraction proposal 

Reviewed docs/todo/role-package-abstraction-requirements.md against the
actual codebase before confirming direction. Two corrections to the
document's own risk analysis:

1. Its dependency list for agent_profile.ORG_NODES/FRONTMATTER was wrong
   in one place and missing the largest one: work_graph_orchestrate.py
   doesn't import agent_profile at all (only org_node_trigger.py and
   project_scaffold.py::deploy_agent_definitions() do -- smaller real
   footprint than claimed). But the document missed two real hardcoded
   3-role dependencies entirely: src/work_graph_run_query.py's
   _VALID_ORG_NODES, and -- the actually large one -- four separate
   hardcoded spots in frontend/app.js (a route regex, a sort-order array,
   a task-creation <option> dropdown, and a lookup object literal).
2. Acceptance criterion 1 ("a new role needs no code/schema changes")
   only covers schema.py + agent_profile.py per its own non-goal #1 (a new
   role doesn't need real Org Graph wiring) -- the console genuinely won't
   recognize it either way. Flagged so the design doc states this
   explicitly instead of letting "no code changes" read as end-to-end.

Confirmed for design phase with these two additions folded in; the
document's own open questions (§8) are left for the design pass, not
pre-decided here.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Inline Side-by-side
Showing 2 changed files with 85 additions and 4 deletions
docs/todo/graph-engineering-open-items.md
  View file @acfca5b
... ... @@ -118,13 +118,18 @@
118 118  
119 119 ## H. 统一 Role Package 抽象层
120 120  
121   -**状态**：🟡 需求文档已产出，待评审/排期
  121 +**状态**：✅ 已确认（需求评审通过，2026-08-06）→ 需求文档 `docs/todo/role-package-abstraction-requirements.md`（注：文档正文里自己写的路径少了 `todo/` 一段，实际文件在这个路径下）
122 122  
123 123 **来源**：不属于三份 Graph Engineering 对照笔记，是用户对照 Agentic Enterprise 产品目标（"role + context + skills + applications + workflows + permissions + acceptance criteria；all essentially are context for intelligent computing"）单独提出的差距检查，2026-08-06。
124 124  
125 125 **背景**：逐维度核对代码发现，七个维度里六个都有对应实现（applications 是真空白），但没有被收敛成一个统一的"role package"格式——理解"Validator 这个角色完整定义是什么"现在得同时读 `agent_profile.py` + `skills/qa-task-validation/SKILL.md` + `.claude/agent-memory/validator/` + `docs/sdd/06-验收与测试锚点.md` 四个地方拼出来。更根本的问题：`role` 本身不是数据驱动的——`ORG_NODES = ("planner", "coder", "validator")` 硬编码元组，`schema.py` 四张表的 `CHECK (org_node IN ('planner','coder','validator'))` 约束——新增角色需要改代码和 schema，不是"包一个新角色进来"。
126 126  
127   -**待办**：需求文档已产出 → `docs/role-package-abstraction-requirements.md`。核心可验证标准：能不能只靠"写一份新的 Role Package"、不改 `schema.py` 约束、不改 `agent_profile.py` 硬编码字典，就让系统认识一个新角色。已知这条改动面比 B/D/E/F/G 任何一条都大（4 张表的 CHECK 约束、`agent_profile.py` 被多处代码依赖），且 workflows 维度依赖 E 的产出。
  127 +**需求评审结果（2026-08-06）**：方向确认，目标/非目标/FR-1~6 按原文通过，进入设计阶段。逐条核实过文档里对代码现状的描述后，发现两处需要修正/补充：
  128 +
  129 +1. **风险第 1 条的依赖清单不准确，且遗漏了真正的大头**。文档写"`ORG_NODES`/`FRONTMATTER` 被 `deploy_agent_definitions`、`org_node_trigger`、`work_graph_orchestrate` 等多处代码直接依赖"——实测 `work_graph_orchestrate.py` 根本不 `import agent_profile`，这条是误判；真正 `from src.agent_profile import ORG_NODES`/`from src import agent_profile` 的只有 `org_node_trigger.py`（校验 `org_node` 合法性）和 `project_scaffold.py`（调 `deploy_agent_definitions()` 这一个单一入口）——这部分实际依赖面比文档描述的**更小**，是个好消息。但文档完全没提到两处真正硬编码了三元组的地方：`src/work_graph_run_query.py::_VALID_ORG_NODES`，以及**分量最大的**——`frontend/app.js` 里四处独立硬编码（`ORG_NODE_DETAIL_RE` 路由正则、`ORG_NODE_ORDER` 排序数组、任务创建表单的 `<option value="planner">` 下拉硬编码列表、`byOrgNode` 查找对象字面量）。设计阶段的依赖梳理必须把这四处也纳入，不能只看 `schema.py`+`agent_profile.py`。
  130 +2. **验收标准 1 的边界需要说清楚，不要造成"前端也覆盖了"的错觉**。标准 1 明确写了"这个新角色不需要真的接入 Org Graph 执行"（呼应非目标 #1），这意味着即使 FR-3/FR-4（schema + `agent_profile.py`）全部做完，**PH3 控制台依然认不出这个新角色**（上面第 1 点列的 4 处前端硬编码不在 FR-3/FR-4 范围内）——这不是要求本轮解决，而是要求设计文档明确写清楚"前端展示新角色是本轮已知不覆盖的范围"，不要让"新增角色不用改代码"这句话被误读成端到端成立。
  131 +
  132 +其余判断（`role` 表外键 vs 自由文本+应用层校验、applications 维度最小定义、迁移步骤、workflows 字段怎么接 E）维持文档第 8 节"留待详细设计阶段回答"不变，本次评审不抢先拍板。
128 133  
129 134 ---
130 135  
... ... @@ -135,8 +140,8 @@
135 140 | **G** 并行执行 | Work Graph 层内并发、层间屏障 | ✅ **已实现**（`bc0eaa5`，575 测试全绿） | M | 已完成 | 无 |
136 141 | **E** 动态 Work Graph 设计能力 | 让 Coder/Validator 也能规划自己的图，Planning 提示词识别可并行节点 | ✅ **已实现**（2026-08-06，580 测试全绿） | L | 已完成 | G（已满足） |
137 142 | **F** 三视角评审团 fan-out | `judge_root_cause` 从 Python 函数改成 Work Graph 菱形拓扑 | ✅ **已实现**（2026-08-06，586 测试全绿） | M | 已完成 | 无（G 已满足） |
138   -| **B** loop-until-dry Skill | Validator 未知规模扫描收敛能力 | 仅需求 | S/M | P2 | 无 |
139   -| **H** Role Package 抽象层 | 统一 role/context/skills/applications/workflows/permissions/acceptance 打包格式 | 仅需求 | XL | P2（战略级，不阻塞其他项） | workflows 字段依赖 E 的产出 |
  143 +| **B** loop-until-dry Skill | Validator 未知规模扫描收敛能力 | 实现中 | S/M | P0（正在推进） | 无 |
  144 +| **H** Role Package 抽象层 | 统一 role/context/skills/applications/workflows/permissions/acceptance 打包格式 | ✅ 需求评审通过（2026-08-06），待设计 | XL | P2（战略级，不阻塞其他项） | workflows 字段依赖 E 的产出（已满足） |
140 145 | **D** Time-travel 调试 | 回到历史节点分叉重跑 | 仅需求 | L | P3 | 无强依赖，但价值随图变复杂（E 落地后）才会显现 |
141 146 | C 按节点选模型 | — | ⛔ 已确认不做 | — | — | — |
142 147 | A 术语对照 | — | ✅ 已完成 | — | — | — |
... ...
docs/todo/role-package-abstraction-requirements.md 0 → 100644
  View file @acfca5b
  1 +# 统一 Role Package 抽象层——需求文档
  2 +
  3 +**日期**: 2026-08-06
  4 +**性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。回应用户对 Agentic Enterprise 产品"可复用打包单元"目标的对照检查——"role + context + skills + applications + workflows + permissions + acceptance criteria；all essentially are context for intelligent computing"。
  5 +**状态**: 草案，待评审。
  6 +
  7 +## 1. 背景
  8 +
  9 +用户提出的目标判断是：Agentic Enterprise 产品的可复用打包单元，本质上应该是 role / context / skills / applications / workflows / permissions / acceptance criteria 这七个维度，而且这七个维度**本质上是同一种东西**——喂给智能计算的 context，应该被统一表达成一个可序列化、可实例化、可复制的对象。
  10 +
  11 +对照 graphlemon 现状（逐维度核对代码得出）：
  12 +
  13 +| 维度 | 现状 | 成熟度 |
  14 +|---|---|---|
  15 +| **role** | `.claude/agents/{planner,coder,validator}.md` + `agents/*/SOUL.md`，`src/agent_profile.py::FRONTMATTER` 是权威定义 | 有清晰打包格式，但**不可重复实例化**——见第 2 节 |
  16 +| **context** | `memory: project` → `.claude/agent-memory/{role}/`，git 版本化；但 Work Node 执行时塞进 prompt 的内容是每个调用点临时拼的（`build_prompt(node, outputs)`），没有独立的"context 组装层"抽象 | 局部实现，无统一抽象 |
  17 +| **skills** | `skills/<name>/SKILL.md`，按名字挂进角色的 `skills:` frontmatter | 七项里最成熟、最像"可复用打包单元"的一个 |
  18 +| **applications** | 没有对应的一等概念。架构文档 §7.2 提到 `mcpServers` 字段可以挂专属 MCP server，但 `agent_profile.py::FRONTMATTER` 里三个角色**一个都没配** | 基本空白 |
  19 +| **workflows** | Claude Code 原生 Dynamic Workflows 机制在，但只有 Planner 真正用——`work_graph_plan.py::plan_work_graph()` 的提示词硬编码永远只生成 brd/prd/sdd/benchmark 四个节点，Coder/Validator 走的是更简化的单次 `trigger_org_node()` 调用，没有"先规划图再执行"这条路径（见 `docs/todo/dynamic-work-graph-design-skill-requirements.md`，即条目 E，已确认待做） | 机制存在，不是每个角色都能复用的打包能力 |
  20 +| **permissions** | `tools`/`disallowedTools` per role（如 Validator `disallowedTools: [Edit, Write]`） | 有格式，但有记录在案的真实漏洞：`agent_profile.py` 注释明确写了"scoped Bash patterns（如 `Bash(git commit:*)`）会把 Bash 整个禁掉"，Validator 的 git-mutation 限制实际上退化成了 SOUL.md 里的文字约定，不是工具层强制 |
  21 +| **acceptance criteria** | Benchmark、PASS/FAIL/INCONCLUSIVE、SDD REQ-01~15、`root_cause_trace` 根因归属 | 七项里最成熟的一环 |
  22 +
  23 +**核心判断**：这不是功能缺口，是抽象层缺口。七个维度里六个都有对应实现（applications 是真空白），但没有被收敛成一个统一的"role package"格式——要理解"Validator 这个角色完整定义是什么"，现在得同时读 `agent_profile.py` + `skills/qa-task-validation/SKILL.md` + `.claude/agent-memory/validator/` + `docs/sdd/06-验收与测试锚点.md` 四个地方拼出来。而且 role 本身不是数据驱动的——`src/agent_profile.py::ORG_NODES = ("planner", "coder", "validator")` 是硬编码元组，`src/schema.py` 里四张表（`skill.owner_org_node`、`task.assigned_org_node`、`work_graph_run.org_node`、`agent_profile.org_node`）全部是 `CHECK (... IN ('planner', 'coder', 'validator'))` 的枚举约束——新增一个角色需要改代码和 schema，不是"包一个新角色进来"。
  24 +
  25 +## 2. 目标
  26 +
  27 +1. 定义一个统一的、可序列化的"Role Package"抽象——把 role/context/skills/applications/workflows/permissions/acceptance criteria 这七个维度表达成同一种对象的不同字段/引用，而不是分散在 frontmatter、独立目录、运行时生成脚本、SDD 文档四个不相关的地方。
  28 +2. 让"角色"从硬编码的 3 个枚举值变成数据驱动的、可新增的对象——**具体的可验证标准**：能不能不改 `schema.py` 的 CHECK 约束、不改 `agent_profile.py` 的硬编码字典，只靠"写一份新的 role package"就让系统认识一个新角色。
  29 +3. 把 applications 这个目前空白的维度定义清楚——至少要回答"一个角色能调用哪些外部工具/集成/MCP server"这件事该怎么表达，不要求第一版就有完整实现。
  30 +4. 现有 Planner/Coder/Validator 三个角色要能**用新格式重新表达**（迁移，不是重写行为），验证这套抽象本身是自洽的，不是只停留在文档设计层面。
  31 +
  32 +## 3. 非目标
  33 +
  34 +1. **不要求第一版就实现"运行时自主创建新角色"**。架构文档 §3"关键设计原则 1"明确 Org Graph 结构是人工定义、代码级固定，改动属于架构变更需要人工评审——这条决策不动。本需求要解决的是"人工新增一个角色时，需要改多少处代码/schema"这个摩擦，而不是让系统自己决定要不要新增角色。新增角色依然是人工发起的动作，只是发起方式从"改代码"变成"写一份声明式的 package"。
  35 +2. **不在本文档里解决 workflows 维度的具体落地**——Coder/Validator 缺少动态 Work Graph 规划能力这件事，已经是条目 E（`docs/todo/dynamic-work-graph-design-skill-requirements.md`）的范围，本文档只要求"Role Package 里要有一个字段/引用指向这个角色的 workflow 规划能力"，不重复设计 E 已经在做的事。
  36 +3. **不在本文档里重新解决 permissions 维度的已知漏洞**（scoped Bash disallowedTools 不生效）——这是 Claude Code 平台本身的行为限制，本文档只要求 Role Package 的 permissions 字段要能诚实反映"这条限制实际上是工具层强制还是仅靠文字约定"，不假装这个漏洞已经修复。
  37 +4. **不要求一次性覆盖全部七个维度到同等成熟度**。applications 维度目前是空白，第一版只需要定义清楚"这个维度存在、字段长什么样、允许为空"，不要求马上有真实的 MCP server 集成可用。
  38 +5. **不做通用的"角色市场/角色商店"之类的产品化能力**。这是纯粹的内部抽象层重构，不涉及把角色包装成可分发、可交易的产品单元。
  39 +
  40 +## 4. 功能需求
  41 +
  42 +| # | 需求描述 | 优先级 |
  43 +|---|---|---|
  44 +| FR-1 | 定义 Role Package 的字段结构，覆盖七个维度：role（身份/人设，对应现有 SOUL.md 正文）、context（memory 配置 + 运行时 context 组装规则的引用）、skills（技能列表，对应现有 `skills:` frontmatter）、applications（可调用的外部工具/集成/MCP server 列表，当前允许为空）、workflows（该角色的 Work Graph 规划能力引用，对接条目 E 的产出）、permissions（tools/disallowedTools，并诚实标注每条限制是工具层强制还是仅文字约定）、acceptance criteria（该角色产出的验收标准引用，比如 Validator 对接 SDD REQ 锚点）。 | 必须 |
  45 +| FR-2 | Role Package 需要是**声明式**的（数据，不是代码）——具体载体形式（单个 YAML/JSON 文件、还是延续现在"一个目录 + 几个子文件"的约定）留待设计阶段决定，但判断标准是"新增一个角色不需要写 Python 代码"。 | 必须 |
  46 +| FR-3 | `src/schema.py` 里 `org_node` 相关的四处 `CHECK (org_node IN ('planner','coder','validator'))` 约束需要改造成不再硬编码这三个值——具体改造方式（改成引用一张新的 `role` 表做外键约束，还是放开成自由文本 + 应用层校验）留待设计阶段决定。 | 必须 |
  47 +| FR-4 | `src/agent_profile.py::ORG_NODES`/`FRONTMATTER` 这两个硬编码常量需要改造成从 Role Package 读取，而不是 Python 字典里硬写三个角色的定义——但 `deploy_agent_definitions()` 对外的部署行为（生成 `.claude/agents/*.md`）保持不变，只是数据来源变了。 | 必须 |
  48 +| FR-5 | 现有 Planner/Coder/Validator 三个角色需要各自被表达成一份 Role Package，作为这套抽象的第一批真实用例，且迁移后系统对外行为（部署出的 `.claude/agents/*.md` 内容、实际执行结果）不应该有可观察的变化——这是一次纯粹的内部表达方式重构，不是功能变更。 | 必须 |
  49 +| FR-6 | applications 维度需要有一个明确的最小定义（哪怕第一版只是"MCP server 列表，允许为空"），不能继续保持"架构文档提过但从未真正定义"的状态。 | 应该 |
  50 +
  51 +## 5. 验收标准
  52 +
  53 +1. **核心验收（对应目标 2 的可验证标准）**：能够只通过"新增一份 Role Package"（不改 `schema.py`、不改 `agent_profile.py` 的硬编码逻辑）让系统认识一个新角色，并成功为它部署出一份 `.claude/agents/<新角色>.md`。这个新角色不需要真的接入 Org Graph 执行（Org Graph 本身仍是人工评审后才能改的架构决策，见非目标第 1 条），只需要验证"定义一个角色"这件事本身不再需要写 Python 代码或改 schema 约束。
  54 +2. 迁移后，现有 Planner/Coder/Validator 三个角色部署出的 `.claude/agents/*.md` 内容（frontmatter 字段、正文）跟迁移前逐字节一致（或差异只是格式规范化，不影响语义），既有测试套件（`src/test_agent_profile.py` 一类）全部通过，不需要修改断言。
  55 +3. 给定一份 Role Package，能够看清楚它在七个维度上分别声明了什么——不需要再像现状一样，为了理解"这个角色能干什么"而去翻四个不同的地方。
  56 +4. permissions 维度里，Validator 的 git-mutation 限制在新格式里被诚实标注为"仅文字约定，非工具层强制"（不是假装它已经被强制执行）。
  57 +
  58 +## 6. 约束与假设
  59 +
  60 +- 这次重构不改变 Org Graph 本身"人工设计、变更需人工评审"的既定原则（架构文档 §3 决策 1），只改变"定义一个角色的具体成本"。
  61 +- Role Package 的 workflows 字段依赖条目 E 的产出（跨 Org Agent 通用的动态 Work Graph 设计能力）——如果 E 还没落地，Role Package 的 workflows 字段可以先指向"占位/尚未实现"，不阻塞本需求其余六个维度的推进。
  62 +- 复用现有的 Skill 目录约定（`skills/<name>/SKILL.md`）和 memory 约定（`memory: project` → `.claude/agent-memory/{role}/`），不重新发明这两块已经工作良好的机制，只是让 Role Package 引用它们，而不是重新定义。
  63 +
  64 +## 7. 风险
  65 +
  66 +- **改动面比 B/D/E/F/G 任何一条都大**：`org_node` 的 CHECK 约束出现在 4 张表上，`ORG_NODES`/`FRONTMATTER` 被 `deploy_agent_definitions`、`org_node_trigger`、`work_graph_orchestrate` 等多处代码直接依赖，改造前需要在设计阶段完整梳理所有依赖点，不能只看 schema 定义本身。
  67 +- **applications 维度定义不清可能导致设计阶段卡壳**——这是七个维度里唯一"从零开始"的，没有现成机制可以对齐（不像 skills/permissions/acceptance criteria 那样已经有半成品可以收编），需要额外的探索性设计工作，不能假设跟其他六个维度一样容易定义。
  68 +- **"声明式、不用写代码就能新增角色"这个目标可能跟 Claude Code 本身的能力边界冲突**——`.claude/agents/*.md` 的部署机制、`skills:`/`tools:` frontmatter 本身已经是 Claude Code 原生支持的声明式格式，Role Package 更多是在这之上再包一层统一抽象，需要在设计阶段验证这层抽象不会变成"重新发明 Claude Code 已经提供的能力"的冗余包装。
  69 +
  70 +## 8. 开放问题（留给详细设计阶段回答）
  71 +
  72 +- [ ] Role Package 的具体载体格式（单文件 vs 目录约定）。
  73 +- [ ] `org_node` CHECK 约束的改造方式——新增 `role` 表做外键，还是放开成自由文本 + 应用层校验。
  74 +- [ ] applications 维度的最小可行定义——只是 MCP server 列表，还是要覆盖更广的"角色能操作哪些外部系统"。
  75 +- [ ] 迁移 Planner/Coder/Validator 三个现有角色到新格式的具体步骤和验证方式。
  76 +- [ ] 这套抽象跟条目 E（动态 Work Graph 设计能力）的接口——Role Package 的 workflows 字段具体怎么引用 E 的产出。
... ...