# https://github.com/cline/cline 项目说明书
生成时间：2026-05-31 03:34:22 UTC
## 目录
- [项目介绍](#project-introduction)
- [快速开始](#quick-start)
- [Hub-Spoke 架构](#hub-spoke-architecture)
- [gRPC 通信协议](#communication-protocol)
- [代码编辑与文件系统操作](#code-editing)
- [Plan 与 Act 模式](#plan-act-modes)
- [检查点与历史管理](#checkpoints)
- [SDK 概览与核心 API](#sdk-overview)
- [插件开发指南](#plugin-development)
- [自定义工具开发](#tool-creation)
## 项目介绍
### 相关页面
相关主题：[快速开始](#quick-start), [Hub-Spoke 架构](#hub-spoke-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/cline/cline/blob/main/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
- [sdk/examples/README.md](https://github.com/cline/cline/blob/main/sdk/examples/README.md)
- [sdk/packages/agents/README.md](https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md)
- [sdk/examples/plugins/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/README.md)
- [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/agents-squad/README.md)
# 项目介绍
Cline 是一个开源的 AI 编程助手，可在 IDE 和终端中使用。它通过集成多种 AI 模型提供商，为开发者提供代码编写、调试、重构和自动化任务执行等能力。
## 产品矩阵
Cline 提供四种使用形式，覆盖从个人开发者到企业团队的不同场景：
| 产品 | 描述 | 位置 |
|------|------|------|
| **SDK** | Node.js 程序化 Agent API 和扩展导出 | [`sdk/`](https://github.com/cline/cline/tree/main/sdk) |
| **CLI** | 终端 UI、无头模式、Shell 命令和 CLI 特定流程 | [`sdk/apps/cli/`](https://github.com/cline/cline/tree/main/sdk/apps/cli) |
| **VS Code 扩展** | Marketplace 扩展和扩展主机集成 | 根目录（正在迁移） |
| **JetBrains 插件** | 支持 IntelliJ IDEA、PyCharm、WebStorm 等 JetBrains 全家桶 | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/28247-cline) |
资料来源：[README.md:1-60]()
## 核心架构
Cline 采用模块化架构设计，SDK 是所有产品的基础，CLI、VS Code 扩展和 JetBrains 插件都构建在同一核心之上，确保跨平台行为一致性。
### 包依赖关系
Cline SDK 由四个核心包组成，每个包有明确的职责边界：
| 包名 | 主要职责 | 典型消费者 | 内部依赖 |
|------|----------|------------|----------|
| `@cline/shared` | 跨包共享原语（路径解析、会话通用类型、索引辅助函数） | `@cline/agents`、`@cline/core`、apps | 无 |
| `@cline/llms` | 模型目录 + 提供商设置模式 + 处理器创建 SDK | `@cline/agents`、`@cline/core`、apps | 无 |
| `@cline/agents` | 无状态 Agent 运行时循环（工具、钩子、扩展、团队、流式处理） | `@cline/core`、apps | `@cline/llms`、`@cline/shared` |
| `@cline/core` | 有状态运行时编排（运行时组合、会话生命周期/存储、本地和 hub 运行时服务、hub 发现和客户端辅助函数） | CLI/Desktop apps | `@cline/agents`、`@cline/llms`、`@cline/shared` |
资料来源：[sdk/packages/README.md:1-25]()
### 数据流向
```mermaid
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：
| Agent | 模型 | 角色 |
|-------|------|------|
| `phantom` | `google/gemini-3-flash-preview` | 快速代码库侦察 — 映射结构、发现约定、从不实现 |
| `oracle` | `anthropic/claude-opus-4.6` | 固执己见的规划 — 挑战假设并产生可执行的计划 |
| `anvil` | `anthropic/claude-opus-4.6` | 精准实现 — 写入前先读取、保持范围、报告精确差异 |
| `inquisitor` | `openai/gpt-5.5` | 对抗性审查 — 发现 bug、严重程度排序 |
典型的编排流程如下：
```
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 能力。插件可通过以下方式安装：
```bash
cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/typescript-lsp/index.ts
cline -i "Find where createTool is defined"
```
插件自动发现位置：
- 工作区 `.cline/plugins`
- `~/.cline/plugins`
- 系统 Plugins 文件夹
支持的插件类型包括：
| 插件示例 | 提供工具 | 功能描述 |
|----------|----------|----------|
| `weather-metrics.ts` | `web_search` | 搜索工具，支持结果限制、域名过滤、时间范围和国家本地化 |
| `typescript-lsp/` | `goto_definition` | TypeScript 语言服务，支持符号定义解析 |
| `agents-squad/` | `start_subagent`, `message_subagent` 等 | 多 Agent 团队编排工具 |
资料来源：[sdk/examples/plugins/README.md:1-60]()
### 自动化任务
Cline 支持两种类型的自动化规格：
#### 循环规格（.cron.md）
按计划周期执行，支持 cron 表达式：
```yaml
---
id: daily-security-audit
title: Daily Security Audit
workspaceRoot: /path/to/repo
schedule: "0 2 * * *" # 每天凌晨2点
tools: read_files,search_codebase
mode: act
timeoutSeconds: 3600
---
```
#### 事件驱动规格（.event.md）
当事件发生时触发，例如 GitHub PR 打开：
```yaml
---
id: pr-security-review
title: Security Review for PRs
workspaceRoot: /path/to/repo
event: github.pull_request.opened
filters:
pullRequest:
baseBranch: main
cooldownSeconds: 300
maxParallel: 3
---
```
资料来源：[sdk/examples/cron/README.md:1-80]()
### 模型支持
Cline 支持多种 AI 模型提供商，配置方式灵活：
| 提供商类型 | 配置方式 | 说明 |
|------------|----------|------|
| 直接 API Key | `cline auth` | 支持 Anthropic、OpenAI、Google Gemini 等 |
| OpenAI 兼容端点 | 自定义 baseUrl | 支持 OpenRouter、LM Studio 等 |
| 云平台 | AWS Bedrock、GCP Vertex 等 | 企业级部署 |
模型目录定义了以下关键字段：
| 字段 | 说明 |
|------|------|
| `contextWindow` | 提供商报告的上下文预算 |
| `maxInputTokens` | 压缩和诊断使用的提示/输入 token 预算 |
| `maxTokens` | 提供商报告的输出 token 预算 |
资料来源：[sdk/packages/llms/src/catalog/README.md:1-50]()
资料来源：[sdk/apps/cli/README.md:1-60]()
## CLI 使用
### 安装
```bash
npm install -g cline
```
### 常用命令
| 命令 | 说明 |
|------|------|
| `cline` | 交互式聊天 |
| `cline "Audit this package"` | 单次提示执行 |
| `cat file.txt \| cline "Summarize"` | 管道输入 |
| `cline --help` | 查看完整标志参考 |
| `cline auth` | 配置 API 提供商 |
| `cline plugin install ` | 安装插件 |
### 关键参数
| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--model ` | 模型标识符 | - |
| `--provider ` | 提供商标识符 | - |
| `--api-key ` | API 密钥 | - |
| `--cwd ` | 工作目录 | 当前目录 |
| `--thinking [none\|low\|medium\|high\|xhigh]` | 模型思考级别 | medium（带标志时） |
| `--compaction ` | 上下文压缩模式 | basic |
| `--retries ` | 最大重试次数 | 3 |
| `--yolo` | 跳过工具批准提示 | - |
| `--zen` | 后台执行并立即退出 | - |
| `--data-dir ` | 隔离本地状态目录 | ~/.cline |
资料来源：[sdk/apps/cli/README.md:60-100]()
## SDK 示例应用
Cline 仓库中包含多个示例应用，展示 SDK 的不同使用场景：
### Code Review Bot
AI 驱动的代码审查仪表板，可对真实 GitHub PR 进行审查：
```bash
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev
```
功能包括：获取真实 PR 元数据和差异、渲染 PR 文件导航和 diff 视图、向 Agent 发送差异并记录审查结果。
资料来源：[sdk/apps/examples/code-review-bot/README.md:1-40]()
### Multi-Agent War Room
Web 应用，同时启动四个专业 Agent 并行工作，通过 SSE 实时流式传输响应，最终由综合 Agent 生成统一决策简报：
```bash
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev
```
资料来源：[sdk/apps/examples/multi-agent/README.md:1-50]()
## 社区与支持
### 官方资源
| 资源 | 链接 |
|------|------|
| 文档 | https://docs.cline.bot |
| Discord | https://discord.gg/cline |
| Reddit | https://www.reddit.com/r/cline/ |
| GitHub Discussions | https://github.com/cline/cline/discussions |
### 版本更新
Cline 采用语义化版本管理，主要版本包含新功能、问题修复和性能优化。近期重要更新包括：
| 版本 | 主要变更 |
|------|----------|
| v3.82.0 | 恢复 VS Code 前台终端支持，添加最新 OpenAI 模型 |
| v3.81.0 | 添加 GPT-5.5 支持，改进内存诊断 |
| v3.80.0 | 企业级 globalSkills 支持，动态推荐模型 |
| v3.79.0 | Claude Opus 4.7 支持，Azure Blob Storage |
| v3.77.0 | 懒人队友模式，chunked 文件读取 |
### 已知问题
社区反馈的常见问题包括：
- **多目录工作区限制**：在多目录工作区中只能选择第一个目录的文件
- **LM Studio 上下文大小**：LM Studio 作为 API 提供商时不报告正确的模型上下文大小
- **API 请求无响应**：部分用户遇到 API 请求无限加载的问题
这些问题已在社区中持续跟踪和讨论。
资料来源：[README.md:1-60]()
## 技术要求
| 组件 | 要求 |
|------|------|
| Node.js | >= 22 |
| 包管理器 | Bun 1.3.13+ |
| TypeScript | ^5.9.3 |
| nanoid | ^5.1.7 |
资料来源：[sdk/package.json:1-20]()
## 下一步
- 阅读 [SDK 文档](https://docs.cline.bot/cline-sdk/overview) 了解更多集成方式
- 查看 [CLI 使用指南](sdk/apps/cli/README.md) 掌握终端操作
- 探索 [示例代码](sdk/examples/README.md) 学习最佳实践
- 参考 [插件开发](sdk/examples/plugins/README.md) 扩展功能
---
## 快速开始
### 相关页面
相关主题：[项目介绍](#project-introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
- [README.md](https://github.com/cline/cline/blob/main/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/apps/examples/quickstart/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/quickstart/README.md)
- [sdk/apps/examples/multi-agent/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/multi-agent/README.md)
- [sdk/examples/README.md](https://github.com/cline/cline/blob/main/sdk/examples/README.md)
- [sdk/examples/cron/README.md](https://github.com/cline/cline/blob/main/sdk/examples/cron/README.md)
# 快速开始
Cline 是一个开源的 AI 编程助手，可在 IDE、终端和自定义应用中运行。本文档帮助你在 5 分钟内启动并运行 Cline。
## 安装方式
### CLI 安装
通过 npm 全局安装：
```bash
npm install -g cline
```
安装 nightly 版本以获取最新功能：
```bash
npm install -g cline@nightly
```
CLI 支持 macOS、Linux 和 Windows 系统，提供 `arm64` 和 `x64` 架构的预编译二进制文件，安装时自动选择对应平台版本，无需额外安装 Node、Bun 或 Zig 运行时。 资料来源：[sdk/apps/cli/README.md:1-20](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
### IDE 扩展安装
| 平台 | 安装方式 |
|------|----------|
| VS Code | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) |
| JetBrains | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/28247-cline) |
## 快速开始流程概览
```mermaid
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 快速开始
### 基本使用
交互式对话模式：
```sh
cline
```
单次任务模式：
```sh
cline "审计这个包并提出修复建议"
```
管道输入模式：
```sh
cat file.txt | cline "总结内容"
```
### CLI 命令行参数
| 参数 | 说明 |
|------|------|
| `-i, --input ` | 直接传递任务文本 |
| `-c, --cwd ` | 设置工具工作目录 |
| `--thinking [none\|low\|medium\|high\|xhigh]` | 模型思考级别 |
| `--compaction ` | 上下文压缩模式 |
| `--auto-approve [true\|false]` | 自动批准工具执行 |
| `-y, --yolo` | 跳过批准提示，启用自动提交 |
| `-z, --zen` | 后台执行任务并立即退出 |
| `--json` | 输出 NDJSON 格式 |
| `--retries ` | 最大重试次数（默认 3） |
资料来源：[sdk/apps/cli/README.md:25-45](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
### 配置 API Provider
Cline 支持多种 AI 服务提供商，包括 OpenAI、Anthropic、Google Gemini、OpenRouter、AWS Bedrock、GCP Vertex、Cerebras、Groq 等。
使用认证命令配置：
```sh
cline auth
```
## SDK 快速开始
### 安装 SDK
```bash
npm install @cline/sdk
```
需要 Node.js 22 或更高版本。 资料来源：[README.md:45-55](https://github.com/cline/cline/blob/main/README.md)
### 最小示例
发送一次请求并流式获取响应，约 15 行代码：
```typescript
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](https://github.com/cline/cline/blob/main/sdk/apps/examples/quickstart/README.md)
### SDK 包结构
| 包名 | 主要职责 | 典型使用者 | 内部依赖 |
|------|----------|------------|----------|
| `@cline/shared` | 跨包共享原语（路径解析、会话类型、索引辅助） | `@cline/agents`、`@cline/core` | 无 |
| `@cline/llms` | 模型目录 + 提供商设置模式 + 处理器创建 | `@cline/agents`、`@cline/core` | 无 |
| `@cline/agents` | 无状态 Agent 运行时循环（工具、钩子、扩展、团队、流式） | `@cline/core` | `@cline/llms`、`@cline/shared` |
| `@cline/core` | 有状态运行时编排（会话生命周期/存储、本地和 Hub 运行时服务） | CLI/桌面应用 | `@cline/agents`、`@cline/llms`、`@cline/shared` |
资料来源：[sdk/packages/README.md:10-25](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
### 环境变量配置
设置 API 密钥：
```bash
export CLINE_API_KEY="cline_..."
```
可选：设置 GitHub 令牌以访问私有仓库和更高速率限制：
```bash
export GITHUB_TOKEN="github_pat_..."
```
## 多 Agent 示例
Cline 支持多 Agent 并行协作，典型场景包括：
1. 启动多个 `Agent` 实例并通过 `Promise.all` 并行执行
2. 每个 Agent 独立的 `subscribe()` 用于事件流
3. 将一个 Agent 的输出作为另一个 Agent 的输入
示例应用架构：
```mermaid
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](https://github.com/cline/cline/blob/main/sdk/apps/examples/multi-agent/README.md)
## 自动化任务快速开始
### 定时任务
在 `~/.cline/cron/` 目录创建 `.cron.md` 规格文件：
```bash
mkdir -p ~/.cline/cron
cp examples/cron/daily-code-review.cron.md ~/.cline/cron/
```
编辑规格文件，设置 `workspaceRoot`、`model` 等参数。任务将在启动时自动调和并排队执行。
### 事件驱动任务
在 `~/.cline/cron/events/` 目录创建 `.event.md` 规格文件：
```bash
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](https://github.com/cline/cline/blob/main/sdk/examples/cron/README.md)
## 常见问题
### API 请求无响应
部分用户报告使用 DeepSeek 等提供商时出现请求无限加载的问题。可能原因包括网络连接问题或 API 提供商限制。建议检查 API 余额和连接状态。 资料来源：[社区问题 #1157](https://github.com/cline/cline/issues/1157)
### LM Studio 上下文大小问题
使用 LM Studio 作为 API 提供商时，模型可能无法正确报告上下文大小。 资料来源：[社区问题 #11158](https://github.com/cline/cline/issues/11158)
### Kimi API 限制
Kimi For Coding 目前仅对特定的编程代理开放，使用时可能返回 403 错误。 资料来源：[社区问题 #10307](https://github.com/cline/cline/issues/10307)
## 下一步
- 查看 [CLI 完整文档](./cli-overview.mdx)
- 了解 [IDE 扩展功能](./ide.mdx)
- 探索 [SDK 示例](../examples/)
- 学习 [插件开发](../examples/plugins/)
---
## Hub-Spoke 架构
### 相关页面
相关主题：[gRPC 通信协议](#communication-protocol), [SDK 概览与核心 API](#sdk-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/sdk/architecture/overview.mdx](https://github.com/cline/cline/blob/main/docs/sdk/architecture/overview.mdx)
- [docs/sdk/architecture/hub-spoke.mdx](https://github.com/cline/cline/blob/main/docs/sdk/architecture/hub-spoke.mdx)
- [sdk/packages/core/src/hub/index.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/hub/index.ts)
- [sdk/apps/cline-hub/src/server/hub.ts](https://github.com/cline/cline/blob/main/sdk/apps/cline-hub/src/server/hub.ts)
- [sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
- [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [apps/vscode/src/hosts/host-provider.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/hosts/host-provider.ts)
# Hub-Spoke 架构
Hub-Spoke 架构是 Cline SDK 的核心通信模型，用于协调多个客户端（Spoke）与中央服务（Hub）之间的连接、会话管理和事件分发。该架构支撑了 Cline Hub 的所有功能，包括实时通知推送、跨客户端会话同步以及后台任务调度。
## 架构概述
Hub-Spoke 模型采用星型拓扑结构，所有客户端（CLI、VS Code 扩展、桌面应用等）作为 Spoke 节点连接到中央 Hub 服务。这种设计将复杂的分布式通信逻辑集中在 Hub 端，简化了客户端的实现复杂度，同时保证了事件分发的一致性和实时性。
```mermaid
graph TD
A[Hub Server
@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](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
## 核心组件
### Hub Server
Hub Server 是整个架构的中心节点，负责管理所有客户端连接、处理事件分发和维护会话状态。它基于 WebSocket 协议实现双向通信，支持广播通知和点对点消息传递。
| 组件路径 | 职责说明 |
|---------|---------|
| `sdk/packages/core/src/hub/index.ts` | Hub 模块的核心导出和类型定义 |
| `sdk/apps/cline-hub/src/server/hub.ts` | Hub 服务器实现，包含连接管理和事件处理逻辑 |
Hub Server 提供以下核心能力：
- **连接管理**：维护客户端连接池，处理连接建立和断开
- **事件广播**：将 UI 事件（如 `ui.notify`、`ui.show_window`）广播给所有订阅者
- **会话追踪**：记录活动会话并提供运行时状态监控
- **权限控制**：支持 local、LAN 和 tunnel 三种访问模式，通过 room secret 进行鉴权
资料来源：[sdk/packages/core/src/hub/index.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/hub/index.ts)
### 客户端 Host
客户端（Host）是连接到 Hub 的 Spoke 节点。VS Code 扩展中的 Host Provider 负责管理与 Hub 的连接生命周期。
```typescript
// 简化的 Host Provider 架构
interface HostProvider {
connect(hubUrl: string): Promise;
sendEvent(event: UiEvent): void;
onNotification(handler: (msg: string) => void): void;
}
```
资料来源：[apps/vscode/src/hosts/host-provider.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/hosts/host-provider.ts)
## 通信协议
Hub 与 Spoke 之间通过 WebSocket 协议进行通信，事件消息采用 JSON 格式序列化。
### 事件类型
| 事件名称 | 方向 | 说明 |
|---------|------|------|
| `ui.notify` | Hub → Spoke | 推送通知到客户端 |
| `ui.show_window` | Hub → Spoke | 请求客户端显示窗口 |
| `hub_state` | Hub → Spoke | 定期发送 Hub 状态心跳 |
| `ready` | Spoke → Hub | 客户端就绪确认 |
### 访问模式
Hub 支持三种访问级别，通过配置控制客户端的网络访问范围：
| 模式 | 访问范围 | 典型用途 |
|------|---------|---------|
| `local` | 仅本地进程 | 开发调试 |
| `lan` | 局域网内 | 团队共享使用 |
| `tunnel` | 通过隧道公网访问 | 远程工作场景 |
所有隧道模式的使用都通过 room secret 进行身份验证，确保只有授权客户端能够连接。
资料来源：[sdk/apps/examples/menubar/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
## 会话管理
Hub-Spoke 架构下的会话管理采用分布式存储与集中协调相结合的策略。
```mermaid
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](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
## Hub Monitor 功能
Hub Monitor 是 Hub 的监控和管理界面，提供实时状态可视化和会话控制能力。
### 主要功能
| 功能 | 说明 |
|------|------|
| Hub 状态监控 | 显示运行时间、连接客户端数量、活动会话数 |
| 会话追踪 | 列出所有运行中的会话并提供检查器 |
| 事件日志 | 记录最近的 UI 通知和后台事件 |
| 后台会话启动器 | 从 Web UI 发起新的后台任务 |
### 部署架构
```
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](https://github.com/cline/cline/blob/main/sdk/apps/examples/menubar/README.md)
## 与 SDK 包的关系
Hub-Spoke 架构是 `@cline/core` 包的核心功能之一，该包负责状态化的运行时编排。
| 包名 | 职责 | 与 Hub 的关系 |
|------|------|---------------|
| `@cline/shared` | 跨包共享原语和类型 | Hub 使用共享类型定义 |
| `@cline/llms` | 模型目录和提供商 | Hub 可调度 LLM 任务 |
| `@cline/agents` | 无状态 Agent 运行时 | Hub 启动和管理 Agent |
| `@cline/core` | 状态化运行时编排 | Hub 的实现位置 |
资料来源：[sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
## 配置与使用
### 启动 Hub
Hub 可作为独立服务启动，支持以下配置选项：
```bash
# 环境变量配置
CLINE_HUB_PORT=8080 # Hub 监听端口
CLINE_HUB_SECRET=xxx # Room secret 用于鉴权
CLINE_HUB_MODE=lan # 访问模式: local|lan|tunnel
```
### 客户端连接
客户端通过配置 Hub URL 建立连接：
```typescript
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](https://github.com/cline/cline/issues/1157)、[GitHub Issue #1959](https://github.com/cline/cline/issues/1959)
## 相关资源
- [SDK 架构总览](./overview.mdx) — SDK 整体架构说明
- [@cline/core API 参考](https://docs.cline.bot/sdk/reference/cline-core) — Hub 相关 API 文档
- [Cline Hub 官方文档](https://docs.cline.bot) — Hub 安装和配置指南
---
## gRPC 通信协议
### 相关页面
相关主题：[Hub-Spoke 架构](#hub-spoke-architecture), [检查点与历史管理](#checkpoints)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/vscode/proto/cline/task.proto](https://github.com/cline/cline/blob/main/apps/vscode/proto/cline/task.proto)
- [apps/vscode/proto/cline/state.proto](https://github.com/cline/cline/blob/main/apps/vscode/proto/cline/state.proto)
- [apps/vscode/src/core/controller/grpc-handler.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/controller/grpc-handler.ts)
- [apps/vscode/src/hosts/vscode/hostbridge-grpc-handler.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/hosts/vscode/hostbridge-grpc-handler.ts)
- [sdk/packages/core/src/hub/server/handlers/run-handlers.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/hub/server/handlers/run-handlers.ts)
# gRPC 通信协议
## 概述
Cline 项目采用 gRPC 作为核心组件间通信的基础协议，用于实现 VS Code 扩展宿主机与运行时核心、CLI 客户端与 Hub 服务之间的双向通信。gRPC 的使用使得 Cline 能够在 VS Code 扩展、CLI 应用和远程 Hub 服务之间建立高效的远程过程调用通道。
## 架构设计
### 通信层次
Cline 的 gRPC 通信分为两个主要层次：
```mermaid
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 文件：
| 文件 | 用途 | 主要消息类型 |
|------|------|-------------|
| `task.proto` | 任务调度与执行协议 | TaskRequest, TaskResponse, TaskStatus |
| `state.proto` | 状态同步与变更协议 | StateUpdate, StateSnapshot, StateDiff |
## Proto 消息定义
### Task 协议 (task.proto)
Task 协议负责处理任务的创建、调度和执行状态的跟踪。
```protobuf
// 任务请求消息
message TaskRequest {
string task_id = 1;
string session_id = 2;
TaskType type = 3;
bytes payload = 4;
map 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 协议负责在客户端和服务器之间同步运行时状态，包括会话状态、技能状态和规则配置。
```protobuf
// 状态更新消息
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 服务端点
- 处理任务请求的路由和分发
- 管理会话生命周期
- 处理错误和重试逻辑
```typescript
// 处理器初始化流程
class GrpcHandler {
private server: grpc.Server;
private services: Map;
async initialize(): Promise {
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` 充当扩展宿主与核心运行时之间的桥接层，负责协议转换和消息路由。
**桥接功能：**
| 功能 | 描述 | 数据流向 |
|------|------|----------|
| 协议转换 | 将 VS Code 消息转换为 gRPC 格式 | VS Code → gRPC |
| 状态同步 | 保持扩展端和核心端状态一致 | 双向同步 |
| 错误传播 | 将远程错误映射到本地异常 | Core → Extension |
| 心跳检测 | 监控连接健康状态 | 定期检测 |
```typescript
class HostBridgeGrpcHandler {
private bridge: HostBridge;
private grpcClient: GrpcClient;
async forward(request: VsCodeRequest): Promise {
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 客户端的任务执行请求。
**处理流程：**
```mermaid
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)
```
**核心端点：**
| 端点 | 方法 | 描述 |
|------|------|------|
| `/hub.RunHandler/Execute` | Unary | 单次任务执行 |
| `/hub.RunHandler/StreamExecute` | Server Streaming | 流式任务执行 |
| `/hub.RunHandler/Cancel` | Unary | 取消正在执行的任务 |
资料来源：[sdk/packages/core/src/hub/server/handlers/run-handlers.ts]()
## 通信流程
### 任务执行流程
```mermaid
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
```
### 状态同步流程
状态同步采用版本化的差异同步机制，确保客户端和服务器之间的状态一致性。
```mermaid
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 支持功能：
| 功能 | gRPC 接口 | 描述 |
|------|-----------|------|
| 会话监控 | `WatchSession` | 实时监控会话状态变化 |
| 流式输出 | `StreamOutput` | 将助手输出流式传输到客户端 |
| 远程重启 | `RestartHub` | 远程重启本地 Hub 服务 |
| 规则管理 | `GlobalRules` | 跨会话应用全局代理规则 |
### 房间密钥认证
Hub 服务的访问通过房间密钥（Room Secret）进行保护：
| 访问模式 | 认证要求 | 用途 |
|----------|----------|------|
| Local | 无需认证 | 本机直接访问 |
| LAN | 房间密钥 | 局域网内远程访问 |
| Tunnel | 房间密钥 | 通过隧道远程访问 |
## 错误处理
### 错误码定义
| 错误码 | 含义 | 处理建议 |
|--------|------|----------|
| `GRPC_UNAVAILABLE` | 服务不可用 | 检查网络连接和服务状态 |
| `GRPC_DEADLINE_EXCEEDED` | 请求超时 | 增加超时时间或重试 |
| `GRPC_UNAUTHENTICATED` | 认证失败 | 验证 API 密钥和房间密钥 |
| `GRPC_RESOURCE_EXHAUSTED` | 资源耗尽 | 等待或增加资源配额 |
### 重试策略
gRPC 处理器实现了自动重试机制：
```typescript
const retryConfig = {
maxRetries: 3,
initialDelay: 1000,
maxDelay: 10000,
backoffMultiplier: 2,
retryableCodes: [
grpc.status.UNAVAILABLE,
grpc.status.RESOURCE_EXHAUSTED
]
};
```
## 性能考虑
### 连接复用
gRPC 支持连接复用以减少连接建立的开销：
- **Keep-Alive**：保持长连接活跃
- **多路复用**：单个连接支持多个并发请求
- **流控制**：防止快速发送方压倒慢速接收方
### 流式处理
对于需要处理大量数据的场景（如文件差异查看、代码补全），使用服务端流式处理：
```typescript
// 流式任务执行
const stream = client.StreamExecute(request);
stream.on('data', (response) => {
process.stdout.write(response.chunk);
});
stream.on('end', () => {
console.log('Stream completed');
});
```
## 配置选项
### gRPC 服务配置
| 配置项 | 默认值 | 描述 |
|--------|--------|------|
| `grpc.port` | 50051 | gRPC 服务监听端口 |
| `grpc.host` | localhost | 服务绑定地址 |
| `grpc.keepalive` | 30000 | Keep-Alive 超时(ms) |
| `grpc.max_message_length` | 100MB | 最大消息长度 |
| `grpc.enable_reflection` | false | 启用 gRPC 反射 |
## 相关资源
- [Cline SDK 文档](https://docs.cline.bot/cline-sdk/overview)
- [Hub 服务架构](../ARCHITECTURE.md#hub-服务)
- [CLI 使用指南](../apps/cli/README.md)
---
## 代码编辑与文件系统操作
### 相关页面
相关主题：[Plan 与 Act 模式](#plan-act-modes), [检查点与历史管理](#checkpoints)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/vscode/src/core/assistant-message/diff.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/assistant-message/diff.ts)
- [apps/vscode/src/core/task/tools/handlers/WriteToFileToolHandler.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/task/tools/handlers/WriteToFileToolHandler.ts)
- [apps/vscode/src/core/task/tools/handlers/ReadFileToolHandler.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/task/tools/handlers/ReadFileToolHandler.ts)
- [apps/vscode/src/core/task/tools/utils/PatchParser.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/task/tools/utils/PatchParser.ts)
- [sdk/packages/core/src/extensions/tools/executors/apply-patch.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/extensions/tools/executors/apply-patch.ts)
# 代码编辑与文件系统操作
## 概述
Cline 的代码编辑与文件系统操作是智能编程助手的核心能力之一，支撑着 AI Agent 对代码库的读取、理解和修改操作。该模块负责处理文件读写、差异计算、Patch 生成与应用等关键功能，是实现自动化代码修改的基础设施。
从架构角度来看，文件系统操作模块处于 Task 系统的工具层（Tool Handler），与 LLM 的 tool_use 调用紧密配合。当 Agent 需要理解代码上下文时，通过 `read_file` 工具获取文件内容；当需要修改代码时，通过 `write_to_file` 或 `apply_patch` 工具执行变更。整个流程设计注重原子性、安全性和可追溯性，确保每次修改都能被验证和回滚。
## 核心组件架构
文件系统操作涉及多个相互协作的组件，每个组件承担特定职责。
| 组件 | 文件路径 | 职责 |
|------|---------|------|
| ReadFileToolHandler | `apps/vscode/src/core/task/tools/handlers/ReadFileToolHandler.ts` | 处理 `read_file` 工具调用，实现文件读取和缓存 |
| WriteToFileToolHandler | `apps/vscode/src/core/task/tools/handlers/WriteToFileToolHandler.ts` | 处理 `write_to_file` 工具调用，执行文件写入 |
| PatchParser | `apps/vscode/src/core/task/tools/utils/PatchParser.ts` | 解析 unified diff 格式的 Patch 字符串 |
| DiffGenerator | `apps/vscode/src/core/assistant-message/diff.ts` | 生成文件差异视图，展示修改内容 |
| ApplyPatchExecutor | `sdk/packages/core/src/extensions/tools/executors/apply-patch.ts` | 在 SDK 层执行 Patch 应用 |
这些组件形成了完整的文件操作闭环：从读取理解到修改生成，再到应用验证，每个环节都有专门的模块负责。
## 文件读取机制
### read_file 工具概述
`read_file` 是 Cline 中使用最频繁的工具之一，允许 Agent 读取指定文件的内容以理解代码上下文。在 v3.77.0 版本中，该工具新增了分块读取（chunked reading）支持，可以针对大文件进行有针对性的访问，避免一次性加载整个文件导致的性能问题。
文件读取还实现了读取去重缓存机制（v3.74.0 引入），在处理多轮对话时避免对同一文件的重复读取操作，显著提升了处理大型代码库时的效率。
### 读取流程
```mermaid
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 确保写入操作的原子性，在写入失败时能够保留原始文件内容。
### 写入流程
```mermaid
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 格式的字符串解析为可执行的操作序列。解析过程包括提取文件路径、识别变更类型（新增、删除、修改）、解析行号范围和内容差异。
```mermaid
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 实际应用到文件系统中。执行过程遵循以下原则：
| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 读取原始文件 | 如果是修改操作，需要读取现有内容 |
| 2 | 验证 hunk 应用条件 | 确保文件未被修改，hunk 行号准确 |
| 3 | 应用每个 hunk | 按顺序将变更写入新文件 |
| 4 | 原子替换 | 使用临时文件确保一致性 |
| 5 | 返回结果 | 报告成功或具体的失败原因 |
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。该机制监控工具调用的模式，当检测到重复执行相同操作时会发出警告或终止执行。
## 配置与优化
### 文件读取配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| maxFileReadSize | 10000 | 单次读取的最大行数 |
| enableChunkedReading | true | 是否启用分块读取 |
| cacheEnabled | true | 是否启用读取缓存 |
| cacheSize | 100 | 缓存文件的最大数量 |
### 文件写入配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| createBackup | true | 写入前是否创建备份 |
| atomicWrite | true | 是否使用原子写入 |
| autoCreateDir | true | 是否自动创建父目录 |
### 性能优化建议
1. **合理使用分块读取**：对于大型文件，指定具体的行范围而非读取全部内容
2. **利用缓存机制**：避免在同一对话中重复读取相同文件
3. **批量操作**：将多个相关修改组织为单一 Patch 一次性应用
4. **限制并发**：避免同时进行大量文件操作以减少 I/O 压力
## 与其他模块的交互
文件系统操作模块与多个核心模块紧密协作：
```mermaid
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 只能识别第一个目录的文件。用户期待能够同时操作不同目录下的文件。
2. **MCP 服务器日志可见性**（Issue #1959）：MCP 服务器运行时会输出 stderr 日志，但 Cline 目前没有提供查看这些日志的用户界面，影响了调试体验。
3. **LM Studio 上下文大小报告**：使用 LM Studio 作为 API 提供者时，模型上下文大小报告可能不准确，需要用户手动验证。
## 最佳实践
1. **验证后再修改**：使用 `read_file` 确认文件当前状态后再进行修改
2. **使用 Patch 进行批量变更**：多个相关修改建议打包为单一 Patch 应用
3. **注意备份**：重要文件修改前确认备份机制已启用
4. **理解边界**：熟悉文件操作工具的能力边界，避免超出设计范围的操作
## 参考资料
- 文件读取处理器：[ReadFileToolHandler.ts](apps/vscode/src/core/task/tools/handlers/ReadFileToolHandler.ts)
- 文件写入处理器：[WriteToFileToolHandler.ts](apps/vscode/src/core/task/tools/handlers/WriteToFileToolHandler.ts)
- Patch 解析器：[PatchParser.ts](apps/vscode/src/core/task/tools/utils/PatchParser.ts)
- 差异生成器：[diff.ts](apps/vscode/src/core/assistant-message/diff.ts)
- Patch 执行器：[apply-patch.ts](sdk/packages/core/src/extensions/tools/executors/apply-patch.ts)
---
## Plan 与 Act 模式
### 相关页面
相关主题：[代码编辑与文件系统操作](#code-editing)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/vscode/src/core/prompts/system-prompt/components/act_vs_plan_mode.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/prompts/system-prompt/components/act_vs_plan_mode.ts)
- [apps/vscode/src/core/prompts/commands/deep-planning/index.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/prompts/commands/deep-planning/index.ts)
- [apps/vscode/src/core/task/tools/handlers/PlanModeRespondHandler.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/task/tools/handlers/PlanModeRespondHandler.ts)
- [apps/vscode/src/core/task/tools/handlers/ActModeRespondHandler.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/task/tools/handlers/ActModeRespondHandler.ts)
# Plan 与 Act 模式
## 概述
Cline 中的 Plan（计划）与 Act（执行）模式是控制智能体行为的核心机制，分别对应"规划优先"和"行动优先"两种不同的工作方式。这两种模式通过系统提示词组件和独立的任务响应处理器来实现，确保智能体在不同场景下能够按照预期的方式工作。
**Plan 模式**适用于需要先制定详细计划、评估方案可行性的场景，让用户在执行前有机会审查和调整行动方案。
**Act 模式**则直接执行任务，适用于用户已明确知道需要做什么、只需快速完成操作的场景。
这两种模式的存在解决了自动化代理系统中的核心矛盾：如何在"快速行动"与"谨慎规划"之间取得平衡。资料来源：[act_vs_plan_mode.ts:1-50]()
## 模式架构
Cline 的模式系统由以下核心组件构成：
```mermaid
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[任务完成]
```
### 核心组件职责
| 组件 | 职责 | 位置 |
|------|------|------|
| `act_vs_plan_mode.ts` | 定义模式系统提示词组件 | `apps/vscode/src/core/prompts/system-prompt/components/` |
| `PlanModeRespondHandler` | 处理计划模式下的响应逻辑 | `apps/vscode/src/core/task/tools/handlers/` |
| `ActModeRespondHandler` | 处理执行模式下的响应逻辑 | `apps/vscode/src/core/task/tools/handlers/` |
| `deep-planning` | 深度规划命令实现 | `apps/vscode/src/core/prompts/commands/` |
资料来源：[PlanModeRespondHandler.ts:1-30]()[ActModeRespondHandler.ts:1-30]()
## Plan 模式详解
### 工作流程
Plan 模式采用"提议-确认-执行"的交互范式。当用户启用计划模式时，智能体会先分析任务需求，生成详细的执行计划，并等待用户确认后再执行具体操作。
```mermaid
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 模式采用"直接执行"的交互范式。智能体在分析任务后直接执行工具调用，适用于需要快速响应的场景。
```mermaid
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]()
### 模式差异对比
| 特性 | Plan 模式 | Act 模式 |
|------|-----------|----------|
| 执行时机 | 用户确认后 | 即时执行 |
| 用户交互 | 高（需确认计划） | 低（自动执行） |
| 适用场景 | 复杂任务、高风险操作 | 简单任务、低风险操作 |
| 错误处理 | 用户决策 | 自动重试/调整 |
| 速度 | 较慢（需等待确认） | 快速（自动推进） |
| 安全性 | 高（用户可控） | 中（自动执行） |
资料来源：[act_vs_plan_mode.ts:150-200]()
## Deep Planning 深度规划
### 功能概述
Deep Planning 是 Cline 提供的深度规划命令，用于在 Plan 模式基础上进行更深入的需求分析和方案设计。当任务较为复杂或涉及多个子任务时，普通计划模式可能不足以覆盖所有细节，此时可以使用深度规划功能。
深度规划会：
1. **多轮分析**：对用户需求进行多角度、深层次的分析
2. **依赖识别**：识别任务间的依赖关系和执行顺序
3. **风险评估**：评估每个步骤的潜在风险和备选方案
4. **资源规划**：考虑执行所需的时间和工具资源
资料来源：[deep-planning/index.ts:1-50]()
### 使用方式
深度规划通过专门的命令接口触发，用户可以通过以下方式调用：
```bash
/deep-planning
```
或者在智能体对话中请求使用深度规划模式。深度规划会生成一份更详尽的执行计划文档，包含但不限于：
- 任务分解结构
- 每个子任务的具体要求
- 预期的执行时间线
- 可能的失败场景及应对策略
资料来源：[deep-planning/index.ts:50-150]()
## 模式切换与触发
### 手动切换
用户可以在任务执行过程中手动切换模式：
| 操作 | 方式 |
|------|------|
| 切换到 Plan 模式 | 使用 `/plan` 命令或界面按钮 |
| 切换到 Act 模式 | 使用 `/act` 命令或界面按钮 |
| 触发深度规划 | 使用 `/deep-planning` 命令 |
### 自动切换
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. **快速验证**：验证某个想法或假设
### 模式使用建议
| 经验水平 | 建议模式 | 原因 |
|----------|----------|------|
| 初学者 | 优先 Plan 模式 | 便于理解系统行为，避免意外操作 |
| 中级用户 | 根据场景选择 | 简单任务用 Act，复杂任务用 Plan |
| 高级用户 | 灵活切换 | 在 Plan 和 Act 间快速切换以优化效率 |
## 技术实现细节
### 系统提示词注入机制
模式系统通过向智能体的系统提示词注入特定组件来实现行为差异：
```typescript
// 伪代码示例
const systemPromptComponents = [
...baseComponents,
...(mode === 'plan' ? planModeComponents : []),
...(mode === 'act' ? actModeComponents : []),
];
```
这些组件会在对话开始时注入，并影响整个对话过程中智能体的行为。资料来源：[act_vs_plan_mode.ts:200-250]()
### 响应处理器注册
PlanModeRespondHandler 和 ActModeRespondHandler 通过工厂模式注册到任务工具系统中：
```typescript
const respondHandlers = {
plan: new PlanModeRespondHandler(),
act: new ActModeRespondHandler(),
};
```
系统根据当前模式选择对应的处理器来处理智能体响应。资料来源：[PlanModeRespondHandler.ts:100-150]()[ActModeRespondHandler.ts:100-150]()
## 更新历史
| 版本 | 更新内容 |
|------|----------|
| v3.77.0 | 添加"Lazy Teammate Mode"实验性切换 |
| 早期版本 | 基础 Plan/Act 模式实现 |
社区反馈表明，用户对 Plan 和 Act 模式的灵活切换有较高需求，特别是希望能够在执行过程中根据任务复杂度动态调整模式设置。
---
## 检查点与历史管理
### 相关页面
相关主题：[代码编辑与文件系统操作](#code-editing), [gRPC 通信协议](#communication-protocol)
相关源码文件
以下源码文件用于生成本页说明：
- [apps/vscode/src/integrations/checkpoints/index.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/integrations/checkpoints/index.ts)
- [apps/vscode/src/core/controller/checkpoints/checkpointDiff.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/controller/checkpoints/checkpointDiff.ts)
- [apps/vscode/src/core/controller/checkpoints/checkpointRestore.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/controller/checkpoints/checkpointRestore.ts)
- [apps/vscode/src/core/controller/task/getTaskHistory.ts](https://github.com/cline/cline/blob/main/apps/vscode/src/core/controller/task/getTaskHistory.ts)
- [sdk/packages/core/src/session/checkpoint-restore.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/session/checkpoint-restore.ts)
# 检查点与历史管理
## 概述
检查点（Checkpoint）与历史管理是 Cline 系统中用于保存和恢复会话状态的核心功能。该系统允许用户在任何时刻保存当前工作状态，并在需要时完整恢复到该状态，包括文件系统的变更、对话历史、工具调用记录等。这对于长时间运行的任务、自动化工作流以及需要暂停和恢复的复杂开发场景至关重要。
Cline 的检查点系统由 VS Code 扩展端的集成层和 SDK 核心层的会话管理模块共同实现。VS Code 扩展负责创建、检查点差异计算和状态恢复功能，而 SDK 核心层提供了可复用的检查点与恢复 API，供 CLI、桌面应用及其他集成使用。
## 架构设计
### 核心组件
检查点与历史管理涉及多个协同工作的组件：
| 组件 | 位置 | 职责 |
|------|------|------|
| 检查点集成模块 | `apps/vscode/src/integrations/checkpoints/index.ts` | VS Code 扩展的检查点入口点，协调检查点操作 |
| 差异计算模块 | `apps/vscode/src/core/controller/checkpoints/checkpointDiff.ts` | 计算当前状态与检查点之间的差异 |
| 恢复模块 | `apps/vscode/src/core/controller/checkpoints/checkpointRestore.ts` | 执行从检查点恢复操作 |
| 历史获取模块 | `apps/vscode/src/core/controller/task/getTaskHistory.ts` | 获取和管理任务历史记录 |
| 会话检查点 | `sdk/packages/core/src/session/checkpoint-restore.ts` | SDK 核心层的检查点与恢复逻辑 |
### 数据流架构
```mermaid
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` 模块提供了任务历史的查询接口。每个任务记录包含：
| 字段 | 描述 |
|------|------|
| taskId | 任务的唯一标识符 |
| createdAt | 任务创建时间 |
| updatedAt | 最后更新时间 |
| status | 当前状态（进行中、已完成、已取消） |
| checkpoints | 关联的检查点列表 |
| workspaceRoot | 工作区根路径 |
| summary | 任务摘要信息 |
### 自动化中的状态持久化
在 Cline 的自动化功能中，检查点概念通过 `notesDirectory` 字段得到延伸。定时任务和事件驱动任务可以使用持久化笔记目录来维护多轮运行之间的状态：
```yaml
---
id: daily-code-review
title: Daily Code Review
workspaceRoot: /path/to/repo
schedule: "0 9 * * MON-FRI"
mode: act
notesDirectory: .cline/automation-notes
---
```
这种设计允许：
- **跨会话状态共享**：不同运行之间传递上下文
- **增量处理**：后续运行可以读取前次运行的结果
- **故障恢复**：任务中断后可以从上次状态继续
## SDK 集成
### checkpoint-restore.ts API
`sdk/packages/core/src/session/checkpoint-restore.ts` 导出了核心的检查点与恢复功能，供 SDK 使用者集成到自己的应用中：
- **createCheckpoint(sessionId)**：为指定会话创建检查点
- **restoreCheckpoint(checkpointId)**：从检查点恢复会话
- **listCheckpoints(filter?)**：列出可用的检查点
- **deleteCheckpoint(checkpointId)**：删除不再需要的检查点
- **getCheckpointDiff(from, to)**：获取两个检查点之间的差异
这些 API 设计遵循一致性原则，确保不同客户端（CLI、桌面应用、自动化脚本）具有统一的检查点行为。
### 会话生命周期
检查点与恢复功能深度集成在 Cline 的会话生命周期管理中：
```mermaid
stateDiagram-v2
[*] --> 活跃会话: 创建新会话
活跃会话 --> 检查点创建: 用户保存
活跃会话 --> 已完成: 任务结束
活跃会话 --> 已暂停: 会话中断
检查点创建 --> 活跃会话: 继续工作
已暂停 --> 活跃会话: 恢复会话
已完成 --> 检查点创建: 从历史恢复
检查点创建 --> [*]: 删除
已完成 --> [*]: 清理
```
## 使用场景
### 长时间任务
对于需要数小时甚至数天完成的任务，用户可以：
1. 在关键里程碑处创建检查点
2. 关闭 IDE 或终端，不丢失进度
3. 稍后恢复并从上次位置继续
### 自动化工作流
自动化任务可以利用检查点实现：
- **断点续传**：长时间运行的自动化任务支持中断恢复
- **状态传递**：通过 `notesDirectory` 在多次运行间共享数据
- **历史审计**：查看每次自动化运行的结果和变更
### 实验性更改
在尝试有风险的代码修改时：
1. 先创建检查点保存当前状态
2. 执行实验性修改
3. 如果结果不理想，一键恢复到检查点
4. 避免了手动撤销大量变更的麻烦
## 相关资源
- [SDK 核心包](../packages/core/README.md) - 会话管理与运行时编排
- [CLI 文档](../apps/cli/README.md) - 命令行检查点操作
- [自动化配置](./cron/README.md) - 使用 notesDirectory 实现状态持久化
---
*最后更新：基于 Cline 源码库最新版本*
---
## SDK 概览与核心 API
### 相关页面
相关主题：[插件开发指南](#plugin-development), [自定义工具开发](#tool-creation), [Hub-Spoke 架构](#hub-spoke-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [sdk/README.md](https://github.com/cline/cline/blob/main/sdk/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/packages/agents/README.md](https://github.com/cline/cline/blob/main/sdk/packages/agents/README.md)
- [sdk/packages/llms/README.md](https://github.com/cline/cline/blob/main/sdk/packages/llms/README.md)
- [sdk/examples/README.md](https://github.com/cline/cline/blob/main/sdk/examples/README.md)
- [sdk/examples/plugins/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/README.md)
- [sdk/apps/examples/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/README.md)
# SDK 概览与核心 API
## 概述
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 至关重要。以下表格展示了各包的职责范围和典型消费者：
| 包名 | 主要职责 | 典型消费者 | 内部依赖 |
|------|----------|------------|----------|
| `@cline/shared` | 跨包共享原语（路径解析、会话通用类型、索引辅助函数） | `@cline/agents`、`@cline/core`、应用层 | 无 |
| `@cline/llms` | 模型目录、提供商设置 schema、handler 创建 SDK | `@cline/agents`、`@cline/core`、应用层 | 无 |
| `@cline/agents` | 无状态代理运行时循环（工具、钩子、扩展、团队、流式处理） | `@cline/core`、应用层 | `@cline/llms`、`@cline/shared` |
| `@cline/core` | 有状态运行时编排（运行时组合、会话生命周期/存储、本地和 Hub 运行时服务、Hub 发现和客户端辅助函数） | CLI/桌面应用 | `@cline/agents`、`@cline/llms`、`@cline/shared` |
资料来源：[sdk/packages/README.md]()
### 包协作流程
```mermaid
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`：
```ts
new Agent({
providerId: "openai",
modelId: "gpt-5",
apiKey: process.env.OPENAI_API_KEY,
// baseUrl, headers 也支持
tools: [/* ... */],
});
```
**Model 形式**面向高级用户，直接提供预构建的 `AgentModel`。当你已经拥有 gateway 构建逻辑时（这是 `@cline/core` 内部使用的方式）这很有用：
```ts
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` 接口，每个工具都有 JSON Schema 格式的 `inputSchema` 和返回工具输出的 `execute(input, context)` 函数：
```ts
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(...)` 可以创建一个小型注册表，包含配置的提供商及其默认模型、内置提供商发现以及自定义提供商注册功能：
```ts
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](https://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 的访问：
```bash
# 交互式代理
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 包：
```bash
cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/weather-metrics.ts
cline plugin install ./examples/plugins/agents-squad
```
资料来源：[sdk/examples/README.md]()
### 插件类型
SDK 提供了多种插件类型，每种都有不同的使用场景：
| 插件类型 | 功能 | 示例 |
|----------|------|------|
| 天气查询 | 外部 API 集成 | `weather-metrics.ts` |
| macOS 通知 | 系统集成 | `mac-notify.ts` |
| 自定义压缩 | 上下文管理 | `custom-compaction.ts` |
| 自动化事件 | 事件驱动 | `automation-events.ts` |
| 后台终端 | 长时间任务 | `background-terminal.ts` |
### TypeScript LSP 插件示例
TypeScript LSP 插件提供了一个 `goto_definition` 工具，由 TypeScript Language Service API 驱动。与文本搜索不同，它通过导入、重导出、类型别名和声明合并解析符号——与 IDE 的工作方式相同：
```bash
cline plugin install https://github.com/cline/cline/blob/main/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` 并行度限制。
```yaml
---
id: pr-security-review
title: Security Review for PRs
workspaceRoot: /path/to/repo
event: github.pull_request.opened
filters:
pullRequest:
baseBranch: main
cooldownSeconds: 300
maxParallel: 3
---
Summarize the changes, check for security risks, and recommend approval or changes.
```
## 快速入门示例
### 入门级示例
SDK 提供了从简单到复杂的工作示例：
| 示例 | 描述 | 核心概念 |
|------|------|----------|
| quickstart | 发送一次提示并流式传输响应，约 15 行代码 | `Agent`、`subscribe`、`run()` |
| cli-agent | 带 shell 工具的交互式终端聊天 | `createTool`、多轮 `run()`/`continue()`、流式处理 |
| cline-core-cli-agent | 由 ClineCore 驱动的交互式终端聊天 | `ClineCore.create()`、`cline.start()`、`cline.send()`、内置工具、流式处理 |
运行任何示例：
```bash
cd apps/examples/
bun install
bun run build:sdk
export CLINE_API_KEY="cline_..."
bun dev
```
需要 Node.js 22+。
资料来源：[sdk/apps/examples/README.md]()
### 代码审查机器人示例
代码审查机器人是一个 AI 驱动的 GitHub PR 审查仪表板，功能包括：获取真实 GitHub PR 的元数据、变更文件和补丁；渲染带有文件导航、差异视图、审查通道和问题卡片的 PR；将真实 PR 差异发送给带有三个自定义工具的代理（`get_file_context`、`add_review_finding` 等）。
## 安装与配置
### 安装 SDK
```bash
npm install @cline/sdk
```
对于 `@cline/llms` 单独使用：
```bash
npm install @cline/llms zod
```
### 环境变量配置
需要设置的主要环境变量：
| 变量 | 说明 | 必需 |
|------|------|------|
| `CLINE_API_KEY` | Cline API 密钥 | 是 |
| `GITHUB_TOKEN` | GitHub 个人访问令牌 | 推荐（私有仓库必需） |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | 使用 Claude 时必需 |
| `OPENAI_API_KEY` | OpenAI API 密钥 | 使用 GPT 时必需 |
| `EXA_API_KEY` | Exa API 密钥 | 使用 Web 搜索工具时必需 |
| `ENABLE_GITHUB_REVIEW_POSTING` | 启用发布审查到 GitHub | 可选 |
## 相关资源
- [官方文档](https://docs.cline.bot/cline-sdk/overview)
- [构建指南](https://docs.cline.bot/sdk/guides/building-an-agent)
- [架构概览](https://docs.cline.bot/sdk/architecture/overview)
- [API 参考](https://docs.cline.bot/sdk/reference/cline-core)
- [Discord 社区](https://discord.gg/cline)
- [贡献指南](../CONTRIBUTING.md)
---
## 插件开发指南
### 相关页面
相关主题：[SDK 概览与核心 API](#sdk-overview), [自定义工具开发](#tool-creation)
相关源码文件
以下源码文件用于生成本页说明：
- [sdk/examples/plugins/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/README.md)
- [sdk/examples/plugins/typescript-lsp/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/typescript-lsp/README.md)
- [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/agents-squad/README.md)
- [sdk/examples/cron/README.md](https://github.com/cline/cline/blob/main/sdk/examples/cron/README.md)
- [sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
- [sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
- [sdk/apps/examples/README.md](https://github.com/cline/cline/blob/main/sdk/apps/examples/README.md)
# 插件开发指南
本文档介绍如何在 Cline 平台中开发、安装和管理插件。插件是扩展 Cline CLI 和 SDK 功能的主要方式，允许开发者添加自定义工具、集成外部服务、注册生命周期钩子，以及实现后台自动化任务。
## 插件系统概述
### 什么是 Cline 插件
Cline 插件是一个 TypeScript 模块，通过 `AgentPlugin` 接口向 Cline 运行时注册自定义功能。插件可以：
- 注册自定义工具（Tools），供 Agent 在对话中调用
- 监听 Agent 生命周期事件（Hooks）
- 参与系统提示词构建（Rules）
- 实现自动化任务触发器
- 贡献静态或动态的配置内容
资料来源：[sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
### 插件与 SDK 的关系
Cline SDK 提供了一套完整的 TypeScript API，插件系统构建于其之上。以下是相关包的职责划分：
| 包名 | 职责 | 插件消费者 |
|------|------|-----------|
| `@cline/shared` | 跨包共享原语（路径解析、会话类型、索引助手） | `@cline/agents`、`@cline/core`、apps |
| `@cline/llms` | 模型目录 + 提供商设置模式 + 处理器创建 | `@cline/agents`、`@cline/core`、apps |
| `@cline/agents` | 无状态 Agent 运行时循环（工具、钩子、扩展、团队、流式处理） | `@cline/core`、apps |
| `@cline/core` | 有状态运行时编排（运行时组合、会话生命周期/存储、本地和 Hub 运行时服务） | CLI/Desktop apps |
资料来源：[sdk/packages/README.md](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
## 插件架构
### 插件加载机制
Cline 采用多层次插件发现和加载机制：
```mermaid
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](https://github.com/cline/cline/blob/main/sdk/examples/plugins/README.md)
### 插件沙箱机制
插件在隔离的沙箱环境中执行，确保主运行时不受插件代码影响。沙箱提供：
- 安全的模块作用域隔离
- 插件资源的生命周期管理
- 错误边界和恢复机制
### 插件自动发现路径
CLI 自动从以下位置发现插件：
| 搜索路径 | 说明 |
|---------|------|
| `$(pwd)/.cline/plugins` | 工作区本地插件 |
| `~/.cline/plugins` | 用户级全局插件 |
| 系统 Plugins 文件夹 | 安装时配置的系统路径 |
资料来源：[sdk/examples/plugins/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/README.md)
## 创建插件
### 插件基本结构
每个 Cline 插件必须导出一个符合 `AgentPlugin` 接口的对象：
```typescript
import type { AgentPlugin } from "@cline/core";
const plugin: AgentPlugin = {
name: "插件名称",
manifest: {
capabilities: ["tools", "hooks", "rules"], // 声明插件能力
},
setup(api) {
// 注册工具、钩子、规则等
},
teardown?: () => void, // 可选清理函数
};
```
### 创建自定义工具
工具是 Agent 与外部系统交互的主要方式。使用 `createTool()` 函数创建工具：
```typescript
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()` 方法中注册工具：
```typescript
setup(api) {
api.registerTool(myTool);
}
```
资料来源：[sdk/apps/cli/README.md](https://github.com/cline/cline/blob/main/sdk/apps/cli/README.md)
### 工具输入模式
工具的 `inputSchema` 采用 JSON Schema 格式，支持以下类型：
| 类型 | 说明 | 示例 |
|------|------|------|
| `string` | 字符串参数 | `"hello"` |
| `number` | 数值参数 | `42`, `3.14` |
| `integer` | 整数参数 | `100` |
| `boolean` | 布尔参数 | `true`/`false` |
| `array` | 数组参数 | `["a", "b", "c"]` |
| `object` | 对象参数 | `{key: "value"}` |
每个参数可指定：
- `type`：数据类型（必需）
- `description`：参数用途说明
- `required`：是否必需
- `default`：默认值
### 工具执行上下文
工具执行函数接收两个参数：
```typescript
async execute(input: T, context: ToolExecutionContext) {
// input: 经过验证的输入参数
// context: 执行上下文
}
```
`ToolExecutionContext` 提供：
- `agentId`：当前 Agent ID
- `sessionId`：当前会话 ID
- `workspaceRoot`：工作区根目录
- `abortSignal`：取消信号
## 插件能力系统
### 声明插件能力
插件在 `manifest.capabilities` 中声明其提供的功能：
```typescript
manifest: {
capabilities: ["tools"], // 提供工具
// capabilities: ["hooks"], // 提供钩子
// capabilities: ["rules"], // 提供规则
}
```
### 工具注册
```typescript
setup(api) {
api.registerTool(createTool({...}));
}
```
### 生命周期钩子
插件可以监听 Agent 生命周期事件：
```typescript
setup(api) {
api.registerHook("onToolCall", async (tool, input) => {
console.log(`Tool ${tool} called with:`, input);
});
api.registerHook("onResponse", async (response) => {
// 处理响应
});
}
```
### 规则注册
插件可以贡献系统提示词规则：
```typescript
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](https://github.com/cline/cline/blob/main/sdk/packages/README.md)
## 插件安装与分发
### 使用 CLI 安装插件
Cline CLI 提供 `plugin install` 命令安装插件：
```bash
# 从 GitHub 文件 URL 安装
cline plugin install https://github.com/cline/cline/blob/main/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` 目录。
### 插件安装命令参数
| 参数 | 说明 | 示例 |
|------|------|------|
| `--cwd ` | 指定工作目录 | `~/.cline/plugins` |
| 本地路径 | 本地 `.ts` 或 `.js` 文件 | `./plugins/weather.ts` |
| GitHub URL | 指向单个文件的 raw URL | GitHub raw 文件链接 |
| npm 包名 | 发布到 npm 的包 | `my-plugin` |
| Git 仓库 | Git 仓库 URL | `https://github.com/user/repo` |
资料来源：[sdk/examples/plugins/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/README.md)
### 插件列表与卸载
```bash
# 列出已安装插件
cline plugin list
# 卸载插件
cline plugin uninstall
```
## 插件示例
### 天气指标工具
最简单的插件示例，添加一个天气查询工具：
```typescript
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 实现精确的符号跳转：
```typescript
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](https://github.com/cline/cline/blob/main/sdk/examples/plugins/typescript-lsp/README.md)
### 多智能体团队插件
`agents-squad` 插件展示了如何在 Cline 中编排多个后台 Agent：
| 工具名称 | 功能描述 |
|---------|---------|
| `start_subagent` | 启动后台子 Agent |
| `message_subagent` | 向子 Agent 发送消息 |
| `get_subagent` | 获取子 Agent 状态和输出 |
| `list_agent_presets` | 列出捆绑的 Agent 预设 |
| `list_skills` | 发现可加载的技能指令 |
| `save_handoff` | 在子 Agent 间共享信息 |
预配置 Agent 列表：
| Agent 名称 | 模型 | 角色 |
|-----------|------|------|
| `phantom` | `google/gemini-3-flash-preview` | 快速代码库侦察 |
| `oracle` | `anthropic/claude-opus-4.6` | 架构规划 |
| `anvil` | `anthropic/claude-opus-4.6` | 精确实现 |
| `inquisitor` | `openai/gpt-5.5` | 对抗性审查 |
资料来源：[sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/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`）可以引用插件提供的工具和扩展：
```yaml
---
id: daily-security-audit
title: Daily Security Audit
workspaceRoot: /path/to/repo
schedule: "0 2 * * *" # 每天凌晨2点
tools: read_files, search_codebase
mode: act
timeoutSeconds: 3600
extensions:
- skills
---
Search for hardcoded secrets, outdated dependencies, and insecure patterns.
```
### 事件驱动任务中的插件
事件驱动任务（`.event.md`）响应 GitHub Webhook 或插件事件：
```yaml
---
id: pr-security-review
title: Security Review for PRs
event: github.pull_request.opened
filters:
pullRequest:
baseBranch: main
cooldownSeconds: 300
maxParallel: 3
---
Summarize the changes, check for security risks, and recommend approval or changes.
```
资料来源：[sdk/examples/cron/README.md](https://github.com/cline/cline/blob/main/sdk/examples/cron/README.md)
## 高级特性
### 插件资源管理
在 `setup()` 中注册的资源会在插件卸载时自动清理：
```typescript
const plugin: AgentPlugin = {
name: "resource-plugin",
setup(api) {
// 注册资源清理回调
api.onDispose(() => {
// 释放资源：关闭连接、清理定时器等
});
},
};
```
### 条件功能检测
插件可以检查运行时环境，决定是否注册特定功能：
```typescript
setup(api) {
// 检查平台支持
if (process.platform === "darwin") {
api.registerTool(macOSOnlyTool);
}
// 检查环境变量
if (process.env.MY_API_KEY) {
api.registerTool(apiTool);
}
}
```
### 错误处理
工具执行函数应返回结构化错误：
```typescript
async execute(input) {
try {
const result = await riskyOperation();
return { success: true, data: result };
} catch (error) {
return {
success: false,
error: error.message
};
}
}
```
## 最佳实践
### 插件命名规范
- 使用 kebab-case：`my-awesome-plugin`
- 包含功能前缀：`weather-metrics`、`ts-lsp`
- 避免与内置工具冲突
### 工具设计原则
| 原则 | 说明 |
|------|------|
| 单一职责 | 每个工具只做一件事 |
| 清晰描述 | `description` 准确说明工具用途和使用时机 |
| 最小参数 | 只暴露必需参数，提供合理默认值 |
| 幂等性 | 重复执行产生相同结果 |
| 错误处理 | 返回明确的成功/失败状态和原因 |
### 安全性考虑
- 敏感信息通过环境变量获取，不要硬编码
- 验证所有输入参数
- 限制工具的执行时间和资源使用
- 使用沙箱隔离执行环境
### 性能优化
- 复用连接和缓存
- 避免在工具中执行长时间阻塞操作
- 对于复杂操作，考虑使用后台任务
## 调试与故障排除
### 常见问题
**插件未加载**
- 检查插件文件语法是否正确
- 确认插件导出符合 `AgentPlugin` 接口
- 查看 CLI 日志中的错误信息
**工具不可见**
- 确认 `manifest.capabilities` 包含 `"tools"`
- 确认工具已在 `setup()` 中注册
- 检查工具名称是否与调用匹配
**依赖解析失败**
- 使用 `bun install` 安装依赖
- 确认插件使用的包在工作区中可用
- 考虑将依赖打包到插件中
### 日志调试
启用详细日志查看插件加载过程：
```bash
cline --verbose plugin install ./my-plugin.ts
```
## 相关资源
| 资源 | 链接 |
|------|------|
| SDK 文档 | https://docs.cline.bot/cline-sdk/overview |
| 插件示例仓库 | [sdk/examples/plugins/](https://github.com/cline/cline/tree/main/sdk/examples/plugins) |
| Cline Hub | https://cline.bot/join-us |
| 社区 Discord | https://discord.gg/cline |
---
如需了解定时任务和事件驱动自动化的详细内容，请参阅[自动化指南](./automation.md)。
---
## 自定义工具开发
### 相关页面
相关主题：[SDK 概览与核心 API](#sdk-overview), [插件开发指南](#plugin-development)
相关源码文件
以下源码文件用于生成本页说明：
- [sdk/packages/shared/src/tools/create.ts](https://github.com/cline/cline/blob/main/sdk/packages/shared/src/tools/create.ts)
- [sdk/packages/core/src/extensions/tools/definitions.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/extensions/tools/definitions.ts)
- [sdk/packages/core/src/extensions/tools/types.ts](https://github.com/cline/cline/blob/main/sdk/packages/core/src/extensions/tools/types.ts)
- [docs/sdk/guides/creating-custom-tools.mdx](https://github.com/cline/cline/blob/main/docs/sdk/guides/creating-custom-tools.mdx)
- [sdk/examples/plugins/typescript-lsp/index.ts](https://github.com/cline/cline/blob/main/sdk/examples/plugins/typescript-lsp/index.ts)
- [sdk/examples/plugins/weather-metrics.ts](https://github.com/cline/cline/blob/main/sdk/examples/plugins/weather-metrics.ts)
- [sdk/examples/plugins/agents-squad/README.md](https://github.com/cline/cline/blob/main/sdk/examples/plugins/agents-squad/README.md)
# 自定义工具开发
## 概述
Cline 的自定义工具（Custom Tools）是扩展 agent 能力的核心机制。通过 SDK 提供的 `createTool()` 函数，开发者可以注册自定义工具，让 agent 在执行任务时调用这些工具来完成特定操作。工具可以执行任意 JavaScript/TypeScript 代码，访问外部 API、操作文件系统、调用内部系统，或与第三方服务交互。
工具开发属于 Cline 插件体系的一部分，可通过 `cline plugin install` 命令安装到 CLI 或集成到 SDK 应用中。
## 工具架构
### 核心组件
Cline 工具系统由以下核心组件构成：
| 组件 | 职责 | 位置 |
|------|------|------|
| `createTool()` | 工具创建工厂函数 | `@cline/shared` |
| `AgentExtension` | 插件扩展接口，用于注册工具 | `@cline/core` |
| `ToolDefinition` | 工具定义类型 | `@cline/core` |
| `ToolCall` | 工具调用数据结构 | `@cline/shared` |
### 工具注册流程
```mermaid
graph TD
A[Plugin setup] --> B[获取 AgentExtension API]
B --> C[调用 api.registerTool]
C --> D[createTool 创建工具定义]
D --> E[Agent 运行时发现并调用工具]
E --> F[工具执行器返回结果]
F --> G[结果注入 agent 上下文]
```
## 工具定义结构
### 基本属性
```typescript
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 规范，支持以下类型：
| 类型 | 说明 | 示例 |
|------|------|------|
| `string` | 字符串参数 | `description`, `url` |
| `number` | 数字参数 | `limit`, `timeout` |
| `integer` | 整数参数 | `line` (行号) |
| `boolean` | 布尔参数 | `verbose`, `recursive` |
| `array` | 数组参数 | `paths`, `filters` |
| `object` | 嵌套对象参数 | 复杂配置 |
## 插件开发指南
### 插件结构
Cline 插件是一个导出 `AgentPlugin` 对象的 TypeScript 模块：
```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
```
### 完整示例：天气查询工具
以下是一个完整的自定义工具示例，实现天气和指标查询功能：
```typescript
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 实现精确的代码导航功能：
```typescript
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 协作能力，包含以下工具：
| 工具名 | 功能 |
|--------|------|
| `start_subagent` | 启动后台子 agent |
| `message_subagent` | 向子 agent 发送消息 |
| `get_subagent` | 获取子 agent 状态和输出 |
| `list_agent_presets` | 列出可用 agent 预设 |
| `list_skills` / `get_skill` | 发现和加载技能 |
| `save_handoff` / `read_handoff` | 子 agent 间共享文本 |
### 预置 Agent 角色
| Agent | 模型 | 职责 |
|-------|------|------|
| `phantom` | Gemini 3 Flash | 代码库结构探索，快速映射 |
| `oracle` | Claude Opus 4.6 | 架构规划，挑战假设 |
| `anvil` | Claude Opus 4.6 | 精准实现，读取后写入 |
| `inquisitor` | GPT-5.5 | 对抗性审查，发现 bug |
## 工具安装与使用
### CLI 安装
通过 `cline plugin install` 命令安装插件：
```bash
# 从 GitHub URL 安装
cline plugin install https://github.com/cline/cline/blob/main/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. 错误处理
```typescript
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 服务器对比
| 特性 | Cline 工具 | MCP 服务器 |
|------|-----------|-----------|
| 实现语言 | TypeScript/JavaScript | 任意（通过 stdio 通信） |
| 部署复杂度 | 低（单文件插件） | 高（需要托管服务） |
| 依赖管理 | npm 包或文件引用 | 独立进程管理 |
| 状态共享 | 插件内直接共享 | 需要外部机制 |
| 调试 | IDE 直接调试 | 需要查看 stderr 日志 |
社区中有用户反馈 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`
---
---
## Doramagic 踩坑日志
项目：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