mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
docs: 完成大纲的编写
This commit is contained in:
claude-code-best
161
docs/SITE-RESTRUCTURE-PROPOSAL.md
Normal file
161
docs/SITE-RESTRUCTURE-PROPOSAL.md
Normal file
@@ -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 | （不变） |
|
||||
@@ -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 |
|
||||
Reference in New Issue
Block a user