产品矩阵

Cline 提供四种使用形式，覆盖从个人开发者到企业团队的不同场景：

资料来源：README.md:1-60

核心架构

Cline 采用模块化架构设计，SDK 是所有产品的基础，CLI、VS Code 扩展和 JetBrains 插件都构建在同一核心之上，确保跨平台行为一致性。

包依赖关系

Cline SDK 由四个核心包组成，每个包有明确的职责边界：

资料来源：sdk/packages/README.md:1-25

数据流向

graph TD
    A[用户输入] --> B{CLI / VS Code / JetBrains / SDK}
    B --> C[@cline/core]
    C --> D[@cline/agents]
    D --> E[@cline/llms]
    E --> F[AI 模型提供商]
    F --> G[响应流]
    G --> D
    D --> C
    C --> B

包协作流程

1. @cline/llms 定义模型/提供商能力并构建具体处理器
2. @cline/agents 在这些处理器和工具执行原语之上运行 Agent 循环
3. @cline/core 通过持久化会话/存储和本地或 hub 支持的运行时服务组合运行时行为
4. @cline/core hub 服务编排调度运行时执行、执行历史和计划命令处理

资料来源：sdk/packages/README.md:18-25

主要功能

多 Agent 协作

Cline 支持多 Agent 团队协作，可同时启动多个专业 Agent 并行工作。SDK 提供了 agents-squad 插件，包含以下预配置 Agent：

典型的编排流程如下：

parent → start_subagent(preset: "phantom", task: "Map the auth module")
       → phantom: save_handoff("auth/recon.md", ...)
       → start_subagent(preset: "oracle", task: "Plan refactor from auth/recon.md")
       → oracle: save_handoff("auth/plan.md", ...)

资料来源：sdk/examples/plugins/agents-squad/README.md:1-50

插件系统

Cline 提供灵活的插件机制，允许扩展 Agent 能力。插件可通过以下方式安装：

cline plugin install https://github.com/cline/cline/blob/31a118fc0cc85d2638a1ed2b1b7204ad836e3e52/sdk/examples/plugins/typescript-lsp/index.ts
cline -i "Find where createTool is defined"

插件自动发现位置：

• 工作区 .cline/plugins
• ~/.cline/plugins
• 系统 Plugins 文件夹

支持的插件类型包括：

资料来源：sdk/examples/plugins/README.md:1-60

自动化任务

Cline 支持两种类型的自动化规格：

#### 循环规格（.cron.md）

按计划周期执行，支持 cron 表达式：

安装方式

CLI 安装

通过 npm 全局安装：

npm install -g cline

安装 nightly 版本以获取最新功能：

npm install -g cline@nightly

CLI 支持 macOS、Linux 和 Windows 系统，提供 arm64 和 x64 架构的预编译二进制文件，安装时自动选择对应平台版本，无需额外安装 Node、Bun 或 Zig 运行时。 资料来源：sdk/apps/cli/README.md:1-20

IDE 扩展安装

快速开始流程概览

graph TD
    A[开始使用 Cline] --> B{使用场景}
    B -->|终端交互| C[安装 CLI]
    B -->|IDE 集成| D[安装扩展]
    B -->|自定义应用| E[使用 SDK]
    C --> F[配置 API Provider]
    D --> F
    E --> G[编写 Agent 代码]
    F --> H[开始对话]
    G --> I[集成到应用]
    H --> J[完成]
    I --> J

CLI 快速开始

基本使用

交互式对话模式：

cline

单次任务模式：

cline "审计这个包并提出修复建议"

管道输入模式：

cat file.txt | cline "总结内容"

CLI 命令行参数

资料来源：sdk/apps/cli/README.md:25-45

配置 API Provider

Cline 支持多种 AI 服务提供商，包括 OpenAI、Anthropic、Google Gemini、OpenRouter、AWS Bedrock、GCP Vertex、Cerebras、Groq 等。

使用认证命令配置：

cline auth

SDK 快速开始

安装 SDK

npm install @cline/sdk

需要 Node.js 22 或更高版本。 资料来源：README.md:45-55

最小示例

发送一次请求并流式获取响应，约 15 行代码：

import { Agent } from "@cline/sdk";

const agent = new Agent();

agent.subscribe((event) => {
  if (event.type === "assistant-text-delta") {
    process.stdout.write(event.text);
  }
});

await agent.run("解释什么是依赖注入");

资料来源：sdk/apps/examples/quickstart/README.md

SDK 包结构

资料来源：sdk/packages/README.md:10-25

环境变量配置

设置 API 密钥：

export CLINE_API_KEY="cline_..."

可选：设置 GitHub 令牌以访问私有仓库和更高速率限制：

export GITHUB_TOKEN="github_pat_..."

多 Agent 示例

Cline 支持多 Agent 并行协作，典型场景包括：

1. 启动多个 Agent 实例并通过 Promise.all 并行执行
2. 每个 Agent 独立的 subscribe() 用于事件流
3. 将一个 Agent 的输出作为另一个 Agent 的输入

示例应用架构：

graph LR
    A[用户输入 Mission] --> B[Architect Agent]
    A --> C[Security Analyst Agent]
    A --> D[Pragmatist Agent]
    A --> E[Skeptic Agent]
    B --> F[Synthesizer Agent]
    C --> F
    D --> F
    E --> F
    F --> G[统一决策简报]

资料来源：sdk/apps/examples/multi-agent/README.md:1-35

自动化任务快速开始

定时任务

在 ~/.cline/cron/ 目录创建 .cron.md 规格文件：

mkdir -p ~/.cline/cron
cp examples/cron/daily-code-review.cron.md ~/.cline/cron/

编辑规格文件，设置 workspaceRoot、model 等参数。任务将在启动时自动调和并排队执行。

事件驱动任务

在 ~/.cline/cron/events/ 目录创建 .event.md 规格文件：

mkdir -p ~/.cline/cron/events
cp examples/cron/events/pr-review.event.md ~/.cline/cron/events/

配置 GitHub App 或 Webhook 来接收事件。

资料来源：sdk/examples/cron/README.md:20-60

常见问题

API 请求无响应

部分用户报告使用 DeepSeek 等提供商时出现请求无限加载的问题。可能原因包括网络连接问题或 API 提供商限制。建议检查 API 余额和连接状态。 资料来源：社区问题 #1157

LM Studio 上下文大小问题

使用 LM Studio 作为 API 提供商时，模型可能无法正确报告上下文大小。 资料来源：社区问题 #11158

Kimi API 限制

Kimi For Coding 目前仅对特定的编程代理开放，使用时可能返回 403 错误。 资料来源：社区问题 #10307

下一步

• 查看 CLI 完整文档
• 了解 IDE 扩展功能
• 探索 SDK 示例
• 学习 插件开发

架构概述

Hub-Spoke 模型采用星型拓扑结构，所有客户端（CLI、VS Code 扩展、桌面应用等）作为 Spoke 节点连接到中央 Hub 服务。这种设计将复杂的分布式通信逻辑集中在 Hub 端，简化了客户端的实现复杂度，同时保证了事件分发的一致性和实时性。

graph TD
    A[Hub Server<br/>@cline/core/hub] --> B[CLI Client]
    A --> C[VS Code Extension]
    A --> D[Desktop App]
    A --> E[Other Agents]
    B --> F[WebSocket Connection]
    C --> F
    D --> F
    E --> F
    A --> G[Session Storage]
    A --> H[Event Broadcasting]

资料来源：sdk/apps/examples/menubar/README.md

核心组件

Hub Server

Hub Server 是整个架构的中心节点，负责管理所有客户端连接、处理事件分发和维护会话状态。它基于 WebSocket 协议实现双向通信，支持广播通知和点对点消息传递。

Hub Server 提供以下核心能力：

• 连接管理：维护客户端连接池，处理连接建立和断开
• 事件广播：将 UI 事件（如 ui.notify、ui.show_window）广播给所有订阅者
• 会话追踪：记录活动会话并提供运行时状态监控
• 权限控制：支持 local、LAN 和 tunnel 三种访问模式，通过 room secret 进行鉴权

资料来源：sdk/packages/core/src/hub/index.ts

客户端 Host

客户端（Host）是连接到 Hub 的 Spoke 节点。VS Code 扩展中的 Host Provider 负责管理与 Hub 的连接生命周期。

// 简化的 Host Provider 架构
interface HostProvider {
  connect(hubUrl: string): Promise<WebSocket>;
  sendEvent(event: UiEvent): void;
  onNotification(handler: (msg: string) => void): void;
}

资料来源：apps/vscode/src/hosts/host-provider.ts

通信协议

Hub 与 Spoke 之间通过 WebSocket 协议进行通信，事件消息采用 JSON 格式序列化。

事件类型

访问模式

Hub 支持三种访问级别，通过配置控制客户端的网络访问范围：

所有隧道模式的使用都通过 room secret 进行身份验证，确保只有授权客户端能够连接。

资料来源：sdk/apps/examples/menubar/README.md

会话管理

Hub-Spoke 架构下的会话管理采用分布式存储与集中协调相结合的策略。

sequenceDiagram
    participant CLI as CLI Client
    participant Hub as Hub Server
    participant VSCode as VS Code Extension
    participant Storage as Session Storage
    
    CLI->>Hub: 建立 WebSocket 连接
    Hub->>Storage: 创建/加载会话
    Storage-->>Hub: 会话状态
    Hub-->>CLI: 会话就绪
    
    VSCode->>Hub: 连接并订阅同一会话
    Hub->>VSCode: 广播会话状态
    Hub->>CLI: 通知新客户端加入

生命周期

1. 会话创建：客户端首次连接时，Hub 为其分配唯一会话 ID
2. 会话保持：WebSocket 连接维持会话活跃状态
3. 会话同步：多客户端可加入同一会话，实现协作功能
4. 会话清理：连接断开后，Hub 根据配置决定是否保留会话数据

资料来源：sdk/packages/README.md

Hub Monitor 功能

Hub Monitor 是 Hub 的监控和管理界面，提供实时状态可视化和会话控制能力。

主要功能

部署架构

Hub Monitor Window (UI)
    │
    │  JSON lines on stdout/stderr
    ▼
Menu Bar Sidecar (TypeScript/Bun)
    │
    │  WebSocket
    ▼
Hub Server (@cline/core/hub)

资料来源：sdk/apps/examples/menubar/README.md

与 SDK 包的关系

Hub-Spoke 架构是 @cline/core 包的核心功能之一，该包负责状态化的运行时编排。

资料来源：sdk/packages/README.md

配置与使用

启动 Hub

Hub 可作为独立服务启动，支持以下配置选项：

# 环境变量配置
CLINE_HUB_PORT=8080        # Hub 监听端口
CLINE_HUB_SECRET=xxx       # Room secret 用于鉴权
CLINE_HUB_MODE=lan         # 访问模式: local|lan|tunnel

客户端连接

客户端通过配置 Hub URL 建立连接：

const hub = await ClineCore.create({
  hub: {
    url: "ws://localhost:8080",
    secret: process.env.CLINE_HUB_SECRET,
  },
});

常见问题与社区反馈

根据社区讨论，Hub-Spoke 架构相关的常见问题包括：

• 连接稳定性：部分用户报告 API 请求无限加载的问题，可能与 WebSocket 连接状态有关
• 多目录工作区：当前实现中，客户端可能只能从单一目录选择文件
• MCP 服务器日志：Hub 架构下 MCP 服务器的错误日志需要通过 Hub 的事件系统进行暴露

这些反馈推动了架构的持续优化，包括连接状态诊断、错误处理改进等方面的更新。

资料来源：GitHub Issue #1157、GitHub Issue #1959

相关资源

• SDK 架构总览 — SDK 整体架构说明
• @cline/core API 参考 — Hub 相关 API 文档
• Cline Hub 官方文档 — Hub 安装和配置指南

概述

Cline 项目采用 gRPC 作为核心组件间通信的基础协议，用于实现 VS Code 扩展宿主机与运行时核心、CLI 客户端与 Hub 服务之间的双向通信。gRPC 的使用使得 Cline 能够在 VS Code 扩展、CLI 应用和远程 Hub 服务之间建立高效的远程过程调用通道。

架构设计

通信层次

Cline 的 gRPC 通信分为两个主要层次：

graph TB
    subgraph "客户端层"
        CLI[CLI 终端]
        VSCODE[VS Code 扩展]
        JETBRAINS[JetBrains 插件]
    end
    
    subgraph "Hub 服务层"
        HUB[Hub Server]
        RUNNER[Runner Service]
        DISCOVERY[Discovery Service]
    end
    
    subgraph "扩展宿主层"
        EXTENSION[Extension Host]
        CORE[Core Controller]
    end
    
    CLI <-->|"gRPC"| HUB
    VSCODE <-->|"gRPC"| EXTENSION
    EXTENSION <-->|"gRPC"| CORE
    CORE <-->|"gRPC"| HUB
    HUB <-->|"gRPC"| RUNNER

Proto 定义文件

Cline 的 gRPC 协议定义位于 apps/vscode/proto/cline/ 目录，主要包含两个核心 proto 文件：

Proto 消息定义

Task 协议 (task.proto)

Task 协议负责处理任务的创建、调度和执行状态的跟踪。

// 任务请求消息
message TaskRequest {
    string task_id = 1;
    string session_id = 2;
    TaskType type = 3;
    bytes payload = 4;
    map<string, string> metadata = 5;
}

// 任务类型枚举
enum TaskType {
    TASK_TYPE_UNSPECIFIED = 0;
    TASK_TYPE_RUN = 1;
    TASK_TYPE_STREAM = 2;
    TASK_TYPE_CANCEL = 3;
}

// 任务响应消息
message TaskResponse {
    string task_id = 1;
    TaskStatus status = 2;
    bytes result = 3;
    string error = 4;
}

// 任务状态枚举
enum TaskStatus {
    TASK_STATUS_UNSPECIFIED = 0;
    TASK_STATUS_PENDING = 1;
    TASK_STATUS_RUNNING = 2;
    TASK_STATUS_COMPLETED = 3;
    TASK_STATUS_FAILED = 4;
    TASK_STATUS_CANCELLED = 5;
}

资料来源：apps/vscode/proto/cline/task.proto

State 协议 (state.proto)

State 协议负责在客户端和服务器之间同步运行时状态，包括会话状态、技能状态和规则配置。

// 状态更新消息
message StateUpdate {
    string session_id = 1;
    StateType type = 2;
    bytes payload = 3;
    int64 timestamp = 4;
    string source = 5;
}

// 状态类型枚举
enum StateType {
    STATE_TYPE_UNSPECIFIED = 0;
    STATE_TYPE_SESSION = 1;
    STATE_TYPE_SKILL = 2;
    STATE_TYPE_RULES = 3;
    STATE_TYPE_CONFIG = 4;
}

// 状态快照
message StateSnapshot {
    string session_id = 1;
    repeated StateEntry entries = 2;
    int64 version = 3;
}

// 状态差异
message StateDiff {
    string session_id = 1;
    repeated StateChange changes = 2;
    int64 from_version = 3;
    int64 to_version = 4;
}

资料来源：apps/vscode/proto/cline/state.proto

gRPC 服务处理器

GrpcHandler (扩展端)

GrpcHandler 是 VS Code 扩展端的 gRPC 服务处理器，负责处理来自 Core 的请求并将结果返回给扩展宿主。

核心职责：

• 注册和管理 gRPC 服务端点
• 处理任务请求的路由和分发
• 管理会话生命周期
• 处理错误和重试逻辑

// 处理器初始化流程
class GrpcHandler {
    private server: grpc.Server;
    private services: Map<string, ServiceHandler>;
    
    async initialize(): Promise<void> {
        this.server = new grpc.Server();
        this.registerServices();
        await this.server.bindAsync(
            'localhost:50051',
            grpc.ServerCredentials.createInsecure()
        );
    }
}

资料来源：apps/vscode/src/core/controller/grpc-handler.ts

HostBridgeGrpcHandler (桥接层)

HostBridgeGrpcHandler 充当扩展宿主与核心运行时之间的桥接层，负责协议转换和消息路由。

桥接功能：

class HostBridgeGrpcHandler {
    private bridge: HostBridge;
    private grpcClient: GrpcClient;
    
    async forward(request: VsCodeRequest): Promise<VsCodeResponse> {
        const grpcRequest = this.encode(request);
        const grpcResponse = await this.grpcClient.call(grpcRequest);
        return this.decode(grpcResponse);
    }
}

资料来源：apps/vscode/src/hosts/vscode/hostbridge-grpc-handler.ts

RunHandlers (Hub 服务端)

Hub 服务器端的 run-handlers 负责处理来自 CLI 客户端的任务执行请求。

处理流程：

sequenceDiagram
    participant CLI as CLI 客户端
    participant HUB as Hub Server
    participant RUNNER as Runner Service
    participant CORE as Core Runtime

    CLI->>HUB: RunRequest (gRPC)
    HUB->>HUB: 认证与授权检查
    HUB->>RUNNER: 创建执行上下文
    RUNNER->>CORE: 启动会话
    CORE-->>RUNNER: 会话就绪
    RUNNER-->>HUB: 执行状态更新
    HUB-->>CLI: 流式响应 (gRPC streaming)

核心端点：

资料来源：sdk/packages/core/src/hub/server/handlers/run-handlers.ts

通信流程

任务执行流程

graph LR
    A[CLI/扩展] -->|TaskRequest| B[Hub Server]
    B -->|验证| C{认证通过?}
    C -->|否| D[返回错误]
    C -->|是| E[创建 TaskContext]
    E -->|调度| F[Runner Service]
    F -->|执行| G[Core Runtime]
    G -->|状态更新| H[State Sync]
    H -->|流式返回| B
    B -->|TaskResponse| A

状态同步流程

状态同步采用版本化的差异同步机制，确保客户端和服务器之间的状态一致性。

graph TD
    A[State Change] --> B{检查版本}
    B -->|首次同步| C[获取完整快照]
    B -->|增量同步| D[计算差异]
    C --> E[应用快照]
    D --> F[应用差异]
    E --> G[更新版本号]
    F --> G
    G --> H[通知订阅者]

Hub 服务集成

Cline Hub 功能

根据 v3.0.15 版本更新，Hub 服务新增了以下 gRPC 支持功能：

房间密钥认证

Hub 服务的访问通过房间密钥（Room Secret）进行保护：

错误处理

错误码定义

重试策略

gRPC 处理器实现了自动重试机制：

const retryConfig = {
    maxRetries: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    backoffMultiplier: 2,
    retryableCodes: [
        grpc.status.UNAVAILABLE,
        grpc.status.RESOURCE_EXHAUSTED
    ]
};

性能考虑

连接复用

gRPC 支持连接复用以减少连接建立的开销：

• Keep-Alive：保持长连接活跃
• 多路复用：单个连接支持多个并发请求
• 流控制：防止快速发送方压倒慢速接收方

流式处理

对于需要处理大量数据的场景（如文件差异查看、代码补全），使用服务端流式处理：

// 流式任务执行
const stream = client.StreamExecute(request);
stream.on('data', (response) => {
    process.stdout.write(response.chunk);
});
stream.on('end', () => {
    console.log('Stream completed');
});

配置选项

gRPC 服务配置

相关资源

• Cline SDK 文档
• Hub 服务架构
• CLI 使用指南

概述

Cline 的代码编辑与文件系统操作是智能编程助手的核心能力之一，支撑着 AI Agent 对代码库的读取、理解和修改操作。该模块负责处理文件读写、差异计算、Patch 生成与应用等关键功能，是实现自动化代码修改的基础设施。

从架构角度来看，文件系统操作模块处于 Task 系统的工具层（Tool Handler），与 LLM 的 tool_use 调用紧密配合。当 Agent 需要理解代码上下文时，通过 read_file 工具获取文件内容；当需要修改代码时，通过 write_to_file 或 apply_patch 工具执行变更。整个流程设计注重原子性、安全性和可追溯性，确保每次修改都能被验证和回滚。

核心组件架构

文件系统操作涉及多个相互协作的组件，每个组件承担特定职责。

这些组件形成了完整的文件操作闭环：从读取理解到修改生成，再到应用验证，每个环节都有专门的模块负责。

文件读取机制

read_file 工具概述

read_file 是 Cline 中使用最频繁的工具之一，允许 Agent 读取指定文件的内容以理解代码上下文。在 v3.77.0 版本中，该工具新增了分块读取（chunked reading）支持，可以针对大文件进行有针对性的访问，避免一次性加载整个文件导致的性能问题。

文件读取还实现了读取去重缓存机制（v3.74.0 引入），在处理多轮对话时避免对同一文件的重复读取操作，显著提升了处理大型代码库时的效率。

读取流程

graph TD
    A[read_file 工具调用] --> B{文件已在缓存中?}
    B -->|是| C[返回缓存内容]
    B -->|否| D[检查文件是否存在]
    D -->|不存在| E[抛出文件不存在错误]
    D -->|存在| F[读取文件内容]
    F --> G{需要分块读取?}
    G -->|是| H[读取指定行范围]
    G -->|否| I[读取全部内容]
    H --> J[缓存读取结果]
    I --> J
    J --> K[返回文件内容]

核心实现

ReadFileToolHandler 实现了标准的 AgentTool 接口，其 execute 方法接收文件路径和可选的读取参数。处理流程首先验证文件可访问性，然后根据请求参数决定是读取全部内容还是指定行范围。对于大文件，分块读取模式只加载请求的字节范围，有效控制内存占用。

资料来源：apps/vscode/src/core/task/tools/handlers/ReadFileToolHandler.ts:1-100

缓存机制

为了优化性能，ReadFileToolHandler 维护了一个内存缓存层。当同一文件在短时间内被多次读取时，直接从缓存返回结果，避免重复的磁盘 I/O 操作。缓存策略采用 LRU（最近最少使用）淘汰机制，当缓存达到上限时自动清理较早的条目。

v3.74.0 版本增强的缓存系统特别针对代码审查场景进行了优化，在处理 PR 变更等需要频繁读取相关文件的场景下效果尤为显著。

文件写入机制

write_to_file 工具概述

write_to_file 工具负责将修改后的内容写入文件系统。这是 Agent 实施代码变更的最终环节，需要处理文件创建、覆盖和目录自动创建等场景。WriteToFileToolHandler 确保写入操作的原子性，在写入失败时能够保留原始文件内容。

写入流程

graph TD
    A[write_to_file 工具调用] --> B[解析目标文件路径]
    B --> C{父目录存在?}
    C -->|否| D[创建父目录结构]
    C -->|是| E{文件已存在?}
    E -->|是| F[创建备份]
    E -->|否| G[继续写入]
    D --> G
    F --> G
    G --> H[写入临时文件]
    H --> I{写入成功?}
    I -->|否| J[清理临时文件, 报告错误]
    I -->|是| K[原子替换原文件]
    K --> L[更新缓存]
    L --> M[返回成功结果]

原子性保证

WriteToFileToolHandler 采用写入临时文件再原子替换的策略来保证写入操作的原子性。这种实现方式确保了即使在写入过程中发生异常，原有文件也不会被破坏。临时文件使用与目标文件相同的文件系统，保证了跨文件系统操作的一致性。

资料来源：apps/vscode/src/core/task/tools/handlers/WriteToFileToolHandler.ts:1-150

目录自动创建

当目标文件的父目录不存在时，WriteToFileToolHandler 会自动创建所需的目录结构。这一行为简化了 Agent 的操作流程，无需显式调用 mkdir 工具即可创建嵌套路径下的新文件。

Patch 机制详解

Patch 格式

Cline 采用 unified diff 格式表示文件变更，这是 GNU diff 的标准输出格式，也是大多数版本控制系统（如 Git）使用的格式。Patch 字符串包含文件头信息和具体的差异内容，能够精确描述原始内容与修改后内容的区别。

一个典型的 Patch 包含以下部分：

--- a/src/utils/helper.ts
+++ b/src/utils/helper.ts
@@ -10,7 +10,9 @@ export function calculate() {
 old_content
 new_content

Patch 解析

PatchParser 负责将 unified diff 格式的字符串解析为可执行的操作序列。解析过程包括提取文件路径、识别变更类型（新增、删除、修改）、解析行号范围和内容差异。

graph TD
    A[Patch 字符串输入] --> B[提取文件路径信息]
    B --> C[解析 unified diff 头部]
    C --> D[提取 hunk 信息]
    D --> E[解析原始内容行范围]
    E --> F[解析新内容行范围]
    F --> G[构建 hunk 对象列表]
    G --> H[返回解析结果]

解析器需要处理多种边界情况，包括没有原始文件的创建操作、删除所有内容、跨多行的修改等。PatchParser 生成的中间表示可直接传递给 ApplyPatchExecutor 执行实际的文件变更。

资料来源：apps/vscode/src/core/task/tools/utils/PatchParser.ts:1-200

Patch 应用

ApplyPatchExecutor 负责将解析后的 Patch 实际应用到文件系统中。执行过程遵循以下原则：

ApplyPatchExecutor 在 SDK 层实现，可被 CLI、VS Code 扩展和 JetBrains 插件共同使用，保证了跨平台行为的一致性。

资料来源：sdk/packages/core/src/extensions/tools/executors/apply-patch.ts:1-180

差异展示

DiffGenerator 功能

DiffGenerator 组件负责将文件变更转换为人类可读的差异视图。它不仅生成标准的 unified diff 格式输出，还支持在 VS Code 的 WebView 中渲染美观的差异对比界面。

差异展示支持以下特性：

• 行号映射：显示原始行号和新行号的对应关系
• 语法高亮：保留代码的语言特征进行着色
• 上下文折叠：对于大型变更，支持折叠未修改的上下文区域
• 内联差异：支持在单行内高亮显示字符级别的变更

变更通知

当文件被修改后，Cline 会通过 WebView 通知前端更新差异展示。v3.78.0 版本修复了一个问题，现在 Chat UI 中会显示实际的 read_file 读取行范围，帮助用户理解 Agent 的操作上下文。

资料来源：apps/vscode/src/core/assistant-message/diff.ts:1-150

错误处理与边界情况

文件操作常见错误

Patch 应用失败处理

当 Patch 应用失败时，ApplyPatchExecutor 会返回详细的错误信息，包括失败的 hunk 序号和具体的失败原因。常见的失败原因包括文件已被外部修改、hunk 行号不匹配等。针对文件已修改的情况，系统会提示用户确认是否强制应用变更。

循环检测

v3.76.0 版本引入了重复工具调用循环检测机制，防止 Agent 在某些情况下陷入无限循环，重复执行相同的文件操作而浪费 tokens。该机制监控工具调用的模式，当检测到重复执行相同操作时会发出警告或终止执行。

配置与优化

文件读取配置

文件写入配置

性能优化建议

1. 合理使用分块读取：对于大型文件，指定具体的行范围而非读取全部内容
2. 利用缓存机制：避免在同一对话中重复读取相同文件
3. 批量操作：将多个相关修改组织为单一 Patch 一次性应用
4. 限制并发：避免同时进行大量文件操作以减少 I/O 压力

与其他模块的交互

文件系统操作模块与多个核心模块紧密协作：

graph LR
    A[LLM 层] -->|tool_use 调用| B[Task 系统]
    B --> C[Tool Handler]
    C --> D[ReadFileToolHandler]
    C --> E[WriteToFileToolHandler]
    D --> F[文件系统]
    E --> F
    C --> G[PatchParser]
    G --> H[ApplyPatchExecutor]
    H --> F
    F --> I[缓存层]
    I --> D
    D --> J[DiffGenerator]
    J --> K[WebView/UI]

Agent 通过 LLM 层理解代码需求，生成工具调用指令。Task 系统接收并路由这些调用到相应的 Tool Handler。Tool Handler 执行实际操作并通过缓存层优化性能。DiffGenerator 将变更结果反馈到用户界面，完成整个交互闭环。

社区关注的问题

根据社区反馈，以下文件系统相关问题值得关注：

1. 多目录工作空间限制（Issue #653）：当前在多目录工作空间中，Cline 只能识别第一个目录的文件。用户期待能够同时操作不同目录下的文件。

1. MCP 服务器日志可见性（Issue #1959）：MCP 服务器运行时会输出 stderr 日志，但 Cline 目前没有提供查看这些日志的用户界面，影响了调试体验。

1. LM Studio 上下文大小报告：使用 LM Studio 作为 API 提供者时，模型上下文大小报告可能不准确，需要用户手动验证。

最佳实践

1. 验证后再修改：使用 read_file 确认文件当前状态后再进行修改
2. 使用 Patch 进行批量变更：多个相关修改建议打包为单一 Patch 应用
3. 注意备份：重要文件修改前确认备份机制已启用
4. 理解边界：熟悉文件操作工具的能力边界，避免超出设计范围的操作

参考资料

• 文件读取处理器：ReadFileToolHandler.ts
• 文件写入处理器：WriteToFileToolHandler.ts
• Patch 解析器：PatchParser.ts
• 差异生成器：diff.ts
• Patch 执行器：apply-patch.ts

概述

Cline 中的 Plan（计划）与 Act（执行）模式是控制智能体行为的核心机制，分别对应"规划优先"和"行动优先"两种不同的工作方式。这两种模式通过系统提示词组件和独立的任务响应处理器来实现，确保智能体在不同场景下能够按照预期的方式工作。

Plan 模式适用于需要先制定详细计划、评估方案可行性的场景，让用户在执行前有机会审查和调整行动方案。

Act 模式则直接执行任务，适用于用户已明确知道需要做什么、只需快速完成操作的场景。

这两种模式的存在解决了自动化代理系统中的核心矛盾：如何在"快速行动"与"谨慎规划"之间取得平衡。资料来源：act_vs_plan_mode.ts:1-50

模式架构

Cline 的模式系统由以下核心组件构成：

graph TD
    A[用户输入] --> B{模式选择}
    B -->|Plan 模式| C[PlanModeRespondHandler]
    B -->|Act 模式| D[ActModeRespondHandler]
    C --> E[生成计划]
    D --> F[执行工具调用]
    E --> G[用户确认]
    G -->|批准| F
    G -->|拒绝| H[调整计划]
    H --> C
    F --> I[任务完成]

核心组件职责

资料来源：PlanModeRespondHandler.ts:1-30ActModeRespondHandler.ts:1-30

Plan 模式详解

工作流程

Plan 模式采用"提议-确认-执行"的交互范式。当用户启用计划模式时，智能体会先分析任务需求，生成详细的执行计划，并等待用户确认后再执行具体操作。

sequenceDiagram
    participant U as 用户
    participant A as Agent
    participant P as PlanModeRespondHandler
    participant T as 工具系统
    
    U->>A: 发送任务请求
    A->>P: 进入 Plan 模式处理
    P->>A: 生成计划建议
    A->>U: 展示计划方案
    U->>A: 确认/修改计划
    A->>T: 执行工具调用
    T->>A: 返回执行结果

Plan 模式响应处理器

PlanModeRespondHandler 是计划模式的核心处理器，负责：

1. 计划生成：根据用户意图生成结构化的执行计划
2. 方案展示：将计划以清晰易读的格式呈现给用户
3. 用户交互：等待用户确认、修改或拒绝计划
4. 计划调整：根据用户反馈调整优化计划方案

处理器会检查响应内容是否符合计划格式要求，并对不符合的部分进行格式化处理。资料来源：PlanModeRespondHandler.ts:1-100

系统提示词组件

act_vs_plan_mode.ts 中定义的系统提示词组件确保智能体在 Plan 模式下遵循特定的响应规范。这些组件包括：

• 计划结构规范：定义计划应该包含的必要元素，如目标、步骤、风险评估
• 用户交互指南：指导智能体如何清晰地向用户展示计划并等待确认
• 条件分支处理：处理用户在确认前可能提出的问题和修改要求

计划模式下的智能体不会自动执行任何修改操作，所有变更都需要用户明确授权。资料来源：act_vs_plan_mode.ts:50-150

Act 模式详解

工作流程

Act 模式采用"直接执行"的交互范式。智能体在分析任务后直接执行工具调用，适用于需要快速响应的场景。

graph LR
    A[用户请求] --> B[Agent 分析]
    B --> C[直接执行工具]
    C --> D{执行结果}
    D -->|成功| E[继续下一步]
    D -->|失败| F[重试/调整]
    E --> G[任务完成]
    F --> C

Act 模式响应处理器

ActModeRespondHandler 负责处理执行模式下的所有响应逻辑：

1. 工具调用管理：直接执行智能体决定调用的工具
2. 错误处理：当工具执行失败时进行重试或调整策略
3. 状态维护：跟踪任务执行状态，处理多步骤任务的连续性
4. 结果反馈：将执行结果格式化后返回给智能体用于后续决策

与 Plan 模式不同，Act 模式下的处理器会在工具执行失败时自动尝试替代方案，无需用户干预。资料来源：ActModeRespondHandler.ts:1-100

模式差异对比

资料来源：act_vs_plan_mode.ts:150-200

Deep Planning 深度规划

功能概述

Deep Planning 是 Cline 提供的深度规划命令，用于在 Plan 模式基础上进行更深入的需求分析和方案设计。当任务较为复杂或涉及多个子任务时，普通计划模式可能不足以覆盖所有细节，此时可以使用深度规划功能。

深度规划会：

1. 多轮分析：对用户需求进行多角度、深层次的分析
2. 依赖识别：识别任务间的依赖关系和执行顺序
3. 风险评估：评估每个步骤的潜在风险和备选方案
4. 资源规划：考虑执行所需的时间和工具资源

资料来源：deep-planning/index.ts:1-50

使用方式

深度规划通过专门的命令接口触发，用户可以通过以下方式调用：

/deep-planning

或者在智能体对话中请求使用深度规划模式。深度规划会生成一份更详尽的执行计划文档，包含但不限于：

• 任务分解结构
• 每个子任务的具体要求
• 预期的执行时间线
• 可能的失败场景及应对策略

资料来源：deep-planning/index.ts:50-150

模式切换与触发

手动切换

用户可以在任务执行过程中手动切换模式：

自动切换

Cline 的智能体可以根据上下文自动建议模式切换：

• 当检测到复杂的多步骤任务时，提示用户切换到 Plan 模式
• 当计划已确认且执行路径清晰时，建议切换到 Act 模式加速执行
• 当工具调用连续失败时，建议返回 Plan 模式重新评估方案

与其他功能集成

与 Skill 的配合

Plan 和 Act 模式可以与 Cline 的 Skill 功能配合使用：

• Plan 模式下：智能体可以参考 Skills 库中的最佳实践来制定计划
• Act 模式下：智能体可以调用 Skills 中定义的操作模板来执行任务

与 Hook 的交互

Hook 系统可以在模式切换时触发自定义逻辑：

• beforePlanModeEnter：进入计划模式前的预处理
• afterPlanModeEnter：进入计划模式后的后处理
• beforeActModeEnter：进入执行模式前的预处理
• afterActModeEnter：进入执行模式后的后处理

与 Subagent 的协作

在多智能体场景下，不同的子智能体可以运行在不同的模式下：

• 主智能体使用 Plan 模式进行整体规划和协调
• 子智能体使用 Act 模式快速执行具体分配的任务
• 子智能体的执行结果由主智能体在 Plan 模式下进行整合和调整

常见问题与最佳实践

何时使用 Plan 模式

建议在以下场景使用 Plan 模式：

1. 文件系统修改：创建、删除或修改重要文件
2. 多步骤任务：需要多个工具调用的复杂工作流程
3. 风险操作：可能影响系统稳定性或数据完整性的操作
4. 首次探索：首次在陌生代码库中工作时
5. 关键决策：涉及架构调整或重大变更的任务

何时使用 Act 模式

建议在以下场景使用 Act 模式：

1. 代码重构：已有清晰方案的局部代码调整
2. 测试执行：运行测试套件或单个测试
3. 文档更新：更新已有文档内容
4. 调试操作：添加日志或进行问题诊断
5. 快速验证：验证某个想法或假设

模式使用建议

技术实现细节

系统提示词注入机制

模式系统通过向智能体的系统提示词注入特定组件来实现行为差异：

// 伪代码示例
const systemPromptComponents = [
  ...baseComponents,
  ...(mode === 'plan' ? planModeComponents : []),
  ...(mode === 'act' ? actModeComponents : []),
];

这些组件会在对话开始时注入，并影响整个对话过程中智能体的行为。资料来源：act_vs_plan_mode.ts:200-250

响应处理器注册

PlanModeRespondHandler 和 ActModeRespondHandler 通过工厂模式注册到任务工具系统中：

const respondHandlers = {
  plan: new PlanModeRespondHandler(),
  act: new ActModeRespondHandler(),
};

系统根据当前模式选择对应的处理器来处理智能体响应。资料来源：PlanModeRespondHandler.ts:100-150ActModeRespondHandler.ts:100-150

更新历史

社区反馈表明，用户对 Plan 和 Act 模式的灵活切换有较高需求，特别是希望能够在执行过程中根据任务复杂度动态调整模式设置。

概述

检查点（Checkpoint）与历史管理是 Cline 系统中用于保存和恢复会话状态的核心功能。该系统允许用户在任何时刻保存当前工作状态，并在需要时完整恢复到该状态，包括文件系统的变更、对话历史、工具调用记录等。这对于长时间运行的任务、自动化工作流以及需要暂停和恢复的复杂开发场景至关重要。

Cline 的检查点系统由 VS Code 扩展端的集成层和 SDK 核心层的会话管理模块共同实现。VS Code 扩展负责创建、检查点差异计算和状态恢复功能，而 SDK 核心层提供了可复用的检查点与恢复 API，供 CLI、桌面应用及其他集成使用。

架构设计

核心组件

检查点与历史管理涉及多个协同工作的组件：

数据流架构

graph TD
    A[用户发起检查点操作] --> B[检查点集成模块]
    B --> C{操作类型}
    C -->|创建检查点| D[快照当前状态]
    C -->|查看历史| E[历史获取模块]
    C -->|恢复状态| F[恢复模块]
    
    D --> G[计算状态差异]
    G --> H[checkpointDiff.ts]
    H --> I[生成检查点数据]
    I --> J{存储位置}
    J -->|本地| K[文件系统]
    J -->|Hub| L[远程存储]
    
    F --> M[应用检查点差异]
    M --> N[恢复文件变更]
    M --> O[重建对话状态]
    
    E --> P[加载历史记录]
    P --> Q[显示检查点列表]

检查点操作

创建检查点

创建检查点时，系统会捕获当前会话的完整状态快照。快照内容包括：

• 文件系统状态：工作区中已修改的文件列表及变更内容
• 对话历史：所有用户消息和助手响应的完整记录
• 工具调用链：已执行工具的名称、参数和结果
• 会话元数据：创建时间戳、检查点标识符、关联的任务信息

检查点数据被持久化到本地文件系统或远程 Hub 存储，确保即使在扩展重启后也能恢复。

状态差异计算

checkpointDiff.ts 模块负责计算两个状态之间的差异。这种差异计算对于以下场景至关重要：

• 增量存储：只保存自上次检查点以来的变更，而非完整快照
• 变更预览：在恢复前向用户展示将要应用的变更
• 冲突检测：识别当前状态与目标检查点之间的潜在冲突

差异计算采用高效的 diff 算法，能够处理大文件的局部修改，同时保持良好的内存效率。

状态恢复

恢复操作从选定的检查点开始，逐步还原所有保存的状态：

1. 前置验证：检查目标检查点的完整性
2. 文件还原：按顺序应用文件系统的变更
3. 对话重建：恢复对话历史记录
4. 工具链重放：重建工具调用序列（可选）

恢复过程支持选择性恢复，用户可以决定是否包含文件变更、对话历史或仅恢复特定组件。

历史管理

任务历史

getTaskHistory.ts 模块提供了任务历史的查询接口。每个任务记录包含：

自动化中的状态持久化

在 Cline 的自动化功能中，检查点概念通过 notesDirectory 字段得到延伸。定时任务和事件驱动任务可以使用持久化笔记目录来维护多轮运行之间的状态：

概述

Cline SDK 是一个用于构建 AI 代理和集成的 Node.js 程序化接口，由驱动 CLI、Kanban、VS Code 扩展和 JetBrains 插件的同一引擎提供支持。SDK 提供自定义工具、多代理团队、连接器、定时自动化等功能，使开发者能够在自己的应用程序中利用 Cline 的核心能力。 资料来源：sdk/README.md

核心设计理念

Cline SDK 采用分层架构设计，允开发者按需使用不同层级的功能。这种设计确保了灵活性——既可以通过安装 @cline/sdk 获取完整功能，也可以选择性地引入特定的子包以减少依赖体积。SDK 的核心理念是将复杂的 AI 代理运行时封装为可组合的构建块，让开发者能够专注于业务逻辑而非底层实现细节。

SDK 支持与所有主流 LLM 提供商的开箱即用集成，包括 Anthropic、OpenAI、Google、Bedrock、Mistral 等。通过统一的抽象层，开发者可以在不改变上层代码的情况下切换不同的模型提供商。此外，SDK 提供了完整的 TypeScript 类型定义和 Zod schema 验证，确保开发时的类型安全和运行时验证。

包结构与依赖关系

Cline SDK 由多个分层包组成，每个包都有明确的职责边界。理解这些包之间的关系对于正确使用 SDK 至关重要。以下表格展示了各包的职责范围和典型消费者：

资料来源：sdk/packages/README.md

包协作流程

graph TD
    A[用户应用] --> B[@cline/core]
    B --> C[@cline/agents]
    C --> D[@cline/llms]
    C --> E[@cline/shared]
    D --> E
    B --> F[@cline/llms]
    F --> E
    
    G[CLI] --> B
    H[VS Code Extension] --> B
    I[Kanban] --> B

各包的协作遵循以下流程：首先，@cline/llms 定义模型和提供商的 capabilities 并构建具体的 handler；其次，@cline/agents 在这些 handler 和工具执行原语之上运行代理循环；然后，@cline/core 将运行时行为与持久化会话/存储以及本地或 Hub 支持的运行时服务组合在一起；最后，@cline/core 的 Hub 服务编排定时运行时执行、执行历史记录和调度命令处理。

Agent 核心 API

创建 Agent 实例

Agent 是 SDK 的核心抽象，代表一个可以执行工具并与 LLM 交互的 AI 代理。有两种方式创建 Agent 实例：

Provider 形式提供了友好的入口点，运行时通过 @cline/llms 为你构建 AgentModel：

new Agent({
    providerId: "openai",
    modelId: "gpt-5",
    apiKey: process.env.OPENAI_API_KEY,
    // baseUrl, headers 也支持
    tools: [/* ... */],
});

Model 形式面向高级用户，直接提供预构建的 AgentModel。当你已经拥有 gateway 构建逻辑时（这是 @cline/core 内部使用的方式）这很有用：

import { createGateway } from "@cline/llms";

const gateway = createGateway({ providerConfigs: [/* ... */] });
const model = gateway.createAgentModel({ providerId, modelId });

new Agent({
    model,
    tools: [/* ... */],
});

资料来源：sdk/packages/agents/README.md

工具系统

工具是 Agent 与外部世界交互的主要方式。工具符合 @cline/shared 中的 AgentTool<TInput, TOutput> 接口，每个工具都有 JSON Schema 格式的 inputSchema 和返回工具输出的 execute(input, context) 函数：

import type { AgentTool } from "@cline/shared";

const summarize: AgentTool<{ text: string }, { summary: string }> = {
    name: "summarize_text",
    description: "Summarize text into a short preview.",
    inputSchema: {
        type: "object",
        properties: { text: { type: "string" } },
        required: ["text"],
    },
    async execute({ text }, context) {
        // context.signal — 当运行被取消时中止
        // context.emitUpdate(...) — 流式传输进度
        return { summary: text.slice(0, 100) };
    },
};

资料来源：sdk/packages/agents/README.md

工具系统支持上下文传播，包括 context.signal 用于取消操作、context.emitUpdate() 用于流式传输进度更新。这种设计使得工具能够优雅地处理长时间运行的任务，同时保持对运行时的响应能力。

LLM 提供商与模型目录

运行时配置

@cline/llms 提供了模型和提供商层，为 Cline SDK 提供类型化提供商设置、模型目录、共享 gateway 契约和 AI SDK 支持的 handler 创建。使用 createLlmsRuntime(...) 可以创建一个小型注册表，包含配置的提供商及其默认模型、内置提供商发现以及自定义提供商注册功能：

import { createLlmsRuntime, defineLlmsConfig } from "@cline/llms";

const config = defineLlmsConfig({
    providers: [
        {
            providerId: "anthropic",
            apiKey: process.env.ANTHROPIC_API_KEY ?? "",
            models: ["claude-sonnet-4-6", "claude-opus-4-7"],
        },
    ],
});

const runtime = createLlmsRuntime(config);

资料来源：sdk/packages/llms/README.md

模型目录语义

模型目录是 SDK 对提供商和模型元数据的规范化副本。大部分内置目录数据来自 models.dev，通过 catalog-live.ts 获取并由模型生成脚本写入 catalog.generated.ts。目录中的 token 限制字段有明确的语义定义：

models.dev 在 limit 下暴露模型限制：limit.context 是提供商报告的最大上下文预算；limit.input 是可选的更严格的 prompt/input token 预算；limit.output 是提供商报告的最大输出 token 预算。目录将这些源字段映射到 ModelInfo：contextWindow 是提供商报告的上下文预算；maxInputTokens 是压缩和诊断使用的 prompt/input token 预算；maxTokens 是提供商报告的输出 token 预算。

资料来源：sdk/packages/llms/src/catalog/README.md

这些字段不是累加保证。例如，以下是有效的目录元数据：contextWindow: 200000、maxInputTokens: 200000、maxTokens: 128000。这意味着 prompt 可能被允许接近 200000 tokens，模型可能能够生成最多 128000 tokens 的输出，但单个请求仍需要 prompt + 输出符合提供商的规则。不要推断 maxInputTokens + maxTokens 必须小于某个值。

核心运行时服务

会话管理

@cline/core 负责有状态运行时编排，包括运行时组合、会话生命周期和存储、以及本地和 Hub 运行时服务。Hub 服务编排定时运行时执行、执行历史记录和调度命令处理。

会话管理支持跨进程的场景，这意味着多个客户端可以连接到同一个运行时实例并共享会话状态。这对于需要在多个终端或 IDE 实例之间保持一致状态的团队协作场景特别有用。

Hub 发现与客户端

Cline Hub 是一个 Web 应用，用于监控连接的客户端、查看和驱动会话、流式传输助手输出以及重启本地 Hub。Hub 的使用通过 room secret 进行本地、LAN 和 tunnel 访问控制。SDK 提供了 Hub 发现和客户端辅助函数，简化了与 Hub 服务的连接流程。

资料来源：sdk/packages/README.md

CLI 与工具集成

CLI 命令行工具

Cline CLI 通过终端提供对完整 SDK 的访问：

# 交互式代理
cline

# 单次提示
cline "Refactor the auth module to use JWT"

# 创建定时任务，每天运行
cline schedule create "PR summary" --cron "0 9 * * MON-FRI" --prompt "Summarize open PRs"

# 连接 Telegram 机器人
cline connect telegram -k "$TELEGRAM_BOT_TOKEN"

资料来源：sdk/README.md

CLI 支持单次提示、交互式聊天和定时任务等多种使用模式。对于 Telegram 特定的连接器行为，可以参考相关适配器文档。

内置工具

CLI 自带内置工具集，包括 read_file、write_file、search_codebase、execute_command 等常见操作。开发者也可以通过插件系统扩展 CLI 的能力，添加自定义工具或覆盖默认行为。

插件系统

插件安装与发现

CLI 自动从工作区的 .cline/plugins、~/.cline/plugins 和系统 Plugins 文件夹中发现插件。使用 cline plugin install 可以安装本地文件、GitHub 文件 URL、包目录、git 仓库和 npm 包：

cline plugin install https://github.com/cline/cline/blob/31a118fc0cc85d2638a1ed2b1b7204ad836e3e52/sdk/examples/plugins/weather-metrics.ts
cline plugin install ./examples/plugins/agents-squad

资料来源：sdk/examples/README.md

插件类型

SDK 提供了多种插件类型，每种都有不同的使用场景：

TypeScript LSP 插件示例

TypeScript LSP 插件提供了一个 goto_definition 工具，由 TypeScript Language Service API 驱动。与文本搜索不同，它通过导入、重导出、类型别名和声明合并解析符号——与 IDE 的工作方式相同：

cline plugin install https://github.com/cline/cline/blob/31a118fc0cc85d2638a1ed2b1b7204ad836e3e52/sdk/examples/plugins/typescript-lsp/index.ts
cline -i "Find where createTool is defined"

资料来源：sdk/examples/plugins/typescript-lsp/README.md

多代理团队插件

agents-squad 插件添加了后台代理编排工具，包括 start_subagent、message_subagent、get_subagent、list_agent_presets、list_skills 以及交接工具。它包含预配置代理（Anvil、Inquisitor、Oracle、Phantom）和可用技能（API 设计、代码审查、调试、文档、迁移、重构、测试生成）。

资料来源：sdk/examples/README.md

定时自动化

Cron 规范

Cron 规范文件支持基于时间和事件的自动化。工作目录结构为 ~/.cline/cron/，规范文件基于 frontmatter 配置。定时任务支持 cron 表达式指定运行时间，工具白名单控制可用操作，以及模式配置（plan/act）和超时设置。

资料来源：sdk/examples/cron/README.md

事件驱动规范

事件驱动规范位于 ~/.cline/cron/events/，在接收规范化事件时触发。可以配置 event 字段指定事件类型、filters 字段匹配范围、debounceSeconds 等待更多事件、dedupeWindowSeconds 忽略重复事件、cooldownSeconds 控制运行间隔以及 maxParallel 并行度限制。

插件系统概述

什么是 Cline 插件

Cline 插件是一个 TypeScript 模块，通过 AgentPlugin 接口向 Cline 运行时注册自定义功能。插件可以：

• 注册自定义工具（Tools），供 Agent 在对话中调用
• 监听 Agent 生命周期事件（Hooks）
• 参与系统提示词构建（Rules）
• 实现自动化任务触发器
• 贡献静态或动态的配置内容

资料来源：sdk/packages/README.md

插件与 SDK 的关系

Cline SDK 提供了一套完整的 TypeScript API，插件系统构建于其之上。以下是相关包的职责划分：

资料来源：sdk/packages/README.md

插件架构

插件加载机制

Cline 采用多层次插件发现和加载机制：

graph TD
    A[插件源] --> B[插件加载器 PluginLoader]
    B --> C{加载方式}
    C -->|本地文件| D[直接加载 .ts/.js]
    C -->|GitHub URL| E[下载并缓存]
    C -->|npm 包| F[解析并安装]
    C -->|Git 仓库| G[克隆并构建]
    D --> H[插件沙箱 PluginSandbox]
    E --> H
    F --> H
    G --> H
    H --> I[Agent 运行时]

插件加载器负责从多种来源解析插件模块，包括：

• 本地文件路径（.ts 或 .js）
• GitHub 文件 URL
• npm 包名
• Git 仓库地址

资料来源：sdk/examples/plugins/README.md

插件沙箱机制

插件在隔离的沙箱环境中执行，确保主运行时不受插件代码影响。沙箱提供：

• 安全的模块作用域隔离
• 插件资源的生命周期管理
• 错误边界和恢复机制

插件自动发现路径

CLI 自动从以下位置发现插件：

资料来源：sdk/examples/plugins/README.md

创建插件

插件基本结构

每个 Cline 插件必须导出一个符合 AgentPlugin 接口的对象：

import type { AgentPlugin } from "@cline/core";

const plugin: AgentPlugin = {
  name: "插件名称",
  manifest: {
    capabilities: ["tools", "hooks", "rules"],  // 声明插件能力
  },
  
  setup(api) {
    // 注册工具、钩子、规则等
  },
  
  teardown?: () => void,  // 可选清理函数
};

创建自定义工具

工具是 Agent 与外部系统交互的主要方式。使用 createTool() 函数创建工具：

import { createTool } from "@cline/core";

const myTool = createTool({
  name: "my_custom_tool",
  description: "工具描述，说明何时使用",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "参数描述" },
      param2: { type: "number", description: "可选数值参数" },
    },
    required: ["param1"],
  },
  
  async execute(input, context) {
    const { param1, param2 = 0 } = input;
    
    // 执行工具逻辑
    const result = await doSomething(param1, param2);
    
    return result;
  },
});

在 setup() 方法中注册工具：

setup(api) {
  api.registerTool(myTool);
}

资料来源：sdk/apps/cli/README.md

工具输入模式

工具的 inputSchema 采用 JSON Schema 格式，支持以下类型：

每个参数可指定：

• type：数据类型（必需）
• description：参数用途说明
• required：是否必需
• default：默认值

工具执行上下文

工具执行函数接收两个参数：

async execute(input: T, context: ToolExecutionContext) {
  // input: 经过验证的输入参数
  // context: 执行上下文
}

ToolExecutionContext 提供：

• agentId：当前 Agent ID
• sessionId：当前会话 ID
• workspaceRoot：工作区根目录
• abortSignal：取消信号

插件能力系统

声明插件能力

插件在 manifest.capabilities 中声明其提供的功能：

manifest: {
  capabilities: ["tools"],      // 提供工具
  // capabilities: ["hooks"],    // 提供钩子
  // capabilities: ["rules"],    // 提供规则
}

工具注册

setup(api) {
  api.registerTool(createTool({...}));
}

生命周期钩子

插件可以监听 Agent 生命周期事件：

setup(api) {
  api.registerHook("onToolCall", async (tool, input) => {
    console.log(`Tool ${tool} called with:`, input);
  });
  
  api.registerHook("onResponse", async (response) => {
    // 处理响应
  });
}

规则注册

插件可以贡献系统提示词规则：

setup(api) {
  api.registerRule({
    id: "my-rule",
    name: "My Rule",
    content: "You should always check X before doing Y.",
    priority: "normal",
  });
}

资料来源：sdk/packages/README.md

插件安装与分发

使用 CLI 安装插件

Cline CLI 提供 plugin install 命令安装插件：

# 从 GitHub 文件 URL 安装
cline plugin install https://github.com/cline/cline/blob/31a118fc0cc85d2638a1ed2b1b7204ad836e3e52/sdk/examples/plugins/weather-metrics.ts

# 从本地文件安装
cline plugin install ./my-plugin.ts

# 从 npm 包安装
cline plugin install my-cline-plugin

# 从 Git 仓库安装
cline plugin install https://github.com/user/my-cline-plugin

安装后插件会被复制到 ~/.cline/plugins 目录。

插件安装命令参数

资料来源：sdk/examples/plugins/README.md

插件列表与卸载

# 列出已安装插件
cline plugin list

# 卸载插件
cline plugin uninstall <plugin-name>

插件示例

天气指标工具

最简单的插件示例，添加一个天气查询工具：

import type { AgentPlugin } from "@cline/core";
import { createTool } from "@cline/core";

const weatherTool = createTool({
  name: "get_weather",
  description: "获取指定城市的天气信息",
  inputSchema: {
    type: "object",
    properties: {
      city: { type: "string", description: "城市名称" },
      unit: { 
        type: "string", 
        enum: ["celsius", "fahrenheit"],
        description: "温度单位",
        default: "celsius"
      },
    },
    required: ["city"],
  },
  async execute(input) {
    const weather = await fetchWeather(input.city, input.unit);
    return weather;
  },
});

export const plugin: AgentPlugin = {
  name: "weather-metrics",
  manifest: { capabilities: ["tools"] },
  setup(api) {
    api.registerTool(weatherTool);
  },
};

TypeScript LSP 插件

这是一个高级示例，展示如何利用 TypeScript Language Service API 实现精确的符号跳转：

import type { AgentPlugin } from "@cline/core";
import { createTool } from "@cline/core";
import * as ts from "typescript";

const gotoDefinitionTool = createTool({
  name: "goto_definition",
  description: "查找 TypeScript/JavaScript 符号的定义位置",
  inputSchema: {
    type: "object",
    properties: {
      file: { type: "string", description: "文件绝对路径" },
      line: { type: "integer", description: "行号（1-based）" },
    },
    required: ["file", "line"],
  },
  async execute(input) {
    // 1. 向上查找 tsconfig.json
    // 2. 创建或复用 TypeScript Language Service
    // 3. 扫描目标行的标识符
    // 4. 解析定义位置
    return result;
  },
});

该插件使用工作区项目自身的 TypeScript 版本，无需额外依赖。

资料来源：sdk/examples/plugins/typescript-lsp/README.md

多智能体团队插件

agents-squad 插件展示了如何在 Cline 中编排多个后台 Agent：

预配置 Agent 列表：

资料来源：sdk/examples/plugins/agents-squad/README.md

典型编排流程

parent → start_subagent(preset: "phantom", task: "Map the auth module")
       → phantom: save_handoff("auth/recon.md", ...)
       → start_subagent(preset: "oracle", task: "Plan refactor from auth/recon.md")
       → oracle: save_handoff("auth/plan.md", ...)

插件与自动化集成

定时任务中的插件

定时任务（.cron.md）可以引用插件提供的工具和扩展：

概述

Cline 的自定义工具（Custom Tools）是扩展 agent 能力的核心机制。通过 SDK 提供的 createTool() 函数，开发者可以注册自定义工具，让 agent 在执行任务时调用这些工具来完成特定操作。工具可以执行任意 JavaScript/TypeScript 代码，访问外部 API、操作文件系统、调用内部系统，或与第三方服务交互。

工具开发属于 Cline 插件体系的一部分，可通过 cline plugin install 命令安装到 CLI 或集成到 SDK 应用中。

工具架构

核心组件

Cline 工具系统由以下核心组件构成：

工具注册流程

graph TD
    A[Plugin setup] --> B[获取 AgentExtension API]
    B --> C[调用 api.registerTool]
    C --> D[createTool 创建工具定义]
    D --> E[Agent 运行时发现并调用工具]
    E --> F[工具执行器返回结果]
    F --> G[结果注入 agent 上下文]

工具定义结构

基本属性

const tool = createTool({
  name: "tool_name",           // 工具唯一标识符
  description: "工具描述",      // agent 理解工具用途的依据
  inputSchema: {               // 输入参数 schema
    type: "object",
    properties: {
      param1: { type: "string", description: "参数说明" }
    },
    required: ["param1"]
  },
  execute: async (input) => {   // 工具执行逻辑
    // 实现代码
    return { result: "success" }
  }
})

inputSchema 规范

工具的 inputSchema 必须符合 JSON Schema 规范，支持以下类型：

插件开发指南

插件结构

Cline 插件是一个导出 AgentPlugin 对象的 TypeScript 模块：

import type { AgentPlugin } from "@cline/core"
import { createTool } from "@cline/shared"

const plugin: AgentPlugin = {
  name: "my-plugin",
  manifest: {
    capabilities: ["tools"],  // 声明提供的功能类型
  },
  setup(api) {
    // 注册工具
    api.registerTool(createTool({ ... }))
  }
}

export default plugin

完整示例：天气查询工具

以下是一个完整的自定义工具示例，实现天气和指标查询功能：

import { createTool } from "@cline/shared"
import type { AgentPlugin } from "@cline/core"

const weatherMetricsPlugin: AgentPlugin = {
  name: "weather-metrics",
  manifest: { capabilities: ["tools"] },
  
  setup(api) {
    api.registerTool(
      createTool({
        name: "get_weather",
        description: "获取指定城市的当前天气信息，包括温度、湿度和天气状况",
        inputSchema: {
          type: "object",
          properties: {
            city: { 
              type: "string", 
              description: "城市名称（英文）" 
            },
            units: {
              type: "string",
              enum: ["celsius", "fahrenheit"],
              description: "温度单位",
              default: "celsius"
            }
          },
          required: ["city"]
        },
        async execute({ city, units = "celsius" }) {
          // 实际实现中调用天气 API
          const data = await fetchWeather(city, units)
          return {
            city,
            temperature: data.temp,
            humidity: data.humidity,
            condition: data.condition
          }
        }
      })
    )
  }
}

export default weatherMetricsPlugin

高级示例：TypeScript LSP 工具

TypeScript LSP 插件展示了如何利用语言服务 API 实现精确的代码导航功能：

const gotoDefinitionTool = createTool({
  name: "goto_definition",
  description: "使用 TypeScript 语言服务解析符号定义位置，支持 imports、re-exports 和类型别名",
  inputSchema: {
    type: "object",
    properties: {
      file: { type: "string", description: "目标文件的绝对路径" },
      line: { type: "integer", description: "符号所在行号（1-based）" }
    },
    required: ["file", "line"]
  },
  async execute({ file, line }) {
    // 1. 向上查找 tsconfig.json
    // 2. 创建/复用 TypeScript Language Service
    // 3. 扫描 AST 找到行上的标识符
    // 4. 解析定义位置
    const definitions = await resolveDefinitions(file, line)
    return { definitions }
  }
})

此工具利用 TypeScript 编译器 API 解析符号，比文本搜索更精确，能区分定义、引用、重导出和遮蔽变量。

子 Agent 工具集

agents-squad 插件提供了多 agent 协作能力，包含以下工具：

预置 Agent 角色

工具安装与使用

CLI 安装

通过 cline plugin install 命令安装插件：

# 从 GitHub URL 安装
cline plugin install https://github.com/cline/cline/blob/31a118fc0cc85d2638a1ed2b1b7204ad836e3e52/sdk/examples/plugins/weather-metrics.ts

# 从本地文件安装
cline plugin install ./my-plugin.ts

# 从 npm 包安装
cline plugin install @myorg/cline-plugin

目录位置

CLI 自动发现以下位置的插件：

• 项目工作区 .cline/plugins/
• 用户目录 ~/.cline/plugins/
• 系统插件目录

运行时行为

插件在 agent 会话初始化时加载，setup() 方法注册工具到运行时。工具名称在所有已加载插件中必须唯一。

输入压缩与工具描述

工具的 description 字段对 agent 正确调用工具至关重要。Cline 会在上下文压缩时将工具描述纳入考虑，简洁准确的描述有助于：

• 提升工具选择准确性
• 减少压缩后的 token 消耗
• 避免工具误用

最佳实践

1. 参数设计

• 使用 enum 限制可选值，减少 agent 错误输入
• 为所有参数提供清晰的 description
• 设置合理的 required 数组

2. 错误处理

async execute(input) {
  try {
    const result = await performOperation(input)
    return { success: true, data: result }
  } catch (error) {
    return { 
      success: false, 
      error: error.message 
    }
  }
}

3. 异步操作

工具执行函数支持 async/await，工具可以：

• 调用外部 HTTP API
• 执行数据库操作
• 运行后台进程

4. 类型安全

使用 TypeScript 编译时检查确保：

• 输入参数类型正确
• 返回数据结构一致
• 插件 manifest 完整

与 MCP 服务器对比

社区中有用户反馈 MCP 服务器的日志不可见（Issue #1959），而 Cline 工具作为插件运行，可直接在 IDE 中断点调试。

参考资料

• createTool() 函数源码：sdk/packages/shared/src/tools/create.ts
• 工具类型定义：sdk/packages/core/src/extensions/tools/types.ts
• 工具定义实现：sdk/packages/core/src/extensions/tools/definitions.ts
• 官方开发指南：docs/sdk/guides/creating-custom-tools.mdx
• 天气工具示例：sdk/examples/plugins/weather-metrics.ts
• TypeScript LSP 示例：sdk/examples/plugins/typescript-lsp/index.ts

Pitfall Log / 踩坑日志

项目：cline/cline

摘要：发现 35 个潜在踩坑项，其中 12 个为 high/blocking；最高优先级：安装坑 - 来源证据：ACP new sessions do not persist last selected provider/model in Zed on Windows。

1. 安装坑 · 来源证据：ACP new sessions do not persist last selected provider/model in Zed on Windows

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ACP new sessions do not persist last selected provider/model in Zed on Windows
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6c666b426e184cc68942e447f8497b34 | https://github.com/cline/cline/issues/11130 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Feature: Add Clarvia MCP quality scorer to recommended MCP servers

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Add Clarvia MCP quality scorer to recommended MCP servers
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8f4e7a4ae6d14f019020c38d0e8e981b | https://github.com/cline/cline/issues/10068 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c6e2166cf8bd485abada3621694898a3 | https://github.com/cline/cline/issues/11142 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b494d39931824fb08752c30da1e491f1 | https://github.com/cline/cline/issues/10596 | 来源类型 github_issue 暴露的待验证使用条件。

5. 配置坑 · 来源证据：Impossible to scroll in JetBrains Plugin

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Impossible to scroll in JetBrains Plugin
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1e50ca8cdb714e1a95984b3de7f39e12 | https://github.com/cline/cline/issues/11155 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

6. 维护坑 · 来源证据：lm studio issues

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：lm studio issues
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ce82c0e9e38b4b56a313e37ac27b2efd | https://github.com/cline/cline/issues/11158 | 来源类型 github_issue 暴露的待验证使用条件。

7. 安全/权限坑 · 来源证据：403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, e…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_abc760ef752e4e21acc8b3c659b68e53 | https://github.com/cline/cline/issues/10307 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

8. 安全/权限坑 · 来源证据：Clarvia AEO Score: Quality validation for MCP servers used in Cline

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Clarvia AEO Score: Quality validation for MCP servers used in Cline
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_726383b653d748969aa41afa2ea71e30 | https://github.com/cline/cline/issues/10076 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安全/权限坑 · 来源证据：Context mentions menu can't find @ files (since upgrading VS Code)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Context mentions menu can't find @ files (since upgrading VS Code)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4b312123333840f4bf88b05c25c6f2f5 | https://github.com/cline/cline/issues/11105 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

10. 安全/权限坑 · 来源证据：Improve Context Window Management and Large File Handling

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Improve Context Window Management and Large File Handling
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_08df034f6cea401c828566efcc7c5bc9 | https://github.com/cline/cline/issues/4389 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：Large files can cause conversations to break

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Large files can cause conversations to break
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_44f9b2daf34f42bbbd3cd52934bc43a2 | https://github.com/cline/cline/issues/5251 | 来源类型 github_issue 暴露的待验证使用条件。

12. 安全/权限坑 · 来源证据：keeps engaging in endless self-reasoning without asking any questions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：keeps engaging in endless self-reasoning without asking any questions
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7dfcdf7724b3448f9a676341aa03c5dd | https://github.com/cline/cline/issues/11154 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安装坑 · 失败模式：installation: ACP new sessions do not persist last selected provider/model in Zed on Windows

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: ACP new sessions do not persist last selected provider/model in Zed on Windows
• 对用户的影响：Developers may fail before the first successful local run: ACP new sessions do not persist last selected provider/model in Zed on Windows
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: ACP new sessions do not persist last selected provider/model in Zed on Windows. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_9781d06dd135650eb7443b989cb3f119 | https://github.com/cline/cline/issues/11130 | ACP new sessions do not persist last selected provider/model in Zed on Windows

14. 安装坑 · 失败模式：installation: CLI v3.0.12

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: CLI v3.0.12
• 对用户的影响：Upgrade or migration may change expected behavior: CLI v3.0.12
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: CLI v3.0.12. Context: Observed during installation or first-run setup.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_b3c36610dc82ecf1b5b3517bd705ce71 | https://github.com/cline/cline/releases/tag/cli-v3.0.12 | CLI v3.0.12

15. 安装坑 · 失败模式：installation: CLI v3.0.15

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: CLI v3.0.15
• 对用户的影响：Upgrade or migration may change expected behavior: CLI v3.0.15
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: CLI v3.0.15. Context: Observed during installation or first-run setup.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_50a911befc28c5946ad67615c88a1a9c | https://github.com/cline/cline/releases/tag/cli-v3.0.15 | CLI v3.0.15

16. 安装坑 · 失败模式：installation: Context mentions menu can't find @ files (since upgrading VS Code)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Context mentions menu can't find @ files (since upgrading VS Code)
• 对用户的影响：Developers may fail before the first successful local run: Context mentions menu can't find @ files (since upgrading VS Code)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Context mentions menu can't find @ files (since upgrading VS Code). Context: Observed when using windows, linux, cuda
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_14575f606192f4b17f8e3d2cebdf56bd | https://github.com/cline/cline/issues/11105 | Context mentions menu can't find @ files (since upgrading VS Code)

17. 安装坑 · 失败模式：installation: Feature: Add Clarvia MCP quality scorer to recommended MCP servers

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Feature: Add Clarvia MCP quality scorer to recommended MCP servers
• 对用户的影响：Developers may fail before the first successful local run: Feature: Add Clarvia MCP quality scorer to recommended MCP servers
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature: Add Clarvia MCP quality scorer to recommended MCP servers. Context: Observed when using node
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_e1aadce51a7a5c20910d8bdb03189ff4 | https://github.com/cline/cline/issues/10068 | Feature: Add Clarvia MCP quality scorer to recommended MCP servers

18. 安装坑 · 失败模式：installation: SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgr...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails)
• 对用户的影响：Developers may fail before the first successful local run: SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails). Context: Observed when using linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_8bb8953b67d872dd363792a46908cff3 | https://github.com/cline/cline/issues/11142 | SSH: @ file references fail with searchFiles unknown error (host index unimplemented -> ripgrep fallback also fails)

19. 配置坑 · 失败模式：configuration: 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Co...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.. Context: Observed when using linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_61bfcf097e3bc5ac5df144e36437977c | https://github.com/cline/cline/issues/10307 | 403 Kimi For Coding is currently only available for Coding Agents such as Kimi CLI, Claude Code, Roo Code, Kilo Code, etc.

20. 配置坑 · 失败模式：configuration: CLI v3.0.14

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: CLI v3.0.14
• 对用户的影响：Upgrade or migration may change expected behavior: CLI v3.0.14
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: CLI v3.0.14. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_181eada2a9a95163185cbcdbc5a47806 | https://github.com/cline/cline/releases/tag/cli-v3.0.14 | CLI v3.0.14

21. 配置坑 · 失败模式：configuration: Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_57686ab9dad083e9954799704bf50191 | https://github.com/cline/cline/issues/10596 | Cline's OpenRouter integration lacks provider pinning, inflating costs by 3-5x

22. 配置坑 · 失败模式：configuration: Impossible to scroll in JetBrains Plugin

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Impossible to scroll in JetBrains Plugin
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Impossible to scroll in JetBrains Plugin
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Impossible to scroll in JetBrains Plugin. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_6ef867741fe2d3345a1c5467be125a51 | https://github.com/cline/cline/issues/11155 | Impossible to scroll in JetBrains Plugin

23. 配置坑 · 失败模式：configuration: Improve Context Window Management and Large File Handling

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Improve Context Window Management and Large File Handling
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Improve Context Window Management and Large File Handling
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Improve Context Window Management and Large File Handling. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_c936cab419cb3037e1df613bd0c97bcd | https://github.com/cline/cline/issues/4389 | Improve Context Window Management and Large File Handling

24. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:824874689 | https://github.com/cline/cline | README/documentation is current enough for a first validation pass.

25. 维护坑 · 来源证据：Unknown or disabled provider "openai".

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Unknown or disabled provider "openai".
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_157e6dc53c3148fca716c7b3ada09b60 | https://github.com/cline/cline/issues/11016 | 来源类型 github_issue 暴露的待验证使用条件。

26. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:824874689 | https://github.com/cline/cline | last_activity_observed missing

27. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:824874689 | https://github.com/cline/cline | no_demo; severity=medium

28. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:824874689 | https://github.com/cline/cline | no_demo; severity=medium

29. 能力坑 · 失败模式：capability: Add HVTracker badge to README?

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Add HVTracker badge to README?
• 对用户的影响：Developers may hit a documented source-backed failure mode: Add HVTracker badge to README?
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Add HVTracker badge to README?. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_c8c4e917c948a42b250ca448b2c229c8 | https://github.com/cline/cline/issues/11157 | Add HVTracker badge to README?

30. 能力坑 · 失败模式：capability: Large files can cause conversations to break

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Large files can cause conversations to break
• 对用户的影响：Developers may hit a documented source-backed failure mode: Large files can cause conversations to break
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Large files can cause conversations to break. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_653d8452f6a5c6525969e8aeb1216f1b | https://github.com/cline/cline/issues/5251 | Large files can cause conversations to break

31. 能力坑 · 失败模式：capability: lm studio issues

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: lm studio issues
• 对用户的影响：Developers may hit a documented source-backed failure mode: lm studio issues
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: lm studio issues. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_4e45923ce0454787fbe338d5fe53f0e3 | https://github.com/cline/cline/issues/11158 | lm studio issues

32. 能力坑 · 失败模式：conceptual: Clarvia AEO Score: Quality validation for MCP servers used in Cline

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Clarvia AEO Score: Quality validation for MCP servers used in Cline
• 对用户的影响：Developers may hit a documented source-backed failure mode: Clarvia AEO Score: Quality validation for MCP servers used in Cline
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_543ddc6639f5043c5242d99bc0611c69 | https://github.com/cline/cline/issues/10076 | Clarvia AEO Score: Quality validation for MCP servers used in Cline

33. 能力坑 · 失败模式：conceptual: keeps engaging in endless self-reasoning without asking any questions

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: keeps engaging in endless self-reasoning without asking any questions
• 对用户的影响：Developers may hit a documented source-backed failure mode: keeps engaging in endless self-reasoning without asking any questions
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_b0ae7b74b9b2456e9444709e2a1d1453 | https://github.com/cline/cline/issues/11154 | keeps engaging in endless self-reasoning without asking any questions

34. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:824874689 | https://github.com/cline/cline | issue_or_pr_quality=unknown

35. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:824874689 | https://github.com/cline/cline | release_recency=unknown