arch-acp-bridge.html 30 KB
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width,initial-scale=1" />
<title>ACP Bridge · LemonBoss 桥接 · LemonBoss PRD</title>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,300;9..144,500;9..144,700&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet" />
<link rel="stylesheet" href="assets/shell.css" />
</head>
<body data-page="arch-acp-bridge.html">
<div class="shell">
  <aside id="sidebar"></aside>
  <main class="page">
    <header class="page-head">
      <div class="crumb"><span class="pill">05 · ARCHITECTURE</span><span class="sep">/</span><span>ACP Bridge</span></div>
      <h1>ACP Bridge · LoopController ↔ LemonBoss agent-manager</h1>
      <p class="deck">前面文档反复出现 <code>agentManager.callAgent(name, input)</code>。本页交代这一行的<b>实际实现链路</b>:从 LoopController 调用,到 LemonBoss 既有 agent-manager 怎么走,到 SessionPool 复用,到 Claude CLI 子进程启动,到工具调用回路。</p>
    </header>
    <article class="body">

      <section>
        <h2>① 现状梳理 · 既有 LemonBoss 链路</h2>
        <p>LemonBoss 已经有完整的 ACP / Master Agent / SessionPool 链路:</p>
        <svg viewBox="0 0 1100 280" width="100%" role="img">
          <defs><marker id="arrAB" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M0,0 L10,5 L0,10 Z" fill="#0E0E10"/></marker></defs>
          <g font-family="JetBrains Mono" font-size="11" fill="#0E0E10">
            <rect x="20"   y="40" width="200" height="60" rx="6" fill="#EAEAEA" stroke="#666"/>
            <text x="120" y="65" text-anchor="middle" font-weight="700">master-session.js</text>
            <text x="120" y="83" text-anchor="middle" font-size="10">既有 entry</text>

            <rect x="260"  y="40" width="200" height="60" rx="6" fill="#EAEAEA" stroke="#666"/>
            <text x="360" y="65" text-anchor="middle" font-weight="700">agent-manager.js</text>
            <text x="360" y="83" text-anchor="middle" font-size="10">callAgent facade</text>

            <rect x="500"  y="40" width="200" height="60" rx="6" fill="#EAEAEA" stroke="#666"/>
            <text x="600" y="65" text-anchor="middle" font-weight="700">session-pool.js</text>
            <text x="600" y="83" text-anchor="middle" font-size="10">key:(agent,client,deploy,workDir)</text>

            <rect x="740"  y="40" width="200" height="60" rx="6" fill="#EAEAEA" stroke="#666"/>
            <text x="840" y="65" text-anchor="middle" font-weight="700">ClaudeCliProtocol</text>
            <text x="840" y="83" text-anchor="middle" font-size="10">spawn claude</text>

            <rect x="20"  y="160" width="200" height="60" rx="6" fill="#FCE7E2" stroke="#C7341A"/>
            <text x="120" y="185" text-anchor="middle" font-weight="700">LoopController · NEW</text>
            <text x="120" y="203" text-anchor="middle" font-size="10">runProject / runUnit</text>

            <rect x="260"  y="160" width="200" height="60" rx="6" fill="#FCE7E2" stroke="#C7341A"/>
            <text x="360" y="185" text-anchor="middle" font-weight="700">callAgentWithPersistence</text>
            <text x="360" y="203" text-anchor="middle" font-size="10">P-8 包装层</text>

            <g stroke="#0E0E10" fill="none" marker-end="url(#arrAB)">
              <line x1="220" y1="70"  x2="255" y2="70"/>
              <line x1="460" y1="70"  x2="495" y2="70"/>
              <line x1="700" y1="70"  x2="735" y2="70"/>
              <line x1="120" y1="160" x2="120" y2="100"/>
              <line x1="220" y1="190" x2="255" y2="190"/>
              <line x1="360" y1="160" x2="360" y2="100"/>
            </g>
          </g>
        </svg>

        <p><b>关键 insight:</b>DevLoop 的 LoopController <b>不需要新建</b> agent-manager 等价物。它<b>复用</b>既有 agent-manager.callAgent,只在上面套一层「持久化包装」(P-8 的 callAgentWithPersistence)。</p>
      </section>

      <section>
        <h2>② callAgentWithPersistence 的完整实现</h2>
        <p>这是 LoopController 调任何 Agent 的<b>唯一入口</b>。它包住 agent-manager.callAgent 同时管 M-10/M-12/M-13。</p>

<pre class="code shape"><span class="c">// server/src/core/loop-controller.js · 节选</span>
<span class="k">const</span> <span class="p">{</span> agentManager <span class="p">}</span>   = <span class="n">require</span>(<span class="s">'./agent-manager'</span>);
<span class="k">const</span> <span class="p">{</span> unitRegistry <span class="p">}</span>   = <span class="n">require</span>(<span class="s">'../../services/unit-registry'</span>);
<span class="k">const</span> <span class="p">{</span> docStore <span class="p">}</span>       = <span class="n">require</span>(<span class="s">'../../services/doc-store'</span>);
<span class="k">const</span> <span class="p">{</span> bugTracker <span class="p">}</span>     = <span class="n">require</span>(<span class="s">'../../services/bug-tracker'</span>);
<span class="k">const</span> <span class="p">{</span> sseBroker <span class="p">}</span>      = <span class="n">require</span>(<span class="s">'../../services/sse-broker'</span>);
<span class="k">const</span> <span class="p">{</span> timelineLogger <span class="p">}</span> = <span class="n">require</span>(<span class="s">'../../services/timeline-logger'</span>);
<span class="k">const</span> <span class="p">{</span> loadAllTools <span class="p">}</span>   = <span class="n">require</span>(<span class="s">'../tools/tool-registry'</span>);

<span class="k">const</span> toolRegistry = <span class="n">loadAllTools</span>();   <span class="c">// 单例</span>

<span class="k">async function</span> <span class="n">callAgentWithPersistence</span>(name, input) <span class="p">{</span>
  <span class="k">const</span> <span class="p">{</span> pid, unit_id <span class="p">}</span> = input;
  <span class="k">const</span> call_id = <span class="n">genCallId</span>();
  <span class="k">const</span> startedAt = <span class="n">Date.now</span>();

  <span class="c">// 1. 注入运行态 (M-10)</span>
  <span class="k">await</span> <span class="n">writeRuntimeState</span>(pid, name, <span class="p">{</span>
    agent: name, status: <span class="s">'running'</span>, call_id, unit_id,
    current_step: <span class="v">0</span>, total_steps: <span class="v">0</span>,
    started_at: <span class="k">new</span> <span class="n">Date</span>().<span class="n">toISOString</span>(),
  <span class="p">}</span>);

  timelineLogger.<span class="n">append</span>(pid, <span class="p">{</span>
    source: <span class="s">'system'</span>, kind: <span class="s">'agent_started'</span>,
    ref: <span class="s">`agent/</span><span class="v">${name}</span><span class="s">/</span><span class="v">${call_id}</span><span class="s">`</span>,
    summary: <span class="s">`</span><span class="v">${name}</span><span class="s"> started`</span>,
  <span class="p">}</span>);
  sseBroker.<span class="n">emit</span>(pid, <span class="s">'agent.started'</span>, <span class="p">{</span> agent: name, call_id, unit_id <span class="p">}</span>);

  <span class="c">// 2. 注入 memory + 构建 prompt</span>
  <span class="k">const</span> systemPrompt = <span class="k">await</span> <span class="n">buildPromptWithMemory</span>(name, pid);

  <span class="c">// 3. 构建 ctx (传给所有工具的运行时上下文)</span>
  <span class="k">const</span> ctx = <span class="p">{</span>
    pid, agent: name, unit_id, call_id,
    loopController: module.<span class="n">exports</span>,
    docStore, unitRegistry, bugTracker, timelineLogger, sseBroker,
    companyDir: <span class="n">companyDirOf</span>(pid),
    projectDir: <span class="n">projectsDir</span>(pid),
    unitDir: unit_id ? <span class="n">unitDirOf</span>(pid, unit_id) : <span class="v">null</span>,
  <span class="p">}</span>;

  <span class="c">// 4. 调既有 agent-manager (这是关键的"桥"那一行)</span>
  <span class="k">let</span> result;
  <span class="k">try</span> <span class="p">{</span>
    result = <span class="k">await</span> agentManager.<span class="n">callAgent</span>(<span class="p">{</span>
      agentName:    <span class="s">`devloop-</span><span class="v">${name}</span><span class="s">`</span>,    <span class="c">// 与 _registry.json 中 id 对齐</span>
      client:       <span class="n">companyDirOf</span>(pid),  <span class="c">// SessionPool key 之一</span>
      deploy:       pid,                  <span class="c">// 另一个 key</span>
      workDir:      ctx.unitDir || ctx.projectDir,
      systemPrompt,
      input,                              <span class="c">// 透传 PMInput / ArchitectInput / etc</span>
      toolPolicy:   <span class="n">getToolPolicy</span>(name),   <span class="c">// 从 _registry.json 读</span>
      toolRegistry, toolCtx: ctx,         <span class="c">// 关键:工具上下文注入</span>
      timeoutMs:    <span class="n">getTimeout</span>(name),       <span class="c">// PM 10min,Coder 5min, etc</span>
      onChunk: (chunk) =&gt; <span class="p">{</span>             <span class="c">// 流式回调</span>
        sseBroker.<span class="n">emit</span>(pid, <span class="s">'agent.stream'</span>, <span class="p">{</span>
          agent: name, unit_id, chunk
        <span class="p">}</span>);
      <span class="p">}</span>,
    <span class="p">}</span>);

    <span class="c">// 5. 成功收尾</span>
    <span class="k">await</span> <span class="n">writeRuntimeState</span>(pid, name, <span class="p">{</span>
      status: <span class="s">'done'</span>,
      last_output_ref: <span class="k">await</span> <span class="n">snapshot</span>(result, pid, call_id),
      updated_at: <span class="k">new</span> <span class="n">Date</span>().<span class="n">toISOString</span>(),
    <span class="p">}</span>);
    timelineLogger.<span class="n">append</span>(pid, <span class="p">{</span>
      source: name, kind: <span class="s">'agent_done'</span>,
      ref: <span class="s">`agent/</span><span class="v">${name}</span><span class="s">/</span><span class="v">${call_id}</span><span class="s">`</span>,
      summary: <span class="s">`</span><span class="v">${name}</span><span class="s"> done in </span><span class="v">${Date.now() - startedAt}</span><span class="s">ms`</span>,
      payload: <span class="p">{</span> tokens: result.tokens_used <span class="p">}</span>,
    <span class="p">}</span>);
    sseBroker.<span class="n">emit</span>(pid, <span class="s">'agent.done'</span>, <span class="p">{</span> agent: name, call_id, ...result <span class="p">}</span>);
    <span class="k">return</span> result;

  <span class="p">}</span> <span class="k">catch</span> (e) <span class="p">{</span>
    <span class="c">// 6. 失败处理 (P-8 状态机)</span>
    <span class="k">await</span> <span class="n">writeRuntimeState</span>(pid, name, <span class="p">{</span>
      status: <span class="s">'error'</span>,
      error: <span class="p">{</span> code: e.code || <span class="s">'AGENT_CRASH'</span>, message: e.message, stack: e.stack <span class="p">}</span>,
      updated_at: <span class="k">new</span> <span class="n">Date</span>().<span class="n">toISOString</span>(),
    <span class="p">}</span>);
    timelineLogger.<span class="n">append</span>(pid, <span class="p">{</span>
      source: <span class="s">'system'</span>, kind: <span class="s">'agent_error'</span>,
      ref: <span class="s">`agent/</span><span class="v">${name}</span><span class="s">/</span><span class="v">${call_id}</span><span class="s">`</span>,
      summary: e.message,
    <span class="p">}</span>);
    sseBroker.<span class="n">emit</span>(pid, <span class="s">'agent.error'</span>, <span class="p">{</span> agent: name, call_id, code: e.code, message: e.message <span class="p">}</span>);
    <span class="k">throw</span> e;
  <span class="p">}</span>
<span class="p">}</span></pre>
      </section>

      <section>
        <h2>③ agent-manager.callAgent 需要扩展的字段</h2>
        <p>LemonBoss 既有 <code>agent-manager.callAgent</code> 已经接受 agentName / client / deploy / workDir 等。要支持 DevLoop 需要<b>追加 3 个字段</b>:</p>

        <table>
          <thead><tr><th>新字段</th><th>类型</th><th>含义</th><th>改 agent-manager 的代码量</th></tr></thead>
          <tbody>
            <tr><td><code>toolRegistry</code></td><td>Map&lt;string, ToolDef&gt;</td><td>本次注册的 79 个工具(来自 loadAllTools)</td><td>+5 行:透传给 SessionPool → Protocol</td></tr>
            <tr><td><code>toolCtx</code></td><td>object</td><td>工具调用时的 ctx(pid · sseBroker · etc)</td><td>+3 行:同上透传</td></tr>
            <tr><td><code>onChunk</code></td><td>function</td><td>流式回调(SSE 用)</td><td>+2 行:传给 stream-executor</td></tr>
          </tbody>
        </table>

        <p>合计 ~10 行修改 <code>server/src/core/agent-manager.js</code>。<b>不改 agent-manager 的 public API</b>,所有新字段都是可选;不传时行为同既有。</p>
      </section>

      <section>
        <h2>④ SessionPool key 设计</h2>
        <p>既有 SessionPool key = <code>(agentName, client, deploy, workDir)</code>。DevLoop 把它映射成:</p>

        <table class="dense">
          <thead><tr><th>SessionPool key 段</th><th>DevLoop 填入</th></tr></thead>
          <tbody>
            <tr><td>agentName</td><td><code>devloop-pm</code> / <code>devloop-architect</code> / ...(与 _registry.json id 一致)</td></tr>
            <tr><td>client</td><td><code>data/companies/{cid}/</code></td></tr>
            <tr><td>deploy</td><td><code>{pid}</code></td></tr>
            <tr><td>workDir</td><td>project / unit 目录</td></tr>
          </tbody>
        </table>

        <p>这样得到的复用粒度:</p>
        <ul>
          <li>同 <code>(company, project, agent)</code> 内 → ACP session 复用(多次 callAgent 上下文延续)</li>
          <li>跨 project → 独立 session(避免 PM 把 A 项目知识带进 B 项目)</li>
          <li>同 project 不同 unit 的 Coder → 独立 session(避免 todo-be 的 prompt 污染 auth-be)</li>
        </ul>

        <h3>Coder/Tester 特殊:workDir 必须含 unit_id</h3>
        <p>Coder/Tester 的 workDir 是 <code>units/{unit_id}/</code>。SessionPool key 因此天然按 unit 隔离。<b>意外效果</b>:retry 同 unit 时<b>复用 session</b>(上下文连续),跨 unit 时不复用(互不干扰)。这正是想要的。</p>
      </section>

      <section>
        <h2>⑤ 流式输出 + tool_use 中断处理</h2>
        <p>Claude CLI 输出经 stream-executor 处理。DevLoop 需要的额外行为:</p>

        <table class="dense">
          <thead><tr><th>事件</th><th>原 stream-executor 行为</th><th>DevLoop 加什么</th></tr></thead>
          <tbody>
            <tr><td>text chunk</td><td>累积到 result.content</td><td>+ onChunk 回调 → SSE agent.stream</td></tr>
            <tr><td>tool_use 请求</td><td>路由到工具,执行后回 tool_result</td><td>+ 工具内部可调 sseBroker(如 update_todo_item → SSE agent.step)</td></tr>
            <tr><td>tool 失败</td><td>把错误打回给 Claude</td><td>+ 标准化 ToolValidationError / ToolSandboxError,给 Claude 明确格式</td></tr>
            <tr><td>stop</td><td>返回 final result</td><td>+ 自动写 timeline.agent_done</td></tr>
          </tbody>
        </table>

        <p class="sig">stream-executor 在 LemonBoss 已经处理大部分,DevLoop 主要是<b>挂回调钩子</b>。改动量小。</p>
      </section>

      <section>
        <h2>⑥ 错误传播链</h2>
        <pre class="code"><span class="c">// 错误 4 层传播</span>
工具 execute throws ToolValidationError
        ↓
ToolRegistry 包装成 tool_result { is_error: true, content: "..." }
        ↓
Claude CLI 收到错,继续 reasoning → 可能重试或换路径
        ↓
若多次失败 / 超 budget → Claude stop → result.ok = false
        ↓
callAgentWithPersistence catch → writeRuntimeState status=error
        ↓
LoopController 决定 retry / block / 升 L3</pre>

        <p>这个链路在 <a href="sdd-process.html">P-8 Agent State 持久化</a> 描述了行为,本页是<b>实现细节</b>。</p>
      </section>

      <section>
        <h2>⑦ Mock Claude CLI 模式(开发期省 token)</h2>
        <p>P0 阶段开发 79 工具时,不可能每次都真调 Claude(烧 token + 等响应慢)。需要一个 <code>MOCK_CLAUDE=1</code> 环境变量让 ClaudeCliProtocol 返回 stub 回复,工具流照常跑通。</p>

        <h3>设计</h3>
<pre class="code shape"><span class="c">// packages/acp-core/protocol/ClaudeCliProtocol.js · 增量改动 ~40 行</span>
<span class="k">const</span> MOCK = process.<span class="n">env</span>.<span class="n">MOCK_CLAUDE</span> === <span class="s">'1'</span>;
<span class="k">const</span> mockResponsesDir = path.<span class="n">resolve</span>(__dirname, <span class="s">'../../../system/mock-responses'</span>);

<span class="k">class</span> <span class="n">ClaudeCliProtocol</span> <span class="p">{</span>
  <span class="k">async</span> <span class="n">sendPrompt</span>(input) <span class="p">{</span>
    <span class="k">if</span> (MOCK) <span class="k">return</span> <span class="k">this</span>.<span class="n">_sendPromptMock</span>(input);
    <span class="k">return</span> <span class="k">this</span>.<span class="n">_sendPromptReal</span>(input);
  <span class="p">}</span>

  <span class="k">async</span> <span class="n">_sendPromptMock</span>(input) <span class="p">{</span>
    <span class="c">// 1. 解析 agent name 从 system prompt 或 input.agent</span>
    <span class="k">const</span> agent = <span class="k">this</span>.<span class="n">agentName</span>;             <span class="c">// 启动时存的</span>
    <span class="k">const</span> mode  = input.mode || <span class="s">'default'</span>;

    <span class="c">// 2. 读 mock 响应文件</span>
    <span class="k">const</span> p = path.<span class="n">join</span>(mockResponsesDir, agent, <span class="s">`</span><span class="v">${mode}</span><span class="s">.json`</span>);
    <span class="k">if</span> (!fs.<span class="n">existsSync</span>(p)) <span class="p">{</span>
      <span class="k">return</span> <span class="k">this</span>.<span class="n">_fallbackMock</span>(agent, input);
    <span class="p">}</span>

    <span class="k">const</span> mock = <span class="n">JSON.parse</span>(fs.<span class="n">readFileSync</span>(p, <span class="s">'utf8'</span>));

    <span class="c">// 3. 按 mock 描述的 tool_use 序列,逐个回调工具</span>
    <span class="c">//    模拟 Claude 自己调工具的行为</span>
    <span class="k">for</span> (<span class="k">const</span> step <span class="k">of</span> mock.steps) <span class="p">{</span>
      <span class="k">if</span> (step.tool_use) <span class="p">{</span>
        <span class="k">const</span> result = <span class="k">await</span> <span class="k">this</span>.<span class="n">_dispatchTool</span>(step.tool_use.name, step.tool_use.input);
        <span class="c">// 工具回执理论上影响下一步,简化版直接忽略 result</span>
        <span class="c">// (高级版可让 mock 描述含 tool_result 处理逻辑)</span>
      <span class="p">}</span>
      <span class="k">if</span> (step.delay_ms) <span class="k">await</span> <span class="k">new</span> <span class="n">Promise</span>(r =&gt; <span class="n">setTimeout</span>(r, step.delay_ms));
      <span class="k">if</span> (step.text) <span class="k">this</span>.<span class="n">_emitChunk</span>(step.text);
    <span class="p">}</span>

    <span class="k">return</span> mock.final_result;
  <span class="p">}</span>

  <span class="n">_fallbackMock</span>(agent, input) <span class="p">{</span>
    <span class="c">// 没有专门 mock 文件时,返回最小合规结果</span>
    <span class="k">return</span> <span class="p">{</span>
      ok: <span class="v">true</span>,
      duration_ms: <span class="v">100</span>,
      tokens_used: <span class="v">0</span>,
      content: <span class="s">'[mock fallback response]'</span>,
    <span class="p">}</span>;
  <span class="p">}</span>
<span class="p">}</span></pre>

        <h3>Mock 响应文件结构</h3>
<pre class="tree">
system/mock-responses/                  <span class="com"># 由 P0.A2 创建</span>
├── pm/
│   ├── init.json                       <span class="com"># PM init mode 的 stub</span>
│   ├── incremental.json
│   └── resume.json
├── architect/
│   ├── generate.json
│   ├── patch.json
│   └── resume.json
├── coder/
│   ├── implement.json
│   └── retry.json
├── tester/
│   ├── test.json
│   └── retry.json
├── integrator/
│   ├── run.json
│   └── retry.json
└── bug-triager/
    └── triage.json
</pre>

        <h3>Mock 响应文件示例 · pm/init.json</h3>
<pre class="code"><span class="p">{</span>
  <span class="n">"description"</span>: <span class="s">"PM init mock: 假装解析需求并写出 prd/ 11 章节"</span>,
  <span class="n">"steps"</span>: <span class="p">[</span>
    <span class="p">{</span> <span class="n">"text"</span>: <span class="s">"读取上下文...\n"</span> <span class="p">}</span>,
    <span class="p">{</span> <span class="n">"tool_use"</span>: <span class="p">{</span>
        <span class="n">"name"</span>: <span class="s">"write_todolist"</span>,
        <span class="n">"input"</span>: <span class="p">{</span> <span class="n">"items"</span>: <span class="p">[</span>
          <span class="p">{</span> <span class="n">"id"</span>: <span class="s">"step-001"</span>, <span class="n">"description"</span>: <span class="s">"解析需求"</span> <span class="p">}</span>,
          <span class="p">{</span> <span class="n">"id"</span>: <span class="s">"step-002"</span>, <span class="n">"description"</span>: <span class="s">"bootstrap_prd_site"</span> <span class="p">}</span>,
          <span class="p">{</span> <span class="n">"id"</span>: <span class="s">"step-003"</span>, <span class="n">"description"</span>: <span class="s">"写 index.html"</span> <span class="p">}</span>
        <span class="p">]</span> <span class="p">}</span>
    <span class="p">}</span> <span class="p">}</span>,
    <span class="p">{</span> <span class="n">"tool_use"</span>: <span class="p">{</span> <span class="n">"name"</span>: <span class="s">"bootstrap_prd_site"</span>, <span class="n">"input"</span>: <span class="p">{</span> <span class="n">"pid"</span>: <span class="s">"$pid"</span> <span class="p">}</span> <span class="p">}</span> <span class="p">}</span>,
    <span class="p">{</span> <span class="n">"tool_use"</span>: <span class="p">{</span> <span class="n">"name"</span>: <span class="s">"write_chapter"</span>,
        <span class="n">"input"</span>: <span class="p">{</span> <span class="n">"pid"</span>: <span class="s">"$pid"</span>, <span class="n">"section"</span>: <span class="s">"index"</span>, <span class="n">"page"</span>: <span class="s">"index"</span>,
                   <span class="n">"html"</span>: <span class="s">"&lt;!doctype html&gt;...mock content...&lt;/html&gt;"</span> <span class="p">}</span>
    <span class="p">}</span> <span class="p">}</span>,
    <span class="p">{</span> <span class="n">"tool_use"</span>: <span class="p">{</span> <span class="n">"name"</span>: <span class="s">"echo_diff"</span>,
        <span class="n">"input"</span>: <span class="p">{</span> <span class="n">"summary"</span>: <span class="s">"创建 mock PRD 站点"</span> <span class="p">}</span> <span class="p">}</span> <span class="p">}</span>
  <span class="p">]</span>,
  <span class="n">"final_result"</span>: <span class="p">{</span>
    <span class="n">"ok"</span>: <span class="v">true</span>,
    <span class="n">"mode"</span>: <span class="s">"init"</span>,
    <span class="n">"prd_rev"</span>: <span class="v">1</span>,
    <span class="n">"files_written"</span>: <span class="p">[</span><span class="s">"prd/index.html"</span><span class="p">]</span>,
    <span class="n">"change_summary"</span>: <span class="s">"[mock] PM init"</span>,
    <span class="n">"duration_ms"</span>: <span class="v">100</span>,
    <span class="n">"tokens_used"</span>: <span class="v">0</span>
  <span class="p">}</span>
<span class="p">}</span></pre>

        <h3>什么时候用 mock vs 真</h3>
        <table class="dense">
          <thead><tr><th>场景</th><th>用什么</th><th>原因</th></tr></thead>
          <tbody>
            <tr><td>开发新工具,验证落盘 / SSE 正确</td><td>mock</td><td>不烧 token;快速迭代</td></tr>
            <tr><td>调试 LoopController 主循环</td><td>mock</td><td>同上</td></tr>
            <tr><td>跑 phase0-verify CI</td><td>mock</td><td>CI 不能依赖真 Claude</td></tr>
            <tr><td>验证 Agent system prompt 质量</td><td><b>真</b></td><td>mock 不能反映 prompt 修改</td></tr>
            <tr><td>P1 验收(30s 内 prd/ 落盘)</td><td><b>真</b></td><td>真 token 消耗 + 真 prompt 检验</td></tr>
            <tr><td>P3 BugTriager 归因准确率测试</td><td><b>真</b></td><td>核心检验项</td></tr>
          </tbody>
        </table>

        <h3>$pid / $unit_id 占位符</h3>
        <p>mock JSON 里写 <code>"$pid"</code> 时,dispatch 前 protocol 替换为实际运行时值。简单但够用:</p>
<pre class="code shape"><span class="k">function</span> <span class="n">interpolate</span>(input, ctx) <span class="p">{</span>
  <span class="k">const</span> json = <span class="n">JSON.stringify</span>(input);
  <span class="k">const</span> resolved = json.<span class="n">replace</span>(<span class="s">/"\$(\w+)"/g</span>, (_, key) =&gt;
    <span class="n">JSON.stringify</span>(ctx[key] || <span class="s">'__missing_'</span> + key)
  );
  <span class="k">return</span> <span class="n">JSON.parse</span>(resolved);
<span class="p">}</span></pre>

        <div class="callout ok">
          <b>关键好处:</b>有了 mock 模式,工具实现(P0.A)+ 集成调试(P0.H)+ 验证脚本(P0.I/J)<b>全程零 token 消耗</b>。等所有工具就位 + system prompt 都提取了,再切到 <code>MOCK_CLAUDE=0</code> 跑一遍真 PM 验证。
        </div>
      </section>

      <section>
        <h2>⑧ 性能考量</h2>
        <table>
          <thead><tr><th>项</th><th>关注点</th><th>数字 / 缓解</th></tr></thead>
          <tbody>
            <tr><td>Claude CLI 冷启动</td><td>每个 ACP session 第一次 ~1.5s</td><td>SessionPool 复用让大部分调用是热的</td></tr>
            <tr><td>tool_use 往返延迟</td><td>每次工具调用 ~10-30ms(stdio JSON-RPC)</td><td>合理;高频工具(update_todo_item)不要每行都调</td></tr>
            <tr><td>system prompt 长度</td><td>PM 主体 ~4KB + memory ~3KB = 7KB</td><td>OK,Claude 200K context 完全够</td></tr>
            <tr><td>并发 session 数</td><td>每个 ACP session 占 ~100MB RAM + 1 个 Claude CLI 进程</td><td>单机建议 ≤ 10 并发;项目内并行 ≤ 5</td></tr>
            <tr><td>磁盘 I/O</td><td>工具大量小文件写(agent-state/ + timeline.ndjson)</td><td>同步写 fsync,无 cache;项目目录有 ~100 文件就够大了</td></tr>
            <tr><td>SSE fan-out</td><td>1 项目 1 个广播</td><td>broker 内部 Set,O(订阅数)</td></tr>
          </tbody>
        </table>
      </section>

      <section>
        <h2>⑨ 安全边界</h2>
        <p>沙箱通过三层强制:</p>
        <ol>
          <li><b>ACP 进程层:</b>Claude CLI 起在 cwd 锁定的子进程,不能 cd 出去</li>
          <li><b>工具层:</b>Write/Edit 工具检查 writeAllowList,越界抛 ToolSandboxError</li>
          <li><b>系统层(兜底):</b>定期 scanSandbox 扫描 mtime 在 call 周期内变化的文件,跨边界写直接拒收 result</li>
        </ol>

        <pre class="code shape"><span class="c">// 第二层实现:Write 工具的 sandbox check</span>
module.<span class="n">exports</span>.Write = <span class="p">{</span>
  name: <span class="s">'Write'</span>, ...
  <span class="k">async</span> <span class="n">execute</span>(<span class="p">{</span> path: target, content <span class="p">}</span>, ctx) <span class="p">{</span>
    <span class="k">const</span> abs = path.<span class="n">resolve</span>(ctx.workDir, target);
    <span class="k">const</span> allow = <span class="n">getAllowList</span>(ctx.agent, ctx);   <span class="c">// 来自 _registry.json</span>
    <span class="k">if</span> (!<span class="n">withinAllow</span>(abs, allow))
      <span class="k">throw new</span> <span class="n">ToolSandboxError</span>(target, ctx.agent);
    fs.<span class="n">writeFileSync</span>(abs, content);
    <span class="k">return</span> <span class="p">{</span> ok: <span class="v">true</span>, path: abs <span class="p">}</span>;
  <span class="p">}</span>
<span class="p">}</span>;</pre>
      </section>

      <section>
        <h2>⑩ 一行总结</h2>
        <div class="callout ok">
          <b>桥的全貌:</b>LoopController.callAgent (P-8 包装) → agent-manager.callAgent (透传 toolRegistry/toolCtx) → SessionPool (key 含 pid) → ClaudeCliProtocol (spawn claude + --tools) → Claude CLI (tool_use API) → ToolRegistry.execute (业务工具) → 写文件 / 发 SSE → 回到 Claude。<b>没有新协议,只有现有接口的扩展</b>。
        </div>
      </section>

      <section>
        <h2>⑪ 关联</h2>
        <ul>
          <li><a href="arch-tool-registry.html">Tool Registry</a> · 工具层细节</li>
          <li><a href="sdd-process.html">P-8 Agent State 持久化</a> · 包装层为啥这么写</li>
          <li><a href="arch-mapping.html">LemonBoss 映射</a> · 既有 session-pool / agent-manager / scheduler 怎么 REUSE</li>
        </ul>
      </section>

    </article>
    <nav class="prev-next"></nav>
    <footer class="site">
      <div><b>Section</b>05 · Architecture</div>
      <div><b>Page</b>arch-acp-bridge.html</div>
      <div><b>Spec Rev</b>v2 · 2026-05-13</div>
    </footer>
  </main>
</div>
<script src="assets/shell.js"></script>
</body>
</html>