AI Research 技术调研

Cline：bun-workspace 单体仓库 + hub-spoke 多客户端编码 agent harness

19分钟阅读

Cline

一句话定位

Cline 是从”VS Code 扩展”演化成的多前端编码 agent 平台：内核是分层 SDK （@cline/shared → @cline/llms → @cline/agents → @cline/core），运行时用 hub-spoke 架构——本地单例 daemon（hub）协调会话状态/路由，“spoke”工作进程跑真正 的 agent 循环，VS Code/CLI/JetBrains/Telegram 等客户端通过 WebSocket 挂接。

核心架构总览

仓库为 bun workspace 单体仓库，HEAD commit 8b6f2cf0b73eba33af21b6c19a0b50492412042c （commit message: “Raise live catalog default input tokens (#11930)“，2026-07-06）。

cline/ (monorepo, bun workspaces)
├── sdk/packages/
│   ├── shared/   — @cline/shared: 类型定义、tool contract、hook contract、默认 prompt 模板
│   ├── llms/     — @cline/llms: provider/model 网关，逐 vendor 的请求整形（thinking/reasoning 等）
│   ├── agents/   — @cline/agents: 真正的 agent loop（AgentRuntime），浏览器兼容、无 Node 专属 I/O
│   └── core/     — @cline/core（亦称 @cline/sdk）: Node 编排层——session、内置工具、hub daemon、
│                    插件、MCP、automation/cron、telemetry
├── apps/
│   ├── vscode/   — VS Code 扩展，通过 "session factory" 包装 @cline/core
│   ├── cli/      — cline CLI / TUI，ACP 支持，Telegram/Slack 等 connector
│   └── cline-hub/— hub daemon 的 web/server 部分
├── docs/         — Mintlify 文档，含 docs/sdk/architecture/*.mdx（一手架构设计文档，随仓库同 commit 追踪）
└── evals/        — 开发侧 eval harness（冒烟测试、cline-bench 子模块、失败分类器）

Hub-spoke 细节（源自 docs/sdk/architecture/hub-spoke.mdx，已存档为 key-files/docs-hub-spoke.mdx）：本地单例 daemon（hub）监听 127.0.0.1:25463，协调 会话状态与路由；“spoke” 工作进程运行 @cline/core 执行实际 agent 循环；VS Code/CLI/ JetBrains/connector 等客户端通过 WebSocket 挂接 hub。会话状态落盘在 ~/.cline/data/sessions/（SQLite 索引 + 每会话 JSON 作为 source of truth），锁文件在 ~/.cline/locks/hub/owners/。

这是新近发生的重写：历史上”单一 VS Code 扩展 + src/core/Cline.ts”的心智模型 在当前 HEAD 已不适用。

Agent Loop（主循环 / 何时继续何时停）

核心实现：sdk/packages/agents/src/agent-runtime.ts（1644 行，全文读完）， AgentRuntime.execute() 约在第 570-756 行。

  • 主循环是一个由 maxIterations 限界的 while 循环。每次迭代：
    1. generateAssistantMessage() —— 流式调用模型、组装 tool call；
    2. 若无 tool call 且无待处理的”完成工具提醒”（completion tool reminder），结束；
    3. 若有 tool call，executeToolCalls()（按 config.toolExecution 配置串行或并行执行）后回到步骤 1。
  • 完成策略（completion policy）：可要求模型必须调用一个被标记 lifecycle.completesRun === true 的终止工具（例如 YOLO 模式下的 submit_and_exit）才允许结束运行；否则运行时会注入一条合成的 [SYSTEM] 提醒消息， 循环继续，而不是静默退出。
  • 中止（abort）是一等公民：AbortController 贯穿每个 await 点 （throwIfAborted()），可随时打断循环。

记忆与上下文管理（压缩、长期记忆、会话持久化）

两条独立轴线：

(a) 上下文压缩 —— sdk/packages/core/src/extensions/context/compaction.ts （510 行，全文读完）。createContextCompactionPrepareTurn 作为运行时的 prepareTurn 钩子，在每次模型调用前执行：估算 token 数并与 maxInputTokens（从模型 contextWindow/maxTokens 或显式配置派生）比较，通过 reserveTokens 或 thresholdRatio 决定是否触发压缩，随后运行以下策略之一：

  • basic（basic-compaction.ts）——确定性截断/丢弃，目标是达到触发阈值的某个比例；
  • agentic（agentic-compaction.ts）——LLM 驱动的摘要化，保留最近 N token 的原文；
  • 或用户自定义的 compact() 函数完全接管。

压缩执行/跳过会发出 task.compaction_executed/task.compaction_skipped 遥测事件。

(b) checkpoint —— session/checkpoint-diff.ts/checkpoint-restore.ts（列出、未全文 读完），是基于 git diff 的工作区文件状态检查点/回滚系统，与对话消息压缩是两套 独立机制。

长期/跨会话记忆：在这一层不存在”记忆库”式的学习型记忆功能——持久化仅限于 会话历史本身，以及 .clinerules/skills 这类静态、用户手写的文件，不是自动积累/学习 出来的记忆。

工具体系（定义/调用协议/注册/权限）

定义位置：sdk/packages/core/src/extensions/tools/definitions.ts（部分读取，约 150 行/更大文件的一部分）、runtime.ts（部分读取）、model-tool-routing.ts（全文）。

  • 工具通过 createTool({name, description, inputSchema, execute, lifecycle}) （来自 @cline/shared）定义，注册进运行时的 Map<string, AgentTool>。
  • 内置工具目录（BASE_TOOL_CATALOG）：read_files、search_codebase、 run_commands（bash）、editor、apply_patch、fetch_web_content、skills、 ask_question、spawn_agent、teams（team_* 工具集）。
  • 启用/禁用是双重感知的：
    • mode-aware：plan/act/yolo 三种预设；
    • model-aware：model-tool-routing.ts —— 例如 OpenAI/codex/gpt 系模型会被替换为 apply_patch 而不是 editor。
  • MCP server 可动态添加工具（见下）。
  • 调用协议：模型流式发出 tool-call-delta 事件，运行时增量组装 JSON 参数；对畸形 JSON 有容错处理——标记 invalid_arguments 并返回一个解析错误的 tool-result，而不是 直接崩溃。

MCP 管理：sdk/packages/core/src/extensions/mcp/manager.ts（部分读取，约 100 行） 的 InMemoryMcpManager：server 注册、connect/disconnect 生命周期、每 server 的工具列表 缓存（5 秒 TTL）、连接状态跟踪。其余文件（client.ts、config-loader.ts、oauth.ts、 plugin-server-registration.ts、policies.ts、tools.ts、name-transform.ts）仅列出， 未深读。

Prompt 设计（系统提示结构、动态组装）

模板定义：sdk/packages/shared/src/prompt/system.ts；组装逻辑： sdk/packages/shared/src/prompt/cline.ts 的 buildClineSystemPrompt()。

  • 两个硬编码模板：
    • DEFAULT_CLINE_SYSTEM_PROMPT —— 通用编码 agent，显式指示批量并行 tool call、不要 对工具使用做元叙述、结束前自我验证结果；
    • YOLO_CLINE_SYSTEM_PROMPT —— headless/后台修 issue 模式，必须调用 submit_and_exit 才算完成，必须跑测试确认修复。
  • 两者都是带占位符的模板字符串：{{PLATFORM_NAME}}、{{CURRENT_DATE}}、 {{IDE_NAME}}、{{CWD}}、{{CLINE_RULES}}、{{CLINE_METADATA}}，由 buildClineSystemPrompt() 填充。
  • VS Code 扩展侧（apps/vscode/src/sdk/cline-session-factory.ts，读了约 560-710/823 行）在此基础上追加：偏好语言指令、Plan 模式下的 PLAN_MODE_INSTRUCTIONS 块（仅探索/分析，必须调用 switch_to_act_mode 工具，且 不能在展示计划的同一轮内调用）、以及经 isClineProvider 门控（仅 Cline 品牌 provider 生效）的工作区元数据（git remote/branch/commit，以 # Workspace Configuration JSON 块形式注入）。
  • 值得记录的对比：这版默认 prompt 明显比历史上广为人知的巨型 Cline 系统提示 短得多/简单得多——新 SDK 的默认 prompt 是几百词量级，不是几千词量级。

Router / 编排（任务分解、多 agent、子 agent）

两层机制，来源：docs/sdk/guides/multi-agent-teams.mdx（全文）、 docs/features/subagents.mdx（全文）、 sdk/packages/core/src/extensions/tools/team/multi-agent.ts（部分，约 150 行）、 spawn-agent-tool.ts（部分，约 120 行）。

  • 子 agent（sub-agents）：spawn_agent 工具（enableSpawnAgent）， createDelegatedAgent 创建带独立 system prompt/任务的子 agent，仅存在于当前 session 内，结果回传给父 agent，不允许嵌套 spawn。子 agent 工具白名单为 只读：read_file/list_files/search_files/list_code_definition_names/ execute_command（仅只读命令）/use_skill——没有 editor、没有浏览器、没有 MCP、 不能再 spawn，这一限制在官方文档中明确写出并在代码结构上体现。
  • 团队（teams）：enableAgentTeams，peer 协调模式——协调者拿到 team_spawn_teammate/team_delegate_task/team_check_status/team_get_result 等工具；状态（task board、mailbox、mission log）持久化到 ~/.cline/data/teams/[team-name]/*.json，可跨 session/CLI 调用存活恢复 （cline --team-name X "..."）。
  • 未发现独立的确定性任务分解 planner 组件——分解逻辑完全由协调者 LLM 自己的 tool call 驱动。

Skill / 插件体系

两套独立机制：

  • Skills：SKILL.md 文件 + YAML frontmatter（name/description/disabled 标志）， 从全局/项目目录扫描（getSkillsDirectoriesForScan）或由组织远程下发 （GlobalInstructionsFile[]）。通过 skills 工具在主对话内联执行（不做沙箱 隔离）——直接对标 Anthropic Claude Code 的 skill 格式。来源： apps/vscode/src/core/context/instructions/user-instructions/skills.ts （部分读取，约 140/313 行）。
  • 插件（Plugins）：AgentPlugin 对象（name、manifest.capabilities、 setup(api, ctx)、hooks），可注册工具/命令/规则/message-builder/provider/MCP server/automation 事件类型。加载后的插件运行在子进程沙箱中： plugin-sandbox.ts（部分，约 140 行，descriptor 式 IPC——插件子进程回报其贡献的 工具/命令/规则/MCP server）+ runtime/tools/subprocess-sandbox.ts（全文）——真正 的沙箱原语，起一个独立 node/bun 子进程，通过 stdio 上的 JSON-RPC 风格 call/response/event 消息通信，带每次调用超时。这是进程级隔离，不是完整的 容器/VM 沙箱。官方作者指南：docs/sdk/guides/writing-plugins.mdx（部分，约 120 行）。

自进化能力（自我改进 / 学习型记忆 / eval 驱动纠错）

未作为运行时/产品功能实现。 未发现任何代码路径会让 session 轨迹、工具调用结果 或用户反馈在运行中/运行后自动调整 prompt、工具选择或模型权重。

存在的是开发侧机制：

  • evals/（evals/ARCHITECTURE.md，全文）——三层 eval 金字塔：
    1. contract/unit 测试（确定性，无 LLM 调用——工具解析、思维轨迹格式）；
    2. 冒烟测试（5 个精选场景 × 3 模型 × 3 次试验，pass@k/pass^k 指标，结果存在 evals/smoke-tests/results/）；
    3. cline-bench——SWE-bench 风格端到端基准，通过 git 子模块 + “Harbor execution”， nightly 运行（当前因 SDK-CLI 重构而在 CI 中禁用）。
  • 失败分类器：evals/analysis/src/classifier.ts（部分）+ evals/analysis/patterns/cline-failures.yaml——正则规则把 eval 日志失败归类为 provider bug、瞬时故障、基础设施问题、策略拒绝、鉴权错误等类别，用于团队人工分诊。
  • MistakeTracker（sdk/packages/core/src/runtime/safety/mistake-tracker.ts，全文） 与 loop-detection.ts（部分，约 100 行）是单次运行内的安全阀——连续失败 N 次 后停止或注入恢复提示、检测重复相同 tool call（signature = 排序后 JSON）后升级警告， 不构成跨运行学习。

结论：eval 驱动的纠错存在于 CI/发布层面，不是 agent 自我改进闭环。

可观测性（日志 / trace 格式）

官方、opt-in 的 OpenTelemetry 支持（docs/enterprise-solutions/monitoring/ opentelemetry.mdx，全文）：OTLP 导出仅限 metrics 和 logs（功能使用计数、任务 执行指标、错误率、结构化系统/错误日志），走 gRPC 或 HTTP(protobuf/JSON)，通过 远程配置面板（app.cline.bot）配置，支持自定义 headers/auth 以对接 Datadog/New Relic/Grafana Cloud。文档明确写出当前不支持分布式 trace（原文：”❌ Distributed tracing (not yet implemented)”）、无自定义埋点 API、无采样配置。数据被 描述为”已匿名化，不包含代码内容/文件路径”。

内部实现：sdk/packages/core/src/services/telemetry/（OpenTelemetryAdapter.ts、 OpenTelemetryProvider.ts、TelemetryService.ts、TelemetryLoggerSink.ts、 core-events.ts，列出、未深读）包装了上述能力，另有更简单的内置 telemetry 路径。 事件命名形如 agent.<event-type>（来自 agent-runtime.ts 的 emit()），以及领域 特定事件如 task.compaction_executed/compaction_skipped（在 compaction.ts 中 实际调用点可见）。此外贯穿整个运行时有一个朴素的 BasicLogger 接口 （debug/log/error）用于本地开发日志。

安全与权限（审批门、密钥管理）

工具级策略系统：toolPolicies: Record<toolName, {enabled?, autoApprove?}>，未设置时 默认启用且自动批准。当某工具 autoApprove: false 时，运行时调用宿主提供的 requestToolApproval() 回调（docs/sdk/guides/permission-handling.mdx 全文，给出了 CLI-readline、always-approve、分层 read/write、条件逻辑等示例模式）；拒绝不是致命 错误——模型会收到一条拒绝消息，可以重试/调整/询问/放弃，不会挂起循环。

在 hub-spoke 部署下，审批请求经由 hub 路由，任何已挂接的客户端都可以响应 （sdk/packages/core/src/hub/server/handlers/approval-handlers.ts、 session-handlers.ts，列出未深读）。

tool-approval.ts（sdk/packages/core/src/runtime/tools/，列出未深读）、以及 apps/vscode/src/shared/AutoApprovalSettings.ts、apps/cli/src/acp/permissions.ts、 apps/cli/src/tui/components/dialogs/tool-approval.tsx 分别是 VS Code/CLI/TUI 侧的 审批 UI/设置实现（均只列出，未深读）。

密钥管理：VS Code 扩展通过 VS Code 原生 vscode.SecretStorage（OS keychain 后端） 存储 API key/凭证，实现在 apps/vscode/src/standalone/vscode-context-utils.ts 的 SecretStore implements vscode.SecretStorage 类——不是自定义加密存储。

沙箱与执行隔离

主 agent 循环的工具执行未发现容器/VM 级沙箱：run_commands/bash 通过 executors/bash.ts 直接在宿主上执行，仅受工具审批门控约束（无进一步隔离证据， executors/bash.ts 本身未在本次调研中读取源码，结论基于 NOTES 中对该路径的定位）。

唯一存在的沙箱是插件：SubprocessSandbox （sdk/packages/core/src/runtime/tools/subprocess-sandbox.ts，全文）起一个专用 node/bun 子进程，通过 stdio 上的 call/response/event JSON 协议通信，使一个行为 异常的插件不能直接破坏宿主进程的内存/状态——但这仍是普通 OS 进程（代码中未见 seccomp/namespace/容器层），若宿主不额外包装，插件继承文件系统/网络访问权限。这是 插件代码的进程边界隔离，不是对 agent 运行的任意 shell 命令做沙箱化。

与模型的协同设计

@cline/llms 有专门的 providers/routing/ 层处理逐模型/逐 provider 的请求整形怪癖。 具体例子：glm-thinking.ts（全文，key-files/glm-thinking-routing.ts）——GLM 模型 原生走 Z.AI 时需要 thinking:{type:"enabled"|"disabled"} 的线路格式，经 OpenAI-兼容端点路由时则需要通用的 reasoning:{enabled} 形状——同一个逻辑上的 “扩展思考”开关，因传输路径不同而序列化方式不同。

同目录下的兄弟文件（列出未深读）minimax-thinking.ts、anthropic-compatible.ts、 generic-compatible.ts、provider-option-rules.ts、reasoning-codecs.ts 提示这一 模式对多个 vendor 重复存在。

另一层协同设计在工具定义层：extensions/tools/model-tool-routing.ts（全文）按 provider/model ID 子串匹配，切换给模型的是哪个工具（apply_patch vs editor）。 即协同设计同时发生在 wire-protocol 层（llms 包）和工具定义层（core 包）两处。

轨迹利用（session/trajectory 是否反哺训练/评测）

Session 完整消息+工具调用历史以 JSON（SessionManifest）持久化 （sdk/packages/core/src/services/session-data.ts、session-artifacts.ts、 session/services/session-service.ts，均列出未深读），主要用途是用户侧的 恢复/历史查看（hub-spoke 文档描述客户端可断线重连并回放事件流）以及 git-diff checkpoint 系统。

未发现该轨迹数据被反馈进模型训练或自动 eval/评分流水线的证据。“轨迹变成 eval 数据”的唯一场所是开发侧：evals/e2e/run-cline-bench.ts 跑 cline-bench（git 子模块） 这个 SWE-bench 风格基准套件，是 Cline 团队自己发布流程的一部分，不是摄取真实用户 session 的实时产品功能。

与同类 harness 的关键差异（先留概述，跨 harness 对比见后续 synthesis 阶段）

  • 多客户端 hub-spoke 是 Cline 相对多数同类 harness 的结构性差异：VS Code 扩展、 CLI、JetBrains、IM connector 共享同一个本地 daemon 和会话状态，而不是各前端各自 维护独立进程内状态。
  • 子 agent 与”团队”两层编排并存，且子 agent 被严格限定为只读、禁止嵌套——这是一个 相对保守、显式设计的权限收紧，而不是任意深度的递归委派。
  • 模型协同设计做到了 wire-protocol 级别（glm-thinking.ts 等按 provider 差异化 请求 payload 形状），而不仅仅是 prompt 层面的适配；同时工具本身也按模型身份路由 （apply_patch vs editor）。
  • 自进化/轨迹反哺训练均为未实现——这点与本次调研摘要中强调的”eval 驱动纠错只在 CI/发布层面”的其他 harness 类似，具体对比留待 synthesis 阶段展开。

原始源码定位

  • repo: https://github.com/cline/cline
  • commit/version analyzed: 8b6f2cf0b73eba33af21b6c19a0b50492412042c（2026-07-06， “Raise live catalog default input tokens (#11930)”），克隆/抓取日期 2026-07-07， git clone --depth 1（浅克隆，单 commit，main 分支）
  • 关键文件列表（相对仓库根路径）：
    • sdk/packages/agents/src/agent-runtime.ts
    • sdk/packages/agents/src/index.ts
    • sdk/packages/core/src/ClineCore.ts
    • sdk/packages/shared/src/prompt/system.ts
    • sdk/packages/shared/src/prompt/cline.ts
    • apps/vscode/src/sdk/cline-session-factory.ts
    • sdk/packages/core/src/extensions/context/compaction.ts
    • sdk/packages/core/src/extensions/context/basic-compaction.ts
    • sdk/packages/core/src/extensions/context/agentic-compaction.ts
    • sdk/packages/core/src/extensions/context/compaction-shared.ts
    • sdk/packages/core/src/session/checkpoint-diff.ts
    • sdk/packages/core/src/session/checkpoint-restore.ts
    • sdk/packages/core/src/extensions/tools/definitions.ts
    • sdk/packages/core/src/extensions/tools/runtime.ts
    • sdk/packages/core/src/extensions/tools/model-tool-routing.ts
    • sdk/packages/core/src/extensions/tools/team/multi-agent.ts
    • sdk/packages/core/src/extensions/tools/team/spawn-agent-tool.ts
    • sdk/packages/core/src/extensions/mcp/manager.ts
    • sdk/packages/core/src/extensions/plugin/plugin-sandbox.ts
    • sdk/packages/core/src/runtime/tools/subprocess-sandbox.ts
    • apps/vscode/src/core/context/instructions/user-instructions/skills.ts
    • sdk/packages/core/src/runtime/safety/mistake-tracker.ts
    • sdk/packages/core/src/runtime/safety/loop-detection.ts
    • sdk/packages/core/src/runtime/tools/tool-approval.ts
    • apps/vscode/src/standalone/vscode-context-utils.ts
    • sdk/packages/llms/src/providers/routing/glm-thinking.ts
    • sdk/packages/core/src/services/telemetry/（OpenTelemetryAdapter.ts 等）
    • evals/ARCHITECTURE.md
    • evals/analysis/src/classifier.ts
    • evals/analysis/patterns/cline-failures.yaml
    • sdk/packages/core/src/services/session-data.ts
    • docs/sdk/architecture/hub-spoke.mdx
    • docs/sdk/guides/permission-handling.mdx
    • docs/sdk/guides/multi-agent-teams.mdx
    • docs/sdk/guides/writing-plugins.mdx
    • docs/features/subagents.mdx
    • docs/enterprise-solutions/monitoring/opentelemetry.mdx
    • .clinerules/*.md（仓库自身的 dogfooding 规则文件）

一手源存档（sources/）

存档目录：/Users/zhao/projects/self-wiki/ai-research/sources/harness/cline/

  • NOTES.md —— 本次调研的完整过程笔记（文件清单、逐维度总结、原始出处）
  • key-files/agent-runtime.ts —— agent loop 全文
  • key-files/compaction.ts、key-files/compaction-shared.ts —— 上下文压缩实现
  • key-files/prompt-system.ts、key-files/prompt-cline.ts —— 系统提示模板与组装
  • key-files/vscode-cline-session-factory.ts —— VS Code 侧 prompt 追加逻辑（节选）
  • key-files/tools-definitions.ts、key-files/tools-runtime.ts —— 工具目录定义
  • key-files/model-tool-routing.ts —— 按模型路由工具
  • key-files/mcp-manager.ts —— MCP server 管理
  • key-files/subprocess-sandbox.ts —— 插件子进程沙箱原语
  • key-files/team-multi-agent.ts、key-files/spawn-agent-tool.ts —— 团队/子 agent 编排
  • key-files/mistake-tracker.ts、key-files/loop-detection.ts —— 运行内安全阀
  • key-files/tool-approval.ts —— 工具审批
  • key-files/glm-thinking-routing.ts —— 模型协同设计样例
  • key-files/evals-architecture.md —— eval 金字塔说明
  • key-files/docs-hub-spoke.mdx —— 官方 hub-spoke 架构文档
  • key-files/docs-architecture-overview.mdx —— 官方架构总览文档
  • key-files/docs-multi-agent-teams.mdx —— 官方多 agent/团队文档
  • key-files/docs-subagents.mdx —— 官方子 agent 功能文档
  • key-files/docs-writing-plugins.mdx —— 官方插件编写指南
  • key-files/docs-permission-handling.mdx —— 官方权限处理指南
  • key-files/docs-opentelemetry.mdx —— 官方 OpenTelemetry 集成文档

关系图谱

反向链接