统一 Role Package 抽象层——需求文档

日期: 2026-08-06 性质: 需求文档（BRD/PRD 层面），不含详细技术设计。回应用户对 Agentic Enterprise 产品"可复用打包单元"目标的对照检查——"role + context + skills + applications + workflows + permissions + acceptance criteria；all essentially are context for intelligent computing"。 状态: 草案，待评审。

1. 背景

用户提出的目标判断是：Agentic Enterprise 产品的可复用打包单元，本质上应该是 role / context / skills / applications / workflows / permissions / acceptance criteria 这七个维度，而且这七个维度本质上是同一种东西——喂给智能计算的 context，应该被统一表达成一个可序列化、可实例化、可复制的对象。

对照 graphlemon 现状（逐维度核对代码得出）：

维度	现状	成熟度
role	.claude/agents/{planner,coder,validator}.md + agents/*/SOUL.md，src/agent_profile.py::FRONTMATTER 是权威定义	有清晰打包格式，但不可重复实例化——见第 2 节
context	memory: project → .claude/agent-memory/{role}/，git 版本化；但 Work Node 执行时塞进 prompt 的内容是每个调用点临时拼的（build_prompt(node, outputs)），没有独立的"context 组装层"抽象	局部实现，无统一抽象
skills	skills/<name>/SKILL.md，按名字挂进角色的 skills: frontmatter	七项里最成熟、最像"可复用打包单元"的一个
applications	没有对应的一等概念。架构文档 §7.2 提到 mcpServers 字段可以挂专属 MCP server，但 agent_profile.py::FRONTMATTER 里三个角色一个都没配	基本空白
workflows	Claude Code 原生 Dynamic Workflows 机制在，但只有 Planner 真正用——work_graph_plan.py::plan_work_graph() 的提示词硬编码永远只生成 brd/prd/sdd/benchmark 四个节点，Coder/Validator 走的是更简化的单次 trigger_org_node() 调用，没有"先规划图再执行"这条路径（见 docs/done/dynamic-work-graph-design-skill-requirements.md，即条目 E，已确认待做）	机制存在，不是每个角色都能复用的打包能力
permissions	tools/disallowedTools per role（如 Validator disallowedTools: [Edit, Write]）	有格式，但有记录在案的真实漏洞：agent_profile.py 注释明确写了"scoped Bash patterns（如 Bash(git commit:*)）会把 Bash 整个禁掉"，Validator 的 git-mutation 限制实际上退化成了 SOUL.md 里的文字约定，不是工具层强制
acceptance criteria	Benchmark、PASS/FAIL/INCONCLUSIVE、SDD REQ-01~15、root_cause_trace 根因归属	七项里最成熟的一环

核心判断：这不是功能缺口，是抽象层缺口。七个维度里六个都有对应实现（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，不是"包一个新角色进来"。

2. 目标

1. 定义一个统一的、可序列化的"Role Package"抽象——把 role/context/skills/applications/workflows/permissions/acceptance criteria 这七个维度表达成同一种对象的不同字段/引用，而不是分散在 frontmatter、独立目录、运行时生成脚本、SDD 文档四个不相关的地方。
2. 让"角色"从硬编码的 3 个枚举值变成数据驱动的、可新增的对象——具体的可验证标准：能不能不改 schema.py 的 CHECK 约束、不改 agent_profile.py 的硬编码字典，只靠"写一份新的 role package"就让系统认识一个新角色。
3. 把 applications 这个目前空白的维度定义清楚——至少要回答"一个角色能调用哪些外部工具/集成/MCP server"这件事该怎么表达，不要求第一版就有完整实现。
4. 现有 Planner/Coder/Validator 三个角色要能用新格式重新表达（迁移，不是重写行为），验证这套抽象本身是自洽的，不是只停留在文档设计层面。

3. 非目标

1. 不要求第一版就实现"运行时自主创建新角色"。架构文档 §3"关键设计原则 1"明确 Org Graph 结构是人工定义、代码级固定，改动属于架构变更需要人工评审——这条决策不动。本需求要解决的是"人工新增一个角色时，需要改多少处代码/schema"这个摩擦，而不是让系统自己决定要不要新增角色。新增角色依然是人工发起的动作，只是发起方式从"改代码"变成"写一份声明式的 package"。
2. 不在本文档里解决 workflows 维度的具体落地——Coder/Validator 缺少动态 Work Graph 规划能力这件事，已经是条目 E（docs/done/dynamic-work-graph-design-skill-requirements.md）的范围，本文档只要求"Role Package 里要有一个字段/引用指向这个角色的 workflow 规划能力"，不重复设计 E 已经在做的事。
3. 不在本文档里重新解决 permissions 维度的已知漏洞（scoped Bash disallowedTools 不生效）——这是 Claude Code 平台本身的行为限制，本文档只要求 Role Package 的 permissions 字段要能诚实反映"这条限制实际上是工具层强制还是仅靠文字约定"，不假装这个漏洞已经修复。
4. 不要求一次性覆盖全部七个维度到同等成熟度。applications 维度目前是空白，第一版只需要定义清楚"这个维度存在、字段长什么样、允许为空"，不要求马上有真实的 MCP server 集成可用。
5. 不做通用的"角色市场/角色商店"之类的产品化能力。这是纯粹的内部抽象层重构，不涉及把角色包装成可分发、可交易的产品单元。

4. 功能需求

#	需求描述	优先级
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 锚点）。	必须
FR-2	Role Package 需要是声明式的（数据，不是代码）——具体载体形式（单个 YAML/JSON 文件、还是延续现在"一个目录 + 几个子文件"的约定）留待设计阶段决定，但判断标准是"新增一个角色不需要写 Python 代码"。	必须
FR-3	src/schema.py 里 org_node 相关的四处 CHECK (org_node IN ('planner','coder','validator')) 约束需要改造成不再硬编码这三个值——具体改造方式（改成引用一张新的 role 表做外键约束，还是放开成自由文本 + 应用层校验）留待设计阶段决定。	必须
FR-4	src/agent_profile.py::ORG_NODES/FRONTMATTER 这两个硬编码常量需要改造成从 Role Package 读取，而不是 Python 字典里硬写三个角色的定义——但 deploy_agent_definitions() 对外的部署行为（生成 .claude/agents/*.md）保持不变，只是数据来源变了。	必须
FR-5	现有 Planner/Coder/Validator 三个角色需要各自被表达成一份 Role Package，作为这套抽象的第一批真实用例，且迁移后系统对外行为（部署出的 .claude/agents/*.md 内容、实际执行结果）不应该有可观察的变化——这是一次纯粹的内部表达方式重构，不是功能变更。	必须
FR-6	applications 维度需要有一个明确的最小定义（哪怕第一版只是"MCP server 列表，允许为空"），不能继续保持"架构文档提过但从未真正定义"的状态。	应该

5. 验收标准

1. 核心验收（对应目标 2 的可验证标准）：能够只通过"新增一份 Role Package"（不改 schema.py、不改 agent_profile.py 的硬编码逻辑）让系统认识一个新角色，并成功为它部署出一份 .claude/agents/<新角色>.md。这个新角色不需要真的接入 Org Graph 执行（Org Graph 本身仍是人工评审后才能改的架构决策，见非目标第 1 条），只需要验证"定义一个角色"这件事本身不再需要写 Python 代码或改 schema 约束。
2. 迁移后，现有 Planner/Coder/Validator 三个角色部署出的 .claude/agents/*.md 内容（frontmatter 字段、正文）跟迁移前逐字节一致（或差异只是格式规范化，不影响语义），既有测试套件（src/test_agent_profile.py 一类）全部通过，不需要修改断言。
3. 给定一份 Role Package，能够看清楚它在七个维度上分别声明了什么——不需要再像现状一样，为了理解"这个角色能干什么"而去翻四个不同的地方。
4. permissions 维度里，Validator 的 git-mutation 限制在新格式里被诚实标注为"仅文字约定，非工具层强制"（不是假装它已经被强制执行）。

6. 约束与假设

• 这次重构不改变 Org Graph 本身"人工设计、变更需人工评审"的既定原则（架构文档 §3 决策 1），只改变"定义一个角色的具体成本"。
• Role Package 的 workflows 字段依赖条目 E 的产出（跨 Org Agent 通用的动态 Work Graph 设计能力）——如果 E 还没落地，Role Package 的 workflows 字段可以先指向"占位/尚未实现"，不阻塞本需求其余六个维度的推进。
• 复用现有的 Skill 目录约定（skills/<name>/SKILL.md）和 memory 约定（memory: project → .claude/agent-memory/{role}/），不重新发明这两块已经工作良好的机制，只是让 Role Package 引用它们，而不是重新定义。

7. 风险

• 改动面比 B/D/E/F/G 任何一条都大：org_node 的 CHECK 约束出现在 4 张表上，ORG_NODES/FRONTMATTER 被 deploy_agent_definitions、org_node_trigger、work_graph_orchestrate 等多处代码直接依赖，改造前需要在设计阶段完整梳理所有依赖点，不能只看 schema 定义本身。
• applications 维度定义不清可能导致设计阶段卡壳——这是七个维度里唯一"从零开始"的，没有现成机制可以对齐（不像 skills/permissions/acceptance criteria 那样已经有半成品可以收编），需要额外的探索性设计工作，不能假设跟其他六个维度一样容易定义。
• "声明式、不用写代码就能新增角色"这个目标可能跟 Claude Code 本身的能力边界冲突——.claude/agents/*.md 的部署机制、skills:/tools: frontmatter 本身已经是 Claude Code 原生支持的声明式格式，Role Package 更多是在这之上再包一层统一抽象，需要在设计阶段验证这层抽象不会变成"重新发明 Claude Code 已经提供的能力"的冗余包装。

8. 开放问题（留给详细设计阶段回答）

• [ ] Role Package 的具体载体格式（单文件 vs 目录约定）。
• [ ] org_node CHECK 约束的改造方式——新增 role 表做外键，还是放开成自由文本 + 应用层校验。
• [ ] applications 维度的最小可行定义——只是 MCP server 列表，还是要覆盖更广的"角色能操作哪些外部系统"。
• [ ] 迁移 Planner/Coder/Validator 三个现有角色到新格式的具体步骤和验证方式。
• [ ] 这套抽象跟条目 E（动态 Work Graph 设计能力）的接口——Role Package 的 workflows 字段具体怎么引用 E 的产出。