# 27-P2. Org Graph 落地 — 需求与设计文档 > **所属**: [27 Graph Agent 架构](./27-graph-agent-architecture.md) 的 Phase P2("Org Graph") > **版本**: v0.2(设计阶段,未实现;相比 v0.1 的核心变化见 §二末尾"为什么从『招聘时可选传 reportsTo』升级为『org-graph-creator 自动生成』") > **日期**: 2026-08-15 > **前置**: P0 地基已完工并提交(commit `8421f55`,`server/services/graph-db.js` + `graph-seed-service.js`)。**P1(虚拟引用寻址)目前仍是设计稿,未实现**——`server/services/graph-service.js` 尚不存在。§九说明 P2 为什么不需要等 P1 落地即可开工。 --- ## 一、目标与非目标 ### 目标(本阶段要交付什么) 按 27 号文档 P2 行的原始定义(27-graph-agent-architecture.md:215): > `company.json.agents[]` 迁移为图结构。`org_graph_nodes`/`edges` 落地;HR/CEO 招聘走新表。验收标准:现有 Company Dashboard 前端能正确读出 org graph 并渲染(哪怕暂时按列表展示)。 结合最新明确的方向——**org graph 不再是招聘过程中零散声明出来的副产品,而是由公司的第一个 agent「org-graph-creator」在公司创建之初,根据公司目标/描述 + 一套按公司类型区分的 org graph 模板 + 当前可招聘的 agent 模板库,一次性规划并执行出来的**——展开为四件具体的事: 1. **补全边(edges)+ 提供写入机制**:P0 只回填了节点(来自 `company.json.agents[]` 的扁平角色名),`org_graph_edges` 表建了但从未写入过一行。P2 要让 `hire()` 支持声明 `reportsTo`,这是所有汇报关系(不管谁写的)最终落地的**唯一通道**。 2. **org-graph-creator agent**:新增一个系统级 agent 模板,作为每家新公司创建后自动"入职"的第一个 agent。它读公司目标/描述、读 `system/org-graph-templates/*.json` 里的候选组织结构模板、读当前 `system/templates/*` 实际能招到的角色,综合判断出一套具体的组织结构,再按拓扑序(先上级后下级)依次调用 `hire()` 把这套结构真正建出来。 3. **组织结构模板库**:新增 `system/org-graph-templates/`,用一组按"公司类型"归类的 JSON 骨架文件(开发型/内容型/运营型……)表达"这类公司通常长什么样",供 org-graph-creator 参考、裁剪、组合——不是每家公司都严格照抄某一个模板,模板只是起点。 4. **提供一个可读的视图**:新增只读 REST 端点把 `(nodes, edges)` 拼成组织架构数据,Company Dashboard 至少能按"谁向谁汇报"分层列表展示。 ### 非目标(本阶段明确不做) - **不做**图形化组织架构图(连线画布、拖拽调整层级)——验收标准原文写明"哪怕暂时按列表展示"即可。 - **不做** `company.json.agents[]` 的废弃或只读化——很多现有代码(`listAgents()`、心跳、Dashboard 概览卡)仍在直接读它,P2 阶段 `org_graph_nodes`/`edges` 是**追加写入**,不是替换现有读取路径。 - **不做**存量公司历史雇佣关系的"猜测式"补边——见 §四.12。 - **不做**已经跑过一次 org-graph-creator 的公司的"重新规划/推倒重来"——org-graph-creator 在 P2 阶段是**一次性的公司创建时动作**,不是可以随时对着一家已经有员工的公司重跑的东西。公司后续想调整组织结构(加人、换汇报对象),走的是 HR agent 走既有 `hire()`/`reportsTo` 机制做增量调整(§四.4),不是重新触发 org-graph-creator。重新规划一家运行中公司的组织结构涉及"已有节点怎么办、正在跑的任务怎么办",复杂度明显更高,留作 Open Question(§八.5)。 - **不做**给 `company.json` 加一个枚举型的 `type` 字段——公司类型的判断是 org-graph-creator(LLM)基于目标/描述做的一次性推理,不是一个需要长期维护、需要建校验逻辑的结构化字段。org-graph-creator 执行完可以顺手把自己判断出的类型写成一段说明文字存档(§四.9),但那是审计用的自由文本,不是可枚举、可用于 if-else 分支的字段。 - **不做** Work Graph(P3)、Loop-Validator(P4)——P2 只处理静态协作结构。 - **不做** `system/agents/` 与 `system/templates/` 之间 6 个同名 id 的冲突解决——这是 27 号文档 §七遗留给"实现阶段之前"的产品决策,P1 §九 Q4 建议在排 P2 之前解决掉,本文档在 §八重申但不阻塞技术交付。 --- ## 二、背景:为什么"边"是空的,不是"没扫描到" 27 号文档 §四数据模型草稿把 `org_graph_edges` 定义为"公司静态协作结构"的关系边,`relation_type` 取 `reports_to` / `collaborates_with`(27-graph-agent-architecture.md:154-160)。但走查现有代码后发现:**这不是"数据源里有汇报关系、只是没写代码去读",而是系统里从来没有任何地方产生过"谁向谁汇报"这条信息**: - `company.json` 的 schema(`company-service.js:50-69`)里 `agents` 是纯字符串数组,没有汇报关系字段。 - HR Agent 的招聘 SOP(`system/templates/hr/agent.md:18-32`)里,CTO 给 HR 发的"招聘需求单"是一句自然语言,HR 执行的命令是 `node bin/lemon.js company hire --id <公司ID> --role <角色名> --type executor --name "岗位名称"`——**没有 `--reportsTo` / `--manager` 这类参数**,`bin/lemon.js` 的 `parseArgs` 选项列表(`bin/lemon.js:63-67`)里也确实没有。 - `config.json` 里唯一带层级意味的字段是 `parentId`(`packages/agent-core/AgentScaffold.js:63`「上级 Agent ID」),但它**只在 `scaffoldNewAgent()`(培养路径,company-service.js:241-283)里被写入**——走模板复制的 `hire()`(招聘路径,绝大多数场景)压根不 touch `parentId`。 - 各模板 `config.json` 的 `type` 字段本身就不构成一致的层级体系:实际扫描结果是 `cxo` / `specialist` / `executor` / `devloop` / `meta` / `quality_assurance` / `skill` 混杂(见 §三.3),`ceo` 模板目录甚至**没有 `config.json`**,导致 `hire()` 里"`type==='cxo'` 才设置 `company.ceo`"的逻辑(company-service.js:211-213)对字面意义上的 "ceo" 角色从不生效,反而任何被标 `type: 'cxo'` 的角色(`cto`/`coo`/`innovator`)招聘时会覆盖 `company.ceo`——这是一个和 P2 无关、但 org-graph-creator 大概率会踩到的既有 bug,见 §八.6。 **结论一**(v0.1 就已确立,本次不变):没有任何历史数据可以无损映射成 `reports_to` 边,`type` 字段也不能作为可靠的层级推导依据。存量数据只补节点(P0 已完成),不自动猜边。 ### 为什么从"招聘时可选传 reportsTo"升级为"org-graph-creator 自动生成" v0.1 的方案是把 `reportsTo` 做成 `hire()` 的一个可选参数,指望 HR/CEO agent 在招聘时"顺手"传一下。这个方案本身没有错——它仍然是本版本的**底层写入机制**(§四.4 完整保留)——但作为唯一的产生边的路径,有一个结构性弱点:HR 是**被动响应**式地一个一个招人("CTO 说招三个人,HR 就招三个人"),从来不会有一个时刻"通盘看一眼这家公司应该长成什么样"。用户指出的改进方向是补上这个缺失的环节:公司创建时先有一个专职的 agent 站在全局视角,根据这家公司**要做什么**(目标/描述)参考"这类公司通常怎么搭"(模板库),一次性把骨架定下来,之后 HR 的增量招聘只是在这个骨架上加叶子节点。这不是推翻 v0.1,而是在它之上加一层"谁来负责最开始把 reportsTo 填对"的机制。 --- ## 三、现状代码走查(决定设计边界的关键证据) ### 3.1 `org_graph_edges` 表已建但从未被写入 `server/services/graph-db.js:54-60` 定义了表结构(`id` 是 `INTEGER PRIMARY KEY AUTOINCREMENT`,不是 27 号文档草稿里写的 `TEXT PRIMARY KEY`——P0 实现时改了主键类型,P2 沿用实际实现)。`server/services/graph-seed-service.js:202` 的注释明确写着"`org_graph_edges` 本阶段留空——company.json 目前没有汇报关系数据,是预期状态,不是 bug"。 ### 3.2 真正被前端调用的招聘/辞退路径,和 `CompanyService` 里同名方法不是一回事 - **招聘**:`POST /:companyId/hire`(`server/routes/company.js:908`)调用的是 `companyService.hireWithTraining()`(`company-service.js:381-383`,内部转调 `this.hire()`),`opts` 会从 route 的 `req.body` 一路传到 `hire()`。 - **辞退**:`POST /:companyId/fire`(`server/routes/company.js:1009-1055`)**没有调用 `companyService.fire()`**。它在路由 handler 里直接重新实现了一遍逻辑:停心跳 → 按 `archive` 参数决定归档还是删除 → 直接改 `company.agents` 数组。`CompanyService.fire()`(company-service.js:411-433)**唯一的调用方是测试脚本 `server/scripts/test-company-e2e.js:227`,是死代码路径**。 - **公司创建**:`POST /create`(`server/routes/company.js:22-38`),目前只创建一个"没有员工的空壳公司",响应里写着"请通知 MasterBot 从 Template 库中雇佣 Agent"——**创建流程本身不会自动招任何 agent**,这是 P2 要打破的现状(见 §四.10)。 给"辞退"加清理逻辑必须改 `/fire` 路由 handler 本体;给"创建"接上 org-graph-creator 必须改 `/create` 路由 handler 本体——两者是同一类问题:真正生效的代码在路由层,不在 service 层的对应方法里。 ### 3.3 `type` 字段现状扫描 对 `system/templates/*/config.json` 逐个读取 `type` 字段(39 个模板目录,2026-08-15 现场扫描): | type 取值 | 数量 | 代表角色 | |---|---|---| | `specialist` | 22 | hr, digester, hunter, content-selector, ... | | `cxo` | 3 | cto, coo, innovator | | `devloop` | 6 | devloop-pm/architect/coder/tester/integrator/triager | | `executor` | 2 | evolver, scrapling_crawler | | `meta` | 1 | evolver-youtube-crawler | | `quality_assurance` | 1 | qa-judge | | `skill` | 1 | claude-youtube-skills | | 无 `config.json` | 1 | **ceo** | 没有任何字段能区分层级,`type` 只是粗粒度的职能分类。 ### 3.4 `listTemplates()` 已经提供了 org-graph-creator 需要的"可招聘角色清单" `company-service.js:480-` 的 `listTemplates()`(`GET /api/company/templates`,HR 已经在用,`system/templates/hr/agent.md:17` 的 `node bin/lemon.js company templates`)对每个模板目录返回 `{id, name, type, description, benchmarkScore, ...}`。这正是 org-graph-creator 判断"模板里写的这个角色,现实里有没有对应的可招模板"所需要的原始数据——**不需要为 org-graph-creator 新开一个查询接口**,复用现成的 CLI 命令即可(见 §四.9)。 ### 3.5 Company Dashboard 现状:纯扁平列表,无层级渲染 `web/src/views/CompanyDashboard.vue:212-229`("团队成员" tab)用 `companyAgents` 渲染一个 `agents-grid`,卡片之间没有连线也没有分组。P2 加"至少列表展示"是**新增**一块 UI。 --- ## 四、设计方案 ### 4.1 总体架构与触发时机 ``` POST /api/company/create │ ├─ companyService.create():建空壳公司(company.json.agents=[],不变) │ ├─ 【新】companyService.hire(companyId, 'org-graph-creator', {}) │ org-graph-creator 是系统模板,招聘流程与其他角色完全一致(走 §3.2 已有的 hire() 路径) │ 不传 reportsTo —— 它是基础设施角色,不挂在业务汇报树里(见 §4.9 末尾) │ └─ 【新】fire-and-forget 触发首轮对话(复用 /hire 路由里已有的 fetch(`/api/agent/{agentId}/chat`) 异步模式,company.js:917-940) 消息内容:公司 id/name/description(见 §4.10) │ ▼ org-graph-creator(LLM agent,system/templates/org-graph-creator/) 1. 读 system/org-graph-templates/*.json(结构骨架候选集,见 §4.8) 2. 读 `node bin/lemon.js company templates`(现实里能招到的角色,见 §3.4) 3. 综合公司 description + 上面两份数据,判断/裁剪出一套具体组织结构 4. 把这套结构写成一份规划记录(workspace/org-plan.md,见 §4.9) 5. 按拓扑序(先上级、后下级)依次执行: node bin/lemon.js company hire --id <公司ID> --role <角色> --reportsTo <上级角色> 6. 全部招完后关闭自己的心跳,转入休眠(一次性任务,见 §4.9 末尾) ``` `hire()`/`org_graph_nodes`/`org_graph_edges`/`reportsTo` 校验规则(§4.4)是这套流程的**底层机制**,org-graph-creator 只是这套机制目前最重要的调用方——HR agent 后续做增量招聘时,走的是同一条 `hire()` + `reportsTo` 路径,不是另一套。 ### 4.2 数据模型改动(在 P0 schema 上追加,不改已有列) ```sql -- org_graph_nodes:追加"是否仍在职"标记,供 fire() 软删除用 ALTER TABLE org_graph_nodes ADD COLUMN status TEXT NOT NULL DEFAULT 'active'; -- status: 'active' | 'removed' CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_nodes_company_role_active ON org_graph_nodes(company_id, role_name) WHERE status = 'active'; CREATE TABLE IF NOT EXISTS org_graph_edges ( id INTEGER PRIMARY KEY AUTOINCREMENT, company_id TEXT NOT NULL, from_node_id INTEGER NOT NULL REFERENCES org_graph_nodes(id), to_node_id INTEGER NOT NULL REFERENCES org_graph_nodes(id), relation_type TEXT NOT NULL CHECK (relation_type IN ('reports_to','collaborates_with')), status TEXT NOT NULL DEFAULT 'active', created_at TEXT NOT NULL ); CREATE UNIQUE INDEX IF NOT EXISTS idx_org_graph_edges_dedupe_active ON org_graph_edges(company_id, from_node_id, to_node_id, relation_type) WHERE status = 'active'; ``` 放进 `server/services/graph-db.js` 的 `getDb()` 里,用 `CREATE ... IF NOT EXISTS` / 探测后 `ALTER TABLE ... ADD COLUMN`,跟 P0 一贯的"只加不改"风格一致。**为什么软删除**:`org_graph_nodes`/`edges` 是审计轨迹的一部分(类比 DevLoop `timeline.ndjson` 的 append-only 原则),物理删除会让"这家公司 3 个月前的组织架构长什么样"无法回答。 ### 4.3 新模块 `server/services/org-graph-service.js`(不复用/不等待 P1 的 `graph-service.js`) ```js // server/services/org-graph-service.js // 职责:org_graph_nodes/edges 的读写,供 company-service.js 和 routes/company.js 调用。 // 与假想中 P1 的 graph-service.js(管 agent.md 从哪读)职责不同、文件不同,都基于 graph-db.js 的 // getDb(),若 P1 之后落地,两个文件共存,org_graph_nodes 表 schema(含本文档新加的 status 列) // 双方共享,实现前需互相 diff 一次 graph-db.js。 function upsertNode(companyId, roleName, systemAgentId = roleName) { /* INSERT ... ON CONFLICT ... */ } function removeNode(companyId, roleName) { /* UPDATE status='removed',级联失效相关边 */ } function addEdge(companyId, fromRoleName, toRoleName, relationType) { /* 见 4.4 校验规则 */ } function getOrgGraph(companyId) { /* JOIN nodes + edges + system_agents */ } module.exports = { upsertNode, removeNode, addEdge, getOrgGraph }; ``` ### 4.4 `hire()` / `hireWithTraining()` 改动 —— 新增可选 `reportsTo`(org-graph-creator 与 HR 共用的机制) `company-service.js:189` 的 `hire(companyId, roleName, opts = {})`:`opts` 新增可选字段 `reportsTo`(角色名字符串,指向同一家公司里另一个已存在的角色)。模板命中分支末尾追加: ```js try { orgGraphService.upsertNode(companyId, roleName); if (opts.reportsTo) { orgGraphService.addEdge(companyId, roleName, opts.reportsTo, 'reports_to'); } } catch (e) { console.warn(`[Company] org_graph 写入失败(不影响招聘结果): ${e.message}`); } ``` try/catch-not-fail:`org_graph_nodes`/`edges` 在 P2 阶段仍然是 `company.json.agents[]` 的旁路记录,写失败不能让招聘这个更重要的操作跟着失败——**这一点对 org-graph-creator 尤其重要**:它会在几十秒内连续调用 `hire()` 十几次,任何一次的 org-graph 旁路写入失败都不该让整个批量招聘链路中断。 **`reportsTo` 校验规则**: 1. `reportsTo` 指向的角色必须已经是该公司 `org_graph_nodes` 里一条 `status='active'` 的节点——否则报错拒绝这次 `hire()`。**这一条对 org-graph-creator 是硬约束**:它必须按拓扑序(先招上级、后招下级)执行,见 §4.11。 2. `reportsTo === roleName` 直接拒绝。 3. 不做环检测——留到 P4 Loop-Validator 上线、或后续 Work Graph 需要拓扑排序时再补,刻意简化。 `hireWithTraining()`(company-service.js:381-383)本身只是 `hire()` 的一层包装,`opts` 透传。**Route 层需要同步改**:`server/routes/company.js:908-914` 的 `/hire` handler 目前从 `req.body` 解构时没有 `reportsTo` 字段,需要加上。 ### 4.5 `/fire` 路由改动(不是 `CompanyService.fire()`——见 §3.2) `server/routes/company.js:1009-1055`,"从公司 agents 列表中移除"之后追加: ```js try { orgGraphService.removeNode(companyId, role); } catch (e) { console.warn(`[Fire] org_graph 清理失败(不影响辞退结果): ${e.message}`); } ``` `removeNode()` 把该节点 `status` 置为 `removed`,同时把所有以它为 `from_node_id`/`to_node_id` 的 active 边一并置为 `removed`。`CompanyService.fire()` 同步做一样的改动(仅为不让测试脚本继续验证一个跟线上不一致的假实现)。 ### 4.6 只读 REST 端点:`GET /api/company/:companyId/org-graph` ```js router.get('/:companyId/org-graph', (req, res) => { res.json(orgGraphService.getOrgGraph(req.params.companyId)); }); ``` 返回形状: ```json { "nodes": [ { "id": 12, "roleName": "cto", "systemAgentId": "cto", "status": "active" }, { "id": 15, "roleName": "hr", "systemAgentId": "hr", "status": "active" } ], "edges": [ { "fromRoleName": "hr", "toRoleName": "cto", "relationType": "reports_to" } ] } ``` 不在这一层拼装 `name`/`type`/心跳状态——那些字段权威来源始终是 `companyService.listAgents()`,前端按 `roleName` 去 join 已经在加载的 `companyAgents` 列表。 ### 4.7 前端:Company Dashboard 新增"组织架构"渲染 不新增 tab。在"团队成员" tab 的 `agents-grid` 上方插入按 `reports_to` 边分层的缩进列表;没有边数据的节点退化成当前的平铺 grid(保证存量公司 Dashboard 展示效果不变);不引入图形库依赖。 ### 4.8 `system/org-graph-templates/`:组织结构模板库 新增目录,每个文件是一种"公司类型"的组织结构骨架,供 org-graph-creator 参考: ```json // system/org-graph-templates/dev.json { "id": "dev", "label": "开发型公司(持续构建/维护软件产品)", "whenToUse": "公司目标包含实现某个产品/功能、需要跑代码开发-测试循环时优先参考", "roles": [ { "role": "ceo", "reportsTo": null, "note": "公司负责人,制定目标" }, { "role": "cto", "reportsTo": "ceo", "note": "技术负责人" }, { "role": "hr", "reportsTo": "ceo", "note": "负责后续增量招聘" }, { "role": "devloop-pm", "reportsTo": "cto" }, { "role": "devloop-architect", "reportsTo": "devloop-pm" }, { "role": "devloop-coder", "reportsTo": "devloop-architect" }, { "role": "devloop-tester", "reportsTo": "devloop-coder" } ] } ``` ```json // system/org-graph-templates/content.json { "id": "content", "label": "内容型公司(持续产出/发布内容)", "whenToUse": "公司目标是短视频/文章/直播等内容的选题-生产-发布流水线", "roles": [ { "role": "ceo", "reportsTo": null }, { "role": "coo", "reportsTo": "ceo", "note": "内容运营负责人" }, { "role": "hr", "reportsTo": "ceo" }, { "role": "trend-scout-cn", "reportsTo": "coo" }, { "role": "story-architect", "reportsTo": "coo" }, { "role": "hook-editor", "reportsTo": "story-architect" }, { "role": "auto-publisher", "reportsTo": "coo" } ] } ``` ```json // system/org-graph-templates/ops.json { "id": "ops", "label": "运营型公司(监控/增长/客户运营为主)", "whenToUse": "公司目标偏向数据监控、增长实验、社群/客户运营,不以持续研发或内容生产为主", "roles": [ { "role": "ceo", "reportsTo": null }, { "role": "coo", "reportsTo": "ceo" }, { "role": "hr", "reportsTo": "ceo" }, { "role": "community-manager", "reportsTo": "coo" }, { "role": "strategy-reflector", "reportsTo": "coo" } ] } ``` 设计要点: - **这是起点集合,不是穷举枚举**——目录里有几个 `.json` 就有几种候选,新增一种公司类型只需要加一个新文件,不需要改任何代码(对应用户选定的"固定模板文件 + LLM 选型"方案:org-graph-creator 在 prompt 里被告知"`ls system/org-graph-templates/` 看看有哪些候选,都读一遍,选最贴近或组合出一个新的",不是在代码里写死一个 `switch(type)`)。 - `roles[].role` 里写的角色名是**建议**,不是强制——org-graph-creator 必须对照 §3.4 的 `company templates` 结果核实这个角色是否真的存在可用模板;如果没有,`hire()` 会走既有的 `needs_training` 分支(自动触发 agent-creator + innovator 培养,company.js:917-940 已有),org-graph-creator 不需要对此做特殊处理,只需要接受 `hire()` 的返回结果继续往下走。 - 模板之间允许被"揉合":比如一家公司同时要做内容生产和一个配套小工具的开发,org-graph-creator 的 prompt 里应该允许它同时参考 `content.json` 和 `dev.json`、合并出一套结构,而不是只能二选一。这是把"选型"这个判断交给 LLM 的直接后果——好处是不需要穷举组合,代价见 §八.1。 - P2 阶段先提供以上 3 个模板作为示例/起点(dev/content/ops),覆盖当前 `system/templates/*` 里能看到的三类角色画像(devloop-* 系列、trend-scout/story-architect/hook-editor 系列、community-manager/strategy-reflector),不追求一次性穷尽所有可能的公司类型。 ### 4.9 `system/templates/org-graph-creator/`:org-graph-creator agent 本体 新增一个系统模板(和 `hr`/`ceo` 同级),字段沿用现有模板骨架(`agent.md`/`soul.md`/`identity.md`/`tools.md`/`config.json`,`config.json.type` 取一个新值 `meta-bootstrap`,与其余"业务角色"的 `type` 区分开)。`agent.md` 的核心工作流大纲(不是完整文案,实现时按仓库现有模板的写作风格——参照 `system/templates/hr/agent.md` 的"招·留·管·退"体例——展开): 1. **读取输入**:公司 `id`/`name`/`description`(由 §4.10 的首轮消息带入)。 2. **读候选骨架**:`ls system/org-graph-templates/`,逐个读取,理解每个模板的 `whenToUse`。 3. **读可招角色清单**:`node bin/lemon.js company templates`,拿到当前系统里真实存在的模板列表(id/name/type/description)。 4. **规划**:综合 1/2/3,判断这家公司最贴近哪个(或哪几个)模板,裁剪/替换/新增角色,产出一份具体的"角色 + reportsTo"清单。**必须包含一个不挂靠任何模板、始终存在的 `hr` 节点**(如果模板里没有就补上)——它是这套结构未来能否被增量维护的前提,org-graph-creator 自己不会长期存在(见第 6 步)。 5. **落盘规划记录**:把第 4 步的结果写成 `workspace/org-plan.md`(角色列表 + 汇报关系 + 为什么这么选的简短理由),供事后审计/调试——这不是给代码读的结构化数据(结构化数据是 DB 里的 `org_graph_nodes`/`edges`),是给人看的"这次规划是怎么想的"。 6. **按拓扑序执行招聘**:从没有 `reportsTo` 的根节点开始,逐层往下,每个角色调用 `node bin/lemon.js company hire --id <公司ID> --role <角色> --reportsTo <上级角色(根节点省略)>`。见 §4.11 关于失败重试的约定。 7. **收尾**:全部招聘执行完(或明确判断某些角色因为需要培养而转入异步流程后),把自己的 `heartbeat.enabled` 设为 `false`(复用现有心跳开关机制,`server/routes/company.js:774` 一带的 `/heartbeat` 端点),不主动退出/不被 fire——它是这家公司组织架构决策的历史记录持有者,保留在 `company.agents[]`/`org_graph_nodes` 里,但不再被心跳唤醒、不参与后续任何招聘(后续增量招聘是 HR 的职责)。 **org-graph-creator 自己在组织图里的位置**:不产生 `reportsTo` 出边(不属于它规划出来的业务汇报树),`getOrgGraph()` 会把它渲染成一个独立的"根"(和 CEO 一样是无入边——不,无出边——的顶层节点,§4.7 的前端渲染本来就允许多个顶层节点并存)。它是基础设施角色,类比 `agent-creator`/`innovator` 这些不出现在业务组织架构里、但确实活跃在系统里的 meta 角色。 ### 4.10 公司创建流程改动 `server/routes/company.js:22-38` 的 `POST /create`:`companyService.create()` 成功后,追加: ```js // 1. 同步招聘 org-graph-creator(跟其他角色一样走模板复制,很快) const bootstrapResult = companyService.hire(id, 'org-graph-creator', {}); // 2. fire-and-forget 触发它的第一轮对话——复用 /hire 路由里已有的 // fetch(`/api/agent/{agentId}/chat`, ...) 异步模式(company.js:917-940) if (bootstrapResult.status === 'hired_from_template') { fetch(`http://127.0.0.1:${PORT}/api/agent/org-graph-creator/chat`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: `公司 ${id}(${name})已创建。公司描述:${description || '(未填写)'}\n请你按照 org-graph-creator 的工作流规划并执行这家公司的初始组织结构。`, conversationId: `org-graph-bootstrap-${id}-${Date.now().toString(36)}`, }), }).catch(e => console.error('[Create] org-graph-creator 触发失败:', e.message)); } ``` 响应文案同步调整:不再是"请通知 MasterBot 从 Template 库中雇佣 Agent",改成"公司已创建,正在由 org-graph-creator 自动规划组织结构(异步进行中)"。 **为什么是路由层而不是 `companyService.create()` 内部**:跟 §3.2/§4.5 同一个理由——`fetch` 调用自己的 HTTP 服务、依赖 `PORT` 等运行时上下文的代码,现有代码库的既有约定是放在路由层(`/hire` 的训练触发逻辑就是这么做的),`CompanyService` 保持不依赖 HTTP 层。 **失败降级**:如果 `hire(id, 'org-graph-creator', {})` 本身失败(比如模板目录被误删),`create()` 的返回结果仍然是成功的空壳公司——这一步失败不应该让公司创建本身失败,跟现有的"招聘失败不影响主流程"原则一致。降级后的行为等同于 P2 上线前的现状:一个没有 org graph、需要人工手动招聘的空壳公司。 ### 4.11 拓扑序执行失败与重试 §4.4 的校验规则 1 要求 `reportsTo` 目标必须已经是 active 节点——这对一个由 LLM 驱动、顺序执行十几次 `hire()` 调用的 agent 来说,存在"记错顺序、先招了子节点"的现实风险。设计上不在 `hire()` 侧放宽这条校验(放宽会让"脏数据"更容易产生,参见 v0.1 §4.4 校验规则 1 的论证),而是让失败可恢复: - `hire()` 对这种情况返回的错误信息要明确指出"角色 `` 尚不存在于该公司,请先招聘它"(不是一个笼统的 500)——org-graph-creator 的 prompt 里要求它读到这类错误后,转去招那个缺失的上级角色,成功后再重试当前角色。 - 每个角色的 `hire()` 调用天然幂等(`already_exists` 短路,company-service.js:194-196),所以"招错顺序 → 报错 → 补招上级 → 重试子节点"这个循环不会因为重复调用产生副作用。 - 不引入一个专门的"依赖排序引擎"帮 org-graph-creator 提前算好正确顺序——§4.9 第 4 步产出的规划记录本身就是一份树状结构,从根遍历下去自然就是拓扑序,只要 org-graph-creator 老老实实按自己写的 `org-plan.md` 从上往下执行,这个问题不常发生;真发生时靠上面的重试机制兜底,不值得为小概率场景builds额外基础设施。 ### 4.12 存量数据 & 已建公司:明确不做的两件事 沿用 v0.1 的结论并扩展一条: | 场景 | 决定 | 理由 | |---|---|---| | P2 上线前已存在的公司(P0 只回填了节点,没有边) | 不补边,`org_graph_edges` 就是空的,前端退化展示 | 没有可靠数据源支撑(见 §二),按 `type`/`parentId` 反推都已被证伪,见 v0.1 版本 §四.7 的完整方案对比表 | | P2 上线后,一家已经跑过 org-graph-creator(或已经手动搭好组织架构)的公司,业务发生变化想要"重新规划" | 不支持——org-graph-creator 只在 §4.10 的创建时触发点运行一次 | 对一家已有员工、可能正在跑任务的公司做"推倒重来"式重新规划,涉及已有节点保留/替换、进行中任务归属等问题,复杂度显著高于"对着空壳公司规划一次",留 Open Question(§八.5),不在 P2 范围内 | --- ## 五、任务划分(Task Breakdown) | # | 任务 | 涉及文件 | 依赖 | 验收方式 | |---|------|----------|------|----------| | **T1** | schema 追加:`org_graph_nodes.status` 列、两个唯一索引、`org_graph_edges.status`/`created_at` | `server/services/graph-db.js` | 无 | 单测:`PRAGMA table_info` 能看到新列;重复插入同 `(company,role)` 的 active 节点报唯一索引冲突 | | **T2** | 新建 `org-graph-service.js`:`upsertNode`/`removeNode`/`addEdge`/`getOrgGraph`,含 `reportsTo` 校验规则(§4.4) | `server/services/org-graph-service.js`(新增) | T1 | 单测覆盖幂等写入、非法 `reportsTo`(不存在/自环)报错且报错信息包含缺失的角色名(供 §4.11 重试逻辑解析)、`removeNode` 级联失效边 | | **T3** | `hire()` 接入:写 node + 可选 edge,try/catch 不阻断主流程 | `server/services/company-service.js` | T2 | 单测:`hire()` 传 `reportsTo` 后 DB 各新增一行;`org-graph-service` 内部抛错时 `hire()` 仍返回 `hired_from_template` | | **T4** | `/hire` 路由透传 `reportsTo`;`/fire` 路由接入 `removeNode()`;`CompanyService.fire()` 同步改 | `server/routes/company.js`、`server/services/company-service.js` | T2 | 集成测试:`POST /hire` body 带 `reportsTo` → 查 DB 有边;`POST /fire` 后节点与相关边均 `removed` | | **T5** | 新增只读端点 `GET /:companyId/org-graph` | `server/routes/company.js` | T2 | 路由测试:返回形状符合 §4.6 契约;不存在的公司返回空数组而非 500 | | **T6** | CLI:`bin/lemon.js company hire` 新增 `--reportsTo` 参数 | `bin/lemon.js` | T4 | 手工跑一次带 `--reportsTo` 的 hire,核对返回值与 DB | | **T7** | 新增 `system/org-graph-templates/`:至少 `dev.json`/`content.json`/`ops.json` 三个骨架 | `system/org-graph-templates/*.json`(新增) | 无(可与 T1-T6 并行) | 人工 review:每个文件的 `roles[].role` 都能在 `system/templates/*` 或 `system/agents/*` 里找到同名目录(避免规划出一个连培养都无从谈起的角色名) | | **T8** | 新增 `system/templates/org-graph-creator/`:agent.md/soul.md/identity.md/tools.md/config.json,落地 §4.9 工作流 | `system/templates/org-graph-creator/*`(新增) | T6, T7 | 人工 review + 手动跑一次完整对话,核对生成的 `org-plan.md` 与实际 `hire()` 调用序列一致 | | **T9** | `/create` 路由接入自动招聘 + fire-and-forget 触发首轮对话 | `server/routes/company.js` | T4, T8 | 集成测试:`POST /create` 后立即查 `company.agents` 含 `org-graph-creator`;等待异步对话完成后查 `org_graph_nodes`/`edges` 有业务角色数据 | | **T10** | HR agent 模板更新:明确"公司初建时的组织结构由 org-graph-creator 负责,HR 只做后续增量招聘"的职责边界 + `reportsTo` 用法 | `system/templates/hr/agent.md` | T6 | 人工 review,确认新增段落不与现有"强制工作流"章节冲突 | | **T11** | 前端:Dashboard 团队成员 tab 加分层列表渲染,退化态验证 | `web/src/views/CompanyDashboard.vue` | T5 | 手动验证:有 `reportsTo` 边的测试公司显示缩进层级;存量公司展示效果与改动前一致 | | **T12** | 回归测试 + 端到端测试:新建 `server/tests/unit/org-graph-service.test.js`;扩展 `server/scripts/test-company-e2e.js` 覆盖"建公司 → org-graph-creator 自动跑完 → 查 org-graph"全链路 | `server/tests/unit/org-graph-service.test.js`(新增)、`server/scripts/test-company-e2e.js` | T3, T4, T9 | `npm run test:unit` 全绿;e2e 脚本能跑通全链路(org-graph-creator 这一步用 mock 模式,参考 DevLoop 的 `ClaudeCliProtocol({mock:true})` 思路,不在自动化测试里真的起 Claude CLI 子进程) | **顺序建议**:T1→T2 是地基。T3/T4/T5 可在 T2 后并行。T7(组织结构模板库)不依赖任何代码改动,可以最早开工、和 T1-T6 并行写。T8(org-graph-creator agent 本体)依赖 T6(CLI 参数)和 T7(有模板可读)。T9(接入创建流程)依赖 T8。T10/T11 分别依赖 T6/T5。T12 贯穿全程,全链路部分要等 T9 完成。 --- ## 六、验收标准 沿用 27 号文档给出的 P2 验收标准(27-graph-agent-architecture.md:215),细化为可直接验证的检查项: 1. **端到端场景(核心)**:`POST /api/company/create` 创建一家 `description` 明确写"我们要做一个短视频内容自动化生产的公司"的测试公司,不做任何手动干预: - 几秒内 `company.agents` 出现 `org-graph-creator` - org-graph-creator 完成一轮对话后,`GET /:companyId/org-graph` 能看到至少 `ceo`/`hr` 加若干与内容生产相关的角色(不强制要求跟 `content.json` 模板逐字一致,因为允许 LLM 裁剪),且存在至少一条 `reports_to` 边 - `workspace/org-plan.md`(org-graph-creator 私有目录下)存在且内容与实际 `hire()` 调用结果一致 2. 对一家新建测试公司依次 `hire(companyId, 'cto', {})` → `hire(companyId, 'hr', {reportsTo: 'cto'})`:`org_graph_nodes` 新增两行,`org_graph_edges` 新增一行 `(hr → cto, reports_to, active)`。 3. `hire(companyId, roleName, {reportsTo: 'nonexistent-role'})`:报错拒绝,不产生半成品数据,且错误信息包含缺失角色名(供 §4.11 重试逻辑验证)。 4. `POST /:companyId/hire` 的 HTTP body 带 `reportsTo` 字段:验证请求确实透传到了 `hireWithTraining()`。 5. `POST /:companyId/fire` 辞退某角色后:该节点与其相关边均 `status='removed'`,`GET /:companyId/org-graph` 不再返回它们。 6. `GET /:companyId/org-graph` 对一家 P0 迁移进来、从未走过新流程的存量公司:返回 `edges: []`,`nodes` 数量与 `company.json.agents.length` 一致。 7. Company Dashboard:有 `reportsTo` 数据的测试公司按层级缩进展示;存量公司展示效果与 P2 上线前一致。 8. `npm run test:unit` 全绿,含新增的 `org-graph-service.test.js`。 --- ## 七、影响面 / Blast Radius | 文件 | 改动类型 | |------|----------| | `server/services/graph-db.js` | 修改:追加 `status` 列 + 两个唯一索引 | | `server/services/org-graph-service.js` | 新增:`upsertNode`/`removeNode`/`addEdge`/`getOrgGraph` | | `server/services/company-service.js` | 修改:`hire()` 接入 org-graph 写入;`fire()` 同步加 `removeNode()` | | `server/routes/company.js` | 修改:`/create` 接入自动招聘 org-graph-creator + 异步触发对话;`/hire` 透传 `reportsTo`;`/fire` 接入 `removeNode()`;新增 `GET /:companyId/org-graph` | | `bin/lemon.js` | 修改:`company hire` 命令新增 `--reportsTo` 选项 | | `system/org-graph-templates/*.json` | 新增:组织结构模板库(至少 dev/content/ops 三份) | | `system/templates/org-graph-creator/*` | 新增:新的系统模板(agent.md/soul.md/identity.md/tools.md/config.json) | | `system/templates/hr/agent.md` | 修改:明确与 org-graph-creator 的职责边界 | | `web/src/views/CompanyDashboard.vue` | 修改:团队成员 tab 加分层渲染逻辑 | **明确不改**:`company.json` 的 schema(`agents` 数组继续是唯一真相源)、`AgentManager`/`PromptBuilder`(P2 不碰运行时寻址)、`CompanyService.listAgents()`。 --- ## 八、风险 / Open Questions 1. **LLM 选型/裁剪质量没有硬性校验**:org-graph-creator 选模板、裁剪角色、判断 `reportsTo` 全靠一次 LLM 推理,没有像 `hire()` 校验规则那样的确定性把关(只保证"图结构合法",不保证"这套结构适合这家公司")。缓解:§4.9 第 5 步的 `org-plan.md` 提供了事后可读的决策记录,公司创建者发现规划不合理时,可以走现有 `fire()`/`hire()` 手动调整——**这也是为什么 §一非目标里明确不支持自动重新规划**:与其让 org-graph-creator 自己判断"要不要推倒重来",不如交给人看着 `org-plan.md` 做增量修正。 2. **一次公司创建多一轮 LLM 对话的成本与延迟**:以前建公司是纯本地文件操作(毫秒级),现在多了一次真实的 Claude CLI 子进程对话(几十秒到几分钟,还有 token 成本)。`POST /create` 保持同步返回(不等 org-graph-creator 跑完,走 fire-and-forget,见 §4.10),前端体验上公司创建本身不受影响,但"什么时候能看到组织结构"变成异步——Dashboard 需要一个"组织结构规划中"的过渡态提示(T11 范围内可以顺手加,不需要单独立项)。 3. **模板揉合没有边界**:§4.8 允许 org-graph-creator 同时参考多个模板文件自由组合,理论上可能拼出一个奇怪的结构(比如把三个模板的角色全招一遍)。P2 阶段不加约束(不限制招聘角色数量上限),如果上线后观察到滥招问题,可以在 org-graph-creator 的 prompt 里加"单次规划角色数不超过 N 个"这类软性约束,不需要代码层面的强制校验。 4. **6 个命名冲突 id 对 org-graph-creator 选型的影响**:P1 §九 Q4 指出的 `agent-creator`/`digester`/`evolver`/`evolver-youtube-crawler`/`hunter`/`innovator` 命名空间冲突问题,现在从"HR 偶尔招到"变成"org-graph-creator 系统性地对照 `company templates` 列表做选型,遇到这批 id 的概率显著提高"。不阻塞 P2 技术交付(`hire()` 本身对这批 id 的处理逻辑不受影响),但建议在 P2 上线前,至少把这 6 个 id 从 `system/org-graph-templates/*.json` 的候选角色名单里排除(在模板文件里就不引用它们),避免规划阶段就把歧义引进来。 5. **已有公司的组织结构再规划**:§4.12 明确列为非目标,但这是一个真实存在的后续需求(公司业务转型、组织结构随规模变化)。留待后续阶段设计——可能的方向是"org-graph-creator 支持增量模式:读现有 org graph + 新目标,只补差集",但这需要先观察 P2 上线后 HR 的增量招聘(§4.4 机制)能不能覆盖大部分场景,不值得在还没有真实使用数据时就设计。 6. **`hire()` 里 `company.ceo` 判定逻辑本身有既有 bug**(§二已指出:`ceo` 模板没有 `config.json`,`type==='cxo'` 判定命中的其实是最后一个被雇的 cxo 类型角色)——org-graph-creator 大概率会招一个字面意义的 `ceo` 角色,这个 bug 会被更频繁地触发(`company.ceo` 显示的可能是 `cto`/`coo` 而不是真正的 `ceo`)。这是 P2 之外的既有缺陷,本文档记录下来供后续排期,不在 P2 任务列表里顺带修(避免这次改动的 diff 范围扩大到不相关的既有逻辑)。 --- ## 九、与 P1 的关系(现状澄清) P1(`27-p1-virtual-reference.md`)**目前仍处于设计阶段,代码未落地**(`server/services/graph-service.js` 不存在,`company-service.js` 里也没有任何 `systemAgentRef`/`companyContextPath` 相关代码)。27 号文档 §六的强顺序声明(27-graph-agent-architecture.md:221)只显式要求 P3 依赖 P1,没有把 P2 排进这条链: - P2 直接基于 P0 的 `graph-db.js`/`org_graph_nodes` 表施工,不需要 P1 的虚拟引用寻址先行。 - P2 新建的 `org-graph-service.js` 与 P1 设计稿里的 `graph-service.js` 是两个独立文件、不同职责。 - 唯一需要协调的是**共享的 `org_graph_nodes` 表 schema**:本文档 §4.2 给这张表加了 `status` 列。如果 P1 之后落地,P1 §4.4 里 `upsertOrgGraphNode()` 的实现需要感知这个新列(默认 `status='active'` 即可)。 - org-graph-creator 本身招聘自己所需要的所有角色时,走的是**当前**(P1 未落地时)的 `hire()` 实现——也就是说 org-graph-creator 招出来的每个角色,`agent.md` 仍然是物理拷贝,不是 P1 设想的虚拟引用。这一点不影响 P2 的正确性,只是意味着 P1 一旦落地,"批量自动招聘"这个新增的调用模式会让"同一个模板被拷贝 N 份"的问题(P1 §二要解决的问题)被更快地放大——这是支持"P1 应该尽早提上日程"的一个新论据,但不是 P2 必须等 P1 的理由。 如果团队希望先补上 P1 再做 P2,也完全可以调换顺序——本文档在设计上不依赖那个决定。