cursor-cli（Hermes 调用 Cursor Agent）

Hermes 调 Cursor Agent CLI 的适配器。只管怎么启动、选模型、盯流式输出。

不管：写什么、写作口径、飞书写入 → 由调用方写作 skill 决定。

本机细节：若 references/local-*.md 存在，先读它（本机调用方 skill 与额外约束）。

When to Use

• 用户或其它 skill 说 cursor-cli / cursor-agent / Cursor 再写一版
• 调用方写作 skill 的第一稿和改稿
• writing-with-cursor：成篇文案 / 文档润色
• 用户明确说「交给 cursor / 让 cursor 写 / 用 cursor 改代码」的编码任务（见下方「编码任务」）
• 要把任务交给 Cursor CLI 而不是自己润色交差

不要用

• 操作 Cursor IDE 窗口 / 键鼠
• 只问「Cursor 是什么」
• 飞书短回复、确认、一句改（见 writing-with-cursor）
• 用户没点名 Cursor 的编码任务：Hermes 不自己决定外包

Prerequisites

• 二进制：~/.local/bin/cursor-agent（login zsh 里 cursor-cli 是它的 alias）
• Hermes 默认 非 login bash，看不到 alias
• 调用必须 zsh -lic（硬·2026-09-21）：解析用 zsh -lic 'whence -v cursor-cli'；真正跑也包进 zsh -lic，或直接 ~/.local/bin/cursor-agent。禁止在非 login shell 里 which cursor-cli 后宣称没有，再空等 --print。
• 必须后台 stream-json：禁止前台 --output-format text / 裸 --print 干等。jsonl 长时间 0 增长或只见 reconnect → kill。课例 2026-09-20 长文空转 34 分钟。

How to Run

1. 选模型（调用方没点名时走这条）：

python3 ${HERMES_SKILL_DIR}/scripts/pick_gemini_flash.py
# 打印一行，例如 gemini-3.8-flash-high；3.9 在 list 里就会打印 3.9

禁止写死带小版本的 Gemini id。picker 失败 → 告诉用户并按调用方降级。版本下限只在脚本 FLOOR，不要抄进 MEMORY。

2. 非交互 print + 流式（长任务默认；必须 zsh -lic 或绝对路径二进制）：

terminal(
  command="zsh -lic '~/.local/bin/cursor-agent --print --output-format stream-json --stream-partial-output --trust --force --sandbox disabled --model <id> --workspace <dir> --add-dir <extra> \"$(cat <prompt-file>)\"'",
  background=true
)

stdout 逐行落 jsonl；text delta 同步写调用方指定的 md。notify 盯结束。

3. 盯进度：轮询 md/jsonl 体积。长时间 0 增长或只见 reconnect → kill 再跑。禁止 --output-format text 前台干等。
4. 超时（硬）：墙钟 12 分钟仍无切干净的终稿 → kill，按调用方降级自己写，第一句标明「Cursor 超时」。不要空等到用户催。

编码任务（用户明确交给 Cursor 时）

• 账号：只用主号（~/.local/bin/cursor-agent，不设 CURSOR_CONFIG_DIR）；禁止 cursor-cli002 / cursorn。跑之前 unset CURSOR_API_KEY CURSOR_CONFIG_DIR AGENT_CLI_CREDENTIAL_STORE。
• 命令同上面第 2 步：后台 stream-json，--workspace 是用户给的仓库；12 分钟超时规则照旧。
• 模型：用户没说 → auto（套餐里 Auto/Composer 额度宽松）。说了 → 查下表。
• 收尾：让 Cursor 在最后输出改了哪些文件；Hermes 自己 git -C <仓库> status --short 和 git diff --stat 核对，再回复用户。不替 Cursor 补写代码冒充它的产物。

切换模型

先跑 ~/.local/bin/cursor-agent --list-models，在输出里按下表前缀找 id；同前缀多个时取版本号最高、不带 -fast 的那个（用户说「快一点」才带 -fast）。找不到 → 告诉用户「当前 Cursor 没有 X」，列出相近的 id，不擅自换别的模型。

用户中途说「换成 X」：kill 当前后台进程，用新 --model 重跑同一个 prompt 文件，告诉用户已切换到哪个 id。

Quick Reference

Procedure

1. 写好 prompt 文件（调用方给契约；本 skill 不发明写作口径）。
2. 解析二进制；没有 → 停，让调用方降级。
3. 取 --model：调用方指定 或 pick_gemini_flash.py。
4. 后台 stream-json；workspace / --add-dir 由调用方给。
5. 从产物里切干净终稿（掉 prompt 回显、过程句、重复全文）。
6. 完成标准：md 有调用方要的终稿，且 jsonl 不再增长。

Pitfalls

Verification

• ~/.local/bin/cursor-agent --list-models 有输出
• picker 打印的 id 出现在 --list-models 里，且是最高 gemini-*.flash-high（下限见脚本 FLOOR）
• 后台 jsonl 有 text delta，不是空转 reconnect
• 终稿文件不是 Hermes 自己改写的第一稿冒充