versun/claude-code
1
0
Fork 0
mirror of https://github.com/claude-code-best/claude-code.git synced 2026-06-18 14:25:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 文档检查/check 20260419 (#296)

Browse Source 
* docs: 修复文档巡检发现的 4 处错误

- daemon.md: 反映实际实现状态（supervisor/worker 已实现而非 stub）
- bridge-mode.md: API 操作数量从 7 修正为 9
- web-search-tool.md: 文件路径从 src/tools/ 修正为 packages/builtin-tools/src/tools/
- remote-control-self-hosting.md: 补充缺失的 RCS_WS_IDLE_TIMEOUT 和 RCS_WS_KEEPALIVE_INTERVAL 配置项

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 Safety 和 Context 文档中的代码引用和类型错误

- permission-model: 修正规则来源从"五层"到八层，优先级顺序对齐代码
- permission-model: PermissionUpdate 类型改为实际的 addRules/replaceRules 等
- permission-model: 补充 acceptEdits 和 dontAsk 两种权限模式
- permission-model: DENIAL_LIMITS 字段名对齐实际代码
- plan-mode: 工具路径从 src/tools/ 改为 packages/builtin-tools/src/tools/
- compaction: 修正 COMPACTABLE_TOOLS 和 POST_COMPACT_* 的行号
- project-memory: 修正 ENTRYPOINT_NAME 常量的行号
- system-prompt: 修正 SystemPrompt 类型定义文件路径和多个行号引用

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修复 introduction 文档中的错误路径和行号引用

- why-this-whitepaper.mdx: BashTool 路径从 src/tools/ 修正为 packages/builtin-tools/src/tools/
- what-is-claude-code.mdx: 移除不存在的 Azure provider，改为实际的 7 种 provider
- architecture-overview.mdx: State 类型行号从 204 修正为 207

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修复 conversation/features 文档中的错误

- streaming.mdx: queryStreamRaw → queryModelWithStreaming 函数名修正
- streaming.mdx: Azure 提供商不存在，替换为实际 7 个提供商
- debug-mode.mdx: --inspect-wait 描述错误，实际使用 BUN_INSPECT 环境变量
- buddy.mdx: 补充缺失的 companionReact.ts、CompanionCard.tsx、index.ts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修复文档巡检中的源码引用错误

- feature-flags.mdx: 修正 feature() 兜底描述，实际从 bun:bundle 导入而非 cli.tsx:3 内联
- feature-flags.mdx: 修正工具 require 路径为 @claude-code-best/builtin-tools 包路径
- ant-only-world.mdx: 修正 tools.ts 中 require 路径为包路径
- ant-only-world.mdx: 修正 INTERNAL_ONLY_COMMANDS 行号 (267-295) 和数量 (24+)
- skills.mdx: 修正 COMMANDS memoize 行号 258 → 299
- mcp-protocol.mdx: 修正 fetchToolsForClient LRU 缓存上限 20 → 100
- streaming.mdx: 修正流式事件引用
- file-operations.mdx: 修正工具路径引用
- search-and-navigation.mdx: 修正搜索工具引用
- shell-execution.mdx: 修正 shell 工具引用
- buddy.mdx: 补充缺失的 frontmatter 字段
- debug-mode.mdx: 修正调试模式描述

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 tools/agent 文档中的文件路径和行号引用

- 修正 TodoWriteTool、AgentTool、ToolSearchTool 等工具路径
  src/tools/ → packages/builtin-tools/src/tools/
- 更新 Tool.ts、tools.ts、BashTool.tsx 中过时的行号引用
- 修正 WebSearchTool/WebFetchTool/EnterWorktreeTool/ExitWorktreeTool 路径
- 修正 AgentTool.tsx 中多行行号引用

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 feature 文档中的文件路径和行号引用

- ultraplan.md: 更新文件行数（525/349/127）
- fork-subagent.md: 路径迁移 src/tools/ → packages/builtin-tools/
- mcp-skills.md: 修正 getMcpSkillCommands 行号 547→604，client.ts 行号 117→129
- kairos.md: 修正 getBriefSection/getProactiveSection 行号
- proactive.md: 修正 getProactiveSection 行号 860→864

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正顶层文档中的路径迁移和行号引用

- auto-updater.md: config.ts 行号 1735→1737，标注未接入启动流程的函数
- external-dependencies.md: WebSearchTool/WebFetchTool 路径迁移到 builtin-tools 包，Vertex 行号修正
- lsp-integration.md: LSPTool 路径从 src/tools/ 迁移到 packages/builtin-tools/
- stub-recovery-design-1-4.md: 修正 Windows 绝对路径链接为标准代码引用

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 task 文档中的文件扩展名和路径引用

- task-004: AssistantSessionChooser.ts → .tsx, assistant.ts → .tsx
- task-003: cli.tsx 行号 249→272, markdownConfigLoader.ts 行号 29→35
- lan-pipes: SendMessageTool 路径迁移到 packages/builtin-tools/

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 补充 computer-use-tools-reference 缺失的 Windows 工具

添加遗漏的 open_terminal 和 activate_window 两个 Windows 专属工具，
修正工具总数 37→39，Windows 工具数 10→12。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 audit/bash-classifier/token-budget/tree-sitter 文档

- feature-flags-audit: ScheduleCronTool 路径迁移、DAEMON 状态更新为 COMPLETE、assistant 文件标记已补全、UDS 标记已实现
- bash-classifier: BashPermissionRequest 文件路径修正、withRetry 行号移除
- token-budget: attachments.ts 行号范围修正
- tree-sitter-bash: bashPermissions.ts 路径迁移到 packages/builtin-tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 langfuse-monitoring AgentTool 路径迁移

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 bridgeApi 行号和 Tool.ts 行号引用

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 Safety/Extensibility 文档中的工具路径迁移和行号引用

- sandbox.mdx: shouldUseSandbox.ts 和 bashPermissions.ts 路径迁移至 packages/builtin-tools
- why-safety-matters.mdx: bashPermissions.ts 路径迁移（3 处）
- plan-mode.mdx: EnterPlanModeTool/prompt.ts 路径迁移
- auto-mode.mdx: Auto mode 指令行号 3464→3481
- hooks.mdx: AgentTool/runAgent.ts 路径迁移
- skills.mdx: SkillTool.ts 路径迁移
- custom-agents.mdx: Agent built-in 目录和 exploreAgent.ts 路径迁移

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 internals 文档引用计数和路径

- ant-only-world: USER_TYPE 引用计数 465→410+，工具路径迁移到 builtin-tools
- growthbook-ab-testing: growthbook.ts 行数 1156→1258
- hidden-features: 语音模式状态更新（audio-napi 已恢复）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正工具文档中的行号引用

- sub-agents: AgentTool.call 入口行号 340→387
- shell-execution: ShellCommand onTimeout 行号 129→144

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 feature 文档中的状态、路径和计数

- all-features-guide: 修正 feature flag 启用范围（dev only vs dev+build）
- tier3-stubs: 大量状态修正（stub→已实现），缩减过时条目
- workflow-scripts: 路径迁移到 builtin-tools，状态更新
- web-browser-tool: 工具状态缺失→已实现，路径迁移
- context-collapse: CtxInspectTool 状态缺失→已实现
- computer-use: 行号引用更新，平台分发描述修正
- computer-use-tools-reference: 工具数 39→38
- voice-mode: voiceModeEnabled 行数 55→54

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 更新 the-loop 查询循环行号引用

query.ts 代码变更后终止原因行号整体偏移约 40 行

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 补充 feature-flags-audit 完整 build 默认 feature 列表

添加 ULTRATHINK/LODESTONE/ACP/DAEMON 等 19 个缺失的 build 默认 feature，
修正 dev-only 特征标注（UDS_INBOX/LAN_PIPES/BG_SESSIONS/TEMPLATES）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 feature-flags-audit ConfigTool 路径迁移

ConfigTool 路径从 src/tools/ 迁移到 packages/builtin-tools/src/tools/

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 feature-flags-audit BashTool 路径迁移

BashTool 路径从 src/tools/ 迁移到 packages/builtin-tools/src/tools/

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 修正 feature-flags-audit SkillTool 路径迁移

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: 更新 feature-flags-audit WorkflowTool 状态为已实现

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
claude-code-best
2026-04-19 09:30:00 +08:00
committed by GitHub
parent a57ca08566
commit c5edee431f
61 changed files with 485 additions and 451 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/tools/file-operations.mdx
View File

@@ -22,14 +22,14 @@ Read 的 `maxResultSizeChars` 是 `Infinity`，但这并不意味着无限制输
## FileRead：多模态文件读取引擎
源码路径：`src/tools/FileReadTool/FileReadTool.ts`
源码路径：`packages/builtin-tools/src/tools/FileReadTool/FileReadTool.ts`
### 读取去重机制
Read 工具有一个常被忽视但至关重要的**去重层**。当 AI 重复读取同一个文件的同一范围时，系统不会浪费 token 发送两份完整内容：
```typescript
// FileReadTool.ts:530-573 — 去重逻辑
// FileReadTool.ts — 去重逻辑
const existingState = readFileState.get(fullFilePath)
if (existingState && !existingState.isPartialView && existingState.offset !== undefined) {
const rangeMatch = existingState.offset === offset && existingState.limit === limit
@@ -83,7 +83,7 @@ Read 工具在 `validateInput()` 中设置了多层安全门：
当文件不存在时，Read 不会只报一个 "file not found"：
```typescript
// FileReadTool.ts:639-647
// FileReadTool.ts
const similarFilename = findSimilarFile(fullFilePath) // 相似扩展名
const cwdSuggestion = await suggestPathUnderCwd(fullFilePath) // cwd 相对路径建议
// macOS 截图特殊处理：薄空格(U+202F) vs 普通空格
@@ -94,7 +94,7 @@ const altPath = getAlternateScreenshotPath(fullFilePath)
## FileEdit：精确字符串替换引擎
源码路径：`src/tools/FileEditTool/FileEditTool.ts` + `utils.ts`
源码路径：`packages/builtin-tools/src/tools/FileEditTool/FileEditTool.ts` + `utils.ts`
### 引号标准化：AI 无法输出的字符怎么办
@@ -138,7 +138,7 @@ Edit 工具在 `validateInput()` 中检查两个条件：
2. **文件未被外部修改**（`mtime` 未变，或全量读取时内容完全一致）
```typescript
// FileEditTool.ts:290-311 — Windows 特殊处理
// FileEditTool.ts — Windows 特殊处理
const isFullRead = readTimestamp.offset === undefined && readTimestamp.limit === undefined
if (isFullRead && fileContent === readTimestamp.content) {
// 内容不变，安全继续（Windows 云同步/杀毒可能改 mtime）
@@ -157,7 +157,7 @@ const MAX_EDIT_FILE_SIZE = 1024 * 1024 * 1024 // 1 GiB
## FileWrite：全量写入与创建
源码路径：`src/tools/FileWriteTool/FileWriteTool.ts`
源码路径：`packages/builtin-tools/src/tools/FileWriteTool/FileWriteTool.ts`
Write 工具与 Edit 共享大部分基础设施（权限检查、mtime 校验、fileHistory 备份），但有两个关键差异：

14
docs/tools/search-and-navigation.mdx
View File

@@ -77,7 +77,7 @@ Glob 默认把**最近修改的文件排在前面**。这不是默认的文件
实际效果：AI 优先看到"活"的代码，而不是沉寂的历史文件
```
在 `src/tools/GlobTool/` 中，ripgrep 的输出在返回给 AI 前按 mtime 排序。
在 `packages/builtin-tools/src/tools/GlobTool/` 中，ripgrep 的输出在返回给 AI 前按 mtime 排序。
### ripgrep 的错误处理
@@ -92,7 +92,7 @@ ripgrep 执行有专门的错误恢复链（`src/utils/ripgrep.ts`）：
## ToolSearch：在 50+ 工具中发现目标
当可用工具超过 50 个时（含 MCP 提供的外部工具），AI 可能不知道该用哪个。**ToolSearch**（`src/tools/ToolSearchTool/`）提供了工具发现机制。
当可用工具超过 50 个时（含 MCP 提供的外部工具），AI 可能不知道该用哪个。**ToolSearch**（`packages/builtin-tools/src/tools/ToolSearchTool/`）提供了工具发现机制。
### 搜索算法
@@ -139,14 +139,14 @@ function getDeferredToolsCacheKey(deferredTools: Tools): string {
AI 的信息获取不局限于本地代码：
- **WebSearch**（`src/tools/WebSearchTool/`）：调用 Anthropic API 的 `web_search_20250305` server tool 搜索互联网
- **WebFetch**（`src/tools/WebFetchTool/`）：抓取特定 URL 内容，转换为 Markdown 供 AI 阅读
- **WebSearch**（`packages/builtin-tools/src/tools/WebSearchTool/`）：调用 Anthropic API 的 `web_search_20250305` server tool 搜索互联网
- **WebFetch**（`packages/builtin-tools/src/tools/WebFetchTool/`）：抓取特定 URL 内容，转换为 Markdown 供 AI 阅读
这让 AI 可以查阅文档、搜索 Stack Overflow、阅读 GitHub issue——和人类开发者的工作方式一致。
### WebSearch 实现机制
WebSearch 通过适配器模式支持三种搜索后端，由 `src/tools/WebSearchTool/adapters/` 中的工厂函数 `createAdapter()` 选择：
WebSearch 通过适配器模式支持三种搜索后端，由 `packages/builtin-tools/src/tools/WebSearchTool/adapters/` 中的工厂函数 `createAdapter()` 选择：
```
适配器架构:
@@ -229,7 +229,7 @@ WebSearch 通过适配器模式支持三种搜索后端，由 `src/tools/WebSear
### WebSearchTool 统一接口
`WebSearchTool`（`src/tools/WebSearchTool/WebSearchTool.ts`）是面向主循环的工具定义，所有 provider 均可使用（`isEnabled()` 始终返回 true）。它将适配器返回的 `SearchResult[]` 转换为内部 `Output` 格式，`mapToolResultToToolResultBlockParam` 将搜索结果格式化为带 markdown 超链接的文本，并附加 "REMINDER" 要求主模型在回复中包含 Sources。
`WebSearchTool`（`packages/builtin-tools/src/tools/WebSearchTool/WebSearchTool.ts`）是面向主循环的工具定义，所有 provider 均可使用（`isEnabled()` 始终返回 true）。它将适配器返回的 `SearchResult[]` 转换为内部 `Output` 格式，`mapToolResultToToolResultBlockParam` 将搜索结果格式化为带 markdown 超链接的文本，并附加 "REMINDER" 要求主模型在回复中包含 Sources。
### WebFetch 实现机制
@@ -264,7 +264,7 @@ WebFetch 是一个完整的 HTTP 客户端 + 内容处理管线：
| **URL 验证** | `validateURL()` | 长度、协议、用户名密码、公网域名检查 |
| **egress 检测** | `X-Proxy-Error: blocked-by-allowlist` | 检测企业代理拦截 |
预批准域名（`src/tools/WebFetchTool/preapproved.ts`）：
预批准域名（`packages/builtin-tools/src/tools/WebFetchTool/preapproved.ts`）：
用户无需手动授权即可抓取的域名列表，包含 ~90 个主流技术文档站点（MDN、Python docs、React docs、AWS docs 等）。列表分为 hostname-only 和 path-prefix 两类，查找复杂度 O(1)。

14
docs/tools/shell-execution.mdx
View File

@@ -31,7 +31,7 @@ spawn(wrapped_command) ← 实际进程创建
## 只读命令的判定：为什么 Read 免审批而 Bash 不一定
BashTool 的 `isReadOnly()` 方法（`BashTool.tsx:437`）决定一条命令是否被视为"只读"：
BashTool 的 `isReadOnly()` 方法（`packages/builtin-tools/src/tools/BashTool/BashTool.tsx:655`）决定一条命令是否被视为"只读"：
```typescript
isReadOnly(input) {
@@ -41,7 +41,7 @@ isReadOnly(input) {
}
```
判定逻辑基于 4 个命令集合（`BashTool.tsx:60-78`）：
判定逻辑基于 4 个命令集合（`BashTool.tsx:120-166`）：
| 集合 | 命令 | 性质 |
|------|------|------|
@@ -53,7 +53,7 @@ isReadOnly(input) {
对于复合命令（`ls dir && echo "---" && ls dir2`），系统拆分后逐段检查——**所有非中性段都必须属于上述集合**，整条命令才被视为只读。
```typescript
// BashTool.tsx:95 — 简化的判定逻辑
// BashTool.tsx — 简化的判定逻辑
for (const part of partsWithOperators) {
if (BASH_SEMANTIC_NEUTRAL_COMMANDS.has(baseCommand)) continue // 跳过中性段
if (!isPartSearch && !isPartRead && !isPartList) {
@@ -64,7 +64,7 @@ for (const part of partsWithOperators) {
## AST 安全解析：tree-sitter bash 解析
`preparePermissionMatcher()`（`BashTool.tsx:445`）在权限检查前用 `parseForSecurity()` 解析命令结构：
`preparePermissionMatcher()`（`BashTool.tsx:663`）在权限检查前用 `parseForSecurity()` 解析命令结构：
```typescript
async preparePermissionMatcher({ command }) {
@@ -92,14 +92,14 @@ getDefaultTimeoutMs()
└── 最大上限：600,000ms（10 分钟，用户显式设置时）
```
超时后系统不会直接杀进程——`ShellCommand`（`src/utils/ShellCommand.ts:129`）通过 `onTimeout` 回调通知调用方，由调用方决定是终止还是后台化。
超时后系统不会直接杀进程——`ShellCommand`（`src/utils/ShellCommand.ts:144`）通过 `onTimeout` 回调通知调用方，由调用方决定是终止还是后台化。
## 自动后台化
长时间运行的命令可以自动转为后台任务，不阻塞 AI 的 agentic loop：
```typescript
// BashTool.tsx:880
// BashTool.tsx:1158
const shouldAutoBackground = !isBackgroundTasksDisabled
&& isAutobackgroundingAllowed(command)
```
@@ -148,7 +148,7 @@ Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read
| **并发安全** | `isConcurrencySafe()` 返回 `true` → 可并行执行 | Bash 命令可能有副作用，串行执行 |
| **安全审计** | 工具名精确匹配权限规则 | 需 AST 解析命令结构后匹配 |
`isConcurrencySafe()`（`BashTool.tsx:434`）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。
`isConcurrencySafe()`（`BashTool.tsx:652`）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。
## 进度反馈的流式设计

2
docs/tools/task-management.mdx
View File

@@ -25,7 +25,7 @@ Claude Code 的任务管理并非单一系统，而是两个并存、按运行
TodoWrite 本质是一个**全量替换**操作——每次调用传入完整的 `todos[]` 数组，完全覆盖之前的状态：
```typescript
// src/tools/TodoWriteTool/TodoWriteTool.ts — call() 核心逻辑
// packages/builtin-tools/src/tools/TodoWriteTool/TodoWriteTool.ts — call() 核心逻辑
async call({ todos }, context) {
const todoKey = context.agentId ?? getSessionId()
const oldTodos = appState.todos[todoKey] ?? []

8
docs/tools/what-are-tools.mdx
View File

@@ -16,7 +16,7 @@ keywords: ["工具系统", "Tool 抽象", "AI 工具", "function calling", "buil
## Tool 类型：35 个字段的统一接口
所有工具都实现 `src/Tool.ts:362` 的 `Tool<Input, Output, Progress>` 类型。这不是一个 class，而是一个包含 35+ 字段的**结构化类型**（structural typing），任何满足该接口的对象就是一个工具：
所有工具都实现 `src/Tool.ts:368` 的 `Tool<Input, Output, Progress>` 类型。这不是一个 class，而是一个包含 35+ 字段的**结构化类型**（structural typing），任何满足该接口的对象就是一个工具：
### 核心四要素
@@ -69,7 +69,7 @@ keywords: ["工具系统", "Tool 抽象", "AI 工具", "function calling", "buil
## 工具注册：`getTools()` 的分层组装
`src/tools.ts` 的 `getAllBaseTools()`（第 191 行）是工具注册的核心：
`src/tools.ts` 的 `getAllBaseTools()`（第 195 行）是工具注册的核心：
```
固定工具（始终可用）:
@@ -96,7 +96,7 @@ Ant-only 工具:
← process.env.USER_TYPE === 'ant' ? [REPLTool, ConfigTool, TungstenTool]
```
`getTools()`（第 269 行）在 `getAllBaseTools()` 基础上应用权限过滤：
`getTools()`（第 274 行）在 `getAllBaseTools()` 基础上应用权限过滤：
```typescript
export const getTools = (permissionContext): Tools => {
@@ -110,7 +110,7 @@ export const getTools = (permissionContext): Tools => {
## `buildTool()` 工厂函数
大多数工具通过 `buildTool()` 创建（`src/Tool.ts:721`），它是一个类型安全的构造器：
大多数工具通过 `buildTool()` 创建（`src/Tool.ts:789`），它是一个类型安全的构造器：
```typescript
export const BashTool: Tool<...> = buildTool({