# 32. 招聘装配的时间窗 —— 修法评估(评估完成,未实施) > **日期**: 2026-08-21 > **性质**: 承接 [30-task-delegation-reliability-gaps](./30-task-delegation-reliability-gaps.md) §2.1(那份是"现状调研,不代表已拍板要改")。 > 本文档做的是**具体修法评估**:比较了两条候选路径,有明确推荐,但**代码还没有改一行**。 > **触发**:本体装配静默坑那一轮修完读侧(work 节点缺 soul/identity 等、org node 角色定义截断不可见, > 见 `graph-engine.js`/`prompt-builder.js` 那次提交)之后,回头看写侧(招聘时)同一类问题,发现 > 更严重——读侧顶多是"给的上下文不全",写侧是"这个角色永久卡死,没人知道"。 --- ## 一、问题:招聘装配这段异步调用没有任何可靠性保证 **文件**:`server/routes/company.js:1005-1024`(`POST /:companyId/hire` 路由内联的自执行异步块) ```js fetch(`http://127.0.0.1:${PORT}/api/agent/agent-creator/chat`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: buildAgentDefinitionBrief({...}), conversationId: `create-...` }) }).catch(e => console.error('[Hire] Agent-Creator 请求错误:', e.message)); ``` `hireWithTraining()` 建完空壳目录后,fire-and-forget 发一个 HTTP 请求给 `agent-creator`,让它把 `agent.md`/`soul.md`/技能文件填成角色专属内容。**这一发请求成不成功,调用方完全不关心**: `.catch` 只接网络层错误(连不上、超时),**不检查响应状态码**。 ### 1.1 真正的失败点:`agent-creator` 是单会话,撞车直接丢 `server/routes/agent-chat.js:2496,2510-2525`: ```js const agentChatLocks = new Map(); // agentId → { convId, startedAt } ... const existingLock = agentChatLocks.get(agentId); if (existingLock && Date.now() - existingLock.startedAt < 30 * 60 * 1000) { return res.status(429).json({ error: `Agent ${agentId} 正在执行另一个会话`, activeConvId: existingLock.convId }); } ``` `/api/agent/:agentId/chat` 路由用一个进程内 `Map` 做每 agent 的互斥锁,撞车返回 **429**。而 `company.js` 那发 `fetch` 的 `.catch` 不检查 `res.ok`/`res.status`——**429 被当成"请求成功"直接吞掉**。 按拓扑序连着招 N 个模板库外的新角色时,只有第一个会被 agent-creator 真正处理,其余全部 **永久停在 base 空壳 + `status=training`**,唯一的痕迹是一行 `console.error`(而且这一行在 429 场景下根本不会触发——429 是正常 HTTP 响应,不是网络错误,`.catch` 都摸不到它)。 ### 1.2 `body_not_ready` 网关只挡了"重复招聘",没挡"卡住不动" `company-service.js:430,500-511` 现在会在 `hire()` 时现场校验角色定义是否就绪,挡住别家公司 在定义写完前抢招同一角色(`org-coder-has-no-shared-body` 记忆记录的那次修复,2026-08-21)。 **这道网关解决的是"别人趁乱抢招",不解决"这个角色本身卡住了"**——被卡住的那个招聘请求, 其发起方(第一个招它的公司)拿到的仍然是一个永远填不满的 `training` 空壳,没有任何信号。 --- ## 二、评估过的两条修法 ### 方案 A:把这发请求改走 `POST /api/agent/task/dispatch`(任务队列) `org-coder-has-no-shared-body` 记忆里记过一条"更省事的补救"——人工手动发一次 `task/dispatch`(`autoExecute:true`)确实能让卡住的空壳在约 2 分钟内被填好。看起来像是 "把 fire-and-forget 换成排队",但深入代码后发现**不是**: - `task/dispatch`(`agent-chat.js:1816-1970`)最终还是走 `selfChat()`(`agent-chat.js:44-63`)—— 一个 `http.request` 回本进程的 `/api/agent/:agentId/chat`,**跟 `company.js` 现在用的 `fetch` 是同一条执行路径**,不是另一套调度器。`task-scheduler.js:115` 的注释也确认 dispatch 和 graph 引擎的调度器是两个互不相干的"执行载体"。 - `selfChat()` 同样不检查响应状态码,`/api/agent/:agentId/chat` 撞上 `agentChatLocks` 时同样 返回 429 且同样被静默吞掉——**task/dispatch 在这条失败路径上没有比现在的代码多做任何事**。 - 它真正带来的价值只有一样:往 `tasks` 表写一条持久化行(`status` 字段可查),所以"卡住了" 这件事**变得可观测**,但**不会自动恢复**,也不是它本身有重试。 - 语义不合适:dispatch 会在保留字公司 `_global`(`DISPATCH_COMPANY`,`agent-chat.js:1721`) 下建一条 `goals` 行(`标题: "来自 X 的派单"`)+ `tasks` 行——"填自己的定义文件"这种 系统内部的引导动作会被包装成一条面向用户的可见任务,扫全局任务列表的地方都会看到它, 语义上是错位的(穿着用户任务的外衣做系统内部的事)。 - 没有先例:全仓库找不到任何内部调用方**直接调用**(不经过 HTTP)dispatch 的实现函数, 想用它只能还是绕一圈 HTTP 回自己——没有省掉现在这次 HTTP 往返,只是多了一层。 **结论:方案 A 不成立**——它解决的是可观测性,不是可靠性,而且要素与本次要修的问题不匹配。 ### 方案 B:`company.js` 的 hire 路由直接同进程调 `AgentManager.callAgent`(推荐,但有一个前提要先补上) `company.js` 本来就跑在同一个 Node 进程里,`AgentManager` 也是同进程对象——现在这发 `fetch` 回环到 `127.0.0.1:${PORT}` 纯属多余的一次 HTTP 往返(大概率是历史遗留:早期这段可能是独立 脚本/进程,现在已经不是)。直接 `await agentManager.callAgent('agent-creator', prompt, opts)` 可以: - 拿到真实的调用结果/异常,而不是网络层的 `.catch`; - 在结果显示"忙"的时候做**真正的重试**(有限次数 + 退避),而不是丢掉; - 重试耗尽时写一个**明确、可查询的失败标记**(而不是一行日志),供人工或后续的扫描发现。 **但这里有一个方案 B 必须先解决的坑,是本次评估新发现的(评估最初的方向没提到):** `server/src/core/session-pool.js:160-179` 的 `getOrCreate()`: ```js if (existing?.protocol?.isConnected) { ... return existing; // 直接复用——不检查这个会话是不是「正在处理上一次请求」 } ``` `SessionPool` **没有"当前是否有一次调用正在途中"这个判据**,它只看"连接还在不在"。 `agentChatLocks` 那把互斥锁**只存在于 `agent-chat.js` 这一层路由代码里**,不是 `AgentManager`/`SessionPool` 自身的保证。这意味着:**如果绕开 HTTP、直接并发调用两次 `AgentManager.callAgent('agent-creator', ...)`,`SessionPool` 会把第二次调用复用到同一个 还在处理第一次请求的 CLI 会话上**——两条 prompt 同时往一个 stdio 管道里写,这不是"干净地 排队",是**在一个进程上下文里塞进两轮对话**,行为未定义(很可能是内容串台或协议层报错, 不是本文档能只凭读代码断言的,需要真跑验证),比现在"第二个请求被 429 丢掉"更危险—— 现在的行为好歹是可预测的(丢弃),换成方案 B 如果不额外加锁,可能变成不可预测的 (污染)。 **所以方案 B 的正确形态是「同进程调用 + 自己的互斥锁 + 重试」,不是「同进程调用 + 重试」。** 互斥锁具体怎么做(新建一个专用的 `Map`,还是把 `agentChatLocks` 从 `agent-chat.js` 导出 共用)是实现阶段要定的事,`agentChatLocks` 现在只是模块内变量、没有导出 (`agent-chat.js` 的 `module.exports` 只有 `router`),选哪条看实现时的耦合取舍。 --- ## 三、推荐方案与要点 **方案 B + 显式互斥锁 + 有限重试 + 失败落地为可查询状态**,不做方案 A。 需要的改动(供后续实施时拆解,本文档不实施): 1. **互斥**:招 `agent-creator` 之前先拿一把按 agentId 的锁(复用或新建,见上);拿不到锁不是 立刻失败,是**等一等再试**(不是当场拒绝,因为发起方就是想让它填完,等待是合理语义)。 2. **重试**:有限次数 + 退避(不是无限重试——理由同图引擎的熔断哲学,无限重试等于把"卡住" 换成"一直在跑但看起来没卡住",一样发现不了)。 3. **失败可见**:重试耗尽后,写一个明确的标记——可以是本体目录下的一个哨兵文件,也可以是 `company-service` 已有的某个状态列(具体落点看实现时 `company-service.js` 现有 schema, 本文档不预设)。**核心要求只有一条:不能只是一行 console.error**,得是能被查询/扫描到的 东西,这样以后要做「主动喊人」那一层(30 号文档 §三点名的共性缺口)时,这里已经是 现成的数据源,不用回头补。 4. **不做**:不做「保证自动跑到底」——这跟 30 号文档 §三的结论一致,全系统没有一处做这个 保证,这里也不该单独破例发明一套。目标只是把"静默卡死"变成"卡死了但看得见"。 --- ## 四、风险 / 未决问题 1. **`SessionPool` 并发复用同一会话的真实后果没有实测验证**——本文档的论证是读代码推出来的 (`getOrCreate` 不检查在途状态),没有起真实两个并发请求去验证具体报错形态还是内容串台。 实施前应该先补一个能复现这个场景的测试(两个并发 `callAgent` 调用同一个 agentId), 把「后果具体是什么」钉死,而不是只停留在「读代码觉得危险」。 2. **互斥锁选型未定**:导出 `agentChatLocks` 共用,还是新建一把只给招聘装配用的锁——前者 避免了「系统里有两把语义相同但互相不知道对方存在的锁」,后者改动面更小。留给实施时定。 3. **失败标记落在哪个字段/文件**:本文档故意不预设,需要先看 `company-service.js` 现有 `status`(`training`/`draft`/`active` 等)取值域,判断是新增一个值还是叠加一个独立字段。 4. **这只是三处同构缺口(30 号文档 §三)里的一处**:DevLoop 的 `retry_budget` 耗尽和 Graph 执行的 `blocked` 收敛,是不是也该补同一层"失败可查询/主动喊人",本文档不展开——三处 要不要统一设计成一层公共机制,还是各自打各自的补丁,是比这份文档更大的一个决策, 留给以后。 --- ## 参考 - [30-task-delegation-reliability-gaps](./30-task-delegation-reliability-gaps.md) §2.1 —— 本文档承接的现状调研 - [28-followups](./28-followups.md) —— `body_not_ready` 网关落地背景