mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-16 13:25:51 +00:00
Compare commits
25 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
73e54d4bbc | ||
|
|
2fdfb844cb | ||
|
|
4230f0fff1 | ||
|
|
7fe448d9e9 | ||
|
|
aa06cea904 | ||
|
|
c43efecbab | ||
|
|
cb4a6e76cf | ||
|
|
f7f69b759c | ||
|
|
771e3dbcf0 | ||
|
|
e3c0699f5b | ||
|
|
e8759f3402 | ||
|
|
958ac3a0d5 | ||
|
|
5895362178 | ||
|
|
8cfe9b6dc3 | ||
|
|
12f5aedf99 | ||
|
|
c7efac6b8d | ||
|
|
2f150d3ecd | ||
|
|
68c7ebb242 | ||
|
|
9e299a7208 | ||
|
|
941bcbd240 | ||
|
|
fd66ddc45f | ||
|
|
5c107e5f8c | ||
|
|
c4e9efb7a8 | ||
|
|
26ddbda849 | ||
|
|
5dc4d8f8a2 |
File diff suppressed because it is too large
Load Diff
225
docs/features/background-agent-selector.md
Normal file
225
docs/features/background-agent-selector.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Background Agent Selector — 底部统一后台 Agent 切换器
|
||||
|
||||
> Feature Flag: 无（直接启用）
|
||||
> 实现状态：完整可用
|
||||
> 依赖：`viewingAgentTaskId` / `enterTeammateView` / `exitTeammateView` 已有机制
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
Background Agent Selector 是渲染在 PromptInput 下方的常驻状态条，列出当前所有 **backgrounded 的 local_agent 任务**（包括 `/fork` 派生的 fork agent 和 Task/AgentTool 调用 `run_in_background: true` 派生的子 agent）。用户可以用 ↑/↓ 方向键在 `main` 和各 agent 之间切换焦点，按 Enter 把 REPL 主视图替换为所选 agent 的实时 transcript，再按 Enter 选中 `main` 即可回到主对话。
|
||||
|
||||
整个机制完全复用官方已有的 teammate transcript 查看基础设施，不引入新的视图层 / 数据流，仅新增一条 footer pill 类型。
|
||||
|
||||
### 核心特性
|
||||
|
||||
- **统一入口**：`/fork`、Task 派生的 subagent、所有 `run_in_background: true` 的 agent 都在同一栏显示
|
||||
- **就地切换**：prompt 为空时按 ↓ 溢出进入底部 selector，↑↓ 选中某行，Enter 即切主视图
|
||||
- **实时状态**：每行显示 agent 类型 + 描述 + 运行时长 + 已消耗 token；running 时圆点为绿色
|
||||
- **Keep-alive 视图**：agent 完成后在 `evictAfter` grace 窗口内保留一段时间，用户可回看
|
||||
- **零界面侵入**：tasks 数为 0 时 selector 完全不渲染，不占屏幕高度
|
||||
- **与旧 Dialog 共存**：Shift+↓ 打开的 `BackgroundTasksDialog` 原有行为保留，selector 只作为展示 + 快捷切换
|
||||
|
||||
## 二、用户交互
|
||||
|
||||
### 触发方式
|
||||
|
||||
有任何 background agent 时，selector 自动出现在 `bypass permissions on` 行下方：
|
||||
|
||||
```
|
||||
claude-code | Opus 4.7 (1M context) | ctx:4%
|
||||
▶▶ bypass permissions on (shift+tab to cycle)
|
||||
|
||||
○ main ↑/↓ to select · Enter to view
|
||||
● Explore Research src/hooks 23s · ↓ 10.9k tokens
|
||||
○ Explore Research src/components 22s · ↓ 9.5k tokens
|
||||
○ Explore Research src/utils 21s · ↓ 13.6k tokens
|
||||
```
|
||||
|
||||
### 键盘路由
|
||||
|
||||
| 位置 / 状态 | 按键 | 行为 |
|
||||
|---|---|---|
|
||||
| PromptInput 非空 | ↑↓ | 光标移动 / 翻历史（不变） |
|
||||
| PromptInput 空 + 历史底部 | ↓ | 焦点下放到 selector，高亮到 `● main` |
|
||||
| Selector 聚焦（`footerSelection === 'bg_agent'`） | ↓ | 高亮下移，-1 → 0 → ... → N-1 |
|
||||
| Selector 聚焦 | ↑ | 高亮上移；在 `main` 再 ↑ → 焦点回 PromptInput |
|
||||
| Selector 聚焦 | Enter | `-1` → `exitTeammateView`；`>=0` → `enterTeammateView(agentId)`。焦点保留在 pill |
|
||||
| Selector 聚焦 | Esc | `footer:clearSelection`，焦点回 PromptInput |
|
||||
|
||||
### 视觉规则
|
||||
|
||||
- `● main` / `● <agent>`：当前被**查看**（viewingAgentTaskId 指向）或被**光标聚焦**（pill focused 时以光标为准）的一行
|
||||
- running 状态的 agent：圆点渲染为 `success` 色（绿色），与 `BackgroundTasksDialog` 状态语义对齐
|
||||
- 右上角 hint 随状态变化：
|
||||
- pill 聚焦：`↑/↓ to select · Enter to view`
|
||||
- 已选中 running agent：`shift+↓ to manage · x to stop`
|
||||
- 已选中 terminal agent：`shift+↓ to manage · x to clear`
|
||||
- 未选中任何 agent：`shift+↓ to manage background agents`
|
||||
|
||||
## 三、实现架构
|
||||
|
||||
### 3.1 数据层：`useBackgroundAgentTasks`
|
||||
|
||||
文件：`src/hooks/useBackgroundAgentTasks.ts`
|
||||
|
||||
封装对 `useAppState(s => s.tasks)` 的过滤：
|
||||
|
||||
```ts
|
||||
export function useBackgroundAgentTasks(): LocalAgentTaskState[] {
|
||||
const tasks = useAppState(s => s.tasks)
|
||||
return useMemo(() => {
|
||||
const now = Date.now()
|
||||
return Object.values(tasks)
|
||||
.filter(isLocalAgentTask)
|
||||
.filter(t => t.agentType !== 'main-session')
|
||||
.filter(t => t.isBackgrounded !== false)
|
||||
.filter(t => t.evictAfter === undefined || t.evictAfter > now)
|
||||
.sort((a, b) => a.startTime - b.startTime)
|
||||
}, [tasks])
|
||||
}
|
||||
```
|
||||
|
||||
`/fork` 和 `AgentTool` 的 `run_in_background: true` 底层都走 `registerAsyncAgent → runAsyncAgentLifecycle`，最终写入同一个 `appState.tasks` Map；此 hook 是唯一数据源，Selector 和 PromptInput 的 `bgAgentList` 都消费它。
|
||||
|
||||
### 3.2 状态层：新增两个字段
|
||||
|
||||
文件：`src/state/AppStateStore.ts`
|
||||
|
||||
```ts
|
||||
export type FooterItem =
|
||||
| 'tasks' | 'tmux' | 'bagel' | 'teams' | 'bridge' | 'companion'
|
||||
| 'bg_agent' // ← 新增
|
||||
|
||||
export type AppState = DeepImmutable<{
|
||||
// ...
|
||||
selectedBgAgentIndex: number // -1 = main, 0..N-1 = 选中的 agent
|
||||
}>
|
||||
```
|
||||
|
||||
- `'bg_agent'` 作为 `FooterItem` 加入 footer pill 体系，享受既有的 `footer:up` / `footer:down` / `footer:openSelected` keybinding 路由
|
||||
- `selectedBgAgentIndex` 记录 selector 的光标位置，与 `viewingAgentTaskId`（"正在看什么"）独立；它不可从 `viewingAgentTaskId` 派生——Enter 后光标留在 pill 继续导航，查看目标才变
|
||||
|
||||
### 3.3 键盘路由：PromptInput footer pill 分支
|
||||
|
||||
文件：`src/components/PromptInput/PromptInput.tsx`
|
||||
|
||||
1. **`bg_agent` 进入 footerItems[0]**：保证 prompt ↓ 溢出时（`handleHistoryDown` → `selectFooterItem(footerItems[0])`）直接进入 selector，而不是 `tasks` 等其他 pill
|
||||
2. **`footer:up` 分支**：`bgAgentSelected` 时 `selectedBgAgentIndex > -1` 则递减；在 -1 → `selectFooterItem(null)` 退出 pill
|
||||
3. **`footer:down` 分支**：`selectedBgAgentIndex < bgAgentList.length - 1` 则递增，到底 clamp
|
||||
4. **`footer:openSelected` 分支**：index === -1 → `exitTeammateView`；否则 `enterTeammateView(bgAgentList[i].agentId)`。**不清理 pill 焦点**，光标留在 selector 上继续导航
|
||||
5. **`selectFooterItem('bg_agent')`**：入 pill 时重置 `selectedBgAgentIndex = -1`（光标落到 `main`）
|
||||
|
||||
### 3.4 渲染层：`BackgroundAgentSelector`
|
||||
|
||||
文件：`src/components/tasks/BackgroundAgentSelector.tsx`
|
||||
|
||||
纯展示组件，不订阅键盘：
|
||||
|
||||
```tsx
|
||||
const tasks = useBackgroundAgentTasks()
|
||||
const viewingId = useAppState(s => s.viewingAgentTaskId)
|
||||
const footerSelection = useAppState(s => s.footerSelection)
|
||||
const selectedBgIndex = useAppState(s => s.selectedBgAgentIndex)
|
||||
|
||||
if (tasks.length === 0) return null
|
||||
|
||||
const pillFocused = footerSelection === 'bg_agent'
|
||||
const highlightedId = pillFocused
|
||||
? (selectedBgIndex === -1 ? null : tasks[selectedBgIndex]?.agentId ?? null)
|
||||
: (viewingId ?? null)
|
||||
```
|
||||
|
||||
**高亮派生规则**：pill 聚焦 → 跟 `selectedBgAgentIndex`；未聚焦 → 镜像 `viewingAgentTaskId`。这样当用户通过 Shift+↓ Dialog 或 `enterTeammateView` 其它途径切换视图时，selector 也会正确反映。
|
||||
|
||||
### 3.5 主视图切换：复用 `viewingAgentTaskId`
|
||||
|
||||
REPL.tsx 主体仍复用原有查看逻辑：
|
||||
|
||||
```ts
|
||||
const viewedTask = viewingAgentTaskId ? tasks[viewingAgentTaskId] : undefined
|
||||
const viewedAgentTask = ... (isLocalAgentTask(viewedTask) ? viewedTask : undefined)
|
||||
const displayedMessages = viewedAgentTask ? displayedAgentMessages : messages
|
||||
```
|
||||
|
||||
当 `enterTeammateView(agentId)` 把 `viewingAgentTaskId` 设成某个 local_agent 的 id：
|
||||
|
||||
- `viewedAgentTask` 解析成该 agent
|
||||
- `displayedMessages` 切换到 agent 的 messages
|
||||
- 消息列表、spinner、unseen divider 等一整套组件自动用 agent transcript 重渲染
|
||||
- 主对话流被"暂停"（并非销毁，回到 `main` 时仍在原处）
|
||||
|
||||
`enterTeammateView` 同步负责：设 `retain: true` 阻止 eviction、清 `evictAfter`、触发 disk bootstrap 从 `agent-<id>.jsonl` 加载完整 transcript 到 `task.messages`。
|
||||
|
||||
#### Fork agent prompt 归一化
|
||||
|
||||
`/fork` agent 的 transcript 和普通 subagent 不同：它继承 main agent 的上下文，真实初始消息形态是：
|
||||
|
||||
```text
|
||||
...parent messages
|
||||
assistant([...tool_use])
|
||||
user([tool_result..., text("<fork-boilerplate>...Your directive: <prompt>")])
|
||||
...fork live messages
|
||||
```
|
||||
|
||||
这里的 prompt 文本混在 `[tool_result..., text]` 多 block user message 里。消息渲染管线会优先把这条 user message 当作 tool-result plumbing 来处理，导致 `<fork-boilerplate>` 里的用户 prompt 不稳定可见。为保证切换到 fork agent 时总能看到用户发起的 fork prompt，REPL.tsx 对 fork 视图做一次展示层归一化：
|
||||
|
||||
1. 仅当 `viewedAgentTask.agentType === 'fork'` 时启用，不影响普通 Explore / Task subagent。
|
||||
2. 从原始 messages 中识别包含 `<fork-boilerplate>` 的 carrier message。
|
||||
3. 剥离 carrier message 里的 boilerplate text block，但保留 `tool_result` blocks，避免破坏父 assistant `tool_use` 的承接关系。
|
||||
4. 强制插入一条独立 `createUserMessage({ content: viewedAgentTask.prompt })` 作为可见用户 prompt。
|
||||
5. 插入位置优先为 boilerplate carrier 后；如果 sidechain bootstrap 还没读到 carrier，则插到最后一条 inherited `assistant tool_use` 后面，确保 prompt 接在 main 上下文之后，而不是跑到视图顶部。
|
||||
|
||||
这个归一化只影响 UI 展示用的 `displayedAgentMessages`，不回写 `task.messages`，也不改变发送给模型的 fork transcript。
|
||||
|
||||
### 3.6 生命周期
|
||||
|
||||
完全复用官方既有机制：
|
||||
|
||||
- **运行中**：`isBackgroundTask()` 谓词为真，selector 列出
|
||||
- **完成 / 失败 / 中止**：`completeAgentTask` / `failAgentTask` / `killAsyncAgent` 设 `status` 为 terminal
|
||||
- **回访后退出**：`exitTeammateView` 调 `release(task)`——清 `retain`、清 `messages`、terminal 状态下设 `evictAfter = now + PANEL_GRACE_MS (30s)`
|
||||
- **evictAfter 过期**：`useBackgroundAgentTasks` 过滤时自然剔除，selector 行消失
|
||||
- **手动清除**：`stopOrDismissAgent(taskId)` 设 `evictAfter = 0`，立即消失
|
||||
|
||||
## 四、设计决策
|
||||
|
||||
1. **数据源单一**：`useBackgroundAgentTasks` 是唯一过滤点，PromptInput 也复用，避免过滤条件散落
|
||||
2. **pill 聚焦保留**：Enter 切视图后不松焦，让 ↑↓ 连续导航，贴近官方体验
|
||||
3. **`bg_agent` 放 footerItems[0]**：确保 ↓ 溢出直接进入 selector 而非其它 pill
|
||||
4. **selector 不订阅键盘**：所有按键路由集中在 PromptInput 的 `footer:*` 分支，避免 selector 组件和 PromptInput 双重 `useInput` 的冲突
|
||||
5. **`selectedBgAgentIndex` 存 AppState 而非局部 state**：selector 和 PromptInput 分别在两棵不同子树，需要全局字段协调；该值不能从 `viewingAgentTaskId` 派生
|
||||
6. **与 `BackgroundTasksDialog` 共存**：Shift+↓ 行为完全不变，selector 是补充快捷入口；Dialog 仍管 shell / workflow / monitor_mcp 等 selector 不显示的 task 类型
|
||||
7. **fork prompt 展示层兜底**：fork prompt 不依赖 boilerplate 自身渲染，统一在 `displayedAgentMessages` 中合成独立用户消息；普通 subagent 不走该分支，避免 prompt 重复
|
||||
|
||||
## 五、关键 API 复用
|
||||
|
||||
| 官方已有能力 | selector 如何使用 |
|
||||
|---|---|
|
||||
| `AppState.tasks` | 单一数据源，无需 file watcher / output JSONL 订阅 |
|
||||
| `registerAsyncAgent` | `/fork` 和 AgentTool 共用，selector 不区分来源 |
|
||||
| `enterTeammateView(id)` | Enter 时调用，负责 retain + disk bootstrap |
|
||||
| `exitTeammateView` | Enter 选中 `main` 时调用 |
|
||||
| `release(task)` + `PANEL_GRACE_MS` | 30s keep-alive，selector 自动生效 |
|
||||
| `useElapsedTime` | 每行时长显示，非 running 自动停 interval |
|
||||
| `formatTokens` (`utils/format.ts`) | token 数 1k 缩写 |
|
||||
| `footer:up` / `footer:down` / `footer:openSelected` keybinding | 键盘路由复用 Footer context |
|
||||
|
||||
## 六、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/hooks/useBackgroundAgentTasks.ts` | 数据过滤 hook（backgrounded local_agent + evictAfter 过滤 + startTime 排序） |
|
||||
| `src/components/tasks/BackgroundAgentSelector.tsx` | 底部 selector UI，纯展示 |
|
||||
| `src/components/PromptInput/PromptInput.tsx` | 新增 `'bg_agent'` footer pill + 对应的 `footer:up/down/openSelected` 分支 |
|
||||
| `src/state/AppStateStore.ts` | `FooterItem` 加 `'bg_agent'`；新增 `selectedBgAgentIndex` 字段 |
|
||||
| `src/main.tsx` | `getDefaultAppState` 同步初始化 `selectedBgAgentIndex: -1` |
|
||||
| `src/screens/REPL.tsx` | 在 PromptInput + SessionBackgroundHint 之后挂载 `<BackgroundAgentSelector />`；切换 agent 主视图；对 fork transcript 做 prompt 归一化 |
|
||||
| `src/components/messages/AssistantToolUseMessage.tsx` | 新增 `defaultCollapsed?: boolean` prop，为后续详情视图默认折叠工具块预留 |
|
||||
| `src/components/messages/UserTextMessage.tsx` | 识别 `<fork-boilerplate>`，交给 fork 专用 renderer 处理 |
|
||||
| `src/components/messages/UserForkBoilerplateMessage.tsx` | 将 fork boilerplate text 折叠为纯用户 prompt；作为 transcript 中原位渲染的兼容路径 |
|
||||
|
||||
## 七、已知限制
|
||||
|
||||
- `Date.now()` 在 `useBackgroundAgentTasks` 的 useMemo 里冻结于 `[tasks]` 触发时：若长时间没有新 task 变更事件，某个 terminal agent 的 grace 期过期后不会立即从 selector 消失，要等下一次 tasks 变化才刷新。在典型使用（主对话一直在产生消息）下感知不到，暂不额外加 interval。
|
||||
- Selector 当前不处理 Shell Task / Workflow / Monitor MCP 等类型——这些仍走 `BackgroundTasksDialog`（Shift+↓）管理。
|
||||
- `AssistantToolUseMessage` 的 `defaultCollapsed` prop 目前无调用方传值，保留作为后续"agent 详情视图内工具块默认折叠"扩展点。
|
||||
275
docs/features/status-line.mdx
Normal file
275
docs/features/status-line.mdx
Normal file
@@ -0,0 +1,275 @@
|
||||
---
|
||||
title: "StatusLine 底部状态栏 - 自定义 shell 渲染管线"
|
||||
description: "从源码角度解析 Claude Code 底部状态栏：自定义 shell 脚本 + JSON stdin 协议、三种触发源（event / settings / time）、debounce + abort、信任与 hook 开关、以及本仓库 refreshInterval 缺失修复。"
|
||||
keywords: ["statusLine", "状态栏", "自定义提示符", "refreshInterval", "Hooks"]
|
||||
---
|
||||
|
||||
{/* 本章目标：完整讲清 StatusLine 的渲染管线、触发模型、协议契约与安全网关，并记录本仓库相对官方版本的已知缺口与修复 */}
|
||||
|
||||
## 概述
|
||||
|
||||
StatusLine 是 Claude Code REPL 底部显示的一行自定义文本，由**用户提供的 shell 命令**渲染。主进程把运行时状态（模型、工作目录、token、限流、会话元数据等）打包成 JSON 通过 stdin 喂给脚本，脚本在 stdout 输出一行字符串，Ink 侧以 ANSI 转义渲染到 footer。
|
||||
|
||||
核心设计哲学：**语言无关 + 进程隔离 + Unix 管道**。用户可用 bash / python / node / 任意语言写脚本；脚本崩溃不影响主进程；输入输出都是纯文本，可以离线测试（`echo '{...}' | ./script.sh`）。
|
||||
|
||||
## 配置
|
||||
|
||||
`~/.claude/settings.json` 里添加 `statusLine` 字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"statusLine": {
|
||||
"type": "command",
|
||||
"command": "bash ~/.claude/statusline-command.sh",
|
||||
"refreshInterval": 1,
|
||||
"padding": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 作用 |
|
||||
|------|------|------|
|
||||
| `type` | `"command"` | 目前仅支持 command 型 |
|
||||
| `command` | `string` | shell 命令字符串；主进程用系统 shell 解释执行 |
|
||||
| `refreshInterval` | `number` (秒) | 定时刷新周期；缺省/0 表示不定时刷新 |
|
||||
| `padding` | `number` | 左右 padding，单位为 Ink cell |
|
||||
|
||||
Schema 定义在 `src/utils/settings/types.ts:550`（`statusLine` Zod object）。
|
||||
|
||||
## 渲染管线（整体图）
|
||||
|
||||
```
|
||||
┌─────────────────────── Ink 侧 ───────────────────────┐ ┌──────── 用户侧 ────────┐
|
||||
│ │ │ │
|
||||
│ buildStatusLineCommandInput() ──┐ │ │ ~/.claude/ │
|
||||
│ 收集运行时状态 │ │ │ statusline-*.sh │
|
||||
│ ▼ │ │ │
|
||||
│ executeStatusLineCommand() ─── JSON via stdin ────────────► jq '.model...' │
|
||||
│ execCommandHook() 拉起 shell │ │ 计算、格式化 │
|
||||
│ ▲ │ │ │
|
||||
│ stdout ◄──────────────────── 一行文本 ──────────────── printf '...' │
|
||||
│ │ │ │ │
|
||||
│ setAppState({ statusLineText }) ─┘ │ └────────────────────────┘
|
||||
│ zustand 存字段，组件 memo 订阅 │
|
||||
│ │
|
||||
│ <StatusLine /> → <Text><Ansi>{text}</Ansi></Text> │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Input 协议：主进程 → 脚本
|
||||
|
||||
`buildStatusLineCommandInput`（`src/components/StatusLine.tsx:53`）构造的 JSON 对象字段如下，**这是脚本可以 `jq` 读取的全部内容**：
|
||||
|
||||
| 字段 | 来源 | 备注 |
|
||||
|------|------|------|
|
||||
| `session_id` | `getSessionId()` | UUID，用于脚本侧 per-session 状态隔离 |
|
||||
| `session_name` | `getCurrentSessionTitle(sessionId)` | 用户命名的会话标题（可选） |
|
||||
| `model.id` / `model.display_name` | `getRuntimeMainLoopModel()` | 运行时真实模型（经 permission mode 降级/200k 升级） |
|
||||
| `workspace.current_dir` / `project_dir` / `added_dirs` | `getCwd()` / `getOriginalCwd()` / permission context | current_dir 随 `cd` 变化 |
|
||||
| `version` | `MACRO.VERSION` | 构建注入，如 `2.1.888` |
|
||||
| `output_style.name` | `settings.outputStyle` | 缺省 `DEFAULT_OUTPUT_STYLE_NAME` |
|
||||
| `cost.total_cost_usd` / `total_duration_ms` / `total_api_duration_ms` / `total_lines_added` / `total_lines_removed` | `cost-tracker.js` 聚合 | 会话累计 |
|
||||
| `context_window.total_input_tokens` / `total_output_tokens` | 同上 | 累计 token |
|
||||
| `context_window.context_window_size` | `getContextWindowForModel()` | 模型上下文上限 |
|
||||
| `context_window.current_usage` | `getCurrentUsage(messages)` | **最新一次 assistant message 的 usage**；含 `input_tokens` / `cache_creation_input_tokens` / `cache_read_input_tokens` / `output_tokens` |
|
||||
| `context_window.used_percentage` / `remaining_percentage` | `calculateContextPercentages()` | 0-100 浮点 |
|
||||
| `exceeds_200k_tokens` | 检查最近 assistant message | 用于 1M 上下文模型的展示 |
|
||||
| `rate_limits.five_hour` / `seven_day` | `getRawUtilization()` | `{ used_percentage, resets_at }`，来自 Claude.ai 限流 API |
|
||||
| `vim.mode` | 启用 vim 模式时 | `INSERT` / `NORMAL` / ... |
|
||||
| `agent.name` | 主线程 agent 类型 | 子 agent fork 时非空 |
|
||||
| `remote.session_id` | Bridge / Remote Control 模式 | 远程会话 |
|
||||
| `worktree` | 当前 worktree 元信息 | `name` / `path` / `branch` / `original_cwd` / `original_branch` |
|
||||
|
||||
类型签名目前在 `src/types/statusLine.ts` 是 `any` 的 stub（反编译残留），实际字段以上表为准。
|
||||
|
||||
## Output 协议：脚本 → 主进程
|
||||
|
||||
`executeStatusLineCommand`（`src/utils/hooks.ts:4752`）对脚本 stdout 做如下处理：
|
||||
|
||||
1. `trim()` 首尾空白
|
||||
2. 按 `\n` 拆行，每行再 `trim()`
|
||||
3. 空行丢弃，剩余用 `\n` 重新拼接
|
||||
|
||||
多行输出会被**保留为多行**（Ink 渲染时 `<Text>` 允许换行），但设计推荐**单行**——多行会挤占 REPL 高度，fullscreen 模式下可能挤掉 ScrollBox 行。
|
||||
|
||||
状态码约定：
|
||||
- `exit 0` + 有 stdout → 显示
|
||||
- `exit 0` + 空 stdout → 清空 statusLine（显示为空）
|
||||
- 非 0 → 忽略，保留上次内容；`logResult=true` 时 warn 级日志
|
||||
- 超时（默认 5000ms） → 忽略
|
||||
- 被 AbortController 取消 → 忽略
|
||||
|
||||
ANSI 颜色可用，Ink 通过 `<Ansi>{text}</Ansi>` 组件解析 SGR 序列。
|
||||
|
||||
## 三种触发源
|
||||
|
||||
StatusLine 的重算由**三类事件**驱动，全部经同一个 debounce 队列：
|
||||
|
||||
### 1. Event-driven（`src/components/StatusLine.tsx:275`）
|
||||
|
||||
监听这些状态变化，触发 `scheduleUpdate()`：
|
||||
|
||||
- `lastAssistantMessageId` — 新助手回复出现
|
||||
- `permissionMode` — `/mode` 切换权限模式
|
||||
- `vimMode` — vim insert/normal 切换
|
||||
- `mainLoopModel` — `/model` 切换
|
||||
|
||||
### 2. Settings-driven（`src/components/StatusLine.tsx:294`）
|
||||
|
||||
`settings.statusLine.command` 字符串变化时（热重载 settings.json），标记下一次结果 log 并立即 `doUpdate()`。
|
||||
|
||||
### 3. Time-driven（`src/components/StatusLine.tsx:292`，本仓库补丁）
|
||||
|
||||
读取 `settings.statusLine.refreshInterval`（秒），`setInterval` 每到点走一次 `scheduleUpdate()`。配置为 0 或缺省时不启定时器（零开销）。
|
||||
|
||||
> **本仓库历史缺口**：反编译出的 `StatusLine.tsx` 最初没有 Time-driven 触发路径，`refreshInterval` 字段也不在 Zod schema 里。导致脚本里 TTL 倒计时、时钟类动态内容不会秒刷，只有助手回复出现时才重算。已在 2026-05-06 补齐，细节见下方"已知缺口与修复"。
|
||||
|
||||
## Debounce + Abort
|
||||
|
||||
三种触发源都走 `scheduleUpdate`（`src/components/StatusLine.tsx:259`）：
|
||||
|
||||
```
|
||||
scheduleUpdate() → setTimeout(300ms) → doUpdate()
|
||||
│
|
||||
└─ 再次 schedule 会 clearTimeout 前次
|
||||
```
|
||||
|
||||
300ms debounce 合并抖动事件（例如短时间连续切 vim/permission）。
|
||||
|
||||
`doUpdate()` 里：
|
||||
|
||||
```
|
||||
abortControllerRef.current?.abort() // 取消上一次 in-flight shell
|
||||
controller = new AbortController()
|
||||
executeStatusLineCommand(..., controller.signal, ...)
|
||||
```
|
||||
|
||||
**单飞（single-flight）语义**：任何新触发都会 abort 上一次未完成的 shell 调用，保证同一时刻最多一个子进程。这对 `refreshInterval: 1` 尤其关键——若脚本执行 > 1 秒，新 tick 到来时老进程被 kill，不会堆积。
|
||||
|
||||
## 安全网关
|
||||
|
||||
`executeStatusLineCommand`（`src/utils/hooks.ts:4752`）在执行前有**三层拦截**：
|
||||
|
||||
1. `shouldDisableAllHooksIncludingManaged()` → managed settings 全局禁用 hooks 时直接返回
|
||||
2. `shouldSkipHookDueToTrust()` → **工作区未接受信任对话框时跳过**，避免打开未知仓库时执行任意 shell 命令（RCE 防护）
|
||||
3. `shouldAllowManagedHooksOnly()` → 非 managed settings 禁用 hooks 但 managed 未禁用时，只读取 policySettings 源的 statusLine
|
||||
|
||||
组件侧配合（`src/components/StatusLine.tsx:318`）：未接受 trust 时在通知中心提示 `"statusline skipped · restart to fix"`。
|
||||
|
||||
另外，`statusLineShouldDisplay`（`src/components/StatusLine.tsx:46`）在 **Kairos assistant mode** 下直接返回 false——因为那时 statusline 字段反映的是 REPL/daemon 进程状态，不是 agent 子进程在跑的东西，显示出来会误导用户。
|
||||
|
||||
## 渲染细节
|
||||
|
||||
### memo 隔离
|
||||
|
||||
```tsx
|
||||
export const StatusLine = memo(StatusLineInner)
|
||||
```
|
||||
|
||||
父组件 `PromptInputFooter` 每次 `setMessages` 都 rerender，但 `StatusLine` 的 props 只有 `lastAssistantMessageId` 会变，`memo` 阻断了无意义的重渲染。此前（未 memo 版本）一个 session 内大约 18 次冗余渲染。
|
||||
|
||||
### 订阅粒度
|
||||
|
||||
```tsx
|
||||
const statusLineText = useAppState(s => s.statusLineText)
|
||||
```
|
||||
|
||||
`useAppState` 是选择器订阅，仅在 `statusLineText` 字段变化时触发 rerender；`doUpdate()` 里还做了幂等检查（`prev.statusLineText === text` 则直接返回原 state），**文本不变就不更新 zustand**，连一次 notify 都省掉。
|
||||
|
||||
### Fullscreen 占位
|
||||
|
||||
```tsx
|
||||
{statusLineText ? (
|
||||
<Text dimColor wrap="truncate"><Ansi>{statusLineText}</Ansi></Text>
|
||||
) : isFullscreenEnvEnabled() ? (
|
||||
<Text> </Text> // 占位一行
|
||||
) : null}
|
||||
```
|
||||
|
||||
Fullscreen 模式下 footer `flexShrink:0`，statusline 从 0 行变 1 行会挤掉 ScrollBox 一行内容导致抖动。首次脚本还没返回时，用空格文本占住一行高度，脚本返回后原位替换。
|
||||
|
||||
## 内置 `/statusline` slash command
|
||||
|
||||
`src/commands/statusline.tsx` 定义了一个 **prompt 型 command**，展开成自然语言指令喂给主 Agent：
|
||||
|
||||
```
|
||||
Create an AgentTool with subagent_type "statusline-setup" and the prompt "<user-args>"
|
||||
```
|
||||
|
||||
默认 prompt 是 `"Configure my statusLine from my shell PS1 configuration"`。主 Agent 收到后会调用内置子 agent `statusline-setup`。该子 agent 权限极小：
|
||||
|
||||
- **Tools**: 仅 `Read`、`Edit`
|
||||
- **Allowed paths**: `Read(~/**)`、`Edit(~/.claude/settings.json)`
|
||||
|
||||
也就是说它**不能 Write 新文件、不能跑 Bash**。典型工作是读用户的 shell 配置、读/改 `settings.json`、增量编辑已有的 statusline 脚本。
|
||||
|
||||
## 编写自定义脚本的要点
|
||||
|
||||
1. **脚本必须无状态** — 每次 tick 主进程 fork 一次新 shell，进程内变量不跨调用保留。需要跨 tick 的状态（上次时间戳、上次 token 数）用 `~/.claude/statusline-state/<hash>.state` 文件持久化。
|
||||
2. **按 `session_id` 哈希隔离状态文件** — 多会话同时开着时共享一个 state 文件会串。典型做法：`md5(session_id) | head -c 16` 作为文件名。
|
||||
3. **防御性读取** — state 文件可能损坏/被截断，按行 read + 字段校验（数字字段用 `case "$var" in ''|*[!0-9]*) invalid ;;`）。
|
||||
4. **`refreshInterval` 不等于"脚本秒级调用"** — tick 和事件触发（新消息、模式切换）都走同一 debounce 队列，脚本实际被调用的频率介于"每 N 秒"和"每 N+0.3 秒"之间；且 abort 机制下，上一次没跑完会被 kill。
|
||||
5. **执行时间预算** — 默认 5000ms 超时；为避免 `refreshInterval=1` 时频繁超时，脚本热路径应在 100ms 内完成。重计算（curl、git log 拉取）需缓存。
|
||||
6. **颜色用 ANSI 转义** — 不要依赖 TERM 环境变量；Ink 的 `<Ansi>` 组件独立解析 SGR。
|
||||
7. **不要输出多行** — 单行文本，否则挤占 REPL 布局。
|
||||
8. **处理 `current_usage` 为 null 的情况** — 首次响应之前 `context_window.current_usage` 可能为 null，脚本应有 fallback（如读 state 里上次命中率）。
|
||||
|
||||
### 示例：Cache 命中率 + TTL 倒计时
|
||||
|
||||
本仓库默认安装了一个示例脚本 `~/.claude/statusline-command.sh`（用户侧），输出格式 `<dir> | <model> | ctx:N% | Cache 97% 59:43`：
|
||||
|
||||
- **命中率** = `cache_read / (input + cache_creation + cache_read)`（取自 `current_usage`）
|
||||
- **TTL** 从上次响应倒数 60 分钟，**只在 token signature 变化时重置时间戳**，避免秒级 tick 把 TTL 一直锁在 60:00
|
||||
- **颜色分段** — 命中率 ≥50% 绿 / <50% 灰；TTL 0-20m 绿 / 20-40m 黄 / 40-55m 红 / 最后 5m 闪红 / 过期 `exp` 灰
|
||||
- **Per-session state** — `~/.claude/statusline-state/<md5(session_id)[:16]>.state` 三行（signature、timestamp、hit），读前做 numeric 校验
|
||||
- **Fallback** — `current_usage` 为 null 时读 state 显示上次命中率
|
||||
|
||||
> 该脚本配合 `refreshInterval: 1` 即可秒刷 TTL，前提是 `refreshInterval` 触发路径已实现（见下节）。
|
||||
|
||||
## 已知缺口与修复（本仓库）
|
||||
|
||||
反编译版的 `StatusLine.tsx` 存在一处功能缺口：
|
||||
|
||||
| 项 | 官方 Claude Code | 本仓库原始 | 本仓库现状 |
|
||||
|----|-----------------|-----------|-----------|
|
||||
| `refreshInterval` Zod 字段 | ✅ 有 | ❌ 无 | ✅ 已补 |
|
||||
| Time-driven `setInterval` 触发 | ✅ 有 | ❌ 无 | ✅ 已补 |
|
||||
| Event-driven 触发 | ✅ 有 | ✅ 有 | — |
|
||||
| Settings-driven 触发 | ✅ 有 | ✅ 有 | — |
|
||||
| Debounce + Abort | ✅ 有 | ✅ 有 | — |
|
||||
| Trust 网关 | ✅ 有 | ✅ 有 | — |
|
||||
|
||||
修复（2026-05-06）：
|
||||
|
||||
**1. `src/utils/settings/types.ts:554`** — statusLine schema 新增 `refreshInterval: z.number().optional()`，让字段进入类型系统而非被当未知键忽略。
|
||||
|
||||
**2. `src/components/StatusLine.tsx:292`** — 新增 Time-driven useEffect：
|
||||
|
||||
```tsx
|
||||
const refreshIntervalMs = (settings?.statusLine?.refreshInterval ?? 0) * 1000;
|
||||
useEffect(() => {
|
||||
if (refreshIntervalMs <= 0) return;
|
||||
const id = setInterval(() => scheduleUpdate(), refreshIntervalMs);
|
||||
return () => clearInterval(id);
|
||||
}, [refreshIntervalMs, scheduleUpdate]);
|
||||
```
|
||||
|
||||
关键点：
|
||||
- 走 `scheduleUpdate`（非 `doUpdate`）复用 300ms debounce，interval + event 双触发不会双跑
|
||||
- `refreshIntervalMs <= 0` 时不启定时器，对未启用该字段的用户零开销
|
||||
- 依赖数组含 `refreshIntervalMs`，settings 热重载会自动清理旧 interval 重建新的
|
||||
|
||||
**静默失效特征**：修复前 settings.json 写 `refreshInterval: 1` 无任何报错——JSON 解析通过，Zod schema 默认 strip 多余字段，官方文档又说支持这个字段，用户很容易以为生效了而没意识到 TTL/时钟类输出根本没秒刷。这是反编译版本的典型"文档与实现不一致"。
|
||||
|
||||
## 相关源码
|
||||
|
||||
| 文件 | 作用 |
|
||||
|------|------|
|
||||
| `src/components/StatusLine.tsx` | UI 组件、触发逻辑、buildStatusLineCommandInput |
|
||||
| `src/utils/hooks.ts:4752` | `executeStatusLineCommand`：shell 执行、输出处理、安全网关 |
|
||||
| `src/utils/settings/types.ts:550` | `statusLine` Zod schema |
|
||||
| `src/types/statusLine.ts` | `StatusLineCommandInput` 类型（当前为 stub） |
|
||||
| `src/commands/statusline.tsx` | `/statusline` slash command 定义 |
|
||||
| `src/state/AppStateStore.ts:95` | `statusLineText` 字段声明 |
|
||||
| `src/components/PromptInput/PromptInputFooter.tsx:159` | StatusLine 组件挂载点 |
|
||||
152
learn/LEARN.md
152
learn/LEARN.md
@@ -1,152 +0,0 @@
|
||||
# Claude Code 源码学习路线
|
||||
|
||||
> 基于反编译版 Claude Code CLI (v2.1.888) 的源码学习跟踪
|
||||
>
|
||||
> 各阶段详细笔记见同目录下的 `phase-*.md` 文件
|
||||
|
||||
## 第一阶段：启动流程（入口链路） ✅
|
||||
|
||||
详细笔记：[phase-1-startup-flow.md](phase-1-startup-flow.md)
|
||||
|
||||
理解程序从命令行启动到用户看到交互界面的完整路径。
|
||||
|
||||
- [x] `src/entrypoints/cli.tsx` — 真正入口，polyfill 注入 + 快速路径分发
|
||||
- [x] 全局 polyfill：`feature()` 永远返回 false、`MACRO` 全局对象、`BUILD_*` 常量
|
||||
- [x] 快速路径设计：按开销从低到高检查，能早返回就早返回
|
||||
- [x] 动态 import 模式：`await import()` 延迟加载，减少启动时间
|
||||
- [x] 最终出口：`import("../main.jsx")` → `cliMain()`
|
||||
- [x] `src/main.tsx` — Commander.js CLI 定义，重型初始化（4683 行）
|
||||
- [x] 三段式结构：辅助函数(1-584) → main()(585-856) → run()(884-4683)
|
||||
- [x] side-effect import：profileCheckpoint、startMdmRawRead、startKeychainPrefetch 并行预加载
|
||||
- [x] preAction 钩子：MDM 等待、init()、迁移、远程设置
|
||||
- [x] Commander 参数定义：40+ CLI 选项
|
||||
- [x] action handler（2800 行）：参数解析 → 服务初始化 → showSetupScreens → launchRepl()
|
||||
- [x] --print 分支走 print.ts；交互分支走 launchRepl()（7 个场景分支）
|
||||
- [x] 子命令注册：mcp/auth/plugin/doctor/update/install 等
|
||||
- [x] `src/replLauncher.tsx` — 桥梁（22 行），组合 `<App>` + `<REPL>` 渲染到终端
|
||||
- [x] `src/screens/REPL.tsx` — 交互式 REPL 界面（5009 行）
|
||||
- [x] Props：commands、tools、messages、systemPrompt、thinkingConfig 等
|
||||
- [x] 50+ 状态：messages、inputValue、screen、streamingText、queryGuard 等
|
||||
- [x] 核心数据流：onSubmit → handlePromptSubmit → onQuery → onQueryImpl → query() → onQueryEvent
|
||||
- [x] QueryGuard 并发控制：idle → running → idle，防止重复查询
|
||||
- [x] 渲染：Transcript 模式（只读历史）/ Prompt 模式（Messages + PermissionRequest + PromptInput）
|
||||
|
||||
**数据流**：`bun run dev` → `package.json scripts.dev` → `bun run src/entrypoints/cli.tsx` → 快速路径检查 → `main.tsx:main()` → `launchRepl()` → `<App><REPL /></App>`
|
||||
|
||||
---
|
||||
|
||||
## 第二阶段：核心对话循环 ✅
|
||||
|
||||
详细笔记：[phase-2-conversation-loop.md](phase-2-conversation-loop.md)
|
||||
|
||||
理解用户发一句话后，如何变成 API 请求、如何处理流式响应和工具调用。
|
||||
|
||||
- [x] `src/query.ts` — 核心查询循环（1732 行）
|
||||
- [x] `query()` AsyncGenerator 入口，委托给 `queryLoop()`
|
||||
- [x] `queryLoop()` — while(true) 主循环，State 对象管理迭代状态
|
||||
- [x] 消息预处理（autocompact、compact boundary）
|
||||
- [x] `deps.callModel()` → 流式 API 调用
|
||||
- [x] StreamingToolExecutor — API 流式返回时并行执行工具
|
||||
- [x] 工具调用循环（tool use → 执行 → result → continue）
|
||||
- [x] 错误恢复（prompt-too-long、max_output_tokens 升级+多轮恢复）
|
||||
- [x] 模型降级（FallbackTriggeredError → 切换 fallbackModel）
|
||||
- [x] Withheld 消息模式（暂扣可恢复错误）
|
||||
- [x] `src/QueryEngine.ts` — 高层编排器（1320 行）
|
||||
- [x] QueryEngine 类 — 一个 conversation 一个实例
|
||||
- [x] `submitMessage()` — 处理用户输入 → 调用 `query()` → 消费事件流
|
||||
- [x] SDK/print 模式专用（REPL 直接调用 query()）
|
||||
- [x] 会话持久化（recordTranscript）
|
||||
- [x] Usage 跟踪、权限拒绝记录
|
||||
- [x] `ask()` 便捷包装函数
|
||||
- [x] `src/services/api/claude.ts` — API 客户端（3420 行）
|
||||
- [x] `queryModelWithStreaming` / `queryModelWithoutStreaming` — 两个公开入口
|
||||
- [x] `queryModel()` — 核心私有函数（2400 行）
|
||||
- [x] 请求参数组装（system prompt、betas、tools、cache control）
|
||||
- [x] Anthropic SDK 流式调用（`anthropic.beta.messages.stream()`）
|
||||
- [x] `BetaRawMessageStreamEvent` 事件处理（message_start/content_block_*/message_delta/stop）
|
||||
- [x] withRetry 重试策略（429/500/529 + 模型降级）
|
||||
- [x] Prompt Caching 策略（ephemeral/1h TTL/global scope）
|
||||
- [x] 多 provider 支持（Anthropic / Bedrock / Vertex / Azure）
|
||||
|
||||
**数据流**：REPL.onSubmit → handlePromptSubmit → onQuery → onQueryImpl → `query()` AsyncGenerator → `queryLoop()` while(true) → `deps.callModel()` → `claude.ts queryModel()` → `anthropic.beta.messages.stream()` → 流式事件 → 收集 tool_use → 执行工具 → 结果追加到 messages → continue → 无工具调用时 return
|
||||
|
||||
---
|
||||
|
||||
## 第三阶段：工具系统
|
||||
|
||||
理解 Claude 如何定义、注册、调用工具。先读框架，再挑具体工具。
|
||||
|
||||
- [ ] `src/Tool.ts` — Tool 接口定义
|
||||
- [ ] `Tool` 类型结构（name、description、inputSchema、call）
|
||||
- [ ] `findToolByName`、`toolMatchesName` 工具函数
|
||||
- [ ] `src/tools.ts` — 工具注册表
|
||||
- [ ] 工具列表组装逻辑
|
||||
- [ ] 条件加载（feature flag、USER_TYPE）
|
||||
- [ ] 具体工具实现（挑选 2-3 个深入阅读）：
|
||||
- [ ] `src/tools/BashTool/` — 执行 shell 命令，最常用的工具
|
||||
- [ ] `src/tools/FileReadTool/` — 读取文件，简单直观，适合理解工具模式
|
||||
- [ ] `src/tools/FileEditTool/` — 编辑文件，理解 diff/patch 机制
|
||||
- [ ] `src/tools/AgentTool/` — 子 Agent 机制，较复杂但核心
|
||||
|
||||
---
|
||||
|
||||
## 第四阶段：上下文与系统提示
|
||||
|
||||
理解 Claude 如何"知道"项目信息、用户偏好等上下文。
|
||||
|
||||
- [ ] `src/context.ts` — 系统/用户上下文构建
|
||||
- [ ] git 状态注入
|
||||
- [ ] CLAUDE.md 内容加载
|
||||
- [ ] 内存文件（memory）注入
|
||||
- [ ] 日期、平台等环境信息
|
||||
- [ ] `src/utils/claudemd.ts` — CLAUDE.md 发现与加载
|
||||
- [ ] 项目层级搜索逻辑
|
||||
- [ ] 多级 CLAUDE.md 合并
|
||||
|
||||
---
|
||||
|
||||
## 第五阶段：UI 层（按兴趣选读）
|
||||
|
||||
理解终端 UI 的渲染机制（React/Ink）。
|
||||
|
||||
- [ ] `src/components/App.tsx` — 根组件，Provider 注入
|
||||
- [ ] `src/state/AppState.tsx` — 全局状态类型与 Context
|
||||
- [ ] `src/components/permissions/` — 工具权限审批 UI
|
||||
- [ ] `src/components/messages/` — 消息渲染组件
|
||||
|
||||
---
|
||||
|
||||
## 第六阶段：外围系统（按需探索）
|
||||
|
||||
- [ ] `src/services/mcp/` — MCP 协议（Model Context Protocol）
|
||||
- [ ] `src/skills/` — 技能系统（/commit 等斜杠命令）
|
||||
- [ ] `src/commands/` — CLI 子命令
|
||||
- [ ] `src/tasks/` — 后台任务系统
|
||||
- [ ] `src/utils/model/providers.ts` — 多 provider 选择逻辑
|
||||
|
||||
---
|
||||
|
||||
## 学习笔记
|
||||
|
||||
### 关键设计模式
|
||||
|
||||
| 模式 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| 快速路径 | cli.tsx | 按开销从低到高逐级检查，减少不必要的模块加载 |
|
||||
| 动态 import | cli.tsx / main.tsx | `await import()` 延迟加载，优化启动时间 |
|
||||
| feature flag | 全局 | `feature()` 永远返回 false，所有内部功能禁用 |
|
||||
| React/Ink | UI 层 | 用 React 组件模型渲染终端 UI |
|
||||
| 工具循环 | query.ts | AI 返回工具调用 → 执行 → 结果回传 → 继续，直到无工具调用 |
|
||||
| AsyncGenerator 链 | query.ts → claude.ts | `yield*` 透传事件流，形成管道 |
|
||||
| State 对象 | query.ts queryLoop | 循环间通过不可变 State + transition 字段传递状态 |
|
||||
| StreamingToolExecutor | query.ts | API 流式返回时并行执行工具 |
|
||||
| Withheld 消息 | query.ts | 暂扣可恢复错误，恢复成功则吞掉 |
|
||||
| withRetry | claude.ts | 429/500/529 自动重试 + 模型降级 |
|
||||
| Prompt Caching | claude.ts | 缓存系统提示和历史消息，减少 token 消耗 |
|
||||
|
||||
### 需要忽略的内容
|
||||
|
||||
- `_c()` 调用 — React Compiler 反编译产物
|
||||
- `feature('...')` 后面的代码块 — 全部是死代码
|
||||
- tsc 类型错误 — 反编译导致，不影响 Bun 运行
|
||||
- `packages/@ant/` — stub 包，无实际实现
|
||||
@@ -1,273 +0,0 @@
|
||||
# 第一阶段 Q&A
|
||||
|
||||
## Q1：cli.tsx 的快速路径分发具体在做什么？
|
||||
|
||||
**核心思想**：根据用户输入的命令参数，尽早决定走哪条路，避免加载不需要的代码。cli.tsx 充当一个轻量级路由器，把简单请求就地处理，只有真正需要完整 CLI 时才加载 main.tsx。
|
||||
|
||||
### 场景对比
|
||||
|
||||
#### 场景 1：`claude --version`（命中快速路径）
|
||||
|
||||
```
|
||||
cli.tsx main() 开始执行
|
||||
├── args = ["--version"]
|
||||
├── 命中第 64 行: args[0] === "--version" ✅
|
||||
├── console.log("2.1.888 (Claude Code)")
|
||||
└── return ← 立即退出，零 import，~10ms
|
||||
```
|
||||
|
||||
#### 场景 2：`claude --claude-in-chrome-mcp`（命中中间路径）
|
||||
|
||||
```
|
||||
cli.tsx main() 开始执行
|
||||
├── 第 64 行: --version? ❌
|
||||
├── 第 75 行: 加载 profileCheckpoint（仅此一个 import）
|
||||
├── 第 81 行: feature("DUMP_SYSTEM_PROMPT") → false ❌
|
||||
├── 第 95 行: --claude-in-chrome-mcp? ✅ 命中
|
||||
├── await import("../utils/claudeInChrome/mcpServer.js") ← 只加载这一个模块
|
||||
└── return ← 没有加载 main.tsx 的 200+ import
|
||||
```
|
||||
|
||||
#### 场景 3：`claude`（无参数，最常见，全部未命中）
|
||||
|
||||
```
|
||||
cli.tsx main() 开始执行
|
||||
├── --version? ❌
|
||||
├── profileCheckpoint 加载
|
||||
├── feature(DUMP)? ❌ (feature=false)
|
||||
├── --chrome-mcp? ❌
|
||||
├── --chrome-native? ❌
|
||||
├── feature(CHICAGO)? ❌ (feature=false)
|
||||
├── feature(DAEMON)? ❌ (feature=false)
|
||||
├── feature(BRIDGE)? ❌ (feature=false)
|
||||
├── ... 所有快速路径逐一检查，全部未命中
|
||||
│
|
||||
├── 走到第 310 行 ← 最终出口
|
||||
├── await import("../main.jsx") ← 加载完整 CLI（200+ import，~135ms）
|
||||
└── await cliMain() ← 进入 main.tsx 重型初始化
|
||||
```
|
||||
|
||||
### 性能对比
|
||||
|
||||
| 方式 | `claude --version` 耗时 |
|
||||
|------|------------------------|
|
||||
| 无快速路径（全部走 main.tsx） | ~200ms（加载 200+ import → 初始化 Commander → 解析参数 → 打印） |
|
||||
| 有快速路径（cli.tsx 拦截） | ~10ms（读 args → 打印 → 退出） |
|
||||
|
||||
### feature() 的加速作用
|
||||
|
||||
大量快速路径被 `feature()` 守护：
|
||||
|
||||
```ts
|
||||
if (feature("DAEMON") && args[0] === "daemon") { ... }
|
||||
```
|
||||
|
||||
`feature()` 返回 false → `&&` 短路求值 → 连 `args[0]` 都不检查，直接跳过。在反编译版本中这些路径等于不存在，进一步加速了"全部没命中 → 走默认路径"的过程。
|
||||
|
||||
---
|
||||
|
||||
## Q2：main.tsx 中不同命令的具体执行流程是怎样的？
|
||||
|
||||
所有命令都会经过 main() → run()，但在 run() 内部根据 Commander 路由到不同分支。
|
||||
|
||||
### 场景 1：`claude`（无参数 — 启动交互 REPL）
|
||||
|
||||
最常见的场景，走完整条主命令路径：
|
||||
|
||||
```
|
||||
main() (第 585 行)
|
||||
├── 信号处理注册（SIGINT、exit）
|
||||
├── feature flag 路径全部跳过
|
||||
├── isNonInteractive = false（有 TTY，没有 -p）
|
||||
├── clientType = 'cli'
|
||||
└── await run()
|
||||
│
|
||||
▼
|
||||
run() (第 884 行)
|
||||
├── Commander 初始化 + preAction 钩子 + 主命令选项注册
|
||||
├── isPrintMode = false → 注册所有子命令
|
||||
└── program.parseAsync(process.argv)
|
||||
│ Commander 匹配到主命令，先执行 preAction
|
||||
▼
|
||||
preAction (第 907 行)
|
||||
├── await ensureMdmSettingsLoaded() ← 等 side-effect import 的子进程完成
|
||||
├── await ensureKeychainPrefetchCompleted() ← 等 keychain 预读完成
|
||||
├── await init() ← 遥测、配置、信任
|
||||
├── initSinks() ← 分析日志
|
||||
├── runMigrations() ← 数据迁移
|
||||
└── loadRemoteManagedSettings() / loadPolicyLimits() ← 非阻塞
|
||||
│ 然后执行 action handler
|
||||
▼
|
||||
action(undefined, options) (第 1007 行) ← prompt = undefined
|
||||
├── [参数解析] permissionMode, model, thinkingConfig...
|
||||
├── [工具加载] tools = getTools(toolPermissionContext)
|
||||
├── [并行初始化]
|
||||
│ ├── setup() ← worktree、CWD
|
||||
│ ├── getCommands() ← 加载斜杠命令
|
||||
│ └── getAgentDefinitionsWithOverrides() ← 加载 agent 定义
|
||||
├── [MCP 连接] 连接配置的 MCP 服务器
|
||||
├── [构建初始状态] initialState = { tools, mcp, permissions, ... }
|
||||
│
|
||||
├── [UI 初始化]（交互模式专属）
|
||||
│ ├── createRoot() ← 创建 Ink 渲染根节点
|
||||
│ └── showSetupScreens() ← 信任对话框 / OAuth / 引导
|
||||
│
|
||||
├── [后续初始化] LSP、插件版本、session 注册
|
||||
│
|
||||
└── 默认分支 (第 3760 行) ← 没有 --continue/--resume/--print
|
||||
└── await launchRepl(root, {
|
||||
initialState
|
||||
}, {
|
||||
...sessionConfig,
|
||||
initialMessages: undefined ← 全新对话，无历史消息
|
||||
}, renderAndRun)
|
||||
│
|
||||
▼
|
||||
REPL.tsx 渲染，用户看到空白对话界面
|
||||
```
|
||||
|
||||
### 场景 2：`echo "explain this" | claude -p`（管道/非交互模式）
|
||||
|
||||
```
|
||||
main() →
|
||||
├── isNonInteractive = true（-p 标志 + stdin 不是 TTY）
|
||||
├── clientType = 'sdk-cli'
|
||||
└── run()
|
||||
│
|
||||
▼
|
||||
run()
|
||||
├── Commander 初始化 + preAction + 主命令选项
|
||||
├── isPrintMode = true
|
||||
│ → ★ 跳过所有子命令注册（节省 ~65ms）
|
||||
└── program.parseAsync() ← 直接解析，Commander 路由到主命令 action
|
||||
│
|
||||
▼
|
||||
preAction → init、迁移等（同场景 1）
|
||||
│
|
||||
▼
|
||||
action("", { print: true, ... })
|
||||
├── inputPrompt = await getInputPrompt("")
|
||||
│ ├── stdin.isTTY = false → 从 stdin 读数据
|
||||
│ ├── 等待最多 3s 读入: "explain this"
|
||||
│ └── 返回 "explain this"
|
||||
├── tools = getTools()
|
||||
├── setup() + getCommands()（并行）
|
||||
│
|
||||
├── isNonInteractiveSession = true → 走 --print 分支（第 2584 行）
|
||||
│ ├── applyConfigEnvironmentVariables() ← -p 模式信任隐含
|
||||
│ ├── 构建 headlessInitialState（无 UI）
|
||||
│ ├── headlessStore = createStore(headlessInitialState)
|
||||
│ │
|
||||
│ ├── await import('src/cli/print.js')
|
||||
│ └── runHeadless(inputPrompt, ...) ★ 不走 REPL
|
||||
│ ├── 发送 API 请求
|
||||
│ ├── 流式输出到 stdout
|
||||
│ └── 完成后 process.exit()
|
||||
│
|
||||
└── ← 不走 createRoot()、showSetupScreens()、launchRepl()
|
||||
```
|
||||
|
||||
**关键差异**：
|
||||
- 检测到 `-p` 后跳过子命令注册（节省 ~65ms）
|
||||
- 不创建 Ink UI，不调用 `showSetupScreens()`
|
||||
- 从 stdin 读取输入（`getInputPrompt` 第 857 行）
|
||||
- 走 `print.js` 路径直接执行查询输出到 stdout
|
||||
|
||||
### 场景 3：`claude -c`（继续最近对话）
|
||||
|
||||
```
|
||||
... main() → run() → preAction → action（前半部分同场景 1）
|
||||
│
|
||||
▼
|
||||
action(undefined, { continue: true, ... })
|
||||
├── [参数解析 + 工具加载 + 并行初始化 + UI 初始化]（同场景 1）
|
||||
│
|
||||
├── options.continue = true → 命中第 3101 行
|
||||
│ ├── clearSessionCaches() ← 清除过期缓存
|
||||
│ ├── result = await loadConversationForResume()
|
||||
│ │ └── 从 ~/.claude/projects/<cwd>/ 读最近的会话 JSONL
|
||||
│ │
|
||||
│ ├── result 为 null? → exitWithError("No conversation found")
|
||||
│ │
|
||||
│ ├── loaded = await processResumedConversation(result)
|
||||
│ │ ├── 解析 JSONL → messages[]
|
||||
│ │ ├── 恢复文件历史快照
|
||||
│ │ └── 重建 initialState
|
||||
│ │
|
||||
│ └── await launchRepl(root, {
|
||||
│ initialState: loaded.initialState
|
||||
│ }, {
|
||||
│ ...sessionConfig,
|
||||
│ initialMessages: loaded.messages, ★ 带上历史消息
|
||||
│ initialFileHistorySnapshots: loaded.fileHistorySnapshots,
|
||||
│ initialAgentName: loaded.agentName
|
||||
│ }, renderAndRun)
|
||||
│ │
|
||||
│ ▼
|
||||
│ REPL.tsx 渲染，显示历史对话，用户继续聊天
|
||||
│
|
||||
└── ← 其他分支不执行
|
||||
```
|
||||
|
||||
**关键差异**：`initialMessages` 有值（历史消息），REPL 启动时会渲染之前的对话内容。
|
||||
|
||||
### 场景 4：`claude mcp list`（子命令）
|
||||
|
||||
```
|
||||
main() → run()
|
||||
│
|
||||
▼
|
||||
run()
|
||||
├── Commander 初始化 + preAction 钩子
|
||||
├── 注册主命令 .action(...)
|
||||
├── isPrintMode = false → 注册所有子命令
|
||||
│ ├── program.command('mcp') (第 3894 行)
|
||||
│ │ ├── mcp.command('serve').action(...)
|
||||
│ │ ├── mcp.command('add').action(...)
|
||||
│ │ ├── mcp.command('list').action(async () => { ★
|
||||
│ │ │ const { mcpListHandler } = await import('./cli/handlers/mcp.js');
|
||||
│ │ │ await mcpListHandler();
|
||||
│ │ │ })
|
||||
│ │ └── ...
|
||||
│ ├── program.command('auth')
|
||||
│ ├── program.command('doctor')
|
||||
│ └── ...
|
||||
│
|
||||
└── program.parseAsync(["node", "claude", "mcp", "list"])
|
||||
│ Commander 匹配到 mcp → list
|
||||
▼
|
||||
preAction (第 907 行) ← 子命令也触发 preAction
|
||||
├── await init()
|
||||
├── initSinks()
|
||||
├── runMigrations()
|
||||
└── ...
|
||||
│
|
||||
▼ 执行子命令自己的 action（不走主命令 action）
|
||||
mcp list action
|
||||
├── await import('./cli/handlers/mcp.js')
|
||||
└── await mcpListHandler()
|
||||
├── 读取 MCP 配置（user/project/local 三级）
|
||||
├── 连接每个服务器做健康检查
|
||||
├── 格式化输出到终端
|
||||
└── 退出
|
||||
|
||||
← 主命令的 action handler 完全不执行
|
||||
← 没有 REPL、没有 Ink UI、没有 showSetupScreens
|
||||
```
|
||||
|
||||
**关键差异**：
|
||||
- Commander 路由到子命令，**主命令 action 完全跳过**
|
||||
- `preAction` 仍然执行（基础初始化所有命令都需要）
|
||||
- 子命令有自己独立的轻量 action
|
||||
|
||||
### 四种场景对比
|
||||
|
||||
| | `claude` | `claude -p` | `claude -c` | `claude mcp list` |
|
||||
|---|---------|------------|------------|-------------------|
|
||||
| preAction | 执行 | 执行 | 执行 | 执行 |
|
||||
| 主命令 action | 执行 | 执行 | 执行 | **跳过** |
|
||||
| 子命令注册 | 注册 | **跳过** | 注册 | 注册 |
|
||||
| showSetupScreens | 执行 | **跳过** | 执行 | **跳过** |
|
||||
| createRoot (Ink) | 执行 | **跳过** | 执行 | **跳过** |
|
||||
| 加载历史消息 | 否 | 否 | **是** | 否 |
|
||||
| 最终出口 | launchRepl | print.js | launchRepl | 子命令 action |
|
||||
@@ -1,597 +0,0 @@
|
||||
# 第一阶段：启动流程详解
|
||||
|
||||
> 从 `bun run dev` 到用户看到交互界面的完整路径
|
||||
|
||||
## 启动链路总览
|
||||
|
||||
```
|
||||
bun run dev
|
||||
→ package.json scripts.dev: "bun run src/entrypoints/cli.tsx"
|
||||
→ cli.tsx: polyfill 注入 + 快速路径检查
|
||||
→ import("../main.jsx") → cliMain()
|
||||
→ main.tsx: main() → run()
|
||||
→ Commander 参数解析 → preAction 钩子
|
||||
→ action handler: 服务初始化 → showSetupScreens
|
||||
→ launchRepl()
|
||||
→ replLauncher.tsx: <App><REPL /></App>
|
||||
→ REPL.tsx: 渲染交互界面，等待用户输入
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. cli.tsx（321 行）— 入口与快速路径分发
|
||||
|
||||
**文件路径**: `src/entrypoints/cli.tsx`
|
||||
|
||||
### 1.1 全局 Polyfill（第 1-53 行）
|
||||
|
||||
模块加载时立即执行的 side-effect，在 `main()` 之前运行。
|
||||
|
||||
#### feature() 桩函数（第 3 行）
|
||||
|
||||
```ts
|
||||
const feature = (_name: string) => false;
|
||||
```
|
||||
|
||||
原版 Claude Code 构建时，Bun bundler 通过 `bun:bundle` 提供 `feature()` 函数，用于**编译时 feature flag**（类似 C 的 `#ifdef`）。反编译版没有构建流程，所以直接定义为永远返回 `false`。
|
||||
|
||||
**效果**：所有 Anthropic 内部功能分支全部禁用，包括：
|
||||
- `COORDINATOR_MODE` — 协调器模式
|
||||
- `KAIROS` — 助手模式
|
||||
- `DAEMON` — 后台守护进程
|
||||
- `BRIDGE_MODE` — 远程控制
|
||||
- `SSH_REMOTE` — SSH 远程
|
||||
- `BG_SESSIONS` — 后台会话
|
||||
- ... 等 20+ 个 flag
|
||||
|
||||
#### MACRO 全局对象（第 4-14 行）
|
||||
|
||||
```ts
|
||||
globalThis.MACRO = {
|
||||
VERSION: "2.1.888",
|
||||
BUILD_TIME: new Date().toISOString(),
|
||||
FEEDBACK_CHANNEL: "",
|
||||
ISSUES_EXPLAINER: "",
|
||||
NATIVE_PACKAGE_URL: "",
|
||||
PACKAGE_URL: "",
|
||||
VERSION_CHANGELOG: "",
|
||||
};
|
||||
```
|
||||
|
||||
原版构建时 Bun 会把这些值内联到代码里。这里模拟注入，让后续代码读 `MACRO.VERSION` 时能拿到值。
|
||||
|
||||
#### 构建常量（第 16-18 行）
|
||||
|
||||
```ts
|
||||
BUILD_TARGET = "external"; // 标记为"外部"构建（非 Anthropic 内部）
|
||||
BUILD_ENV = "production"; // 生产环境
|
||||
INTERFACE_TYPE = "stdio"; // 标准输入输出模式
|
||||
```
|
||||
|
||||
这三个全局变量在代码各处被读取，用来区分运行环境。`"external"` 意味着很多 `("external" as string) === 'ant'` 的检查会返回 false。
|
||||
|
||||
#### 环境修补（第 22-33 行）
|
||||
|
||||
- 禁用 corepack 自动 pin（防止污染 package.json）
|
||||
- 远程模式下设置 Node.js 堆内存上限 8GB
|
||||
|
||||
#### ABLATION_BASELINE（第 40-53 行）
|
||||
|
||||
```ts
|
||||
if (feature("ABLATION_BASELINE") && ...) { ... }
|
||||
```
|
||||
|
||||
`feature()` 返回 false，**永远不执行**。Anthropic 内部 A/B 测试代码。
|
||||
|
||||
### 1.2 main() 函数（第 60-317 行）
|
||||
|
||||
设计模式：**分层快速路径（fast path cascading）**——按开销从低到高逐级检查，命中即返回。
|
||||
|
||||
#### 快速路径列表
|
||||
|
||||
| 优先级 | 行号 | 检查条件 | 功能 | 开销 | 可执行 |
|
||||
|--------|------|---------|------|------|--------|
|
||||
| 1 | 64-72 | `--version` / `-v` | 打印版本号退出 | **零 import** | 是 |
|
||||
| 2 | 81-94 | `feature("DUMP_SYSTEM_PROMPT")` | 导出系统提示 | - | 否（flag） |
|
||||
| 3 | 95-99 | `--claude-in-chrome-mcp` | Chrome MCP 服务 | 动态 import | 是 |
|
||||
| 4 | 101-105 | `--chrome-native-host` | Chrome Native Host | 动态 import | 是 |
|
||||
| 5 | 108-116 | `feature("CHICAGO_MCP")` | Computer Use MCP | - | 否（flag） |
|
||||
| 6 | 123-127 | `feature("DAEMON")` | Daemon Worker | - | 否（flag） |
|
||||
| 7 | 133-178 | `feature("BRIDGE_MODE")` | 远程控制 | - | 否（flag） |
|
||||
| 8 | 181-190 | `feature("DAEMON")` | Daemon 主进程 | - | 否（flag） |
|
||||
| 9 | 195-225 | `feature("BG_SESSIONS")` | ps/logs/attach/kill | - | 否（flag） |
|
||||
| 10 | 228-240 | `feature("TEMPLATES")` | 模板任务 | - | 否（flag） |
|
||||
| 11 | 244-253 | `feature("BYOC_ENVIRONMENT_RUNNER")` | BYOC 运行器 | - | 否（flag） |
|
||||
| 12 | 258-264 | `feature("SELF_HOSTED_RUNNER")` | 自托管运行器 | - | 否（flag） |
|
||||
| 13 | 267-293 | `--tmux` + `--worktree` | tmux worktree | 动态 import | 是 |
|
||||
|
||||
#### 参数修正（第 296-307 行）
|
||||
|
||||
```ts
|
||||
// --update/--upgrade → 重写为 update 子命令
|
||||
if (args[0] === "--update") process.argv = [..., "update"];
|
||||
// --bare → 设置简单模式环境变量
|
||||
if (args.includes("--bare")) process.env.CLAUDE_CODE_SIMPLE = "1";
|
||||
```
|
||||
|
||||
#### 最终出口（第 310-316 行）
|
||||
|
||||
```ts
|
||||
const { startCapturingEarlyInput } = await import("../utils/earlyInput.js");
|
||||
startCapturingEarlyInput(); // 捕获用户提前输入的内容
|
||||
const { main: cliMain } = await import("../main.jsx");
|
||||
await cliMain(); // 进入 main.tsx 重型初始化
|
||||
```
|
||||
|
||||
所有快速路径都没命中时（99% 的情况），才走到这里。
|
||||
|
||||
### 1.3 启动（第 320 行）
|
||||
|
||||
```ts
|
||||
void main();
|
||||
```
|
||||
|
||||
`void` 表示不关心 Promise 返回值。
|
||||
|
||||
### 1.4 关键设计思想
|
||||
|
||||
- **快速路径**：`--version` 零开销返回，不加载任何模块
|
||||
- **动态 import**：`await import()` 替代静态 import，每条路径只加载自己需要的模块
|
||||
- **feature flag 过滤**：`feature()` 返回 false 使大量内部功能成为死代码
|
||||
|
||||
---
|
||||
|
||||
## 2. main.tsx（4683 行）— 重型初始化与 Commander CLI
|
||||
|
||||
**文件路径**: `src/main.tsx`
|
||||
|
||||
整个项目最大的单文件，但结构清晰：**辅助函数 → main() → run()**。
|
||||
|
||||
### 2.1 Import 区（第 1-215 行）
|
||||
|
||||
200+ 行 import，加载几乎所有子系统。关键的是前三个 **side-effect import**（import 即执行）：
|
||||
|
||||
```ts
|
||||
// 第 9 行：记录时间戳
|
||||
profileCheckpoint('main_tsx_entry');
|
||||
|
||||
// 第 16 行：启动 MDM 子进程读取（macOS plutil）
|
||||
startMdmRawRead();
|
||||
|
||||
// 第 20 行：启动 keychain 预读取（OAuth token、API key）
|
||||
startKeychainPrefetch();
|
||||
```
|
||||
|
||||
这三个在 import 阶段就**并行启动子进程**，和后续 ~135ms 的模块加载同时进行——**用并行隐藏延迟**。
|
||||
|
||||
### 2.2 辅助函数（第 216-584 行）
|
||||
|
||||
| 函数 | 行号 | 作用 |
|
||||
|------|------|------|
|
||||
| `logManagedSettings()` | 216 | 记录企业托管设置到分析日志 |
|
||||
| `isBeingDebugged()` | 232 | 检测调试模式，**外部构建下直接 exit(1)**（第 266 行） |
|
||||
| `logSessionTelemetry()` | 279 | Session 遥测（技能、插件） |
|
||||
| `getCertEnvVarTelemetry()` | 291 | SSL 证书环境变量收集 |
|
||||
| `runMigrations()` | 326 | 数据迁移（模型重命名、设置格式升级等） |
|
||||
| `prefetchSystemContextIfSafe()` | 360 | 信任关系建立后安全预取系统上下文 |
|
||||
| `startDeferredPrefetches()` | 388 | REPL 首次渲染后的延迟预取 |
|
||||
| `eagerLoadSettings()` | 502 | 在 init() 之前提前加载 `--settings` 参数 |
|
||||
| `initializeEntrypoint()` | 517 | 根据运行模式设置 `CLAUDE_CODE_ENTRYPOINT` |
|
||||
|
||||
还有 `_pendingConnect`、`_pendingSSH`、`_pendingAssistantChat` 三个状态变量（第 542-583 行），用于暂存子命令参数。
|
||||
|
||||
### 2.3 main() 函数（第 585-856 行）
|
||||
|
||||
`main()` 本身不长，做完环境检测后调用 `run()`：
|
||||
|
||||
```
|
||||
main()
|
||||
├── 安全设置（NoDefaultCurrentDirectoryInExePath）
|
||||
├── 信号处理（SIGINT → exit, exit → 恢复光标）
|
||||
├── feature flag 保护的特殊路径（全部跳过）
|
||||
├── 检测 -p/--print / --init-only → 判断是否交互模式
|
||||
├── clientType 判断（cli / sdk-typescript / remote / github-action 等）
|
||||
├── eagerLoadSettings()
|
||||
└── await run() ← 进入真正的逻辑
|
||||
```
|
||||
|
||||
### 2.4 run() 函数（第 884-4683 行）
|
||||
|
||||
占 3800 行，是整个文件的核心。
|
||||
|
||||
#### Commander 初始化 + preAction 钩子（第 884-967 行）
|
||||
|
||||
```ts
|
||||
const program = new CommanderCommand()
|
||||
.configureHelp(createSortedHelpConfig())
|
||||
.enablePositionalOptions();
|
||||
```
|
||||
|
||||
**preAction 钩子**（所有命令执行前都会运行）：
|
||||
|
||||
```
|
||||
preAction
|
||||
├── await ensureMdmSettingsLoaded() ← 等 MDM 子进程完成
|
||||
├── await ensureKeychainPrefetchCompleted() ← 等 keychain 预读完成
|
||||
├── await init() ← 一次性初始化
|
||||
├── initSinks() ← 分析日志接收器
|
||||
├── runMigrations() ← 数据迁移
|
||||
├── loadRemoteManagedSettings() ← 企业远程设置（非阻塞）
|
||||
└── loadPolicyLimits() ← 策略限制（非阻塞）
|
||||
```
|
||||
|
||||
#### 主命令 Option 定义（第 968-1006 行）
|
||||
|
||||
定义了 40+ CLI 参数，关键的包括：
|
||||
|
||||
| 参数 | 作用 |
|
||||
|------|------|
|
||||
| `-p, --print` | 非交互模式，输出后退出 |
|
||||
| `--model <model>` | 指定模型（如 sonnet、opus） |
|
||||
| `--permission-mode <mode>` | 权限模式 |
|
||||
| `-c, --continue` | 继续最近对话 |
|
||||
| `-r, --resume` | 恢复指定对话 |
|
||||
| `--mcp-config` | MCP 服务器配置文件 |
|
||||
| `--allowedTools` | 允许的工具列表 |
|
||||
| `--system-prompt` | 自定义系统提示 |
|
||||
| `--dangerously-skip-permissions` | 跳过所有权限检查 |
|
||||
| `--output-format` | 输出格式（text/json/stream-json） |
|
||||
| `--effort <level>` | 推理努力级别（low/medium/high/max） |
|
||||
| `--bare` | 最小模式 |
|
||||
|
||||
#### action 处理器（第 1006-3808 行）
|
||||
|
||||
主命令的执行逻辑，内部按阶段和场景分支：
|
||||
|
||||
```
|
||||
action(async (prompt, options) => {
|
||||
│
|
||||
├── [1007-1600] 参数解析与预处理
|
||||
│ ├── --bare 模式
|
||||
│ ├── 解析 model / permission-mode / thinking / effort
|
||||
│ ├── 解析 MCP 配置、工具列表、系统提示
|
||||
│ └── 初始化工具权限上下文
|
||||
│
|
||||
├── [1600-2220] 服务初始化
|
||||
│ ├── MCP 客户端连接
|
||||
│ ├── 插件加载 + 技能初始化
|
||||
│ ├── 工具列表组装
|
||||
│ └── 初始 AppState 构建
|
||||
│
|
||||
├── [2220-2315] UI 初始化（交互模式）
|
||||
│ ├── createRoot() — 创建 Ink 渲染根节点
|
||||
│ ├── showSetupScreens() — 信任对话框、OAuth 登录、引导
|
||||
│ └── 登录后刷新各种服务
|
||||
│
|
||||
├── [2315-2582] 后续初始化
|
||||
│ ├── LSP 管理器、插件版本管理
|
||||
│ ├── session 注册、遥测日志
|
||||
│ └── 遥测上报
|
||||
│
|
||||
├── [2584-3050] --print 非交互模式分支
|
||||
│ ├── 构建 headless AppState + store
|
||||
│ └── 交给 print.ts 执行
|
||||
│
|
||||
└── [3050-3808] 交互模式：启动 REPL（7 个分支）
|
||||
├── --continue → 加载最近对话 → launchRepl()
|
||||
├── DIRECT_CONNECT → ❌ flag 关闭
|
||||
├── SSH_REMOTE → ❌ flag 关闭
|
||||
├── KAIROS assistant → ❌ flag 关闭
|
||||
├── --resume <id> → 恢复指定对话 → launchRepl()
|
||||
├── --resume 无 ID → 显示对话选择器
|
||||
└── 默认（无参数） → launchRepl() ★最常走的路径
|
||||
})
|
||||
```
|
||||
|
||||
#### 子命令注册（第 3808-4683 行）
|
||||
|
||||
| 子命令 | 行号 | 作用 |
|
||||
|--------|------|------|
|
||||
| `claude mcp` | 3892 | MCP 服务器管理（serve/add/remove/list/get） |
|
||||
| `claude server` | 3960 | Session 服务器（❌ flag 关闭） |
|
||||
| `claude auth` | 4098 | 认证管理（login/logout/status/token） |
|
||||
| `claude plugin` | 4148 | 插件管理（install/uninstall/list/update） |
|
||||
| `claude setup-token` | 4267 | 设置长期认证 token |
|
||||
| `claude agents` | 4278 | 列出已配置的 agents |
|
||||
| `claude doctor` | 4346 | 健康检查 |
|
||||
| `claude update` | 4362 | 检查更新 |
|
||||
| `claude install` | 4394 | 安装原生构建 |
|
||||
| `claude log` | 4411 | 查看对话日志（内部） |
|
||||
| `claude completion` | 4491 | Shell 自动补全 |
|
||||
|
||||
最后执行解析：
|
||||
|
||||
```ts
|
||||
await program.parseAsync(process.argv);
|
||||
```
|
||||
|
||||
### 2.5 main.tsx 学习建议
|
||||
|
||||
- **不要通读**。记住三段结构：辅助函数 → main() → run()
|
||||
- `feature()` 返回 false 的分支全部跳过，可忽略 50%+ 代码
|
||||
- `("external" as string) === 'ant'` 的分支也跳过（内部构建专用）
|
||||
- 需要深入某功能时，通过搜索定位对应代码段
|
||||
|
||||
---
|
||||
|
||||
## 3. replLauncher.tsx（22 行）— 胶水层
|
||||
|
||||
**文件路径**: `src/replLauncher.tsx`
|
||||
|
||||
极其简单，就做一件事：
|
||||
|
||||
```tsx
|
||||
export async function launchRepl(root, appProps, replProps, renderAndRun) {
|
||||
const { App } = await import('./components/App.js');
|
||||
const { REPL } = await import('./screens/REPL.js');
|
||||
await renderAndRun(root, <App {...appProps}><REPL {...replProps} /></App>);
|
||||
}
|
||||
```
|
||||
|
||||
- `App` — 全局 Provider（AppState、Stats、FpsMetrics）
|
||||
- `REPL` — 交互界面组件
|
||||
- `renderAndRun` — 把 React 元素渲染到 Ink 终端
|
||||
|
||||
动态 import 保持了按需加载的策略。
|
||||
|
||||
---
|
||||
|
||||
## 4. REPL.tsx（5009 行）— 交互界面
|
||||
|
||||
**文件路径**: `src/screens/REPL.tsx`
|
||||
|
||||
项目第二大文件，是用户直接交互的界面。一个巨型 React 函数组件。
|
||||
|
||||
### 4.1 文件结构
|
||||
|
||||
```
|
||||
REPL.tsx (5009 行)
|
||||
├── [1-310] Import 区（150+ import）
|
||||
├── [312-525] 辅助组件
|
||||
│ ├── median() — 数学工具函数
|
||||
│ ├── TranscriptModeFooter — 转录模式底栏
|
||||
│ ├── TranscriptSearchBar — 转录搜索栏
|
||||
│ └── AnimatedTerminalTitle — 终端标题动画
|
||||
├── [527-571] Props 类型定义
|
||||
└── [573-5009] REPL() 组件主体
|
||||
├── [600-900] 状态声明（50+ 个 useState/useRef/useAppState）
|
||||
├── [900-2750] 副作用与回调（useEffect/useCallback）
|
||||
├── [2750-2860] onQueryImpl — 核心：执行 API 查询
|
||||
├── [2860-3030] onQuery — 查询守卫与并发控制
|
||||
├── [3030-3145] 查询相关辅助回调
|
||||
├── [3146-3550] onSubmit — 用户提交处理
|
||||
├── [3550-4395] 更多副作用与状态管理
|
||||
└── [4396-5009] JSX 渲染
|
||||
```
|
||||
|
||||
### 4.2 Props
|
||||
|
||||
从 main.tsx 通过 launchRepl() 传入：
|
||||
|
||||
| Prop | 类型 | 含义 |
|
||||
|------|------|------|
|
||||
| `commands` | `Command[]` | 可用的斜杠命令 |
|
||||
| `debug` | `boolean` | 调试模式 |
|
||||
| `initialTools` | `Tool[]` | 初始工具集 |
|
||||
| `initialMessages` | `MessageType[]` | 初始消息（恢复对话时有值） |
|
||||
| `pendingHookMessages` | `Promise<...>` | 延迟加载的 hook 消息 |
|
||||
| `mcpClients` | `MCPServerConnection[]` | MCP 服务器连接 |
|
||||
| `systemPrompt` | `string` | 自定义系统提示 |
|
||||
| `appendSystemPrompt` | `string` | 追加系统提示 |
|
||||
| `onBeforeQuery` | `fn` | 查询前回调，返回 false 可阻止查询 |
|
||||
| `onTurnComplete` | `fn` | 轮次完成回调 |
|
||||
| `mainThreadAgentDefinition` | `AgentDefinition` | 主线程 Agent 定义 |
|
||||
| `thinkingConfig` | `ThinkingConfig` | 思考模式配置 |
|
||||
| `disabled` | `boolean` | 禁用输入 |
|
||||
|
||||
### 4.3 状态管理
|
||||
|
||||
分三层：
|
||||
|
||||
**全局 AppState（通过 useAppState 选择器读取）：**
|
||||
|
||||
```ts
|
||||
const toolPermissionContext = useAppState(s => s.toolPermissionContext);
|
||||
const verbose = useAppState(s => s.verbose);
|
||||
const mcp = useAppState(s => s.mcp);
|
||||
const plugins = useAppState(s => s.plugins);
|
||||
const agentDefinitions = useAppState(s => s.agentDefinitions);
|
||||
```
|
||||
|
||||
**本地状态（useState）：**
|
||||
|
||||
```ts
|
||||
const [messages, setMessages] = useState(initialMessages ?? []);
|
||||
const [inputValue, setInputValue] = useState('');
|
||||
const [screen, setScreen] = useState<Screen>('prompt');
|
||||
const [streamingText, setStreamingText] = useState(null);
|
||||
const [streamingToolUses, setStreamingToolUses] = useState([]);
|
||||
// ... 50+ 个状态
|
||||
```
|
||||
|
||||
**关键 Ref：**
|
||||
|
||||
```ts
|
||||
const queryGuard = useRef(new QueryGuard()).current; // 查询并发控制
|
||||
const messagesRef = useRef(messages); // 消息的同步引用（避免闭包问题）
|
||||
const abortController = ...; // 取消请求控制器
|
||||
const responseLengthRef = useRef(0); // 响应长度追踪
|
||||
```
|
||||
|
||||
### 4.4 核心数据流：用户输入 → API 调用
|
||||
|
||||
```
|
||||
用户按回车
|
||||
│
|
||||
▼
|
||||
onSubmit (第 3146 行)
|
||||
├── 斜杠命令？→ immediate command 直接执行 或 handlePromptSubmit 路由
|
||||
├── 空输入？→ 忽略
|
||||
├── 空闲检测 → 可能弹出"是否开始新对话"对话框
|
||||
├── 加入历史记录
|
||||
│
|
||||
▼
|
||||
handlePromptSubmit (外部函数，src/utils/handlePromptSubmit.ts)
|
||||
├── 斜杠命令 → 路由到对应 Command handler
|
||||
├── 普通文本 → 构建 UserMessage，调用 onQuery()
|
||||
│
|
||||
▼
|
||||
onQuery (第 2860 行) — 并发守卫层
|
||||
├── queryGuard.tryStart() → 已有查询？排队等待
|
||||
├── setMessages([...old, ...newMessages]) — 追加用户消息
|
||||
├── onQueryImpl()
|
||||
│
|
||||
▼
|
||||
onQueryImpl (第 2750 行) — 真正执行 API 调用
|
||||
│
|
||||
├── 1. 并行加载上下文:
|
||||
│ await Promise.all([
|
||||
│ getSystemPrompt(), // 构建系统提示
|
||||
│ getUserContext(), // 用户上下文
|
||||
│ getSystemContext(), // 系统上下文（git、平台等）
|
||||
│ ])
|
||||
│
|
||||
├── 2. buildEffectiveSystemPrompt() — 合成最终系统提示
|
||||
│
|
||||
├── 3. for await (const event of query({...})) ★核心★
|
||||
│ │ 调用 src/query.ts 的 query() AsyncGenerator
|
||||
│ │ 流式产出事件
|
||||
│ │
|
||||
│ └── onQueryEvent(event) — 处理每个流式事件
|
||||
│ ├── 更新 streamingText（打字机效果）
|
||||
│ ├── 更新 messages（工具调用结果）
|
||||
│ └── 更新 inProgressToolUseIDs
|
||||
│
|
||||
└── 4. 收尾：resetLoadingState()、onTurnComplete()
|
||||
```
|
||||
|
||||
**核心代码（第 2797-2807 行）**：
|
||||
|
||||
```ts
|
||||
for await (const event of query({
|
||||
messages: messagesIncludingNewMessages,
|
||||
systemPrompt,
|
||||
userContext,
|
||||
systemContext,
|
||||
canUseTool,
|
||||
toolUseContext,
|
||||
querySource: getQuerySourceForREPL()
|
||||
})) {
|
||||
onQueryEvent(event);
|
||||
}
|
||||
```
|
||||
|
||||
`query()` 来自 `src/query.ts`，是第二阶段要学的核心函数。
|
||||
|
||||
### 4.5 QueryGuard 并发控制
|
||||
|
||||
防止同时发起多个 API 请求的状态机：
|
||||
|
||||
```
|
||||
idle ──tryStart()──▶ running ──end()──▶ idle
|
||||
│
|
||||
└── tryStart() 返回 null（已在运行）
|
||||
→ 新消息排入队列
|
||||
```
|
||||
|
||||
- `tryStart()` — 原子操作，检查并转换 idle→running，返回 generation 号
|
||||
- `end(generation)` — 检查 generation 匹配后转换 running→idle
|
||||
- 防止 cancel+resubmit 竞态条件
|
||||
|
||||
### 4.6 JSX 渲染
|
||||
|
||||
两个互斥的渲染分支：
|
||||
|
||||
#### Transcript 模式（第 4396-4493 行）
|
||||
|
||||
按 `v` 键切换，只读浏览对话历史，支持搜索：
|
||||
|
||||
```tsx
|
||||
<KeybindingSetup>
|
||||
<AnimatedTerminalTitle />
|
||||
<GlobalKeybindingHandlers />
|
||||
<ScrollKeybindingHandler />
|
||||
<CancelRequestHandler />
|
||||
<FullscreenLayout
|
||||
scrollable={<Messages />}
|
||||
bottom={<TranscriptSearchBar /> 或 <TranscriptModeFooter />}
|
||||
/>
|
||||
</KeybindingSetup>
|
||||
```
|
||||
|
||||
#### Prompt 模式（第 4552-5009 行）
|
||||
|
||||
主交互界面，从上到下：
|
||||
|
||||
```tsx
|
||||
<KeybindingSetup>
|
||||
<AnimatedTerminalTitle /> // 终端 tab 标题
|
||||
<GlobalKeybindingHandlers /> // 全局快捷键
|
||||
<CommandKeybindingHandlers /> // 命令快捷键
|
||||
<ScrollKeybindingHandler /> // 滚动快捷键
|
||||
<CancelRequestHandler /> // Ctrl+C 取消
|
||||
<MCPConnectionManager> // MCP 连接管理
|
||||
<FullscreenLayout
|
||||
overlay={<PermissionRequest />} // 权限审批覆盖层
|
||||
scrollable={ // 可滚动区域
|
||||
<>
|
||||
<Messages /> // ★ 对话消息渲染
|
||||
<UserTextMessage /> // 用户输入占位
|
||||
{toolJSX} // 工具 UI
|
||||
<SpinnerWithVerb /> // 加载动画
|
||||
</>
|
||||
}
|
||||
bottom={ // 固定底部
|
||||
<>
|
||||
{/* 各种对话框 */}
|
||||
<SandboxPermissionRequest />
|
||||
<PromptDialog />
|
||||
<ElicitationDialog />
|
||||
<CostThresholdDialog />
|
||||
<FeedbackSurvey />
|
||||
|
||||
{/* ★ 用户输入框 */}
|
||||
<PromptInput
|
||||
onSubmit={onSubmit}
|
||||
commands={commands}
|
||||
isLoading={isLoading}
|
||||
messages={messages}
|
||||
// ... 20+ props
|
||||
/>
|
||||
</>
|
||||
}
|
||||
/>
|
||||
</MCPConnectionManager>
|
||||
</KeybindingSetup>
|
||||
```
|
||||
|
||||
### 4.7 REPL.tsx 学习建议
|
||||
|
||||
- 核心只有一条线：`onSubmit → onQuery → query() → onQueryEvent → 更新消息`
|
||||
- 其余 4000+ 行是 UI 细节：快捷键、对话框、动画、边界情况处理
|
||||
- `feature('...')` 保护的 JSX 全部跳过
|
||||
- `("external" as string) === 'ant'` 的分支也跳过
|
||||
|
||||
---
|
||||
|
||||
## 关键设计模式总结
|
||||
|
||||
| 模式 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| 快速路径 | cli.tsx | 按开销从低到高逐级检查，零开销处理简单请求 |
|
||||
| 动态 import | cli.tsx / main.tsx | `await import()` 延迟加载，每条路径只加载需要的模块 |
|
||||
| Side-effect import | main.tsx 顶部 | import 阶段就并行启动子进程，用并行隐藏延迟 |
|
||||
| feature flag | 全局 | `feature()` 永远返回 false，编译时消除死代码 |
|
||||
| preAction 钩子 | main.tsx run() | Commander.js 命令执行前统一初始化 |
|
||||
| QueryGuard | REPL.tsx | 状态机防止并发 API 请求，带 generation 计数防竞态 |
|
||||
| React/Ink | UI 层 | 用 React 组件模型渲染终端 UI，支持全屏和虚拟滚动 |
|
||||
|
||||
## 需要忽略的代码模式
|
||||
|
||||
| 模式 | 来源 | 说明 |
|
||||
|------|------|------|
|
||||
| `_c(N)` 调用 | React Compiler | 反编译产生的 memoization 样板代码 |
|
||||
| `feature('FLAG')` 后面的代码 | Bun bundler | 全部是死代码，在当前版本不会执行 |
|
||||
| `("external" as string) === 'ant'` | 构建目标检查 | 永远为 false（external !== ant） |
|
||||
| tsc 类型错误 | 反编译 | `unknown`/`never`/`{}` 类型，不影响 Bun 运行 |
|
||||
| `packages/@ant/` | stub 包 | 空实现，仅满足 import 依赖 |
|
||||
@@ -1,774 +0,0 @@
|
||||
# 第二阶段：核心对话循环详解
|
||||
|
||||
> 用户发一句话后，如何变成 API 请求、如何处理流式响应和工具调用
|
||||
|
||||
## 对话循环总览
|
||||
|
||||
```
|
||||
用户输入 "帮我读取 README.md"
|
||||
│
|
||||
▼
|
||||
REPL.tsx: onSubmit → onQuery → onQueryImpl
|
||||
│
|
||||
├── 1. 并行加载上下文:
|
||||
│ getSystemPrompt() + getUserContext() + getSystemContext()
|
||||
│
|
||||
├── 2. buildEffectiveSystemPrompt() — 合成最终系统提示
|
||||
│
|
||||
├── 3. for await (const event of query({...})) ★ 核心循环
|
||||
│ │
|
||||
│ │ query.ts: queryLoop()
|
||||
│ │ ├── while (true) {
|
||||
│ │ │ ├── autocompact / microcompact 处理
|
||||
│ │ │ ├── deps.callModel() → claude.ts 流式 API 调用
|
||||
│ │ │ │ └── for await (message of stream) { yield message }
|
||||
│ │ │ │
|
||||
│ │ │ ├── 收集 assistant 消息中的 tool_use 块
|
||||
│ │ │ │
|
||||
│ │ │ ├── needsFollowUp?
|
||||
│ │ │ │ ├── true → 执行工具 → 收集结果 → state = next → continue
|
||||
│ │ │ │ └── false → 检查错误恢复 → return { reason: 'completed' }
|
||||
│ │ │ }
|
||||
│ │
|
||||
│ └── onQueryEvent(event) — 更新 UI 状态
|
||||
│
|
||||
└── 4. 收尾: resetLoadingState(), onTurnComplete()
|
||||
```
|
||||
|
||||
### 两条数据路径
|
||||
|
||||
| 路径 | 调用方 | 说明 |
|
||||
|------|--------|------|
|
||||
| **交互式（REPL）** | REPL.tsx → `query()` | 直接调用 `query()` AsyncGenerator |
|
||||
| **非交互式（SDK/print）** | print.ts → `QueryEngine.submitMessage()` → `query()` | 通过 QueryEngine 包装，增加了会话持久化、usage 跟踪等 |
|
||||
|
||||
---
|
||||
|
||||
## 1. query.ts（1732 行）— 核心查询循环
|
||||
|
||||
**文件路径**: `src/query.ts`
|
||||
|
||||
### 1.1 文件结构
|
||||
|
||||
```
|
||||
query.ts (1732 行)
|
||||
├── [0-120] Import 区 + feature flag 条件模块加载
|
||||
├── [122-148] yieldMissingToolResultBlocks() — 为未配对的 tool_use 生成错误 tool_result
|
||||
├── [150-178] 常量与辅助函数 (MAX_OUTPUT_TOKENS_RECOVERY_LIMIT, isWithheldMaxOutputTokens)
|
||||
├── [180-198] QueryParams 类型定义
|
||||
├── [200-216] State 类型 — 循环迭代间的可变状态
|
||||
├── [218-238] query() — 导出的 AsyncGenerator，委托给 queryLoop()
|
||||
├── [240-1732] queryLoop() — 核心 while(true) 循环
|
||||
│ ├── [241-306] 初始化 State + 内存预取
|
||||
│ ├── [307-448] 循环开头：解构 state、消息预处理（snip/microcompact/context collapse）
|
||||
│ ├── [449-578] 系统提示构建(第449行) + autocompact(第453行) + StreamingToolExecutor 初始化(第562行)
|
||||
│ ├── [650-866] ★ deps.callModel()(第659行) + 流式响应处理 + tool_use 收集
|
||||
│ ├── [896-956] 错误处理（FallbackTriggeredError、通用错误）
|
||||
│ ├── [1002-1054] 中断处理（abortController.signal.aborted）
|
||||
│ ├── [1065-1360] 无 followUp 时的终止/恢复逻辑
|
||||
│ │ ├── prompt-too-long 恢复
|
||||
│ │ ├── max_output_tokens 恢复（升级 + 多轮）
|
||||
│ │ ├── stop hooks 执行
|
||||
│ │ └── return { reason: 'completed' }
|
||||
│ └── [1360-1732] 有 followUp 时的工具执行 + 下一轮准备
|
||||
│ ├── 工具执行（streaming 或 sequential）
|
||||
│ ├── attachment 注入（排队命令、内存预取、技能发现）
|
||||
│ ├── maxTurns 检查
|
||||
│ └── state = next → continue
|
||||
```
|
||||
|
||||
### 1.2 入口：query() 函数（第 219 行）
|
||||
|
||||
```ts
|
||||
export async function* query(params: QueryParams):
|
||||
AsyncGenerator<StreamEvent | Message | ..., Terminal> {
|
||||
const consumedCommandUuids: string[] = []
|
||||
const terminal = yield* queryLoop(params, consumedCommandUuids)
|
||||
// 通知所有消费的排队命令已完成
|
||||
for (const uuid of consumedCommandUuids) {
|
||||
notifyCommandLifecycle(uuid, 'completed')
|
||||
}
|
||||
return terminal
|
||||
}
|
||||
```
|
||||
|
||||
`query()` 本身很薄，只做两件事：
|
||||
1. 委托给 `queryLoop()` 执行实际逻辑
|
||||
2. 在正常返回后通知排队命令的生命周期
|
||||
|
||||
### 1.3 QueryParams（第 181 行）
|
||||
|
||||
```ts
|
||||
type QueryParams = {
|
||||
messages: Message[] // 当前对话消息
|
||||
systemPrompt: SystemPrompt // 系统提示
|
||||
userContext: { [k: string]: string } // 用户上下文（CLAUDE.md 等）
|
||||
systemContext: { [k: string]: string } // 系统上下文（git 状态等）
|
||||
canUseTool: CanUseToolFn // 工具权限检查函数
|
||||
toolUseContext: ToolUseContext // 工具执行上下文
|
||||
fallbackModel?: string // 备用模型
|
||||
querySource: QuerySource // 查询来源标识
|
||||
maxTurns?: number // 最大轮次限制
|
||||
taskBudget?: { total: number } // 令牌预算
|
||||
}
|
||||
```
|
||||
|
||||
### 1.4 State — 循环迭代间的可变状态（第 204 行）
|
||||
|
||||
```ts
|
||||
type State = {
|
||||
messages: Message[] // 累积的消息列表
|
||||
toolUseContext: ToolUseContext // 工具执行上下文
|
||||
autoCompactTracking: ... // 自动压缩跟踪
|
||||
maxOutputTokensRecoveryCount: number // 输出令牌恢复尝试次数
|
||||
hasAttemptedReactiveCompact: boolean // 是否已尝试响应式压缩
|
||||
maxOutputTokensOverride: number | undefined // 输出令牌覆盖
|
||||
pendingToolUseSummary: Promise<...> // 待处理的工具使用摘要
|
||||
stopHookActive: boolean | undefined // stop hook 是否活跃
|
||||
turnCount: number // 当前轮次
|
||||
transition: Continue | undefined // 上一次迭代为何 continue
|
||||
}
|
||||
```
|
||||
|
||||
**设计关键**：每次 `continue` 时通过 `state = { ... }` 一次性更新所有状态，而不是分散的 9 个赋值。`transition` 字段记录了为什么要继续循环（便于调试和测试）。
|
||||
|
||||
### 1.5 queryLoop() 核心流程（第 241 行）
|
||||
|
||||
`while (true)` 循环（第 307 行）的每次迭代代表一次 API 调用。循环直到：
|
||||
- 模型不需要工具调用 → `return { reason: 'completed' }`
|
||||
- 被用户中断 → `return { reason: 'aborted_*' }`
|
||||
- 达到最大轮次 → `return { reason: 'max_turns' }`
|
||||
- 遇到不可恢复的错误 → `return { reason: 'model_error' }`
|
||||
|
||||
#### 步骤 1：消息预处理
|
||||
|
||||
```
|
||||
每次迭代开头:
|
||||
├── 解构 state → messages, toolUseContext, tracking, ...
|
||||
├── getMessagesAfterCompactBoundary() — 只保留压缩边界后的消息
|
||||
├── snip 处理（feature flag，跳过）
|
||||
├── microcompact 处理（feature flag，跳过）
|
||||
└── autocompact 检查 — 消息过长时自动压缩
|
||||
```
|
||||
|
||||
#### 步骤 2：系统提示构建（第 449 行）
|
||||
|
||||
```ts
|
||||
const fullSystemPrompt = asSystemPrompt(
|
||||
appendSystemContext(systemPrompt, systemContext),
|
||||
)
|
||||
```
|
||||
|
||||
将系统上下文（git 状态、日期等）追加到系统提示。注意：用户上下文（CLAUDE.md 等）不在这里注入，而是在 `deps.callModel()` 调用时通过 `prependUserContext(messagesForQuery, userContext)` 注入到消息数组的最前面（第 660 行）。
|
||||
|
||||
#### 步骤 3：Autocompact（第 454-543 行）
|
||||
|
||||
当消息历史过长时自动压缩：
|
||||
|
||||
```
|
||||
autocompact 流程:
|
||||
├── 检查 token 数量是否超过阈值
|
||||
├── 超过 → 调用 compact API（用 Haiku 总结历史）
|
||||
│ ├── yield compactBoundaryMessage ← 标记压缩边界
|
||||
│ └── 更新 messages 为压缩后的版本
|
||||
└── 未超过 → 继续
|
||||
```
|
||||
|
||||
#### 步骤 4：调用 API（第 559-708 行）— 核心
|
||||
|
||||
StreamingToolExecutor 在第 562 行初始化，API 调用在第 659 行开始：
|
||||
|
||||
```ts
|
||||
// 第 562 行：初始化流式工具执行器
|
||||
let streamingToolExecutor = useStreamingToolExecution
|
||||
? new StreamingToolExecutor(
|
||||
toolUseContext.options.tools, canUseTool, toolUseContext,
|
||||
)
|
||||
: null
|
||||
|
||||
// 第 659 行：调用 API
|
||||
for await (const message of deps.callModel({
|
||||
messages: prependUserContext(messagesForQuery, userContext), // ← 用户上下文注入到消息最前面
|
||||
systemPrompt: fullSystemPrompt,
|
||||
thinkingConfig: toolUseContext.options.thinkingConfig,
|
||||
tools: toolUseContext.options.tools,
|
||||
signal: toolUseContext.abortController.signal,
|
||||
options: { model: currentModel, querySource, fallbackModel, ... }
|
||||
})) {
|
||||
// 处理每条流式消息（第 708-866 行）
|
||||
}
|
||||
```
|
||||
|
||||
`deps.callModel()` 最终调用 `claude.ts` 的 `queryModelWithStreaming()`。
|
||||
|
||||
#### 步骤 5：流式响应处理（第 708-866 行）
|
||||
|
||||
处理逻辑在 `for await` 循环体内（第 708 行的 `})` 之后到第 866 行）：
|
||||
|
||||
```
|
||||
for await (const message of stream):
|
||||
├── message.type === 'assistant'?
|
||||
│ ├── 记录到 assistantMessages[]
|
||||
│ ├── 提取 tool_use 块 → toolUseBlocks[]
|
||||
│ ├── needsFollowUp = true（如果有 tool_use）
|
||||
│ └── streamingToolExecutor.addTool() ← 流式工具并行执行
|
||||
│
|
||||
├── withheld? (prompt-too-long / max_output_tokens)
|
||||
│ └── 暂扣不 yield，等后面恢复逻辑处理
|
||||
│
|
||||
└── yield message ← 正常 yield 给上层（REPL/QueryEngine）
|
||||
```
|
||||
|
||||
**StreamingToolExecutor**：在 API 流式返回的同时就开始执行工具（如读文件），不等流结束。通过 `addTool()` 添加待执行工具，`getCompletedResults()` 获取已完成的结果。
|
||||
|
||||
#### 步骤 6A：无 followUp — 终止/恢复（第 1065-1360 行）
|
||||
|
||||
当模型没有请求工具调用时（`needsFollowUp === false`）：
|
||||
|
||||
```
|
||||
无 followUp:
|
||||
├── prompt-too-long 恢复?
|
||||
│ ├── context collapse drain（feature flag，跳过）
|
||||
│ ├── reactive compact → 压缩消息重试
|
||||
│ └── 都失败 → yield 错误 + return
|
||||
│
|
||||
├── max_output_tokens 恢复?
|
||||
│ ├── 第一次 → 升级到 64k token 限制，continue
|
||||
│ ├── 后续 → 注入恢复消息（"继续，别道歉"），continue
|
||||
│ └── 超过 3 次 → yield 错误 + return
|
||||
│
|
||||
├── stop hooks 执行
|
||||
│ ├── preventContinuation? → return
|
||||
│ └── blockingErrors? → 将错误加入消息，continue
|
||||
│
|
||||
└── return { reason: 'completed' } ★ 正常结束
|
||||
```
|
||||
|
||||
**恢复消息内容（第 1229 行）**：
|
||||
```
|
||||
"Output token limit hit. Resume directly — no apology, no recap of what
|
||||
you were doing. Pick up mid-thought if that is where the cut happened.
|
||||
Break remaining work into smaller pieces."
|
||||
```
|
||||
|
||||
#### 步骤 6B：有 followUp — 工具执行 + 下一轮（第 1363-1731 行）
|
||||
|
||||
当模型请求了工具调用时（`needsFollowUp === true`）：
|
||||
|
||||
```
|
||||
有 followUp:
|
||||
├── 工具执行（两种模式）
|
||||
│ ├── streamingToolExecutor? → getRemainingResults()（流式已启动）
|
||||
│ └── 否 → runTools()（传统顺序执行）
|
||||
│
|
||||
├── for await (const update of toolUpdates):
|
||||
│ ├── yield update.message ← 工具结果消息
|
||||
│ └── toolResults.push(...) ← 收集工具结果
|
||||
│
|
||||
├── 中断检查（abortController.signal.aborted）
|
||||
│ └── return { reason: 'aborted_tools' }
|
||||
│
|
||||
├── attachment 注入
|
||||
│ ├── 排队命令（其他线程提交的消息）
|
||||
│ ├── 内存预取（相关记忆文件）
|
||||
│ └── 技能发现预取
|
||||
│
|
||||
├── maxTurns 检查
|
||||
│ └── 超过 → yield max_turns_reached + return
|
||||
│
|
||||
└── state = { messages: [...old, ...assistant, ...toolResults], turnCount: +1 }
|
||||
→ continue ★ 回到循环顶部，发起下一次 API 调用
|
||||
```
|
||||
|
||||
### 1.6 错误处理与模型降级（第 897-956 行）
|
||||
|
||||
```
|
||||
API 调用出错:
|
||||
├── FallbackTriggeredError（529 过载）?
|
||||
│ ├── 切换到 fallbackModel
|
||||
│ ├── 清空本轮 assistant/tool 消息
|
||||
│ ├── yield 系统消息 "Switched to X due to high demand for Y"
|
||||
│ └── continue（重试整个请求）
|
||||
│
|
||||
└── 其他错误
|
||||
├── ImageSizeError/ImageResizeError → yield 友好错误 + return
|
||||
├── yieldMissingToolResultBlocks() — 补全未配对的 tool_result
|
||||
└── yield API 错误消息 + return
|
||||
```
|
||||
|
||||
### 1.7 关键设计思想
|
||||
|
||||
| 设计 | 说明 |
|
||||
|------|------|
|
||||
| **AsyncGenerator 模式** | `query()` 是 `async function*`，通过 `yield` 逐条产出事件，调用者用 `for await` 消费 |
|
||||
| **while(true) + state 对象** | 每次 `continue` 构建新 State 对象，避免分散的状态修改 |
|
||||
| **transition 字段** | 记录为什么要 continue（`next_turn`、`max_output_tokens_recovery`、`reactive_compact_retry`...），便于调试 |
|
||||
| **StreamingToolExecutor** | API 流式返回时就并行执行工具，不等流结束 |
|
||||
| **Withheld 消息** | 可恢复错误先暂扣，恢复成功则不 yield 错误，失败才 yield |
|
||||
|
||||
---
|
||||
|
||||
## 2. QueryEngine.ts（1320 行）— 高层编排器
|
||||
|
||||
**文件路径**: `src/QueryEngine.ts`
|
||||
|
||||
### 2.1 定位
|
||||
|
||||
QueryEngine 是 `query()` 的**上层包装**，主要用于：
|
||||
- **print 模式**（`claude -p`）：通过 `ask()` → `QueryEngine.submitMessage()`
|
||||
- **SDK 模式**：外部程序通过 SDK 调用
|
||||
- **REPL 不用它**：REPL 直接调用 `query()`
|
||||
|
||||
### 2.2 文件结构
|
||||
|
||||
```
|
||||
QueryEngine.ts (1320 行)
|
||||
├── [0-130] Import 区 + feature flag 条件模块
|
||||
├── [131-174] QueryEngineConfig 类型定义
|
||||
├── [185-1202] QueryEngine 类
|
||||
│ ├── [185-208] 成员变量 + constructor
|
||||
│ ├── [210-1181] submitMessage() — 核心方法（~970 行）
|
||||
│ │ ├── [210-400] 参数解析 + processUserInputContext 构建
|
||||
│ │ ├── [400-465] 用户输入处理 + 会话持久化
|
||||
│ │ ├── [465-660] 斜杠命令处理 + 无需查询的快速返回
|
||||
│ │ ├── [660-690] 文件历史快照
|
||||
│ │ ├── [679-1074] ★ for await (const message of query({...})) — 消费 query()
|
||||
│ │ └── [1074-1181] 结果提取 + yield result
|
||||
│ ├── [1183-1202] interrupt() / getMessages() / setModel() 辅助方法
|
||||
├── [1210-1320] ask() — 便捷包装函数
|
||||
```
|
||||
|
||||
### 2.3 QueryEngineConfig
|
||||
|
||||
```ts
|
||||
type QueryEngineConfig = {
|
||||
cwd: string // 工作目录
|
||||
tools: Tools // 工具列表
|
||||
commands: Command[] // 斜杠命令
|
||||
mcpClients: MCPServerConnection[] // MCP 服务器连接
|
||||
agents: AgentDefinition[] // Agent 定义
|
||||
canUseTool: CanUseToolFn // 权限检查
|
||||
getAppState / setAppState // 全局状态存取
|
||||
initialMessages?: Message[] // 初始消息（恢复对话）
|
||||
readFileCache: FileStateCache // 文件读取缓存
|
||||
customSystemPrompt?: string // 自定义系统提示
|
||||
thinkingConfig?: ThinkingConfig // 思考模式配置
|
||||
maxTurns?: number // 最大轮次
|
||||
maxBudgetUsd?: number // USD 预算上限
|
||||
jsonSchema?: Record<...> // 结构化输出 schema
|
||||
// ... 更多配置
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 submitMessage() 核心流程
|
||||
|
||||
```
|
||||
submitMessage(prompt)
|
||||
│
|
||||
├── 1. 参数准备
|
||||
│ ├── 解构 config 获取 tools, commands, model, ...
|
||||
│ ├── 构建 wrappedCanUseTool（包装权限检查，跟踪拒绝）
|
||||
│ ├── fetchSystemPromptParts() — 获取系统提示各部分
|
||||
│ └── 构建 processUserInputContext
|
||||
│
|
||||
├── 2. 用户输入处理
|
||||
│ ├── processUserInput(prompt) — 解析斜杠命令 / 普通文本
|
||||
│ ├── mutableMessages.push(...messagesFromUserInput)
|
||||
│ └── recordTranscript(messages) — 持久化到 JSONL
|
||||
│
|
||||
├── 3. yield buildSystemInitMessage() — SDK 初始化消息
|
||||
│
|
||||
├── 4. shouldQuery === false?（斜杠命令的本地执行结果）
|
||||
│ ├── yield 命令输出
|
||||
│ ├── yield { type: 'result', subtype: 'success' }
|
||||
│ └── return
|
||||
│
|
||||
├── 5. ★ for await (const message of query({...}))
|
||||
│ │ 消费 query() 产出的每条消息
|
||||
│ │
|
||||
│ ├── message.type === 'assistant'
|
||||
│ │ ├── mutableMessages.push(msg)
|
||||
│ │ ├── recordTranscript() ← fire-and-forget
|
||||
│ │ ├── yield* normalizeMessage(msg) — 转换为 SDK 格式
|
||||
│ │ └── 捕获 stop_reason
|
||||
│ │
|
||||
│ ├── message.type === 'user'（工具结果）
|
||||
│ │ ├── mutableMessages.push(msg)
|
||||
│ │ ├── turnCount++
|
||||
│ │ └── yield* normalizeMessage(msg)
|
||||
│ │
|
||||
│ ├── message.type === 'stream_event'
|
||||
│ │ ├── 跟踪 usage（message_start/delta/stop）
|
||||
│ │ └── includePartialMessages? → yield 流事件
|
||||
│ │
|
||||
│ ├── message.type === 'system'
|
||||
│ │ ├── compact_boundary → GC 旧消息 + yield 给 SDK
|
||||
│ │ └── api_error → yield 重试信息
|
||||
│ │
|
||||
│ └── maxBudgetUsd 检查 → 超预算则 yield error + return
|
||||
│
|
||||
└── 6. yield { type: 'result', subtype: 'success', result: textResult }
|
||||
```
|
||||
|
||||
### 2.5 ask() 便捷函数（第 1211 行）
|
||||
|
||||
```ts
|
||||
export async function* ask({ prompt, tools, ... }) {
|
||||
const engine = new QueryEngine({ ... })
|
||||
try {
|
||||
yield* engine.submitMessage(prompt)
|
||||
} finally {
|
||||
setReadFileCache(engine.getReadFileState())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`ask()` 是 `QueryEngine` 的一次性包装，创建 engine → 提交消息 → 清理。用于 `print.ts` 的 `--print` 模式。
|
||||
|
||||
### 2.6 QueryEngine vs REPL 直接调用 query()
|
||||
|
||||
| 特性 | QueryEngine (SDK/print) | REPL 直接调用 query() |
|
||||
|------|------------------------|---------------------|
|
||||
| 会话持久化 | 自动 recordTranscript | 由 useLogMessages 处理 |
|
||||
| Usage 跟踪 | 内部 totalUsage 累积 | 由外层 cost-tracker 处理 |
|
||||
| 权限拒绝跟踪 | 记录 permissionDenials[] | 直接 UI 交互 |
|
||||
| 结果格式 | yield SDKMessage 格式 | 原始 Message 格式 |
|
||||
| 消息 GC | compact_boundary 后释放旧消息 | UI 需要保留完整历史 |
|
||||
|
||||
---
|
||||
|
||||
## 3. claude.ts（3420 行）— API 客户端
|
||||
|
||||
**文件路径**: `src/services/api/claude.ts`
|
||||
|
||||
### 3.1 文件结构
|
||||
|
||||
```
|
||||
claude.ts (3420 行)
|
||||
├── [0-260] Import 区（大量 SDK 类型、工具函数）
|
||||
├── [272-331] getExtraBodyParams() — 构建额外请求体参数
|
||||
├── [333-502] 缓存相关（getPromptCachingEnabled, getCacheControl, should1hCacheTTL, configureEffortParams, configureTaskBudgetParams）
|
||||
├── [504-587] verifyApiKey() — API 密钥验证
|
||||
├── [589-675] 消息转换（userMessageToMessageParam, assistantMessageToMessageParam）
|
||||
├── [677-708] Options 类型定义
|
||||
├── [710-781] queryModelWithoutStreaming / queryModelWithStreaming — 公开的两个入口
|
||||
├── [783-813] 辅助函数（shouldDeferLspTool, getNonstreamingFallbackTimeoutMs）
|
||||
├── [819-918] executeNonStreamingRequest() — 非流式请求辅助
|
||||
├── [920-999] 更多辅助函数（getPreviousRequestIdFromMessages, stripExcessMediaItems）
|
||||
├── [1018-3420] ★ queryModel() — 核心私有函数（2400 行）
|
||||
│ ├── [1018-1370] 前置检查 + 工具 schema 构建 + 消息归一化 + 系统提示组装
|
||||
│ ├── [1539-1730] paramsFromContext() — 构建 API 请求参数
|
||||
│ ├── [1777-2100] withRetry + 流式 API 调用（anthropic.beta.messages.create + stream）
|
||||
│ ├── [1941-2300] 流式事件处理（for await of stream）
|
||||
│ └── [2300-3420] 非流式降级 + 日志、分析、清理
|
||||
```
|
||||
|
||||
### 3.2 两个公开入口
|
||||
|
||||
```ts
|
||||
// 入口 1：流式（主要路径）
|
||||
export async function* queryModelWithStreaming({
|
||||
messages, systemPrompt, thinkingConfig, tools, signal, options
|
||||
}) {
|
||||
yield* withStreamingVCR(messages, async function* () {
|
||||
yield* queryModel(messages, systemPrompt, thinkingConfig, tools, signal, options)
|
||||
})
|
||||
}
|
||||
|
||||
// 入口 2：非流式（compact 等内部用途）
|
||||
export async function queryModelWithoutStreaming({
|
||||
messages, systemPrompt, thinkingConfig, tools, signal, options
|
||||
}) {
|
||||
let assistantMessage
|
||||
for await (const message of ...) {
|
||||
if (message.type === 'assistant') assistantMessage = message
|
||||
}
|
||||
return assistantMessage
|
||||
}
|
||||
```
|
||||
|
||||
两者都委托给内部的 `queryModel()`。`withStreamingVCR` 是一个 VCR（录像/回放）包装器，用于调试。
|
||||
|
||||
### 3.3 Options 类型（第 677 行）
|
||||
|
||||
```ts
|
||||
type Options = {
|
||||
getToolPermissionContext: () => Promise<ToolPermissionContext>
|
||||
model: string // 模型名称
|
||||
toolChoice?: BetaToolChoiceTool // 强制使用特定工具
|
||||
isNonInteractiveSession: boolean // 是否非交互模式
|
||||
fallbackModel?: string // 备用模型
|
||||
querySource: QuerySource // 查询来源
|
||||
agents: AgentDefinition[] // Agent 定义
|
||||
enablePromptCaching?: boolean // 启用提示缓存
|
||||
effortValue?: EffortValue // 推理努力级别
|
||||
mcpTools: Tools // MCP 工具
|
||||
fastMode?: boolean // 快速模式
|
||||
taskBudget?: { total: number; remaining?: number } // 令牌预算
|
||||
}
|
||||
```
|
||||
|
||||
### 3.4 queryModel() 核心流程（第 1018 行）
|
||||
|
||||
这是整个 API 调用的核心，2400 行。关键步骤：
|
||||
|
||||
#### 阶段 1：前置准备（1018-1400 行）
|
||||
|
||||
```
|
||||
queryModel()
|
||||
├── off-switch 检查（Opus 过载时的全局关闭开关）
|
||||
├── beta headers 组装（getMergedBetas）
|
||||
│ ├── 基础 betas
|
||||
│ ├── advisor beta（如果启用）
|
||||
│ ├── tool search beta（如果启用）
|
||||
│ ├── cache scope beta
|
||||
│ └── effort / task budget betas
|
||||
│
|
||||
├── 工具过滤
|
||||
│ ├── tool search 启用 → 只包含已发现的 deferred tools
|
||||
│ └── tool search 未启用 → 过滤掉 ToolSearchTool
|
||||
│
|
||||
├── toolToAPISchema() — 每个工具转为 API 格式
|
||||
│
|
||||
├── normalizeMessagesForAPI() — 消息转换为 API 格式
|
||||
│ ├── UserMessage → { role: 'user', content: ... }
|
||||
│ ├── AssistantMessage → { role: 'assistant', content: ... }
|
||||
│ └── 跳过 system/attachment/progress 等内部消息类型
|
||||
│
|
||||
└── 系统提示最终组装
|
||||
├── getAttributionHeader(fingerprint)
|
||||
├── getCLISyspromptPrefix()
|
||||
├── ...systemPrompt
|
||||
└── advisor 指令（如果启用）
|
||||
```
|
||||
|
||||
#### 阶段 2：构建请求参数 — paramsFromContext()（第 1539-1730 行）
|
||||
|
||||
```ts
|
||||
const paramsFromContext = (retryContext: RetryContext) => {
|
||||
// ... 动态 beta headers、effort、task budget 配置 ...
|
||||
|
||||
// 思考模式配置（adaptive 或 enabled + budget）
|
||||
let thinking = undefined
|
||||
if (hasThinking && modelSupportsThinking(options.model)) {
|
||||
if (modelSupportsAdaptiveThinking(options.model)) {
|
||||
thinking = { type: 'adaptive' }
|
||||
} else {
|
||||
thinking = { type: 'enabled', budget_tokens: thinkingBudget }
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
model: normalizeModelStringForAPI(options.model),
|
||||
messages: addCacheBreakpoints(messagesForAPI, ...), // 带缓存标记的消息
|
||||
system, // 系统提示块（已构建好）
|
||||
tools: allTools, // 工具 schema
|
||||
tool_choice: options.toolChoice,
|
||||
max_tokens: maxOutputTokens,
|
||||
thinking,
|
||||
...(temperature !== undefined && { temperature }),
|
||||
...(useBetas && { betas: betasParams }),
|
||||
metadata: getAPIMetadata(),
|
||||
...extraBodyParams,
|
||||
...(speed !== undefined && { speed }), // 快速模式
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 阶段 3：流式 API 调用（第 1779-1858 行）
|
||||
|
||||
```ts
|
||||
// 使用 withRetry 包装，自动处理重试
|
||||
const generator = withRetry(
|
||||
() => getAnthropicClient({ maxRetries: 0, model, source: querySource }),
|
||||
async (anthropic, attempt, context) => {
|
||||
const params = paramsFromContext(context)
|
||||
|
||||
// ★ 核心 API 调用（第 1823 行）
|
||||
// 使用 .create() + stream: true（而非 .stream()）
|
||||
// 避免 BetaMessageStream 的 O(n²) partial JSON 解析开销
|
||||
const result = await anthropic.beta.messages
|
||||
.create(
|
||||
{ ...params, stream: true },
|
||||
{ signal, ...(clientRequestId && { headers: { ... } }) },
|
||||
)
|
||||
.withResponse()
|
||||
|
||||
return result.data // Stream<BetaRawMessageStreamEvent>
|
||||
},
|
||||
{ model, fallbackModel, thinkingConfig, signal, querySource }
|
||||
)
|
||||
|
||||
// 消费 withRetry 的系统错误消息（重试通知等）
|
||||
let e
|
||||
do {
|
||||
e = await generator.next()
|
||||
if (!('controller' in e.value)) yield e.value // yield API 错误消息
|
||||
} while (!e.done)
|
||||
stream = e.value // 获取最终的 Stream 对象
|
||||
|
||||
// 处理流式事件（第 1941 行）
|
||||
for await (const part of stream) {
|
||||
switch (part.type) {
|
||||
case 'message_start': // 记录 request_id、usage
|
||||
case 'content_block_start': // 新的内容块开始（text/thinking/tool_use）
|
||||
case 'content_block_delta': // 增量内容 → yield stream_event 给 UI
|
||||
case 'content_block_stop': // 内容块完成 → yield AssistantMessage
|
||||
case 'message_delta': // stop_reason、usage 更新
|
||||
case 'message_stop': // 整条消息完成
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 阶段 4：withRetry 重试策略
|
||||
|
||||
```
|
||||
withRetry 逻辑:
|
||||
├── 429 (Rate Limit) → 等待 Retry-After 后重试
|
||||
├── 529 (Overloaded) → 切换到 fallbackModel，throw FallbackTriggeredError
|
||||
├── 500 (Server Error) → 指数退避重试
|
||||
├── 408 (Timeout) → 重试
|
||||
├── 其他错误 → 不重试，直接抛出
|
||||
└── 最大重试次数: 根据模型和错误类型动态计算
|
||||
```
|
||||
|
||||
#### 阶段 5：非流式降级
|
||||
|
||||
当流式请求中途失败时，可能降级为非流式请求：
|
||||
|
||||
```
|
||||
流式失败（部分响应已收到）:
|
||||
├── 已接收的内容 → yield 给上层
|
||||
├── 剩余部分 → 降级为非流式请求（anthropic.beta.messages.create）
|
||||
└── 非流式结果 → 转换格式 yield
|
||||
```
|
||||
|
||||
### 3.5 消息转换函数
|
||||
|
||||
```ts
|
||||
// UserMessage → API 格式
|
||||
userMessageToMessageParam(message, addCache, enablePromptCaching, querySource)
|
||||
→ { role: 'user', content: [...] }
|
||||
// addCache=true 时最后一个 content block 添加 cache_control
|
||||
|
||||
// AssistantMessage → API 格式
|
||||
assistantMessageToMessageParam(message, addCache, enablePromptCaching, querySource)
|
||||
→ { role: 'assistant', content: [...] }
|
||||
// thinking/redacted_thinking 块不加 cache_control
|
||||
```
|
||||
|
||||
### 3.6 Prompt Caching 策略
|
||||
|
||||
```
|
||||
缓存策略:
|
||||
├── cache_control: { type: 'ephemeral' } — 默认，5 分钟 TTL
|
||||
├── cache_control: { type: 'ephemeral', ttl: '1h' } — 订阅用户/Ant，1 小时
|
||||
├── cache_control: { ..., scope: 'global' } — 跨会话共享（无 MCP 工具时）
|
||||
└── 禁用条件：
|
||||
├── DISABLE_PROMPT_CACHING 环境变量
|
||||
├── DISABLE_PROMPT_CACHING_HAIKU（仅 Haiku）
|
||||
└── DISABLE_PROMPT_CACHING_SONNET（仅 Sonnet）
|
||||
```
|
||||
|
||||
### 3.7 多 Provider 支持
|
||||
|
||||
`getAnthropicClient()` 根据配置返回不同的 SDK 客户端：
|
||||
|
||||
| Provider | 入口 | 说明 |
|
||||
|----------|------|------|
|
||||
| Anthropic | 直接 API | 默认，`api.anthropic.com` |
|
||||
| AWS Bedrock | 通过 Bedrock | 使用 `@anthropic-ai/bedrock-sdk` |
|
||||
| Google Vertex | 通过 Vertex | 使用 `@anthropic-ai/vertex-sdk` |
|
||||
| Azure | 通过 Azure | 类似 Bedrock 的包装 |
|
||||
|
||||
Provider 选择逻辑在 `src/utils/model/providers.ts` 的 `getAPIProvider()` 中。
|
||||
|
||||
---
|
||||
|
||||
## 完整数据流：一次工具调用的生命周期
|
||||
|
||||
以用户输入 "读取 README.md" 为例：
|
||||
|
||||
```
|
||||
1. REPL.tsx: 用户按回车
|
||||
onSubmit("读取 README.md")
|
||||
└── handlePromptSubmit()
|
||||
└── onQuery([userMessage])
|
||||
|
||||
2. REPL.tsx: onQueryImpl()
|
||||
├── getSystemPrompt() + getUserContext() + getSystemContext()
|
||||
└── for await (event of query({messages, systemPrompt, ...}))
|
||||
|
||||
3. query.ts: queryLoop() — 第 1 次迭代
|
||||
├── messagesForQuery = [...messages] // 包含用户消息
|
||||
├── deps.callModel({...})
|
||||
│ └── claude.ts: queryModel()
|
||||
│ ├── 构建 API 参数
|
||||
│ └── anthropic.beta.messages.create({ ...params, stream: true })
|
||||
│
|
||||
├── API 流式返回:
|
||||
│ content_block_start: { type: 'tool_use', name: 'Read', id: 'toolu_123' }
|
||||
│ content_block_delta: { input: '{"file_path": "/path/to/README.md"}' }
|
||||
│ content_block_stop
|
||||
│ message_delta: { stop_reason: 'tool_use' }
|
||||
│
|
||||
├── 收集: toolUseBlocks = [{ name: 'Read', id: 'toolu_123', input: {...} }]
|
||||
├── needsFollowUp = true
|
||||
│
|
||||
├── 工具执行:
|
||||
│ streamingToolExecutor.getRemainingResults()
|
||||
│ └── Read 工具执行 → 返回文件内容
|
||||
│ yield toolResultMessage ← 包含文件内容
|
||||
│
|
||||
└── state = { messages: [...old, assistantMsg, toolResultMsg], turnCount: 2 }
|
||||
→ continue
|
||||
|
||||
4. query.ts: queryLoop() — 第 2 次迭代
|
||||
├── messagesForQuery 现在包含:
|
||||
│ [userMsg, assistantMsg(tool_use), userMsg(tool_result)]
|
||||
│
|
||||
├── deps.callModel({...}) ← 再次调用 API
|
||||
│
|
||||
├── API 返回:
|
||||
│ content_block_start: { type: 'text' }
|
||||
│ content_block_delta: { text: "README.md 的内容是..." }
|
||||
│ content_block_stop
|
||||
│ message_delta: { stop_reason: 'end_turn' }
|
||||
│
|
||||
├── toolUseBlocks = [] ← 没有工具调用
|
||||
├── needsFollowUp = false
|
||||
│
|
||||
└── return { reason: 'completed' } ★ 循环结束
|
||||
|
||||
5. REPL.tsx: onQueryEvent(event)
|
||||
├── 更新 streamingText（打字机效果）
|
||||
├── 更新 messages 数组
|
||||
└── 重新渲染 UI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键设计模式总结
|
||||
|
||||
| 模式 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| AsyncGenerator 链式传递 | query.ts → claude.ts | `yield*` 将底层事件透传给上层，形成事件流管道 |
|
||||
| while(true) + State 对象 | query.ts queryLoop | 循环迭代间通过不可变 State 传递，transition 字段记录原因 |
|
||||
| StreamingToolExecutor | query.ts | API 流式返回时并行执行工具，不等流结束 |
|
||||
| Withheld 消息 | query.ts | 可恢复错误先暂扣不 yield，恢复成功则吞掉错误 |
|
||||
| withRetry 重试 | claude.ts | 429/500/529 自动重试，529 触发模型降级 |
|
||||
| Prompt Caching | claude.ts | 缓存系统提示和历史消息，减少 API token 消耗 |
|
||||
| 非流式降级 | claude.ts | 流式请求中途失败时降级为非流式完成剩余部分 |
|
||||
| QueryEngine 包装 | QueryEngine.ts | 为 SDK/print 提供会话管理、持久化、usage 跟踪 |
|
||||
|
||||
## 需要忽略的代码
|
||||
|
||||
| 模式 | 说明 |
|
||||
|------|------|
|
||||
| `feature('REACTIVE_COMPACT')` / `feature('CONTEXT_COLLAPSE')` 等 | 所有 feature flag 保护的代码 — 全部是死代码 |
|
||||
| `feature('CACHED_MICROCOMPACT')` | 缓存微压缩 — 死代码 |
|
||||
| `feature('HISTORY_SNIP')` / `snipModule` | 历史截断 — 死代码 |
|
||||
| `feature('TOKEN_BUDGET')` / `budgetTracker` | 令牌预算 — 死代码 |
|
||||
| `feature('BG_SESSIONS')` / `taskSummaryModule` | 后台会话 — 死代码 |
|
||||
| `process.env.USER_TYPE === 'ant'` | Anthropic 内部专用代码 |
|
||||
| VCR (withStreamingVCR/withVCR) | 调试录像/回放包装器，不影响正常流程 |
|
||||
@@ -1,372 +0,0 @@
|
||||
# 第二阶段 Q&A
|
||||
|
||||
## Q1：query.ts 的流式消息处理具体是怎样的？
|
||||
|
||||
**核心问题**：`deps.callModel()` yield 出的每一条消息，在 `queryLoop()` 的 `for await` 循环体（L659-866）中具体经历了什么处理？
|
||||
|
||||
### 场景
|
||||
|
||||
用户说：**"帮我看看 package.json 的内容"**
|
||||
|
||||
模型回复：一段文字 "我来读取文件。" + 一个 Read 工具调用。
|
||||
|
||||
### callModel yield 的完整消息序列
|
||||
|
||||
claude.ts 的 `queryModel()` 会 yield 两种类型的消息：
|
||||
|
||||
| 类型标记 | 含义 | 产出时机 |
|
||||
|---------|------|---------|
|
||||
| `stream_event` | 原始 SSE 事件包装 | 每个 SSE 事件都产出一条 |
|
||||
| `assistant` | 完整的 AssistantMessage | 仅在 `content_block_stop` 时产出 |
|
||||
|
||||
本例中 callModel 依次 yield **共 13 条消息**：
|
||||
|
||||
```
|
||||
#1 { type: 'stream_event', event: { type: 'message_start', ... }, ttftMs: 342 }
|
||||
#2 { type: 'stream_event', event: { type: 'content_block_start', index: 0, content_block: { type: 'text' } } }
|
||||
#3 { type: 'stream_event', event: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: '我来' } } }
|
||||
#4 { type: 'stream_event', event: { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: '读取文件。' } } }
|
||||
#5 { type: 'stream_event', event: { type: 'content_block_stop', index: 0 } }
|
||||
#6 { type: 'assistant', uuid: 'uuid-1', message: { content: [{ type: 'text', text: '我来读取文件。' }], stop_reason: null } }
|
||||
#7 { type: 'stream_event', event: { type: 'content_block_start', index: 1, content_block: { type: 'tool_use', id: 'toolu_001', name: 'Read' } } }
|
||||
#8 { type: 'stream_event', event: { type: 'content_block_delta', index: 1, delta: { type: 'input_json_delta', partial_json: '{"file_path":' } } }
|
||||
#9 { type: 'stream_event', event: { type: 'content_block_delta', index: 1, delta: { type: 'input_json_delta', partial_json: '"/path/package.json"}' } } }
|
||||
#10 { type: 'stream_event', event: { type: 'content_block_stop', index: 1 } }
|
||||
#11 { type: 'assistant', uuid: 'uuid-2', message: { content: [{ type: 'tool_use', id: 'toolu_001', name: 'Read', input: { file_path: '/path/package.json' } }], stop_reason: null } }
|
||||
#12 { type: 'stream_event', event: { type: 'message_delta', delta: { stop_reason: 'tool_use' }, usage: { output_tokens: 87 } } }
|
||||
#13 { type: 'stream_event', event: { type: 'message_stop' } }
|
||||
```
|
||||
|
||||
注意 `#6` 和 `#11` 是 **assistant 类型**（content_block_stop 时由 claude.ts 组装），其余全是 **stream_event 类型**。
|
||||
|
||||
### 循环体结构
|
||||
|
||||
循环体在 L708-866，结构如下：
|
||||
|
||||
```
|
||||
for await (const message of deps.callModel({...})) { // L659
|
||||
// A. 降级检查 (L712)
|
||||
// B. backfill (L747-789)
|
||||
// C. withheld 检查 (L801-824)
|
||||
// D. yield (L825-827)
|
||||
// E. assistant 收集 + addTool (L828-848)
|
||||
// F. getCompletedResults (L850-865)
|
||||
}
|
||||
```
|
||||
|
||||
### 逐条走循环体
|
||||
|
||||
#### #1 stream_event (message_start)
|
||||
|
||||
```
|
||||
A. L712: streamingFallbackOccured = false → 跳过
|
||||
|
||||
B. L748: message.type === 'assistant'?
|
||||
→ 'stream_event' !== 'assistant' → 跳过整个 backfill 块
|
||||
|
||||
C. L801-824: withheld 检查
|
||||
→ 不是 assistant 类型，各项检查均为 false → withheld = false
|
||||
|
||||
D. L825: yield message ✅ → 透传给 REPL（REPL 记录 ttftMs）
|
||||
|
||||
E. L828: message.type === 'assistant'? → 否 → 跳过
|
||||
|
||||
F. L850-854: streamingToolExecutor.getCompletedResults()
|
||||
→ tools 数组为空 → 无结果
|
||||
```
|
||||
|
||||
**净效果**：`yield` 透传。
|
||||
|
||||
---
|
||||
|
||||
#### #2 stream_event (content_block_start, type: text)
|
||||
|
||||
```
|
||||
A-C. 同 #1
|
||||
D. yield message ✅ → REPL 设置 spinner 为 "Responding..."
|
||||
E-F. 同 #1
|
||||
```
|
||||
|
||||
**净效果**：`yield` 透传。
|
||||
|
||||
---
|
||||
|
||||
#### #3 stream_event (text_delta: "我来")
|
||||
|
||||
```
|
||||
A-C. 同 #1
|
||||
D. yield message ✅ → REPL 追加 streamingText += "我来"（打字机效果）
|
||||
E-F. 同 #1
|
||||
```
|
||||
|
||||
**净效果**：`yield` 透传。
|
||||
|
||||
---
|
||||
|
||||
#### #4 stream_event (text_delta: "读取文件。")
|
||||
|
||||
```
|
||||
同 #3
|
||||
D. yield message ✅ → REPL streamingText += "读取文件。"
|
||||
```
|
||||
|
||||
**净效果**：`yield` 透传。
|
||||
|
||||
---
|
||||
|
||||
#### #5 stream_event (content_block_stop, index:0)
|
||||
|
||||
```
|
||||
同 #2
|
||||
D. yield message ✅ → REPL 无特殊操作（真正的 AssistantMessage 在下一条 #6）
|
||||
```
|
||||
|
||||
**净效果**：`yield` 透传。
|
||||
|
||||
---
|
||||
|
||||
#### #6 assistant (text block 完整消息) ★
|
||||
|
||||
第一条 `type: 'assistant'` 的消息，走**完全不同的路径**：
|
||||
|
||||
```
|
||||
A. L712: streamingFallbackOccured = false → 跳过
|
||||
|
||||
B. L748: message.type === 'assistant'? → ✅ 进入 backfill
|
||||
L750: contentArr = [{ type: 'text', text: '我来读取文件。' }]
|
||||
L752: for i=0: block.type === 'text'
|
||||
L754: block.type === 'tool_use'? → 否 → 跳过
|
||||
L783: clonedContent 为 undefined → yieldMessage = message（原样不变）
|
||||
|
||||
C. L801: let withheld = false
|
||||
L802: feature('CONTEXT_COLLAPSE') → false → 跳过
|
||||
L813: reactiveCompact?.isWithheldPromptTooLong(message) → 否 → false
|
||||
L822: isWithheldMaxOutputTokens(message)
|
||||
→ message.message.stop_reason === null → false
|
||||
→ withheld = false
|
||||
|
||||
D. L825: yield message ✅ → REPL 清除 streamingText，添加完整 text 消息到列表
|
||||
|
||||
E. L828: message.type === 'assistant'? → ✅
|
||||
L830: assistantMessages.push(message)
|
||||
→ assistantMessages = [uuid-1(text)]
|
||||
|
||||
L832-834: msgToolUseBlocks = content.filter(type === 'tool_use')
|
||||
→ []（这是 text block，没有 tool_use）
|
||||
|
||||
L835: length > 0? → 否 → 不设 needsFollowUp
|
||||
L844: msgToolUseBlocks 为空 → 不调用 addTool
|
||||
|
||||
F. L854: getCompletedResults() → 空
|
||||
```
|
||||
|
||||
**净效果**：`yield` 消息 + `assistantMessages` 增加一条。`needsFollowUp` 仍为 `false`。
|
||||
|
||||
---
|
||||
|
||||
#### #7 stream_event (content_block_start, tool_use: Read)
|
||||
|
||||
```
|
||||
A-C. 同 stream_event 通用路径
|
||||
D. yield message ✅ → REPL 设置 spinner 为 "tool-input"，添加 streamingToolUse
|
||||
E. 不是 assistant → 跳过
|
||||
F. getCompletedResults() → 空
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### #8 stream_event (input_json_delta: `'{"file_path":'`)
|
||||
|
||||
```
|
||||
D. yield message ✅ → REPL 追加工具输入 JSON 碎片
|
||||
F. getCompletedResults() → 空
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### #9 stream_event (input_json_delta: '"/path/package.json"}')
|
||||
|
||||
```
|
||||
D. yield message ✅
|
||||
F. getCompletedResults() → 空
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### #10 stream_event (content_block_stop, index:1)
|
||||
|
||||
```
|
||||
D. yield message ✅
|
||||
F. getCompletedResults() → 空
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### #11 assistant (tool_use block 完整消息) ★★
|
||||
|
||||
这条是**最关键的**——触发工具执行：
|
||||
|
||||
```
|
||||
A. L712: streamingFallbackOccured = false → 跳过
|
||||
|
||||
B. L748: message.type === 'assistant'? → ✅ 进入 backfill
|
||||
L750: contentArr = [{ type: 'tool_use', id: 'toolu_001', name: 'Read',
|
||||
input: { file_path: '/path/package.json' } }]
|
||||
L752: for i=0:
|
||||
L754: block.type === 'tool_use'? → ✅
|
||||
L756: typeof block.input === 'object' && !== null? → ✅
|
||||
L759: tool = findToolByName(tools, 'Read') → Read 工具定义
|
||||
L763: tool.backfillObservableInput 存在? → 假设存在
|
||||
L764-766: inputCopy = { file_path: '/path/package.json' }
|
||||
tool.backfillObservableInput(inputCopy)
|
||||
→ 可能添加 absolutePath 字段
|
||||
L773-776: addedFields? → 假设有新增字段
|
||||
clonedContent = [...contentArr]
|
||||
clonedContent[0] = { ...block, input: inputCopy }
|
||||
L783-788: yieldMessage = {
|
||||
...message, // uuid, type, timestamp 不变
|
||||
message: {
|
||||
...message.message, // stop_reason, usage 不变
|
||||
content: clonedContent // ★ 替换为带 absolutePath 的副本
|
||||
}
|
||||
}
|
||||
// ★ 原始 message 保持不变（回传 API 保证缓存一致）
|
||||
|
||||
C. L801-824: withheld 检查 → 全部 false → withheld = false
|
||||
|
||||
D. L825: yield yieldMessage ✅
|
||||
→ yield 的是克隆版（带 backfill 字段），给 REPL 和 SDK 用
|
||||
→ 原始 message 下面存进 assistantMessages，回传 API 保证缓存一致
|
||||
|
||||
E. L828: message.type === 'assistant'? → ✅
|
||||
L830: assistantMessages.push(message) // ★ push 原始 message，不是 yieldMessage
|
||||
→ assistantMessages = [uuid-1(text), uuid-2(tool_use)]
|
||||
|
||||
L832-834: msgToolUseBlocks = content.filter(type === 'tool_use')
|
||||
→ [{ type: 'tool_use', id: 'toolu_001', name: 'Read', input: {...} }]
|
||||
|
||||
L835: length > 0? → ✅
|
||||
L836: toolUseBlocks.push(...msgToolUseBlocks)
|
||||
→ toolUseBlocks = [Read_block]
|
||||
L837: needsFollowUp = true // ★★★ 决定 while(true) 不会终止
|
||||
|
||||
L840-842: streamingToolExecutor 存在 ✓ && !aborted ✓
|
||||
L844-846: for (const toolBlock of msgToolUseBlocks):
|
||||
streamingToolExecutor.addTool(Read_block, uuid-2消息)
|
||||
// ★★★ 工具开始执行！
|
||||
// → StreamingToolExecutor 内部：
|
||||
// isConcurrencySafe = true（Read 是安全的）
|
||||
// queued → processQueue() → canExecuteTool() → true
|
||||
// → executeTool() → runToolUse() → 后台异步读文件
|
||||
|
||||
F. L850-854: getCompletedResults()
|
||||
→ Read 刚开始执行，status = 'executing' → 无完成结果
|
||||
```
|
||||
|
||||
**净效果**：
|
||||
- `yield` 克隆消息（带 backfill 字段）
|
||||
- `assistantMessages` push 原始消息
|
||||
- `needsFollowUp = true`
|
||||
- **Read 工具在后台异步开始执行**
|
||||
|
||||
---
|
||||
|
||||
#### #12 stream_event (message_delta, stop_reason: 'tool_use')
|
||||
|
||||
```
|
||||
A-C. 同 stream_event 通用路径
|
||||
D. yield message ✅
|
||||
|
||||
E. 不是 assistant → 跳过
|
||||
|
||||
F. L854: getCompletedResults()
|
||||
→ ★ 此时 Read 可能已经完成了!（读文件通常 <1ms）
|
||||
→ 如果完成: status = 'completed', results 有值
|
||||
L428(StreamingToolExecutor): tool.status = 'yielded'
|
||||
L431-432: yield { message: UserMsg(tool_result) }
|
||||
→ 回到 query.ts:
|
||||
L855: result.message 存在
|
||||
L856: yield result.message ✅ → REPL 显示工具结果
|
||||
L857-862: toolResults.push(normalizeMessagesForAPI([result.message])...)
|
||||
→ toolResults = [Read 的 tool_result]
|
||||
```
|
||||
|
||||
**净效果**：`yield` stream_event + **可能 yield 工具结果**（如果工具已完成）。
|
||||
|
||||
---
|
||||
|
||||
#### #13 stream_event (message_stop)
|
||||
|
||||
```
|
||||
D. yield message ✅
|
||||
F. getCompletedResults()
|
||||
→ 如果 Read 在 #12 已被收割 → 空
|
||||
→ 如果 Read 此时才完成 → yield 工具结果（同 #12 的 F 逻辑）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### for await 循环退出后
|
||||
|
||||
```
|
||||
L1018: aborted? → false → 跳过
|
||||
|
||||
L1065: if (!needsFollowUp)
|
||||
→ needsFollowUp = true → 不进入 → 跳过终止逻辑
|
||||
|
||||
L1383: toolUpdates = streamingToolExecutor.getRemainingResults()
|
||||
→ 如果 Read 已在 #12/#13 被收割 → 立即返回空
|
||||
→ 如果 Read 还没完成 → 阻塞等待 → 完成后 yield 结果
|
||||
|
||||
L1387-1404: for await (const update of toolUpdates) {
|
||||
yield update.message → REPL 显示
|
||||
toolResults.push(...) → 收集
|
||||
}
|
||||
|
||||
L1718-1730: 构建 next State:
|
||||
state = {
|
||||
messages: [
|
||||
...messagesForQuery, // [UserMessage("帮我看看...")]
|
||||
...assistantMessages, // [AssistantMsg(text), AssistantMsg(tool_use)]
|
||||
...toolResults, // [UserMsg(tool_result)]
|
||||
],
|
||||
turnCount: 1,
|
||||
transition: { reason: 'next_turn' },
|
||||
}
|
||||
→ continue → while(true) 第 2 次迭代 → 带着工具结果再次调 API
|
||||
```
|
||||
|
||||
### 循环体判定树总结
|
||||
|
||||
```
|
||||
for await (const message of deps.callModel(...)) {
|
||||
│
|
||||
├─ message.type === 'stream_event'?
|
||||
│ │
|
||||
│ └─ YES → 几乎零操作
|
||||
│ ├─ yield message（透传给 REPL 做实时 UI）
|
||||
│ └─ getCompletedResults()（顺便检查有没有完成的工具）
|
||||
│
|
||||
└─ message.type === 'assistant'?
|
||||
│
|
||||
├─ B. backfill: 有 tool_use + backfillObservableInput?
|
||||
│ ├─ YES → 克隆消息，yield 克隆版（原始消息保留给 API）
|
||||
│ └─ NO → yield 原始消息
|
||||
│
|
||||
├─ C. withheld: prompt_too_long / max_output_tokens?
|
||||
│ ├─ YES → 不 yield（暂扣，等后面恢复逻辑处理）
|
||||
│ └─ NO → yield
|
||||
│
|
||||
├─ E. assistantMessages.push(原始 message)
|
||||
│
|
||||
├─ E. 有 tool_use block?
|
||||
│ ├─ YES → toolUseBlocks.push()
|
||||
│ │ + needsFollowUp = true
|
||||
│ │ + streamingToolExecutor.addTool() → ★ 立即开始执行工具
|
||||
│ └─ NO → 什么都不做
|
||||
│
|
||||
└─ F. getCompletedResults() → 收割已完成的工具结果
|
||||
}
|
||||
```
|
||||
|
||||
**一句话总结**：stream_event 透传不处理；assistant 消息才是"真正的货"——收集起来、判断要不要暂扣、有工具就立即开始执行、顺便收割已完成的工具结果。
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "claude-code-best",
|
||||
"version": "2.1.0",
|
||||
"version": "2.2.1",
|
||||
"description": "Reverse-engineered Anthropic Claude Code CLI — interactive AI coding assistant in the terminal",
|
||||
"type": "module",
|
||||
"author": "claude-code-best <claude-code-best@proton.me>",
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
import type { ToolResultBlockParam } from '@anthropic-ai/sdk/resources/index.mjs';
|
||||
import type { StructuredPatchHunk } from 'diff';
|
||||
import * as React from 'react';
|
||||
import { Suspense, use, useState } from 'react';
|
||||
import { FileEditToolUseRejectedMessage } from 'src/components/FileEditToolUseRejectedMessage.js';
|
||||
import { MessageResponse } from 'src/components/MessageResponse.js';
|
||||
import { extractTag } from 'src/utils/messages.js';
|
||||
@@ -10,10 +12,15 @@ import { Text } from '@anthropic/ink';
|
||||
import { FilePathLink } from 'src/components/FilePathLink.js';
|
||||
import type { Tools } from 'src/Tool.js';
|
||||
import type { Message, ProgressMessage } from 'src/types/message.js';
|
||||
import { adjustHunkLineNumbers, CONTEXT_LINES } from 'src/utils/diff.js';
|
||||
import { FILE_NOT_FOUND_CWD_NOTE, getDisplayPath } from 'src/utils/file.js';
|
||||
import { logError } from 'src/utils/log.js';
|
||||
import { getPlansDirectory } from 'src/utils/plans.js';
|
||||
import { readEditContext } from 'src/utils/readEditContext.js';
|
||||
import { firstLineOf } from 'src/utils/stringUtils.js';
|
||||
import type { ThemeName } from 'src/utils/theme.js';
|
||||
import type { FileEditOutput } from './types.js';
|
||||
import { findActualString, getPatchForEdit, preserveQuoteStyle } from './utils.js';
|
||||
|
||||
export function userFacingName(
|
||||
input:
|
||||
@@ -84,6 +91,8 @@ export function renderToolResultMessage(
|
||||
<FileEditToolUpdatedMessage
|
||||
filePath={filePath}
|
||||
structuredPatch={structuredPatch}
|
||||
firstLine={originalFile.split('\n')[0] ?? null}
|
||||
fileContent={originalFile}
|
||||
style={style}
|
||||
verbose={verbose}
|
||||
previewHint={isPlanFile ? '/plan to preview' : undefined}
|
||||
@@ -99,7 +108,7 @@ export function renderToolUseRejectedMessage(
|
||||
replace_all?: boolean;
|
||||
edits?: unknown[];
|
||||
},
|
||||
_options: {
|
||||
options: {
|
||||
columns: number;
|
||||
messages: Message[];
|
||||
progressMessagesForMessage: ProgressMessage[];
|
||||
@@ -109,14 +118,40 @@ export function renderToolUseRejectedMessage(
|
||||
verbose: boolean;
|
||||
},
|
||||
): React.ReactElement {
|
||||
const { style, verbose } = _options;
|
||||
const { style, verbose } = options;
|
||||
const filePath = input.file_path;
|
||||
const isNewFile = input.old_string === '';
|
||||
const oldString = input.old_string ?? '';
|
||||
const newString = input.new_string ?? '';
|
||||
const replaceAll = input.replace_all ?? false;
|
||||
|
||||
// Defensive: if input has an unexpected shape, show a simple rejection message
|
||||
if ('edits' in input && input.edits != null) {
|
||||
return (
|
||||
<FileEditToolUseRejectedMessage file_path={filePath} operation="update" firstLine={null} verbose={verbose} />
|
||||
);
|
||||
}
|
||||
|
||||
const isNewFile = oldString === '';
|
||||
|
||||
// For new file creation, show content preview instead of diff
|
||||
if (isNewFile) {
|
||||
return (
|
||||
<FileEditToolUseRejectedMessage
|
||||
file_path={filePath}
|
||||
operation="write"
|
||||
content={newString}
|
||||
firstLine={firstLineOf(newString)}
|
||||
verbose={verbose}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<FileEditToolUseRejectedMessage
|
||||
file_path={filePath}
|
||||
operation={isNewFile ? 'write' : 'update'}
|
||||
<EditRejectionDiff
|
||||
filePath={filePath}
|
||||
oldString={oldString}
|
||||
newString={newString}
|
||||
replaceAll={replaceAll}
|
||||
style={style}
|
||||
verbose={verbose}
|
||||
/>
|
||||
@@ -149,3 +184,103 @@ export function renderToolUseErrorMessage(
|
||||
}
|
||||
return <FallbackToolUseErrorMessage result={result} verbose={verbose} />;
|
||||
}
|
||||
|
||||
type RejectionDiffData = {
|
||||
patch: StructuredPatchHunk[];
|
||||
firstLine: string | null;
|
||||
fileContent: string | undefined;
|
||||
};
|
||||
|
||||
function EditRejectionDiff({
|
||||
filePath,
|
||||
oldString,
|
||||
newString,
|
||||
replaceAll,
|
||||
style,
|
||||
verbose,
|
||||
}: {
|
||||
filePath: string;
|
||||
oldString: string;
|
||||
newString: string;
|
||||
replaceAll: boolean;
|
||||
style?: 'condensed';
|
||||
verbose: boolean;
|
||||
}): React.ReactNode {
|
||||
const [dataPromise] = useState(() => loadRejectionDiff(filePath, oldString, newString, replaceAll));
|
||||
return (
|
||||
<Suspense
|
||||
fallback={
|
||||
<FileEditToolUseRejectedMessage file_path={filePath} operation="update" firstLine={null} verbose={verbose} />
|
||||
}
|
||||
>
|
||||
<EditRejectionBody promise={dataPromise} filePath={filePath} style={style} verbose={verbose} />
|
||||
</Suspense>
|
||||
);
|
||||
}
|
||||
|
||||
function EditRejectionBody({
|
||||
promise,
|
||||
filePath,
|
||||
style,
|
||||
verbose,
|
||||
}: {
|
||||
promise: Promise<RejectionDiffData>;
|
||||
filePath: string;
|
||||
style?: 'condensed';
|
||||
verbose: boolean;
|
||||
}): React.ReactNode {
|
||||
const { patch, firstLine, fileContent } = use(promise);
|
||||
return (
|
||||
<FileEditToolUseRejectedMessage
|
||||
file_path={filePath}
|
||||
operation="update"
|
||||
patch={patch}
|
||||
firstLine={firstLine}
|
||||
fileContent={fileContent}
|
||||
style={style}
|
||||
verbose={verbose}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
async function loadRejectionDiff(
|
||||
filePath: string,
|
||||
oldString: string,
|
||||
newString: string,
|
||||
replaceAll: boolean,
|
||||
): Promise<RejectionDiffData> {
|
||||
try {
|
||||
// Chunked read — context window around the first occurrence. replaceAll
|
||||
// still shows matches *within* the window via getPatchForEdit; we accept
|
||||
// losing the all-occurrences view to keep the read bounded.
|
||||
const ctx = await readEditContext(filePath, oldString, CONTEXT_LINES);
|
||||
if (ctx === null || ctx.truncated || ctx.content === '') {
|
||||
// ENOENT / not found / truncated — diff just the tool inputs.
|
||||
const { patch } = getPatchForEdit({
|
||||
filePath,
|
||||
fileContents: oldString,
|
||||
oldString,
|
||||
newString,
|
||||
});
|
||||
return { patch, firstLine: null, fileContent: undefined };
|
||||
}
|
||||
const actualOld = findActualString(ctx.content, oldString) || oldString;
|
||||
const actualNew = preserveQuoteStyle(oldString, actualOld, newString);
|
||||
const { patch } = getPatchForEdit({
|
||||
filePath,
|
||||
fileContents: ctx.content,
|
||||
oldString: actualOld,
|
||||
newString: actualNew,
|
||||
replaceAll,
|
||||
});
|
||||
return {
|
||||
patch: adjustHunkLineNumbers(patch, ctx.lineOffset - 1),
|
||||
firstLine: ctx.lineOffset === 1 ? firstLineOf(ctx.content) : null,
|
||||
fileContent: ctx.content,
|
||||
};
|
||||
} catch (e) {
|
||||
// User may have manually applied the change while the diff was shown.
|
||||
logError(e as Error);
|
||||
return { patch: [], firstLine: null, fileContent: undefined };
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
import type { ToolResultBlockParam } from '@anthropic-ai/sdk/resources/index.mjs';
|
||||
import { relative } from 'path';
|
||||
import type { StructuredPatchHunk } from 'diff';
|
||||
import { isAbsolute, relative, resolve } from 'path';
|
||||
import * as React from 'react';
|
||||
import { Suspense, use, useState } from 'react';
|
||||
import { MessageResponse } from 'src/components/MessageResponse.js';
|
||||
import { extractTag } from 'src/utils/messages.js';
|
||||
import { CtrlOToExpand } from 'src/components/CtrlOToExpand.js';
|
||||
@@ -15,8 +17,11 @@ import { FilePathLink } from 'src/components/FilePathLink.js';
|
||||
import type { ToolProgressData } from 'src/Tool.js';
|
||||
import type { ProgressMessage } from 'src/types/message.js';
|
||||
import { getCwd } from 'src/utils/cwd.js';
|
||||
import { getPatchForDisplay } from 'src/utils/diff.js';
|
||||
import { getDisplayPath } from 'src/utils/file.js';
|
||||
import { logError } from 'src/utils/log.js';
|
||||
import { getPlansDirectory } from 'src/utils/plans.js';
|
||||
import { openForScan, readCapped } from 'src/utils/readEditContext.js';
|
||||
import type { Output } from './FileWriteTool.js';
|
||||
|
||||
const MAX_LINES_TO_RENDER = 10;
|
||||
@@ -122,10 +127,115 @@ export function renderToolUseMessage(
|
||||
}
|
||||
|
||||
export function renderToolUseRejectedMessage(
|
||||
{ file_path }: { file_path: string; content: string },
|
||||
{ file_path, content }: { file_path: string; content: string },
|
||||
{ style, verbose }: { style?: 'condensed'; verbose: boolean },
|
||||
): React.ReactNode {
|
||||
return <FileEditToolUseRejectedMessage file_path={file_path} operation="write" style={style} verbose={verbose} />;
|
||||
return <WriteRejectionDiff filePath={file_path} content={content} style={style} verbose={verbose} />;
|
||||
}
|
||||
|
||||
type RejectionDiffData =
|
||||
| { type: 'create' }
|
||||
| { type: 'update'; patch: StructuredPatchHunk[]; oldContent: string }
|
||||
| { type: 'error' };
|
||||
|
||||
function WriteRejectionDiff({
|
||||
filePath,
|
||||
content,
|
||||
style,
|
||||
verbose,
|
||||
}: {
|
||||
filePath: string;
|
||||
content: string;
|
||||
style?: 'condensed';
|
||||
verbose: boolean;
|
||||
}): React.ReactNode {
|
||||
const [dataPromise] = useState(() => loadRejectionDiff(filePath, content));
|
||||
const firstLine = content.split('\n')[0] ?? null;
|
||||
const createFallback = (
|
||||
<FileEditToolUseRejectedMessage
|
||||
file_path={filePath}
|
||||
operation="write"
|
||||
content={content}
|
||||
firstLine={firstLine}
|
||||
verbose={verbose}
|
||||
/>
|
||||
);
|
||||
return (
|
||||
<Suspense fallback={createFallback}>
|
||||
<WriteRejectionBody
|
||||
promise={dataPromise}
|
||||
filePath={filePath}
|
||||
firstLine={firstLine}
|
||||
createFallback={createFallback}
|
||||
style={style}
|
||||
verbose={verbose}
|
||||
/>
|
||||
</Suspense>
|
||||
);
|
||||
}
|
||||
|
||||
function WriteRejectionBody({
|
||||
promise,
|
||||
filePath,
|
||||
firstLine,
|
||||
createFallback,
|
||||
style,
|
||||
verbose,
|
||||
}: {
|
||||
promise: Promise<RejectionDiffData>;
|
||||
filePath: string;
|
||||
firstLine: string | null;
|
||||
createFallback: React.ReactNode;
|
||||
style?: 'condensed';
|
||||
verbose: boolean;
|
||||
}): React.ReactNode {
|
||||
const data = use(promise);
|
||||
if (data.type === 'create') return createFallback;
|
||||
if (data.type === 'error') {
|
||||
return (
|
||||
<MessageResponse>
|
||||
<Text>(No changes)</Text>
|
||||
</MessageResponse>
|
||||
);
|
||||
}
|
||||
return (
|
||||
<FileEditToolUseRejectedMessage
|
||||
file_path={filePath}
|
||||
operation="update"
|
||||
patch={data.patch}
|
||||
firstLine={firstLine}
|
||||
fileContent={data.oldContent}
|
||||
style={style}
|
||||
verbose={verbose}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
async function loadRejectionDiff(filePath: string, content: string): Promise<RejectionDiffData> {
|
||||
try {
|
||||
const fullFilePath = isAbsolute(filePath) ? filePath : resolve(getCwd(), filePath);
|
||||
const handle = await openForScan(fullFilePath);
|
||||
if (handle === null) return { type: 'create' };
|
||||
let oldContent: string | null;
|
||||
try {
|
||||
oldContent = await readCapped(handle);
|
||||
} finally {
|
||||
await handle.close();
|
||||
}
|
||||
// File exceeds MAX_SCAN_BYTES — fall back to the create view rather than
|
||||
// OOMing on a diff of a multi-GB file.
|
||||
if (oldContent === null) return { type: 'create' };
|
||||
const patch = getPatchForDisplay({
|
||||
filePath,
|
||||
fileContents: oldContent,
|
||||
edits: [{ old_string: oldContent, new_string: content, replace_all: false }],
|
||||
});
|
||||
return { type: 'update', patch, oldContent };
|
||||
} catch (e) {
|
||||
// User may have manually applied the change while the diff was shown.
|
||||
logError(e as Error);
|
||||
return { type: 'error' };
|
||||
}
|
||||
}
|
||||
|
||||
export function renderToolUseErrorMessage(
|
||||
@@ -179,6 +289,8 @@ export function renderToolResultMessage(
|
||||
<FileEditToolUpdatedMessage
|
||||
filePath={filePath}
|
||||
structuredPatch={structuredPatch}
|
||||
firstLine={content.split('\n')[0] ?? null}
|
||||
fileContent={originalFile ?? undefined}
|
||||
style={style}
|
||||
verbose={verbose}
|
||||
previewHint={isPlanFile ? '/plan to preview' : undefined}
|
||||
|
||||
@@ -62,11 +62,11 @@ export const DEFAULT_BUILD_FEATURES = [
|
||||
'HISTORY_SNIP', // 历史消息裁剪，压缩上下文窗口
|
||||
// 'CONTEXT_COLLAPSE', // 已禁用：实现是空壳 stub，启用后会抑制 auto compact 导致上下文管理完全失效
|
||||
'MONITOR_TOOL', // Monitor 工具，流式监控后台进程输出
|
||||
// 'FORK_SUBAGENT', // 已禁用：显式 `fork: true` 参数触发 fork 路径（继承父级上下文和模型），不影响 forceAsync 和探索任务模型选择
|
||||
// 'UDS_INBOX', // inbox 数组只增不减（非 GB 级主因）
|
||||
// 'FORK_SUBAGENT', // 已禁用：通过 Agent tool 的特殊方式实现了等效功能，无需再开
|
||||
'KAIROS', // Kairos 定时任务系统核心
|
||||
// 'COORDINATOR_MODE', // 已禁用：AgentSummary 30s fork 循环，GB 级泄露主因
|
||||
// 'LAN_PIPES', // 依赖 UDS_INBOX（已随 UDS_INBOX 恢复）
|
||||
'COORDINATOR_MODE', // 多 worker 编排模式（AgentSummary 泄露已在 52b61c2c 修复）
|
||||
// 'UDS_INBOX', // 进程间通信管道（inbox/pipe/peers 等命令）构建后 nodejs 环境卡住
|
||||
// 'LAN_PIPES', // 局域网管道，依赖 UDS_INBOX 构建后 nodejs 环境卡住
|
||||
'BG_SESSIONS', // 后台会话管理（ps/logs/attach/kill）
|
||||
'TEMPLATES', // 模板任务（new/list/reply 子命令）
|
||||
// 'REVIEW_ARTIFACT', // 代码审查产物（API 请求无响应，待排查 schema 兼容性）
|
||||
@@ -84,7 +84,7 @@ export const DEFAULT_BUILD_FEATURES = [
|
||||
// this branch (see docs/agent/sur-skill-overflow-bugs.md) close the
|
||||
// overflow risk, but Haiku-on-first-Chinese-query and disk-side
|
||||
// observation accumulation remain operator-discretion concerns.
|
||||
// 'EXPERIMENTAL_SKILL_SEARCH',
|
||||
'EXPERIMENTAL_SKILL_SEARCH', // 技能搜索（bounded caches 已修复 overflow，内存问题已解决）
|
||||
// 'SKILL_LEARNING',
|
||||
// P3: poor mode
|
||||
'POOR', // 穷鬼模式，跳过 extract_memories/prompt_suggestion 减少消耗
|
||||
|
||||
@@ -43,8 +43,12 @@ export async function call(
|
||||
// Omitting subagent_type triggers implicit fork.
|
||||
const input = {
|
||||
prompt: directive,
|
||||
fork: true, // 触发 AgentTool 的 fork 路径：继承父会话上下文 + system prompt + 模型
|
||||
run_in_background: true, // fork always runs async
|
||||
description: `Fork: ${directive.slice(0, 30)}${directive.length > 30 ? '...' : ''}`,
|
||||
// description 只显示在底部 selector / BackgroundTasksDialog，保持简短标签
|
||||
// 即可；用户输入的 prompt 会作为第一条用户消息呈现在主视图里，这里不要
|
||||
// 重复显示。
|
||||
description: 'forked from main',
|
||||
};
|
||||
|
||||
// Call AgentTool with proper parameters:
|
||||
|
||||
@@ -115,6 +115,8 @@ export function ContextVisualization({ data }: Props): React.ReactNode {
|
||||
agents,
|
||||
skills,
|
||||
messageBreakdown,
|
||||
cacheHitRate,
|
||||
cacheThreshold,
|
||||
} = data;
|
||||
|
||||
// Filter out categories with 0 tokens for the legend, and exclude Free space, Autocompact buffer, and deferred
|
||||
@@ -166,6 +168,12 @@ export function ContextVisualization({ data }: Props): React.ReactNode {
|
||||
{model} · {formatTokens(totalTokens)}/{formatTokens(rawMaxTokens)} tokens ({percentage}%)
|
||||
</Text>
|
||||
<CollapseStatus />
|
||||
{cacheHitRate !== undefined && cacheThreshold !== undefined && (
|
||||
<Text color={cacheHitRate < cacheThreshold ? 'warning' : undefined}>
|
||||
Cache hit rate: {cacheHitRate.toFixed(0)}%
|
||||
{cacheHitRate < cacheThreshold ? ` (below ${cacheThreshold}% threshold)` : ''}
|
||||
</Text>
|
||||
)}
|
||||
<Text> </Text>
|
||||
<Text dimColor italic>
|
||||
Estimated usage by category
|
||||
|
||||
@@ -1,23 +1,31 @@
|
||||
import type { StructuredPatchHunk } from 'diff';
|
||||
import * as React from 'react';
|
||||
import { Text } from '@anthropic/ink';
|
||||
import { useTerminalSize } from '../hooks/useTerminalSize.js';
|
||||
import { Box, Text } from '@anthropic/ink';
|
||||
import { count } from '../utils/array.js';
|
||||
import { MessageResponse } from './MessageResponse.js';
|
||||
import { StructuredDiffList } from './StructuredDiffList.js';
|
||||
|
||||
type Props = {
|
||||
filePath: string;
|
||||
structuredPatch: { lines: string[] }[];
|
||||
structuredPatch: StructuredPatchHunk[];
|
||||
firstLine: string | null;
|
||||
fileContent?: string;
|
||||
style?: 'condensed';
|
||||
verbose: boolean;
|
||||
previewHint?: string;
|
||||
};
|
||||
|
||||
export function FileEditToolUpdatedMessage({
|
||||
filePath: _filePath,
|
||||
filePath,
|
||||
structuredPatch,
|
||||
firstLine,
|
||||
fileContent,
|
||||
style,
|
||||
verbose,
|
||||
previewHint,
|
||||
}: Props): React.ReactNode {
|
||||
const { columns } = useTerminalSize();
|
||||
const numAdditions = structuredPatch.reduce((acc, hunk) => acc + count(hunk.lines, _ => _.startsWith('+')), 0);
|
||||
const numRemovals = structuredPatch.reduce((acc, hunk) => acc + count(hunk.lines, _ => _.startsWith('-')), 0);
|
||||
|
||||
@@ -39,7 +47,7 @@ export function FileEditToolUpdatedMessage({
|
||||
|
||||
// Plan files: invert condensed behavior
|
||||
// - Regular mode: just show the hint (user can type /plan to see full content)
|
||||
// - Condensed mode (subagent view): show the text
|
||||
// - Condensed mode (subagent view): show the diff
|
||||
if (previewHint) {
|
||||
if (style !== 'condensed' && !verbose) {
|
||||
return (
|
||||
@@ -52,5 +60,19 @@ export function FileEditToolUpdatedMessage({
|
||||
return text;
|
||||
}
|
||||
|
||||
return <MessageResponse>{text}</MessageResponse>;
|
||||
return (
|
||||
<MessageResponse>
|
||||
<Box flexDirection="column">
|
||||
<Text>{text}</Text>
|
||||
<StructuredDiffList
|
||||
hunks={structuredPatch}
|
||||
dim={false}
|
||||
width={columns - 12}
|
||||
filePath={filePath}
|
||||
firstLine={firstLine}
|
||||
fileContent={fileContent}
|
||||
/>
|
||||
</Box>
|
||||
</MessageResponse>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,17 +1,39 @@
|
||||
import type { StructuredPatchHunk } from 'diff';
|
||||
import { relative } from 'path';
|
||||
import * as React from 'react';
|
||||
import { useTerminalSize } from 'src/hooks/useTerminalSize.js';
|
||||
import { getCwd } from 'src/utils/cwd.js';
|
||||
import { Box, Text } from '@anthropic/ink';
|
||||
import { HighlightedCode } from './HighlightedCode.js';
|
||||
import { MessageResponse } from './MessageResponse.js';
|
||||
import { StructuredDiffList } from './StructuredDiffList.js';
|
||||
|
||||
const MAX_LINES_TO_RENDER = 10;
|
||||
|
||||
type Props = {
|
||||
file_path: string;
|
||||
operation: 'write' | 'update';
|
||||
// For updates - show diff
|
||||
patch?: StructuredPatchHunk[];
|
||||
firstLine: string | null;
|
||||
fileContent?: string;
|
||||
// For new file creation - show content preview
|
||||
content?: string;
|
||||
style?: 'condensed';
|
||||
verbose: boolean;
|
||||
};
|
||||
|
||||
export function FileEditToolUseRejectedMessage({ file_path, operation, style, verbose }: Props): React.ReactNode {
|
||||
export function FileEditToolUseRejectedMessage({
|
||||
file_path,
|
||||
operation,
|
||||
patch,
|
||||
firstLine,
|
||||
fileContent,
|
||||
content,
|
||||
style,
|
||||
verbose,
|
||||
}: Props): React.ReactNode {
|
||||
const { columns } = useTerminalSize();
|
||||
const text = (
|
||||
<Box flexDirection="row">
|
||||
<Text color="subtle">User rejected {operation} to </Text>
|
||||
@@ -26,5 +48,42 @@ export function FileEditToolUseRejectedMessage({ file_path, operation, style, ve
|
||||
return <MessageResponse>{text}</MessageResponse>;
|
||||
}
|
||||
|
||||
return <MessageResponse>{text}</MessageResponse>;
|
||||
// For new file creation, show content preview (dimmed)
|
||||
if (operation === 'write' && content !== undefined) {
|
||||
const lines = content.split('\n');
|
||||
const numLines = lines.length;
|
||||
const plusLines = numLines - MAX_LINES_TO_RENDER;
|
||||
const truncatedContent = verbose ? content : lines.slice(0, MAX_LINES_TO_RENDER).join('\n');
|
||||
|
||||
return (
|
||||
<MessageResponse>
|
||||
<Box flexDirection="column">
|
||||
{text}
|
||||
<HighlightedCode code={truncatedContent || '(No content)'} filePath={file_path} width={columns - 12} dim />
|
||||
{!verbose && plusLines > 0 && <Text dimColor>… +{plusLines} lines</Text>}
|
||||
</Box>
|
||||
</MessageResponse>
|
||||
);
|
||||
}
|
||||
|
||||
// For updates, show diff
|
||||
if (!patch || patch.length === 0) {
|
||||
return <MessageResponse>{text}</MessageResponse>;
|
||||
}
|
||||
|
||||
return (
|
||||
<MessageResponse>
|
||||
<Box flexDirection="column">
|
||||
{text}
|
||||
<StructuredDiffList
|
||||
hunks={patch}
|
||||
dim
|
||||
width={columns - 12}
|
||||
filePath={file_path}
|
||||
firstLine={firstLine}
|
||||
fileContent={fileContent}
|
||||
/>
|
||||
</Box>
|
||||
</MessageResponse>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -26,6 +26,7 @@ import { useSetPromptOverlayDialog } from '../../context/promptOverlayContext.js
|
||||
import { formatImageRef, formatPastedTextRef, getPastedTextRefNumLines, parseReferences } from '../../history.js';
|
||||
import type { VerificationStatus } from '../../hooks/useApiKeyVerification.js';
|
||||
import { type HistoryMode, useArrowKeyHistory } from '../../hooks/useArrowKeyHistory.js';
|
||||
import { useBackgroundAgentTasks } from '../../hooks/useBackgroundAgentTasks.js';
|
||||
import { useDoublePress } from '../../hooks/useDoublePress.js';
|
||||
import { useHistorySearch } from '../../hooks/useHistorySearch.js';
|
||||
import type { IDESelection } from '../../hooks/useIdeSelection.js';
|
||||
@@ -415,6 +416,16 @@ function PromptInput({
|
||||
// First ↓ selects the pill, second ↓ moves to row 0. Prevents double-select
|
||||
// of pill + row when both bg tasks (pill) and forked agents (rows) are visible.
|
||||
const coordinatorTaskIndex = useAppState(s => s.coordinatorTaskIndex);
|
||||
const selectedBgAgentIndex = useAppState(s => s.selectedBgAgentIndex);
|
||||
const setSelectedBgAgentIndex = useCallback(
|
||||
(v: number | ((prev: number) => number)) =>
|
||||
setAppState(prev => {
|
||||
const next = typeof v === 'function' ? v(prev.selectedBgAgentIndex) : v;
|
||||
if (next === prev.selectedBgAgentIndex) return prev;
|
||||
return { ...prev, selectedBgAgentIndex: next };
|
||||
}),
|
||||
[setAppState],
|
||||
);
|
||||
const setCoordinatorTaskIndex = useCallback(
|
||||
(v: number | ((prev: number) => number)) =>
|
||||
setAppState(prev => {
|
||||
@@ -501,10 +512,13 @@ function PromptInput({
|
||||
(runningTaskCount > 0 || (process.env.USER_TYPE === 'ant' && coordinatorTaskCount > 0)) &&
|
||||
!shouldHideTasksFooter(tasks, showSpinnerTree);
|
||||
const teamsFooterVisible = cachedTeams.length > 0;
|
||||
const bgAgentList = useBackgroundAgentTasks();
|
||||
const bgAgentFooterVisible = bgAgentList.length > 0;
|
||||
|
||||
const footerItems = useMemo(
|
||||
() =>
|
||||
[
|
||||
bgAgentFooterVisible && 'bg_agent',
|
||||
tasksFooterVisible && 'tasks',
|
||||
tmuxFooterVisible && 'tmux',
|
||||
bagelFooterVisible && 'bagel',
|
||||
@@ -513,6 +527,7 @@ function PromptInput({
|
||||
companionFooterVisible && 'companion',
|
||||
].filter(Boolean) as FooterItem[],
|
||||
[
|
||||
bgAgentFooterVisible,
|
||||
tasksFooterVisible,
|
||||
tmuxFooterVisible,
|
||||
bagelFooterVisible,
|
||||
@@ -540,6 +555,7 @@ function PromptInput({
|
||||
const _bagelSelected = footerItemSelected === 'bagel';
|
||||
const teamsSelected = footerItemSelected === 'teams';
|
||||
const bridgeSelected = footerItemSelected === 'bridge';
|
||||
const bgAgentSelected = footerItemSelected === 'bg_agent';
|
||||
|
||||
function selectFooterItem(item: FooterItem | null): void {
|
||||
setAppState(prev => (prev.footerSelection === item ? prev : { ...prev, footerSelection: item }));
|
||||
@@ -547,6 +563,9 @@ function PromptInput({
|
||||
setTeammateFooterIndex(0);
|
||||
setCoordinatorTaskIndex(minCoordinatorIndex);
|
||||
}
|
||||
if (item === 'bg_agent') {
|
||||
setSelectedBgAgentIndex(-1);
|
||||
}
|
||||
}
|
||||
|
||||
// delta: +1 = down/right, -1 = up/left. Returns true if nav happened
|
||||
@@ -1808,6 +1827,15 @@ function PromptInput({
|
||||
useKeybindings(
|
||||
{
|
||||
'footer:up': () => {
|
||||
// ↑ in bg_agent pill: move selection up (-1 = main). At -1, leave pill.
|
||||
if (bgAgentSelected) {
|
||||
if (selectedBgAgentIndex > -1) {
|
||||
setSelectedBgAgentIndex(prev => prev - 1);
|
||||
} else {
|
||||
selectFooterItem(null);
|
||||
}
|
||||
return;
|
||||
}
|
||||
// ↑ scrolls within the coordinator task list before leaving the pill
|
||||
if (
|
||||
tasksSelected &&
|
||||
@@ -1821,6 +1849,13 @@ function PromptInput({
|
||||
navigateFooter(-1, true);
|
||||
},
|
||||
'footer:down': () => {
|
||||
// ↓ in bg_agent pill: move selection down through agents. Clamp at last.
|
||||
if (bgAgentSelected) {
|
||||
if (selectedBgAgentIndex < bgAgentList.length - 1) {
|
||||
setSelectedBgAgentIndex(prev => prev + 1);
|
||||
}
|
||||
return;
|
||||
}
|
||||
// ↓ scrolls within the coordinator task list, never leaves the pill
|
||||
if (tasksSelected && process.env.USER_TYPE === 'ant' && coordinatorTaskCount > 0) {
|
||||
if (coordinatorTaskIndex < coordinatorTaskCount - 1) {
|
||||
@@ -1906,6 +1941,15 @@ function PromptInput({
|
||||
setShowBridgeDialog(true);
|
||||
selectFooterItem(null);
|
||||
break;
|
||||
case 'bg_agent':
|
||||
if (selectedBgAgentIndex === -1) {
|
||||
exitTeammateView(setAppState);
|
||||
} else {
|
||||
const picked = bgAgentList[selectedBgAgentIndex];
|
||||
if (picked) enterTeammateView(picked.agentId, setAppState);
|
||||
}
|
||||
// Keep the pill focused so ↑/↓ continue to work after Enter.
|
||||
break;
|
||||
}
|
||||
},
|
||||
'footer:clearSelection': () => {
|
||||
|
||||
@@ -288,6 +288,15 @@ function StatusLineInner({ messagesRef, lastAssistantMessageId, vimMode }: Props
|
||||
}
|
||||
}, [lastAssistantMessageId, permissionMode, vimMode, mainLoopModel, scheduleUpdate]);
|
||||
|
||||
// Time-driven refresh: tick setInterval(refreshInterval seconds) through the
|
||||
// existing debounced scheduleUpdate so interval + message-change don't double-fire.
|
||||
const refreshIntervalMs = (settings?.statusLine?.refreshInterval ?? 0) * 1000;
|
||||
useEffect(() => {
|
||||
if (refreshIntervalMs <= 0) return;
|
||||
const id = setInterval(() => scheduleUpdate(), refreshIntervalMs);
|
||||
return () => clearInterval(id);
|
||||
}, [refreshIntervalMs, scheduleUpdate]);
|
||||
|
||||
// When the statusLine command changes (hot reload), log the next result
|
||||
const statusLineCommand = settings?.statusLine?.command;
|
||||
const isFirstSettingsRender = useRef(true);
|
||||
|
||||
@@ -30,6 +30,7 @@ type Props = {
|
||||
inProgressToolCallCount?: number;
|
||||
lookups: ReturnType<typeof buildMessageLookups>;
|
||||
isTranscriptMode?: boolean;
|
||||
defaultCollapsed?: boolean;
|
||||
};
|
||||
|
||||
export function AssistantToolUseMessage({
|
||||
@@ -45,6 +46,7 @@ export function AssistantToolUseMessage({
|
||||
inProgressToolCallCount,
|
||||
lookups,
|
||||
isTranscriptMode,
|
||||
defaultCollapsed,
|
||||
}: Props): React.ReactNode {
|
||||
const terminalSize = useTerminalSize();
|
||||
const [theme] = useTheme();
|
||||
@@ -167,6 +169,7 @@ export function AssistantToolUseMessage({
|
||||
</Box>
|
||||
{!isResolved &&
|
||||
!isQueued &&
|
||||
!defaultCollapsed &&
|
||||
(isClassifierChecking ? (
|
||||
<MessageResponse height={1}>
|
||||
<Text dimColor>
|
||||
|
||||
@@ -3,28 +3,31 @@
|
||||
*/
|
||||
import type { TextBlockParam } from '@anthropic-ai/sdk/resources/index.mjs';
|
||||
import * as React from 'react';
|
||||
import { Box, Text } from '@anthropic/ink';
|
||||
import { FORK_BOILERPLATE_TAG, FORK_DIRECTIVE_PREFIX } from '../../constants/xml.js';
|
||||
import { extractTag } from '../../utils/messages.js';
|
||||
import { UserPromptMessage } from './UserPromptMessage.js';
|
||||
|
||||
type Props = {
|
||||
addMargin: boolean;
|
||||
param: TextBlockParam;
|
||||
isTranscriptMode?: boolean;
|
||||
timestamp?: string;
|
||||
};
|
||||
|
||||
export function UserForkBoilerplateMessage({ param, addMargin }: Props): React.ReactNode {
|
||||
const text = param.text;
|
||||
const extracted = extractTag(text, 'fork-boilerplate');
|
||||
if (!extracted) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const firstLine = extracted.trim().split('\n')[0] ?? '';
|
||||
const preview = firstLine.length > 80 ? firstLine.slice(0, 77) + '...' : firstLine;
|
||||
export function UserForkBoilerplateMessage({ param, addMargin, isTranscriptMode, timestamp }: Props): React.ReactNode {
|
||||
if (!extractTag(param.text, FORK_BOILERPLATE_TAG)) return null;
|
||||
const closeTag = `</${FORK_BOILERPLATE_TAG}>`;
|
||||
const afterTag = param.text.slice(param.text.indexOf(closeTag) + closeTag.length).trimStart();
|
||||
const userPrompt = afterTag.startsWith(FORK_DIRECTIVE_PREFIX)
|
||||
? afterTag.slice(FORK_DIRECTIVE_PREFIX.length)
|
||||
: afterTag;
|
||||
|
||||
return (
|
||||
<Box flexDirection="row" marginTop={addMargin ? 1 : 0}>
|
||||
<Text dimColor>[fork] </Text>
|
||||
<Text>{preview}</Text>
|
||||
</Box>
|
||||
<UserPromptMessage
|
||||
addMargin={addMargin}
|
||||
param={{ type: 'text', text: userPrompt }}
|
||||
isTranscriptMode={isTranscriptMode}
|
||||
timestamp={timestamp}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -4,6 +4,7 @@ import * as React from 'react';
|
||||
import { NO_CONTENT_MESSAGE } from '../../constants/messages.js';
|
||||
import {
|
||||
COMMAND_MESSAGE_TAG,
|
||||
FORK_BOILERPLATE_TAG,
|
||||
LOCAL_COMMAND_CAVEAT_TAG,
|
||||
TASK_NOTIFICATION_TAG,
|
||||
TEAMMATE_MESSAGE_TAG,
|
||||
@@ -124,16 +125,21 @@ export function UserTextMessage({
|
||||
}
|
||||
|
||||
// Fork child's first message: collapse the rules/format boilerplate, show
|
||||
// only the directive. FORK_BOILERPLATE_TAG is inlined so the import doesn't
|
||||
// ship in external builds where feature('FORK_SUBAGENT') is false.
|
||||
if (feature('FORK_SUBAGENT')) {
|
||||
if (param.text.includes('<fork-boilerplate>')) {
|
||||
/* eslint-disable @typescript-eslint/no-require-imports */
|
||||
const { UserForkBoilerplateMessage } =
|
||||
require('./UserForkBoilerplateMessage.js') as typeof import('./UserForkBoilerplateMessage.js');
|
||||
/* eslint-enable @typescript-eslint/no-require-imports */
|
||||
return <UserForkBoilerplateMessage addMargin={addMargin} param={param} />;
|
||||
}
|
||||
// only the user prompt. Independent of FORK_SUBAGENT flag — the fork agent
|
||||
// transcript always needs to render the prompt as a normal user bubble.
|
||||
if (param.text.includes(`<${FORK_BOILERPLATE_TAG}>`)) {
|
||||
/* eslint-disable @typescript-eslint/no-require-imports */
|
||||
const { UserForkBoilerplateMessage } =
|
||||
require('./UserForkBoilerplateMessage.js') as typeof import('./UserForkBoilerplateMessage.js');
|
||||
/* eslint-enable @typescript-eslint/no-require-imports */
|
||||
return (
|
||||
<UserForkBoilerplateMessage
|
||||
addMargin={addMargin}
|
||||
param={param}
|
||||
isTranscriptMode={isTranscriptMode}
|
||||
timestamp={timestamp}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
// Cross-session UDS message (from another Claude session's SendMessage).
|
||||
|
||||
63
src/components/tasks/BackgroundAgentSelector.tsx
Normal file
63
src/components/tasks/BackgroundAgentSelector.tsx
Normal file
@@ -0,0 +1,63 @@
|
||||
import { Box, Text } from '@anthropic/ink';
|
||||
import { useBackgroundAgentTasks } from '../../hooks/useBackgroundAgentTasks.js';
|
||||
import { useElapsedTime } from '../../hooks/useElapsedTime.js';
|
||||
import { useAppState } from '../../state/AppState.js';
|
||||
import type { LocalAgentTaskState } from '../../tasks/LocalAgentTask/LocalAgentTask.js';
|
||||
import { formatTokens } from '../../utils/format.js';
|
||||
|
||||
function AgentRow({ task, selected }: { task: LocalAgentTaskState; selected: boolean }) {
|
||||
const elapsed = useElapsedTime(task.startTime, task.status === 'running');
|
||||
const tokens = task.progress?.tokenCount ?? 0;
|
||||
const isRunning = task.status === 'running';
|
||||
return (
|
||||
<Box flexDirection="row" width="100%" justifyContent="space-between">
|
||||
<Box flexDirection="row" flexShrink={1}>
|
||||
<Text color={isRunning ? 'success' : undefined}>{selected ? '● ' : '○ '}</Text>
|
||||
<Text bold={selected} wrap="truncate-end">
|
||||
{task.agentType} <Text dimColor>{task.description}</Text>
|
||||
</Text>
|
||||
</Box>
|
||||
<Box flexShrink={0}>
|
||||
<Text dimColor>
|
||||
{elapsed} · ↓ {formatTokens(tokens)} tokens
|
||||
</Text>
|
||||
</Box>
|
||||
</Box>
|
||||
);
|
||||
}
|
||||
|
||||
function getHint(pillFocused: boolean, viewedTask: LocalAgentTaskState | null): string {
|
||||
if (pillFocused) return '↑/↓ to select · Enter to view';
|
||||
if (!viewedTask) return 'shift+↓ to manage background agents';
|
||||
return viewedTask.status === 'running' ? 'shift+↓ to manage · x to stop' : 'shift+↓ to manage · x to clear';
|
||||
}
|
||||
|
||||
export function BackgroundAgentSelector(): React.ReactNode {
|
||||
const tasks = useBackgroundAgentTasks();
|
||||
const viewingId = useAppState(s => s.viewingAgentTaskId);
|
||||
const footerSelection = useAppState(s => s.footerSelection);
|
||||
const selectedBgIndex = useAppState(s => s.selectedBgAgentIndex);
|
||||
|
||||
if (tasks.length === 0) return null;
|
||||
|
||||
const pillFocused = footerSelection === 'bg_agent';
|
||||
const highlightedId = pillFocused
|
||||
? selectedBgIndex === -1
|
||||
? null
|
||||
: (tasks[selectedBgIndex]?.agentId ?? null)
|
||||
: (viewingId ?? null);
|
||||
const mainHighlighted = pillFocused ? selectedBgIndex === -1 : viewingId === undefined;
|
||||
const viewedTask = viewingId ? (tasks.find(t => t.agentId === viewingId) ?? null) : null;
|
||||
|
||||
return (
|
||||
<Box flexDirection="column" width="100%">
|
||||
<Box flexDirection="row" width="100%" justifyContent="space-between">
|
||||
<Text bold={mainHighlighted}>{mainHighlighted ? '● ' : '○ '}main</Text>
|
||||
<Text dimColor>{getHint(pillFocused, viewedTask)}</Text>
|
||||
</Box>
|
||||
{tasks.map(task => (
|
||||
<AgentRow key={task.agentId} task={task} selected={task.agentId === highlightedId} />
|
||||
))}
|
||||
</Box>
|
||||
);
|
||||
}
|
||||
@@ -1,4 +1,4 @@
|
||||
export const PRODUCT_URL = 'https://claude.com/claude-code'
|
||||
export const PRODUCT_URL = 'https://github.com/claude-code-best/claude-code'
|
||||
|
||||
// Claude Code Remote session URLs
|
||||
export const CLAUDE_AI_BASE_URL = 'https://claude.ai'
|
||||
|
||||
19
src/hooks/useBackgroundAgentTasks.ts
Normal file
19
src/hooks/useBackgroundAgentTasks.ts
Normal file
@@ -0,0 +1,19 @@
|
||||
import { useMemo } from 'react'
|
||||
import { useAppState } from '../state/AppState.js'
|
||||
import {
|
||||
isLocalAgentTask,
|
||||
type LocalAgentTaskState,
|
||||
} from '../tasks/LocalAgentTask/LocalAgentTask.js'
|
||||
|
||||
export function useBackgroundAgentTasks(): LocalAgentTaskState[] {
|
||||
const tasks = useAppState(s => s.tasks)
|
||||
return useMemo(() => {
|
||||
const now = Date.now()
|
||||
return Object.values(tasks)
|
||||
.filter(isLocalAgentTask)
|
||||
.filter(t => t.agentType !== 'main-session')
|
||||
.filter(t => t.isBackgrounded !== false)
|
||||
.filter(t => t.evictAfter === undefined || t.evictAfter > now)
|
||||
.sort((a, b) => a.startTime - b.startTime)
|
||||
}, [tasks])
|
||||
}
|
||||
@@ -3485,6 +3485,7 @@ async function run(): Promise<CommanderCommand> {
|
||||
: 'none',
|
||||
showTeammateMessagePreview: isAgentSwarmsEnabled() ? false : undefined,
|
||||
selectedIPAgentIndex: -1,
|
||||
selectedBgAgentIndex: -1,
|
||||
coordinatorTaskIndex: -1,
|
||||
viewSelectionMode: 'none',
|
||||
footerSelection: null,
|
||||
|
||||
@@ -1,43 +1,15 @@
|
||||
import { logEvent } from '../services/analytics/index.js'
|
||||
import {
|
||||
getDefaultMainLoopModelSetting,
|
||||
isOpus1mMergeEnabled,
|
||||
parseUserSpecifiedModel,
|
||||
} from '../utils/model/model.js'
|
||||
import {
|
||||
getSettingsForSource,
|
||||
updateSettingsForSource,
|
||||
} from '../utils/settings/settings.js'
|
||||
import { isOpus1mMergeEnabled } from '../utils/model/model.js'
|
||||
|
||||
/**
|
||||
* Migrate users with 'opus' pinned in their settings to 'opus[1m]' when they
|
||||
* are eligible for the merged Opus 1M experience (Max/Team Premium on 1P).
|
||||
*
|
||||
* CLI invocations with --model opus are unaffected: that flag is a runtime
|
||||
* override and does not touch userSettings, so it continues to use plain Opus.
|
||||
*
|
||||
* Pro subscribers are skipped — they retain separate Opus and Opus 1M options.
|
||||
* 3P users are skipped — their model strings are full model IDs, not aliases.
|
||||
*
|
||||
* Idempotent: only writes if userSettings.model is exactly 'opus'.
|
||||
* Migration disabled: users who manually remove [1m] suffix should not
|
||||
* have it automatically re-added. The migration was too aggressive and
|
||||
* didn't respect user choice.
|
||||
*/
|
||||
export function migrateOpusToOpus1m(): void {
|
||||
// No-op - respect user's manual model choice
|
||||
if (!isOpus1mMergeEnabled()) {
|
||||
return
|
||||
}
|
||||
|
||||
const model = getSettingsForSource('userSettings')?.model
|
||||
if (model !== 'opus') {
|
||||
return
|
||||
}
|
||||
|
||||
const migrated = 'opus[1m]'
|
||||
const modelToSet =
|
||||
parseUserSpecifiedModel(migrated) ===
|
||||
parseUserSpecifiedModel(getDefaultMainLoopModelSetting())
|
||||
? undefined
|
||||
: migrated
|
||||
updateSettingsForSource('userSettings', { model: modelToSet })
|
||||
|
||||
logEvent('tengu_opus_to_opus1m_migration', {})
|
||||
logEvent('tengu_opus_to_opus1m_migration', { skipped: true })
|
||||
}
|
||||
|
||||
31
src/query.ts
31
src/query.ts
@@ -127,6 +127,11 @@ import {
|
||||
isLangfuseEnabled,
|
||||
} from './services/langfuse/index.js'
|
||||
import { getAPIProvider } from './utils/model/providers.js'
|
||||
import {
|
||||
createCacheWarningMessage,
|
||||
getCacheThreshold,
|
||||
shouldShowCacheWarning,
|
||||
} from './utils/cacheWarning.js'
|
||||
|
||||
/* eslint-disable @typescript-eslint/no-require-imports */
|
||||
const snipModule = feature('HISTORY_SNIP')
|
||||
@@ -1229,6 +1234,32 @@ async function* queryLoop(
|
||||
return { reason: 'model_error', error }
|
||||
}
|
||||
|
||||
// 检测缓存命中率并在需要时 yield 警告消息
|
||||
// 必须在 executePostSamplingHooks 之前执行，确保警告消息在工具结果之前显示
|
||||
if (
|
||||
assistantMessages.length > 0 &&
|
||||
!toolUseContext.options.isNonInteractiveSession
|
||||
) {
|
||||
const lastAssistant = assistantMessages.at(-1)
|
||||
const usage = lastAssistant?.message?.usage as
|
||||
| {
|
||||
input_tokens: number
|
||||
cache_creation_input_tokens: number
|
||||
cache_read_input_tokens: number
|
||||
}
|
||||
| undefined
|
||||
if (usage) {
|
||||
const warningInfo = shouldShowCacheWarning(
|
||||
usage,
|
||||
querySource,
|
||||
getCacheThreshold(),
|
||||
)
|
||||
if (warningInfo) {
|
||||
yield createCacheWarningMessage(warningInfo)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Execute post-sampling hooks after model response is complete
|
||||
if (assistantMessages.length > 0) {
|
||||
void executePostSamplingHooks(
|
||||
|
||||
@@ -244,7 +244,14 @@ import {
|
||||
formatCommandInputTags,
|
||||
} from '../utils/messages.js';
|
||||
import { generateSessionTitle } from '../utils/sessionTitle.js';
|
||||
import { BASH_INPUT_TAG, COMMAND_MESSAGE_TAG, COMMAND_NAME_TAG, LOCAL_COMMAND_STDOUT_TAG } from '../constants/xml.js';
|
||||
import {
|
||||
BASH_INPUT_TAG,
|
||||
COMMAND_MESSAGE_TAG,
|
||||
COMMAND_NAME_TAG,
|
||||
FORK_BOILERPLATE_TAG,
|
||||
LOCAL_COMMAND_STDOUT_TAG,
|
||||
} from '../constants/xml.js';
|
||||
import { FORK_SUBAGENT_TYPE } from '@claude-code-best/builtin-tools/tools/AgentTool/forkSubagent.js';
|
||||
import { escapeXml } from '../utils/xml.js';
|
||||
import type { ThinkingConfig } from '../utils/thinking.js';
|
||||
import { gracefulShutdownSync } from '../utils/gracefulShutdown.js';
|
||||
@@ -336,6 +343,7 @@ import {
|
||||
import { isBgSession, updateSessionName, updateSessionActivity } from '../utils/concurrentSessions.js';
|
||||
import { isInProcessTeammateTask, type InProcessTeammateTaskState } from '../tasks/InProcessTeammateTask/types.js';
|
||||
import { restoreRemoteAgentTasks } from '../tasks/RemoteAgentTask/RemoteAgentTask.js';
|
||||
import { BackgroundAgentSelector } from '../components/tasks/BackgroundAgentSelector.js';
|
||||
import { useInboxPoller } from '../hooks/useInboxPoller.js';
|
||||
// Dead code elimination: conditional import for loop mode
|
||||
/* eslint-disable @typescript-eslint/no-require-imports */
|
||||
@@ -800,6 +808,21 @@ export type Props = {
|
||||
|
||||
export type Screen = 'prompt' | 'transcript';
|
||||
|
||||
// Boilerplate carrier lives in a mixed user message ([tool_result..., text])
|
||||
// that AgentTool/forkSubagent.buildForkedMessages emits as the fork child's
|
||||
// first user turn. The text block wraps <FORK_BOILERPLATE_TAG>...</..> + the
|
||||
// user prompt; tool_result siblings keep the parent's tool calls closed.
|
||||
const FORK_BOILERPLATE_OPEN_TAG = `<${FORK_BOILERPLATE_TAG}>`;
|
||||
|
||||
function isForkBoilerplateTextBlock(block: { type: string; text?: string }): boolean {
|
||||
return block.type === 'text' && typeof block.text === 'string' && block.text.includes(FORK_BOILERPLATE_OPEN_TAG);
|
||||
}
|
||||
|
||||
function isForkBoilerplateMessage(message: MessageType): boolean {
|
||||
if (message.type !== 'user' || !Array.isArray(message.message?.content)) return false;
|
||||
return message.message.content.some(isForkBoilerplateTextBlock);
|
||||
}
|
||||
|
||||
export function REPL({
|
||||
commands: initialCommands,
|
||||
debug,
|
||||
@@ -5548,8 +5571,72 @@ export function REPL({
|
||||
const usesSyncMessages = showStreamingText || !isLoading;
|
||||
// When viewing an agent, never fall through to leader — empty until
|
||||
// bootstrap/stream fills. Closes the see-leader-type-agent footgun.
|
||||
const rawAgentMessages = viewedAgentTask?.messages;
|
||||
// Fork sidechain encodes the user prompt inside a mixed user message alongside
|
||||
// tool_result blocks; surface the prompt as a standalone bubble and strip the
|
||||
// boilerplate text from its original carrier while preserving tool_results.
|
||||
const displayedAgentMessages = useMemo(() => {
|
||||
if (!viewedAgentTask) return undefined;
|
||||
const agentMessages = rawAgentMessages ?? [];
|
||||
if (
|
||||
!isLocalAgentTask(viewedAgentTask) ||
|
||||
viewedAgentTask.agentType !== FORK_SUBAGENT_TYPE ||
|
||||
!viewedAgentTask.prompt
|
||||
) {
|
||||
return agentMessages;
|
||||
}
|
||||
// Single pass: locate boilerplate carrier, check whether the prompt text is
|
||||
// already present elsewhere, and find the fallback insertion point (after
|
||||
// the last parent assistant tool_use).
|
||||
const trimmedPrompt = viewedAgentTask.prompt.trim();
|
||||
let boilerplateIndex = -1;
|
||||
let lastAssistantToolUseIndex = -1;
|
||||
let promptAlreadyRendered = false;
|
||||
for (let i = 0; i < agentMessages.length; i++) {
|
||||
const m = agentMessages[i]!;
|
||||
if (m.type === 'user' && Array.isArray(m.message?.content)) {
|
||||
const hasBoilerplate = m.message.content.some(isForkBoilerplateTextBlock);
|
||||
if (hasBoilerplate) {
|
||||
boilerplateIndex = i;
|
||||
} else if (!promptAlreadyRendered) {
|
||||
const firstText = m.message.content.find(b => b.type === 'text' && typeof b.text === 'string') as
|
||||
| { type: 'text'; text: string }
|
||||
| undefined;
|
||||
if (firstText && firstText.text.trim() === trimmedPrompt) promptAlreadyRendered = true;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
if (m.type === 'assistant' && Array.isArray(m.message?.content)) {
|
||||
if (m.message.content.some(b => b.type === 'tool_use')) lastAssistantToolUseIndex = i;
|
||||
}
|
||||
}
|
||||
|
||||
const stripped =
|
||||
boilerplateIndex === -1
|
||||
? agentMessages
|
||||
: agentMessages.map((m, i) => {
|
||||
if (i !== boilerplateIndex) return m;
|
||||
if (!Array.isArray(m.message?.content)) return m;
|
||||
return {
|
||||
...m,
|
||||
message: {
|
||||
...m.message,
|
||||
content: m.message.content.filter(b => !isForkBoilerplateTextBlock(b)),
|
||||
},
|
||||
};
|
||||
});
|
||||
|
||||
if (promptAlreadyRendered) return stripped;
|
||||
|
||||
const insertAt = boilerplateIndex !== -1 ? boilerplateIndex + 1 : lastAssistantToolUseIndex + 1;
|
||||
const synthetic = createUserMessage({
|
||||
content: viewedAgentTask.prompt,
|
||||
timestamp: new Date(viewedAgentTask.startTime).toISOString(),
|
||||
});
|
||||
return [...stripped.slice(0, insertAt), synthetic, ...stripped.slice(insertAt)];
|
||||
}, [viewedAgentTask, rawAgentMessages]);
|
||||
const displayedMessages = viewedAgentTask
|
||||
? (viewedAgentTask.messages ?? [])
|
||||
? (displayedAgentMessages ?? [])
|
||||
: usesSyncMessages
|
||||
? messages
|
||||
: deferredMessages;
|
||||
@@ -6286,6 +6373,7 @@ export function REPL({
|
||||
voiceInterimRange={voice.interimRange}
|
||||
/>
|
||||
<SessionBackgroundHint onBackgroundSession={handleBackgroundSession} isLoading={isLoading} />
|
||||
<BackgroundAgentSelector />
|
||||
</>
|
||||
)}
|
||||
{cursor && (
|
||||
|
||||
@@ -509,10 +509,30 @@ export function getAPIMetadata() {
|
||||
}
|
||||
}
|
||||
|
||||
const deviceId = getOrCreateUserID()
|
||||
|
||||
// Third-party API providers (DeepSeek, etc.) validate user_id against
|
||||
// ^[a-zA-Z0-9_-]+$ which rejects JSON strings containing {, ", :, etc.
|
||||
// When using a non-Anthropic base URL, send only the device_id (hex string).
|
||||
const baseUrl = process.env.ANTHROPIC_BASE_URL
|
||||
const isThirdParty =
|
||||
baseUrl &&
|
||||
(() => {
|
||||
try {
|
||||
return new URL(baseUrl).host !== 'api.anthropic.com'
|
||||
} catch {
|
||||
return false
|
||||
}
|
||||
})()
|
||||
|
||||
if (isThirdParty) {
|
||||
return { user_id: deviceId }
|
||||
}
|
||||
|
||||
return {
|
||||
user_id: jsonStringify({
|
||||
...extra,
|
||||
device_id: getOrCreateUserID(),
|
||||
device_id: deviceId,
|
||||
// Only include OAuth account UUID when actively using OAuth authentication
|
||||
account_uuid: getOauthAccountInfo()?.accountUuid ?? '',
|
||||
session_id: getSessionId(),
|
||||
|
||||
@@ -74,7 +74,10 @@ import {
|
||||
} from '../../utils/errors.js'
|
||||
import { getMCPUserAgent } from '../../utils/http.js'
|
||||
import { maybeNotifyIDEConnected } from '../../utils/ide.js'
|
||||
import { maybeResizeAndDownsampleImageBuffer } from '../../utils/imageResizer.js'
|
||||
import {
|
||||
type ImageLimits,
|
||||
maybeResizeAndDownsampleImageBuffer,
|
||||
} from '../../utils/imageResizer.js'
|
||||
import { logMCPDebug, logMCPError } from '../../utils/log.js'
|
||||
import {
|
||||
getBinaryBlobSavedMessage,
|
||||
@@ -102,6 +105,7 @@ import {
|
||||
isPersistError,
|
||||
persistToolResult,
|
||||
} from '../../utils/toolResultStorage.js'
|
||||
import { checkStatsigFeatureGate_CACHED_MAY_BE_STALE } from '../analytics/growthbook.js'
|
||||
import {
|
||||
type AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
|
||||
logEvent,
|
||||
@@ -2486,15 +2490,23 @@ export function prefetchAllMcpResources(
|
||||
export async function transformResultContent(
|
||||
resultContent: PromptMessage['content'],
|
||||
serverName: string,
|
||||
limits?: ImageLimits,
|
||||
includeMeta = false,
|
||||
): Promise<Array<ContentBlockParam>> {
|
||||
switch (resultContent.type) {
|
||||
case 'text':
|
||||
return [
|
||||
{
|
||||
type: 'text',
|
||||
text: resultContent.text,
|
||||
},
|
||||
]
|
||||
case 'text': {
|
||||
const block: ContentBlockParam = {
|
||||
type: 'text',
|
||||
text: resultContent.text,
|
||||
}
|
||||
if (includeMeta) {
|
||||
const meta = resultContent._meta
|
||||
if (meta) {
|
||||
;(block as { _meta?: unknown })._meta = meta
|
||||
}
|
||||
}
|
||||
return [block]
|
||||
}
|
||||
case 'audio': {
|
||||
const audioData = resultContent as {
|
||||
type: 'audio'
|
||||
@@ -2516,6 +2528,7 @@ export async function transformResultContent(
|
||||
imageBuffer,
|
||||
imageBuffer.length,
|
||||
ext,
|
||||
limits,
|
||||
)
|
||||
return [
|
||||
{
|
||||
@@ -2551,6 +2564,7 @@ export async function transformResultContent(
|
||||
imageBuffer,
|
||||
imageBuffer.length,
|
||||
ext,
|
||||
limits,
|
||||
)
|
||||
const content: MessageParam['content'] = []
|
||||
if (prefix) {
|
||||
@@ -2671,6 +2685,7 @@ export async function transformMCPResult(
|
||||
result: unknown,
|
||||
tool: string, // Tool name for validation (e.g., "search")
|
||||
name: string, // Server name for transformation (e.g., "slack")
|
||||
limits?: ImageLimits, // Image processing limits, plumbed to transformResultContent
|
||||
): Promise<TransformedMCPResult> {
|
||||
if (result && typeof result === 'object') {
|
||||
if ('toolResult' in result) {
|
||||
@@ -2694,7 +2709,9 @@ export async function transformMCPResult(
|
||||
if ('content' in result && Array.isArray(result.content)) {
|
||||
const transformedContent = (
|
||||
await Promise.all(
|
||||
result.content.map(item => transformResultContent(item, name)),
|
||||
result.content.map(item =>
|
||||
transformResultContent(item, name, limits, true),
|
||||
),
|
||||
)
|
||||
).flat()
|
||||
return {
|
||||
@@ -2729,8 +2746,15 @@ export async function processMCPResult(
|
||||
result: unknown,
|
||||
tool: string, // Tool name for validation (e.g., "search")
|
||||
name: string, // Server name for IDE check and transformation (e.g., "slack")
|
||||
limits?: ImageLimits, // Image processing limits, plumbed to transformMCPResult
|
||||
skipLargeOutput = false, // If true, skip large-output handling for non-image content
|
||||
): Promise<MCPToolResult> {
|
||||
const { content, type, schema } = await transformMCPResult(result, tool, name)
|
||||
const { content, type, schema } = await transformMCPResult(
|
||||
result,
|
||||
tool,
|
||||
name,
|
||||
limits,
|
||||
)
|
||||
|
||||
// IDE tools are not going to the model directly, so we don't need to
|
||||
// handle large output.
|
||||
@@ -2738,6 +2762,12 @@ export async function processMCPResult(
|
||||
return content
|
||||
}
|
||||
|
||||
// Caller opted out of large-output handling (e.g., result already truncated
|
||||
// upstream); only continue if the content has images that may need handling.
|
||||
if (skipLargeOutput && !contentContainsImages(content)) {
|
||||
return content
|
||||
}
|
||||
|
||||
// Check if content needs truncation (i.e., is too large)
|
||||
if (!(await mcpContentNeedsTruncation(content))) {
|
||||
return content
|
||||
@@ -2775,9 +2805,15 @@ export async function processMCPResult(
|
||||
// Generate a unique ID for the persisted file (server__tool-timestamp)
|
||||
const timestamp = Date.now()
|
||||
const persistId = `mcp-${normalizeNameForMCP(name)}-${normalizeNameForMCP(tool)}-${timestamp}`
|
||||
// Convert to string for persistence (persistToolResult expects string or specific block types)
|
||||
// When the large-string format gate is on, unwrap a single bare text block
|
||||
// (no annotations, no _meta) into raw text so the model gets plain text in
|
||||
// the persisted file instead of a JSON-wrapped block. The `_meta` check is
|
||||
// why transformResultContent preserves _meta on text blocks.
|
||||
const unwrappedText = unwrapSingleTextBlock(content)
|
||||
const contentStr =
|
||||
typeof content === 'string' ? content : jsonStringify(content, null, 2)
|
||||
typeof content === 'string'
|
||||
? content
|
||||
: (unwrappedText ?? jsonStringify(content, null, 2))
|
||||
const persistResult = await persistToolResult(contentStr, persistId)
|
||||
|
||||
if (isPersistError(persistResult)) {
|
||||
@@ -2798,7 +2834,10 @@ export async function processMCPResult(
|
||||
persistedSizeChars: persistResult.originalSize,
|
||||
} as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS)
|
||||
|
||||
const formatDescription = getFormatDescription(type, schema)
|
||||
const formatDescription =
|
||||
unwrappedText !== undefined
|
||||
? getFormatDescription('toolResult')
|
||||
: getFormatDescription(type, schema)
|
||||
return getLargeOutputInstructions(
|
||||
persistResult.filepath,
|
||||
persistResult.originalSize,
|
||||
@@ -2806,6 +2845,39 @@ export async function processMCPResult(
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns true when the large-string output format is enabled (matches
|
||||
* binary's `sf8()`). When enabled, processMCPResult unwraps a single bare
|
||||
* text block to raw text for persistence instead of JSON-wrapping it.
|
||||
*
|
||||
* Gating sources, in order:
|
||||
* 1. MCP_TRUNCATION_PROMPT_OVERRIDE env var (anything except "legacy" enables)
|
||||
* 2. Statsig gate `tengu_mcp_subagent_prompt`
|
||||
*/
|
||||
function isLargeStringFormatEnabled(): boolean {
|
||||
const override = process.env.MCP_TRUNCATION_PROMPT_OVERRIDE
|
||||
if (override) return override !== 'legacy'
|
||||
return checkStatsigFeatureGate_CACHED_MAY_BE_STALE(
|
||||
'tengu_mcp_subagent_prompt',
|
||||
)
|
||||
}
|
||||
|
||||
/**
|
||||
* Unwraps a single bare text content block to its raw text when the
|
||||
* large-string format gate is on. Returns undefined when the gate is off,
|
||||
* the content is not an array, the array doesn't contain exactly one text
|
||||
* block, or the block carries annotations or _meta. Matches binary mg5's
|
||||
* `M=...` computation.
|
||||
*/
|
||||
function unwrapSingleTextBlock(content: MCPToolResult): string | undefined {
|
||||
if (!isLargeStringFormatEnabled()) return undefined
|
||||
if (!Array.isArray(content) || content.length !== 1) return undefined
|
||||
const block = content[0]
|
||||
if (!block || block.type !== 'text') return undefined
|
||||
if ('annotations' in block || '_meta' in block) return undefined
|
||||
return block.text
|
||||
}
|
||||
|
||||
/**
|
||||
* Call an MCP tool, handling UrlElicitationRequiredError (-32042) by
|
||||
* displaying the URL elicitation to the user, waiting for the completion
|
||||
@@ -2827,6 +2899,8 @@ export async function callMCPToolWithUrlElicitationRetry({
|
||||
signal,
|
||||
setAppState,
|
||||
onProgress,
|
||||
imageLimits,
|
||||
hasResultSizeAnnotation = false,
|
||||
callToolFn = callMCPTool,
|
||||
handleElicitation,
|
||||
}: {
|
||||
@@ -2838,6 +2912,8 @@ export async function callMCPToolWithUrlElicitationRetry({
|
||||
signal: AbortSignal
|
||||
setAppState: (f: (prev: AppState) => AppState) => void
|
||||
onProgress?: (data: MCPProgress) => void
|
||||
imageLimits?: ImageLimits
|
||||
hasResultSizeAnnotation?: boolean
|
||||
/** Injectable for testing. Defaults to callMCPTool. */
|
||||
callToolFn?: (opts: {
|
||||
client: ConnectedMCPServer
|
||||
@@ -2846,6 +2922,8 @@ export async function callMCPToolWithUrlElicitationRetry({
|
||||
meta?: Record<string, unknown>
|
||||
signal: AbortSignal
|
||||
onProgress?: (data: MCPProgress) => void
|
||||
imageLimits?: ImageLimits
|
||||
hasResultSizeAnnotation?: boolean
|
||||
}) => Promise<MCPToolCallResult>
|
||||
/** Handler for URL elicitations when no hook handles them.
|
||||
* In print/SDK mode, delegates to structuredIO. In REPL, falls back to queue. */
|
||||
@@ -2865,6 +2943,8 @@ export async function callMCPToolWithUrlElicitationRetry({
|
||||
meta,
|
||||
signal,
|
||||
onProgress,
|
||||
imageLimits,
|
||||
hasResultSizeAnnotation,
|
||||
})
|
||||
} catch (error) {
|
||||
// The MCP SDK's Protocol creates plain McpError (not UrlElicitationRequiredError)
|
||||
@@ -3041,6 +3121,8 @@ async function callMCPTool({
|
||||
meta,
|
||||
signal,
|
||||
onProgress,
|
||||
imageLimits,
|
||||
hasResultSizeAnnotation = false,
|
||||
}: {
|
||||
client: ConnectedMCPServer
|
||||
tool: string
|
||||
@@ -3048,6 +3130,8 @@ async function callMCPTool({
|
||||
meta?: Record<string, unknown>
|
||||
signal: AbortSignal
|
||||
onProgress?: (data: MCPProgress) => void
|
||||
imageLimits?: ImageLimits
|
||||
hasResultSizeAnnotation?: boolean
|
||||
}): Promise<{
|
||||
content: MCPToolResult
|
||||
_meta?: Record<string, unknown>
|
||||
@@ -3176,7 +3260,13 @@ async function callMCPTool({
|
||||
})
|
||||
}
|
||||
|
||||
const content = await processMCPResult(result, tool, name)
|
||||
const content = await processMCPResult(
|
||||
result,
|
||||
tool,
|
||||
name,
|
||||
imageLimits,
|
||||
hasResultSizeAnnotation,
|
||||
)
|
||||
return {
|
||||
content,
|
||||
_meta: result._meta as Record<string, unknown> | undefined,
|
||||
|
||||
@@ -85,6 +85,7 @@ export type FooterItem =
|
||||
| 'teams'
|
||||
| 'bridge'
|
||||
| 'companion'
|
||||
| 'bg_agent'
|
||||
|
||||
export type AppState = DeepImmutable<{
|
||||
settings: SettingsJson
|
||||
@@ -97,6 +98,9 @@ export type AppState = DeepImmutable<{
|
||||
// Optional - only present when ENABLE_AGENT_SWARMS is true (for dead code elimination)
|
||||
showTeammateMessagePreview?: boolean
|
||||
selectedIPAgentIndex: number
|
||||
// Selection index for the bottom BackgroundAgentSelector.
|
||||
// -1 = main, 0..N-1 = index into useBackgroundAgentTasks().
|
||||
selectedBgAgentIndex: number
|
||||
// CoordinatorTaskPanel selection: -1 = pill, 0 = main, 1..N = agent rows.
|
||||
// AppState (not local) so the panel can read it directly without prop-drilling
|
||||
// through PromptInput → PromptInputFooter.
|
||||
@@ -477,6 +481,7 @@ export function getDefaultAppState(): AppState {
|
||||
isBriefOnly: false,
|
||||
showTeammateMessagePreview: false,
|
||||
selectedIPAgentIndex: -1,
|
||||
selectedBgAgentIndex: -1,
|
||||
coordinatorTaskIndex: -1,
|
||||
viewSelectionMode: 'none',
|
||||
footerSelection: null,
|
||||
|
||||
@@ -229,6 +229,10 @@ export interface ContextData {
|
||||
cache_creation_input_tokens: number
|
||||
cache_read_input_tokens: number
|
||||
} | null
|
||||
/** Cache hit rate percentage (0-100), undefined if no data */
|
||||
readonly cacheHitRate?: number
|
||||
/** Cache warning threshold percentage */
|
||||
readonly cacheThreshold?: number
|
||||
}
|
||||
|
||||
export async function countToolDefinitionTokens(
|
||||
@@ -1396,5 +1400,13 @@ export async function analyzeContextUsage(
|
||||
isAutoCompactEnabled: isAutoCompact,
|
||||
messageBreakdown: formattedMessageBreakdown,
|
||||
apiUsage,
|
||||
...(() => {
|
||||
if (!apiUsage) return {}
|
||||
const { calculateCacheHitRate, getCacheThreshold } =
|
||||
require('./cacheWarning.js') as typeof import('./cacheWarning.js')
|
||||
const hitRate = calculateCacheHitRate(apiUsage)
|
||||
if (hitRate === null) return {}
|
||||
return { cacheHitRate: hitRate, cacheThreshold: getCacheThreshold() }
|
||||
})(),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -18,18 +18,12 @@ import {
|
||||
type AttributionData,
|
||||
calculateCommitAttribution,
|
||||
isInternalModelRepo,
|
||||
isInternalModelRepoCached,
|
||||
sanitizeModelName,
|
||||
} from './commitAttribution.js'
|
||||
import { logForDebugging } from './debug.js'
|
||||
import { parseJSONL } from './json.js'
|
||||
import { logError } from './log.js'
|
||||
import {
|
||||
getCanonicalName,
|
||||
getMainLoopModel,
|
||||
getPublicModelDisplayName,
|
||||
getPublicModelName,
|
||||
} from './model/model.js'
|
||||
import { getAttributionEmail } from './attributionEmail.js'
|
||||
import { getRealModelName } from './attributionModel.js'
|
||||
import { isMemoryFileAccess } from './sessionFileAccessHooks.js'
|
||||
import { getTranscriptPath } from './sessionStorage.js'
|
||||
import { readTranscriptForLoad } from './sessionStoragePortable.js'
|
||||
@@ -44,7 +38,8 @@ export type AttributionTexts = {
|
||||
/**
|
||||
* Returns attribution text for commits and PRs based on user settings.
|
||||
* Handles:
|
||||
* - Dynamic model name via getPublicModelName()
|
||||
* - Dynamic model name via getRealModelName()
|
||||
* - Auto email mapping via getAttributionEmail()
|
||||
* - Custom attribution settings (settings.attribution.commit/pr)
|
||||
* - Backward compatibility with deprecated includeCoAuthoredBy setting
|
||||
* - Remote mode: returns session URL for attribution
|
||||
@@ -67,17 +62,10 @@ export function getAttributionTexts(): AttributionTexts {
|
||||
return { commit: '', pr: '' }
|
||||
}
|
||||
|
||||
// @[MODEL LAUNCH]: Update the hardcoded fallback model name below (guards against codename leaks).
|
||||
// For internal repos, use the real model name. For external repos,
|
||||
// fall back to "Claude Opus 4.6" for unrecognized models to avoid leaking codenames.
|
||||
const model = getMainLoopModel()
|
||||
const isKnownPublicModel = getPublicModelDisplayName(model) !== null
|
||||
const modelName =
|
||||
isInternalModelRepoCached() || isKnownPublicModel
|
||||
? getPublicModelName(model)
|
||||
: 'Claude Opus 4.7'
|
||||
const defaultAttribution = `🤖 Generated with [Claude Code](${PRODUCT_URL})`
|
||||
const defaultCommit = `Co-Authored-By: ${modelName} <noreply@anthropic.com>`
|
||||
const modelName = getRealModelName()
|
||||
const email = getAttributionEmail(modelName)
|
||||
const defaultAttribution = `🤖 Generated with [Claude Code Best](${PRODUCT_URL})`
|
||||
const defaultCommit = `Co-Authored-By: ${modelName} <${email}>`
|
||||
|
||||
const settings = getInitialSettings()
|
||||
|
||||
@@ -354,11 +342,8 @@ export async function getEnhancedPRAttribution(
|
||||
`PR Attribution: claudePercent: ${claudePercent}, promptCount: ${promptCount}, memoryAccessCount: ${memoryAccessCount}`,
|
||||
)
|
||||
|
||||
// Get short model name, sanitized for non-internal repos
|
||||
const rawModelName = getCanonicalName(getMainLoopModel())
|
||||
const shortModelName = isInternal
|
||||
? rawModelName
|
||||
: sanitizeModelName(rawModelName)
|
||||
// Get real model name for attribution
|
||||
const realModelName = getRealModelName()
|
||||
|
||||
// If no attribution data, return default
|
||||
if (claudePercent === 0 && promptCount === 0 && memoryAccessCount === 0) {
|
||||
@@ -371,7 +356,7 @@ export async function getEnhancedPRAttribution(
|
||||
memoryAccessCount > 0
|
||||
? `, ${memoryAccessCount} ${memoryAccessCount === 1 ? 'memory' : 'memories'} recalled`
|
||||
: ''
|
||||
const summary = `🤖 Generated with [Claude Code](${PRODUCT_URL}) (${claudePercent}% ${promptCount}-shotted by ${shortModelName}${memSuffix})`
|
||||
const summary = `🤖 Generated with [Claude Code Best](${PRODUCT_URL}) (${claudePercent}% ${promptCount}-shotted by ${realModelName}${memSuffix})`
|
||||
|
||||
// Append trailer lines for squash-merge survival. Only for allowlisted repos
|
||||
// (INTERNAL_MODEL_REPOS) and only in builds with COMMIT_ATTRIBUTION enabled —
|
||||
|
||||
27
src/utils/attributionEmail.ts
Normal file
27
src/utils/attributionEmail.ts
Normal file
@@ -0,0 +1,27 @@
|
||||
const MODEL_EMAIL_MAP: Array<{ keywords: string[]; email: string }> = [
|
||||
{ keywords: ['claude'], email: 'noreply@anthropic.com' },
|
||||
// 由于找不到他们的邮箱和头像, 所以改为了使用我们的邮箱先记录, 后续官方有 github 能用的邮箱可以替换
|
||||
// github 组织是不能用 co author 的
|
||||
{
|
||||
keywords: ['gpt', 'dall-e', 'o1-', 'o3-', 'o4-'],
|
||||
email: 'openai@claude-code-best.win',
|
||||
},
|
||||
{ keywords: ['gemini'], email: 'google-gemini@claude-code-best.win' },
|
||||
{ keywords: ['grok'], email: 'xai-org@claude-code-best.win' },
|
||||
{ keywords: ['glm'], email: 'zai-org@claude-code-best.win' },
|
||||
{ keywords: ['deepseek'], email: 'deepseek-ai@claude-code-best.win' },
|
||||
{ keywords: ['qwen'], email: 'QwenLM@claude-code-best.win' },
|
||||
{ keywords: ['minimax'], email: 'MiniMax-AI@claude-code-best.win' },
|
||||
{ keywords: ['mimo'], email: 'XiaomiMiMo@claude-code-best.win' },
|
||||
{ keywords: ['kimi'], email: 'MoonshotAI@claude-code-best.win' },
|
||||
]
|
||||
|
||||
export function getAttributionEmail(modelName: string): string {
|
||||
const lower = modelName.toLowerCase()
|
||||
for (const { keywords, email } of MODEL_EMAIL_MAP) {
|
||||
if (keywords.some(kw => lower.includes(kw))) {
|
||||
return email
|
||||
}
|
||||
}
|
||||
return 'noreply@anthropic.com'
|
||||
}
|
||||
24
src/utils/attributionModel.ts
Normal file
24
src/utils/attributionModel.ts
Normal file
@@ -0,0 +1,24 @@
|
||||
import {
|
||||
resolveGeminiModel,
|
||||
resolveGrokModel,
|
||||
resolveOpenAIModel,
|
||||
} from '@ant/model-provider'
|
||||
import { getMainLoopModel } from './model/model.js'
|
||||
import { getAPIProvider } from './model/providers.js'
|
||||
|
||||
function resolveProviderModel(anthropicModel: string): string {
|
||||
switch (getAPIProvider()) {
|
||||
case 'openai':
|
||||
return resolveOpenAIModel(anthropicModel)
|
||||
case 'gemini':
|
||||
return resolveGeminiModel(anthropicModel)
|
||||
case 'grok':
|
||||
return resolveGrokModel(anthropicModel)
|
||||
default:
|
||||
return anthropicModel
|
||||
}
|
||||
}
|
||||
|
||||
export function getRealModelName(): string {
|
||||
return resolveProviderModel(getMainLoopModel())
|
||||
}
|
||||
131
src/utils/cacheWarning.ts
Normal file
131
src/utils/cacheWarning.ts
Normal file
@@ -0,0 +1,131 @@
|
||||
import { createUserMessage } from './messages.js'
|
||||
import { getInitialSettings } from './settings/settings.js'
|
||||
import type { Message } from '../types/message.js'
|
||||
|
||||
// Usage 类型（从 API 响应中提取）
|
||||
interface Usage {
|
||||
input_tokens: number
|
||||
cache_creation_input_tokens: number
|
||||
cache_read_input_tokens: number
|
||||
}
|
||||
|
||||
export interface CacheHitRateInfo {
|
||||
hitRate: number
|
||||
threshold: number
|
||||
trend: number | null // 正数=上升，负数=下降
|
||||
shouldWarn: boolean
|
||||
}
|
||||
|
||||
interface CacheWarningState {
|
||||
lastHitRate: number | null
|
||||
lastTimestamp: number | null
|
||||
}
|
||||
|
||||
// 模块级状态，每个 querySource 独立跟踪
|
||||
const cacheWarningStateBySource = new Map<string, CacheWarningState>()
|
||||
|
||||
const DEFAULT_CACHE_THRESHOLD = 80
|
||||
|
||||
/**
|
||||
* 从 settings.json 读取缓存阈值配置
|
||||
*/
|
||||
export function getCacheThreshold(): number {
|
||||
const settings = getInitialSettings()
|
||||
return settings.cacheThreshold ?? DEFAULT_CACHE_THRESHOLD
|
||||
}
|
||||
|
||||
/**
|
||||
* 计算缓存命中率
|
||||
* 返回值范围 0-100，null 表示无有效数据
|
||||
*/
|
||||
export function calculateCacheHitRate(
|
||||
usage: Usage | null | undefined,
|
||||
): number | null {
|
||||
if (!usage) return null
|
||||
|
||||
const { input_tokens, cache_creation_input_tokens, cache_read_input_tokens } =
|
||||
usage
|
||||
|
||||
// 所有缓存字段为 0 表示无缓存数据
|
||||
if (cache_read_input_tokens === 0 && cache_creation_input_tokens === 0) {
|
||||
return null
|
||||
}
|
||||
|
||||
const totalInputTokens =
|
||||
input_tokens + cache_creation_input_tokens + cache_read_input_tokens
|
||||
if (totalInputTokens === 0) return null
|
||||
|
||||
return (cache_read_input_tokens / totalInputTokens) * 100
|
||||
}
|
||||
|
||||
/**
|
||||
* 检测是否需要显示缓存警告
|
||||
* @param usage API usage 数据
|
||||
* @param querySource 查询来源（用于独立跟踪状态）
|
||||
* @param threshold 缓存阈值百分比
|
||||
* @returns 警告信息，如果不需要警告则返回 null
|
||||
*/
|
||||
export function shouldShowCacheWarning(
|
||||
usage: Usage | null | undefined,
|
||||
querySource: string,
|
||||
threshold: number,
|
||||
): CacheHitRateInfo | null {
|
||||
const hitRate = calculateCacheHitRate(usage)
|
||||
|
||||
// 无缓存数据
|
||||
if (hitRate === null) {
|
||||
return null
|
||||
}
|
||||
|
||||
// 获取或初始化该 querySource 的状态
|
||||
let state = cacheWarningStateBySource.get(querySource)
|
||||
if (!state) {
|
||||
state = { lastHitRate: null, lastTimestamp: null }
|
||||
cacheWarningStateBySource.set(querySource, state)
|
||||
}
|
||||
|
||||
// 首次请求不显示警告
|
||||
if (state.lastHitRate === null) {
|
||||
state.lastHitRate = hitRate
|
||||
state.lastTimestamp = Date.now()
|
||||
return null
|
||||
}
|
||||
|
||||
// 计算趋势
|
||||
const trend = hitRate - state.lastHitRate
|
||||
|
||||
// 更新状态
|
||||
state.lastHitRate = hitRate
|
||||
state.lastTimestamp = Date.now()
|
||||
|
||||
// 检查是否需要警告
|
||||
if (hitRate < threshold) {
|
||||
return { hitRate, threshold, trend, shouldWarn: true }
|
||||
}
|
||||
|
||||
return null
|
||||
}
|
||||
|
||||
/**
|
||||
* 生成缓存警告消息
|
||||
* @param info 缓存警告信息
|
||||
* @returns 用户消息，标记为 isVisibleInTranscriptOnly
|
||||
*/
|
||||
export function createCacheWarningMessage(info: CacheHitRateInfo): Message {
|
||||
const { hitRate, threshold, trend } = info
|
||||
|
||||
// 构建消息内容
|
||||
let content = `Cache hit rate ${hitRate.toFixed(0)}%, below ${threshold}% threshold`
|
||||
|
||||
if (trend !== null && Math.abs(trend) > 0.1) {
|
||||
const trendIcon = trend > 0 ? '^' : 'v'
|
||||
const trendPercent = Math.abs(trend).toFixed(0)
|
||||
content += ` (${trendIcon}${trendPercent}%)`
|
||||
}
|
||||
|
||||
return createUserMessage({
|
||||
content,
|
||||
isMeta: true,
|
||||
isVisibleInTranscriptOnly: true,
|
||||
})
|
||||
}
|
||||
@@ -162,6 +162,16 @@ interface CompressedImageResult {
|
||||
originalSize: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Per-call image processing limits, overriding the module-level defaults.
|
||||
*/
|
||||
export interface ImageLimits {
|
||||
targetRawSize: number
|
||||
maxWidth: number
|
||||
maxHeight: number
|
||||
maxBase64Size: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Extracted from FileReadTool's readImage function
|
||||
* Resizes image buffer to meet size and dimension constraints
|
||||
@@ -170,7 +180,13 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
imageBuffer: Buffer,
|
||||
originalSize: number,
|
||||
ext: string,
|
||||
limits?: ImageLimits,
|
||||
): Promise<ResizeResult> {
|
||||
const targetRawSize = limits?.targetRawSize ?? IMAGE_TARGET_RAW_SIZE
|
||||
const maxWidth = limits?.maxWidth ?? IMAGE_MAX_WIDTH
|
||||
const maxHeight = limits?.maxHeight ?? IMAGE_MAX_HEIGHT
|
||||
const maxBase64Size = limits?.maxBase64Size ?? API_IMAGE_MAX_BASE64_SIZE
|
||||
|
||||
if (imageBuffer.length === 0) {
|
||||
// Empty buffer would fall through the catch block below (sharp throws
|
||||
// "Unable to determine image format"), and the fallback's size check
|
||||
@@ -189,7 +205,7 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
|
||||
// If dimensions aren't available from metadata
|
||||
if (!metadata.width || !metadata.height) {
|
||||
if (originalSize > IMAGE_TARGET_RAW_SIZE) {
|
||||
if (originalSize > targetRawSize) {
|
||||
// Create fresh sharp instance for compression
|
||||
const compressedBuffer = await sharp(imageBuffer)
|
||||
.jpeg({ quality: 80 })
|
||||
@@ -210,9 +226,9 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
|
||||
// Check if the original file just works
|
||||
if (
|
||||
originalSize <= IMAGE_TARGET_RAW_SIZE &&
|
||||
width <= IMAGE_MAX_WIDTH &&
|
||||
height <= IMAGE_MAX_HEIGHT
|
||||
originalSize <= targetRawSize &&
|
||||
width <= maxWidth &&
|
||||
height <= maxHeight
|
||||
) {
|
||||
return {
|
||||
buffer: imageBuffer,
|
||||
@@ -226,20 +242,19 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
}
|
||||
}
|
||||
|
||||
const needsDimensionResize =
|
||||
width > IMAGE_MAX_WIDTH || height > IMAGE_MAX_HEIGHT
|
||||
const needsDimensionResize = width > maxWidth || height > maxHeight
|
||||
const isPng = normalizedMediaType === 'png'
|
||||
|
||||
// If dimensions are within limits but file is too large, try compression first
|
||||
// This preserves full resolution when possible
|
||||
if (!needsDimensionResize && originalSize > IMAGE_TARGET_RAW_SIZE) {
|
||||
if (!needsDimensionResize && originalSize > targetRawSize) {
|
||||
// For PNGs, try PNG compression first to preserve transparency
|
||||
if (isPng) {
|
||||
// Create fresh sharp instance for each compression attempt
|
||||
const pngCompressed = await sharp(imageBuffer)
|
||||
.png({ compressionLevel: 9, palette: true })
|
||||
.toBuffer()
|
||||
if (pngCompressed.length <= IMAGE_TARGET_RAW_SIZE) {
|
||||
if (pngCompressed.length <= targetRawSize) {
|
||||
return {
|
||||
buffer: pngCompressed,
|
||||
mediaType: 'png',
|
||||
@@ -258,7 +273,7 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
const compressedBuffer = await sharp(imageBuffer)
|
||||
.jpeg({ quality })
|
||||
.toBuffer()
|
||||
if (compressedBuffer.length <= IMAGE_TARGET_RAW_SIZE) {
|
||||
if (compressedBuffer.length <= targetRawSize) {
|
||||
return {
|
||||
buffer: compressedBuffer,
|
||||
mediaType: 'jpeg',
|
||||
@@ -275,14 +290,14 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
}
|
||||
|
||||
// Constrain dimensions if needed
|
||||
if (width > IMAGE_MAX_WIDTH) {
|
||||
height = Math.round((height * IMAGE_MAX_WIDTH) / width)
|
||||
width = IMAGE_MAX_WIDTH
|
||||
if (width > maxWidth) {
|
||||
height = Math.round((height * maxWidth) / width)
|
||||
width = maxWidth
|
||||
}
|
||||
|
||||
if (height > IMAGE_MAX_HEIGHT) {
|
||||
width = Math.round((width * IMAGE_MAX_HEIGHT) / height)
|
||||
height = IMAGE_MAX_HEIGHT
|
||||
if (height > maxHeight) {
|
||||
width = Math.round((width * maxHeight) / height)
|
||||
height = maxHeight
|
||||
}
|
||||
|
||||
// IMPORTANT: Always create fresh sharp(imageBuffer) instances for each operation.
|
||||
@@ -298,7 +313,7 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
.toBuffer()
|
||||
|
||||
// If still too large after resize, try compression
|
||||
if (resizedImageBuffer.length > IMAGE_TARGET_RAW_SIZE) {
|
||||
if (resizedImageBuffer.length > targetRawSize) {
|
||||
// For PNGs, try PNG compression first to preserve transparency
|
||||
if (isPng) {
|
||||
const pngCompressed = await sharp(imageBuffer)
|
||||
@@ -308,7 +323,7 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
})
|
||||
.png({ compressionLevel: 9, palette: true })
|
||||
.toBuffer()
|
||||
if (pngCompressed.length <= IMAGE_TARGET_RAW_SIZE) {
|
||||
if (pngCompressed.length <= targetRawSize) {
|
||||
return {
|
||||
buffer: pngCompressed,
|
||||
mediaType: 'png',
|
||||
@@ -331,7 +346,7 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
})
|
||||
.jpeg({ quality })
|
||||
.toBuffer()
|
||||
if (compressedBuffer.length <= IMAGE_TARGET_RAW_SIZE) {
|
||||
if (compressedBuffer.length <= targetRawSize) {
|
||||
return {
|
||||
buffer: compressedBuffer,
|
||||
mediaType: 'jpeg',
|
||||
@@ -407,11 +422,11 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
imageBuffer[1] === 0x50 &&
|
||||
imageBuffer[2] === 0x4e &&
|
||||
imageBuffer[3] === 0x47 &&
|
||||
(imageBuffer.readUInt32BE(16) > IMAGE_MAX_WIDTH ||
|
||||
imageBuffer.readUInt32BE(20) > IMAGE_MAX_HEIGHT)
|
||||
(imageBuffer.readUInt32BE(16) > maxWidth ||
|
||||
imageBuffer.readUInt32BE(20) > maxHeight)
|
||||
|
||||
// If original image's base64 encoding is within API limit, allow it through uncompressed
|
||||
if (base64Size <= API_IMAGE_MAX_BASE64_SIZE && !overDim) {
|
||||
if (base64Size <= maxBase64Size && !overDim) {
|
||||
logEvent('tengu_image_resize_fallback', {
|
||||
original_size_bytes: originalSize,
|
||||
base64_size_bytes: base64Size,
|
||||
@@ -423,7 +438,7 @@ export async function maybeResizeAndDownsampleImageBuffer(
|
||||
// Image is too large and we failed to compress it - fail with user-friendly error
|
||||
throw new ImageResizeError(
|
||||
overDim
|
||||
? `Unable to resize image — dimensions exceed the ${IMAGE_MAX_WIDTH}x${IMAGE_MAX_HEIGHT}px limit and image processing failed. ` +
|
||||
? `Unable to resize image — dimensions exceed the ${maxWidth}x${maxHeight}px limit and image processing failed. ` +
|
||||
`Please resize the image to reduce its pixel dimensions.`
|
||||
: `Unable to resize image (${formatFileSize(originalSize)} raw, ${formatFileSize(base64Size)} base64). ` +
|
||||
`The image exceeds the 5MB API limit and compression failed. ` +
|
||||
|
||||
@@ -552,6 +552,7 @@ export const SettingsSchema = lazySchema(() =>
|
||||
type: z.literal('command'),
|
||||
command: z.string(),
|
||||
padding: z.number().optional(),
|
||||
refreshInterval: z.number().optional(),
|
||||
})
|
||||
.optional()
|
||||
.describe('Custom status line display configuration'),
|
||||
@@ -1071,6 +1072,15 @@ export const SettingsSchema = lazySchema(() =>
|
||||
'Only applies to User, Project, and Local memory types (Managed/policy files cannot be excluded). ' +
|
||||
'Examples: "/home/user/monorepo/CLAUDE.md", "**/code/CLAUDE.md", "**/some-dir/.claude/rules/**"',
|
||||
),
|
||||
cacheThreshold: z
|
||||
.number()
|
||||
.int()
|
||||
.min(0)
|
||||
.max(100)
|
||||
.optional()
|
||||
.describe(
|
||||
'Prompt cache hit rate threshold (0-100). Warnings shown when cache hit rate falls below this percentage. Default: 80.',
|
||||
),
|
||||
pluginTrustMessage: z
|
||||
.string()
|
||||
.optional()
|
||||
|
||||
Reference in New Issue
Block a user