# 27-NAMING · Graph Agent 体系命名规范 > **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的跨文档命名约定。 > **版本**: v0.1 > **日期**: 2026-08-15 > **适用范围**: 27 系列全部文档 + 后续实现中新建的 system agent id、表名、字段名、API 路径。 > **为什么需要这份文档**: 本体系引入的概念(planner / validator / planning / benchmark)在仓库里**全部已经有同名但不同义的既有占用**。不先统一,日后 grep 和排查会持续付出代价。 --- ## 一、总规则 ``` {作用域}-{职能} ``` **任何 agent id、验收产物类型、评测体系名,都必须带作用域前缀**,不允许裸用 `planner` / `validator` / `planning` / `benchmark`。 作用域从大到小: | 作用域 | 含义 | |---|---| | `orggraph` | 公司级 workflow | | `workgraph` | org node 级 workflow | | `{domain}` | 业务领域(`code` / `content` / `ops` …),即 org node 所属领域 | | `task` | 单个任务 | | `agent` | 单个 system agent | | `skill` | 单个 skill | --- ## 二、规划类 agent —— `{产出物}-planning` | id | 职责 | 所在层级 | |---|---|---| | `orggraph-planning` | 根据公司目标/描述,生成**公司级 workflow**(org graph) | company,建公司时跑一次 | | `workgraph-planning` | 根据任务,为某个 org node 生成**该节点的 workflow**(work graph) | org node,每次接到任务时 | | `brd-planning` | 产出 BRD | work graph 内的节点 | | `prd-planning` | 产出 PRD | work graph 内的节点 | | `sdd-planning` | 产出 SDD | work graph 内的节点 | ⚠️ **重命名**:[27-P2](./27-p2-org-graph.md) v0.2/v0.3 里叫 `org-graph-creator` 的 agent,**统一改名为 `orggraph-planning`**。v0.4 起全文使用新名。 --- ## 三、Org node agent —— `{domain}-{职能}` org graph 上的节点 agent,一律带领域前缀: | id | 职责 | |---|---| | `code-planner` | 开发领域:规划阶段的 org node | | `code-coder` | 开发领域:实现阶段的 org node | | `code-validator` | 开发领域:验收阶段的 org node | | `content-planner` / `content-writer` / `content-validator` | 内容领域的同构三段 | **不允许**裸用 `planner` / `coder` / `validator` —— 它们必须能被一眼看出属于哪个领域,否则跨领域公司(既做开发又做内容)会立刻撞名。 --- ## 四、验收产物 —— `task-{类型}` work graph 内动态选入的验收产出节点(见 [27-E2E](./27-e2e-task-execution-flow.md) §十一): | id | 产出 | |---|---| | `task-benchmark` | 打分式验收标准(维度 + 权重 + 及格线) | | `task-test-data` | 输入样本集(正常 / 边界 / 异常) | | `task-test-script` | 可执行断言脚本 | ### 为什么是 `task-` 而不是 `goal-` 原本的理由是"`goal` 被 OKR 体系占用",但 §六 决定把 OKR 体系从 `goal` 改名为 `okr`,**这个撞名理由已经不成立**。改用 `task-` 的理由现在只剩一条,但它本身足够: **验收标准的生命周期跟着一次 task 执行走** —— 由该 task 的 `{domain}-planner` 阶段产出、该 task 的 `{domain}-validator` 阶段消费、task 结束即归档。而 OKR 里的 Key Result 是**跨多个 task、长周期的度量目标**,两者时间尺度不同。用 `task-` 与它的真实作用域一致。 > `goal-` 现在是空闲的,如果更偏好那个词,全局换一下即可,不影响任何其他设计。 --- ## 五、三种 benchmark 必须分开(当前全部叫 `benchmark`) 仓库里 `benchmark` 一词同时指三件完全不同的事。**统一加前缀区分**: | 新名 | 指什么 | 现状 | |---|---|---| | **`skill-benchmark`** | 给 **Skill** 打分 + Arena ELO 排行榜 | ✅ 已实现:`server/services/benchmark-runner.js`、`benchmark-db.js`、`benchmark_runs` 表(主键 `skill_name`)、`comparisons` ELO 表、路由 `/benchmarks` `/benchmark-all` `/benchmark/status` | | **`agent-benchmark`** | 给**单个 system agent** 打能力分,用于 hire / `depositTemplate()` 的 **≥95 门槛** | ⚠️ 部分存在:`system_agents.benchmark_score` 字段(P0 已落地)、`_registry.json` 的 `benchmarkScore`(实测仅 3 条非空:ceo=97 / qa-judge=95 / base=90) | | **`task-benchmark`** | 给**单个任务**定验收标准,由 `task-benchmark` agent 产出、validator 节点执行 | 🔴 本次设计新增,尚未实现 | ### 代码层重命名的影响面(未执行,需单独排期) 文档层的消歧已在 27 系列全部完成。**代码层的重命名是一次真实的数据迁移,不是 find-replace**,因此本轮只给出影响面清单,不动代码: | 对象 | 位置 | 风险 | |---|---|---| | `benchmark_runs` / `comparisons` / `security_scans` 表 | `data/benchmark.sqlite` | 改表名需迁移脚本 + 停机;这三张表服务于线上 Arena 排行榜 | | `benchmarkScore` 字段 | `system/templates/_registry.json`(磁盘数据) | 改字段名需同步改所有读写方 + 迁移已有数据 | | `/benchmarks` `/benchmark-all` `/benchmark/status` | `server/routes/` | 公开 API,改路径破坏外部调用方 | | `benchmark-runner.js` / `benchmark-db.js` | `server/services/` | 文件重命名成本低,但所有 require 点要同步 | **建议**:代码层保持现状(既有的就默认是 `skill-benchmark` 语义),**只对新增代码强制用新前缀**。即 `task-benchmark` 相关的表、字段、路由从第一天就带前缀,不与既有的混在一起。等哪天真要清理历史命名时,再按上表单独排期。 --- ## 六、OKR 体系:从 `goal` 改名为 `okr` 这棵树的正式名称是 **OKR(Objective - Key Result)**,不应该叫 "goal"。当前代码里 `goal` 既是树的名字、又是树里第 1 层节点的名字,是一处自我遮蔽的命名。 ### 现状层级 ``` G-001 → Goal (第1层) G-001.1 → Objective (第2层) G-001.1.1 → Key Result (第3层) G-001.1.1.1 → Sub-Task (第4层+) ``` ### 建议改法 体系整体叫 **OKR**,第 1 层的 "Goal" 也一并正名 —— OKR 的标准词汇里没有 "Goal" 这一层,现在的第 1 层实际承担的是"一个大目标下挂多组 OKR"的容器角色: | 层 | 现名 | 建议 | ID 前缀 | |---|---|---|---| | 1 | Goal | **Objective**(顶层目标) | `O-001` | | 2 | Objective | **Key Result** | `O-001.1` | | 3 | Key Result | **Sub-Task** | `O-001.1.1` | | 4+ | Sub-Task | (合并进 Sub-Task 层级) | `O-001.1.1.1` | > 这样是标准的 Objective → Key Result → Sub-Task 三层。如果确实需要保留四层,则第 1 层建议叫 **Mission**(`M-001`),下挂 Objective / Key Result / Sub-Task —— 但**不要**再叫 Goal。 ### 影响面(代码层,需单独排期,本轮未执行) | 对象 | 位置 | 风险 | |---|---|---| | `server/services/goals.js` → `okr-service.js` | 文件重命名 | 低,改 require 点 | | `server/routes/goals.js` → `okr.js` | 文件重命名 | 低 | | `/api/goals/*`、`/api/company/:cid/goals/*`(共 9 条路径) | 公开 API | **中**:破坏外部调用方,需保留旧路径做别名过渡 | | `data/companies/{cid}/goals/` → `okr/` | **磁盘数据目录** | **高**:需迁移脚本,涉及已有公司数据(如 `idearun`) | | ID 前缀 `G-` → `O-` | 磁盘上已有的 `goal.json` 文件名与内容 | **高**:同上,且 `agent-chat.js` 的 task meta 里存了 `goalId` 反向引用 | | `goalId` / `goalsDir` / `goalContext` 等 8 个字段名 | `goals.js`、`agent-chat.js` | 中:跨文件,且注入 agent prompt 的文本里也有 | | `OkrDashboard.vue` | 前端 | ✅ 已经叫 OKR,改完后前后端才终于一致 | **建议**:与 §五 的 benchmark 改名同一策略 —— **新增代码一律用 `okr-`;存量代码保持现状直到单独排期做迁移**。27 系列文档全部使用新词汇。 ### 对 27 系列的直接影响 [27-E2E](./27-e2e-task-execution-flow.md) §三 阶段 3 指出:27 号文档 `work_graphs.goal_task_id` 这个单字段不足以定位一个 OKR 节点(需要 `companyId` + 树 ID + 节点 ID 三元组)。改名后该字段应为: ```sql okr_node_id TEXT, -- 形如 'O-001.1.1',配合 company_id 定位 task_id TEXT, -- 形如 'T-xxx',system/tasklog/{taskId}.json ``` --- ## 七、速查表 | 不要用 | 要用 | |---|---| | `planner` | `code-planner` / `content-planner` / … | | `validator` | `code-validator` / `content-validator` / … | | `planning` | `orggraph-planning` / `workgraph-planning` / `brd-planning` / `prd-planning` / `sdd-planning` | | `org-graph-creator` | `orggraph-planning` | | `benchmark`(裸用) | `skill-benchmark` / `agent-benchmark` / `task-benchmark` | | `test-data` / `test-script`(裸用) | `task-test-data` / `task-test-script` | | `goal` / `goals`(指 OKR 体系时) | `okr` | | `Goal`(指 OKR 第 1 层节点) | `Objective`(或 `Mission`,若保留四层) | | `goalId` | `okrNodeId` | | `G-001.1.1` | `O-001.1.1` |