@axhub/genie 0.1.7 → 0.1.9

package/README.md

@@ -1,2 +1,2 @@
-Axhub Genie 是一个 Web UI，用来管理与使用本地/远程的 Claude Code、Cursor CLI 和 Codex 会话。
+Axhub Genie 是一个 Web UI，用来管理与使用本地/远程的 Claude Code、Codex、Gemini 和 OpenCode 会话。
 它提供聊天、文件与终端等能力，便于在桌面和移动端统一操作。

package/dist/api-docs.html

@@ -303,14 +303,14 @@
           This page is auto-generated. Do not edit <code>public/api-docs.html</code> directly.
         </div>
         <article id="markdown-root" class="markdown-body"></article>
-        <footer>Generated at: 2026-02-12T09:22:33.366Z</footer>
+        <footer>Generated at: 2026-03-17T18:03:51.485Z</footer>
       </div>
     </section>
   </main>
 
   <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
   <script>
-    const markdownSource = "# 开放接口使用文档（MVP）\n\n> 单一事实源（Single Source of Truth）文件：`docs/open-api-mvp.zh-CN.md`  \n> 页面入口：`/api-docs.html`（由脚本自动生成，请勿手改 HTML）\n\n<a id=\"overview\"></a>\n\n> 适用场景：外部系统（本地 Web / 本地服务）与 Assistant UI 本地服务通信，实现**创建会话、进入指定会话、续聊指定会话**。\n\n## Quick English Summary\n\n- Backend endpoints: `GET /health`, `POST /api/agent`\n- Frontend integration: URL query params + iframe `postMessage` (`update_context`, `update_prompt`)\n- Auth default: local anonymous is allowed for `/api/agent`; `X-API-Key` is optional unless `AGENT_API_KEY_REQUIRED=true`\n\n## 1. 基本信息\n\n- Assistant 前端地址（示例）：`http://localhost:5173`\n- Assistant 后端地址（示例）：`http://localhost:32123`\n- 会话页面路由格式：`/session/{sessionId}`\n- 健康检查：`GET /health`\n\n### 1.0 地址发现（先执行命令）\n\n在开发、测试、生产环境中，地址可能不同。请先在部署机器执行：\n\n```bash\naxhub-genie status\n```\n\n建议使用三项核心字段：\n\n- `endpoint.environment`\n- `endpoint.frontendUrl`\n- `endpoint.apiBaseUrl`\n\n说明：\n\n- 在不知道 API 地址时，不需要先调用任何 HTTP 接口；直接用 `axhub-genie status` 获取。\n- 后续所有文档中的 `http://localhost:32123`，都可以替换为 `endpoint.apiBaseUrl` 对应主机地址。\n- 文中示例的 `<CURRENT_API_BASE>` 指 `endpoint.apiBaseUrl`（例如 `http://localhost:32123/api`）。\n\n### 1.1 完整示例\n\n```bash\naxhub-genie status --json\n```\n\n完整返回示例：\n\n```json\n{\n  \"running\": true,\n  \"pid\": 12345,\n  \"port\": 32123,\n  \"startedAt\": \"2026-02-08T03:12:45.321Z\",\n  \"statusFile\": \"/Users/you/.axhub-genie/runtime-status.json\",\n  \"endpoint\": {\n    \"environment\": \"development\",\n    \"frontendUrl\": \"http://localhost:5173\",\n    \"apiBaseUrl\": \"http://localhost:32123/api\"\n  }\n}\n```\n\n### 1.0.1 健康检查与服务身份识别\n\n为了避免外部系统误把其他项目当成 Assistant 服务，建议在探活时同时校验 `service.id` 或响应头中的 `X-App-Identifier`。\n\n请求示例：\n\n```bash\ncurl -i http://localhost:32123/health\n```\n\n响应体示例：\n\n```json\n{\n  \"status\": \"ok\",\n  \"timestamp\": \"2026-02-09T12:00:00.000Z\",\n  \"service\": {\n    \"id\": \"@axhub/genie\",\n    \"name\": \"Axhub Genie\",\n    \"version\": \"1.16.3\"\n  },\n  \"runtime\": {\n    \"environment\": \"development\",\n    \"port\": 32123\n  }\n}\n```\n\n关键响应头（可用于快速识别）：\n\n- `X-App-Identifier: @axhub/genie`\n- `X-App-Name: Axhub Genie`\n- `X-App-Version: 1.16.3`\n- `X-App-Environment: development`\n\n可选环境变量（用于自定义身份/环境标识）：\n\n- `APP_IDENTIFIER`（默认：`@axhub/genie`）\n- `APP_DISPLAY_NAME`（默认：`Axhub Genie`）\n- `APP_VERSION`（默认：读取 `package.json` 的 `version`）\n- `APP_RUNTIME_ENV`（默认：`APP_RUNTIME_ENV || NODE_ENV || development`）\n\n建议：\n\n- 探活成功条件 = HTTP `200` 且 `status=ok` 且 `service.id` 命中预期值。\n- 如果你的网关会剥离自定义 Header，优先校验响应体中的 `service.id`。\n\n### 1.1 前端 URL 参数（新增）\n\n你现在可以通过 `http://localhost:5173/` 的查询参数，预选项目和默认工具：\n\n| 参数 | 示例 | 说明 |\n|---|---|---|\n| `project` | `?project=my-project` | 按项目名/显示名/路径精确匹配项目 |\n| `projectName` | `?projectName=my-project` | `project` 的同义参数 |\n| `cwd` | `?cwd=/Users/you/my-project` | 按项目路径匹配（优先） |\n| `workdir` | `?workdir=/Users/you/my-project` | `cwd` 的同义参数 |\n| `provider` | `?provider=codex` | 预设默认工具（`claude`/`cursor`/`codex`/`gemini`/`opencode`） |\n| `tool` | `?tool=codex` | `provider` 的同义参数 |\n| `cli` | `?cli=codex` | `provider` 的同义参数 |\n| `context` | `?context=%7B%22version%22%3A%221%22%2C%22systemContext%22%3A%22tenant%3Aacme%22%2C%22currentFile%22%3A%22docs%2Fopen-api-mvp.zh-CN.md%22%2C%22selectedElements%22%3A%5B%7B%22tag%22%3A%22iframe%22%2C%22selector%22%3A%22%23preview-frame%22%2C%22label%22%3A%22%E9%A2%84%E8%A7%88%E5%8C%BA%E5%9F%9F%22%7D%5D%7D` | 动态上下文（`contextV1` JSON，首次发送消息时自动附加，仅发送一次） |\n| `prompt` | `?prompt=%E8%AF%B7%E5%85%88%E5%88%86%E6%9E%90%E5%BD%93%E5%89%8D%E9%A1%B5` | 预填输入框内容（仅页面生命周期内首次 URL 生效，默认不自动发送） |\n\n示例：\n\n- `http://localhost:5173/?project=my-project&provider=codex`\n- `http://localhost:5173/?cwd=/Users/you/my-project&provider=cursor`\n- `http://localhost:5173/?project=my-project&provider=codex&context=%7B%22version%22%3A%221%22%2C%22systemContext%22%3A%22tenant%3Aacme%22%2C%22currentFile%22%3A%22docs%2Fopen-api-mvp.zh-CN.md%22%2C%22selectedElements%22%3A%5B%7B%22tag%22%3A%22iframe%22%2C%22selector%22%3A%22%23preview-frame%22%2C%22label%22%3A%22%E9%A2%84%E8%A7%88%E5%8C%BA%E5%9F%9F%22%7D%5D%7D`\n- `http://localhost:5173/?project=my-project&provider=codex&prompt=%E8%AF%B7%E5%85%88%E6%A3%80%E6%9F%A5%E5%BD%93%E5%89%8D%E9%A1%B5%E9%9D%A2`\n\n`context` 采用固定 `contextV1` 结构（不兼容旧格式）：\n\n```json\n{\n  \"version\": \"1\",\n  \"systemContext\": \"租户:acme; 角色:analyst\",\n  \"currentFile\": \"docs/open-api-mvp.zh-CN.md\",\n  \"selectedElements\": [\n    {\n      \"tag\": \"iframe\",\n      \"selector\": \"#preview-frame\",\n      \"label\": \"预览区域\"\n    }\n  ],\n  \"extensions\": {\n    \"pageId\": \"dashboard\"\n  }\n}\n```\n\n字段约束：\n\n- `version`：必填，固定值 `\"1\"`\n- `systemContext`：必填字符串，可为空字符串\n- `currentFile`：必填字符串，可为空字符串（仅路径）\n- `selectedElements`：必填数组，可为空；元素必须包含 `tag`、`selector`、`label` 字符串字段\n- `extensions`：可选对象，预留扩展\n\n兼容性说明：\n\n- URL 仅支持 `context` 参数，不再读取 `externalContext`、`iframeContext`\n\n## 1.1 前端 URL 可选参数\n\n你可以在前端链接上附带以下参数：\n\n- `cwd`：工作目录（本地项目路径）\n- `model`：默认选中模型（与 UI 模型下拉一致）\n\n示例：\n\n- `http://localhost:5173/?cwd=/Users/you/your-project&model=sonnet`\n- `http://localhost:5173/session/019c...c32e?cwd=/Users/you/your-project&model=gpt-5.2-codex`\n\n说明：\n\n- `cwd` 会尝试匹配已存在的项目并自动选中\n- `model` 会自动选中对应模型；若同名模型同时出现在多个 provider 中，会优先保持当前 provider\n\n### 1.2 iframe 场景：通过 `postMessage` 更新 context\n\n当 Assistant UI 被 iframe 内嵌时，可通过 `postMessage` 动态更新 context。\n\n行为规则：\n\n- context 只会在**下一次用户发送消息**时自动附加一次。\n- 一旦附加发送过，会标记为“已发送”。\n- 任何新的 `postMessage` 更新都会将状态重置为“未发送”，并在下一次消息时重新附加。\n- `update_context` 新增可选 `mode`：默认 `replace`（覆盖），可选 `append`（追加，适合分多次选择元素）。\n\n推荐消息格式（父页面 -> iframe）：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_context',\n  mode: 'replace', // 可选：replace(默认) / append\n  context: {\n    version: '1',\n    systemContext: '租户:acme; 角色:analyst',\n    currentFile: 'docs/open-api-mvp.zh-CN.md',\n    selectedElements: [\n      {\n        tag: 'div',\n        selector: '#main-content > .toolbar',\n        label: '顶部工具条'\n      }\n    ],\n    extensions: {\n      pageId: 'dashboard'\n    }\n  }\n}, '*');\n```\n\n追加模式示例（分多次追加选中元素）：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_context',\n  mode: 'append',\n  context: {\n    selectedElements: [\n      {\n        tag: 'button',\n        selector: '#save-btn',\n        label: '保存按钮'\n      }\n    ]\n  }\n}, '*');\n```\n\n协议约束（MVP v2）：\n\n- 仅支持 `type: update_context`\n- `mode` 可选：`replace`（默认）/ `append`\n- `mode=replace` 时：`context` 必须是对象，且满足 `contextV1` 结构\n- `mode=append` 时：`context` 允许按需传字段；`selectedElements` 会追加到现有上下文（建议按 `tag+selector+label` 去重）\n- `mode=append` 时：除 `selectedElements` 外，其它字段（如 `systemContext`/`currentFile`/`extensions`）若传入则按传入值更新；未传入字段保持原值\n- 不再兼容 `set_context`、`external_context_update`\n- 不再兼容 `payload`、`value`、`customContext`\n- 非法 `context` 会被忽略并输出 `console.warn`，不会阻断正常聊天发送\n\n### 1.3 iframe 场景：通过 `postMessage` 更新预填输入（prompt）\n\n当 Assistant UI 被 iframe 内嵌时，可通过 `postMessage` 动态更新输入框预填内容。\n\n行为规则：\n\n- URL 参数 `prompt` 只在页面生命周期内首次生效（不会随 URL 后续变化重复覆盖）。\n- `postMessage` 的 `update_prompt` 会直接替换输入框内容。\n- 默认仅预填，不自动发送。\n- 当 `autoSend=true` 时，仅在“当前可发送”（已选项目且未在生成中）才立即发送；否则只预填，不排队重试。\n\n推荐消息格式（父页面 -> iframe）：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_prompt',\n  prompt: '请基于当前页面状态继续分析',\n  autoSend: false\n}, '*');\n```\n\n自动发送示例：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_prompt',\n  prompt: '请基于当前页面状态继续分析',\n  autoSend: true\n}, '*');\n```\n\n完整消息 JSON 示例：\n\n```json\n{\n  \"type\": \"update_prompt\",\n  \"prompt\": \"请先总结当前页面上下文，再给出下一步建议\",\n  \"autoSend\": true\n}\n```\n\n兼容类型：`update_prompt`、`set_prompt`、`external_prompt_update`\n\n兼容字段：`prompt`（推荐）、`payload`、`value`、`prefill`\n\n<a id=\"authentication\"></a>\n\n## 2. 鉴权策略（MVP）\n\n当前默认策略：\n\n- `POST /api/agent` **可本地匿名调用**（不传 `X-API-Key` 也可）\n- 如果传了 `X-API-Key`，会执行校验\n- 如需强制鉴权，设置环境变量：`AGENT_API_KEY_REQUIRED=true`\n\n<a id=\"agent\"></a>\n\n## 3. 核心开放接口\n\n### 3.1 创建或续聊会话\n\n`POST /api/agent`\n\n#### 请求体\n\n| 字段 | 类型 | 必填 | 说明 |\n|---|---|---|---|\n| `projectPath` | string | 条件必填 | 本地项目路径（建议 MVP 直接使用此字段） |\n| `message` | string | 条件必填 | 本轮用户输入。`openOnly=true` 时可为空 |\n| `provider` | string | 否 | `claude` / `cursor` / `codex` / `gemini` / `opencode`，默认 `claude` |\n| `sessionId` | string | 否 | 传入则续聊指定会话，不传则创建新会话 |\n| `openOnly` | boolean | 否 | `true` 表示只返回会话跳转信息，不触发模型调用 |\n| `stream` | boolean | 否 | 是否流式，默认 `true`；集成场景建议 `false` |\n| `model` | string | 否 | 指定模型 |\n| `githubUrl` | string | 否 | 需要自动 clone 仓库时使用 |\n| `cleanup` | boolean | 否 | clone 场景完成后是否清理（默认 `true`） |\n| `githubToken` | string | 否 | GitHub Personal Access Token；请求内优先级高于设置页保存值 |\n| `branchName` | string | 否 | 自定义分支名；传入后会自动开启 `createBranch=true` |\n| `createBranch` | boolean | 否 | 任务完成后创建并推送 Git 分支（默认 `false`） |\n| `createPR` | boolean | 否 | 任务完成后创建 GitHub Pull Request（默认 `false`） |\n\n#### 关键校验规则\n\n- `openOnly=true` 或“`message` 为空且 `sessionId` 非空”时，会进入 only-open 模式。\n- only-open 模式下必须传 `sessionId`。\n- only-open 模式下不支持 `githubUrl` / `createBranch` / `createPR`。\n- `openOnly=true` 请求会忽略 `cleanup`，无需额外传 `cleanup=false`。\n\n#### 返回（`stream: false`）\n\n```json\n{\n  \"success\": true,\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"isResumed\": false,\n  \"messages\": [],\n  \"tokens\": {\n    \"inputTokens\": 0,\n    \"outputTokens\": 0,\n    \"cacheReadTokens\": 0,\n    \"cacheCreationTokens\": 0,\n    \"totalTokens\": 0\n  },\n  \"projectPath\": \"/Users/you/your-project\"\n}\n```\n\n字段说明：\n\n- `sessionId`：后续续聊和跳转的核心 ID\n- `sessionPath`：前端相对路径\n- `sessionUrl`：可直接打开的前端完整链接\n- `isResumed`：`true` 表示这次请求是续聊\n- `branch`：仅在 `createBranch=true` 时返回（成功返回分支信息，失败返回错误对象）\n- `pullRequest`：仅在 `createPR=true` 时返回（成功返回 PR 信息，失败返回错误对象）\n\n---\n\n### 3.2 进入指定会话（前端跳转）\n\nAssistant 当前已支持固定链接格式，无需新增接口：\n\n- `{FRONTEND_URL}/session/{sessionId}`（生产环境推荐配置 `FRONTEND_URL`）\n- 本地开发默认：`http://localhost:5173/session/{sessionId}`\n\n因此，外部系统调用 `POST /api/agent` 后，拿到 `sessionUrl` 直接打开即可。\n\n### 3.3 只打开会话（不发送消息）\n\n如果你只想“进入某个会话页面”，不想触发模型，可以调用：\n\n- `POST /api/agent`\n- 传 `openOnly: true`\n- `message` 可为空\n- 必须传 `sessionId`\n\n请求示例：\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"openOnly\": true,\n    \"stream\": false\n  }'\n```\n\n返回示例：\n\n```json\n{\n  \"success\": true,\n  \"openOnly\": true,\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"isResumed\": true,\n  \"message\": \"Session link generated. No model call triggered.\"\n}\n```\n\n## 4. 对接流程（推荐）\n\n### 流程 A：创建新会话并打开\n\n1. 外部系统调用 `POST /api/agent`（不传 `sessionId`，且带 `message`）\n2. 保存返回的 `sessionId`\n3. 打开返回的 `sessionUrl`\n\n### 流程 B：进入并续聊已有会话\n\n1. 外部系统根据业务会话键找到已保存的 `sessionId`\n2. 调用 `POST /api/agent` 且传 `openOnly=true`（或直接拼接 URL）\n3. 如需服务端触发续聊，再调用 `POST /api/agent` 并传 `sessionId`\n\n<a id=\"usage-examples\"></a>\n\n## 5. cURL 示例\n\n### 5.1 创建新会话（MVP 无鉴权）\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"provider\": \"claude\",\n    \"message\": \"请先梳理当前项目结构并给出重构计划\",\n    \"stream\": false\n  }'\n```\n\n### 5.2 续聊指定会话\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"provider\": \"claude\",\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"message\": \"继续上一轮，把第 1、2 点先落代码\",\n    \"stream\": false\n  }'\n```\n\n### 5.3 只打开会话（不输入）\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"openOnly\": true,\n    \"stream\": false\n  }'\n```\n\n### 5.4 可选：携带 API Key\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: ck_xxx\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"message\": \"继续处理\"\n  }'\n```\n\n### 5.5 自动创建分支并发起 PR\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: ck_xxx\" \\\n  -d '{\n    \"githubUrl\": \"https://github.com/user/repo\",\n    \"message\": \"修复鉴权逻辑并补充测试\",\n    \"createBranch\": true,\n    \"createPR\": true,\n    \"stream\": false\n  }'\n```\n\n### 5.6 指定自定义分支名\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"message\": \"新增 API 网关重试策略\",\n    \"branchName\": \"feature/api-retry-strategy\",\n    \"createPR\": true,\n    \"stream\": false\n  }'\n```\n\n## 6. 外部系统会话映射建议\n\n建议在外部系统保存映射：\n\n- `external_conversation_key -> sessionId`\n\n这样可保证：\n\n- 可重入（同一业务会话可重复进入）\n- 可续聊（服务端调用时带 `sessionId`）\n- 可跳转（拼接前端链接）\n\n<a id=\"frontend-integration\"></a>\n\n## 7. 动态上下文注入规范（MVP v2）\n\n当前前端会在“下一次用户发送消息”时自动附加一次动态上下文，注入格式如下：\n\n```text\n[DYNAMIC CONTEXT V1]\n{ ...contextV1 json... }\n\n[USER MESSAGE]\n...用户输入...\n```\n\n行为规则：\n\n1. `context` 仅附加一次；发送后标记为已发送。\n2. 收到新的 URL `context` 或新的 `postMessage(update_context)` 后，重置为未发送。\n3. `postMessage(update_context)` 默认 `mode=replace`（覆盖当前待发送上下文）。\n4. 当 `mode=append` 时：`selectedElements` 采用追加策略（建议按 `tag+selector+label` 去重），便于分批选元素。\n5. 当 `mode=append` 时：未传入字段保持原值；已传入字段更新为最新值。\n6. 输入区会展示上下文标签（系统上下文 / 当前文件 / 选中元素）。\n7. 用户可手动取消某个标签；取消仅影响当前待发送上下文。\n8. 如果用户取消后上下文为空，则本次不附加动态上下文块。\n\n非法输入处理：\n\n- `context` 非法 JSON（URL）或字段校验失败：忽略该上下文并 `console.warn`\n- 不会阻止用户继续发送消息\n\n<a id=\"faq\"></a>\n\n## 8. 常见问题\n\n### Q1：只想“打开会话页面”，不想触发模型怎么办？\n\n两种方式都可以：\n\n1. 直接跳转：`/session/{sessionId}`\n2. 调用 `POST /api/agent` 并传 `openOnly=true`\n\n### Q2：`sessionId` 传了但会话不存在会怎样？\n\n不同 provider 的底层行为可能不同（可能报错或新建）。建议外部系统以“本地已保存映射”为准，避免传错 ID。\n\n### Q3：如何从当前地址拿到 sessionId？\n\n例如你的地址：\n\n- `http://localhost:5173/session/019c3263-967f-7ba2-84fe-fc5c694f6316`\n\n其中 `019c3263-967f-7ba2-84fe-fc5c694f6316` 就是 `sessionId`。\n\n## 9. 版本说明\n\n- 文档版本：MVP v1.1\n- 更新日期：2026-02-12\n- 文档来源：`docs/open-api-mvp.zh-CN.md`（`/api-docs.html` 由脚本生成）\n- 对应能力：`/api/agent` 支持 `sessionId` 续聊、`openOnly` 仅打开、`gemini/opencode` provider、可选 `createBranch/createPR`\n";
+    const markdownSource = "# 开放接口使用文档（MVP）\n\n> 单一事实源（Single Source of Truth）文件：`docs/open-api-mvp.zh-CN.md`  \n> 页面入口：`/api-docs.html`（由脚本自动生成，请勿手改 HTML）\n\n<a id=\"overview\"></a>\n\n> 适用场景：外部系统（本地 Web / 本地服务）与 Assistant UI 本地服务通信，实现**创建会话、进入指定会话、续聊指定会话、中断运行中会话**。\n\n## Quick English Summary\n\n- Backend endpoints: `GET /health`, `POST /api/agent`, `POST /api/agent/abort`\n- Frontend integration: URL query params + iframe `postMessage` (`update_context`, `update_prompt`)\n- Auth default: local anonymous is allowed for `/api/agent`; `X-API-Key` is optional unless `AGENT_API_KEY_REQUIRED=true`\n\n## 1. 基本信息\n\n- Assistant 前端地址（示例）：`http://localhost:5173`\n- Assistant 后端地址（示例）：`http://localhost:32123`\n- 会话页面路由格式：`/session/{sessionId}`\n- 健康检查：`GET /health`\n\n### 1.0 地址发现（先执行命令）\n\n在开发、测试、生产环境中，地址可能不同。请先在部署机器执行：\n\n```bash\naxhub-genie status\n```\n\n建议使用三项核心字段：\n\n- `endpoint.environment`\n- `endpoint.frontendUrl`\n- `endpoint.apiBaseUrl`\n\n说明：\n\n- 在不知道 API 地址时，不需要先调用任何 HTTP 接口；直接用 `axhub-genie status` 获取。\n- 后续所有文档中的 `http://localhost:32123`，都可以替换为 `endpoint.apiBaseUrl` 对应主机地址。\n- 文中示例的 `<CURRENT_API_BASE>` 指 `endpoint.apiBaseUrl`（例如 `http://localhost:32123/api`）。\n\n### 1.1 完整示例\n\n```bash\naxhub-genie status --json\n```\n\n完整返回示例：\n\n```json\n{\n  \"running\": true,\n  \"pid\": 12345,\n  \"port\": 32123,\n  \"startedAt\": \"2026-02-08T03:12:45.321Z\",\n  \"statusFile\": \"/Users/you/.axhub-genie/runtime-status.json\",\n  \"endpoint\": {\n    \"environment\": \"development\",\n    \"frontendUrl\": \"http://localhost:5173\",\n    \"apiBaseUrl\": \"http://localhost:32123/api\"\n  }\n}\n```\n\n### 1.0.1 健康检查与服务身份识别\n\n为了避免外部系统误把其他项目当成 Assistant 服务，建议在探活时同时校验 `service.id` 或响应头中的 `X-App-Identifier`。\n\n请求示例：\n\n```bash\ncurl -i http://localhost:32123/health\n```\n\n响应体示例：\n\n```json\n{\n  \"status\": \"ok\",\n  \"timestamp\": \"2026-02-09T12:00:00.000Z\",\n  \"service\": {\n    \"id\": \"@axhub/genie\",\n    \"name\": \"Axhub Genie\",\n    \"version\": \"1.16.3\"\n  },\n  \"runtime\": {\n    \"environment\": \"development\",\n    \"port\": 32123\n  }\n}\n```\n\n关键响应头（可用于快速识别）：\n\n- `X-App-Identifier: @axhub/genie`\n- `X-App-Name: Axhub Genie`\n- `X-App-Version: 1.16.3`\n- `X-App-Environment: development`\n\n可选环境变量（用于自定义身份/环境标识）：\n\n- `APP_IDENTIFIER`（默认：`@axhub/genie`）\n- `APP_DISPLAY_NAME`（默认：`Axhub Genie`）\n- `APP_VERSION`（默认：读取 `package.json` 的 `version`）\n- `APP_RUNTIME_ENV`（默认：`APP_RUNTIME_ENV || NODE_ENV || development`）\n\n建议：\n\n- 探活成功条件 = HTTP `200` 且 `status=ok` 且 `service.id` 命中预期值。\n- 如果你的网关会剥离自定义 Header，优先校验响应体中的 `service.id`。\n\n### 1.1 前端 URL 参数（新增）\n\n你现在可以通过 `http://localhost:5173/` 的查询参数，预选项目和默认工具：\n\n| 参数 | 示例 | 说明 |\n|---|---|---|\n| `project` | `?project=my-project` | 按项目名/显示名/路径精确匹配项目 |\n| `projectName` | `?projectName=my-project` | `project` 的同义参数 |\n| `cwd` | `?cwd=/Users/you/my-project` | 按项目路径匹配（优先） |\n| `workdir` | `?workdir=/Users/you/my-project` | `cwd` 的同义参数 |\n| `provider` | `?provider=codex` | 预设默认工具（`claude`/`cursor`/`codex`/`gemini`/`opencode`） |\n| `tool` | `?tool=codex` | `provider` 的同义参数 |\n| `cli` | `?cli=codex` | `provider` 的同义参数 |\n| `context` | `?context=%7B%22version%22%3A%221%22%2C%22systemContext%22%3A%22tenant%3Aacme%22%2C%22currentFile%22%3A%22docs%2Fopen-api-mvp.zh-CN.md%22%2C%22selectedElements%22%3A%5B%7B%22tag%22%3A%22iframe%22%2C%22selector%22%3A%22%23preview-frame%22%2C%22label%22%3A%22%E9%A2%84%E8%A7%88%E5%8C%BA%E5%9F%9F%22%7D%5D%7D` | 动态上下文（`contextV1` JSON，首次发送消息时自动附加，仅发送一次） |\n| `prompt` | `?prompt=%E8%AF%B7%E5%85%88%E5%88%86%E6%9E%90%E5%BD%93%E5%89%8D%E9%A1%B5` | 预填输入框内容（仅页面生命周期内首次 URL 生效，默认不自动发送） |\n\n示例：\n\n- `http://localhost:5173/?project=my-project&provider=codex`\n- `http://localhost:5173/?cwd=/Users/you/my-project&provider=cursor`\n- `http://localhost:5173/?project=my-project&provider=codex&context=%7B%22version%22%3A%221%22%2C%22systemContext%22%3A%22tenant%3Aacme%22%2C%22currentFile%22%3A%22docs%2Fopen-api-mvp.zh-CN.md%22%2C%22selectedElements%22%3A%5B%7B%22tag%22%3A%22iframe%22%2C%22selector%22%3A%22%23preview-frame%22%2C%22label%22%3A%22%E9%A2%84%E8%A7%88%E5%8C%BA%E5%9F%9F%22%7D%5D%7D`\n- `http://localhost:5173/?project=my-project&provider=codex&prompt=%E8%AF%B7%E5%85%88%E6%A3%80%E6%9F%A5%E5%BD%93%E5%89%8D%E9%A1%B5%E9%9D%A2`\n\n`context` 采用固定 `contextV1` 结构（不兼容旧格式）：\n\n```json\n{\n  \"version\": \"1\",\n  \"systemContext\": \"租户:acme; 角色:analyst\",\n  \"currentFile\": \"docs/open-api-mvp.zh-CN.md\",\n  \"selectedElements\": [\n    {\n      \"tag\": \"iframe\",\n      \"selector\": \"#preview-frame\",\n      \"label\": \"预览区域\"\n    }\n  ],\n  \"extensions\": {\n    \"pageId\": \"dashboard\"\n  }\n}\n```\n\n字段约束：\n\n- `version`：必填，固定值 `\"1\"`\n- `systemContext`：必填字符串，可为空字符串\n- `currentFile`：必填字符串，可为空字符串（仅路径）\n- `selectedElements`：必填数组，可为空；元素必须包含 `tag`、`selector`、`label` 字符串字段\n- `extensions`：可选对象，预留扩展\n\n兼容性说明：\n\n- URL 仅支持 `context` 参数，不再读取 `externalContext`、`iframeContext`\n\n## 1.1 前端 URL 可选参数\n\n你可以在前端链接上附带以下参数：\n\n- `cwd`：工作目录（本地项目路径）\n- `model`：默认选中模型（与 UI 模型下拉一致）\n\n示例：\n\n- `http://localhost:5173/?cwd=/Users/you/your-project&model=sonnet`\n- `http://localhost:5173/session/019c...c32e?cwd=/Users/you/your-project&model=gpt-5.2-codex`\n\n说明：\n\n- `cwd` 会尝试匹配已存在的项目并自动选中\n- `model` 会自动选中对应模型；若同名模型同时出现在多个 provider 中，会优先保持当前 provider\n\n### 1.2 iframe 场景：通过 `postMessage` 更新 context\n\n当 Assistant UI 被 iframe 内嵌时，可通过 `postMessage` 动态更新 context。\n\n行为规则：\n\n- context 只会在**下一次用户发送消息**时自动附加一次。\n- 一旦附加发送过，会标记为“已发送”。\n- 任何新的 `postMessage` 更新都会将状态重置为“未发送”，并在下一次消息时重新附加。\n- `update_context` 新增可选 `mode`：默认 `replace`（覆盖），可选 `append`（追加，适合分多次选择元素）。\n\n推荐消息格式（父页面 -> iframe）：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_context',\n  mode: 'replace', // 可选：replace(默认) / append\n  context: {\n    version: '1',\n    systemContext: '租户:acme; 角色:analyst',\n    currentFile: 'docs/open-api-mvp.zh-CN.md',\n    selectedElements: [\n      {\n        tag: 'div',\n        selector: '#main-content > .toolbar',\n        label: '顶部工具条'\n      }\n    ],\n    extensions: {\n      pageId: 'dashboard'\n    }\n  }\n}, '*');\n```\n\n追加模式示例（分多次追加选中元素）：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_context',\n  mode: 'append',\n  context: {\n    selectedElements: [\n      {\n        tag: 'button',\n        selector: '#save-btn',\n        label: '保存按钮'\n      }\n    ]\n  }\n}, '*');\n```\n\n协议约束（MVP v2）：\n\n- 仅支持 `type: update_context`\n- `mode` 可选：`replace`（默认）/ `append`\n- `mode=replace` 时：`context` 必须是对象，且满足 `contextV1` 结构\n- `mode=append` 时：`context` 允许按需传字段；`selectedElements` 会追加到现有上下文（建议按 `tag+selector+label` 去重）\n- `mode=append` 时：除 `selectedElements` 外，其它字段（如 `systemContext`/`currentFile`/`extensions`）若传入则按传入值更新；未传入字段保持原值\n- 不再兼容 `set_context`、`external_context_update`\n- 不再兼容 `payload`、`value`、`customContext`\n- 非法 `context` 会被忽略并输出 `console.warn`，不会阻断正常聊天发送\n\n### 1.3 iframe 场景：通过 `postMessage` 更新预填输入（prompt）\n\n当 Assistant UI 被 iframe 内嵌时，可通过 `postMessage` 动态更新输入框预填内容。\n\n行为规则：\n\n- URL 参数 `prompt` 只在页面生命周期内首次生效（不会随 URL 后续变化重复覆盖）。\n- `postMessage` 的 `update_prompt` 会直接替换输入框内容。\n- 默认仅预填，不自动发送。\n- 当 `autoSend=true` 时，仅在“当前可发送”（已选项目且未在生成中）才立即发送；否则只预填，不排队重试。\n\n推荐消息格式（父页面 -> iframe）：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_prompt',\n  prompt: '请基于当前页面状态继续分析',\n  autoSend: false\n}, '*');\n```\n\n自动发送示例：\n\n```js\niframeEl.contentWindow.postMessage({\n  type: 'update_prompt',\n  prompt: '请基于当前页面状态继续分析',\n  autoSend: true\n}, '*');\n```\n\n完整消息 JSON 示例：\n\n```json\n{\n  \"type\": \"update_prompt\",\n  \"prompt\": \"请先总结当前页面上下文，再给出下一步建议\",\n  \"autoSend\": true\n}\n```\n\n兼容类型：`update_prompt`、`set_prompt`、`external_prompt_update`\n\n兼容字段：`prompt`（推荐）、`payload`、`value`、`prefill`\n\n<a id=\"authentication\"></a>\n\n## 2. 鉴权策略（MVP）\n\n当前默认策略：\n\n- `POST /api/agent` **可本地匿名调用**（不传 `X-API-Key` 也可）\n- 如果传了 `X-API-Key`，会执行校验\n- 如需强制鉴权，设置环境变量：`AGENT_API_KEY_REQUIRED=true`\n\n<a id=\"agent\"></a>\n\n## 3. 核心开放接口\n\n### 3.1 创建或续聊会话\n\n`POST /api/agent`\n\n#### 请求体\n\n| 字段 | 类型 | 必填 | 说明 |\n|---|---|---|---|\n| `projectPath` | string | 条件必填 | 本地项目路径（建议 MVP 直接使用此字段） |\n| `message` | string | 条件必填 | 本轮用户输入。`openOnly=true` 时可为空 |\n| `provider` | string | 否 | `claude` / `cursor` / `codex` / `gemini` / `opencode`，默认 `claude` |\n| `sessionId` | string | 否 | 传入则续聊指定会话，不传则创建新会话 |\n| `openOnly` | boolean | 否 | `true` 表示只返回会话跳转信息，不触发模型调用 |\n| `stream` | boolean | 否 | 是否流式，默认 `true`；集成场景建议 `false` |\n| `model` | string | 否 | 指定模型 |\n| `githubUrl` | string | 否 | 需要自动 clone 仓库时使用 |\n| `cleanup` | boolean | 否 | clone 场景完成后是否清理（默认 `true`） |\n| `githubToken` | string | 否 | GitHub Personal Access Token；请求内优先级高于设置页保存值 |\n| `branchName` | string | 否 | 自定义分支名；传入后会自动开启 `createBranch=true` |\n| `createBranch` | boolean | 否 | 任务完成后创建并推送 Git 分支（默认 `false`） |\n| `createPR` | boolean | 否 | 任务完成后创建 GitHub Pull Request（默认 `false`） |\n| `callback` | object | 否 | 终态回调配置。支持 `url` / `events` / `secret`，任务以 `completed` / `errored` / `aborted` 结束时异步回调 |\n\n#### 关键校验规则\n\n- `openOnly=true` 或“`message` 为空且 `sessionId` 非空”时，会进入 only-open 模式。\n- only-open 模式下必须传 `sessionId`。\n- only-open 模式下不支持 `githubUrl` / `createBranch` / `createPR`。\n- only-open 模式下也不支持 `callback`。\n- `openOnly=true` 请求会忽略 `cleanup`，无需额外传 `cleanup=false`。\n- `callback.url` 必须是合法的 `http/https` 地址。\n- `callback.events` 可选，默认等于 `[\"completed\", \"errored\", \"aborted\"]`。\n- `callback.events` 只允许包含 `completed` / `errored` / `aborted`。\n- `callback.secret` 可选；传入后回调请求会带 `X-Agent-Signature` HMAC 签名。\n\n#### 返回（`stream: false`）\n\n```json\n{\n  \"success\": true,\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"isResumed\": false,\n  \"messages\": [],\n  \"tokens\": {\n    \"inputTokens\": 0,\n    \"outputTokens\": 0,\n    \"cacheReadTokens\": 0,\n    \"cacheCreationTokens\": 0,\n    \"totalTokens\": 0\n  },\n  \"projectPath\": \"/Users/you/your-project\"\n}\n```\n\n字段说明：\n\n- `sessionId`：后续续聊和跳转的核心 ID\n- `sessionPath`：前端相对路径\n- `sessionUrl`：可直接打开的前端完整链接\n- `isResumed`：`true` 表示这次请求是续聊\n- `branch`：仅在 `createBranch=true` 时返回（成功返回分支信息，失败返回错误对象）\n- `pullRequest`：仅在 `createPR=true` 时返回（成功返回 PR 信息，失败返回错误对象）\n\n#### `callback` 字段示例\n\n```json\n{\n  \"projectPath\": \"/Users/you/your-project\",\n  \"message\": \"请修复首页按钮点击态\",\n  \"provider\": \"codex\",\n  \"stream\": false,\n  \"callback\": {\n    \"url\": \"https://external.example.com/agent/callback\",\n    \"events\": [\"completed\", \"errored\", \"aborted\"],\n    \"secret\": \"shared-secret\"\n  }\n}\n```\n\n#### 终态回调说明\n\n- `callback` 只做终态通知，不推送中间流式事件。\n- 回调投递为异步旁路，不阻塞主接口响应。\n- 最多尝试 3 次：首次立即发送，失败后约在 1 秒、5 秒后重试。\n- 仅网络错误、超时、HTTP `>=500` 会重试；HTTP `4xx` 不重试。\n- 回调 Header：\n  - `X-Agent-Event`\n  - `X-Agent-Event-Id`\n  - `X-Agent-Delivery-Attempt`\n  - `X-Agent-Signature`（仅当传入 `callback.secret`）\n\n#### 终态回调 Payload 示例\n\n成功：\n\n```json\n{\n  \"event\": \"completed\",\n  \"eventId\": \"agentcb_12345678-1234-1234-1234-1234567890ab\",\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"provider\": \"codex\",\n  \"status\": \"completed\",\n  \"success\": true,\n  \"projectPath\": \"/Users/you/your-project\",\n  \"isResumed\": false,\n  \"startedAt\": \"2026-03-18T10:00:00.000Z\",\n  \"finishedAt\": \"2026-03-18T10:00:08.000Z\",\n  \"result\": {\n    \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"messages\": [],\n    \"tokens\": {\n      \"inputTokens\": 0,\n      \"outputTokens\": 0,\n      \"cacheReadTokens\": 0,\n      \"cacheCreationTokens\": 0,\n      \"totalTokens\": 0\n    },\n    \"branch\": null,\n    \"pullRequest\": null\n  },\n  \"error\": null\n}\n```\n\n失败：\n\n```json\n{\n  \"event\": \"errored\",\n  \"eventId\": \"agentcb_12345678-1234-1234-1234-1234567890ab\",\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"provider\": \"codex\",\n  \"status\": \"errored\",\n  \"success\": false,\n  \"projectPath\": \"/Users/you/your-project\",\n  \"isResumed\": false,\n  \"startedAt\": \"2026-03-18T10:00:00.000Z\",\n  \"finishedAt\": \"2026-03-18T10:00:08.000Z\",\n  \"result\": {\n    \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"messages\": [],\n    \"tokens\": {\n      \"inputTokens\": 0,\n      \"outputTokens\": 0,\n      \"cacheReadTokens\": 0,\n      \"cacheCreationTokens\": 0,\n      \"totalTokens\": 0\n    },\n    \"branch\": null,\n    \"pullRequest\": null\n  },\n  \"error\": {\n    \"message\": \"Project path does not exist: /Users/you/missing-project\"\n  }\n}\n```\n\n---\n\n### 3.2 进入指定会话（前端跳转）\n\nAssistant 当前已支持固定链接格式，无需新增接口：\n\n- `{FRONTEND_URL}/session/{sessionId}`（生产环境推荐配置 `FRONTEND_URL`）\n- 本地开发默认：`http://localhost:5173/session/{sessionId}`\n\n因此，外部系统调用 `POST /api/agent` 后，拿到 `sessionUrl` 直接打开即可。\n\n### 3.3 只打开会话（不发送消息）\n\n如果你只想“进入某个会话页面”，不想触发模型，可以调用：\n\n- `POST /api/agent`\n- 传 `openOnly: true`\n- `message` 可为空\n- 必须传 `sessionId`\n\n请求示例：\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"openOnly\": true,\n    \"stream\": false\n  }'\n```\n\n返回示例：\n\n```json\n{\n  \"success\": true,\n  \"openOnly\": true,\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionPath\": \"/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"sessionUrl\": \"https://assistant.example.com/session/019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"isResumed\": true,\n  \"message\": \"Session link generated. No model call triggered.\"\n}\n```\n\n### 3.4 中断会话\n\n`POST /api/agent/abort`\n\n用于中断当前仍在运行中的会话。\n\n#### 请求体\n\n| 字段 | 类型 | 必填 | 说明 |\n|---|---|---|---|\n| `sessionId` | string | 是 | 要中断的会话 ID |\n| `provider` | string | 否 | `claude` / `codex` / `gemini` / `opencode`；默认 `claude` |\n\n#### 关键校验规则\n\n- `sessionId` 必须是非空字符串。\n- `provider` 如果传入，必须是 `claude` / `codex` / `gemini` / `opencode`。\n- 如果不传 `provider`，服务端按 `claude` 处理，不做自动识别。\n- 如果没有找到仍在运行中的会话，返回 `HTTP 200`，但 `success=false`。\n\n#### 返回（成功）\n\n```json\n{\n  \"success\": true,\n  \"aborted\": true,\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"provider\": \"claude\",\n  \"message\": \"Session aborted\"\n}\n```\n\n#### 返回（未找到活跃会话）\n\n```json\n{\n  \"success\": false,\n  \"aborted\": false,\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"provider\": \"claude\",\n  \"error\": \"Active session not found\"\n}\n```\n\n## 4. 对接流程（推荐）\n\n### 流程 A：创建新会话并打开\n\n1. 外部系统调用 `POST /api/agent`（不传 `sessionId`，且带 `message`）\n2. 保存返回的 `sessionId`\n3. 打开返回的 `sessionUrl`\n\n### 流程 B：进入并续聊已有会话\n\n1. 外部系统根据业务会话键找到已保存的 `sessionId`\n2. 调用 `POST /api/agent` 且传 `openOnly=true`（或直接拼接 URL）\n3. 如需服务端触发续聊，再调用 `POST /api/agent` 并传 `sessionId`\n\n<a id=\"usage-examples\"></a>\n\n## 5. cURL 示例\n\n### 5.1 创建新会话（MVP 无鉴权）\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"provider\": \"claude\",\n    \"message\": \"请先梳理当前项目结构并给出重构计划\",\n    \"stream\": false\n  }'\n```\n\n### 5.2 续聊指定会话\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"provider\": \"claude\",\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"message\": \"继续上一轮，把第 1、2 点先落代码\",\n    \"stream\": false\n  }'\n```\n\n### 5.3 只打开会话（不输入）\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"openOnly\": true,\n    \"stream\": false\n  }'\n```\n\n### 5.4 可选：携带 API Key\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: ck_xxx\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"message\": \"继续处理\"\n  }'\n```\n\n### 5.5 自动创建分支并发起 PR\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-API-Key: ck_xxx\" \\\n  -d '{\n    \"githubUrl\": \"https://github.com/user/repo\",\n    \"message\": \"修复鉴权逻辑并补充测试\",\n    \"createBranch\": true,\n    \"createPR\": true,\n    \"stream\": false\n  }'\n```\n\n### 5.6 指定自定义分支名\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectPath\": \"/Users/you/your-project\",\n    \"message\": \"新增 API 网关重试策略\",\n    \"branchName\": \"feature/api-retry-strategy\",\n    \"createPR\": true,\n    \"stream\": false\n  }'\n```\n\n### 5.7 中断运行中的会话\n\n```bash\ncurl -X POST <CURRENT_API_BASE>/agent/abort \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"provider\": \"codex\"\n  }'\n```\n\n## 6. 外部系统会话映射建议\n\n建议在外部系统保存映射：\n\n- `external_conversation_key -> sessionId`\n\n这样可保证：\n\n- 可重入（同一业务会话可重复进入）\n- 可续聊（服务端调用时带 `sessionId`）\n- 可跳转（拼接前端链接）\n\n<a id=\"frontend-integration\"></a>\n\n## 7. 动态上下文注入规范（MVP v2）\n\n当前前端会在“下一次用户发送消息”时自动附加一次动态上下文，注入格式如下：\n\n```text\n[DYNAMIC CONTEXT V1]\n{ ...contextV1 json... }\n\n[USER MESSAGE]\n...用户输入...\n```\n\n行为规则：\n\n1. `context` 仅附加一次；发送后标记为已发送。\n2. 收到新的 URL `context` 或新的 `postMessage(update_context)` 后，重置为未发送。\n3. `postMessage(update_context)` 默认 `mode=replace`（覆盖当前待发送上下文）。\n4. 当 `mode=append` 时：`selectedElements` 采用追加策略（建议按 `tag+selector+label` 去重），便于分批选元素。\n5. 当 `mode=append` 时：未传入字段保持原值；已传入字段更新为最新值。\n6. 输入区会展示上下文标签（系统上下文 / 当前文件 / 选中元素）。\n7. 用户可手动取消某个标签；取消仅影响当前待发送上下文。\n8. 如果用户取消后上下文为空，则本次不附加动态上下文块。\n\n非法输入处理：\n\n- `context` 非法 JSON（URL）或字段校验失败：忽略该上下文并 `console.warn`\n- 不会阻止用户继续发送消息\n\n<a id=\"faq\"></a>\n\n## 8. 常见问题\n\n### Q1：只想“打开会话页面”，不想触发模型怎么办？\n\n两种方式都可以：\n\n1. 直接跳转：`/session/{sessionId}`\n2. 调用 `POST /api/agent` 并传 `openOnly=true`\n\n### Q2：`sessionId` 传了但会话不存在会怎样？\n\n不同 provider 的底层行为可能不同（可能报错或新建）。建议外部系统以“本地已保存映射”为准，避免传错 ID。\n\n### Q3：如何从当前地址拿到 sessionId？\n\n例如你的地址：\n\n- `http://localhost:5173/session/019c3263-967f-7ba2-84fe-fc5c694f6316`\n\n其中 `019c3263-967f-7ba2-84fe-fc5c694f6316` 就是 `sessionId`。\n\n### Q4：`POST /api/agent/abort` 为什么返回 200 但 `success=false`？\n\n这表示请求本身是合法的，但服务端没有找到可中断的运行中会话。常见原因包括：\n\n1. `sessionId` 传错了\n2. `provider` 传错了\n3. 会话已经自然结束或之前已被中断\n\n## 9. 版本说明\n\n- 文档版本：MVP v1.2\n- 更新日期：2026-03-18\n- 文档来源：`docs/open-api-mvp.zh-CN.md`（`/api-docs.html` 由脚本生成）\n- 对应能力：`/api/agent` 支持 `sessionId` 续聊、`openOnly` 仅打开、`gemini/opencode` provider、可选 `createBranch/createPR`，`/api/agent/abort` 支持中断运行中会话\n";
     const root = document.getElementById('markdown-root');
 
     function scrollToHashAnchor() {