用途：在 shell 中无 IDE 界面地调用或委派 Cursor 代理处理任务（如“call cursor”“ask cursor”“invoke cursor”）。不用于 harness 的 change-review 工作流（应用 harness run change-review --agent cursor），也不用于 Cursor IDE 内聊天（用 Task 工具）或长期服务（用 @cursor/sdk）。
主要能力：默认只读，--force 才允许改文件或执行变更命令；--mode plan|ask 为只读模式；可指定 --model、--workspace；--resume <session-id> 续接会话；--schema/--schema-json 校验 JSON 输出；--format toon|json 选择输出格式（默认 TOON）；--full 取完整结果；--max-runtime-ms 默认 30 分钟；--idle-timeout-ms 默认关闭。退出码：0 成功，1 错误，2 用法错误。错误信息也写入 stdout。
使用方式：代理不应假定 cursor-cli 在 PATH 中，直接运行技能脚本：node <skill-root>/scripts/cursor-cli.ts …，<skill-root> 从加载的 cursor-cli 技能目录解析（packaged skills/cursor-cli/、.agents/skills/cursor-cli/ 或 ~/.agents/skills/cursor-cli/）。仅当运行 skills/cursor-cli/scripts/install.sh 且 command -v cursor-cli 成功后才可使用 ~/.local/bin/cursor-cli。示例：cursor-cli "explain the backend routing"；cursor-cli --force "add a regression test for auth"；cursor-cli --resume <session-id> "follow up"。调用方流程：解析 stdout → 检查 status → 读取 structuredOutput 或 result → 保存 sessionId。
认证：交互式 shell 可导出 CURSOR_API_KEY；代理子进程或嵌套调用必须设置 CURSOR_API_KEY，Keychain 登录不可靠；CI/无头服务器只用 CURSOR_API_KEY。
限制：Cursor CLI 无原生 JSON Schema 模式，封装器将 schema 指令注入提示并解析、校验基本子集（type、required、properties、items、enum）。封装器固定传 --trust --approve-mcps。安装、平台与收费信息资料未提供。