- commit
- 65fcbc4
- parent
- e108fd6
- author
- im_wower
- date
- 2026-03-28 17:52:53 +0800 CST
docs: add T-S043 Claude Code CLI duplex integration task card Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2 files changed,
+209,
-0
+203,
-0
1@@ -0,0 +1,203 @@
2+# Task T-S043：接入 Claude Code CLI 双工模式
3+
4+## 状态
5+
6+- 当前状态：`待开始`
7+- 规模预估：`M`
8+- 依赖任务：无（独立于 T-S039~T-S042，可并行）
9+- 建议执行者：`Claude`（需要理解现有 codexd 架构并复刻，涉及 stdio 双工协议）
10+
11+## 直接给对话的提示词
12+
13+读 `/Users/george/code/baa-conductor/tasks/T-S043.md` 任务文档，完成开发任务。
14+
15+如需补背景，再读：
16+
17+- `/Users/george/code/baa-conductor/apps/codexd/src/daemon.ts`（codexd 实现参考）
18+- `/Users/george/code/baa-conductor/apps/codexd/src/app-server-transport.ts`（stdio transport 参考）
19+- `/Users/george/code/baa-conductor/apps/codexd/src/local-service.ts`（HTTP API 层参考）
20+- `/Users/george/code/baa-conductor/docs/runtime/codexd.md`（codexd 运行时文档）
21+
22+## 当前基线
23+
24+- 仓库：`/Users/george/code/baa-conductor`
25+- 分支基线：`main`
26+- 提交：`e108fd6`
27+
28+## 分支与 worktree（强制）
29+
30+每个任务必须使用独立的分支和 worktree，禁止直接在 main 上修改，禁止多个任务共用同一个 worktree。
31+
32+- 分支名：`feat/claude-code-daemon`
33+- worktree 路径：`/Users/george/code/baa-conductor-claude-code-daemon`
34+
35+开工步骤：
36+
37+1. `cd /Users/george/code/baa-conductor`
38+2. `git worktree add ../baa-conductor-claude-code-daemon -b feat/claude-code-daemon main`
39+3. `cd ../baa-conductor-claude-code-daemon`
40+4. 在这个 worktree 目录里开发，不要回到主仓库目录
41+
42+完成后合并步骤：
43+
44+1. 在 worktree 里提交所有变更
45+2. `cd /Users/george/code/baa-conductor`
46+3. `git merge feat/claude-code-daemon`
47+4. `git worktree remove ../baa-conductor-claude-code-daemon`
48+
49+合并冲突处理：
50+
51+1. 如果 `git merge` 报冲突，先 `git diff` 查看冲突文件
52+2. 手动解决冲突后 `git add` 冲突文件
53+3. `git merge --continue` 完成合并
54+4. 不要用 `git merge --abort` 然后 force 覆盖
55+
56+## 目标
57+
58+将 Claude Code CLI 以 stdio 双工流模式接入 conductor，提供与 codexd 类似的 HTTP API 层，支持通过 BAA 指令调用 Claude Code 执行任务。
59+
60+## 背景
61+
62+当前 conductor 已接入 codexd（Codex app-server），通过 stdio 双工通信管理会话和多轮对话。Claude Code CLI 同样支持 stream-json 双工模式：
63+
64+```bash
65+claude -p \
66+ --input-format stream-json \
67+ --output-format stream-json \
68+ --replay-user-messages
69+```
70+
71+stdin 写入 JSON 消息，stdout 读取 JSON 流式响应，进程常驻。接入模式与 codexd 本质相同，可以复刻 codexd 的架构。
72+
73+## 涉及仓库
74+
75+- `/Users/george/code/baa-conductor`
76+
77+## 范围
78+
79+- 新建 `apps/claude-coded/`（Claude Code 守护进程）
80+- spawn Claude Code CLI 子进程，stdio 双工通信
81+- 包装 HTTP API 层（类似 codexd 的 local-service）
82+- conductor 代理路由
83+- BAA 指令系统新增 `@claude-code` target（可选，视进度）
84+
85+## 路径约束
86+
87+- 新应用放在 `apps/claude-coded/`
88+- HTTP 端口：`4320`（codexd 用 4319，紧跟其后）
89+- launchd label：`so.makefile.baa-claude-coded`
90+- 日志目录：`logs/claude-coded/`
91+- 状态目录：`state/claude-coded/`
92+
93+## 推荐实现边界
94+
95+参照 codexd 架构，逐层对应：
96+
97+| codexd | claude-coded | 说明 |
98+|---|---|---|
99+| `daemon.ts` | `daemon.ts` | 子进程生命周期管理 |
100+| `app-server-transport.ts` | `stream-json-transport.ts` | stdio JSON 双工传输 |
101+| `local-service.ts` | `local-service.ts` | HTTP API 层 |
102+| `config.ts` | `config.ts` | 配置与默认值 |
103+| `index.ts` | `index.ts` | 入口 |
104+
105+## 允许修改的目录
106+
107+- `/Users/george/code/baa-conductor/apps/` （新建 claude-coded）
108+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/local-api.ts` （加代理路由）
109+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/index.ts` （注入配置）
110+- `/Users/george/code/baa-conductor/scripts/runtime/` （安装/验证脚本）
111+
112+## 尽量不要修改
113+
114+- `/Users/george/code/baa-conductor/apps/codexd/` （参考但不改）
115+- `/Users/george/code/baa-conductor/plugins/` （不动）
116+- `/Users/george/code/baa-conductor/packages/db/` （不动）
117+- `/Users/george/code/baa-conductor/apps/conductor-daemon/src/instructions/` （target 注册可以后续单独做）
118+
119+## 必须完成
120+
121+### 1. Claude Code 子进程管理
122+
123+- spawn `claude` 子进程，参数：`-p --input-format stream-json --output-format stream-json --replay-user-messages --permission-mode bypassPermissions --bare`
124+- stdio pipe 双向通信
125+- 子进程异常退出时自动重启（带指数退避）
126+- 优雅关闭（SIGTERM → 等待 → SIGKILL）
127+- 可配置子进程的 cwd、model、额外参数
128+
129+### 2. stream-json 传输层
130+
131+- stdin 写入：JSON 消息 + 换行
132+- stdout 读取：JSON 流式响应，按行解析
133+- 处理部分 JSON（chunk 可能跨行）
134+- 超时保护（单轮对话最长等待时间，可配置）
135+- 事件发射：turn_start、content_delta、turn_complete、error
136+
137+### 3. HTTP API 层
138+
139+- `GET /healthz` — 健康检查
140+- `GET /describe` — 服务描述
141+- `GET /v1/claude-coded/status` — 守护进程和子进程状态
142+- `POST /v1/claude-coded/ask` — 提交单轮请求，等待完整响应
143+- `POST /v1/claude-coded/ask/stream` — 提交请求，SSE 流式返回
144+- `WS /v1/claude-coded/events` — WebSocket 事件流（可选）
145+
146+端口：`127.0.0.1:4320`（本地只监听）
147+
148+### 4. conductor 代理路由
149+
150+- `GET /v1/claude-coded` — 代理到 claude-coded status
151+- `POST /v1/claude-coded/ask` — 代理到 claude-coded ask
152+- 环境变量：`BAA_CLAUDE_CODED_LOCAL_API_BASE`，默认 `http://127.0.0.1:4320`
153+
154+### 5. 运维脚本
155+
156+- `scripts/runtime/install-claude-coded.sh` — launchd 安装
157+- 在 `scripts/runtime/verify-mini.sh` 中加入 claude-coded 健康检查（可选）
158+
159+## 需要特别注意
160+
161+- Claude Code 的 stream-json 格式可能与 codex app-server 不同，需要先实测确认消息格式再写解析逻辑
162+- `--bare` 模式跳过 hooks、LSP 等重型初始化，启动更快
163+- `--permission-mode bypassPermissions` 只在受信目录使用
164+- Claude Code 进程比较重（内存、启动时间），不要频繁重启
165+- 会话持续性：Claude Code 的 `--continue` 和 `--resume` 依赖本地 session 文件，需要确认在 stream-json 模式下是否支持
166+- 所有开发必须在 worktree 中进行，不要在主仓库目录修改代码
167+
168+## 验收标准
169+
170+- `claude-coded` 独立启动，spawn claude 子进程成功
171+- `curl http://127.0.0.1:4320/healthz` 返回 200
172+- `curl http://127.0.0.1:4320/v1/claude-coded/status` 返回子进程状态
173+- `curl -X POST http://127.0.0.1:4320/v1/claude-coded/ask -d '{"prompt":"echo hello"}'` 返回 Claude 的回复
174+- 子进程崩溃后自动重启
175+- conductor 代理路由 `curl http://100.71.210.78:4317/v1/claude-coded` 返回状态
176+
177+## 推荐验证命令
178+
179+- `cd /Users/george/code/baa-conductor-claude-code-daemon && pnpm build`
180+- `cd /Users/george/code/baa-conductor-claude-code-daemon && pnpm test`
181+- `curl http://127.0.0.1:4320/healthz`
182+- `curl http://127.0.0.1:4320/v1/claude-coded/status | jq .`
183+- `curl -X POST http://127.0.0.1:4320/v1/claude-coded/ask -H 'Content-Type: application/json' -d '{"prompt":"what is 1+1?"}'`
184+
185+## 执行记录
186+
187+> 以下内容由执行任务的 AI 填写，创建任务时留空。
188+
189+### 开始执行
190+
191+- 执行者：
192+- 开始时间：
193+- 状态变更：`待开始` → `进行中`
194+
195+### 完成摘要
196+
197+- 完成时间：
198+- 状态变更：`进行中` → `已完成`
199+- 修改了哪些文件：
200+- 核心实现思路：
201+- 跑了哪些测试：
202+
203+### 剩余风险
204+
+6,
-0
1@@ -46,6 +46,12 @@
2
3 执行顺序：T-S039 先行 → T-S040 和 T-S041 可并行 → T-S042 独立
4
5+### 独立任务
6+
7+| 任务 | 标题 | 规模 | 依赖 | 建议 AI | 状态 |
8+|---|---|---|---|---|---|
9+| [`T-S043`](./T-S043.md) | 接入 Claude Code CLI 双工模式 | M | 无（独立于 artifact 主线） | Claude | 待开始 |
10+
11 ### P1（并行优化）
12
13 - [`../bugs/OPT-002-executor-timeout.md`](../bugs/OPT-002-executor-timeout.md)