# 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 所属领域 |
| `goal` | **一个人类需求描述**（唯一，验收边界）|
| `task` | 图中的执行单元（一个 goal 分解出多个，可并行）|
| `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` —— 它们必须能被一眼看出属于哪个领域，否则跨领域公司（既做开发又做内容）会立刻撞名。

---

## 四、验收产物 —— `goal-{类型}`

work graph 内动态选入的验收产出节点（见 [27-E2E](./27-e2e-task-execution-flow.md) §十一）：

| id | 产出 |
|---|---|
| `goal-benchmark` | 打分式验收标准（维度 + 权重 + 及格线） |
| `goal-test-data` | 输入样本集（正常 / 边界 / 异常） |
| `goal-test-script` | 可执行断言脚本 |

### 为什么是 `goal-` 而不是 `task-`

**关键区分是基数**：

| 概念 | 基数 | 定义 |
|---|---|---|
| **goal** | 一个人类需求描述 = **1 个** | 验收的边界。回答"这次交付到底算不算满足了人提的要求" |
| **task** | 一个 goal 分解出 **N 个** | 图中的执行单元。可并行、可下钻 sub agent，一个 goal 在图里会有很多个 |
| **okr** | 跨多个 goal 的长周期度量树 | Objective / Key Result，见 §六 |

验收标准回答的是"**人类想要的东西做到了没有**"——这是 goal 级的判定。task 只是达成它的执行分支，一个 goal 下有很多个；把验收挂在 task 上会导致"到底以哪个 task 的验收为准"根本无法回答。

> **决策沿革**（完整过程见 [27-REQ](./27-requirement.md) R-10 / R-12）：最初选 `task-`，理由是"`goal` 被 OKR 占用"；§六 把 OKR 正名后该理由失效，改用"验收跟着一次 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） |
| **`goal-benchmark`** | 给**单个 goal**（一次人类需求描述）定验收标准，由 `goal-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` 语义），**只对新增代码强制用新前缀**。即 `goal-benchmark` 相关的表、字段、路由从第一天就带前缀，不与既有的混在一起。等哪天真要清理历史命名时，再按上表单独排期。

---

## 六、OKR 体系：从 `goal` 改名为 `okr`

> ⚠️ **注意与 §四 的区别**：本节说的是**把 OKR 体系/树/节点从 `goal` 这个词里解放出来**。解放之后 `goal` 被重新赋予 §四 的新含义 ——「一个人类需求描述」。两者不冲突，但读的时候要分清：`okr` 是跨多个 goal 的长周期度量树，`goal` 是一次具体的人类需求。

这棵树的正式名称是 **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` / `goal-benchmark` |
| `test-data` / `test-script`（裸用） | `goal-test-data` / `goal-test-script` |
| `goal` / `goals`（指 OKR 体系时） | `okr` |
| `Goal`（指 OKR 第 1 层节点） | `Objective`（或 `Mission`，若保留四层） |
| `goalId` | `okrNodeId` |
| `G-001.1.1` | `O-001.1.1` |