# 统一 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 的产出。