从 IDE 插件
到可嵌入引擎

数字化的项目形状

入口一：CLI（apps/cli/src/index.ts，94 行）

#!/usr/bin/env bun，package.json bin: { cline: "src/index.ts" }。index.ts 做进程分支决策（worker / hub daemon / connector 进程），转发 SIGINT 到 active-runtime，然后动态 import("./main") 的 runCli()（src/main.ts，1197 行）。框架是 commander v14 + @clack/prompts（wizard 交互）+ OpenTUI（@opentui/core + @opentui/react + react-reconciler + react 19）。

命令全部注册在 main.ts：auth、config、plugin、skill、connect、mcp、doctor、hook、schedule、hub、dashboard、history、team + 默认 chat。共享根选项在 commands/program.ts（--plan、--json、--auto-approve、-c --cwd、-P --provider、-k --key、-z --zen、--config）。

和 core 的集成：session/session.ts 的 createCliCore() → ClineCore.create()（来自 @cline/core）。默认 backendMode 连 hub（传 hub: {clientType: "cli"}），forceLocalBackend 可进程内直跑。

入口二：VS Code 扩展（apps/vscode/src/extension.ts，753 行）

activate（L66）顺序：① setupHostProvider（必须最先）→ ② legacy 存储迁移 → ③ exportVSCodeStorageToSharedFiles 统一到 ~/.cline/data/（与 CLI/JetBrains 共享）→ ④ initialize 创建 VscodeWebviewProvider → ⑤ 注册 commands。

和 core 的连接是进程内直接 import：extension.ts 与 SdkController.ts（2110 行）直接 import @cline/core，引擎跑在扩展宿主进程里。hosts/vscode/hostbridge/（gRPC）只是宿主能力桥（diff/terminal/workspace），不承载 core。整个 Cline UI 是单个 WebView 内的 React 应用（claude-dev.SidebarProvider，activitybar 容器）。

入口三：hub daemon（apps/cli/src/commands/hub.ts → daemon/entry.ts）

独立守护进程，本地 WebSocket 服务器（core/src/hub/server/hub-websocket-server.ts，ws 库，协议版本协商）。connectors、cron schedule、UI 都是 hub 客户端——实现跨进程共享会话/审批/通知。

鉴权与数据

登录走 WorkOS Device Flow + OAuth（auth/cline.ts，api.workos.com/user_management/*），本地 OAuth server 回调端口 48801-48811；Provider 密钥存 ~/.cline/data/secrets.json（chmod 0o600）。

工具清单（28 个）

extensions/tools/constants.ts 的 ALL_DEFAULT_TOOL_NAMES（9 个）：read_files、search_codebase、run_commands、fetch_web_content、apply_patch、editor、skills、ask_question、submit_and_exit（工厂在 definitions.ts L247/343/457/518/611/660/723/780/801）。另有 spawn_agent（team/spawn-agent-tool.ts）和 18 个 team_* 工具（team-tools.ts:195）。

对比 Claude Code 的 40 个：少了 WebSearch/Glob/TodoWrite/NotebookEdit/Task 等（web 搜索退化为仅 fetch_web_content，glob 靠 search_codebase+run_commands）；多了 ask_question（交互提问）、submit_and_exit（无头结束运行）、skills（技能调用）、spawn_agent 与全套 team_* 多智能体工具。

编辑双雄：editor vs apply_patch

Cline 把编辑拆成两个互斥工具（definitions.ts:917 同一时刻只启用其一）：

• editor（最接近 Claude Code 的 Edit）：old_text→new_text 字面替换、insert_line 行插入或建文件，单文件精确编辑。
• apply_patch：aider 风格自由格式补丁（*** Begin Patch / *** Update File / +- 上下文行 / Add/Delete/Move），无行号、基于上下文匹配，一次调用批量编辑多文件（executors/apply-patch.ts + apply-patch-parser.ts）。

审批链路（tool-approval.ts，102 行）

流程：模型发出工具调用 → SessionRuntime 按 toolPolicies 合并全局 * 与工具级策略（session-runtime-orchestrator.ts:117-133）判 enabled → beforeTool 钩子（含循环检测）→ 若 autoApprove !== true 且宿主提供 requestToolApproval 能力 → 审批 → 执行 → afterTool。

requestDesktopToolApproval（tool-approval.ts:29）是桌面 IPC 实现：向 approvalDir 写 <sessionId>.request.<id>.json，每 200ms 轮询 decision 文件，5 分钟超时——一种"文件即 IPC"的朴素但可靠机制。ToolPolicy = {enabled?, autoApprove?}（sdk/packages/shared/src/llms/tools.ts:7），默认 enabled + autoApprove。

五套 preset（presets.ts）

act / plan / search / minimal / yolo。分级通过 ToolPolicyPresetName = "default"|"yolo"（presets.ts:137）实现——yolo 对 * 及全部默认工具 autoApprove: true。

工具注册：扁平声明式目录 vs 连续前缀

Claude Code 用 trie 做连续前缀匹配缓存。Cline 相反：runtime.ts 的 BASE_TOOL_CATALOG（9 条：工具 id/描述/headlessToolNames）→ 经 preset + model-tool-routing（按 provider/model 禁用工具的规则）+ disabledToolIds 解析出启用集合（getCoreBuiltinToolCatalog/resolveCoreSelectedToolIds，206-245 行）→ createDefaultTools 按"开关 flag && 有 executor"实例化 AgentTool[]（createTool 封装 name/description/inputSchema/execute/timeoutMs/retryable/maxRetries/lifecycle，sdk/packages/shared/src/tools/create.ts:81）。模型请求端是普通 JSON Schema 数组，无前缀排序——替代方案是 per-model 路由规则显式决定哪些工具可见。

死循环检测（runtime/safety/loop-detection.ts，162 行）

toolCallSignature 对 input 做排序键 JSON 序列化（L50）；checkRepeatedToolCall 统计连续相同"工具名+签名"次数，soft=3 / hard=5（L113）。LoopDetectionTracker.inspect（L136）返回 ok/soft/hard 三档；SessionRuntime 中 soft→往对话注入"换种方式"提示，hard→以 forceAtLimit: true 喂给 MistakeTracker 并中止运行（orchestrator:1244-1273）。

MistakeTracker（runtime/safety/mistake-tracker.ts，229 行）

三种原因：api_error / invalid_tool_call / tool_execution_failed。record() 累加 consecutiveMistakes，达上限经 onLimitReached 回调决策（默认 stop）；continue 则清零并附加恢复指引；stop 则写停止信息并 activeRuntime.abort()。所有 record 经 activeTrackerWork Promise 链串行化保证顺序。

SubprocessSandbox（runtime/tools/subprocess-sandbox.ts，346 行）

解决"插件/浏览器沙箱代码在主进程跑不安全、不可控"：spawn node/bun 子进程走 IPC，父进程发 {type:"call"}、子进程回 {type:"response"|"event"}；call 超时则 SIGTERM→SIGKILL 强杀（210-274 行）；resolveSubprocessRuntimeExecutable（L73）解析 node/bun 运行时。崩溃隔离 + 超时强制 + 事件转发。

规则系统（.clinerules，runtime/safety/rules.ts，49 行）

从 UserInstructionConfigWatcher 取快照，过滤 disabled、按名字排序，渲染为 ## 名称\n指令，拼到 system prompt 的 # Rules 段。

会话数据模型（session/models + stores）

• 索引：sessions.index.json（file-session-service.ts L50）——{version:1, sessions: {sessionId: SessionRow}} 单文件全量 JSON，atomicWriteJson 临时文件+rename 原子替换，statusLock 乐观并发（CAS）。
• manifest：sessions/<id>/session.json——会话元数据（Zod 校验）。
• 消息：sessions/<id>/<id>.json——{version:1, updated_at, agent, sessionId, messages[], system_prompt}（session-data.ts L304）整体重写（非追加）。
• SessionPersistenceAdapter 抽象存储层，默认文件实现；hub/remote 可换。

checkpoint（git 实现！）

checkpoint-diff.ts（150 行）：compareCheckpointToWorkspace（L142）→ listChangedPaths（L76）用 git diff --name-only -z <ref> + git ls-files --others 找变更文件，逐个对比产出 CheckpointContentDiff[]。有路径逃逸防护（L44）。

checkpoint-restore.ts（413 行）： - readSessionCheckpointHistory（L156）：从 metadata 解析 {ref, createdAt, runCount, kind} 历史。 - findCheckpointForRun（L202）：runCount 之前最近一个 checkpoint。 - trimMessagesToCheckpoint（L245）：用 getUserRunSpan 定位第 runCount 次用户回合，截断消息。 - beginWorktreeRestoreTransaction（L50）：回滚前用 git stash push --include-untracked 快照当前工作区，对象转移到私有 ref refs/cline/restore-transactions/<uuid>——commit 时删 ref、rollback 时 reset --hard + clean -fd + stash apply --index 还原。 - applyCheckpointToWorktree（L357）：区分 stash 与普通 commit 的 reset 路径；仅当快照含第三个父提交（<ref>^3，捕获了 untracked）才 clean -fd，避免不可恢复删除。

存什么：工作区完整快照存成 git commit/stash（含 untracked 时三父提交），会话消息本身不存（靠截断保留）。怎么回滚：SessionVersioningService.restoreCheckpoint（session-versioning-service.ts:134）编排全流程：验证 → 恢复计划 → 事务快照 → apply → 以截断消息启动新会话 → commit 事务；失败则 rollback 工作区 + 清理新会话。

🧠 一句话：checkpoint 直接复用 git 对象库做"可回滚的工作区快照"，且把回滚本身做成可回滚的事务（先 stash 再动）——这是 Cline 最优雅的工程之一。

插件系统（extensions/plugin/）

插件通过 SubprocessSandbox 子进程加载，JSON IPC 通信（initialize/executeTool/invokeHook/buildMessages）。插件可贡献：tools、commands、rules、messageBuilders、providers、automationEventTypes、mcpServers、shortcuts、flags。安装来源 npm / git / local / remote（plugin-install.ts，1218 行），含官方 slug 校验。

hooks（10 个生命周期事件）

外部 hook 事件（shared/hooks/events.ts）：agent_start / agent_resume / agent_abort / agent_end / agent_error / tool_call / tool_result / prompt_submit / pre_compact / session_shutdown。运行时钩子 AgentHooks：beforeRun / afterRun / beforeModel / afterModel / beforeTool / afterTool / onEvent。实现：hook-file-hooks.ts（1010 行，读 .hooks/ 配置）+ subprocess-runner.ts（转发到 agent hook 子进程）。

多 agent 团队（extensions/tools/team/multi-agent.ts，1852 行）

AgentTeamsRuntime（协调器核心）：内存态含 members / tasks / missionLog / mailbox / runs（队列+租约）/ outcomes / outcomeFragments；lead 通过团队工具（team-tools.ts 916 行：create_team_task、spawn_teammate、route_to_teammate、team_outcome 等）拆任务委派给 specialist（spawn-agent-tool.ts）。任务状态机 pending → in_progress → blocked（blockedBy）→ completed；运行队列 maxConcurrentRuns 限流 + 心跳 + buildRecoveredRunMessage 中断自动恢复。持久化：exportState()/hydrateState() 全量快照 → team-session-coordinator.ts（240 行）转发 TeamEvent，落 sqlite-team-store.ts（537 行）/ file-team-store.ts。

cron（31 个文件）

规范文件 .md 由 cron-watcher 监听、spec-parser 解析、reconciler 同步。sqlite-cron-store.ts（1719 行）：独立 {data}/db/cron.db，表 cron_specs/cron_runs/cron_event_log；claim_token+claim_until_at 租约机制防多进程重复执行。触发：one_off / schedule（cron 表达式）/ event；schedule-service.ts（443 行）轮询+并发限流。

connectors（IM）

core 只管生命周期（active-connectors.ts）；实际 IM 实现在 apps/cli/src/connectors/：slack/discord/telegram/gchat/whatsapp/linear 六平台，每平台独立 adapter 进程注册到 hub。

hub（46 个文件）——本地协作中心

本地 WebSocket 服务器，handlers 含 session/run/capability/approval/connector；hub-runtime-host.ts（2156 行）是 RuntimeHost 实现，hooks/tools/checkpoint/compaction 按 capability prefix 协商。

auth / account

auth/cline.ts：WorkOS Device Flow + OAuth；account/cline-account-service.ts：用户信息 RPC、featurebase token。

14.1 引擎架构：单体 vs 分层可嵌入

14.2 工具与权限

14.3 上下文与缓存

14.4 形态与目标

14.5 一句话各自的分工

• Claude Code：Claude 深度优化的终端单体——工具前缀缓存、microcompact、命令式 driver 都是为"单一模型极致体验"服务的。
• opencode：干净的多 provider 终端 TUI，工程模式（doom_loop、permission 三态）值得抄。
• Cline：广度之王——模型最多、形态最多（IDE/CLI/CI）、引擎可嵌入。缺点：工具少而精（web/glob 退化）、bun 工具链。
• CodePilot：桌面三 Runtime 客户端——同一个前端跑 Claude SDK/Native/Codex 三条引擎。
• pi：协议驱动可组合基础设施——无状态循环 + 二进制线协议 + 自扩展 Extensions，理念与 Cline 的"引擎 SDK 化"最接近，但 pi 把 Agent 拆得更碎、走协议。
• OpenWorker：交付成品的数字同事——重心在无人值守审批/连接器/定时/收件箱，不为写代码优化。

🧠 一句话：Cline 重构后的位置是"Agent 引擎的中立供应商"——不绑模型（约 180 Provider ID）、不绑界面（IDE/CLI/hub）、不绑语言（SDK 任意嵌入）。如果你要挑一个项目学"怎么把一个 Agent 做成能给别人用的引擎"，Cline 的 monorepo 分层（shared→llms→agents→core→apps）是最完整的教材。

三件事（如果只记三个设计）

1. 无状态主循环引擎（@cline/agents）与有状态编排（@cline/core）的硬分离。 AgentRuntime 不知道宿主是谁、不持有持久化；会话层反复 new AgentRuntime() 重入循环，用全量转录播种。这让同一个引擎被 CLI、VS Code、hub 三种宿主驱动成为可能——这是"引擎产品化"（@cline/sdk）的根。Claude Code 的单体架构做不出这个。

2. 事件链的三段翻译（AgentRuntimeEvent → legacy AgentEvent → CoreSessionEvent）。 引擎发出新事件，RuntimeEventAdapter（runtime-event-adapter.ts:183）做有状态翻译（usage 增量差值、tool durationMs），再经 AgentEventBridge 给 UI。重构期通过 adapter 保持对旧事件消费者的兼容——这是大型重构的教科书做法。

3. checkpoint 的 git 事务回滚。 工作区快照存成 git commit/stash（三父提交捕获 untracked），回滚本身先 stash 再动、可整体 rollback——"回滚回滚"的能力。比 Claude Code 的简单 diff 回滚强一个量级。

取舍与"适合谁"

一句话选型：想要一个住在 IDE 里、也能跑终端/CI、能嵌进自己产品的开源编程 Agent 引擎——Cline（尤其重构后的 @cline/sdk）是当前最完整的选择。想要极致深度的 Claude 优化单体，回 Claude Code；想要协议驱动的可组合基础设施，看 pi；想要桌面多引擎客户端，看 CodePilot。

🔍 源码指路（回源码核对）

本分析基于 cline/cline main 分支 2026-08 实际检出源码撰写（CLI v3.0.49 / VS Code 4.1.3 / SDK 0.0.69），所有结论标注 文件:行号 可回源核对。与本系列其他分析同框架。