a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
92 lines
2.8 KiB
Markdown
92 lines
2.8 KiB
Markdown
# 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` 检测）。
|
||
|
||
返回示例：
|
||
|
||
```json
|
||
{
|
||
"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`）成功示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"cli": "codex",
|
||
"output": "...",
|
||
"cached": false,
|
||
"timestamp": "2026-02-06T00:00:00.000Z"
|
||
}
|
||
```
|
||
|
||
交互模式（`interactive=true`）成功示例：
|
||
|
||
```json
|
||
{
|
||
"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 输出乱码影响日志和错误判定。
|