@swifty.js/swifty 0.0.1 → 0.0.2

package/docs/ch2.md

@@ -1,273 +0,0 @@
-# LLM API、对话管理
-
-请求 Demo
-
-```bash
-# Anthropic
-curl https://api.anthropic.com/v1/messages \
-  -H 'Content-Type: application/json'      \
-  -H 'anthropic-version: 2023-06-01'       \
-  -H "X-Api-Key: $ANTHROPIC_API_KEY"       \
-  -d '{
-    "max_tokens": 1024,
-    "model": "claude-sonnet-4-6",
-    "messages": [
-      {
-        "role": "user",
-        "content": "Hello claude."
-      }
-    ]
-  }'
-```
-
-响应 Demo
-
-<!-- 源码: src/llm/anthropic.ts (usage 字段) -->
-
-```json
-{
-  "id": "msg_abcdefghijklmn0123456789",
-  "type": "message",
-  "role": "assistant",
-  "content": [
-    {
-      "type": "text",
-      "text": "Hello! How can I assist you today?"
-    }
-  ],
-  "model": "claude-sonnet-4-6",
-  "stop_reason": "end_turn",
-  "usage": {
-    "input_tokens": 10,
-    "output_tokens": 12,
-    "cache_read_input_tokens": 0,
-    "cache_creation_input_tokens": 0
-  }
-}
-```
-
-- 请求的 messages: 每条 message 有 role 和 content 两个字段, role (API 请求场景下) 只有两个值: user 和 assistant; messages 数组中, 最好保持 user 和 assistant 两个 role 交替出现; 如果连续传递两条 user 消息, API 不会报错, 会自动合并为一条 user 消息
-- LLM 返回一个工具调用 (tool_use) 请求, 这是 assistant 消息; 用户调用工具拿到结果, 该工具调用结果需要作为 user 消息发送; 如果错误的将工具调用结果作为 assistant 消息发送, 则会导致连续两条 assistant 消息, API 会直接报错
-- 响应的 content 字段是一个数组: LLM 的响应可能包含多种内容, 每种内容是一个独立的 content block, 类型可能是 text、tool_use 等
-- 流式响应基于 SSE (Server-Sent Events), 本质是 HTTP 长连接
-
-Claude 的流式事件有固定顺序
-
-<!-- 源码: src/llm/anthropic.ts (SSE 事件处理) -->
-
-```txt
-message_start 整个响应开始, 携带 input_tokens 输入 token 数、cache_read_input_tokens、cache_creation_input_tokens
-  content_block_start 一个内容块开始 (thinking 推理、text 文本或 tool_use 工具调用), 一个响应可能有多个 content_block 内容块
-    content_block_delta 内容块的内容增量, delta.type 有 4 种:
-      text_delta 文本增量, 每到达一个词, 可以将内容增量提交给 UI 渲染
-      thinking_delta 推理增量
-      input_json_delta 工具调用参数增量
-      signature_delta 签名增量
-  content_block_stop 一个内容块结束
-message_delta 消息增量 (output_tokens 输出 token 数, stop_reason 停止原因)
-message_stop 整个响应结束
-```
-
-<!-- 源码: src/llm/events.ts (StreamEvent) -->
-
-封装层将 LLM API 的 SSE 事件映射到 CLI 的 StreamEvent:
-
-```txt
-content_block_delta (text_delta)       -> text_delta
-content_block_delta (thinking_delta)   -> thinking_delta
-content_block_stop                     -> thinking_complete
-content_block_start (tool_use)         -> tool_call_start
-content_block_delta (input_json_delta) -> tool_call_delta
-content_block_stop                     -> tool_call_complete
-message_stop                           -> stream_end
-```
-
-## 请求的 system, messages, tools
-
-- system 参数存放用户信息和环境信息, 包括: 你是谁、操作系统是什么、工作目录是什么
-- messages 参数存放对话历史、上下文窗口
-- tools 参数存放工具描述
-
-<!-- 源码: src/llm/anthropic.ts -->
-<!-- 源码: src/tools/read-file.ts (ReadFile 工具定义、描述) -->
-
-```json
-{
-  "model": "claude-sonnet-4-6",
-  "max_tokens": 4096,
-  "system": [
-    {
-      "type": "text",
-      "text": "You are Swifty, a terminal AI programming assistant.\n\n# Environment\nOperating System: MacOS\nWorking Directory: /path/to/cwd\nCurrent Time: 2026-06-22",
-      "cache_control": { "type": "ephemeral" }
-    }
-  ],
-  "messages": [
-    { "role": "user", "content": "Explain the contents of ./app.ts." },
-    {
-      "role": "assistant",
-      "content": "Sure, let me read the contents of ./app.ts.\nfunction main() {\n  console.log(\"javascript newbie\")\n}"
-    },
-    { "role": "user", "content": "What functions are in this file?" }
-  ],
-  "tools": [
-    {
-      "name": "ReadFile",
-      "description": "Read a file and return its contents with line numbers.\n\nUsage Notes\n\n- The file_path should be an absolute path when possible.\n- By default reads up to 2000 lines from the beginning of the file.\n- Use offset and limit to read specific parts of large files.",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "file_path": {
-            "type": "string",
-            "description": "Absolute path to the file"
-          },
-          "offset": {
-            "type": "integer",
-            "description": "Line number to start from (0-based)",
-            "default": 0
-          },
-          "limit": {
-            "type": "integer",
-            "description": "Max lines to read",
-            "default": 2000
-          }
-        },
-        "required": ["file_path"]
-      }
-    }
-  ]
-}
-```
-
-<!-- 源码: src/llm/anthropic.ts (最后一个 tool 标记 cache_control) -->
-
-### OpenAI 兼容
-
-<!-- 源码: src/llm/openai.ts (OpenAIClient.stream) -->
-
-```json
-{
-  "model": "gpt-4.1",
-  "max_output_tokens": 4096, // 使用 max_output_tokens 而不是 max_tokens
-  "input": [
-    // 使用 input 而不是 messages
-    { "role": "system", "content": "You are a helpful assistant." },
-    { "role": "user", "content": "Hello" }
-  ],
-  "stream": true
-}
-```
-
-OpenAI 没有 prompt cache 的 cache_control, cache_read 通过 `usage.input_tokens_details.cached_tokens` 返回
-
-<!-- 源码: src/llm/openai.ts (OpenAI cache_read 解析) -->
-
-## token
-
-token 是 LLM 的计费单位, 每个英文单词约 1-2 个 token, 每个汉字约 1-2 个 token, 具体取决于 LLM 使用的 tokenizer
-
-Claude API 的计费分为
-
-- inputTokens: 未命中 prompt cache 的输入 token 数, 即发送给 LLM 的内容, 即 system_prompt, tools 描述和 messages 中未命中 prompt cache 的输入
-- outputTokens: 输出 token 数, 即 LLM 生成的内容, 输出 token 比输入 token 贵的多
-- cacheReadInputTokens: 命中 prompt cache 的输入 token 数, 价格远低于普通 input_tokens
-- cacheCreationInputTokens: 创建 prompt cache 的输入 token 数, 价格略高于普通 input_tokens
-
-<!-- 源码: src/llm/events.ts (UsageInfo 接口, 包含 4 个 token 字段) -->
-
-### 历史越长、输入越贵
-
-每轮请求, 都需要发送完整的对话历史; 如果和 LLM 聊了 20 轮, 第 21 轮请求会包含前 20 轮的所有消息; input_tokens 会随着对话轮次线形增长, 所以需要上下文压缩
-
-## Extend Thinking 推理
-
-Claude 支持 Extended Thinking, 让 LLM 回复前先进行内部推理, 开启后响应的 content 数组中会多一个 `type: thinking` 的内容块, 排在 text 内容块的前面; thinking 的 token 计算到 output_tokens 中;
-
-包含工具调用的一轮对话, 对话历史中的 thinking 内容块必须携带, 和后面的 tool_result 一起发送给 LLM API, 否则会报错; 对于纯聊天、没有工具调用的场景, 则对话历史中的 thinking 内容块可以不携带, LLM API 会自动忽略
-
-<!-- 源码: src/conversation/conversation.ts (ThinkingBlock 接口: thinking + signature) -->
-<!-- 源码: src/llm/anthropic.ts (assistant 消息 thinking block 的 API 转换) -->
-
-## 如何封装
-
-ProviderConfig 有 8 个字段, 覆盖主流厂商: Anthropic、OpenAI、OpenAI 兼容层
-
-<!-- 源码: src/config/config.ts (ProviderConfigSchema) -->
-
-- name: provider 名称
-- protocol: LLM API 协议, 枚举值 "anthropic" | "openai" | "openai-compat"
-- base_url: 端点地址
-- model: LLM 模型, 例如 claude-haiku-4-6、claude-sonnet-4-6、claude-opus-4-6
-- api_key: 令牌
-- thinking: 是否开启 extended thinking (可选)
-- context_window: 上下文窗口大小 (可选, 默认 200_000)
-- max_output_tokens: 最大输出 token 数 (可选, thinking 开启时默认 200_000, 关闭时默认 128_000)
-
-<!-- 源码: src/config/config.ts (getMaxOutputTokens 默认值逻辑) -->
-<!-- 源码: src/config/config.ts (DEFAULT_CONTEXT_WINDOW = 200_000) -->
-
-封装层负责翻译
-
-## 多轮对话如何实现
-
-每一轮 LLM API 请求, 都包含完整的对话历史, 需要在客户端维护完整的消息列表, 每次用户 (CLI) 发送请求、LLM 响应, 都需要记录, token 消耗会随着对话轮次线形增长
-
-### 消息模型
-
-<!-- 源码: src/conversation/conversation.ts (Message 接口) -->
-
-内部 Message 接口:
-
-```ts
-interface Message {
-  role: "user" | "assistant" | "system";
-  content: string;
-  thinkingBlocks?: ThinkingBlock[];
-  toolUses?: ToolUseBlock[];
-  toolResults?: ToolResultBlock[];
-}
-```
-
-- role: user, assistant, system
-- content: 消息内容
-- thinkingBlocks: 可选, assistant 消息的 extended thinking 推理块 (包含 thinking 文本和 signature)
-- toolUses: 可选, assistant 消息中的工具调用请求列表 (包含 toolUseId、toolName、arguments)
-- toolResults: 可选, user 消息中的工具调用结果列表 (包含 toolUseId、content、isError)
-
-内部层
-
-- ID: `msg_<hash>` 可以根据消息 ID 定位到正在接收的 assistant 消息, 并追加 SSE chunk
-- status: streaming, complete, error 封装层翻译时可以过滤 error 状态的消息
-- timestamp
-- usage: `{ inputTokens, outputTokens, cacheReadInputTokens, cacheCreationInputTokens }`
-- role: user, assistant, system, tool (Only for OpenAI)
-- content: 消息内容 (thinking 推理、text 文本、tool_use 工具调用或其他...)
-
-<!-- 源码: src/llm/openai.ts (buildChatCompletionMessages) -->
-
-### 对话管理器
-
-考虑到流式接收, CLI 正在向 assistant 消息 (SSE chunk 数组) 中追加 SSE chunk, 同时 TUI 正在读 assistant 消息 (SSE chunk 数组) 以渲染 TUI, 两处同时操作同一个列表, 可能导致数据竞争
-
-- Node.js 单线程异步, 避免数据竞争
-- Go 加锁
-
-追加 SSE chunk 时, 拿到 assistant 消息的唯一 ID, 根据 ID 追加 SSE chunk; 更新 TUI 时, 根据 ID 拿到一份 assistant 消息的快照
-
-## 格式转换: 内部消息到 LLM API 消息
-
-- [Anthropic](../src/llm/anthropic.ts)
-- [OpenAI](../src/llm/openai.ts)
-
-<!-- 源码: src/llm/anthropic.ts (buildAnthropicMessages) -->
-
-1. 转换: 内部 Message 的 thinkingBlocks、content、toolUses 转换为 LLM API 的 content block; toolResults 转换为 LLM API 的 tool_result block
-2. 合并: 虽然 Claude API 可以自动合并相邻的相同 role 的消息, 但是在客户端合并是更好的做法, 消息结构更清晰, 减少 token 消耗
-3. 过滤后第一条消息的 role 必须是 user, 并且 message 数组中 user 和 assistant 两个 role 交替出现
-
-### 流式接收机制
-
-<!-- 源码: src/llm/anthropic.ts (AnthropicClient.stream, AsyncGenerator) -->
-<!-- 源码: src/llm/events.ts (StreamEvent 联合类型) -->
-
-用户发送请求后, ConversationManager 的 stream 方法返回 `AsyncGenerator<StreamEvent>`, 每收到一个 SSE chunk, yield 对应的 StreamEvent; CLI 循环消费 AsyncGenerator, 如果是文本增量, 则提交给 UI 渲染, 如果收集到完整的工具调用 json 参数, 则调用工具; 流式接收完成后, agent 循环调用 ConversationManager 的 appendMessages 方法将消息写入对话历史

package/docs/ch3.md

@@ -1,206 +0,0 @@
-# 工具调用
-
-## 告诉 LLM 有哪些工具
-
-调用 LLM API 时, 可以通过 tools 参数告诉 LLM 有哪些工具, 包括名称 name, 描述 description, 参数格式 tool schema
-
-<!-- 源码: src/tools/descriptions.ts, src/tools/read-file.ts -->
-
-```json
-{
-  "tools": [
-    {
-      "name": "ReadFile",
-      "description": "Read a file and return its contents with line numbers.\n\nUsage Notes\n\n- The file_path should be an absolute path when possible.\n- By default reads up to 2000 lines from the beginning of the file.\n- Use offset and limit to read specific parts of large files. Only read what you need.\n- Results are returned with line numbers (1-based) for easy reference.\n- This tool can only read files, not directories. Use glob to list directory contents.\n- Do NOT re-read a file you just edited to verify -- EditFile would have errored if the change failed.",
-      "input_schema": {
-        "type": "object",
-        "properties": {
-          "file_path": {
-            "type": "string",
-            "description": "Absolute path to the file"
-          },
-          "offset": {
-            "type": "integer",
-            "description": "Line number to start from (0-based)",
-            "default": 0
-          },
-          "limit": {
-            "type": "integer",
-            "description": "Max lines to read",
-            "default": 2000
-          }
-        },
-        "required": ["file_path"]
-      }
-    }
-  ]
-}
-```
-
-## LLM 决定调用工具
-
-LLM 决定调用工具时, LLM API 的响应中包含一个结构化的工具调用请求
-
-```json
-{
-  "role": "assistant",
-  "content": [
-    {
-      "type": "text",
-      "text": "Let me read the text content of this file."
-    },
-    {
-      "type": "tool_use",
-      "id": "toolu_123abc",
-      "name": "ReadFile",
-      "input": {
-        "file_path": "src/main.go"
-      }
-    }
-  ]
-}
-```
-
-- 一个 LLM API 的响应中, 可以既包含文本内容块, 又包含工具调用请求内容块, 甚至同时请求调用多个工具
-- 每个 tool_use 工具调用请求, 都有一个唯一 ID
-
-## CLI 执行工具调用, 返回工具调用结果给 LLM API
-
-- CLI 收到 tool_use 工具调用请求后, CLI 执行工具调用相关代码, 将工具调用结果返回给 LLM API
-
-```jsonc
-{
-  // 执行工具调用, role 是 user
-  "role": "user",
-  "content": [
-    {
-      "type": "tool_result",
-      // 必须和 tool_use 工具调用请求的 ID 相同
-      "tool_use_id": "toolu_123abc",
-      "content": "1\tfunction main() {\n2\t  console.log(\"javascript newbie\")\n3\t}",
-    },
-  ],
-}
-```
-
-## LLM 继续
-
-LLM 收到工具调用结果, 继续...
-
-LLM 负责决策, 请求调用工具; CLI 负责执行工具调用, 将工具调用结果返回给 LLM API
-
-- LLM 决定是否调用某个工具时, 主要参考工具描述 (description), 工具描述的质量直接决定 LLM 的工具调用行为, 包括: 什么时候调用工具、调用哪个工具、如何传递参数
-- 好的工具描述应该包括: 工具的核心功能、什么时候应该调用、什么时候不应该调用、输入参数的 schema、输出的工具调用结果的 schema、与其他工具的配合 (工作流建议, 例如对于大文件, 先 Grep 定位再 ReadFile 读文件)
-
-## 工具接口设计
-
-<!-- 源码: src/tools/types.ts -->
-
-- 身份信息: name, description, schema (input_schema)
-- 元信息
-  - category 分类
-  - deferred? 延迟加载
-  - system? 内部工具
-  - concurrencySafe? 是否可以和其他工具并发执行
-- 行为: execute、validateInput?
-
-<!-- 源码: src/tools/types.ts -->
-
-```ts
-export interface ToolResult {
-  output: string;
-  // 工具执行失败对于 LLM 是有价值的反馈, 提示 LLM 调整策略
-  isError: boolean;
-}
-```
-
-### ReadFile
-
-<!-- 源码: src/tools/read-file.ts -->
-
-- properties: file_path, offset, limit
-- 元信息: 只读、非破坏性, `category: read`
-- 行号: 读文件需要带行号前缀, 方便定位代码位置 `"1\tfunction main() {\n2\t  console.log(\"javascript newbie\")\n3\t}"`
-- 大文件: 支持 offset 和 limit 参数, offset 默认 0, limit 默认 2000, 指定从第 offset 行开始读、读 limit 行, 使得 LLM 可以分段读文件
-- 二进制文件: 通过读文件的前 512 字节, 如果包含 NUL 字符 (\x00), 则判定为二进制文件并拒绝读取, 提示 LLM 使用 bash 工具处理
-
-### WriteFile
-
-<!-- 源码: src/tools/write-file.ts -->
-
-- properties: file_path, content
-- 元信息: 非只读、非破坏性, `category: write`
-- 创建或重写, 创建时需要递归的创建父目录
-
-### EditFile
-
-<!-- 源码: src/tools/edit-file.ts -->
-
-- properties: file_path, old_string, new_string, replace_all
-- 元信息: 非只读、非破坏性, `category: write`
-- 如果 replace_all === false, 则 old_string 必须唯一匹配
-  - 如果匹配多个, 报错提示: 该 old_string 匹配 N 个, 请提供更多的上下文使得 old_string 唯一匹配
-  - 如果没有找到, 说明 LLM 记忆的文件内容可能过时
-- 替换成功后, 返回 "Successfully edited ${filePath}", 提供给 LLM 确认修改是否正确
-- new_string 为空, 表示删除 old_string
-
-### Bash
-
-<!-- 源码: src/tools/bash.ts -->
-
-- properties: command, timeout
-- 元信息: 非只读、破坏性, `category: command`
-- 工作目录: 项目根目录, 超时: 120s
-- 输出: stdout、stderr 合并到一个流; 输出过长时截断, 保留前面的部分和截断标记
-- 命令退出码的语义
-  - 默认非 0 退出码 isError: true
-  - grep 退出码 1 表示: 没有找到匹配, 退出码 >=2 视为 error
-  - diff 退出码 1 表示文件有差异, 退出码 >=2 视为 error
-
-### Glob
-
-<!-- 源码: src/tools/glob.ts -->
-
-- properties: pattern, path
-- 元信息: 只读、非破坏性, `category: read`
-- glob 查找文件名
-- 搜索结果按修改时间倒序排序, 最新修改的排在前面
-
-### Grep
-
-<!-- 源码: src/tools/grep.ts -->
-
-- properties: pattern, path, include
-- 元信息: 只读、非破坏性, `category: read`
-- grep 找文件内容
-- 输出格式: 文件路径:行号:匹配的内容
-
-<!-- 源码: src/tools/types.ts (ToolCategory = "read" | "write" | "command") -->
-
-| 工具      | 分类    | 只读 | 破坏性 | 场景            |
-| --------- | ------- | ---- | ------ | --------------- |
-| ReadFile  | read    | 是   | 否     | 读文件          |
-| WriteFile | write   | 否   | 否     | 创建或重写文件  |
-| EditFile  | write   | 否   | 否     | 修改文件        |
-| Bash      | command | 否   | 是     | 执行 shell 命令 |
-| Glob      | read    | 是   | 否     | 查找文件名      |
-| Grep      | read    | 是   | 否     | 查找文件内容    |
-
-## 流式 tool_use 解析: 拼接 partialJson JSON 碎片
-
-```txt
-# tool_use 块开始
-content_block_start -> type: "tool_use", id: "toolu_123abc", name: "ReadFile"
-
-# 传输 JSON 碎片
-content_block_delta -> type: "input_json_delta", partial_json: "{"
-content_block_delta -> type: "input_json_delta", partial_json: "\"path\""
-content_block_delta -> type: "input_json_delta", partial_json: ": \"/main.js\"}"
-
-# tool_use 块结束
-content_block_stop
-```
-
-- tool_use 工具调用请求的 role 是 assistant, tool_result 工具调用结果的 role 是 user
-- 一条 assistant 消息可能同时包含 text 内容块和 tool_use 内容块, 必须在同一条 assistant 消息中, 不能拆成两条 assistant 消息
-- 如果一条 assistant 消息包含多个 tool_use 内容块, 即 LLM 请求同时调用多个工具, 则多个 tool_result 内容块必须在同一条 user 消息中, 通过 id 配对

package/docs/ch4.md

@@ -1,125 +0,0 @@
-# ReAct 和 Agent Loop
-
-ReAct (Reasoning + Acting)
-
-- Thinking 解释为什么要做这一步 (text)
-- Act 选择调用一个工具 (tool_use)
-- Observe (tool_result) 分析工具调用结果, 决定下一步怎么做
-
-## ReAct 对比其他范式
-
-- Chain-of-Thought 只推理, 不行动
-- Act-only 只行动, 不推理
-- ReAct 推理与行动交替
-- Plan-then-execute 先生成完整计划, 再逐步执行
-
-## Agent Loop
-
-<!-- 源码: src/agent/agent.ts -->
-
-```js
-function agentLoop(userMessage) {
-  const messages = [...historyMessages, userMessage];
-  while (true) {
-    const response = streamLLM(systemPrompt, messages, toolSchemas);
-    const toolUses = response.getToolUses();
-    if (toolUses.length === 0) {
-      return response;
-    }
-    messages.push({ role: "assistant", content: response.content });
-    const results = [];
-    for (const tu of toolUses) {
-      const result = executeTool(tu);
-      results.push(result);
-    }
-    messages.push({ role: "user", content: results });
-  }
-}
-```
-
-## 退出 Agent Loop
-
-<!-- 源码: src/agent/agent.ts -->
-
-Swifty 需要 5 种 agent loop 退出条件
-
-1. LLM 决定退出循环: LLM API 响应中没有 tool_use, stop reason 是 end_turn (Anthropic)
-2. 设置最大循环次数, 超过最大循环次数后强制退出循环
-3. 用户按 esc 退出循环: Go 使用 `context.Context`, TS 使用 `AbortController`
-4. 如果 LLM 请求调用的工具不存在或不可用, 则返回错误结果反馈给 LLM 调整; 如果连续请求调用不存在或不可用的工具 (consecutiveUnknown >= 3), 说明 LLM 陷入幻觉, 退出循环
-5. LLM output token 到达 max_tokens: 先提高 output_tokens 到 200_000, 再进行最多 3 轮的多轮恢复, 每轮恢复提示 LLM 从断点继续; 恢复耗尽则降级为正常结束 (TODO: 表述待确认)
-
-## AgentEvent 事件流
-
-agent loop 期间会发射大量事件:
-
-- stream_text: LLM 流式输出的文本增量
-- thinking_text: LLM 推理的文本增量
-- thinking_complete: 完整的推理块, 包含 thinking 和 signature
-- tool_use: LLM 请求调用工具
-- tool_result: LLM 工具调用结束
-- turn_complete: 一轮 LLM 调用结束 (LLM 请求调用工具 + CLI 工具调用结束)
-- loop_complete: 整个 agent loop 结束, stop reason 可以是 end_turn 或 interrupted
-- usage: token 用量更新
-- compact: 上下文压缩完成
-- retry: 自动重试 (output token 到达 max_tokens 恢复或限流等待)
-- error: 发生错误
-
-UI 层只需要从 AgentEvent 事件流中消费事件, 根据事件更新 UI, agent 和 UI 解构; Go 使用 channel, TS 使用 AsyncGenerator (`async function* + yield`)
-
-## 状态机
-
-LLM 响应后, 只有两种可能: 继续循环 / 退出循环
-
-```js
-function classifyResponse(response) {
-  const toolUses = response.getToolUses();
-  if (toolUses.length > 0) {
-    return "continue";
-  }
-  return "terminal";
-}
-```
-
-## 执行工具
-
-按工具的 isConcurrencySafe 分 batch, 并发安全的并发执行, 并发不安全的串行执行; 并发 batch 可以包含多个并发安全的工具调用, 串行 batch 只能包含一个并发不安全的工具调用
-
-```js
-/**
- * e.g. LLM returns [Read, Read, Edit, Read, Read]
- *
- * Batches:
- *   [Read, Read]
- *   [Edit]
- *   [Read, Read]
- */
-function partitionToolCalls(toolUses, registry) {
-  const batches = [];
-  for (const tu of toolUses) {
-    const tool = registry.get(tu.name);
-    const safe = tool?.isConcurrencySafe(tu.input) ?? false;
-
-    if (safe && batches.length > 0) {
-      const lastBatch = batches[batches.length - 1];
-      lastBatch.calls.push(tu);
-    } else {
-      batches.push(
-        new Batch({
-          isConcurrencySafe: safe,
-          calls: [tu],
-        }),
-      );
-    }
-  }
-  return batches;
-}
-```
-
-## System Prompt 与环境信息
-
-每轮 agent loop turn 都需要发送 System Prompt 给 LLM API, System Prompt 包含用户信息、环境信息 (操作系统、工作目录) 和模式指令 (planMode)
-
-## Plan Mode 只规划不做事
-
-通过 prompt 约束 LLM 行为, plan mode 的权限矩阵和 default mode 相同: read=allow, write=ask, command=ask, 特殊的是 plan.md 的 write=allow, 不需要用户确认