From cf69382943565d198d6aadf05cf21dbff21c30dc Mon Sep 17 00:00:00 2001 From: claude-code-best Date: Sun, 19 Apr 2026 22:37:49 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E6=88=90=E5=A4=A7=E7=BA=B2?= =?UTF-8?q?=E7=9A=84=E7=BC=96=E5=86=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/SITE-RESTRUCTURE-PROPOSAL.md | 161 ++++++++++++++++++++++++++++++ docs/features/context-collapse.md | 140 -------------------------- 2 files changed, 161 insertions(+), 140 deletions(-) create mode 100644 docs/SITE-RESTRUCTURE-PROPOSAL.md delete mode 100644 docs/features/context-collapse.md diff --git a/docs/SITE-RESTRUCTURE-PROPOSAL.md b/docs/SITE-RESTRUCTURE-PROPOSAL.md new file mode 100644 index 000000000..86b2a911c --- /dev/null +++ b/docs/SITE-RESTRUCTURE-PROPOSAL.md @@ -0,0 +1,161 @@ +# Claude Code 文档站章节重构方案 + +> 按功能域重新组织，专有名词保留英文，其余简化为中文。 + +--- + +## 一、导航结构 + +``` +开始使用 +├── 项目介绍 +├── 项目动机 +└── 架构总览 + +核心机制 +├── Agent Loop +├── 流式响应 +├── 多轮对话 +├── 系统提示词 +└── 深度规划 + +上下文管理 +├── 令牌预算 +├── 上下文压缩 +├── 项目记忆 +├── 自动记忆整理 +└── 穷鬼模式 + +工具系统 +├── 工具总览 +├── 文件操作 +├── 命令执行 +├── 搜索导航 +├── 任务管理 +├── 网页搜索 +├── 桌面自动化 +└── 浏览器控制 + +多智能体 +├── 子智能体 +├── 自定义智能体 +├── 工作树隔离 +├── 协调模式 +├── 团队记忆 +└── 后台会话 + +MCP +└── MCP 详解 + +Hook 与 Plugin +├── Hook 钩子 +├── 插件市场 +└── LSP 集成 + +Skills +├── Skill 技能系统 +├── Workflow 脚本 +└── Skill 搜索 + +远程控制 +├── 远程控制 +├── ACP 接入 +├── 消息通道 +├── 本地通信 +└── 常驻助手 + +安全机制 +├── 安全概述 +├── 权限模型 +├── 沙箱 +├── Bash 检查 +├── 规划模式 +└── 自动模式 + +额外功能 +├── 特性开关 +├── A/B 测试与配置 +├── 错误追踪 +├── 隐藏功能 +├── Buddy 助手 +├── 命令分类 +└── 语音模式 + +开发人员 +├── 可观测性 +├── 调试模式 +└── 专属特性 + +基础设施 +├── 守护进程 +└── 自动更新 + +附录 +├── 任务追踪 +├── 测试计划 +└── 设计文档 +``` + +--- + +## 二、标题映射 + +| 导航标题 | 新文件路径 | 合并来源 | +|---------|-----------|---------| +| 项目介绍 | docs/introduction/what-is-claude-code | （不变） | +| 项目动机 | docs/introduction/why-this-whitepaper | （不变） | +| 架构总览 | docs/introduction/architecture-overview | （不变） | +| Agent Loop | docs/conversation/the-loop | （不变） | +| 流式响应 | docs/conversation/streaming | （不变） | +| 多轮对话 | docs/conversation/multi-turn | （不变） | +| 系统提示词 | docs/context/system-prompt | （不变） | +| 语音模式 | docs/features/voice-mode | （不变） | +| 深度规划 | docs/features/ultraplan | （不变） | +| 令牌预算 | docs/context/token-budget | （不变） | +| 上下文压缩 | docs/context/compaction | （不变） | +| 项目记忆 | docs/context/project-memory | （不变） | +| 自动记忆整理 | docs/features/auto-dream | （不变） | +| 穷鬼模式 | （新写） | — | +| 工具总览 | docs/tools/what-are-tools | （不变） | +| 文件操作 | docs/tools/file-operations | （不变） | +| 命令执行 | docs/tools/shell-execution | （不变） | +| 搜索导航 | docs/tools/search-and-navigation | （不变） | +| 任务管理 | docs/tools/task-management | （不变） | +| 网页搜索 | docs/features/web-search-tool | （不变） | +| 桌面自动化 | docs/features/computer-use | （不变） | +| 浏览器控制 | docs/features/claude-in-chrome-mcp | （不变） | +| 子智能体 | docs/agent/sub-agents | ← sub-agents + features/fork-subagent | +| 自定义智能体 | docs/extensibility/custom-agents | （不变） | +| 工作树隔离 | docs/agent/worktree-isolation | （不变） | +| 协调模式 | docs/agent/coordinator-and-swarm | （不变） | +| 团队记忆 | docs/features/teammem | （不变） | +| 后台会话 | docs/features/pipes-and-lan | （不变） | +| MCP 详解 | docs/extensibility/mcp | ← extensibility/mcp-protocol + extensibility/mcp-configuration + features/mcp-skills | +| 插件市场 | （新写） | — | +| Hook 钩子 | docs/extensibility/hooks | （不变） | +| Skill 技能系统 | docs/extensibility/skills | （不变） | +| Workflow 脚本 | docs/features/workflow-scripts | （不变） | +| Skill 搜索 | docs/features/experimental-skill-search | （不变） | +| 远程控制 | docs/features/remote-control | ← features/bridge-mode + features/remote-control-self-hosting | +| ACP 接入 | docs/features/acp-link | （不变） | +| 消息通道 | docs/features/channels | （不变） | +| 本地通信 | docs/features/proactive | （不变） | +| 常驻助手 | docs/features/kairos | ← features/proactive + features/kairos | +| 安全概述 | docs/safety/why-safety-matters | （不变） | +| 权限模型 | docs/safety/permission-model | （不变） | +| 沙箱 | docs/safety/sandbox | （不变） | +| Bash 检查 | docs/features/tree-sitter-bash | ← features/tree-sitter-bash + features/bash-classifier | +| 规划模式 | docs/safety/plan-mode | （不变） | +| 自动模式 | docs/safety/auto-mode | （不变） | +| 特性开关 | docs/internals/feature-flags | （不变） | +| A/B 测试与配置 | docs/internals/growthbook | ← internals/growthbook-ab-testing + internals/growthbook-adapter | +| 错误追踪 | docs/internals/sentry-setup | （不变） | +| 隐藏功能 | docs/internals/hidden-features | （不变） | +| 专属特性 | docs/internals/ant-only-world | （不变，移至开发人员） | +| 调试模式 | docs/features/debug-mode | （不变，移至开发人员） | +| Buddy 助手 | docs/features/buddy | （不变） | +| 命令分类 | docs/features/bash-classifier | （不变） | +| 可观测性 | docs/features/langfuse-monitoring | （不变） | +| 守护进程 | docs/features/daemon | （不变） | +| 自动更新 | docs/auto-updater | （不变） | +| LSP 集成 | docs/lsp-integration | （不变） | diff --git a/docs/features/context-collapse.md b/docs/features/context-collapse.md deleted file mode 100644 index afe9f153e..000000000 --- a/docs/features/context-collapse.md +++ /dev/null @@ -1,140 +0,0 @@ -# CONTEXT_COLLAPSE — 上下文折叠 - -> Feature Flag: `FEATURE_CONTEXT_COLLAPSE=1` -> 子 Feature: `FEATURE_HISTORY_SNIP=1` -> 实现状态：核心逻辑全部 Stub，布线完整 -> 引用数：CONTEXT_COLLAPSE 20 + HISTORY_SNIP 16 = 36 - -## 一、功能概述 - -CONTEXT_COLLAPSE 让模型内省上下文窗口使用情况，并智能压缩旧消息。当对话接近上下文限制时，自动将旧消息折叠为压缩摘要，保留关键信息的同时释放 token 空间。 - -### 子 Feature - -| Feature | 功能 | -|---------|------| -| `CONTEXT_COLLAPSE` | 上下文折叠引擎（后台 LLM 调用压缩旧消息） | -| `HISTORY_SNIP` | SnipTool — 标记消息进行折叠/修剪 | - -## 二、实现架构 - -### 2.1 模块状态 - -| 模块 | 文件 | 状态 | -|------|------|------| -| 折叠核心 | `src/services/contextCollapse/index.ts` | **Stub** — 接口完整（`ContextCollapseStats`、`CollapseResult`、`DrainResult`），函数全部空操作 | -| 折叠操作 | `src/services/contextCollapse/operations.ts` | **Stub** — `projectView` 为恒等函数 | -| 折叠持久化 | `src/services/contextCollapse/persist.ts` | **Stub** — `restoreFromEntries` 为空操作 | -| CtxInspectTool | `packages/builtin-tools/src/tools/CtxInspectTool/CtxInspectTool.ts` | **实现** — 上下文内省工具 | -| SnipTool 提示 | `src/tools/SnipTool/prompt.ts` | **Stub** — 空工具名 | -| SnipTool 实现 | `src/tools/SnipTool/SnipTool.ts` | **缺失** | -| force-snip 命令 | `src/commands/force-snip.js` | **缺失** | -| 折叠读取搜索 | `src/utils/collapseReadSearch.ts` | **完整** — Snip 作为静默吸收操作 | -| QueryEngine 集成 | `src/QueryEngine.ts` | **布线** — 导入并使用 snip 投影 | -| Token 警告 UI | `src/components/TokenWarning.tsx` | **布线** — 折叠进度标签 | - -### 2.2 核心接口（已定义，待实现） - -```ts -// contextCollapse/index.ts -interface ContextCollapseStats { - // 上下文使用统计 -} -interface CollapseResult { - // 折叠操作结果 -} -interface DrainResult { - // 紧急释放结果 -} - -// 关键函数（全部 stub）： -isContextCollapseEnabled() // → false -applyCollapsesIfNeeded(messages) // 透传 -recoverFromOverflow(messages) // 透传（413 恢复） -initContextCollapse() // 空操作 -``` - -### 2.3 预期数据流 - -``` -对话持续增长 - │ - ▼ -上下文接近限制（由 query.ts 检测） - │ - ├── 溢出检测 (query.ts:440,616,802) - │ - ▼ -applyCollapsesIfNeeded(messages) [需要实现] - │ - ├── 后台 LLM 调用压缩旧消息 - ├── 保留关键信息（决策、文件路径、错误） - └── 替换旧消息为压缩摘要 - │ - ├── 413 恢复 (query.ts:1093,1179) - │ └── recoverFromOverflow() 紧急折叠 - │ - ▼ -projectView() 过滤折叠后的消息视图 - │ - ▼ -模型继续工作（在压缩后的上下文中） -``` - -### 2.4 HISTORY_SNIP 子功能 - -SnipTool 提供手动折叠能力： - -- `/force-snip` 命令 — 强制执行折叠 -- SnipTool — 标记特定消息进行折叠/修剪 -- `collapseReadSearch.ts` 已完整实现，将 Snip 作为静默吸收操作处理 - -### 2.5 集成点 - -| 文件 | 位置 | 说明 | -|------|------|------| -| `src/query.ts` | 18,440,616,802,1093,1179 | 溢出检测、413 恢复、折叠应用 | -| `src/QueryEngine.ts` | 124,127,1301 | Snip 投影使用 | -| `src/utils/analyzeContext.ts` | 1122 | 跳过保留缓冲区显示 | -| `src/utils/sessionRestore.ts` | 127,494 | 恢复折叠状态 | -| `src/services/compact/autoCompact.ts` | 179,215 | 自动压缩时考虑折叠 | - -## 三、需要补全的内容 - -| 优先级 | 模块 | 工作量 | 说明 | -|--------|------|--------|------| -| 1 | `services/contextCollapse/index.ts` | 大 | 折叠状态机、LLM 调用、消息压缩 | -| 2 | `services/contextCollapse/operations.ts` | 中 | `projectView()` 消息过滤 | -| 3 | `services/contextCollapse/persist.ts` | 小 | `restoreFromEntries()` 磁盘持久化 | -| 4 | `tools/CtxInspectTool/` | 已完成 | 上下文内省工具已实现（`packages/builtin-tools/src/tools/CtxInspectTool/`） | -| 5 | `tools/SnipTool/SnipTool.ts` | 中 | Snip 工具实现 | -| 6 | `commands/force-snip.js` | 小 | `/force-snip` 命令 | - -## 四、关键设计决策 - -1. **后台 LLM 压缩**：折叠不是简单截断，而是用 LLM 生成压缩摘要保留关键信息 -2. **413 恢复**：当 API 返回 413（请求过大）时，紧急折叠是最重要的恢复手段 -3. **与 autoCompact 协作**：折叠和自动压缩（compact）是不同的机制，折叠在消息级别，压缩在对话级别 -4. **持久化**：折叠状态持久化到磁盘，会话恢复时重载 - -## 五、使用方式 - -```bash -# 启用 context collapse -FEATURE_CONTEXT_COLLAPSE=1 bun run dev - -# 启用 snip 子功能 -FEATURE_CONTEXT_COLLAPSE=1 FEATURE_HISTORY_SNIP=1 bun run dev -``` - -## 六、文件索引 - -| 文件 | 职责 | -|------|------| -| `src/services/contextCollapse/index.ts` | 折叠核心（stub，接口已定义） | -| `src/services/contextCollapse/operations.ts` | 投影操作（stub） | -| `src/services/contextCollapse/persist.ts` | 持久化（stub） | -| `src/utils/collapseReadSearch.ts` | Snip 吸收操作（完整） | -| `src/query.ts` | 溢出检测和 413 恢复集成 | -| `src/QueryEngine.ts` | Snip 投影使用 | -| `src/components/TokenWarning.tsx` | 折叠进度 UI |