附录 II：后台智能与持续学习

真正优秀的工具会悄悄变得更懂你——不是因为它在监视你，而是因为它在陪你工作。

附录 II-A：Magic Docs（活文档自动维护）

功能描述

标记了特殊头部的 Markdown 文件会被 Claude Code 自动维护更新。每次主循环结束后（Agent 产生最终回复时），系统在后台悄悄用 forked subagent 将最新的对话洞察写回文档——无需任何人工干预。

触发机制

用户读取文件（FileReadTool）
    │
    ├─ detectMagicDocHeader() 检测文件首行是否为：
    │   # MAGIC DOC: <title>
    │
    ├─ 是 Magic Doc → 注册到 trackedMagicDocs（Map<path, MagicDocInfo>）
    │
    └─ 每次主循环产生最终响应后（无工具调用）
           ↓
       registerPostSamplingHook 触发
           ↓
       对每个 trackedMagicDocs 中的文件，派生 subagent 执行更新

Magic Doc 头部格式（文件首行）：

# MAGIC DOC: Architecture Overview
_This document tracks the evolving architecture decisions._

## 概念层
...（文档正文）

第一行：# MAGIC DOC: <title>
第二行（可选）：斜体文字作为更新指令（告诉 subagent 如何更新）

核心文件

文件	作用
`src/services/MagicDocs/magicDocs.ts`	主逻辑：检测 + 注册 + 触发更新
`src/services/MagicDocs/prompts.ts`	`buildMagicDocsUpdatePrompt()`：构建发给 subagent 的更新提示词

关键设计

只读检测，不主动写入：registerFileReadListener 监听 FileReadTool，只记录"这个文件是 Magic Doc"，实际更新由 registerPostSamplingHook 在对话轮次结束后异步触发。

串行更新防冲突：多个 Magic Doc 文件用 sequential() 依次更新，避免并发写入冲突。

subagent 权限：更新 subagent 只有 FILE_EDIT_TOOL_NAME + FileReadTool 权限——能读写文档，但无法执行 bash 或修改其他文件。

典型用途：ARCHITECTURE.md、API.md、DECISIONS.md 等随开发节奏同步更新的活文档。

附录 II-B：Away Summary（离开摘要）

功能描述

用户离开后再回来（如重新聚焦终端窗口），Claude Code 展示一张"您离开时的进展"卡片：1-3 句话概括当前任务状态和下一步行动。

实现细节

核心文件：src/services/awaySummary.ts

// 只看最近 30 条消息，避免超长 session 出现 "prompt too long" 错误
const RECENT_MESSAGE_WINDOW = 30

// 使用小型快速模型生成，避免阻塞用户输入
const model = getSmallFastModel()   // Haiku 级别

// Prompt 约束（硬编码在 buildAwaySummaryPrompt()）：
// - 写 1-3 句话
// - 先说"在做什么"（高层任务），再说"下一步"
// - 禁止状态报告和 commit 摘要

输入来源：

最近 RECENT_MESSAGE_WINDOW = 30 条对话消息
Session Memory 内容（getSessionMemoryContent()），提供更宏观的任务背景

触发条件：用户离开超过阈值时间后首次输入时触发（具体阈值由调用方控制，awaySummary.ts 本身只负责生成内容）。

摘要格式（Prompt 约束）：

正确示例：
  "You're building a REST API for user authentication.
   Next: implement the JWT refresh token endpoint."

错误示例（被 Prompt 明确禁止）：
  "Status: Completed task 3. Committed: a1b2c3d."  ← 禁止状态报告
  "You ran npm install and edited package.json."  ← 禁止实现细节

附录 II-C：Prompt Suggestion + Speculation（预测执行）

功能描述

两层"预测"机制，在用户思考下一步时提前计算，目标是减少等待时间（TTFT）：

Prompt Suggestion：主 Agent 回复后，立即预测"用户下一条消息"，作为输入框建议展示
Speculation（推测执行）：如果预测置信度够高，提前用只读工具预跑文件读取，用户确认发送后直接复用结果

架构图

主 Agent 产生响应
    │
    ├─ [Prompt Suggestion]
    │   runForkedAgent（只读模式）
    │   预测"用户下一步会说什么"
    │   → 结果存入 AppState.promptSuggestion
    │   → UI 在输入框展示建议
    │
    └─ [Speculation]
        用户开始输入（输入内容与预测匹配）
            │
            ├─ 对 SAFE_READ_ONLY_TOOLS（Read/Glob/Grep/LSP/TaskList）提前执行
            ├─ 结果写入 overlay 目录（getOverlayPath(id)）
            │
            ├─ 用户确认发送 → 合并 overlay 文件缓存到真实 messages → 节省 TTFT
            └─ 预测失败（输入不匹配）→ safeRemoveOverlay() 丢弃，重新执行

核心文件

文件	作用
`src/services/PromptSuggestion/promptSuggestion.ts`	Prompt Suggestion 主逻辑，`generateSuggestion()`、`shouldEnablePromptSuggestion()`
`src/services/PromptSuggestion/speculation.ts`	Speculation 主逻辑：overlay 创建/合并/清理

关键常量与限制

// speculation.ts
const MAX_SPECULATION_TURNS = 20      // 最多推测 20 轮工具调用
const MAX_SPECULATION_MESSAGES = 100  // 最多产生 100 条消息

// Speculation 只对以下只读工具有效：
const SAFE_READ_ONLY_TOOLS = [
  FileReadTool, GlobTool, GrepTool, LSPTool, TaskListTool
]
// BashTool 等有副作用的工具在 Speculation 阶段被明确禁止

特性门控

Prompt Suggestion：环境变量 CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION，或 Statsig 特性 tengu_chomp_inflection
Speculation：由 isSpeculationEnabled() 检查，在 Swarm 模式的 Teammate 中自动禁用（避免干扰协调逻辑）

附录 II-D：Settings Sync & Team Memory Sync

功能描述

两个独立的云同步机制：

Settings Sync：在多台机器间同步用户的 Claude Code 配置
Team Memory Sync：在同一 git 仓库的团队成员间共享 team-memory/ 目录（MEMORY.md、记忆文件等）

Settings Sync

核心文件：src/services/settingsSync/index.ts、types.ts

特性门控：feature('UPLOAD_USER_SETTINGS') / feature('DOWNLOAD_USER_SETTINGS')

工作流程：

上传（UPLOAD_USER_SETTINGS）：
  读取本地 ~/.claude/settings.json
  对比 serverChecksums（只上传内容有变更的 key）
  → POST /api/settings  (delta 上传，节省带宽)

下载（DOWNLOAD_USER_SETTINGS）：
  → GET /api/settings
  合并到本地 settings（服务端内容覆盖本地）
  常见场景：IDE 插件首次安装，先拉取云端配置再启动

Team Memory Sync

核心文件：src/services/teamMemorySync/（5 个文件）

特性门控：feature('TEAMMEM')

工作流程：

标识仓库：
  SHA256(git remote URL) → 仓库唯一 ID

上传（watcher.ts 监听 team-memory/ 目录变化）：
  1. secretScanner.ts 扫描内容（见下方密钥检测）
  2. 对比 serverChecksums → 只上传有变更的 key（delta 上传）
  3. POST /api/team-memory/<repo-id>

拉取：
  GET /api/team-memory/<repo-id>
  服务端内容覆盖本地（server wins）
  本地删除的文件不会同步到服务端（非破坏性）

文件监听（watcher.ts）：
  chokidar 监听 team-memory/ 目录
  文件变化 → 防抖 → 触发上传

Secret Scanner（teamMemSecretGuard.ts）：

上传前用高置信度规则扫描文件内容，发现以下密钥时拒绝上传并提示用户：

Anthropic API key
AWS access token / secret key
GitHub Personal Access Token (PAT)
GCP Service Account key
Slack token

此外，FileWriteTool / FileEditTool 在 validateInput 阶段也会调用 checkTeamMemSecrets()，在 Agent 写入 team-memory/ 前拦截密钥——双重防护。

附录 II-E：Commit Attribution（提交归因）

功能描述

追踪 git commit 中哪些代码行是由 Claude Code 生成的，并在 commit message 尾部添加标准 trailer 标注来源。

特性门控：feature('COMMIT_ATTRIBUTION')

核心文件：src/utils/commitAttribution.ts

工作流程

Agent 修改/创建文件（FileEditTool / FileWriteTool）
    │
    ├─ 记录 AttributionSnapshot：
    │   { filePath, lineRanges, sessionId, timestamp }
    │
    └─ 用户（或 Agent）执行 git commit
           │
           ├─ calculateCommitAttribution() 计算 AI 生成比例
           │
           └─ 在 commit message 末尾追加 trailer：
               Co-Authored-By: Claude <noreply@anthropic.com>
               Claude-Code-Session: <session-uuid>

内部仓库额外追加（仅 INTERNAL_MODEL_REPOS allowlist 中的私有仓库）：

Claude-Code-Model: <internal-codename>

Undercover 模式（内部仓库保护）

// commitAttribution.ts 中 INTERNAL_MODEL_REPOS 的注释说明：
// NOTE: This is intentionally a repo allowlist, not an org-wide check.
// The anthropics and anthropic-experimental orgs contain PUBLIC repos
// (e.g. anthropics/claude-code, anthropics-experimental/sandbox-runtime).
// Undercover mode must stay ON in those to prevent codename leaks.
// Only add repos here that are confirmed PRIVATE.

公开仓库（包括 anthropics/claude-code 本身）保持"undercover 模式"，不在 commit message 中暴露内部模型代号。

附录 II 源码快速导航

后台智能与持续学习
├── Magic Docs（活文档）
│   └── src/services/MagicDocs/
│       ├── magicDocs.ts     ← 检测 MAGIC DOC 头、注册、触发后台更新
│       └── prompts.ts       ← buildMagicDocsUpdatePrompt()
│
├── Away Summary（离开摘要）
│   └── src/services/awaySummary.ts
│       └── generateAwaySummary()  ← 小模型生成 1-3 句摘要
│
├── Prompt Suggestion + Speculation（预测执行）
│   └── src/services/PromptSuggestion/
│       ├── promptSuggestion.ts    ← 预测用户下一步意图
│       └── speculation.ts         ← 只读工具提前执行 + overlay 管理
│
├── Settings Sync（配置云同步）
│   └── src/services/settingsSync/
│       ├── index.ts    ← 上传/下载 settings
│       └── types.ts    ← 同步协议类型
│
├── Team Memory Sync（团队记忆同步）
│   └── src/services/teamMemorySync/
│       ├── index.ts             ← 同步核心逻辑（delta 上传/拉取）
│       ├── watcher.ts           ← 文件变化监听 + 防抖触发
│       ├── teamMemSecretGuard.ts ← 写入拦截（tool 层防护）
│       └── secretScanner.ts     ← 密钥扫描（gitleaks 规则子集）
│
└── Commit Attribution（提交归因）
    └── src/utils/commitAttribution.ts
        ├── calculateCommitAttribution()  ← AI 行比例计算
        └── INTERNAL_MODEL_REPOS          ← 允许暴露内部代号的私有仓库白名单

→ 附录 III：运行时安全与治理