ONE-OS/axhub-make/vite-plugins/aiCliPlugin.spec.md

AI CLI Plugin 规格说明（vite-plugins/aiCliPlugin.ts）

本插件在 Vite Dev Server 上提供 /api/ai/* HTTP 接口，用于从浏览器侧触发本机已安装的 AI CLI（Claude / Gemini / OpenCode / Cursor Agent / Codex）。

1. 端点

1.1 GET /api/ai/status

返回当前机器上相关 CLI 是否可用（通过 which/where 检测）。

返回示例：

{
  "claude": true,
  "gemini": true,
  "opencode": false,
  "cursor": true,
  "codex": true,
  "runningTasks": 0,
  "timestamp": "2026-02-06T00:00:00.000Z"
}

1.2 GET /api/ai/execute

触发执行指定 CLI。

Query 参数

• cli（必填）：claude | gemini | opencode | cursor | codex
• prompt（必填）：字符串
• silent（可选）：默认 true
  • true：服务端捕获 stdout/stderr 并以 JSON 返回（非交互模式推荐）
  • false：输出直接继承到 dev server 所在终端（用于观察实时输出）
• interactive（可选）：默认 false
  • false：非交互模式，接口会等待命令结束并返回输出（内置 60s 超时）
  • true：交互式 TUI，会在 dev server 所在终端启动会话，并立即返回 202（不等待退出，不设置超时）

返回

非交互模式（interactive=false）成功示例：

{
  "success": true,
  "cli": "codex",
  "output": "...",
  "cached": false,
  "timestamp": "2026-02-06T00:00:00.000Z"
}

交互模式（interactive=true）成功示例：

{
  "success": true,
  "cli": "claude",
  "interactive": true,
  "pid": 12345,
  "message": "Interactive session started in the dev server terminal.",
  "timestamp": "2026-02-06T00:00:00.000Z"
}

当已有交互会话正在运行时会返回 409（避免同时抢占同一个终端 TTY）。

2. CLI 行为约定（适配器）

• claude
  • 非交互：claude -p <prompt>
  • 交互：claude <prompt>（首条消息为 prompt）
• gemini
  • 非交互：通过 stdin 写入 prompt
  • 交互：gemini -i <prompt>
• opencode
  • 非交互：opencode run <prompt>
  • 交互：opencode --prompt <prompt>（不同版本可能不支持；不支持时会在启动时报错）
• cursor
  • 非交互：agent -p <prompt> --output-format text
  • 交互：agent <prompt>
• codex
  • 非交互：codex exec <prompt> --full-auto
  • 交互：codex <prompt>

3. 设计备注

• interactive=true 的核心目的是“提交 prompt 后进入 CLI 对话”，因此不会等待进程退出，也不会走输出缓存/防抖逻辑。
• 所有平台均使用 shell=false；Windows 通过统一命令执行层自动包装到 cmd.exe /d /s /c，避免直接开启 shell 带来的注入与转义不一致问题。
• 输出解码由统一命令执行层处理：UTF-8 优先，Windows 下自动按活动代码页回退，避免 CLI 输出乱码影响日志和错误判定。