27-naming-conventions.md 8.92 KB

Edit Raw Blame History


27-NAMING · Graph Agent 体系命名规范

所属: 27 Graph Agent 架构 的跨文档命名约定。
版本: 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 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 §十一）：


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 §三 阶段 3 指出：27 号文档 work_graphs.goal_task_id 这个单字段不足以定位一个 OKR 节点（需要 companyId + 树 ID + 节点 ID 三元组）。改名后该字段应为：
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