Cursor CLI 编码任务执行

技能文档

---
name: cursor-agent-cli
title: Cursor CLI 编码任务执行
description: 在独立子进程中调用 Cursor Agent CLI（agent 命令）完成编码任务——写码、修复、重构、审查或方案规划，不消耗主会话的模型用量。当用户要求写代码、修 bug、重构、审查代码，并希望交给 Cursor 执行时触发；也适用于已知仓库中较大规模的文件修改任务。触发词：Cursor、cursor agent、交给 cursor 做、用 cursor 改代码、cursor 帮我审查。
category: 开发工具
---

# Cursor CLI 编码任务执行

通过 Cursor Agent CLI（`agent` 命令）以子进程方式执行编码任务，运行在用户自己的 Cursor 订阅上，不产生额外 API 费用。对于任何非平凡的编码任务，优先用它代替会话内直接生成。

## 前置条件

**必需二进制：`agent`**（Cursor Agent CLI）

从官方文档安装：https://cursor.com/docs/cli/overview ，安装后用 `agent --version` 验证。
辅助脚本（`scripts/run.sh`）在 `agent` 不在 PATH 中时会报错退出。

## 必须获得用户确认

本技能不得自主触发执行。每次调用都需要：

1. **先说明意图** —— 告知用户：目标仓库、任务内容、所用模型、是否会修改文件
2. **等待明确同意** —— 未经用户清晰批准不得执行
3. **默认只读** —— 使用 `run.sh <仓库> <任务> <模型> ask`，除非用户明确要求修改
4. **写文件之前** —— 先以 `ask` 模式运行并向用户展示计划，然后询问：「应用这些修改吗？」
5. **使用 `--cloud` 之前** —— 明确警告：「这会把仓库内容发送到 cursor.com，确定继续吗？」
6. **提交之前** —— 展示 diff 并获得确认

辅助脚本默认 `ask`（只读）。只有用户确认要应用修改后，才传 `write` 模式。

## 模型路由

| 任务类型 | 模型参数 | 模式参数 |
|---------|---------|---------|
| 简单 / 探索性 | （省略 —— `auto`） | （省略） |
| 修 bug / 功能 / 重构 | `--model sonnet-4.6` | （省略） |
| 代码审查 / 解释（只读） | `--model sonnet-4.6` | `--mode=ask` |
| 架构 / 方案规划 | `--model opus-4.6-thinking` | `--mode=plan` |
| 长时后台任务 | `--model sonnet-4.6` | 用 `--cloud` 代替 `-p` |

可用模型清单见 [references/models.md](references/models.md)。

## 技能工作流

### 步骤1：确认前置条件

确认 `agent` 命令可用（`agent --version`），确认目标仓库路径正确。

### 步骤2：向用户说明并获得确认

告知仓库、任务、模型与是否写文件，等待用户明确同意后才继续。

### 步骤3：以只读模式先跑一遍

**先只读** —— 始终先用 `--mode=ask` 审视方案再动手：

```bash
cd <repo> && agent -p "<task>" --model sonnet-4.6 --mode=ask --output-format text --trust
```

### 步骤4：用户确认后应用修改

**应用修改** —— 仅在用户确认方案后执行：

```bash
cd <repo> && agent -p "<task>" --model sonnet-4.6 --force --output-format text --trust
```

### 步骤5：云端/后台任务（可选）

**云端后台** —— 先警告用户仓库数据会发送到 cursor.com：

```bash
cd <repo> && agent -c "<task>" --model sonnet-4.6 --trust
# 进度查看：cursor.com/agents
```

### 步骤6：提交变更

Cursor 沙箱会拦截 `git commit`，因此在其编辑完成后手动提交：

```bash
cd <repo> && git add -A && git commit -m "<符合约定的提交信息>" && git push
```

改动较大或涉及敏感区域时，先向用户展示 diff 并确认。

### 步骤7：汇报结果

- `--output-format text` → 干净的最终回答，向用户总结关键变更
- `--output-format json` → 结构化输出，用于脚本解析
- 必须回报：改了什么、提交了什么、发现了什么问题

## 仓库与工作目录

- 运行前必须 `cd` 到正确的仓库
- 检查仓库根目录的 `.cursor/rules` 与 `AGENTS.md` —— Cursor 会自动加载它们作为项目上下文

## 上下文与会话

- 在提示词中用 `@<文件>` 把指定文件纳入上下文
- `--continue` 或 `--resume` 继续上一次会话
- `agent ls` 列出历史会话

## 参考

- 模型清单与说明：[references/models.md](references/models.md)
- 交互模式斜杠命令：[references/slash-commands.md](references/slash-commands.md)

使用说明

# Cursor CLI 编码任务执行

在子进程中调用 Cursor Agent CLI（`agent` 命令）完成写码、修复、重构、审查或规划任务，运行在用户自己的 Cursor 订阅上，不产生额外 API 费用。

## 适用场景

- 非平凡的编码任务：修 bug、加功能、重构
- 只读的代码审查与解释
- 架构与方案规划
- 长时后台编码任务（云端模式）

## 使用方式

对 AI 助手说：

```text
用 cursor 帮我修复这个仓库的登录 bug
交给 cursor 审查 src/auth 模块
用 cursor 规划这次数据库迁移方案
```

或直接用脚本：

```bash
scripts/run.sh <仓库路径> <任务> [模型] [模式]
# 模式：ask（默认只读）| plan | write（需用户先确认）
```

## 安全约定

- 默认只读（ask），写文件前必须展示方案并获得确认
- 云端模式会把仓库内容发送到 cursor.com，使用前必须警告
- 提交前展示 diff

## 前置条件

安装 Cursor Agent CLI：https://cursor.com/docs/cli/overview ，验证：`agent --version`

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。