EVILSTAR

关于宗教，信仰，死亡的一些思考

Sat, 16 May 2026 14:01:46 +0800

东方宗教和西方宗教对于死亡的看法很不一样，以佛教为例，认为人死后灵魂进行转世，根据生前的所做所为进行评判，如果生前行善积德，转世生到富贵人家；如果作恶多端，沦为畜生或者饿鬼，在十八层地狱下经受磨难。佛教来自印度教，轮回的概念也是一脉相承下来。对此我有一些疑问，评判的标准是什么，善恶的标准又是什么，如果一个人拥有很多钱财，热衷于慈善事业，拯救了很多濒临死亡的穷人；但同时为了获得财富，他杀掉了一些竞争者。他杀掉的人可能只有几个，但是拯救的人可能有几千个，几万个。那么这个人转世之后会成为人还是成为畜生呢？如果没有客观的标准，那么应该会有一个全知全能的神来判决，神如何判决呢，作为人应该不得而知，不可知的东西为什么会让这么多人深信不疑呢？无论怎样，死亡不是终点，死亡即是新生，轮回无休无止，只有拥有大功德的真佛才可以涅槃超脱。

西方宗教都确信上帝的存在，人死后经由上帝审判，升上天堂或是堕入地狱。天堂和地狱的评判标准我也深表怀疑，虽然圣经里会有对评判规则的阐述，但是我觉得世界太复杂，人类也太复杂，没有绝对的好人和坏人，也无绝对的善恶。升入天堂的灵魂一定是纯洁的吗？会始终保持纯洁吗？堕入地狱的灵魂一定是肮脏的吗？

人是有自由意志的，但是一到死亡，就会被审判，被发配，所以我们可以说死亡是自由意志的终结吗？

伊曼纽·史威登堡认为人死之后并不会被审判，而是进入灵界，灵界和现实世界保持一致，死去的人照常工作，生活，但是世界的色彩会越来越鲜明，然后有一些陌生人逐渐进入他们的生活，这些人一部分是来自地狱的魔鬼，另外的是来自天堂的天使，如果受到魔鬼的引诱则会堕入地狱，如果遵循天使的引导就会升入天堂。也就是说天堂或者地狱并不是由上帝判决的，而是死去的人自己选择的，自由意志并没有因为死亡而终结。堕入地狱的人并不会向往天堂的生活，因为欺诈，卑鄙，偷盗等等行为只有在地狱才可以肆无忌惮的施展，他们无法适应天堂的纯洁的生活。同样升上天堂的人也无法适应地狱的生活。天堂和地狱，并非上帝判决，而是人自己的选择，自由意志从生命到死亡，贯穿始终。

我觉得伊曼纽·史威登堡的观点很有意思，值得深入研究一下。

为了找回散落的 session，我做了一个 Claude Code / Codex 会话管理器

Thu, 14 May 2026 00:00:00 +0000

最近这段时间，我在本地同时用 Claude Code 和 Codex 做开发的频率越来越高。

工具一多，一个很烦的问题就开始反复出现：session 太难找了。

有些对话在 Claude 里，有些在 Codex 里；有些项目我开了很多个 worktree；有时候我只记得一句提问、一个报错，或者记得那次对话大概发生在哪个分支上，但就是想不起来它到底在哪个 session 里。

还有一个更现实的问题：两个工具也不是总能顺手可用。

有时候 Claude 这边刚好不方便用，有时候 Codex 状态不对；还有些时候，Claude 这轮表现不太符合我预期，我会很自然地想：这段上下文能不能直接切到 Codex 继续？ 反过来也一样。

但实际操作往往很别扭。你要先把旧对话翻出来，再复制上下文，再尝试在另一边接上。如果之前那个 session 本身就已经埋在一堆历史记录里，光是“找到它”这一步，就足够把思路打断。

所以我做了这个项目：Agent Session Manage。

项目地址：https://github.com/evilstar9527/agent-session-manage

它不是一个新的 agent，也不是一个新的聊天工具。更准确地说，它是一个本地的会话管理器：把 Claude Code 和 Codex 的历史会话统一索引起来，让我可以更快地搜索、查看、恢复、导出，并且在需要的时候，尽量平滑地把对话切换到另一个工具里继续。

我想做的，其实不是“另一个聊天应用”

这个项目一开始的定位就很明确：我不想重新发明 Claude Code 或 Codex，我只是想把它们已经产生出来的 session 管理得更顺手一点。

所以它解决的问题也非常具体：

历史 session 不好找
想恢复旧对话时路径不顺手
想在 Claude 和 Codex 之间切换时很麻烦
想把有价值的对话沉淀下来时，没有一个舒服的出口

这也决定了它的设计方向：它不接管原始数据，不改变原有 CLI 的工作方式，而是站在旁边，做一层 索引、检索和操作层。

如果只用一句话概括，我会这样描述它：

它是一个以本地 Claude Code / Codex 会话文件为输入、以统一会话模型为中间层、以 SQLite 为索引层、同时提供 CLI 和桌面 UI 的本地会话管理器。

这里面最重要的是三件事：

真实数据源仍然是本地会话文件
不同来源要先归一成统一模型
SQLite 只是索引层，不是 source of truth

我很喜欢这种结构，因为它很克制。

Claude 的会话还是 Claude 的会话
Codex 的会话还是 Codex 的会话
这个工具只是让它们更容易被找到和继续使用

哪怕有一天本地索引库删了，重新扫描也就回来了。

这套架构大概长什么样

先看一张总图：

flowchart LR subgraph Entry["入口层"] CLI["CLI\nsrc/cli.ts"] UI["React UI\nsrc/ui/App.tsx"] end subgraph Desktop["桌面端桥接层"] Main["Electron Main\nsrc/desktop/main.ts"] IPC["IPC Handlers\nsrc/desktop/ipc.ts"] Watcher["Session Watcher\nsrc/desktop/session-watcher.ts"] end subgraph Core["核心业务层"] Service["SessionService\nsrc/app/session-service.ts"] Indexer["Indexer\nsrc/indexer/index.ts"] Discovery["Discovery\nsrc/discovery/*"] Parsers["Parsers\nsrc/parsers/*"] Model["CanonicalSession\nsrc/model/session.ts"] Repo["SessionRepository\nsrc/store/repo.ts"] Export["Markdown Export\nsrc/export/markdown.ts"] Convert["Format Convert\nsrc/convert/*"] end subgraph Storage["存储层"] SourceFiles["源会话文件\n~/.claude/projects\n~/.codex/sessions\n~/.codex/archived_sessions"] SQLite["本地索引库\n~/.agent-session-manage/index.sqlite"] end CLI --> Service UI --> IPC --> Service Main --> IPC Main --> Watcher Watcher --> Service Service --> Indexer Indexer --> Discovery Discovery --> SourceFiles Indexer --> Parsers Parsers --> Model Service --> Repo Model --> Repo Repo --> SQLite Service --> Export Service --> Convert Convert --> SourceFiles

如果用更直白的话来说，它的工作方式其实很简单：

先找到本地会话文件
 -> 解析成统一格式
 -> 写进本地索引库
 -> 在此基础上提供搜索、查看、恢复、导出、转换能力

整个项目最关键的点，不是 Electron，也不是 SQLite，而是中间那层统一模型。因为只有先把不同来源的 session 整理成同一类对象，后面的搜索、导出、恢复、切换这些功能，才值得做，也才不会越写越乱。

为什么我坚持先做“统一模型”

如果没有这层抽象，事情会很快变得很糟。

你很快就会遇到这种问题：

搜索 Claude 和搜索 Codex 的逻辑不一样
导出 Claude 和导出 Codex 的逻辑不一样
恢复命令生成也不一样
转换逻辑会散在一堆条件分支里

所以我一开始就把核心抽象放在 src/model/session.ts 的 CanonicalSession 上。

它的含义并不复杂：

不管输入来自 Claude 还是 Codex，最后都尽量整理成同一类会话对象。

这个对象里最重要的信息包括：

session 基本信息
project path
git branch
title / summary
messages
tool calls
metadata

一旦这层统一了，很多能力都会顺着长出来：

搜索
查看详情
pin / archive
resume-command
export markdown
Claude / Codex 间转换

它们不需要为每个来源单独再做一遍。

会话是怎么被发现、解析和导入的

这部分主要分三步：发现文件、解析格式、写入索引。

第一步：发现文件

src/discovery/claude.ts 会去递归找 Claude 的 .jsonl，src/discovery/codex.ts 会扫描 Codex 的 rollout-*.jsonl。

这里我没有做什么“万能规则引擎”，而是明确针对两种来源分别适配。

我现在越来越喜欢这种写法：知道格式不一样，就老老实实分别处理。

这通常比“看起来很优雅但到处例外”的抽象更稳。

第二步：解析格式

src/parsers/claude.ts 和 src/parsers/codex.ts 会把原始 JSONL 整理成统一模型。

它们做的不是简单地把 JSON 读出来，而是做一层有目的的提炼，比如：

抽出用户和助手消息
整理 tool call / tool result
推断标题
记录 project path、branch、source session id
留一些 metadata

这里有一个现实我很早就接受了：

这种转换不可能 100% 无损。

所以这个项目的目标从来不是“完整重建另一个工具的所有内部运行状态”，而是做实用型归一化。

也就是说，它优先服务的是这些场景：

我想找回旧对话
我想搜里面提到过什么
我想恢复上下文继续工作
我想把它导出来，或者迁到另一个工具里继续

而不是去做一个协议层面的完美镜像。

第三步：写入索引

扫描导入流程在 src/indexer/index.ts，真正的落库存取在 src/store/repo.ts。

这里我比较满意的一个点是：它不是每次都傻傻地全量重建。

repo 层会保存文件指纹，比如：

size
mtime
quickHash

如果文件没变，就直接跳过，不重复解析。

这个优化听起来不大，但对本地工具很重要。因为 session 一旦真的积累起来，数量会涨得很快。如果每次都全量扫一遍，体验很快就会变差。

为什么我把业务逻辑集中在 SessionService

这个项目里我比较刻意的一件事，是把业务能力尽量都收敛到 src/app/session-service.ts。

它统一暴露了这些接口：

scan()
list()
search()
get()
pin()
archive()
delete()
exportMarkdown()
convert()
getResumeCommand()
launchResume()

这样做最大的好处就是：CLI 和桌面端都可以变得很薄。

src/cli.ts 只需要负责参数解析、调用 service、打印结果。桌面端的 src/desktop/ipc.ts 也只是把前端操作映射到 service 上。

这对我来说很重要，因为 UI 通常是变化最快的部分，但 discovery、parser、store、service 这些底层能力往往更稳定。只要边界划清楚，后面加功能时就不会到处互相牵扯。

桌面端为什么还要做 watcher

如果只有 CLI，心智其实很简单：想刷新就手动 scan，想找东西就用命令查。

但桌面端不一样。桌面端一旦存在，用户就会自然期待：它应该自己知道数据变了。

所以我做了 src/desktop/session-watcher.ts，去监听：

Claude projects 目录
Codex sessions 目录
Codex archived_sessions 目录

文件变化后，它不会立刻全量扫描，而是做一个小防抖，再通知窗口刷新列表。

这个功能很朴素，但体验差别非常大。没有它的时候，桌面应用更像一个“偶尔手动刷新的浏览器”；有了它以后，它才更像一个真正的本地工作台。

对我来说，最有价值的不是搜索，而是“可以继续用”

我后来越来越觉得，这个项目最值钱的地方，并不是“我终于能搜到某个 session 了”，而是搜到之后，我真的可以继续拿它工作。

1. 可以直接恢复原生会话

SessionService.getResumeCommand() 会根据来源生成原生命令：

Claude 走 claude --resume
Codex 走 codex resume

而且桌面端还能直接帮我在终端里打开它。

这件事的关键不在命令本身，而在于它让“找回旧对话”和“继续工作”真正连起来了。

2. 可以导出成 Markdown

很多 agent 对话并不只是一次性的。我经常会碰到一些值得留存的内容：

某次排障过程
某次重构思路
某段工具调用和输出
某轮讨论过的取舍

当它能导出成 Markdown，它就更像一份资料，而不是一段只能被埋在工具目录里的聊天历史。

3. 可以在 Claude 和 Codex 之间切换

这其实最接近我做这个项目的初始动机。

我并不是想做一个“理论上完美兼容”的格式转换器，我真正想要的是：

当我对 Claude 当前这轮表现不满意，或者 Claude 这边暂时不好用时，我能不能尽量少折腾地把上下文迁到 Codex 去继续？

反过来也一样。

所以 conversion 的目标从来不是无损复刻，而是尽可能保住上下文的实用价值。只要它能让我少做一次上下文重建，少打断一次工作流，这个能力就已经很有意义了。

这套架构为什么我觉得是对的

如果回头看，这个项目能站住，核心原因其实就一句话：

我没有把它当成“另一个聊天应用”，而是把它当成“已有会话的管理层”。

这个定位影响了几乎所有设计决策。

它不接管原始数据，不试图取代 Claude Code 或 Codex，也不追求协议层面的完美洁癖。它优先解决的是工作流问题：

能不能找到 session
能不能快速恢复
能不能把上下文切到另一边继续
能不能把历史沉淀下来

我觉得这才是它真正应该服务的场景。

当然，它现在也还不完美

至少在我自己看来，还有几件事是后面会继续做的：

搜索还能更强，比如更好的全文索引和过滤组合
前端现在还能继续拆，尤其是 session 详情和筛选部分
转换能力永远有边界，这件事只能尽量做好，不能假装它是完全无损的

但这些都不影响它现在已经解决了我最在意的那部分问题：把那些原本很容易沉下去的 session，重新变成可以找、可以看、可以接着用的东西。

总结

我做 Agent Session Manage 的原因其实不复杂：

session 越来越多，越来越难找
我经常在 Claude Code 和 Codex 之间切换
有时候其中一边不能用
有时候只是单纯想把一段上下文换到另一边继续
我也希望把这些历史对话变成可以搜索、恢复、导出、沉淀的东西

所以最后做出来的，不是一个新的 agent，而是一个本地会话管理器。

如果再用一句话来概括它，我现在更愿意写成这样：

这不是一个“重新发明 agent”的项目，而是一个把 Claude Code 和 Codex 的历史会话重新组织起来，让它们更容易被找到、更容易被继续使用的工具。

对我来说，这种工具真正重要的地方，不是技术栈本身，而是它能不能减少上下文切换的摩擦，能不能把那些本来很容易沉下去的 session，重新变成可以用起来的工作资产。

Claude Code `/compact` 机制分析

Mon, 11 May 2026 00:00:00 +0000

Context（为什么需要这份分析）

用户想弄清楚 Claude Code 的 compact 功能在源码层面是如何实现的。这不是一个实现任务，而是一次对 /Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source 这份泄露源码的逆向阅读。产出就是这份文档——没有要改的代码。

一、总体架构：三层压缩

Claude Code 对上下文的管理不是单一 compact，而是按"代价从小到大"四层递进：

层级	目标	是否调 LLM	关键文件
snip	裁剪被 REPL 显式标记丢掉的旧消息（UI 滚动历史）	否	`src/services/compact/snipCompact.ts`
microcompact	不改消息数、只把旧 `tool_result`（Read/Bash/Grep/Glob/…）内容清空，靠 cache editing 保住 prompt cache	否	`src/services/compact/microCompact.ts`
session memory compact	把靠前的消息裁掉 + 塞进一个已经由 background 线程提取好的 “session memory”，保留最近若干条消息原文	否（预先提取好）	`src/services/compact/sessionMemoryCompact.ts`
full compact（经典 /compact）	用 LLM 生成结构化摘要，替换掉整段历史	是	`src/services/compact/compact.ts` + `prompt.ts`

在 query 主循环里依次执行（src/query.ts:400-468）：snip → microcompact → contextCollapse → autoCompactIfNeeded。前面几层没把 token 压到阈值以下，才会走到 LLM 级 compact。

二、触发路径

2.1 手动 `/compact [自定义指令]`

入口定义在 src/commands/compact/index.ts：

const compact = {
 type: 'local',
 name: 'compact',
 description: 'Clear conversation history but keep a summary in context. Optional: /compact [instructions for summarization]',
 isEnabled: () => !isEnvTruthy(process.env.DISABLE_COMPACT),
 supportsNonInteractive: true,
 load: () => import('./compact.js'),
}

实际执行在 src/commands/compact/compact.ts:40 的 call()：

getMessagesAfterCompactBoundary(messages) —— 只截取上一次 compact 边界之后的消息，避免重复摘要。
没有自定义指令时先尝试 trySessionMemoryCompaction（轻量路径）。
否则先 microcompactMessages 缩一轮，再 compactConversation(...) 走 LLM 摘要。

2.2 自动 autocompact（容量触发）

src/services/compact/autoCompact.ts 定义阈值：

// 为 LLM 输出留 20K tokens
const MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20_000
const AUTOCOMPACT_BUFFER_TOKENS = 13_000 // 距离硬限还剩 13K 就触发
const MANUAL_COMPACT_BUFFER_TOKENS = 3_000 // 3K 就硬阻塞

getEffectiveContextWindowSize(model) = 模型 context window - 为 summary 预留的 output tokens。
getAutoCompactThreshold(model) = 有效窗 - 13K buffer。
shouldAutoCompact() 在每轮 query 开始前估算 token 数，超过阈值就返回 true。
熔断：连续 3 次 compact 失败后停止尝试（MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES），防止 session 死锁空转烧钱。
递归保护：querySource 是 'session_memory' / 'compact' / 'marble_origami' 时直接 return，避免 forked agent 自己再去 compact。

三、核心压缩算法：`compactConversation`

位于 src/services/compact/compact.ts:387。端到端流程：

┌─ 1. PreCompact hooks ─────────────────────────────────────────────────┐
│ executePreCompactHooks({ trigger:'auto'|'manual', customInstructions })
│ hook 可以改写 customInstructions / 加显示文案 │
├─ 2. 拼 summary prompt ────────────────────────────────────────────────┤
│ getCompactPrompt(customInstructions) │
│ = NO_TOOLS_PREAMBLE + BASE_COMPACT_PROMPT + (Additional Instructions)│
│ + NO_TOOLS_TRAILER │
├─ 3. 走 forked agent 调模型 ───────────────────────────────────────────┤
│ runForkedAgent({ │
│ promptMessages: [summaryRequest], │
│ cacheSafeParams, ← 复用主线程 system prompt / tools / 消息前缀 │
│ canUseTool: createCompactCanUseTool(), ← 拒绝所有工具调用 │
│ maxTurns: 1, │
│ skipCacheWrite: true │
│ }) │
│ // ↑ 复用 prompt cache 是关键。experiment 表明主路 98% 命中率， │
│ // 否则每次 compact 会多烧几十 B tokens/day │
├─ 4. 退化路径：forked agent 失败 → queryModelWithStreaming 裸调 │
│ system = "You are a helpful AI assistant tasked with summarizing │
│ conversations." │
│ thinking = disabled，tools 仅 [FileReadTool] 保留 │
│ messages = stripImages(stripReinjectedAttachments( │
│ getMessagesAfterCompactBoundary(messages) + │
│ summaryRequest)) │
├─ 5. prompt_too_long 兜底 ─────────────────────────────────────────────┤
│ summary 开头 = "API Error: prompt is too long" → truncateHeadFor │
│ PTLRetry() 砍掉最老的一组 API round，重试（最多 MAX_PTL_RETRIES 次） │
├─ 6. 清状态 + 重建附件 ────────────────────────────────────────────────┤
│ context.readFileState.clear() │
│ 并行生成： │
│ ┌ createPostCompactFileAttachments —— 把压缩前被读过的文件重读 │
│ │ （上限 5 个文件，每文件 5K tokens，总 50K tokens） │
│ ├ createAsyncAgentAttachmentsIfNeeded │
│ ├ createPlanAttachmentIfNeeded / createPlanModeAttachmentIfNeeded │
│ ├ createSkillAttachmentIfNeeded —— 已调用过的 skill 原文 │
│ │ （上限 5 个，每个 5K，总 25K） │
│ └ getDeferredToolsDeltaAttachment / AgentListing / MCP Instructions│
│ // 总之：把"主动上下文"重新塞回去，LLM 摘要里没覆盖的死信息（刚读 │
│ // 的代码、当前 plan、用到的 skill）靠这些 attachment 复活 │
├─ 7. SessionStart hooks（复用 'compact' 触发语义） │
├─ 8. 构造 boundary + summaryMessage ───────────────────────────────────┤
│ boundaryMarker = createCompactBoundaryMessage('auto'|'manual', …) │
│ // ↑ type:'system', subtype:'compact_boundary'，content="Conversa │
│ // tion compacted"。未来 getMessagesAfterCompactBoundary 会反向 │
│ // 扫描、只保留这之后的消息。 │
│ summaryMessages = [ createUserMessage({ │
│ content: getCompactUserSummaryMessage(summary, suppressFollow…) │
│ isCompactSummary: true, │
│ isVisibleInTranscriptOnly: true │
│ }) ] │
├─ 9. formatCompactSummary —— 去 <analysis>，把 <summary> 变成 │
│ "Summary:\n..." 可读文本 │
├─10. 埋点 tengu_compact（preToken / postToken / 缓存命中率 / …） │
├─11. notifyCompaction() —— 重置 prompt cache 基线，避免后续把 compact │
│ 自身导致的 cache drop 误报成 cache break │
├─12. PostCompact hooks ────────────────────────────────────────────────┤
└─13. return CompactionResult { boundaryMarker, summaryMessages, attach…│
hookResults, userDisplayMessage, … } │

调用方（src/commands/compact/compact.ts 或 autoCompact.ts）拿到 result 后再做 runPostCompactCleanup()、suppressCompactWarning()、markPostCompaction()、notifyCompaction()，然后把新消息数组交回 REPL。

四、摘要提示词（这才是"compact 究竟让 LLM 做什么"的答案）

都在 src/services/compact/prompt.ts。

4.1 前导（`NO_TOOLS_PREAMBLE`）

CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.

注释里写得很露骨：fork 出去的 agent 继承了主线程全部工具定义（为了 cache key 对上才能命中 prompt cache），但 Sonnet 4.6+ 的 adaptive-thinking 有 2.79% 概率无视弱指令去调工具 → maxTurns=1 浪费掉 → 所以把"不准调工具"作为最粗暴的前置指令。

4.2 主体（`BASE_COMPACT_PROMPT`）

要求模型产出九段结构化摘要：

Primary Request and Intent —— 用户原始请求
Key Technical Concepts —— 技术名词列表
Files and Code Sections —— 看过/改过的文件，要求贴代码片段
Errors and fixes —— 坑 + 用户反馈
Problem Solving —— 解决了什么
All user messages —— 所有非 tool_result 的用户消息全列出来（最关键、最怕丢）
Pending Tasks
Current Work —— 压缩前最后在干什么，要贴文件名 + 代码片段
Optional Next Step —— 下一步，要求引用最近对话原话避免漂移

产出格式固定为：

<analysis>
[思考草稿；formatCompactSummary 会剥掉]
</analysis>
<summary>
1. Primary Request and Intent: …
…
9. Optional Next Step: …
</summary>

4.3 结尾（`NO_TOOLS_TRAILER`）

REMINDER: Do NOT call any tools. Respond with plain text only — an
<analysis> block followed by a <summary> block. Tool calls will be
rejected and you will fail the task.

4.4 两个变体

PARTIAL_COMPACT_PROMPT —— 只摘要"最近消息"，前面保留原文（partialCompactConversation，用于 direction='from'）。
PARTIAL_COMPACT_UP_TO_PROMPT —— 摘要前半、后半保留原文，会命中 cache prefix。

4.5 用户自定义指令拼接

if (customInstructions && customInstructions.trim() !== '') {
 prompt += `\n\nAdditional Instructions:\n${customInstructions}`
}

/compact focus on test failures 里的 focus on test failures 就拼在这里。

五、压缩后的会话长什么样

getCompactUserSummaryMessage（prompt.ts:337）产出的单条 user 消息：

This session is being continued from a previous conversation that ran
out of context. The summary below covers the earlier portion of the
conversation.
Summary:
1. Primary Request and Intent:
...
…
9. Optional Next Step:
...
If you need specific details from before compaction (like exact code
snippets, error messages, or content you generated), read the full
transcript at: <transcriptPath>
Recent messages are preserved verbatim. ← 仅在保留尾部时追加
Continue the conversation from where it left off without asking the
user any further questions. Resume directly — do not acknowledge the
summary, do not recap what was happening, do not preface with "I'll
continue" or similar. Pick up the last task as if the break never
happened. ← suppressFollowUpQuestions

autocompact 会设 suppressFollowUpQuestions=true，手动 /compact 不会。最终新消息序列：

[旧 boundary / 旧 summary] ← 若本会话之前就 compact 过，这里保留
[SystemCompactBoundaryMessage] ← 本次分隔符
[UserMessage（上面那段摘要）]
[file attachments] ← 重读的 ≤5 个文件
[plan / skill / 工具 delta attachments]
[SessionStart hook messages]

六、其它关键设计点

runForkedAgent 保证 fork 出去的 compact 调用与主线程 cacheSafeParams 完全一致（system prompt、tools、消息前缀、thinking 配置），这样 Anthropic API 侧 prompt cache 能命中主线程那一份——省出 ~38B tokens/day 的 cache_creation。

6.2 图片/文档剥离

stripImagesFromMessages 把 user 消息和 tool_result 里嵌套的 image / document block 换成 [image] / [document] 文本占位——一方面摘要用不着，另一方面图片会把 compact 自身的 request 撑爆。

6.3 prompt_too_long 重试

如果 compact 请求自己触发了 413，用 truncateHeadForPTLRetry 砍掉最老一组 API round 再试（最多 MAX_PTL_RETRIES 次）。这是 CC-1180 bug 的修复——以前用户直接卡死无法恢复。

6.4 Post-compact 文件重读

Compact 后 context.readFileState.clear() 会被清掉，createPostCompactFileAttachments 会挑最近读过的最多 5 个文件、每个最多 5K tokens、共 50K tokens 重新 Read 一遍塞回来。这就是为什么 compact 后代码细节通常不会丢——摘要里可能写了"修改了 foo.ts 的 bar 函数"，但真正可供 LLM 继续编辑的原文是通过 attachment 再喂一次进来的。

6.5 Boundary 概念

createCompactBoundaryMessage 插一条 subtype: 'compact_boundary' 的 system 消息到历史里。REPL UI 还是能看到全历史（可以滚回去），但是所有发给 API 的消息集合都是 getMessagesAfterCompactBoundary(messages) 反向扫到第一条 boundary 之后的。这就是 UI 和 API 视图解耦的方式。

6.6 Session memory compact（实验路径）

无自定义指令时优先尝试：

后台线程一直在抽取 session memory（工具输出纲要 + 决策点）。
触发时不调 LLM，直接用已提取好的 memory 文本生成"摘要"，保留最近 10K–40K tokens 的原消息（DEFAULT_SM_COMPACT_CONFIG）。
更便宜、对最近上下文无损；有自定义指令时回退到经典路径。

6.7 Reactive compact

在 REACTIVE_COMPACT feature flag 下，autocompact 关闭、只有当 API 真返回 413 (prompt_too_long) 时才就地压缩——更激进地利用 context。

七、一句话总结

Claude Code 的 compact = “让模型用一份固定的九段式结构化 prompt 对整段对话做自我摘要 → 插一条 boundary → 清文件缓存 → 把最近读过的文件/调过的 skill/当前 plan 作为 attachment 重新注入”。配合 microcompact 的 tool_result 清空、session memory 的后台预提取、forked agent 的 prompt cache 复用、PTL 重试熔断，形成一套"压缩代价阶梯 + 摘要永远可重入 + 缓存不破坏"的组合拳。

关键文件索引

文件	作用
`src/commands/compact/index.ts`	`/compact` 命令注册
`src/commands/compact/compact.ts`	`/compact` 的本地命令 `call()` 逻辑
`src/services/compact/prompt.ts`	全部摘要 prompt 字面量 + `formatCompactSummary`
`src/services/compact/compact.ts`	`compactConversation` / `partialCompactConversation` / `streamCompactSummary` / 附件重建
`src/services/compact/autoCompact.ts`	阈值计算、`shouldAutoCompact`、`autoCompactIfNeeded`、熔断
`src/services/compact/microCompact.ts`	清理旧 tool_result 的轻量预压缩
`src/services/compact/sessionMemoryCompact.ts`	不调 LLM 的 session-memory 版压缩
`src/services/compact/postCompactCleanup.ts`	压缩后通用清理钩子
`src/utils/messages.ts:4530+`	`createCompactBoundaryMessage` / `findLastCompactBoundaryIndex` / `getMessagesAfterCompactBoundary`
`src/query.ts:400-468`	主循环里 snip → microcompact → contextCollapse → autocompact 的调度
`src/utils/forkedAgent.ts`	`runForkedAgent`（复用主线程 prompt cache 调 compact）

验证建议（如果想动手跑一遍）

在项目根执行 rg -n "NO_TOOLS_PREAMBLE" src/ 确认 prompt 字面量只此一家。
DEBUG=true 跑一次会话，找 log autocompact: tokens=... threshold=... effectiveWindow=... 观察阈值。
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50 可把触发阈值压到 50%，便于手动复现。
触发后在 ~/.claude/projects/*/ 的 transcript 里搜 subtype":"compact_boundary" 看实际边界消息结构。

Claude Code Task 架构分析

Mon, 11 May 2026 00:00:00 +0000

1. 先说结论

这份源码里的 task 不是一个单一概念，而是两个相关但不同的子系统：

运行时后台任务系统
- 管理正在运行或已结束的后台 bash、agent、remote session 等
- 核心文件：Task.ts、tasks.ts、utils/task/framework.ts、AppStateStore.ts
TodoV2 任务清单系统
- 管理“要做什么”的结构化任务列表
- 核心文件：utils/tasks.ts、useTasksV2.ts、TaskCreateTool、TaskUpdateTool、TaskListTool

这两个系统名字都叫 task，但职责完全不同：

后台任务系统回答的是 “谁正在跑、输出在哪、怎么停”
任务清单系统回答的是 “还有哪些工作项、谁负责、依赖关系是什么”

2. 总体关系图

flowchart TB A["Model / User"] --> B["Task Tools"] B --> C["Runtime Background Task System"] B --> D["TodoV2 Task List System"] subgraph Runtime Background Task System C1["Task.ts contract"] C2["AppState.tasks"] C3["LocalShellTask / LocalAgentTask / RemoteAgentTask"] C4["task output on disk"] C5["stop / output / notifications"] end subgraph TodoV2 Task List System D1["utils/tasks.ts"] D2["task json files + lock"] D3["TaskCreate / Update / Get / List"] D4["useTasksV2 watcher"] end B1["TaskStopTool / TaskOutputTool"] --> C B2["TaskCreateTool / TaskUpdateTool / TaskGetTool / TaskListTool"] --> D

最容易误读源码的地方就在这里：TaskStopTool 停的是运行中的后台任务，不是 TodoV2 清单里的任务项；TaskUpdateTool 更新的是清单任务，不是后台进程状态。

3. 运行时后台任务系统

3.1 核心抽象

后台任务的统一协议在 src/Task.ts：

TaskType
TaskStatus
TaskStateBase
Task
generateTaskId()
createTaskStateBase()

它的设计很克制，Task 本体只保留：

name
type
kill(taskId, setAppState)

也就是说，当前这一层不是一个完整的 OO 基类体系，而是一个最小 kill-dispatch 协议。
任务的 spawn、progress、notification、output 逻辑，下沉到了各个具体 task 实现中。

3.2 运行时任务分层图

flowchart TB A["Task.ts"] --> B["tasks.ts registry"] B --> C["getTaskByType"] C --> D["Concrete task impl"] D --> E["LocalShellTask"] D --> F["LocalAgentTask"] D --> G["RemoteAgentTask"] D --> H["Dream/Workflow/Monitor optional tasks"] E --> I["AppState.tasks"] F --> I G --> I H --> I I --> J["framework.ts register/update/evict"] J --> K["notifications + sdk events"] J --> L["task output on disk"]

这里的关键思想是：

task 类型是开放集合，但统一通过 registry 查找
公共状态收口在 AppState.tasks
公共框架只管注册、更新、驱逐、通知
真正的业务生命周期由具体 task 自己实现

4. AppState 为什么是任务系统的中心

后台任务统一存在 AppState.tasks 里，而不是每种任务自己维护一套 store。

这在 AppStateStore.ts 里很明显：

tasks: { [taskId: string]: TaskState }
foregroundedTaskId
viewingAgentTaskId
remoteBackgroundTaskCount

4.1 状态视图图

flowchart LR A["AppState.tasks"] --> B["taskId -> TaskState"] A --> C["background task list UI"] A --> D["foregroundedTaskId"] A --> E["viewingAgentTaskId"] A --> F["coordinator/task panel"] A --> G["TaskStopTool lookup"] A --> H["TaskOutputTool lookup"]

这样做有几个直接收益：

所有 UI 都从一个状态源读取
TaskStopTool 不需要知道 task 存在哪，只查 AppState.tasks
前后台切换只需要改 task state，不需要迁移数据结构
不同 task type 可以复用统一生命周期字段

5. framework.ts 是运行时任务框架层

src/utils/task/framework.ts 是后台任务系统的核心公共层。它主要负责：

registerTask()
updateTaskState()
evictTerminalTask()
generateTaskAttachments()
applyTaskOffsetsAndEvictions()
pollTasks()

5.1 框架职责图

flowchart TB A["Concrete Task"] --> B["registerTask"] A --> C["updateTaskState"] B --> D["AppState.tasks"] C --> D D --> E["pollTasks"] E --> F["generateTaskAttachments"] F --> G["offset update"] F --> H["terminal eviction"] F --> I["notification enqueue"]

几个关键点：

updateTaskState() 是统一写入口，避免各处直接改 AppState.tasks
registerTask() 在状态登记外，还会发 task_started SDK 事件
终态任务不是立刻全删，而是受 notified、retain、evictAfter 约束
generateTaskAttachments() 不直接负责 completed 通知，completed 通知大多由各 task 类型自己发

这说明作者有意把 framework 限制在“状态基础设施”层，而不是做成一个吞掉所有差异的超大调度器。

6. 输出系统：为什么 task output 单独做了一层

后台任务最核心的问题之一是输出管理。这里拆成了两层：

DiskTaskOutput
TaskOutput

6.1 输出架构图

设计上有两个重点：

对 bash 这种文件模式，stdout/stderr 尽量绕过 JS，直接落文件
对 hook/pipe 模式，先缓存在内存，超阈值再 spill to disk

diskOutput.ts 还专门做了几件工程化处理：

session 级输出目录隔离，避免并发 session 互相踩
O_NOFOLLOW 防止符号链接攻击
5GB disk cap
fire-and-forget 写操作跟踪，避免测试 teardown 时出现异步悬挂

这说明 task 输出在这里不是附属功能，而是后台任务系统的一级公民。

7. LocalShellTask：后台 bash 任务怎么实现

LocalShellTask 体现的是“把 shell command 变成可管理任务”。

7.1 生命周期图

sequenceDiagram participant T as BashTool / caller participant S as spawnShellTask participant A as AppState.tasks participant O as TaskOutput participant N as Notification T->>S: spawnShellTask(shellCommand) S->>A: registerTask(status=running, isBackgrounded=true) S->>O: taskOutput already attached to shellCommand S->>S: shellCommand.background(taskId) S->>S: startStallWatchdog() S->>S: await shellCommand.result S->>A: update status completed/failed/killed S->>N: enqueueShellNotification() S->>O: evictTaskOutput()

这个实现里有几个很实用的点：

startStallWatchdog() 会观察输出 tail，检测像 (y/n) 这样的交互提示
前台运行过久后也可以登记成 foreground task，再 background
shell task 结束后会统一发 task notification，而不是只改 state

这说明 shell task 在这里不是 “子进程句柄”，而是“带观察、通知、恢复语义的后台作业”。

8. LocalAgentTask：后台 agent 任务怎么实现

LocalAgentTask 其实比 shell task 更复杂，因为它不只是运行，还要支持：

进度统计
activity 摘要
前后台切换
teammate transcript 视图
retain / evictAfter
AbortController 父子链

8.1 Agent 任务结构图

flowchart TB A["AgentTool / caller"] --> B["registerAsyncAgent or registerAgentForeground"] B --> C["LocalAgentTaskState"] C --> D["AppState.tasks"] D --> E["progress update"] D --> F["summary update"] D --> G["pending messages"] D --> H["retain / diskLoaded / evictAfter"] D --> I["backgroundAgentTask"] D --> J["killAsyncAgent"] D --> K["completeAgentTask / failAgentTask"]

8.2 关键设计点

registerAsyncAgent() 是一开始就后台化
registerAgentForeground() 是前台执行，但保留后续 background 的可能
backgroundAgentTask() 的本质是改 isBackgrounded 并触发等待 promise
transcript 输出不是简单写文件，而是通过 symlink 指到 agent transcript
progress 不是靠任务系统轮询 tool output，而是从 agent message 流里聚合出来

这是一个很重要的区别：

shell task 的“真相”主要在进程输出
agent task 的“真相”主要在消息流和 transcript

所以两者虽然都叫 task，但底层观测模型完全不同。

9. RemoteAgentTask：后台任务还能落到远端 session

RemoteAgentTask 说明这套 task 系统并不绑定本地进程。
它把远端 session 也包装成统一 task state，纳入同一个 AppState.tasks。

9.1 远端任务图

flowchart LR A["Remote spawn request"] --> B["RemoteAgentTaskState"] B --> C["sessionId + metadata"] C --> D["pollRemoteSessionEvents"] D --> E["appendTaskOutput"] D --> F["update task state"] F --> G["task notification"] F --> H["archive / cleanup metadata"]

这说明 task 子系统的抽象层级是“可被统一管理的异步工作单元”，而不是“本地线程/进程”。

10. 停止与取出输出：运行时任务对模型的桥

后台任务系统主要通过两个 tool 暴露给模型：

TaskStopTool
TaskOutputTool

10.1 停止链路图

flowchart TD A["TaskStopTool"] --> B["stopTask"] B --> C["AppState.tasks lookup"] C --> D["getTaskByType"] D --> E["concreteTask.kill"] E --> F["update state / abort / cleanup"] F --> G["suppress or emit notifications"]

stopTask.ts 的设计很干净：

先查 task
验证是否 running
按 task.type 找实现
调 kill()

也就是说，停止路径是真正用到了 Task registry 的多态分发。

10.2 输出链路图

flowchart TD A["TaskOutputTool"] --> B["lookup task in AppState.tasks"] B --> C{"block?"} C -->|"false"| D["read current output"] C -->|"true"| E["waitForTaskCompletion"] E --> F["read final output"] D --> G["getTaskOutputData"] F --> G G --> H["type-specific normalization"] H --> I["tool result"]

TaskOutputTool 的一个重要信号是：它已经被标记为 deprecated，推荐直接用 Read 去读 task output file。
这说明任务系统的输出最终被收敛成“可读文件路径”这个更通用的抽象。

11. TodoV2 任务清单系统

另一套 task 是 utils/tasks.ts 驱动的结构化任务清单系统。

它不是运行时进程管理，而是轻量任务数据库，底层直接用文件系统：

每个 task 一个 json 文件
目录按 taskListId 划分
用高水位文件保证 ID 不回退
用 lockfile 避免并发写冲突

11.1 任务清单存储图

flowchart TB A["getTaskListId"] --> B["tasks dir"] B --> C["1.json"] B --> D["2.json"] B --> E["3.json"] B --> F[".highwatermark"] B --> G["lock file"] H["createTask/updateTask/deleteTask/listTasks/blockTask"] --> B H --> I["notifyTasksUpdated signal"]

11.2 为什么 taskListId 设计得这么复杂

getTaskListId() 的优先级并不简单，因为它要让：

独立 session
team lead
in-process teammate
tmux/iTerm teammate

都能落到同一套任务清单里，而不是各自有一份。

所以这套系统本质上是一个“共享工作分解板”。

12. TaskCreate / Update / List / Get 是清单系统的 API 层

这些工具并不操作 AppState.tasks，而是操作 utils/tasks.ts 的文件化任务清单。

12.1 清单工具关系图

flowchart LR A["TaskCreateTool"] --> E["utils/tasks.ts"] B["TaskUpdateTool"] --> E C["TaskListTool"] --> E D["TaskGetTool"] --> E E --> F["json task files"] E --> G["notifyTasksUpdated"] G --> H["useTasksV2 store"] H --> I["task list UI"]

几个关键点：

TaskCreateTool 创建新任务，并自动展开 task 面板
TaskUpdateTool 支持状态更新、owner、metadata、依赖关系修改
TaskListTool 会过滤掉内部任务，并对已完成依赖做清理展示
TaskGetTool 是按 ID 读取详情

注意：这里的 status 是 pending / in_progress / completed，和后台任务系统的 pending / running / completed / failed / killed 不是一套状态机。

13. useTasksV2：清单系统的 UI 同步层

useTasksV2.ts 做的不是业务逻辑，而是把文件系统任务清单转成稳定的前端 store。

13.1 同步图

flowchart TD A["TasksV2Store"] --> B["listTasks()"] B --> C["#tasks cache"] C --> D["useSyncExternalStore consumers"] E["fs.watch"] --> A F["onTasksUpdated signal"] --> A G["fallback poll"] --> A A --> H["hide timer"] H --> I["all completed for 5s"] I --> J["resetTaskList"]

这层设计得很务实：

多个组件共享一个 watcher，避免 mount/unmount 抖动
fs.watch + signal + fallback poll 三路兜底
全部完成 5 秒后自动隐藏并 reset

所以 TodoV2 清单系统不是“每次 render 去读文件”，而是一个有缓存、有 watcher、有生命周期的轻量本地数据源。

14. 两套 task 系统的关系

这两套系统不是上下级，而是并列存在、分别解决不同问题。

14.1 关系图

flowchart TB A["Runtime Background Tasks"] --> A1["what is running"] A --> A2["how to stop"] A --> A3["where is output"] B["TodoV2 Task List"] --> B1["what should be done"] B --> B2["who owns it"] B --> B3["what blocks what"] C["Agent / Model workflow"] --> A C --> B A -. may inspire updates .-> B B -. may drive delegation .-> A

用一句话概括：

后台任务系统管理“执行中的异步工作”
TodoV2 管理“结构化工作计划”

两者会互相配合，但不是同一个状态模型。

15. 设计优点与代价

优点

后台任务和任务清单职责清晰，虽然同名但边界明确
后台任务统一收口到 AppState.tasks，易于做 UI 和 tool 集成
输出系统独立成层，兼容本地进程、agent transcript、远端 session
TodoV2 直接基于文件系统，简单、可共享、易恢复
task registry 只负责最小多态分发，没有过度抽象

代价

“task” 一词严重重载，初读源码很容易混淆两套系统
后台任务和 TodoV2 各有自己的状态机，理解成本高
某些行为跨文件分散，比如通知在具体 task 里，轮询在 framework 里，输出在 utils/task 里
TaskOutputTool 已经开始退场，说明接口层正在演进，历史兼容负担仍在

16. 一句话总结

Claude Code 的 task 实现不是单一模块，而是两套系统并存：

一套是运行时后台任务内核，负责异步执行、停止、输出、通知
一套是 TodoV2 任务清单，负责工作分解、依赖、归属和 UI 展示

如果只看名字会觉得混乱，但从职责上看，这个切分其实是合理的。

Claude Code Tools 设计分析

Mon, 11 May 2026 00:00:00 +0000

1. 结论

Claude Code 的 tools 不是一个简单的函数注册表，而是一套统一的能力运行时协议。它把同一个 tool 同时投影到四个面：

模型侧：tool schema、prompt、strict、defer loading
执行侧：参数校验、调用、进度、结果、中断
权限侧：全局规则、工具特化规则、交互确认
UI 侧：tool use、progress、result、error、grouped render

核心抽象集中在：

/Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source/src/Tool.ts
/Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source/src/services/tools/toolExecution.ts
/Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source/src/services/tools/toolOrchestration.ts
/Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source/src/hooks/useCanUseTool.tsx
/Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source/src/utils/api.ts
/Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source/src/utils/toolSearch.ts

2. 总体架构图

flowchart TB A["Model / API"] --> B["Tool Definition Layer"] B --> C["Execution Layer"] B --> D["Permission Layer"] B --> E["UI / Transcript Layer"] B --> F["Concrete Tools"] C --> G["tool_result back to conversation"] D --> C F --> C F --> E subgraph Tool Definition Layer B1["Tool interface"] B2["buildTool defaults"] B3["inputSchema / prompt / render / permission hooks"] end subgraph Execution Layer C1["runTools"] C2["runToolUse"] C3["checkPermissionsAndCallTool"] end subgraph Permission Layer D1["hasPermissionsToUseTool"] D2["tool.checkPermissions"] D3["interactive/coordinator/swarm handlers"] end subgraph UI / Transcript Layer E1["renderToolUseMessage"] E2["renderToolUseProgressMessage"] E3["renderToolResultMessage"] E4["extractSearchText"] end subgraph Concrete Tools F1["FileReadTool"] F2["BashTool"] F3["MCPTool"] F4["AgentTool"] end

这个图表达的重点是：Tool 不是只服务执行器，而是四条链路共享的合同对象。

3. Tool 对象结构图

Tool 接口定义在 Tool.ts，buildTool() 负责补全默认实现。默认值明显偏 fail-closed：

isConcurrencySafe -> false
isReadOnly -> false
isDestructive -> false
toAutoClassifierInput -> ''

classDiagram class Tool { +name +aliases +searchHint +inputSchema +inputJSONSchema +outputSchema +call() +description() +prompt() +validateInput() +checkPermissions() +isConcurrencySafe() +isReadOnly() +isDestructive() +interruptBehavior() +preparePermissionMatcher() +toAutoClassifierInput() +mapToolResultToToolResultBlockParam() +renderToolUseMessage() +renderToolUseProgressMessage() +renderToolResultMessage() +renderToolUseErrorMessage() +renderGroupedToolUse() +extractSearchText() +shouldDefer +alwaysLoad +strict +maxResultSizeChars } class ToolDef { <> } class buildTool { +fills safe defaults } ToolDef --> buildTool buildTool --> Tool

这里的设计意图很明确：tool 的定义阶段就把“执行、权限、UI、模型暴露”全部收拢，而不是散落在多个 registry 中。

4. 执行时序图

执行主链路从 runTools() 到 runToolUse() 再到 checkPermissionsAndCallTool()。

sequenceDiagram participant M as Model participant O as toolOrchestration.runTools participant E as toolExecution.runToolUse participant T as Concrete Tool participant P as Permission Bridge participant U as UI/Transcript M->>O: tool_use blocks O->>O: partitionToolCalls() O->>E: runToolUse(tool_use) E->>E: findToolByName() E->>E: inputSchema.safeParse() E->>T: validateInput() E->>P: canUseTool(...) P->>P: hasPermissionsToUseTool() P->>T: checkPermissions() P-->>E: allow / deny / ask E->>T: call(...) T-->>E: progress events E-->>U: progress message T-->>E: ToolResult E->>T: mapToolResultToToolResultBlockParam() E-->>U: tool_result message U-->>M: result enters next conversation turn

链路被拆成三类关口：

结构校验：inputSchema.safeParse()
语义校验：validateInput()
权限校验：canUseTool() + checkPermissions()

这样做的好处是错误原因能被准确归类，模型也更容易修正下一次调用。

5. 权限设计图

权限系统不是单一 allow/deny 开关，而是“全局规则 + 工具特化 + 交互流程”的组合。

flowchart TD A["tool call request"] --> B["hasPermissionsToUseTool"] B --> C{"behavior"} C -->|"allow"| D["direct allow"] C -->|"deny"| E["reject"] C -->|"ask"| F["build permission description"] F --> G{"mode / environment"} G --> H["coordinator handler"] G --> I["swarm worker handler"] G --> J["interactive dialog"] H --> K["final decision"] I --> K J --> K K --> L["allow with updatedInput"] K --> M["deny"] B --> N["tool.checkPermissions"] N --> C

关键点：

全局系统负责统一规则匹配
每个工具保留 checkPermissions()，处理自己才懂的语义
updatedInput 允许权限层改写调用参数
Bash 还接了 classifier 和 speculative check

这能避免把所有工具差异都堆进一个巨大的统一权限函数里。

6. 并发与批处理图

并发不是“统一线程池策略”，而是每个 tool 自己声明 isConcurrencySafe(input)，由编排器按调用顺序动态分组。

flowchart LR A["tool_use list"] --> B["partitionToolCalls"] B --> C{"isConcurrencySafe?"} C -->|"yes"| D["append to concurrent batch"] C -->|"no"| E["start serial batch"] D --> F["runToolsConcurrently"] E --> G["runToolsSerially"] F --> H["collect queued context modifiers"] H --> I["apply modifiers after batch"] G --> J["apply modifier immediately"]

这套设计的特点：

并发安全是 tool 自声明，不是 orchestration 硬编码
非安全工具串行，避免状态冲突
并发批次内的 contextModifier 延迟到批次完成后统一应用

这说明作者把“调度语义”也纳入了 tool contract。

7. ToolSearch / Deferred Loading 图

这部分是这套架构比较成熟的一点。工具太多时，问题不再是“支不支持 tool”，而是“是否值得在首轮 prompt 暴露全部 schema”。

flowchart TB A["Registered tools"] --> B{"shouldDefer / MCP / ToolSearch mode"} B -->|"inline"| C["toolToAPISchema normal"] B -->|"defer"| D["toolToAPISchema + defer_loading"] C --> E["API request tools array"] D --> E E --> F["Model sees inline tools"] E --> G["Deferred tools discoverable via ToolSearch"] G --> H["Model calls ToolSearchTool"] H --> I["tool_reference / discovered-tool set"] I --> J["Retry actual deferred tool"]

关键实现点：

toolToAPISchema() 负责把 Tool 转成 API schema
strict、eager_input_streaming、cache_control、defer_loading 都在这里统一处理
getToolSearchMode() 和 token/char threshold 控制是否启用动态工具加载

这个设计解决了两个问题：

prompt 太大
MCP / 扩展工具太多时首轮 schema 暴露成本过高

8. 典型工具对比图

flowchart TB subgraph Read["FileReadTool"] R1["isConcurrencySafe = true"] R2["isReadOnly = true"] R3["path backfill"] R4["read permission"] R5["maxResultSizeChars = Infinity"] end subgraph Bash["BashTool"] B1["isConcurrencySafe = isReadOnly"] B2["command parsing"] B3["bash permission"] B4["progress streaming"] B5["background task"] B6["persist large output"] end subgraph MCP["MCPTool"] M1["isMcp = true"] M2["passthrough schema"] M3["dynamic override by mcp client"] M4["permission passthrough"] end subgraph Agent["AgentTool"] A1["dynamic prompt from agents + MCP + permissions"] A2["subagent/team/fork lifecycle"] A3["agent-specific permission check"] A4["tool-based delegation model"] end

四个工具分别体现了不同设计重点：

FileReadTool：安全读取和上下文控制
BashTool：受控任务执行系统
MCPTool：外部能力适配模板
AgentTool：把子 agent 调度也纳入 tool 协议

9. 分层职责表

层	主要对象	解决的问题
抽象层	`Tool`, `ToolDef`, `buildTool`	统一描述 tool 的能力、权限、UI、模型暴露
API 映射层	`toolToAPISchema`, ToolSearch	把本地 tool 转成模型能消费的 schema，控制 prompt 成本
编排层	`runTools`, `partitionToolCalls`	基于 tool 声明的并发属性做批处理
执行层	`runToolUse`, `checkPermissionsAndCallTool`	完成 lookup、校验、权限、执行、结果回写
权限层	`hasPermissionsToUseTool`, `tool.checkPermissions`	统一权限规则与工具专属规则组合
具体工具层	`FileReadTool`, `BashTool`, `MCPTool`, `AgentTool`	实现各类能力的具体运行逻辑
表现层	render / extract / grouping APIs	让工具结果对用户可见、可检索、可折叠

10. 设计优点与代价

优点

一个 tool 对象就能覆盖模型、执行、权限、UI 四个面
buildTool() 提供保守默认值，安全边界清晰
并发是声明式的，扩展新工具成本低
权限支持工具特化，不会退化成全局 switch(tool.name)
ToolSearch 明确把 prompt budget 当成系统级问题处理

代价

Tool 接口很重，接入新工具需要理解的维度较多
UI 渲染逻辑和执行协议耦合在同一个对象中，抽象不够纯
重工具如 BashTool、AgentTool 已经接近子系统复杂度
feature flag、provider、model 能力会影响行为，阅读成本高

11. 一句话总结

Claude Code 的 tools 设计本质上是一套“统一能力运行时协议”。
它并不是把模型调用转发给几个本地函数，而是把 schema、权限、执行、并发、UI 和 transcript 统一建模为同一个 Tool 合同。

Claude Code 源码架构文档

Mon, 11 May 2026 00:00:00 +0000

基于 @anthropic-ai/claude-code v2.1.88 还原源码梳理。

1. 架构结论

Claude Code 不是一个“简单 CLI”，而是一个**单进程宿主（host）+ 会话引擎（conversation engine）+ 工具平台（tool platform）+ 多代理任务系统（multi-agent task runtime）**的 TypeScript/Bun 单体应用。

它的核心特征有 4 个：

单进程多入口 src/entrypoints/cli.tsx 先做轻量分流，按命令进入普通 REPL、headless print/SDK、bridge、daemon、remote control 等不同运行形态。
统一会话内核 无论是交互式 REPL 还是非交互 SDK，核心都汇聚到 QueryEngine / query() 这条消息循环。
工具优先的 Agent 运行时 模型只负责生成消息和 tool_use，真正执行文件、shell、MCP、子代理、远端任务的是本地工具与任务系统。
产品线式编译 build.ts 用 Bun 的 feature() 做编译期开关，很多内部能力通过 dead code elimination 被裁掉，因此“Claude Code 架构”本质上是一个可裁剪产品线架构。

2. 整体架构图

flowchart TD U["User / SDK / Remote Caller"] subgraph Build["Build-Time Product Line"] B1["build.ts"] B2["Feature Flags
feature()"] B3["MACRO constants"] B4["dist/cli.js"] B1 --> B2 B1 --> B3 B2 --> B4 B3 --> B4 end U --> E1 subgraph Entry["Entry & Bootstrap"] E1["src/entrypoints/cli.tsx"] E2["src/main.tsx"] E3["src/entrypoints/init.ts"] E4["src/setup.ts"] E1 --> E2 E2 --> E3 E2 --> E4 end subgraph Surface["Runtime Surface"] S1["Interactive REPL
screens/REPL.tsx"] S2["Headless / SDK
cli/print.ts"] S3["Bridge / Remote Control
bridge/*"] S4["Remote Session Viewer
remote/*"] end E2 --> S1 E2 --> S2 E1 --> S3 E2 --> S4 subgraph UI["Terminal UI Layer"] UI1["src/ink/*"] UI2["components/*"] UI3["state/AppStateStore.ts"] end S1 --> UI1 S1 --> UI2 S1 --> UI3 subgraph Core["Conversation Core"] C1["QueryEngine.ts"] C2["query.ts"] C3["context.ts"] C4["constants/prompts + system prompt assembly"] end S1 --> C1 S2 --> C1 C1 --> C2 C1 --> C3 C1 --> C4 subgraph Exec["Execution Plane"] T1["Tool.ts / tools.ts"] T2["services/tools/*"] T3["tools/*"] T4["tasks/*"] T5["tools/AgentTool/*"] end C2 --> T2 T2 --> T1 T2 --> T3 T3 --> T4 T3 --> T5 T5 --> C2 subgraph Integrations["Integrations & Services"] I1["services/api/*"] I2["services/mcp/*"] I3["services/lsp/*"] I4["services/analytics/*"] I5["remoteManagedSettings / policyLimits / settingsSync"] I6["sessionStorage / memory / CLAUDE.md"] end C2 --> I1 T3 --> I2 S1 --> I3 E2 --> I4 E2 --> I5 C1 --> I6

纯文本分层图

Shell / SDK / Remote caller
 -> entrypoints/cli.tsx
 -> main.tsx
 -> init.ts + setup.ts
 -> REPL (interactive) / print.ts (headless) / bridge / remote
 -> QueryEngine + query loop
 -> Claude API stream
 -> Tool orchestration
 -> local tools
 -> MCP tools/resources
 -> shell/file tools
 -> AgentTool / subagent
 -> remote/background tasks
 -> session persistence / telemetry / memory / policy

3. 源码分层

按目录统计，源码最重的部分不是“入口”而是“能力面”：

目录	文件数（近似）	含义
`utils`	567	共用基础设施、状态操作、IO、git、session、权限、模型工具
`components`	390	终端 UI 组件
`commands`	209	slash command / 子命令体系
`tools`	190	供模型调用的工具实现
`services`	133	API、MCP、LSP、analytics、compact、memory 等服务
`hooks`	104	交互与生命周期 hook
`ink`	98	自研终端渲染层

这说明它本质上是一个宿主型应用：入口薄，运行时能力厚。

4. 启动架构

4.1 第一层入口：`src/entrypoints/cli.tsx`

这一层的职责是：

提供超轻量 fast path，例如 --version
在真正加载大模块前分流特殊模式
通过动态 import 避免不必要的模块求值

可理解为一个 boot dispatcher。

4.2 第二层入口：`src/main.tsx`

这一层是真正的主控器，职责非常重：

初始化 warning handler、信号处理
处理深链路、direct connect、ssh、assistant、bridge 等特殊入口
用 Commander 建立完整 CLI 语义
在 preAction 中统一调用 init()
将运行模式导向 REPL、print、bridge、remote 等不同表面

因此 main.tsx 是运行时编排器，不是单纯参数解析器。

4.3 初始化：`src/entrypoints/init.ts`

init() 负责做“可信但尽量轻”的全局初始化：

启用配置系统
应用安全环境变量
配置 mTLS / proxy / preconnect
初始化 telemetry、remote managed settings、policy limits
注册清理逻辑

这层的设计目标很明确：把重初始化尽量摊薄到异步和缓存里，但又保证最关键的运行前提先就绪。

4.4 会话级准备：`src/setup.ts`

setup() 偏向“当前会话环境落地”，包括：

cwd 与项目根建立
hook snapshot 与 file watcher 初始化
worktree / tmux 建立
session memory、release notes、terminal backup 恢复

所以：

init.ts 更像进程级初始化
setup.ts 更像会话级初始化

5. 交互表面架构

Claude Code 有多个运行表面，但复用同一套内核。

5.1 交互式模式

主链路：

main.tsx -> createRoot() -> replLauncher.tsx -> components/App -> screens/REPL.tsx

其中：

src/ink.ts 与 src/ink/root.ts 提供自研终端 React 渲染根
src/screens/REPL.tsx 是主交互容器
src/state/AppStateStore.ts 管理 UI、MCP、任务、bridge、remote viewer 等状态

这套设计说明 Claude Code 不是“命令执行器包一层 UI”，而是先有终端应用框架，再承载 Agent。

5.2 Headless / SDK 模式

主链路：

main.tsx -> cli/print.ts -> QueryEngine.ask()

这一层负责：

结构化输入输出
stream-json / text / json 输出协议
SDK control 消息
权限请求桥接
headless 的会话恢复与插件/MCP 装配

因此 print 模式本质上是无 UI 的协议适配层。

5.3 Bridge / Remote / Viewer

bridge/*：本机作为远端可控执行环境
remote/*：连接远端 session，接收 SDK 消息和权限请求
server/*：direct connect / session creation 一类能力

这是 Claude Code 向“本地 CLI”之外扩展的关键：它开始具备双向远程会话宿主能力。

6. 会话内核：`QueryEngine` + `query()`

这是整个系统最核心的层。

6.1 `QueryEngine.ts`

QueryEngine 持有一段会话生命周期内的核心状态：

mutableMessages
readFileState
permission denials
usage 累计
abort controller
discovered skills / memory path 等 turn/session 级上下文

它的角色是面向会话的外观层（session facade）。

6.2 `query.ts`

query() 才是真正的 turn loop：

拼接系统提示与上下文
处理 message normalization
发起 Claude API 请求
处理 streaming 消息
提取 tool_use
执行工具
将 tool_result 回注消息流
继续下一轮直到终止

它的角色是面向单次 agentic turn 的状态机。

6.3 共享内核的意义

REPL 和 print/SDK 都复用这套内核，意味着架构上做了明确分离：

上层负责“人机交互/协议”
下层负责“消息循环/工具回路”

这是本项目最正确的一刀。

7. 单轮执行时序图

sequenceDiagram participant User as User / SDK participant Surface as REPL or print.ts participant Engine as QueryEngine participant Loop as query() participant API as services/api/claude.ts participant Tools as services/tools/* participant Impl as tools/* / MCP / tasks User->>Surface: prompt / input event Surface->>Engine: submitMessage() / ask() Engine->>Engine: processUserInput() Engine->>Loop: query(params) Loop->>API: stream message request API-->>Loop: assistant deltas / tool_use Loop->>Tools: runTools() / StreamingToolExecutor Tools->>Impl: execute tool Impl-->>Tools: tool_result / progress Tools-->>Loop: Message updates + new context Loop->>API: next round with tool_result API-->>Loop: final assistant message Loop-->>Engine: messages + usage + terminal result Engine-->>Surface: SDKMessage / UI state updates

8. 工具平台架构

8.1 元模型：`src/Tool.ts`

这里定义了工具系统的核心抽象：

tool schema
permission context
tool use context
progress / UI 回调
app state 访问

ToolUseContext 很关键，它不是简单参数包，而是运行时能力注入容器。

8.2 工具注册：`src/tools.ts`

tools.ts 负责：

聚合所有内建工具
按 feature flag / env / policy 暴露工具
根据运行环境裁剪工具集

因此工具系统不是“扫描目录自动发现”，而是显式装配、可裁剪、可做 prompt cache 稳定控制的工具池。

8.3 工具调度：`services/tools/*`

关键模块：

toolOrchestration.ts：按并发安全性分批执行
StreamingToolExecutor.ts：边流式产生 tool_use 边执行，并维护有序产出
toolExecution.ts：单个工具执行

这里的设计很成熟：

只读 / 并发安全工具可并行
有副作用工具串行
即使并行执行，也保证结果按原始 tool_use 顺序回吐

这说明架构目标不是“最大吞吐”，而是有约束的并行。

9. 多代理与任务系统

这是 Claude Code 区别于普通 CLI Agent 的另一核心。

9.1 AgentTool

tools/AgentTool/AgentTool.tsx 是多代理入口，支持：

新子代理
指定 agent type
背景运行
worktree 隔离
remote 隔离
team / teammate 模式

它既是一个工具，也是任务系统的控制面入口。

9.2 runAgent

tools/AgentTool/runAgent.ts 做的事情包括：

组装 agent 的 system prompt
为 agent 初始化专属 MCP server
克隆 / 隔离 ToolUseContext
调用 query() 运行子代理
记录 sidechain transcript

也就是说，子代理不是一个特别的协议对象，本质上仍然是另一个 QueryEngine/query runtime。

9.3 任务系统

Task.ts + tasks/* 定义统一任务抽象，当前主要有：

local_bash
local_agent
remote_agent
in_process_teammate
dream

其中：

LocalAgentTask 管后台本地 agent 的状态、输出文件、通知、前后台切换
RemoteAgentTask 管远端 Claude.ai/CCR session 的轮询、恢复、归档
LocalShellTask 管 Bash/PowerShell 等 shell 任务

因此任务系统的作用不是“仅做 UI 展示”，而是把长生命周期执行单元从 Query 主循环中拆出来管理。

10. MCP 架构

services/mcp/client.ts 是另一个核心模块。

它负责：

连接 MCP server（stdio / SSE / streamable HTTP / websocket）
OAuth / auth 处理
拉取 tools / prompts / resources
将 MCP 工具转成本地可用 Tool
做工具结果截断、持久化、二进制落盘

MCPConnectionManager.tsx 则把连接管理嵌入到 UI 上下文。

所以 MCP 在 Claude Code 里不是附属插件，而是一级能力平面。

11. 状态架构

Claude Code 有两层状态：

11.1 进程级全局状态：`bootstrap/state.ts`

这里放的是进程级 latch 和统计：

cwd / sessionId / model / telemetry
prompt cache 相关 sticky flag
invoked skills
global counters
session lineage

这层更像process runtime registry。

11.2 UI / 会话视图状态：`state/AppStateStore.ts`

这里放的是当前交互态：

tasks
mcp clients/tools/resources
plugin state
permission context
当前 viewing agent / foregrounded task
bridge / remote viewer 状态

这层更像presentation-oriented session state。

12. 上下文与记忆架构

context.ts 暴露两类核心上下文：

getSystemContext()：git 状态、cache breaker 等系统级上下文
getUserContext()：CLAUDE.md、日期、memory 文件

这说明 Claude Code 的“记忆”首先不是向量库，而是文件化上下文 + 会话附着上下文：

CLAUDE.md
memory files
session transcript
task output sidechain

这和 IDE/代码代理场景非常一致，也降低了外部存储依赖。

13. 编译期产品线架构

build.ts 非常重要，因为它决定“最终产品到底长什么样”。

它通过：

featureFlags
MACRO.*
Bun bundler 的 feature()

做编译期裁剪。

这意味着：

源码里存在一套比公开 npm 包更大的能力面
外部版本只是该产品线上的一个裁剪结果
架构分析必须区分“源码全量能力”与“external build 默认能力”

这是理解 Claude Code 源码时最容易被忽略的一点。

14. 关键设计判断

14.1 它是单体，但不是臃肿单体

虽然文件很多，但主分层其实很清晰：

入口层
交互层
查询内核
工具执行层
集成服务层

这是一种宿主型单体（host monolith），不是业务脚本堆积。

14.2 Query loop 是绝对中心

真正的中心不是 UI、不是 commands、也不是 tools，而是：

QueryEngine -> query() -> API/tool round-trip

其它几乎都围绕这条环工作。

14.3 Tool 与 Task 是两个层次

Tool：模型可调用的能力接口
Task：长生命周期、可恢复、可后台化的执行单元

这两层分开是对的，否则后台 agent、remote session、shell job 会把 query loop 搞得非常混乱。

14.4 REPL 与 SDK 共享内核是最值钱的抽象

这让 Claude Code 同时具备：

终端产品
SDK 运行时
远端会话宿主

而不用维护三套 agent 内核。

15. 一句话总结

Claude Code 的源码可以概括为：

一个用 Bun 构建、以 query() 为中心、以 Tool/Task 为执行平面、以 REPL/SDK/Bridge 为多表面的可裁剪单体 Agent 运行时。

如果后续要继续拆专题，建议优先再写 4 篇：

QueryEngine/query 详细执行流
Tool/Task/AgentTool 三层关系
MCP 接入与权限/认证模型
REPL UI 状态机与自研 Ink 渲染层

Claude Code 系统提示词设计整理

Mon, 11 May 2026 00:00:00 +0000

目标

这份文档整理 Claude Code 在一次 query 中如何构造最终发给模型的 prompt，重点说明：

system prompt 由哪些模块组成
哪些内容其实不在 system，而是在 messages 里
CLAUDE.md、memory、git status、日期、MCP 指令分别从哪里进入
prompt cache 为什么要把 system prompt 切成静态和动态两段
本地日志默认能看到什么，不能看到什么

这里说的“最终 prompt”不是单一字符串，而是一次 API 请求中的两部分：

system blocks
messages 数组

Claude Code 的设计重点不是把所有东西硬拼成一大段文本，而是把不同来源的信息按职责分层，再在发请求前统一装配。

一、总览：最终请求是怎么拼出来的

核心链路可以概括成：

getSystemPrompt()
+ getSystemContext()
+ getUserContext()
+ 当前会话消息
 ↓
query.ts 中组装
 ↓
services/api/claude.ts 中规范化并追加前缀
 ↓
buildSystemPromptBlocks()
 ↓
anthropic.beta.messages.create(...)

更具体一点：

静态 system sections
+ 动态 system sections
+ systemContext(git status 等)
= fullSystemPrompt

userContext(claudeMd, currentDate 等)
+ 原始 messages
= messages with prepended meta context

fullSystemPrompt + normalized messages + tools
= 最终 API 请求

关键文件：

src/query.ts
src/utils/queryContext.ts
src/constants/prompts.ts
src/context.ts
src/utils/api.ts
src/services/api/claude.ts
src/constants/system.ts
src/utils/claudemd.ts
src/memdir/memdir.ts

二、最上游：先取三类基础材料

在 src/utils/queryContext.ts 里，Claude Code 会先取三类基础输入：

defaultSystemPrompt
userContext
systemContext

对应实现：

fetchSystemPromptParts() in src/utils/queryContext.ts
getSystemPrompt() in src/constants/prompts.ts
getUserContext() in src/context.ts
getSystemContext() in src/context.ts

这一步的设计很清楚：

system prompt 负责长期稳定的行为规则
systemContext 负责当前环境快照
userContext 负责以 meta message 形式注入的补充上下文

也就是说，Claude Code 并没有把所有上下文都塞进 system prompt，而是故意拆成了两条通道。

三、system prompt 的主体：`getSystemPrompt()`

src/constants/prompts.ts 是 system prompt 的主装配器。

3.1 静态部分

在 getSystemPrompt() 的返回结果里，前半段是静态内容，也就是跨 turn 尽量稳定的部分。主要包含：

Intro
- 说明“你是 Claude Code，Anthropic 的官方 CLI”
- 说明核心任务是帮助用户完成软件工程任务
# System
- 用户看到的文本规则
- 工具权限模型
- 如何对待 <system-reminder>
- 如何对待外部工具返回数据
- hook 机制
- 上下文自动压缩
# Doing tasks
- 软件工程任务的默认行为规范
- 不要过度设计
- 优先修改已有文件
- 安全要求
- 不要虚报验证结果
- 遇到 Claude Code 本身的问题时如何建议用户 /issue 或 /share
# Executing actions with care
- 哪些操作需要谨慎
- 哪些操作风险大
- 为什么不能随便用破坏性命令
# Using your tools
- 优先用专用工具
- 何时用 Bash
- 何时用 Agent
- 何时用 Skill
# Tone and style
- 输出风格
- 引用代码位置格式
- 工具调用前不要写冒号
# Communicating with the user 或 # Output efficiency
- 用户可见文本的写法
- 什么时候要给进度更新
- 简洁但不能丢关键信息

这些静态 sections 主要在 src/constants/prompts.ts 里定义：

getSimpleIntroSection()
getSimpleSystemSection()
getSimpleDoingTasksSection()
getActionsSection()
getUsingYourToolsSection()
getSimpleToneAndStyleSection()
getOutputEfficiencySection()

3.2 动态部分

在静态部分后面，Claude Code 会追加动态 sections。动态 sections 的定义在 src/constants/prompts.ts 的 dynamicSections 数组。

这部分通常包括：

session_guidance
- 当前会话下的工具使用建议
- 例如什么时候应该让用户自己跑 ! command
- 什么时候该用 Agent 或 Explore
- skills 如何触发
memory
- memory 机制说明
- 告诉模型 persistent memory 在哪里
- 哪些记忆该存，哪些不该存
- MEMORY.md 如何做索引
ant_model_override
- Anthropic 内部场景下的额外 suffix
- external 构建通常不会有
env_info_simple
- 当前环境信息
- working directory、是否 git repo、平台、shell、OS、模型信息、知识截止时间
language
- 用户配置了语言偏好时追加
output_style
- 用户配置了自定义输出风格时追加
mcp_instructions
- 各个 MCP server 自己提供的 instructions
scratchpad
- scratchpad 相关指令
frc
- function result clearing 相关指令
summarize_tool_results
- 工具结果摘要策略
feature flag 控制的额外 section
- numeric length anchors
- token budget
- brief
- proactive 相关能力

这部分的意义是：

静态 prompt 负责通用行为原则
动态 prompt 负责当前会话和当前环境的变化面

这样才能兼顾稳定性和灵活性。

四、`CLI sysprompt prefix` 其实只有一句话

在 src/services/api/claude.ts 中，真正发送请求前，还会把 getCLISyspromptPrefix() 的结果插到最前面。

这个前缀定义在 src/constants/system.ts。

它一共有 3 个候选值：

默认交互式 CLI

You are Claude Code, Anthropic's official CLI for Claude.

非交互式，并且带 appendSystemPrompt

You are Claude Code, Anthropic's official CLI for Claude, running within the Claude Agent SDK.

非交互式，但没有 appendSystemPrompt

You are a Claude agent, built on Anthropic's Claude Agent SDK.

所以 CLI sysprompt prefix 不是一大段规则，它只是一个“身份和运行形态声明”。

它不包含：

tools 说明
git status
CLAUDE.md
日期
memory 内容

这些都来自别的层。

五、真正发出前，system prompt 还会再包两层

在 src/services/api/claude.ts 中，system prompt 最后会被组装成：

getAttributionHeader(fingerprint)
getCLISyspromptPrefix(...)
...systemPrompt
某些可选附加指令
- advisor instructions
- chrome tool search instructions

所以最终的 systemPrompt 不是只有 prompts.ts 出来的正文，还多了两层外围包装：

5.1 Attribution header

这部分来自 src/constants/system.ts 的 getAttributionHeader()。

它大概长这样：

x-anthropic-billing-header: cc_version=...; cc_entrypoint=...;

它更像一个通过 request body 携带的内部标记，而不是面向模型语义的提示词内容。

5.2 CLI prefix

就是上一节说的那句身份声明。

这个设计说明 Claude Code 并不把“身份”硬编码在正文 sections 里，而是作为独立前缀插入，方便缓存分层和后续拆分。

六、systemContext：git status 这类信息其实走 system 通道

src/context.ts 里的 getSystemContext() 会构造 systemContext。

默认最重要的一项是：

gitStatus

其内容包括：

当前 branch
main branch
git user
工作区 status snapshot
最近 commits

注意这里强调的是“snapshot at the start of the conversation”，也就是一个会话开始时的快照，不会自动更新。

在 src/query.ts 里，Claude Code 会这样做：

const fullSystemPrompt = asSystemPrompt(
 appendSystemContext(systemPrompt, systemContext),
)

而 appendSystemContext() 在 src/utils/api.ts 里的实现非常直接：

把 systemContext 的 key/value 直接拼成文本
追加到 system prompt 末尾

所以像下面这些东西，其实属于 system prompt 的一部分：

gitStatus
某些 cache breaker 注入

这就是为什么你在 prompt 结构里应该把 git status 视为 system 层附加上下文，而不是 user message。

七、userContext：CLAUDE.md 和日期其实走首条 meta user message

与 systemContext 不同，userContext 不是 append 到 system prompt，而是通过 prependUserContext() 插入到 messages 最前面。

实现位于 src/utils/api.ts。

它会构造一条 meta user message，内容格式类似：

<system-reminder>
As you answer the user's questions, you can use the following context:
# claudeMd
...
# currentDate
...
IMPORTANT: this context may or may not be relevant...
</system-reminder>

也就是说：

claudeMd 不在 system prompt 里
currentDate 也不在 system prompt 里
它们在 messages 数组里，而且是第 0 条 meta user message

这个设计非常重要，因为它说明 Claude Code 区分了两种东西：

system-level behavior rules
conversation-level contextual hints

CLAUDE.md 更接近第二种。

八、`claudeMd` 的真实来源不是一个文件，而是一组文件汇总

src/utils/claudemd.ts 负责加载用户和项目指令文件。

它的加载层级大致是：

managed memory
- 例如 /etc/claude-code/CLAUDE.md
user memory
- ~/.claude/CLAUDE.md
project memory
- 项目根目录及向上路径中的 CLAUDE.md
- .claude/CLAUDE.md
- .claude/rules/*.md
local memory
- CLAUDE.local.md

而且支持 @include，所以一份 CLAUDE.md 还可能再引入别的文本文件。

最后这些内容会被 getClaudeMds(...) 汇总成一大段 claudeMd 字符串，进入 userContext。

所以从设计上看：

CLAUDE.md 是用户/项目定制规则层
它不是底层 runtime system prompt 模板本身
它是通过“上下文注入”覆盖默认行为的

这也解释了为什么代码里专门有一句：

IMPORTANT: These instructions OVERRIDE any default behavior...

Claude Code 想让模型把这些文件视为高优先级补充规则。

九、memory prompt 和 CLAUDE.md 不是一回事

源码里这两个概念很容易混，但职责完全不同。

9.1 `loadMemoryPrompt()`

这个函数在 src/memdir/memdir.ts。

它生成的是“记忆系统使用规则”，比如：

memory 存放目录在哪里
有哪些 memory type
哪些该存、哪些不该存
怎么写 frontmatter
怎么维护 MEMORY.md

这部分进入 system prompt 的动态 section。

9.2 `claudeMd`

这个来自 src/utils/claudemd.ts，是实际的用户和项目规则正文。

它不是 memory 机制说明，而是具体内容，比如：

项目协作偏好
输出语言要求
操作规范
用户自己的工作方式

这部分进入首条 meta user message。

简化说：

memory prompt = “如何使用记忆系统”
claudeMd = “用户和项目到底要求你做什么”

十、messages 不是原样直发，还会再规范化

到了 src/services/api/claude.ts，Claude Code 会对消息流做进一步处理。

主要步骤有：

normalizeMessagesForAPI(messages, filteredTools)
- 统一 message 结构
- 规范 tool use/tool result 格式
针对 model 能力做后处理
- 不支持 tool search 的模型会 strip 掉对应字段
ensureToolResultPairing(messagesForAPI)
- 修复 tool_use / tool_result 不成对的问题
strip 掉不兼容 blocks
- 比如 advisor block 没开 beta 时去掉
控制媒体数量
- 超过上限时裁剪旧媒体
某些场景下注入额外 meta user message
- 例如 <available-deferred-tools>

这说明“最终 messages”也不是单纯的用户对话历史，而是一个经过修正、注入、约束后的规范化消息流。

十一、prompt cache 的关键设计：静态和动态边界

Claude Code 在 prompt 设计上有一个非常重要的优化点：

SYSTEM_PROMPT_DYNAMIC_BOUNDARY

定义在 src/constants/prompts.ts。

它的作用是把 system prompt 分成：

静态部分
动态部分

然后 splitSysPromptPrefix() in src/utils/api.ts 会据此拆分缓存作用域：

attribution header: 不缓存或特殊处理
CLI prefix: org scope
静态正文: global scope
动态正文: 不走全局缓存

这背后的设计目的很明确：

通用规则尽量跨 session 复用缓存
会变化的内容，如 env、language、MCP、memory prompt 等，单独挂在后面
避免因为一个小变动把整个大 system prompt 的 cache key 打碎

这也是为什么 Claude Code 的 system prompt 不是“随便 join 一下字符串”，而是显式建模成 string[] blocks 再拆。

十二、从模型视角看，最终请求结构可以近似理解为这样

SYSTEM:
1. x-anthropic-billing-header ...
2. You are Claude Code, Anthropic's official CLI for Claude.
3. 静态 system sections
 - intro
 - system
 - doing tasks
 - actions
 - using tools
 - tone/style
 - output efficiency
4. 动态 system sections
 - session guidance
 - memory prompt
 - env info
 - language/output style
 - MCP instructions
 - scratchpad / summarize tool results / frc / brief / token budget 等
5. systemContext
 - gitStatus
 - cacheBreaker(如果有)

MESSAGES:
0. prependUserContext 生成的 meta user message
 - claudeMd
 - currentDate
1. 额外 meta user message
 - 例如 available-deferred-tools
2. 用户真实输入
3. 历史 assistant messages
4. tool use / tool result messages

这个结构基本就是 Claude Code prompt 设计的本质。

十三、为什么要把 CLAUDE.md 放在 userContext，而不是 system prompt 里

从设计上看，这么做有几个好处。

13.1 减少基础 system prompt 波动

如果把 CLAUDE.md 直接拼到 system prompt 里，那么每个项目、每个用户、每次规则变化都会直接打碎 system cache。

放到 prependUserContext() 里，可以把“默认系统行为模板”和“用户项目自定义说明”分层。

13.2 语义更准确

Claude Code 自带规则是产品级 runtime contract。

而 CLAUDE.md 更像“当前工作上下文中的高优先级补充说明”。

把它包装成 <system-reminder> user meta message，语义上更接近“这里有额外上下文，请按需使用，但优先级很高”。

13.3 更适合项目级定制

CLAUDE.md 本来就是用户和项目自定义层，天然更接近 conversation context，而不是产品内核提示词模板。

十四、本地日志能看到哪一层

从源码看，默认本地能看到的是 transcript，不是完整最终请求。

14.1 默认 transcript

src/utils/sessionStorage.ts 会把会话记录写到：

~/.claude/projects/<project-slug>/<sessionId>.jsonl

这里通常能看到：

user message
assistant message
tool_use
tool_result
attachment
一些 metadata

但通常看不到：

完整 system prompt blocks
完整 tools schema
最终 anthropic.beta.messages.create(...) 的原始 request body

14.2 history

~/.claude/history.jsonl 主要是输入历史，不是完整 prompt。

14.3 dump-prompts

真正会把 request body 落盘的是：

src/services/api/dumpPrompts.ts
输出目录：~/.claude/dump-prompts/<sessionOrAgentId>.jsonl

这里会写：

init 记录：system、tools、metadata
message 记录：新 user messages
response 记录：模型响应

但这条路径默认有条件，external 用户通常不开。

所以默认本地日志只够看“对话和工具轨迹”，不够看“完整最终 prompt”。

十五、这一套设计的几个核心取舍

15.1 不是单字符串，而是分层 block 设计

好处：

方便缓存
方便附加前缀
方便只替换动态部分
方便做不同 cache scope

15.2 把 runtime 行为规则和项目上下文分离

产品内核规则进 system
项目/用户规则进 userContext
环境快照进 systemContext

这让每一层的职责很清楚。

15.3 把可缓存部分和高波动部分分离

这是 Claude Code prompt engineering 里最工程化的一点。

重点不是“提示词写得多聪明”，而是“提示词结构怎么减少 token churn”。

15.4 把 message 流也当成 prompt 设计的一部分

Claude Code 没有把 prompt 只理解成 system 文本。

它同样重视：

哪些 meta message 要 prepend
工具消息怎样规范化
哪些内容该留在 messages 层而不是塞进 system

这个视角比“只研究 system prompt 正文”更接近真实实现。

十六、结论

Claude Code 的最终 prompt 设计，可以归纳成一句话：

用静态 system 模板定义默认行为，用动态 system sections 注入当前能力和环境，用 systemContext 追加运行时快照，用首条 meta user message 注入 CLAUDE.md 和日期，再把整个消息流规范化后发送给模型。

如果只盯着某一段 system 文本，很容易误判实际结构。真正重要的是这四层：

CLI prefix 和 attribution header
system prompt sections
systemContext
prepended userContext + normalized messages

Claude Code 的 prompt 设计本质上是一个分层上下文装配系统，不只是一个长 prompt 模板。

附：最值得读的源码入口

如果后续还要继续深入，优先看这几个入口：

src/query.ts
- 看 query 时如何组装 fullSystemPrompt 和 messages
src/constants/prompts.ts
- 看 system prompt 的静态和动态 sections
src/context.ts
- 看 getUserContext() 和 getSystemContext() 的边界
src/utils/api.ts
- 看 appendSystemContext()、prependUserContext()、splitSysPromptPrefix()
src/services/api/claude.ts
- 看最终发送 API 前的规范化和包装
src/utils/claudemd.ts
- 看 CLAUDE.md 汇总逻辑
src/memdir/memdir.ts
- 看 memory prompt 的生成逻辑

Claude Code 缓存设计架构文档

Mon, 11 May 2026 00:00:00 +0000

源码依据：/Users/jishihe/work/civil-engineering-cloud-claude-code-source-v2.1.88/01-claude-code-source-crack/claude-code-source/src 所有行号与路径都指向该目录。

1. 背景与问题域

LLM Agent 的每一轮请求都要把 system + tools + 完整消息历史 再发给模型。随着对话变长，延迟与成本线性增长。Anthropic 官方提供了 prompt caching（cache_control: { type: 'ephemeral' }）：服务端按请求前缀的字节比对命中缓存，5min 或 1h TTL 内复用已经预填（prefill）过的 KV，延迟下降一个数量级。

能用好这个能力的前提是：“下一次请求的前缀字节必须完全等于上一次”。Claude Code 的缓存设计整个就是围绕这一条约束来组织的。

设计目标：

每轮请求尽可能多地命中服务端缓存（cache_read_input_tokens 最大化）。
系统 prompt 的动态变化（时间、cwd、git、CLAUDE.md）不能污染可缓存前缀。
工具集在会话内字节稳定（GrowthBook flag 翻转不能引起 tools 漂移）。
长对话能在不丢失语义的前提下"回收"老的 tool_result 负载。
当缓存意外失效时，能自动定位并报告根因。

2. 顶层架构：请求的三层前缀结构

一个发给 Anthropic API 的请求被切成三段，每段各自管理缓存：

┌─────────────────────────────────────────────────────────────┐
│ system: TextBlockParam[] │
│ ├── [0] attribution header (cache_scope=null) │
│ ├── [1] 静态指令 + 工具说明 (cache_scope=global) │ ← 块边界 cache_control
│ └── [2] 动态上下文 (时间/cwd/git) (cache_scope=null) │
├─────────────────────────────────────────────────────────────┤
│ tools: BetaToolUnion[] │
│ ├── tool_1 │
│ ├── tool_2 │
│ └── tool_N (ttl=1h, scope=org) │ ← 最后一个 tool 上的 cache_control
├─────────────────────────────────────────────────────────────┤
│ messages: MessageParam[] │
│ ├── msg_1 (user) │
│ ├── msg_2 (assistant) │
│ ├── ... ← 旧 tool_result 携带 cache_reference │
│ └── msg_N (user) 最后一个 content block (ttl=1h) │ ← 全局唯一 cache_control 断点
└─────────────────────────────────────────────────────────────┘

关键约束：一次请求里 cache_control 断点 ≤ 4（API 上限），且最后一个断点必须落在 messages 的最后一条——只有这样，下一轮新追加的内容才会被写入"可读前缀"里。

3. 分层实现

3.1 System Prompt：静态 / 动态边界

文件：utils/api.ts:321 splitSysPromptPrefix() 常量：constants/prompts.ts:114 SYSTEM_PROMPT_DYNAMIC_BOUNDARY = '__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'

system prompt 被设计成字符串数组，不是单个大字符串。数组中插入一个哨兵字符串 __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ 作为"静态 | 动态"的分水岭。

// constants/prompts.ts: 拼装 system prompt
[
 BILLING_HEADER,
 CLI_SYSPROMPT_PREFIX, // 包含版本、identity
 ...STATIC_INSTRUCTIONS, // 工作方式、Tool usage 规范
 ...TOOL_USAGE_DESCRIPTIONS,
 SYSTEM_PROMPT_DYNAMIC_BOUNDARY, // <-- 边界
 ...SESSION_SPECIFIC_GUIDANCE, // 依赖 isNonInteractive / hasSkills 等运行期标志
 CWD_AND_TIME,
 CLAUDE_MD_CONTENT,
]

切分规则（splitSysPromptPrefix 输出 3~4 个 TextBlockParam）：

段	cacheScope	合并规则
attribution header	`null`	不打 cache_control
CLI 前缀	`null` 或 `org`	账单级别的小变量
边界之前的所有静态段	`'global'`	合并成一个 TextBlock，所有组织共享同一个服务端缓存条目
边界之后	`null`	不缓存

关键注释（constants/prompts.ts:343-350）：边界之后的每个条件开关都会"让 Blake2b 前缀 hash 翻倍（2^N 种变体）"，所以凡是运行期才确定的文案必须放到边界之后。

MCP 降级路径：如果当前会话接了 MCP 工具（tool 集本身就是组织特定的），splitSysPromptPrefix 被传入 skipGlobalCacheForSystemPrompt=true，三段全部降到 org 作用域，不再走 global。

3.2 Tools：会话内字节稳定 + 末尾断点

文件：utils/api.ts:119 toolToAPISchema()、utils/toolSchemaCache.ts

每个 tool schema 的生成分两步：

Base schema 会话级缓存（toolSchemaCache）：name / description / input_schema / strict / eager_input_streaming 这些不变量计算一次就缓存。
- Cache key 通常是 tool.name；MCP / StructuredOutput 工具带 inputJSONSchema，key 改用 ${name}:${stringify(schema)} 以避免冲突。
- 动机：避免 GrowthBook flag (tengu_tool_pear、tengu_fgts) 或 tool.prompt() 本身的输出抖动把 tools 字节搅乱。
Per-request overlay：在 base schema 上叠加本次请求的 defer_loading 和 cache_control——通过显式字段拷贝，不污染 base。

type BetaToolWithExtras = BetaTool & {
 strict?: boolean
 defer_loading?: boolean
 cache_control?: {
 type: 'ephemeral'
 scope?: 'global' | 'org'
 ttl?: '5m' | '1h'
 }
}

断点位置：tools 数组上通常只给最后一个 tool 挂 cache_control，整个 tools 段成为可缓存前缀的一部分。

3.3 Messages：全局唯一断点位于最后一条

文件：services/api/claude.ts:3063 addCacheBreakpoints()

const markerIndex = skipCacheWrite ? messages.length - 2 : messages.length - 1
const result = messages.map((msg, index) => {
 const addCache = index === markerIndex
 ...
})

为什么只打一个（claude.ts:3078-3088 原注释）：

Exactly one message-level cache_control marker per request. Mycro’s turn-to-turn eviction frees local-attention KV pages at any cached prefix position NOT in cache_store_int_token_boundaries. With two markers the second-to-last position is protected and its locals survive an extra turn even though nothing will ever resume from there — with one marker they’re freed immediately.

断点只打在最后一条消息的最后一个 content block 上：

userMessageToMessageParam (claude.ts:588) 和 assistantMessageToMessageParam (claude.ts:633) 都只给 content[length-1] 挂 cache_control。
Assistant 消息会跳过 thinking 和 redacted_thinking 块（它们不能带 cache_control）。

skipCacheWrite 模式（fire-and-forget 子代理）：marker 挪到倒数第二条——这样写操作落在"已经存在的前缀边界"上，服务端去重为 no-op 合并，子代理不会把自己的尾巴写进 KV cache 污染主线程。

3.4 Tool Result：cache_reference 的引用机制

文件：services/api/claude.ts:3164-3207

在 cache 断点之前的所有 tool_result 块，会被追加一个 cache_reference 字段：

msg.content[j] = Object.assign({}, block, {
 cache_reference: block.tool_use_id,
})

这让服务端可以：

按 tool_use_id 从缓存中取回之前那次的 tool_result 完整内容；
客户端下一轮可以把该 tool_result 的 content 清空（只留引用），大幅缩小 request body；
配合 microcompact 做"负载回收但保留语义"。

4. 横切关注点

4.1 `getCacheControl()`：统一的 cache_control 工厂

文件：services/api/claude.ts:358

export function getCacheControl({ scope, querySource } = {}) {
 return {
 type: 'ephemeral',
 ...(should1hCacheTTL(querySource) && { ttl: '1h' }),
 ...(scope === 'global' && { scope }),
 }
}

所有地方需要 cache_control 的地方都走这一个工厂，保证 TTL / scope 的取值在一次请求内一致——一旦不一致，服务端会把它当成新的缓存条目。

4.2 TTL 决策：`should1hCacheTTL()` 的会话级 latch

文件：services/api/claude.ts:393

决定 1h 还是 5m 的逻辑包含：

Bedrock 第三方：通过 env ENABLE_PROMPT_CACHING_1H_BEDROCK 自助开启。
第一方：只对 Anthropic 员工账号或订阅用户开启，且不在 overage 状态。
GrowthBook allowlist：按 querySource 前缀匹配（如 repl_main_thread*、sdk、agent:*）。

关键设计：这两个判断结果在 session 启动时 latch 到 bootstrap state (getPromptCache1hEligible, getPromptCache1hAllowlist)。原因：

Latch eligibility in bootstrap state for session stability — prevents mid-session overage flips from changing the cache_control TTL, which would bust the server-side prompt cache (~20K tokens per flip).

即：同一会话的 TTL 值必须不变，否则每一次翻转都是一次 cache break。

4.3 缓存失效检测：Phase 1 记录 / Phase 2 诊断

文件：services/api/promptCacheBreakDetection.ts

一个独立的诊断子系统，分两阶段工作：

Phase 1 recordPromptState() (L247)：每次 API 调用之前，把本次的状态指纹化：

systemHash = 剥离 cache_control 后的 system 字节 hash
toolsHash = 剥离 cache_control 后的 tools 字节 hash
cacheControlHash = 只保留 cache_control 字段的 hash（用于检测 scope/TTL 翻转）
perToolHashes = 每个 tool 的独立 hash（解释"77% 的 tool break 来自 schema 描述漂移"）
以及 model / fastMode / betas / autoMode / overage / effort / extraBody 等

与上一次对比，差异写入 pendingChanges 暂存。

Phase 2 checkResponseForCacheBreak() (L437)：响应返回后，读 cache_read_input_tokens：

若 cacheReadTokens >= prevCacheRead * 0.95 或绝对下跌 < 2000，不视作 break（正常抖动）。
否则把 pending changes 翻译成人类可读原因，比如：
- model changed (sonnet-4-6 → opus-4-7)
- tools changed (+1/-0 tools)
- system prompt changed (+120 chars)
- possible 5min TTL expiry (prompt unchanged)
写 tengu_prompt_cache_break 事件 + cache-break-xxxx.diff 供工程师排查。

跟踪键隔离：getTrackingKey() 按 querySource + agentId 分桶，子代理并发不会相互污染。容量 MAX_TRACKED_SOURCES=10，LRU 淘汰。

4.4 上下文压缩：microcompact & cache_edits

文件：services/compact/microCompact.ts、services/compact/compact.ts

两种触发场景：

时间触发（timeBasedMicrocompact, L402）：距离上一次主循环助理消息超过阈值（默认 5min），主动压缩老的 tool_result。
Token 触发：接近 context 上限时触发。

压缩动作：

扫描所有 tool_result 块，按 COMPACTABLE_TOOLS 白名单筛选。
保留最近 keepRecent 条完整内容，更早的：
- 将本地 content 清空或置为简短摘要；
- 在最后一条 user message 里插入 cache_edits 块，声明 { type: 'delete', cache_reference: <tool_use_id> }；
- 服务端按 reference 从缓存读取原文，但本地不再持有长文本。
这些 cache_edits 被 pin 到 pinnedEdits[]，下次请求会再次在同一位置插入，保证服务端视图一致。
notifyCacheDeletion() 告知 cache break 检测器"下一次 cache_read 下跌是预期的"，避免误报。

compact vs microcompact：

microcompact：只动 tool_result 负载，保留消息结构，不触发额外 LLM 调用。
全量 compact：触发一个 LLM 调用总结整段历史，用总结替换历史消息；之后调用 notifyCompaction() 重置 cache baseline。

5. 端到端请求装配流程

用户输入
↓
构造 messages (追加 user turn)
↓
┌────────────────────────────┐
│ recordPromptState() │ Phase 1: 状态指纹化
│ - hash system / tools ... │
│ - diff vs previous state │
└────────────────────────────┘
↓
timeBasedMicrocompact() 检查是否需要压缩老 tool_result
↓
┌────────────────────────────────────────────────┐
│ buildSystemPromptBlocks(systemPrompt) │
│ → splitSysPromptPrefix() │
│ → 3~4 个 TextBlockParam │
│ → 静态段挂 cache_control scope=global │
├────────────────────────────────────────────────┤
│ getTools() → toolToAPISchema(每个) │
│ → toolSchemaCache 读/写 │
│ → 最后一个 tool 挂 cache_control │
├────────────────────────────────────────────────┤
│ addCacheBreakpoints(messages) │
│ → 最后一条消息的最后一个 block 挂 marker │
│ → 旧 tool_result 挂 cache_reference │
│ → 插入 pinnedEdits (如有) │
└────────────────────────────────────────────────┘
↓
POST /v1/messages
↓
响应 usage: { cache_creation_input_tokens, cache_read_input_tokens, ... }
↓
┌────────────────────────────┐
│ checkResponseForCacheBreak │ Phase 2: 用 pendingChanges 解释意外下跌
└────────────────────────────┘

6. 设计原则小结

字节稳定优先：任何会让同一会话 tools/system 字节变化的机制（feature flag、schema 重生成）都要被冻结在 session boot 时。
静态与动态分离：高频变化的值（时间、cwd、git）必须位于所有 cache 断点之后；需要随时间变化但仍想缓存的值（effort、TTL 资格）必须 latch。
单一断点在末尾：不贪多断点，让"新内容"恰好增量写入末尾。
引用替代重传：长 tool_result 用 cache_reference，让服务端缓存成为内容存储。
可观测即正确：每一次缓存未命中都要有自动归因，否则你不知道什么时候悄悄退化了。

7. 源码索引表

主题	文件	关键位置
system prompt 切分与 global scope	`utils/api.ts`	`splitSysPromptPrefix` L321
动态边界哨兵	`constants/prompts.ts`	`SYSTEM_PROMPT_DYNAMIC_BOUNDARY` L114
session-specific 指引（必须在边界后）	`constants/prompts.ts`	`getSessionSpecificGuidanceSection` L352
tool schema 组装 + cache 覆盖	`utils/api.ts`	`toolToAPISchema` L119
tool schema 会话级缓存	`utils/toolSchemaCache.ts`	—
`getCacheControl` 工厂	`services/api/claude.ts`	L358
TTL 资格 latch	`services/api/claude.ts`	`should1hCacheTTL` L393
user/assistant 消息挂 cache_control	`services/api/claude.ts`	L588-674
唯一 message-level marker	`services/api/claude.ts`	`addCacheBreakpoints` L3063-3106
tool_result 加 cache_reference	`services/api/claude.ts`	L3164-3207
构建 system blocks（请求时）	`services/api/claude.ts`	`buildSystemPromptBlocks` L3213
缓存失效检测 Phase 1	`services/api/promptCacheBreakDetection.ts`	`recordPromptState` L247
缓存失效检测 Phase 2	`services/api/promptCacheBreakDetection.ts`	`checkResponseForCacheBreak` L437
压缩后重置 baseline	`services/api/promptCacheBreakDetection.ts`	`notifyCompaction` L689
时间触发 microcompact	`services/compact/microCompact.ts`	`timeBasedMicrocompact` L402
基于 cache_edits 的 microcompact	`services/compact/microCompact.ts`	L253, L296
compact 后清理	`services/compact/postCompactCleanup.ts`	—

8. 可以借鉴到自建 Agent 的四条最小规则

把 system prompt 拆成"静态段 + 动态段"两个 TextBlock，仅给静态段挂 cache_control: { type: 'ephemeral', ttl: '1h' }。
tools 数组的最后一个工具挂一个 cache_control，让整段 tools 跟在 system 静态段之后形成可缓存前缀。
每次请求只在 messages[-1] 的最后一个 content block 上打一个 cache_control；旧消息保持原样，不要修改字节。
每次请求后打印 cache_read_input_tokens / cache_creation_input_tokens；若 cache_read 连续两次为 0 或骤降，立即比对本次 vs 上次 request 的 json.dumps(system) / json.dumps(tools) 差异，就能定位到具体哪个字段漂了。

9. 如何验证本文档对应的实现行为

阅读 services/api/claude.ts:3063-3106 确认 markerIndex 逻辑。
阅读 utils/api.ts:321-435 确认三种切分模式。
运行 Claude Code 并开启 --debug，观察 [PROMPT CACHE BREAK] 日志与 cache-break-*.diff 产物。
用 tengu_api_success 事件里的 cache_read_input_tokens / cache_creation_input_tokens 验证稳态下 read/create 比。

Durable Run 作业化迁移方案

Mon, 11 May 2026 00:00:00 +0000

Summary

把当前“HTTP 请求内跑 agent + SSE 仅负责附着输出”的模型，改成“后台 durable job 驱动执行，HTTP 只负责创建 run、附着流、暂停/恢复/注入消息”。

目标效果：

浏览器断开后，run 继续执行，不依赖原始请求协程存活。
任意客户端可通过 run_id 重新附着同一个执行中的 run。
服务重启后，未完成 run 可被 worker 扫描并恢复或标记失败。
当前 ProjectDraft / ProjectTurn / WorkspaceRunState / SSE buffer 继续保留，但职责更清晰。

默认选择：先做“队列作业化 durable run”，不直接引入外部 workflow 引擎。

Key Changes

1. 抽出 Run 领域模型，停止让 chat.py 直接承载执行状态机

新增一个明确的 ChatRun 持久化对象，职责是描述一次 agent 执行本身，而不是复用 SSE buffer 或 turn payload 隐式表达。

建议新增表：

chat_runs
核心字段：
- run_id
- project_id
- session_id
- draft_id
- turn_id
- status: queued | acquiring_lock | restoring_context | running | waiting_for_user | paused | publishing | completed | failed | cancelled
- worker_id
- lease_expires_at
- continuation_of_run_id
- last_checkpoint_seq
- last_error
- created_at / started_at / updated_at / ended_at
保留现有 ProjectTurn 作为对话与产物视图，但不要再让它兼任运行时真相来源。 ProjectTurn.assistant_message_json.resume_event_id 继续用于前端展示恢复位置，但运行恢复以 chat_runs 为准。

2. 把执行循环搬到独立 worker，不再依赖 HTTP StreamingResponse

新增后台 worker 模块，例如：

apps/api/services/chat_run_worker.py
apps/api/services/chat_run_executor.py
apps/api/services/chat_run_queue.py

职责拆分：
API 路由：
- 创建 run 记录
- 入队
- 立即返回 run_id
- SSE/轮询仅做附着和消费事件
Worker：
- 抢占 run lease
- 加载上下文
- 执行 agent loop
- 持续写 checkpoint、事件流、turn/draft 状态
- 处理暂停、用户回答、proposal apply/reject、enqueue 消息
Queue：
- 可先用 Redis list / stream + DB lease
- 不要求首版引入 Celery / Temporal / Inngest
执行入口从“POST /chat 直接跑”改为：
1. POST /projects/{id}/chat 创建 chat_run
2. 记录 ProjectTurn(status=running) 与 draft
3. 将 run_id 推入队列
4. 返回 run_id
5. 前端立刻连 /chat/stream/{run_id} 或沿用现有 /chat/resume/{run_id}

3. 定义可恢复 checkpoint，恢复执行而不只是恢复 SSE

当前已有：

WorkspaceRunState
ProjectDraft.partial_response_json
model_messages_json
RunEventBuffer

但这些还不足以在进程死掉后真正恢复执行。新增 RunCheckpoint 持久化结构，按“工具边界”保存，而不是按 token 级别保存。

建议 checkpoint 内容：
run_id
seq
phase
message_history_json
assistant_steps_json
tool_calls_json
task_plan_json
workspace_run_state_json
pending_user_interrupt_json
active_tool_name
continuation_prompt
resume_from_checkpoint_kind

checkpoint 触发点：
每次 tool result 完成后
每次进入 waiting_for_user
每次完成 queued message 注入后
publish 前
publish 完成后

不要尝试在任意 token 中间恢复。恢复语义限定为：从最近一个“已完成 tool-return 的稳定边界”继续，这和你们现有 _can_resume_from_tool_checkpoint() 思路一致，但现在要落到持久化 checkpoint，而不是只在单次请求重试里使用。

4. 重新定义 API：创建 run、附着流、控制 run

建议把接口语义改成 run-first：

POST /projects/{project_id}/chat-runs
- 创建新 run 或 continuation run
- 返回 run_id, stream_url, status
GET /projects/{project_id}/chat-runs/{run_id}/stream
- SSE 附着到运行事件
- 内部仍可复用现有 RunEventBuffer
GET /projects/{project_id}/chat-runs/{run_id}
- 查询 run 状态、当前阶段、waiting reason、saved_files
POST /projects/{project_id}/chat-runs/{run_id}/pause
POST /projects/{project_id}/chat-runs/{run_id}/resume
- 对 paused 或 waiting_for_user run 生效
POST /projects/{project_id}/chat-runs/{run_id}/input
- 统一承载 queued user message / question answer / proposal decision
- 不再分散为 continuation 请求参数和多个分支语义
现有 /chat/resume/{chat_run_id} 可以短期兼容，内部转发到新的 run stream。

5. 让 worker 具备 lease 和 crash recovery

要点：

worker 抢 run 时更新 worker_id + lease_expires_at
执行期间周期性续租
如果 worker 崩溃，lease 过期后其他 worker 可接管
接管逻辑：
- 读取最新 checkpoint
- 恢复 sandbox 连接或按 draft manifest 重建
- 从 checkpoint 指定的 continuation point 继续
如果接管时发现 checkpoint 不可恢复：
- 将 run 标记 failed
- 写 terminal 事件
- 不让 run 永远挂在 running
这一步是 durable run 的核心。没有 lease，就只是“后台任务”；有 lease + checkpoint，才是“可恢复执行”。

6. 把 sandbox 生命周期从“请求 keepalive”改成“worker keepalive”

当前 keepalive 在 chat.py 的执行循环里。迁移后改为：

worker 负责 refresh_sandbox_lifecycle
worker 在 lease 续租时顺带刷新 sandbox TTL
run 附着的 SSE 客户端不再承担任何 keepalive 责任

恢复时的 sandbox 策略：
优先 reconnect 当前 session.e2b_sandbox_id
失效时按 ProjectDraft.code_manifest_key 恢复 workspace
再执行 reconcile_sandbox_runtime
只有在 checkpoint 标记“已进入 publishing 且未完成”时，才允许重试 publish；否则只恢复到 pre-publish 状态

7. 收敛当前 chat.py 的职责

apps/api/routers/chat.py 需要逐步瘦身到三类逻辑：

request validation / auth
run creation / control / stream attach
legacy compatibility glue

从中迁出的逻辑：
agent loop
queue interrupt 注入
finalize workspace
checkpoint flush
detached drain
worker keepalive

这样 chat.py 不再是 runtime 内核，只是 transport adapter。

Test Plan

必须覆盖以下场景：

创建 run 后立即断开 SSE，worker 继续执行并最终完成。
两个客户端同时附着同一 run_id，都能看到一致事件流。
worker 进程在 tool result 后崩溃，run 被新 worker 从最近 checkpoint 接管并继续。
worker 在 text streaming 中崩溃，恢复后从最近稳定 checkpoint 继续，不重复执行已完成工具。
waiting_for_user 状态下服务重启，用户提交 answer 后 run 继续。
proposal apply / reject 在 run-first API 下仍能正确更新资源并继续执行。
sandbox 已被回收时，run 接管流程能用 draft manifest 恢复。
publish 过程中失败时，不产生重复版本，也不丢失 draft。
pause 请求到达后，run 最终进入 paused，后续 resume 可继续。
同一 project 同时只允许一个持有 lock 的活跃 run，冲突时返回明确错误。

Assumptions

首版继续使用 Redis + Postgres，不引入 Temporal / Celery / Inngest。
恢复粒度限定为“tool checkpoint 级”，不追求 token 级精确续跑。
RunEventBuffer 继续保留，职责是“事件回放与多端附着”，不是运行时真相。
ProjectDraft 继续作为 workspace 草稿真相来源；ChatRun 只表示执行状态。
首版只支持单 run 单 project lock，不做同项目多并发 agent run。

Open Agents 项目架构文档

Mon, 11 May 2026 00:00:00 +0000

1. 文档目的

本文档基于当前仓库代码，对 open-agents（代码中也大量使用 open-harness 命名）进行面向实现的架构梳理。目标不是复述 README，而是回答以下问题：

这个项目的核心分层是什么
一个会话是如何被创建、初始化 sandbox、启动 agent、持续流式返回结果的
为什么这个系统能够支持长时间运行、断线重连、sandbox 休眠恢复和自动化 GitHub 工作流
当前项目的扩展点、边界和主要风险在哪里

本文档以当前代码为准，重点覆盖：

apps/web
packages/agent
packages/sandbox
与之直接相关的数据库、GitHub/Vercel 集成、workflow 与流恢复机制

2. 系统总览

这个项目本质上不是“一个集成了 LLM 的 Next.js 聊天页”，而是一个三层系统：

Web 控制面
Durable Agent Workflow
Cloud Sandbox 执行面

代码仓库中的官方架构摘要也是这条主链路：

Web -> Agent -> Sandbox

其中最关键的设计决策是：

Agent 不直接运行在 sandbox 中
浏览器请求不直接承载 agent 的完整生命周期
Web 层负责控制、持久化和恢复
Sandbox 只是执行环境，不是控制平面

这使项目具备以下性质：

用户关闭页面后，后台任务仍可继续
浏览器连接断开后，可按 workflow run 恢复流
sandbox 可以单独休眠、恢复、快照、超时延长
agent 模型选择、工具系统、sandbox provider 可以独立演进

3. 仓库结构

这是一个使用 Bun + Turborepo 的 monorepo。

3.1 顶层结构

apps/
 web/ Next.js Web 控制面
packages/
 agent/ Agent runtime、工具系统、subagent、skills
 sandbox/ Sandbox 抽象层与 Vercel 实现
 shared/ 共享 hooks/lib
 tsconfig/ 共享 TS 配置
scripts/ 运维和辅助脚本
docs/agents/ 面向 agent 的仓库说明与架构摘要

3.2 关键包职责

`apps/web`

承担控制面职责：

用户认证
session / chat / message 持久化
会话创建与 sandbox 初始化
聊天工作流启动与流式返回
GitHub / Vercel 集成
sandbox 生命周期编排
使用统计与设置管理

`packages/agent`

承担 agent runtime 职责：

模型选择与 provider 默认配置
system prompt 拼装
工具注册
subagent 委派
skills 发现与加载

`packages/sandbox`

承担执行环境抽象职责：

定义统一的 Sandbox 接口
将状态对象转换为实际 sandbox 连接
目前唯一后端为 Vercel Sandbox

4. 高层架构图

4.1 组件架构图

flowchart LR U["Browser UI"] --> W["Next.js Web App"] W --> DB[("Postgres / Drizzle")] W --> WF["Workflow Runtime"] WF --> AG["Open Harness Agent"] AG --> TOOLS["Tools / Skills / Subagents"] TOOLS --> SB["Sandbox Abstraction"] SB --> VS["Vercel Sandbox VM"] W --> VO["Vercel OAuth"] W --> GH["GitHub App + GitHub APIs"] W --> VC["Vercel Project APIs"] GH --> VS VC --> VS

4.2 分层关系图

flowchart TB subgraph ControlPlane["Web 控制面"] UI["App Router Pages / Hooks"] API["API Routes"] STORE["DB State: sessions/chats/messages"] INT["GitHub / Vercel / Auth Integration"] end subgraph Runtime["Agent 运行时"] WF["Workflow-based durable execution"] OA["openHarnessAgent"] SA["Subagents"] SK["Skills"] TL["Tool Loop"] end subgraph Execution["执行面"] SIF["Sandbox Interface"] VSB["VercelSandbox"] VM["Persistent VM / Repo / Shell / Ports"] end UI --> API API --> STORE API --> WF WF --> OA OA --> TL TL --> SA TL --> SK TL --> SIF SIF --> VSB VSB --> VM API --> INT

5. 核心设计原则

5.1 控制面与执行面分离

Agent 不在 VM 中常驻运行。它通过工具接口远程操作 sandbox：

读写文件
执行 shell
搜索代码
启动 dev server
操作 git

这意味着 sandbox 是“可替换的执行后端”，而不是应用的核心调度器。

5.2 请求生命周期与任务生命周期分离

POST /api/chat 并不在请求内同步跑完整个 agent 流程。它只是：

校验权限
连接 sandbox
装配 agent 选项
启动 workflow
将 workflow 的可读流转发给前端

真正的任务生命周期由 workflow 承载，因此它可以长时间持续。

5.3 一切关键状态可持久化

数据库中不仅有业务数据，也有运行时控制状态：

sessions.sandboxState
sessions.lifecycleState
sessions.sandboxExpiresAt
chats.activeStreamId
workflow_runs
workflow_run_steps
usage_events

这为断线恢复、幂等控制和后台清理提供了基础。

6. Web 控制面架构

apps/web 是整个系统最重的一层。它既是 UI 容器，也是系统控制平面。

6.1 UI 组织

从目录上看，主要页面和路由分成几类：

app/sessions/...
- 主工作区，用户在这里和 agent 交互
app/settings/...
- 模型、偏好、账号与统计设置
app/shared/...
- 分享态只读页面
app/api/...
- 控制面接口

前端核心交互围绕“session -> chat -> messages”展开。

6.2 API 路由分组

app/api 基本可分为以下几类：

认证与账号

/api/auth/signin/vercel
/api/auth/vercel/callback
/api/auth/github/...
/api/auth/info
/api/auth/signout

聊天与 workflow

/api/chat
/api/chat/[chatId]/stream
/api/chat/[chatId]/stop

session / chat / message 数据

/api/sessions
/api/sessions/[sessionId]/...
/api/sessions/[sessionId]/chats/...

sandbox 生命周期

/api/sandbox
/api/sandbox/status
/api/sandbox/reconnect
/api/sandbox/extend
/api/sandbox/snapshot
/api/sandbox/activity

GitHub / Vercel / PR 相关

/api/github/...
/api/vercel/...
/api/generate-pr
/api/check-pr
/api/pr

配置与统计

/api/settings/...
/api/usage
/api/models
/api/transcribe

6.3 认证模型

当前“平台登录”以 Vercel OAuth 为核心：

用户进入 /api/auth/signin/vercel
系统生成 PKCE 参数与 state
用户完成 Vercel OAuth
callback 交换 token，拉取用户信息
用户数据写入 users
生成加密 JWE session cookie

GitHub 更像是“附加能力连接”而不是主登录源，主要用于：

获取 repo 访问权限
安装 GitHub App
创建分支、push、PR
接收 webhook 同步 PR / installation 状态

6.4 Session 创建

会话创建分两步理解：

第一步：创建 session 记录

POST /api/sessions 负责：

校验用户
应用 managed template trial 限制
校验 repo owner/name
解析用户偏好
计算默认标题、默认模型、auto-commit 选项
创建 session + initialChat

这一步结束后：

session.status = running
session.sandboxState = { type: "vercel" }
session.lifecycleState = provisioning

也就是说，session 创建并不等于 sandbox 已准备完成。

第二步：初始化 sandbox

POST /api/sandbox 负责真正创建或恢复 Vercel sandbox，并将最新状态回写到 sessions.sandboxState。

7. Durable Workflow 架构

这是项目能够支持长任务和断线恢复的关键。

7.1 为什么要用 workflow

如果 agent 直接跑在 API 请求内，会遇到典型问题：

请求超时
页面刷新导致任务丢失
网络闪断导致流中断
长时间工具调用无法稳定承载

这个项目的解决方案是：

POST /api/chat 只做启动和接线
真实执行逻辑放进 runAgentWorkflow

7.2 聊天 workflow 主循环

runAgentWorkflow 的职责：

将 UI messages 转成 model messages
生成 assistant message id
打开 workflow writable stream
循环执行 agent step
将每步输出流式写回前端
在合适的时候停止，或者继续下一步
持久化消息、sandbox state、usage、workflow run
在自然完成后可选执行 auto-commit / auto-PR

7.3 step 继续条件

一个 step 完成后，如果 finishReason === "tool-calls"，且工具并未停在“需要用户确认/输入”的状态，则 workflow 会继续推进下一步。

这使得系统支持：

多步工具链
自动 tool loop
中途暂停等待用户输入

7.4 workflow 运行记录

数据库中有两类执行记录：

workflow_runs
workflow_run_steps

其作用包括：

UI 或后台分析执行时长
记录 step 级 finish reason
回溯异常执行
后续做可观测性扩展

8. Agent Runtime 架构

8.1 主 agent 形态

packages/agent/open-harness-agent.ts 中定义了主 agent：

类型：ToolLoopAgent
默认模型：anthropic/claude-opus-4.6
通过 prepareCall() 动态注入运行上下文

注入的上下文包括：

sandbox state
working directory
current branch
environment details
技能列表
主模型和 subagent 模型选择
自定义附加 instructions

8.2 工具系统

主 agent 暴露的核心工具如下：

todo_write
read
write
edit
grep
glob
bash
task
ask_user_question
skill
web_fetch

可以把它理解为一个“统一的 agent OS API”。

8.3 模型网关

模型统一经由 AI SDK gateway 访问。packages/agent/models.ts 做了两件关键事：

把 provider 差异抽象到统一的 gateway(modelId)
对不同 provider 应用默认策略

例如：

Anthropic 4.6 默认 adaptive thinking
OpenAI GPT-5 默认 store: false
GPT-5 开 reasoning/encrypted content 支持

这意味着：

上层逻辑不需要知道 provider 细节
模型切换主要体现在配置层

8.4 Subagent 体系

task 工具不是普通外部工具，而是“启动另一个 agent”：

explorer
- 只读探索、追踪代码、回答问题
executor
- 有文件修改能力，适合实现工作
design
- 专注高质量前端/UI 设计实现

Subagent 机制的价值在于：

让主 agent 保持较短上下文
将复杂任务拆给专门子角色
提升多步工作时的结构清晰度

8.5 Skills 体系

skills 不是硬编码的 prompt 片段，而是运行时从 sandbox 文件系统中发现的：

扫描 skill 目录
查找 SKILL.md
解析 frontmatter
注入到 agent system prompt / tool 体系中

这意味着 skill 是一种“文件系统插件”：

repo 内可以自带项目级 skill
用户还可以安装全局 skill
Web 在创建 sandbox 后会按 session 安装 global skills

9. Sandbox 架构

9.1 抽象接口

packages/sandbox/interface.ts 中定义了统一的 Sandbox 接口，主要能力包括：

文件读写
目录遍历
exec
execDetached
端口映射 domain(port)
stop()
extendTimeout()
snapshot()
getState()

这使 agent 工具不需要关心底层具体是 Vercel、Docker 还是别的执行后端。

9.2 当前唯一实现：Vercel Sandbox

当前 connectSandbox() 最终会走 connectVercel()。

VercelState 支持几种状态来源：

sandboxName
- 连接/恢复持久 sandbox
source
- 从 repo 创建新 sandbox
snapshotId
- 从快照恢复

9.3 Persistent Sandbox 模型

每个 session 通常会绑定一个命名的持久 sandbox：

session 创建后可初始化 sandbox
之后再次打开会话时，Web 侧通过 sandboxState 重新连接
sandbox 超时或休眠后，session 中保留状态用于恢复/清理

9.4 GitHub 凭据代理

一个重要安全设计是：

GitHub token 不直接“裸注入”为 sandbox 内环境变量
而是通过 Vercel Sandbox 的 network policy 做 credential brokering

这样做的好处是：

sandbox 可以访问 GitHub clone/push
但 token 暴露面更小
控制逻辑依然留在 Web/控制面

9.5 Sandbox 初始化时做的额外动作

创建或恢复 sandbox 后，Web 还会做几件控制面动作：

同步 Vercel CLI 登录态到 sandbox
安装 session 绑定的 global skills
更新 sessions.sandboxState
启动 sandbox 生命周期 workflow

10. 端到端运行时序

10.1 会话创建与 sandbox 初始化

sequenceDiagram participant B as Browser participant W as Web API participant DB as Postgres participant SB as Sandbox Layer participant VM as Vercel Sandbox B->>W: POST /api/sessions W->>DB: create session + initial chat W-->>B: session created (provisioning) B->>W: POST /api/sandbox W->>SB: connectSandbox(state, options) SB->>VM: create or resume persistent sandbox VM-->>SB: sandbox ready W->>DB: persist sandboxState + lifecycle active W-->>B: sandbox ready

10.2 一次聊天请求时序

sequenceDiagram participant B as Browser participant W as /api/chat participant DB as Postgres participant WF as Workflow participant AG as Agent participant VM as Sandbox B->>W: POST /api/chat W->>DB: verify ownership / load chat / load session W->>DB: persist latest user message W->>WF: start(runAgentWorkflow) W->>DB: CAS set chats.activeStreamId W-->>B: stream workflow readable loop multi-step tool loop WF->>AG: webAgent.stream(...) AG->>VM: read/write/bash/task/skill VM-->>AG: tool results AG-->>WF: streamed UI chunks WF-->>B: streamed chunks end WF->>DB: persist assistant message WF->>DB: persist sandbox state WF->>DB: record workflow run + usage WF->>DB: clear activeStreamId WF-->>B: finish

11. 数据架构

11.1 为什么数据库是“控制数据库”

这套数据库不仅存业务对象，还存运行控制状态。

11.2 核心表

`users`

平台登录用户。当前主登录来源是 Vercel。

`accounts`

外部账号连接。目前最关键的是 GitHub 用户账号及其 token。

`github_installations`

GitHub App installation 记录，用于 repo 访问授权与安装同步。

`vercel_project_links`

repo 与 Vercel project 的用户级关联。

`sessions`

最重要的聚合根。它同时承载：

repo 上下文
分支信息
Vercel project 关联
auto-commit / auto-PR session override
global skill refs
sandboxState
lifecycle 状态
diff / snapshot / PR 元数据

`chats`

session 下的对话线程。关键控制字段：

modelId
activeStreamId
lastAssistantMessageAt

`chat_messages`

以 JSON 方式存储完整消息 parts，兼容 text、reasoning、tool parts、data parts。

`workflow_runs` / `workflow_run_steps`

workflow 运行与 step 记录。

`user_preferences`

用户默认模型、subagent 模型、global skills、启用模型、auto-commit 等偏好。

`usage_events`

记录 token 使用量与工具调用次数。

11.3 数据模型关系图

erDiagram users ||--o{ sessions : owns users ||--o{ accounts : links users ||--o{ github_installations : installs users ||--o{ usage_events : generates users ||--|| user_preferences : configures sessions ||--o{ chats : contains sessions ||--o{ workflow_runs : records chats ||--o{ chat_messages : contains chats ||--o{ shares : exposes workflow_runs ||--o{ workflow_run_steps : contains

12. 流式传输与稳定性设计

这是当前项目最有工程含量的部分之一。

12.1 问题背景

链路实际上很长：

LLM Provider -> AI SDK / Gateway -> Workflow Runtime -> Next.js Route -> Browser

如果寄希望于“一条长连接永远不断”，系统会非常脆弱。因此当前实现选择的是：

任务与连接分离
流断开可恢复
关键状态入库
客户端主动探测恢复

12.2 `activeStreamId` 作为恢复锚点

chats.activeStreamId 是聊天流恢复的核心锚点：

workflow 启动后，原子写入 runId
浏览器刷新后，通过这个 id 找回当前 workflow
workflow 完成或失败后，清理该字段

并发控制依赖 compare-and-set：

只有当前值匹配预期时才更新
避免重复请求启动多个 workflow
避免旧 workflow 清掉新 workflow 的状态

12.3 `/api/chat/[chatId]/stream`

这个接口的作用不是启动任务，而是：

读取 chat 的 activeStreamId
用 getRun(runId) 连接到已有 workflow
将其 ReadableStream 重新暴露给前端
如果 run 已结束或不存在，则清理陈旧状态

12.4 前端恢复机制

前端使用 AbortableChatTransport，目的是修补 AI SDK 在 reconnect 场景下的 abort 问题：

普通 fetch 可取消
reconnect fetch 也可取消
route unmount 时不泄露连接

同时前端还实现了自动恢复策略：

页面重新 visible
window focus
浏览器恢复 online
长时间没有收到首段输出

此时客户端会：

先 probe 当前 chat 是否仍在 streaming
如果服务端还在跑，则走 resumeStream()
如果用户明确点过 stop，则不自动重连

12.5 `ReadableStream` 取消修补

workflow runtime 返回的 stream 默认取消处理不够稳，因此项目在 Web 层包了一层 createCancelableReadableStream()，专门处理：

client disconnect
abort race
run not found
late 404 / aborted 响应

12.6 设计结果

系统保障的不是“连接永不断”，而是：

浏览器断开，workflow 还在
页面刷新后可恢复现有流
stale stream id 会被清理
本地 transport 可安全 abort / retry

仍然不能完全保证的部分是：

provider 到 workflow 之间单 step 中途失败
用户已经看到但尚未被 server side 持久化的部分 token

换句话说，当前系统对“连接中断”已经有强恢复能力，但对“provider 侧 step 中断”的恢复仍然以重试和重新发起为主。

13. Sandbox 生命周期管理

13.1 生命周期状态

sessions.lifecycleState 目前包括：

provisioning
active
hibernating
hibernated
restoring
archived
failed

13.2 为什么单独做 lifecycle workflow

如果只在用户请求时顺便清理 sandbox，会出现：

用户离线后无人触发回收
sandbox 超时或长期空闲无法主动处理
DB 状态和真实 VM 状态逐渐漂移

因此项目单独引入了 sandboxLifecycleWorkflow：

定期唤醒
查看是否到达 inactivity / expiry 时间点
如果 session 仍在跑 workflow，则跳过
否则停止 sandbox，并更新会话为 hibernated

13.3 生命周期驱动信号

生命周期的“due time”由两类时间共同决定：

inactivity timeout
sandbox 过期时间减去 buffer

取较早者触发休眠判断。

13.4 lifecycle lease

为避免多个后台任务同时处理同一个 session，项目使用：

sessions.lifecycleRunId

它相当于一个 lease：

先 claim
claim 成功者才启动 lifecycle workflow
stale lease 可被识别和回收

13.5 reconnect / status 路由的作用

/api/sandbox/status 和 /api/sandbox/reconnect 是控制面与真实 sandbox 状态对齐的安全阀：

检查 runtime state 是否还有效
发现 lifecycle failed 但 runtime 仍在时，修正状态
发现 sandbox 已不可用时，将 session 转为 hibernated / expired

14. GitHub / Vercel 集成架构

14.1 GitHub 集成分成两层

GitHub 用户 token

用途：

用户级 API 调用
repo clone / push
安装同步

特点：

存储加密
支持 refresh token 刷新
每次按需解密取出

GitHub App installation

用途：

对 repo / org 做正式安装授权
创建 PR
接收 webhook

GitHub webhook 还会回写系统状态：

installation 变化同步 github_installations
PR closed / merged 会更新 session 的 prStatus
部分场景下触发 session 归档

14.2 Vercel 集成

Vercel 集成也分两层：

Vercel OAuth 登录

这是平台身份认证层。

Vercel Project 关联

这是 repo -> deployable project 的映射层，主要用于：

找到 repo 对应的 Vercel project
同步 dev env 配置的潜在能力
在 sandbox 中同步 Vercel CLI 登录态

14.3 自动 Commit / PR

聊天 workflow 自然结束后，若 session 或用户偏好允许：

检查 sandbox 内是否存在可提交更改
执行 auto-commit
如满足条件，再执行 auto-create-PR
将结果以 data parts 追加到 assistant message 中

所以 commit / PR 不是独立后台任务，而是聊天 workflow 的 post-finish 阶段。

15. 分享、只读视图与多聊天模型

15.1 session 与 chat 的关系

设计上：

一个 session 对应一个代码工作区与 sandbox
一个 session 下可有多个 chat

这意味着多个对话线程可以复用同一工作区上下文。

15.2 fork through message

系统支持基于已有 assistant message 分叉 chat：

新 chat 复制原 chat 到某条 assistant message 为止的历史
新 chat 不继承 activeStreamId
共享原 session 的 sandbox 与 repo 上下文

这是“分支式对话”而非“新建执行环境”。

15.3 分享能力

shares 表与 /app/shared/[shareId] 页面提供只读分享视图：

共享的是 chat 视图
不是新的执行 session
分享页会感知 activeStreamId 判断是否正在 streaming

16. 构建与部署模型

16.1 Monorepo 构建

根脚本负责：

bun run web
turbo build
turbo typecheck
bun run ci

16.2 数据库迁移策略

apps/web 的 build 脚本会在 next build 前执行：

bun run db:migrate:apply && next build

这意味着部署时会自动应用待执行迁移。

16.3 当前运行依赖

从代码路径看，当前真正的硬依赖包括：

Postgres
JWE secret / encryption key
Vercel OAuth

若要启用完整的 repo 操作与 PR 工作流，还需要：

GitHub App 配置
GitHub webhook secret

17. 扩展点

17.1 新增 sandbox provider

理论上可以通过 packages/sandbox 增加新的 provider：

只要实现 Sandbox 接口
再扩展 SandboxState 与 connectSandbox()

但当前 Web 控制面有较多地方默认假定 provider 为 vercel，因此真实接入仍需要改动：

session schema
sandbox lifecycle
reconnect/status 路由
UI 状态文案

17.2 新增工具

在 packages/agent/tools 添加工具后：

在主 agent 注册
如涉及 UI state，需要扩展 message part 渲染
如涉及使用量统计，需要考虑 task usage 聚合

17.3 新增 skill 来源

当前 skill 是文件系统驱动，未来可扩展为：

远端 skill registry
per-org skill source
skill 签名与版本管理

17.4 新增前端工作区能力

由于 session 与 sandbox 已经稳定绑定，理论上可以在现有 chat UI 之上继续叠加：

文件树编辑
diff review
终端视图
预览端口管理

这些都属于控制面新功能，而不需要重写 agent runtime。

18. 当前架构优势

18.1 优势

控制面、推理面、执行面边界清晰
天然适合长任务和断线重连
sandbox 生命周期可独立管理
agent 工具与 skill 体系可扩展
session/chat/message 数据模型能支撑复杂 UI
GitHub / Vercel 集成不是硬编码在 agent 内，而是控制面能力

18.2 代价

apps/web 负担很重，既是 UI 又是 orchestration layer
session 表承载信息较多，聚合根很强但也容易膨胀
对 Vercel sandbox provider 的耦合仍然较深
LLM step 级中断恢复还没有做到事务化
技能、subagent、工具、workflow 交叉后，调试复杂度较高

19. 架构风险与后续建议

19.1 当前主要风险

apps/web 控制面逻辑较集中，继续扩展后可能需要更明确的 service layer
provider 侧 step 中途失败时，部分流式可见内容可能还未持久化
sandbox lifecycle 与 reconnect 逻辑已经较复杂，需要持续用测试保护
多种状态来源同时存在时，DB state 与真实 sandbox state 仍可能产生短暂漂移

19.2 建议的演进方向

把 apps/web 中的 orchestration 进一步模块化为 session/chat/sandbox/github service
为 provider step 失败引入更细粒度的中间态持久化
为 sandbox provider 抽象增加更明确的 capability model
为 workflow / reconnect / lifecycle 增加更统一的可观测性事件流

20. 总结

Open Agents 当前的核心不是“聊天 UI”，而是一个围绕 coding agent 构建的完整执行系统：

Web 是控制面，负责认证、持久化、调度、恢复与集成
Workflow + Agent 是推理与工具编排层，负责多步决策与任务推进
Sandbox 是执行面，负责真实文件系统、shell、git 与预览端口

项目最重要的工程价值在于，它把“长时间运行的 coding task”从一次 HTTP 请求中解耦出来，并通过：

workflow 持久化
activeStreamId 流恢复
sandbox lifecycle
DB 控制状态

把一个容易中断的链路，改造成了“连接可断、任务可续、状态可对齐”的系统。

如果把当前项目用一句话概括：

它是一个以 Next.js 为控制面、以 Workflow 为执行编排器、以 Vercel Sandbox 为执行后端的可恢复型 coding agent 平台。

EVILSTAR

关于宗教，信仰，死亡的一些思考

为了找回散落的 session，我做了一个 Claude Code / Codex 会话管理器

我想做的，其实不是“另一个聊天应用”

这套架构大概长什么样

为什么我坚持先做“统一模型”

会话是怎么被发现、解析和导入的

第一步：发现文件

第二步：解析格式

第三步：写入索引

为什么我把业务逻辑集中在 SessionService

桌面端为什么还要做 watcher

对我来说，最有价值的不是搜索，而是“可以继续用”

1. 可以直接恢复原生会话

2. 可以导出成 Markdown

3. 可以在 Claude 和 Codex 之间切换

这套架构为什么我觉得是对的

当然，它现在也还不完美

总结

Claude Code `/compact` 机制分析

Context（为什么需要这份分析）

一、总体架构：三层压缩

二、触发路径

2.1 手动 /compact [自定义指令]

2.2 自动 autocompact（容量触发）

三、核心压缩算法：compactConversation

四、摘要提示词（这才是"compact 究竟让 LLM 做什么"的答案）

4.1 前导（NO_TOOLS_PREAMBLE）

4.2 主体（BASE_COMPACT_PROMPT）

4.3 结尾（NO_TOOLS_TRAILER）

4.4 两个变体

4.5 用户自定义指令拼接

五、压缩后的会话长什么样

六、其它关键设计点

6.1 Cache-sharing fork

6.2 图片/文档剥离

6.3 prompt_too_long 重试

6.4 Post-compact 文件重读

6.5 Boundary 概念

6.6 Session memory compact（实验路径）

6.7 Reactive compact

七、一句话总结

关键文件索引

验证建议（如果想动手跑一遍）

Claude Code Task 架构分析

1. 先说结论

2. 总体关系图

3. 运行时后台任务系统

3.1 核心抽象

3.2 运行时任务分层图

4. AppState 为什么是任务系统的中心

4.1 状态视图图

5. framework.ts 是运行时任务框架层

5.1 框架职责图

6. 输出系统：为什么 task output 单独做了一层

6.1 输出架构图

7. LocalShellTask：后台 bash 任务怎么实现

7.1 生命周期图

8. LocalAgentTask：后台 agent 任务怎么实现

8.1 Agent 任务结构图

8.2 关键设计点

9. RemoteAgentTask：后台任务还能落到远端 session

9.1 远端任务图

10. 停止与取出输出：运行时任务对模型的桥

10.1 停止链路图

10.2 输出链路图

11. TodoV2 任务清单系统

11.1 任务清单存储图

11.2 为什么 taskListId 设计得这么复杂

12. TaskCreate / Update / List / Get 是清单系统的 API 层

12.1 清单工具关系图

13. useTasksV2：清单系统的 UI 同步层

13.1 同步图

14. 两套 task 系统的关系

14.1 关系图

15. 设计优点与代价

优点

代价

16. 一句话总结

Claude Code Tools 设计分析

2.1 手动 `/compact [自定义指令]`

三、核心压缩算法：`compactConversation`

4.1 前导（`NO_TOOLS_PREAMBLE`）

4.2 主体（`BASE_COMPACT_PROMPT`）

4.3 结尾（`NO_TOOLS_TRAILER`）

4.1 第一层入口：`src/entrypoints/cli.tsx`

4.2 第二层入口：`src/main.tsx`

4.3 初始化：`src/entrypoints/init.ts`

4.4 会话级准备：`src/setup.ts`

6. 会话内核：`QueryEngine` + `query()`

6.1 `QueryEngine.ts`

6.2 `query.ts`

8.1 元模型：`src/Tool.ts`

8.2 工具注册：`src/tools.ts`

8.3 工具调度：`services/tools/*`

11.1 进程级全局状态：`bootstrap/state.ts`

11.2 UI / 会话视图状态：`state/AppStateStore.ts`

三、system prompt 的主体：`getSystemPrompt()`

四、`CLI sysprompt prefix` 其实只有一句话

八、`claudeMd` 的真实来源不是一个文件，而是一组文件汇总

9.1 `loadMemoryPrompt()`

9.2 `claudeMd`