vscode-reference

# Claude Code Official Source — Golden Reference Claude Code CLI 和 VS Code extension 共享**同一套 JS 代码**（`@anthropic-ai/claude-code` npm 包）。这是 CloseCrab 的 golden source。CloseCrab 的 IPC、stream 处理、控制流应尽可能对齐官方实现。 ## Architecture ``` Claude API (云端模型) ↑ Claude Code Core (JS 核心库) @anthropic-ai/claude-code ↑ ┌───────────────┼───────────────┐ │ │ │ Terminal UI VS Code UI socketpair IPC (同进程,无IPC) (同代码+UI层) (--input-fd/--output-fd) 你敲 claude VS Code 插件 ↑ CloseCrab Bot (Discord/飞书 UI) ``` 三者都是同一个 JS 核心库的不同前端。Terminal 是同进程直接调用，VS Code 和 CloseCrab 是子进程模式通过 socketpair 通信。 ## Code Locations ### 1. CLI npm 包 (Golden Source — 总是最新) ```bash # 实际文件位置（跟随 nvm 路径） GOLDEN_JS=$(dirname $(readlink -f $(which claude)))/cli.js # 或直接 ~/.nvm/versions/node/v20.20.0/lib/node_modules/@anthropic-ai/claude-code/cli.js ``` - 安装/更新: `npm install -g @anthropic-ai/claude-code`（或 `deploy.sh --npm`） - 查版本: `claude --version` - **不需要 VS Code。CLI 就是最新代码。** ### 2. VS Code Extension (可能过时，仅供参考) ```bash ls -d ~/.vscode/extensions/anthropic.claude-code-* | sort -V | tail -1 ``` - 需要在 VS Code 界面手动点 Update，版本可能落后 CLI ### 3. GitHub / npm - Repo: `github.com/anthropics/claude-code` - npm: `npmjs.com/package/@anthropic-ai/claude-code` - Releases: `gh release list -R anthropics/claude-code --limit 10` ## Workflow: Check for Updates ### 1. Version Comparison ```bash # 当前安装的 CLI 版本 claude --version # npm 上最新版本 npm info @anthropic-ai/claude-code version # 最近 5 个 release gh release list -R anthropics/claude-code --limit 5 ``` ### 2. Changelog Review ```bash # 查看特定 release 的更新内容 gh release view -R anthropics/claude-code <TAG> # 最近 10 个版本号 npm info @anthropic-ai/claude-code versions --json | python3 -c "import json,sys; v=json.load(sys.stdin); print('\n'.join(v[-10:]))" ``` ### 3. Diff Key Patterns 用 golden source 对比 CloseCrab 实现： ```bash GOLDEN_JS=$(dirname $(readlink -f $(which claude)))/cli.js ``` | Area | grep pattern | CloseCrab File | |------|-------------|----------------| | IPC / socketpair | `input-fd\|output-fd` | `workers/claude_code.py` | | Stream JSON | `readMessages\|parseJSON` | `workers/claude_code.py` | | control_request | `control_request\|control_response` | `_reader_loop()` | | Result handling | `"result"\|session_id` | `send()` | | Compaction | `compact\|compaction\|contextTokenThreshold` | N/A (CLI-level) | | Background tasks | `run_in_background\|task_notification` | `_handle_background_event()` | | Process lifecycle | `spawn\|kill\|terminate\|SIGTERM` | `start()` / `stop()` | | keep_alive | `keep_alive` | `_reader_loop()` | ## Reverse Engineering Minified JS cli.js 是 minified 的（变量名被 mangle），但字符串字面量保留原文。 ### Search Techniques ```bash GOLDEN_JS=$(dirname $(readlink -f $(which claude)))/cli.js # 搜索特定模式（字符串字面量不会被 mangle） grep -oP '.{0,200}control_request.{0,200}' "$GOLDEN_JS" | head -5 grep -oP '.{0,200}keep_alive.{0,200}' "$GOLDEN_JS" | head -5 # 扩大上下文理解逻辑 grep -oP '.{0,500}PATTERN.{0,500}' "$GOLDEN_JS" | head -3 ``` ### Known Patterns (from reverse engineering) - **Stream reader**: Async iterable class, line-delimited JSON from socket - **Event routing**: `readMessages()` routes by event type - **Control handler**: Immediate at reader level, never enqueued - **Result consumer**: First `result` event = end of turn, no `system:init` check - **Compaction**: Default `contextTokenThreshold` = 100K (JZ7=1e5), configurable via `autoCompactWindow` ## CloseCrab Alignment Checklist - [ ] **control_request** handled at reader level (not enqueued) - [ ] **keep_alive** silently consumed at reader level - [ ] **control_cancel_request** logged and consumed at reader level - [ ] **Result handling** does NOT depend on `system:init` - [ ] **Graceful stop** uses SIGTERM before SIGKILL - [ ] **Background events** only handle `task_notification` and `result` - [ ] **No polling/draining** — continuous reader loop with asyncio.Queue ## Key Lessons Learned 1. **不检查 `system:init`**。Claude CLI 可能合并 background task 和 user message 到一轮，只发一个 `result`。检查 `system:init` 会导致 stall。 2. **Control messages 永不入队**。Reader level 立即处理，因为 CLI BLOCKS 等 `control_response`。入队 = 死锁。 3. **不需要 buffer polling**。连续 async reader loop，事件路由到 queue（active）或 background handler（idle）。 4. **Line-delimited JSON**。每行一个完整 JSON。注意不完整行需要 buffer 到换行符。