# Agent SDK 桌面客户端方案（最终版 v1）

> **状态**：已对齐决策，待评审/资源批准后立项
> **日期**：2026-05-09
> **决策来源**：Chentao Jia × Claude 共同对齐
> **下一步**：评审通过后迁移到 `docs/modules/agent-client/` 正式立项

---

## 调研（2026-05-10）

> 本节是 v1 方案立项前的技术调研，回答三个问题：(1) Claude Code CLI vs Agent SDK 差异；(2) Claude Code App（桌面/Web/IDE）vs Agent SDK 差异；(3) 自封装外壳的实际工作量。
>
> **来源说明**：[官方] = code.claude.com / platform.claude.com / Anthropic GitHub；[社区] = blog/媒体/第三方仓库；[反编译] = 公开反混淆或 source map 泄露材料。涉及 2026-Q2 之后的 Claude Code 桌面版改版（Routines、并行 session sidebar 等）来源以社区报道为主，**评审时建议复核**。

### 1. Claude Code CLI vs Agent SDK 差异

CLI 和 Agent SDK 共享同一套 query 引擎、工具集、context 管理 [官方]。但 SDK 上层做了减法——很多 CLI 用户体验靠的能力，SDK 默认是关掉/不暴露的。

| 功能 | CLI 行为 | SDK 默认 | SDK 复刻 CLI 行为要做什么 | 工作量 |
|---|---|---|---|---|
| **System prompt** | 269 base tokens + 110+ 条件加载 component（工具指令、编码规范、安全规则）[反编译] | 仅基础工具指令 | `systemPrompt: { preset: "claude_code" }` + `settingSources` 含 `["project","user"]` | 0 |
| **CLAUDE.md 加载** | 自动递归加载 parent dirs + 项目 `CLAUDE.md` + `.claude/rules/` | 不加载 | 配置 `settingSources: ["user","project","local"]` | 0 |
| **Skills** | 自动扫描 `.claude/skills/`，描述常驻 prompt，全文按需加载 | 需显式启用 | 配置 `skills: "all"` 或显式列表 | <1 人周（验 SKILL.md 兼容） |
| **内置工具集** | Read/Edit/Write/Bash/Glob/Grep/Task/TodoWrite/WebFetch/WebSearch/NotebookEdit 等 | 同套，要 `allowedTools` 显式声明 | 配置 `allowedTools` 清单 | 0 |
| **权限模式** | default/acceptEdits/plan/bypassPermissions，含交互弹窗 + 重复 block 自动降级 [官方] | 提供 `canUseTool` callback，**无 UI 弹窗** | 自己写权限弹窗 UI（本次/同类/此项目）+ canUseTool 状态机 | **3-5 人周** |
| **Hooks** | 9 种类型 filesystem hooks（settings.json 配） | 同 + programmatic callback | 配 `settingSources` 即自动加载 | 0 |
| **Context compaction** | 自动触发，阈值 75%，env `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 可调 | 支持但需显式配置 `contextManagement.edits` | 配 env 或 options | 0（行为对等，体验差异要测） |
| **Slash commands** | `/init` `/compact` `/ide` 等 CLI 原生 | 不暴露 | Node service 自己解析 prompt 前缀 + 分发到 handler | **2-3 人周**（4-6 个常用命令）|
| **Session 持久化与恢复** | 本地 JSONL + SQLite 索引自动持久化 | **完全无状态**，每次 `query()` 独立 | 自建 SQLite schema + 序列化 + resume logic | **2-3 人周** |
| **Streaming I/O** | 终端逐 token 流式渲染 | async iterator 吐数据，**渲染要自己写** | Next.js SSE/WebSocket + React 增量渲染 | 见前端层 |
| **Auto memory** | `~/.claude/projects/<project>/memory/MEMORY.md` 自动加载 | 默认开启 | 0 配置 | 0 |
| **Telemetry/logging** | OTLP 选项（CLAUDE_CODE_ENABLE_TELEMETRY）| 无 | 自己写日志/计费埋点 | 1-2 人天 |

**关键 takeaways**

1. **SDK 直接给的（0 工作量）**：工具集、hooks 框架、CLAUDE.md 加载、skills discovery、streaming 数据流、context compaction、permission callback、auto memory。配置 `settingSources` 和 `allowedTools` 就有。
2. **SDK 给一半要补（<2 人周/项）**：slash commands 分发、telemetry。
3. **SDK 完全不给（≥3 人周/项）**：**权限弹窗 UI**、**session 持久化**、**流式 diff/tool call 可视化**。这三块是 Claude Code 体验核心，也是本方案工作量最重的部分。

### 2. Claude Code App（桌面/Web/IDE）vs Agent SDK 差异

Anthropic 在 2026-Q2 对 Claude Code 桌面版做了重大改版 [社区，待复核]。App 形态相比 CLI 多了大量交互/协调能力，这些是 FFOA 用户对自家客户端的**自然预期**。

| 能力 | App 有 | CLI | SDK | 对方案影响 / 工作量 |
|---|---|---|---|---|
| **多 session 并行 sidebar** | ✅ 按状态/项目过滤、拖拽重排 | 单 session/terminal | 应用层管理 ID | 高，**3-4 人周** |
| **session 跨设备同步** | ✅ Remote sessions 在 Anthropic cloud，iOS/Web/Desktop 互通 | ❌ | ❌ | 低，v1 不做 |
| **Side chat（branch 当前任务）** | ✅ | ❌ | ❌ | 中，v2 候选 |
| **可视化 diff** | ✅ hunk 折叠/inline comment | 文本 delta | 流数据 | 高，**8-12 人周**（建议复用 OSS 组件） |
| **Tool call 可视化** | ✅ 折叠面板 | 文本 | 流式 JSON | 中，**4-6 人周** |
| **Routines（计划执行）** | ✅ 时间/API/Webhook 触发 | ❌ | ❌（需手工调度） | 低，v2 用 cron/CI 补 |
| **HTML/PDF preview** | ✅ | ❌ | ❌ | 低，前端 iframe 即可 |
| **IDE 插件**（VS Code/JetBrains）| ✅ inline diff/edit/selection 注入 | ❌ | ❌ | 低，v1 Web 优先，v2 候选 |
| **权限对话** | ✅ 自然语言/可记忆 | 文本 prompt | callback | 高，**5-7 人周**（与 §1 那 3-5 人周部分重合） |
| **配额/计费可视** | ✅ | ❌ | ❌ | 低，v2 |

**关键 takeaways**

1. App 相比 SDK 多出来的能力大部分是 **UI 问题**而非算法问题。SDK 能吐数据，前端负责渲染。
2. **2 人 6 个月最大压力**集中在：权限弹窗 + session sidebar + diff 可视化 + tool call 面板 + streaming markdown，这五项加起来占总工作量 50%+。
3. **可延后到 v2**：side chat、Routines、IDE 插件、计费面板、跨设备同步。

### 3. 自封装外壳的工作量估算

按三层架构 + 桌面壳 + 测试，逐层拆分。

#### A. Node.js Service 层（含 Agent SDK）

| 子项 | 估算 |
|---|---|
| 基础 query() 循环 + streaming | 2-3 天 |
| Session 管理（SQLite schema/CRUD/序列化/resume） | 5-7 人天 |
| 权限回调 canUseTool（不含 UI） | 2 人天 |
| **权限弹窗通道**（WS 长连接，发询问 → 等响应 → 继续，含超时/取消） | **3-4 人周** |
| Slash command 分发器 | 3-5 人天 |
| `/init` `/compact` 等 4-6 个命令 | 5-7 人天 |
| Error & 结构化日志 | 2 人天 |
| **小计** | **4-5 人周** |

#### B. NestJS 中转层（可选）

| 子项 | 估算 |
|---|---|
| 反向代理（http-proxy-middleware）| 1-2 人天 |
| FFOA 登录集成（OAuth/OIDC relay）| 3-5 人天 |
| API key 白名单 + Authorization middleware | 2 人天 |
| **`cache_control` / `anthropic-*` 头透传**（关键，防成本飙升） | 1 人天 + 单测覆盖 |
| 计费 logging + 限流 | 3-4 人天 |
| **小计** | **1.5-2 人周** |

#### C. Next.js 前端层

| 子项 | 估算 |
|---|---|
| 基础架构（SSE/WS + React Context）| 3-4 人天 |
| Session sidebar + 切换 + resume | 3-4 人天 |
| Streaming markdown 渲染（react-markdown + 增量 append）| 4-5 人天 |
| **Diff 可视化**（react-diff-view，hunk 折叠/inline）| **2-3 人周** |
| Tool call 折叠面板（accordion，JSON 高亮）| 5-7 人天 |
| **权限弹窗**（dialog + 本次/同类/此项目 + 超时）| **1-1.5 人周** |
| Error & logs 面板 | 2-3 人天 |
| 主题 + 响应式（tailwind/shadcn）| 2 人天 |
| **小计** | **4-5 人周** |

#### D. Tauri 桌面壳（M3）

| 子项 | 估算 |
|---|---|
| Node sidecar 启动 + 进程管理 | 4-5 人天 |
| 自动更新（tauri-updater）| 3-4 人天 |
| Window/Tray + IPC | 3-4 人天 |
| Mac/Windows 打包验证 + 不签名教程 | 3-5 人天 |
| **小计** | **1-2 人周** |

#### E. 测试 / 文档 / 部署

| 子项 | 估算 |
|---|---|
| 集成测试（Node + Next）| 3-5 人天 |
| Playwright E2E | 2-3 人天 |
| API 文档 | 1-2 人天 |
| Docker / CI / 内部分发 | 3-5 人天 |
| **小计** | **1-1.5 人周** |

#### 总览

| 阶段 | 工作量 |
|---|---|
| Web 全量（A+B+C+E）| **11-13.5 人周** |
| 加 Tauri 壳（+D）| **12-15.5 人周** |

#### "2 人 × 6 个月（≈ 26 人周）"判断：**刚好，吃紧**

- **预算 26 人周 - 实工 12-15.5 人周 = 10-14 人周机动**，看似充裕，但实际会被以下吃掉：
  - 权限交互 UX 反复迭代（**+5-7 周**，spike 必须先做 prototype）
  - Session SQLite schema 重构（**+2-3 周**，schema 没设计好就要重写）
  - Streaming 大 diff 卡顿调优（virtual scroll + 增量渲染，**+1-2 周**）
  - SDK 边界 case 调试（context 溢出、resume 失败、tool 超时，**+1-2 周**）
  - FFOA 登录系统对接的意外复杂度（**+1-2 周**）
- **风险三个**：
  1. 权限弹窗 UX 反复改（最大不确定性，建议 spike 周做 prototype）
  2. SDK 的 compaction 阈值/预算未暴露细节，长 session 体验跟 CLI 可能差很多
  3. Diff 渲染遇到大文件时性能塌陷
- **加速空间（-2-3 周）**：
  - 复用 OpenCode / 其它 OSS diff 组件，不从零写
  - 计费面板、Tauri 自动更新延后到 v2
  - 单 user 假设跳过 session conflict 处理

**结论**：Web 优先策略下，2 人 × 6 个月覆盖 M1-M2 + Tauri 壳 + 内部推广**可行但吃紧**，建议把 Routines / 跨设备同步 / IDE 插件明确划到 v2，否则会超期。

### 4. 调研来源

#### 官方 [官方]
- [Claude Code Docs overview](https://code.claude.com/docs/en/overview)
- [Claude Code permission modes](https://code.claude.com/docs/en/permission-modes)
- [Use Claude Code features in the SDK](https://code.claude.com/docs/en/agent-sdk/claude-code-features)
- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview)
- [Automatic context compaction cookbook](https://platform.claude.com/cookbook/tool-use-automatic-context-compaction)
- [anthropics/claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript)
- [anthropics/claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python)

#### 社区（建议复核） [社区]
- [Claude Code CLI vs Agent SDK: System Prompt Differences](https://github.com/shanraisshan/claude-code-best-practice/blob/main/reports/claude-agent-sdk-vs-cli-system-prompts.md)
- [Anthropic Rebuilds Claude Code Desktop App Around Parallel Sessions (MacRumors)](https://www.macrumors.com/2026/04/15/anthropic-rebuilds-claude-code-desktop-app/)
- [VentureBeat: Claude Code redesigned desktop + Routines](https://venturebeat.com/orchestration/we-tested-anthropics-redesigned-claude-code-desktop-app-and-routines-heres-what-enterprises-should-know/)
- [OpenCode Desktop: Moving to Electron (dev.to)](https://dev.to/brendonovich/moving-opencode-desktop-to-electron-4hip)
- [Continue.dev](https://www.continue.dev/)
- [Tauri Node.js sidecar 文档](https://v2.tauri.app/learn/sidecar-nodejs/)

#### 反编译/泄露材料（仅作实现细节参考，不直接复用代码）[反编译]
- [ghuntley/claude-code-source-code-deobfuscation](https://github.com/ghuntley/claude-code-source-code-deobfuscation)（archived）
- 2026-03-30 npm `2.1.88` source map 事故还原版（Anthropic 定性为 packaging issue，非 breach；未发 DMCA）

---

## 0. 决策摘要表（16 项）

| # | 决策点 | 结论 |
|---|---|---|
| 1 | 目标用户 | **仅 FFOA 内部使用** |
| 2 | 客户端形态 | **Web + Tauri 桌面壳**（Web 先，Tauri 后跟） |
| 3 | 与 agent pool 整合 | **完全独立**（不绑 slot） |
| 4 | 部署模式 | **每人本地装 service**（npm 装） |
| 5 | 项目/cwd 切换 | **内置项目列表，预先注册**（IDE workspace 风格） |
| 6 | 桌面壳发布 | **不签名，内部分发 + 教用户手动允许** |
| 7 | 中转服务器 | **自建 Nest 服务**（跟 FFOA 后端栈一致） |
| 8 | 鉴权 | **走 FFOA 现有登录体系** |
| 9 | 多模型支持 | **一期只跑 Claude**（中转可后续扩展） |
| 10 | Web/Tauri 节奏 | **Web 版先稳定，再加 Tauri 壳** |
| 11 | 配置体系 | **自动继承项目里的 `.claude/`** |
| 12 | 资源预算 | **2 人 × 6 个月（含 1 周 spike）** |
| 13 | 权限默认模式 | **跟 Claude Code 一致**：写操作弹窗问，可"本次/同类/始终" |
| 14 | 同项目多 session | **允许并发 + 风险提示** |
| 15 | 遥测 | **崩溃错误 + 关键事件**（Sentry 类，匿名） |
| 16 | 立项前 spike | **先花 1 周验证联通**，再正式开工 |

---

## 1. 背景与目标

### 痛点
- 直接调 Anthropic API 拿不到 Claude Code 的工程化能力（agent loop / 工具集 / system prompt 调优 / context 压缩 / prompt caching / MCP / hooks / skills），自己造 5-10 人月起步且永远追不上官方迭代。
- Claude Code 桌面版无法走自家中转，不便于做鉴权/计费/审计。
- 团队需要把 Claude Code 的多 session 协作能力跟 FFOA 业务深度集成。

### 目标
做一个 **FFOA 自家的 Claude Code 客户端**，复用 Claude Agent SDK 全部工程能力，但 API 走自家中转、UI 自己掌控、跨平台（Mac + Windows，Linux 顺带）。

### 关键事实（已查证）
- Claude Agent SDK 公开可用（v0.2.x，TS + Python 双绑定，跟 Claude Code CLI 同引擎）
- SDK 工具集 / Hooks / Skills / Slash commands / MCP / 权限模式 / Subagent **跟 CLI 完全对等**
- SDK 通过 `ANTHROPIC_BASE_URL` 支持指向自家 LLM Gateway（官方设计为企业鉴权/路由用）
- SDK 默认行为：**自动加载 cwd 下的 `.claude/skills`、`.claude/commands`、MCP 配置、CLAUDE.md** —— 决策 11 直接利用此特性

---

## 2. 三层架构

```
┌─────────────────────────────────────┐
│  浏览器 UI (Chrome/Edge/Safari)     │  ← 渲染层
│   - 对话流式渲染（markdown + 高亮）   │
│   - Tool call 可视化（diff/折叠）    │
│   - 权限确认弹窗                       │
│   - 项目侧边栏 + 多 session 切换     │
└─────────────────┬───────────────────┘
                  │ WebSocket (localhost)
                  ▼
┌─────────────────────────────────────┐
│  本地 Service (Node + Agent SDK)     │  ← 执行层（本地装）
│   - Agent SDK 跑 agent loop          │
│   - 执行 Read/Write/Edit/Bash 工具    │
│   - 自动加载项目 .claude/ 配置        │
│   - Session 状态本地 sqlite 持久化    │
│   - 项目注册表（用户预先注册的目录）   │
└─────────────────┬───────────────────┘
                  │ HTTPS (ANTHROPIC_BASE_URL → 中转)
                  ▼
┌─────────────────────────────────────┐
│  中转服务器（FFOA 自建 Nest）         │  ← 网络层
│   - 反向代理到 Anthropic API         │
│   - FFOA 登录鉴权（决策 8）          │
│   - 计费 / 审计 / 限流                │
│   - Provider 抽象层（决策 9 预留）   │
└─────────────────┬───────────────────┘
                  │ HTTPS
                  ▼
              Anthropic API
```

### 数据流（以"agent 改文件"为例）

1. 浏览器 → WebSocket → 本地 Service
2. 本地 Service 喂给 Agent SDK，启动 agent loop
3. SDK → HTTPS → 中转 → Anthropic，返回 `tool_use: Read('/path/file')`
4. 本地 Service **直接读用户机器上的文件**（必须本地，远程读不到）
5. 文件内容回 Anthropic，分析后返回 `tool_use: Edit(...)`
6. 触发 PreToolUse hook → 浏览器弹"是否允许编辑此文件"（决策 13）→ 用户点"始终允许此项目"
7. 本地 Service 执行 Edit
8. 流式 message 通过 WebSocket 推回浏览器渲染

---

## 3. 技术选型

| 层 | 选型 | 理由 |
|---|---|---|
| 浏览器 UI 框架 | Next.js / React + TypeScript | 跟 FFOA 前端栈一致，团队熟悉 |
| 流式渲染 | react-markdown + highlight.js + 自定义 tool call 组件 | 成熟方案 |
| 本地 Service | Node 18+ + Express/Fastify + WebSocket（ws） | 跟 SDK 同 runtime |
| Agent SDK | `@anthropic-ai/claude-agent-sdk` (TypeScript) | 官方 TS 绑定 |
| Session 持久化 | SQLite（better-sqlite3） | 单文件、零运维、足够 |
| 中转服务器 | NestJS | 跟 FFOA 后端栈一致 |
| 鉴权 | OAuth/JWT（接 FFOA 现有登录） | 决策 8 |
| 桌面壳 | Tauri 2.x | 体积小（~10MB），Rust 安全性好 |
| 遥测 | Sentry（自托管或 SaaS） | 决策 15 |

---

## 4. 关键 UX 决策细节

### 4.1 项目管理（决策 5）
- 用户首次启动 → 引导添加项目 → 选本地目录 + 给项目起名
- 项目列表持久化在 service 的 sqlite
- 侧边栏列出所有项目，点击进入项目即把 cwd 切换为该目录
- 项目内可开多 session（决策 14）

### 4.2 权限模式（决策 13）
- 默认沿用 Claude Code 模型：Read/Glob/Grep 不问，Write/Edit/Bash 第一次问
- 弹窗选项：「本次允许」「同类（同工具）始终允许」「此项目内始终允许」「拒绝」
- 选项持久化在项目级 sqlite，跟项目走

### 4.3 多 session 并发（决策 14）
- 同一项目允许多 session
- 启动第 2 个 session 时顶部黄条提示："另一个 session 也在此项目中，注意文件冲突"
- 不做强制锁定（保持灵活）
- 不自动开 worktree（避免引入 git 复杂性）

### 4.4 配置继承（决策 11）
- Service 启动 session 时，cwd 设为项目目录
- Agent SDK 默认行为自动加载：
  - `<project>/.claude/skills/*/SKILL.md` → skills 可用
  - `<project>/.claude/commands/*.md` → slash commands 可用
  - `<project>/.claude/settings.json` → MCP servers / hooks
  - `<project>/CLAUDE.md` → system prompt 注入
- FFOA workspace 现有配置 **零改动可用**

---

## 5. Phase 与里程碑（27 周）

```
W0       │ Spike 周（决策 16）
W1-W6    │ M1: Web 版基础（6 周）
W7-W14   │ M2: Web 版完整（8 周）
W15-W18  │ M3: Tauri 桌面壳（4 周）
W19-W26  │ M4: 打磨 + 文档 + 内部推广（8 周）
─────────┼──────────────────────────
合计     │ 27 周（≈ 6 个月，2 人）
```

### W0 — Spike 周（决策 16）
**目标**：验证技术联通，决定是否正式立项
- D1-D2：中转 Nest 服务 hello world，转发到 Anthropic API
- D3：Agent SDK 在本地 Node 服务跑通，输出 tool call
- D4：浏览器 WebSocket 收到流式 message
- D5：联通三层（浏览器 → service → 中转 → Anthropic），完整跑一个"agent 读 1 个文件"流程
- 产出：可运行 PoC + 是否正式立项的决策报告

### M1 — Web 版基础（W1-W6）
- 中转服务接 FFOA 登录，basic 鉴权
- 本地 Service：项目注册、session 创建、SQLite 持久化
- 浏览器 UI：单 session、流式渲染、基本权限弹窗
- 产出：1 个开发者能用起来

### M2 — Web 版完整（W7-W14）
- 多 session 并发 + 风险提示
- Tool call 可视化（diff/Bash output 折叠）
- MCP / Skills / Hooks / CLAUDE.md 自动继承
- 项目切换、历史 session resume
- Sentry 接入（决策 15）
- 产出：5-10 人内部试用

### M3 — Tauri 桌面壳（W15-W18）
- Tauri 包装：Service 作为 sidecar 启动，浏览器换成 Tauri webview
- Mac/Windows 两端打包验证
- 不签名分发，写"如何允许运行"教程
- 自动更新（Tauri updater，连内部下载站）
- 产出：装机版 dmg/msi

### M4 — 打磨 + 文档 + 推广（W19-W26）
- 性能优化、bug 修复
- 用户文档 / 视频教程
- 内部推广，FFOA 全员可用
- 计费视图、管理员看板
- 产出：FFOA 全员能用，作为内部工具稳定运行

---

## 6. 关键风险与缓解

| 风险 | 缓解 |
|---|---|
| **SSE 流式被代理缓冲断流** | Nginx `proxy_buffering off` + `chunked_transfer_encoding on`，spike 周必须验证 |
| **`cache_control: ephemeral` 头丢失导致成本飙升** | 中转服务白名单透传所有 `cache_control` / `anthropic-*` 头，写单测覆盖 |
| **SDK 版本跟随成本** | Service 锁 SDK 版本到 patch level，每月评估升级；封装层保持低耦合 |
| **不签名桌面壳的用户教育成本** | M3 阶段做 "如何首次允许运行" 的截图教程；准备 Mac/Windows 各一段 30s 视频 |
| **多 session 并发文件冲突** | 风险提示（决策 14）+ 鼓励用户切分项目目录；不做强一致性 |
| **FFOA 登录接入复杂度** | M1 第一周就跟登录团队对齐；准备 fallback 走 API key |
| **Tauri Mac/Windows 双端包打不出 / 运行 bug** | M3 单独 4 周冗余足够 |

---

## 7. 立项前置事项

开工前必须就绪：
- [ ] **中转服务器资源**：域名 + 服务器 + Anthropic API key 配额申请
- [ ] **FFOA 登录团队对齐**：明确接入方式（OAuth？JWT？回调地址？）
- [ ] **2 人团队配置**：1 个偏后端（中转 + Service）+ 1 个偏前端（Web UI），两人都需要 TypeScript 经验
- [ ] **Sentry 实例**：自托管 or SaaS 选定
- [ ] **代码仓库**：在 Gitea 建 `ffoa-agent-client` 仓库，配 CI
- [ ] **W0 Spike 任务清单**：5 天每天目标已写在第 5 节，团队确认

立项后第一件事：
- [ ] 在 `docs/modules/agent-client/` 建模块文档（PRD / 数据模型 / API / 状态机 / 测试方案）

---

## 8. 后续可能的扩展（不在本次 6 个月范围）

- **多模型支持**：中转 provider 抽象已预留，未来加 GPT/Gemini 路由（决策 9）
- **VS Code 插件形态**：复用 Web UI 代码，套个 webview 容器
- **桌面壳签名**：如果需要对外发布，加 Mac 公证 + Windows EV 证书
- **共享部署模式**：如果有需要给非开发者用，做共享 service 部署
- **跟 agent pool 集成**：决策 3 是"完全独立"，但如果发现高频用户希望联动，未来可加

---

## 9. 参考资料

### 官方文档
- [Claude Agent SDK Overview](https://code.claude.com/docs/en/agent-sdk/overview)
- [Claude Code Documentation](https://code.claude.com/docs)
- [Model Configuration（含 ANTHROPIC_BASE_URL）](https://code.claude.com/docs/en/model-config)
- [TypeScript SDK GitHub](https://github.com/anthropics/claude-agent-sdk-typescript)
- [Pricing](https://platform.claude.com/docs/en/about-claude/pricing)

### 参考项目（强烈建议 spike 周抽时间研究）
| 项目 | 类型 | 价值 |
|---|---|---|
| Happy (happy.engineering) | Claude Code 包装客户端 | 思路最贴近本方案 |
| OpenCode | Claude Code 开源仿品 | UI 完整度高 |
| Continue.dev | IDE 插件 + 桌面 | 多 provider 架构 |
| Cline | VS Code 插件 | Agent loop 实现参考 |

---

## 10. 修订记录

| 日期 | 版本 | 修订人 | 内容 |
|---|---|---|---|
| 2026-05-09 | v0 | Chentao + Claude | 初稿，列待讨论问题 |
| 2026-05-09 | v1 | Chentao + Claude | 16 项决策对齐完成，固化为最终版，待评审立项 |