@axhub/genie 0.1.8 → 0.2.0

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

@@ -280,7 +280,7 @@
   <header>
     <div class="brand">
       <strong>Axhub Genie Open API</strong>
-      <small>Single Source: <code>docs/open-api-mvp.zh-CN.md</code></small>
+      <small>Source Set: <code>docs/open-api/*.zh-CN.md</code> -> <code>docs/open-api-mvp.zh-CN.md</code></small>
     </div>
     <div class="actions">
       <a href="/" class="primary">Back To App</a>
@@ -292,9 +292,9 @@
       <div class="title">Sections</div>
       <a href="#overview">Overview</a>
       <a href="#authentication">Authentication</a>
-      <a href="#agent">Agent API</a>
-      <a href="#frontend-integration">Frontend Integration</a>
-      <a href="#usage-examples">Usage Examples</a>
+      <a href="#http-api">HTTP API</a>
+      <a href="#ws-api">WebSocket API</a>
+      <a href="#cli-api">CLI API</a>
       <a href="#faq">FAQ</a>
     </nav>
     <section class="content">
@@ -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-22T04:01:13.470Z</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> Source Set：`docs/open-api/*.zh-CN.md`  \n> 聚合产物：`docs/open-api-mvp.zh-CN.md`  \n> 页面入口：`/api-docs.html`\n\n<a id=\"overview\"></a>\n\n适用场景：外部系统、本地服务、AI Agent 以及带网页编辑器的宿主应用，通过 Axhub Genie 的开放接口完成会话创建、续聊、中断、运行态观察，以及对在线网页编辑器实例做定向查询与控制。\n\n## Quick English Summary\n\n- HTTP: `GET /health`, `POST /api/agent`, `POST /api/agent/abort`\n- WebSocket: `WS /api/agent/ws`\n- CLI: `axhub-genie status`, `axhub-genie editor ...`\n- Editor integration model: enumerate online frontend clients first, then send editor requests to a specific `channel + targetClientId`\n\n## 1. 文档地图\n\n| 子文档 | 说明 |\n|---|---|\n| [`docs/open-api/http.zh-CN.md`](./http.zh-CN.md) | HTTP 接口、请求体、返回体、cURL 示例 |\n| [`docs/open-api/ws.zh-CN.md`](./ws.zh-CN.md) | `/api/agent/ws` 协议、集成 WS、editor 指令 |\n| [`docs/open-api/cli.zh-CN.md`](./cli.zh-CN.md) | `axhub-genie` CLI、editor 子命令、JSON 输出约定 |\n\n## 2. 基本信息\n\n- Assistant 前端地址示例：`http://localhost:5173`\n- Assistant 后端地址示例：`http://localhost:32123`\n- API Base 示例：`http://localhost:32123/api`\n- 会话页面路由格式：`/session/{sessionId}`\n- 健康检查：`GET /health`\n\n### 2.1 地址发现\n\n在开发、测试、生产环境中，地址可能不同。推荐始终先执行：\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使用建议：\n\n- 统一把 `endpoint.apiBaseUrl` 当作 `<CURRENT_API_BASE>`\n- editor CLI / WS 默认也以这里发现到的 API Base 为准\n\n### 2.2 服务身份识别\n\n为了避免误连到其他本地服务，建议对 `/health` 额外校验：\n\n- `service.id`\n- 响应头 `X-App-Identifier`\n\n推荐成功条件：\n\n- HTTP `200`\n- `status = ok`\n- `service.id = @axhub/genie`\n\n### 2.3 前端 URL 参数\n\n前端支持通过 URL 预选项目、provider 与动态上下文：\n\n| 参数 | 示例 | 说明 |\n|---|---|---|\n| `project` / `projectName` | `?project=my-project` | 按项目名/显示名/路径匹配 |\n| `cwd` / `workdir` | `?cwd=/Users/you/my-project` | 按工作目录匹配 |\n| `provider` / `tool` / `cli` | `?provider=codex` | 预设默认工具 |\n| `context` | `?context=...` | 动态上下文（`contextV1`） |\n| `prompt` | `?prompt=...` | 预填输入框内容 |\n| `integrationWs=1` | `?integrationWs=1` | 让页面额外连接 `/api/agent/ws` |\n| `integrationClientId` | `?integrationClientId=figma-123` | 当前前端页面实例标识 |\n| `integrationChannel` | `?integrationChannel=project-a` | 当前业务通道标识 |\n\n说明：\n\n- editor 相关的所有外部操作都应先锁定 `channel + targetClientId`\n- 当同时存在多个网页编辑器客户端时，必须先列出客户端，再定向操作\n\n<a id=\"authentication\"></a>\n\n## 3. 鉴权策略（MVP）\n\n- `/api/agent` 与 `/api/agent/ws` 默认允许本地匿名访问\n- 若设置 `AGENT_API_KEY_REQUIRED=true`，则：\n  - HTTP 通过 `X-API-Key`\n  - WebSocket 通过查询参数 `apiKey`\n- editor CLI 与外部系统连接 `/api/agent/ws` 时，复用相同的鉴权规则\n\n### 3.1 对外 WebSocket 与内部 UI WebSocket 的边界\n\n- `/ws`：前端应用内部协议，承载 UI 与 provider 的私有消息，不属于开放接口\n- `/api/agent/ws`：开放接口，承载 Agent 请求流、运行态查询/订阅、集成 WS，以及 editor 集成协议\n\n## 4. 能力总览\n\n### 4.1 HTTP\n\n- 创建会话 / 续聊：`POST /api/agent`\n- 打开既有会话：`POST /api/agent` + `openOnly=true`\n- 中断运行：`POST /api/agent/abort`\n\n详情见 [`docs/open-api/http.zh-CN.md`](./http.zh-CN.md)。\n\n### 4.2 WebSocket\n\n- `agent.run`\n- `agent.abort`\n- `agent.state.query`\n- `agent.state.subscribe`\n- `integration.connect`\n- `integration.ping`\n- `integration.context.update`\n- `integration.prompt.update`\n- `integration.editor.clients.list`\n- `integration.editor.snapshot.get`\n- `integration.editor.nodes.list`\n- `integration.editor.node.screenshot.get`\n- `integration.editor.context-images.get`\n- `integration.editor.editing.set`\n\n详情见 [`docs/open-api/ws.zh-CN.md`](./ws.zh-CN.md)。\n\n### 4.3 CLI\n\n- `axhub-genie status`\n- `axhub-genie editor clients list`\n- `axhub-genie editor snapshot`\n- `axhub-genie editor nodes list`\n- `axhub-genie editor node screenshot`\n- `axhub-genie editor context-images export`\n- `axhub-genie editor editing set`\n\n详情见 [`docs/open-api/cli.zh-CN.md`](./cli.zh-CN.md)。\n\n## 5. 推荐集成顺序\n\n1. 用 `axhub-genie status --json` 或 `/health` 发现服务地址并确认身份。\n2. 如果要操作网页编辑器，先通过 CLI 或 `integration.editor.clients.list` 枚举在线客户端。\n3. 保存 `channel + clientId`，后续请求都显式命中这个客户端。\n4. 对会话调用 HTTP 或 `agent.run`。\n5. 对网页编辑器调用 editor CLI 或 editor WS 指令。\n\n<a id=\"faq\"></a>\n\n## 6. FAQ\n\n### Q1：为什么 editor 命令必须指定客户端？\n\n因为同一时间可能存在多个在线网页编辑器页面，服务端不会默认广播 editor 读写请求。调用方应先拿到客户端列表，再定向到一个 `targetClientId`。\n\n### Q2：客户端还没升级 editor capability 时会怎样？\n\n服务端会返回：\n\n```json\n{\n  \"type\": \"integration.error\",\n  \"payload\": {\n    \"code\": \"UNSUPPORTED_FRONTEND_CAPABILITY\",\n    \"message\": \"Target frontend page does not advertise capability editor.snapshot\"\n  }\n}\n```\n\n### Q3：为什么要保留 `docs/open-api-mvp.zh-CN.md`？\n\n为了保持历史入口与 `/api-docs.html` 不变。维护时请编辑 `docs/open-api/*.zh-CN.md`，不要手改聚合产物。\n\n## 7. 版本说明\n\n- 文档版本：MVP v1.6\n- 更新日期：2026-03-21\n- 维护入口：`docs/open-api/*.zh-CN.md`\n- 聚合产物：`docs/open-api-mvp.zh-CN.md`\n\n---\n\n## HTTP API\n\n<a id=\"http-api\"></a>\n\n### 1. 健康检查\n\n#### `GET /health`\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`\n- `X-App-Name`\n- `X-App-Version`\n- `X-App-Environment`\n\n### 2. 创建或续聊会话\n\n#### `POST /api/agent`\n\n典型用途：\n\n- 新建会话并发送第一条消息\n- 带 `sessionId` 续聊既有会话\n- 带 `openOnly=true` 仅打开会话，不触发模型运行\n\n#### 2.1 请求体\n\n```json\n{\n  \"projectPath\": \"/Users/you/your-project\",\n  \"provider\": \"codex\",\n  \"message\": \"请先梳理当前项目结构并给出重构计划\",\n  \"stream\": false\n}\n```\n\n常用字段：\n\n| 字段 | 说明 |\n|---|---|\n| `projectPath` | 本地项目路径，可选；未传时按“服务启动配置目录 > 服务进程启动目录”回退 |\n| `provider` | `claude` / `codex` / `gemini` / `opencode` |\n| `model` | 可选模型名 |\n| `message` | 用户输入 |\n| `sessionId` | 既有会话 ID |\n| `openOnly` | 仅打开会话 |\n| `stream` | 是否流式返回 |\n| `images[]` | 附加图片 |\n| `createBranch` | 是否自动创建分支 |\n| `branchName` | 自定义分支名 |\n| `createPR` | 是否自动发起 PR |\n| `callback` | 终态回调配置 |\n\n#### 2.2 关键校验规则\n\n- `message` 在 `openOnly !== true` 时必填\n- `provider` 必须是受支持的 provider\n- `sessionId` 续聊时由调用方保证正确\n- `projectPath` 可省略；服务端会按“默认工作目录配置 > 进程当前目录”解析\n- `images[].data` 使用 data URL\n\n#### 2.3 返回（`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### 3. 只打开会话页面\n\n当你只想进入某个既有会话，而不想立刻发消息时：\n\n```json\n{\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"openOnly\": true,\n  \"stream\": false\n}\n```\n\n### 4. 中断运行中的会话\n\n#### `POST /api/agent/abort`\n\n请求示例：\n\n```json\n{\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"provider\": \"codex\"\n}\n```\n\n成功响应：\n\n```json\n{\n  \"success\": true,\n  \"aborted\": true,\n  \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n  \"provider\": \"codex\",\n  \"message\": \"Session aborted\"\n}\n```\n\n未找到活跃会话时，HTTP 仍可能返回 `200`，但 `success=false`。\n\n### 5. cURL 示例\n\n#### 5.1 创建新会话\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\": \"codex\",\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\": \"codex\",\n    \"message\": \"请描述这张截图并指出 UI 问题\",\n    \"images\": [\n      {\n        \"name\": \"ui.png\",\n        \"data\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...\",\n        \"mimeType\": \"image/png\"\n      }\n    ],\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    \"projectPath\": \"/Users/you/your-project\",\n    \"provider\": \"codex\",\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"message\": \"继续上一轮，把第 1、2 点先落代码\",\n    \"stream\": false\n  }'\n```\n\n#### 5.4 只打开会话\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.5 中断运行中的会话\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- 可续聊\n- 可跳转\n- 可中断\n\n---\n\n## WebSocket API\n\n<a id=\"ws-api\"></a>\n\n### 1. 连接地址\n\n```text\nWS /api/agent/ws\n```\n\n鉴权方式：\n\n- 默认本地匿名允许\n- 若开启 API Key，使用查询参数 `apiKey`\n\n### 2. 使用模式\n\n`/api/agent/ws` 同时承载三类开放能力：\n\n- Agent 请求流：`agent.run` / `agent.abort`\n- Agent 运行态：`agent.state.query` / `agent.state.subscribe`\n- 集成流：`integration.*`\n\n其中 editor 相关能力也属于 `integration.*` 协议的一部分。\n\n### 3. Agent 请求流\n\n#### 3.1 入站：`agent.run`\n\n```json\n{\n  \"type\": \"agent.run\",\n  \"requestId\": \"req_001\",\n  \"payload\": {\n    \"projectPath\": \"/Users/you/your-project\",\n    \"provider\": \"codex\",\n    \"message\": \"请继续处理当前任务\"\n  }\n}\n```\n\n说明：\n\n- `payload.projectPath` 可选\n- 若未传，服务端按“默认工作目录配置 > 进程当前目录”回退\n\n#### 3.2 入站：`agent.abort`\n\n```json\n{\n  \"type\": \"agent.abort\",\n  \"requestId\": \"req_002\",\n  \"payload\": {\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"provider\": \"codex\"\n  }\n}\n```\n\n#### 3.3 出站：典型序列\n\n1. `agent.accepted`\n2. `agent.session.created`\n3. 多个 `agent.event`\n4. `agent.completed`\n\n中断时终态为 `agent.aborted`；失败时终态为 `agent.error`。\n\n### 4. Agent 运行态查询/订阅\n\n#### 4.1 查询\n\n```json\n{\n  \"type\": \"agent.state.query\",\n  \"requestId\": \"state_001\",\n  \"payload\": {\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"provider\": \"codex\"\n  }\n}\n```\n\n响应：\n\n```json\n{\n  \"type\": \"agent.state.snapshot\",\n  \"requestId\": \"state_001\",\n  \"payload\": {\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"provider\": \"codex\",\n    \"phase\": \"streaming\",\n    \"isLoading\": true,\n    \"canAbortSession\": true,\n    \"hasPendingApproval\": false,\n    \"updatedAt\": \"2026-03-20T10:00:01.000Z\"\n  }\n}\n```\n\n#### 4.2 订阅\n\n```json\n{\n  \"type\": \"agent.state.subscribe\",\n  \"requestId\": \"state_002\",\n  \"payload\": {\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"provider\": \"codex\"\n  }\n}\n```\n\n确认：\n\n```json\n{\n  \"type\": \"agent.state.subscribed\",\n  \"requestId\": \"state_002\",\n  \"payload\": {\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"provider\": \"codex\",\n    \"subscriptionKey\": \"codex:019c3263-967f-7ba2-84fe-fc5c694f6316\"\n  }\n}\n```\n\n变化通知：\n\n```json\n{\n  \"type\": \"agent.state.changed\",\n  \"payload\": {\n    \"subscriptionKey\": \"codex:019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"provider\": \"codex\",\n    \"phase\": \"completed\",\n    \"isLoading\": false,\n    \"canAbortSession\": false,\n    \"hasPendingApproval\": false,\n    \"updatedAt\": \"2026-03-20T10:00:08.000Z\"\n  }\n}\n```\n\n### 5. 集成流基础协议\n\n#### 5.1 页面注册：`integration.connect`\n\n前端页面示例：\n\n```json\n{\n  \"type\": \"integration.connect\",\n  \"requestId\": \"conn_001\",\n  \"payload\": {\n    \"role\": \"frontend-page\",\n    \"channel\": \"project-a\",\n    \"clientId\": \"figma-123\",\n    \"pageUrl\": \"http://localhost:5173/session/019c...?...\",\n    \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n    \"capabilities\": [\n      \"context.update\",\n      \"prompt.update\",\n      \"presence.report\"\n    ]\n  }\n}\n```\n\n外部系统示例：\n\n```json\n{\n  \"type\": \"integration.connect\",\n  \"requestId\": \"conn_002\",\n  \"payload\": {\n    \"role\": \"external-client\",\n    \"channel\": \"project-a\",\n    \"clientId\": \"host-app-01\",\n    \"capabilities\": [\n      \"presence.query\",\n      \"context.push\",\n      \"prompt.push\",\n      \"editor.query\"\n    ]\n  }\n}\n```\n\n#### 5.2 探活：`integration.ping`\n\n```json\n{\n  \"type\": \"integration.ping\",\n  \"requestId\": \"ping_001\",\n  \"payload\": {\n    \"channel\": \"project-a\",\n    \"targetClientId\": \"figma-123\"\n  }\n}\n```\n\n响应：\n\n```json\n{\n  \"type\": \"integration.pong\",\n  \"requestId\": \"ping_001\",\n  \"payload\": {\n    \"server\": {\n      \"status\": \"ok\",\n      \"started\": true\n    },\n    \"frontend\": {\n      \"connected\": true,\n      \"count\": 1,\n      \"clients\": [\n        {\n          \"clientId\": \"figma-123\",\n          \"lastSeenAt\": \"2026-03-19T10:00:03.000Z\",\n          \"pageUrl\": \"http://localhost:5173/session/019c...?integrationWs=1...\",\n          \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\"\n        }\n      ]\n    }\n  }\n}\n```\n\n#### 5.3 运行期上下文/提示词写入\n\n- `integration.context.update`\n- `integration.prompt.update`\n\n它们沿用既有协议，行为保持不变。\n\n### 6. Editor 集成协议\n\n#### 6.1 设计原则\n\n- 统一复用 `/api/agent/ws`\n- 统一带 `requestId`\n- 除 `clients.list` 外，统一要求 `channel + targetClientId`\n- 读操作终态为 `integration.editor.*.result`\n- 参数错误、目标页离线、超时、能力不支持统一走 `integration.error`\n- 写操作可以先回 `integration.ack`，但终态仍以 `integration.editor.*.result` 或 `integration.error` 为准\n\n#### 6.2 先列出客户端\n\n##### 入站：`integration.editor.clients.list`\n\n```json\n{\n  \"type\": \"integration.editor.clients.list\",\n  \"requestId\": \"editor_clients_001\",\n  \"payload\": {\n    \"channel\": \"project-a\"\n  }\n}\n```\n\n##### 出站：`integration.editor.clients.result`\n\n```json\n{\n  \"type\": \"integration.editor.clients.result\",\n  \"requestId\": \"editor_clients_001\",\n  \"payload\": {\n    \"items\": [\n      {\n        \"channel\": \"project-a\",\n        \"clientId\": \"figma-123\",\n        \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n        \"pageUrl\": \"http://localhost:5173/session/019c...?integrationWs=1...\",\n        \"lastSeenAt\": \"2026-03-21T09:00:00.000Z\",\n        \"connectedAt\": \"2026-03-21T08:58:00.000Z\",\n        \"connectionId\": \"conn_001\",\n        \"capabilities\": [\n          \"context.update\",\n          \"prompt.update\",\n          \"editor.snapshot\",\n          \"editor.nodes.list\",\n          \"editor.node.screenshot\",\n          \"editor.context-images\",\n          \"editor.editing.set\"\n        ]\n      }\n    ],\n    \"total\": 1,\n    \"filters\": {\n      \"channel\": \"project-a\",\n      \"clientId\": null\n    }\n  }\n}\n```\n\n#### 6.3 编辑器快照\n\n##### 入站：`integration.editor.snapshot.get`\n\n```json\n{\n  \"type\": \"integration.editor.snapshot.get\",\n  \"requestId\": \"editor_snapshot_001\",\n  \"payload\": {\n    \"channel\": \"project-a\",\n    \"targetClientId\": \"figma-123\"\n  }\n}\n```\n\n##### 出站：`integration.editor.snapshot.result`\n\n```json\n{\n  \"type\": \"integration.editor.snapshot.result\",\n  \"requestId\": \"editor_snapshot_001\",\n  \"payload\": {\n    \"resource\": null,\n    \"selectedElement\": null,\n    \"modifiedElements\": [],\n    \"textChanges\": [],\n    \"styleChanges\": {\n      \"cssText\": \"\"\n    },\n    \"statusSummary\": {\n      \"active\": true,\n      \"modifiedCount\": 0,\n      \"nodeStateCounts\": {\n        \"clean\": 0,\n        \"dirty\": 0,\n        \"handled\": 0,\n        \"editing\": 0,\n        \"completed\": 0,\n        \"error\": 0\n      }\n    }\n  }\n}\n```\n\n#### 6.4 节点列表\n\n##### 入站：`integration.editor.nodes.list`\n\n```json\n{\n  \"type\": \"integration.editor.nodes.list\",\n  \"requestId\": \"editor_nodes_001\",\n  \"payload\": {\n    \"channel\": \"project-a\",\n    \"targetClientId\": \"figma-123\",\n    \"status\": [\"pending-dispatch\", \"dirty\"],\n    \"elementKey\": null,\n    \"limit\": 100\n  }\n}\n```\n\n##### 出站：`integration.editor.nodes.result`\n\n```json\n{\n  \"type\": \"integration.editor.nodes.result\",\n  \"requestId\": \"editor_nodes_001\",\n  \"payload\": {\n    \"items\": [\n      {\n        \"elementKey\": \"hero-card\",\n        \"label\": \"body > main > section.hero-card\",\n        \"changeState\": \"dirty\",\n        \"taskState\": \"idle\",\n        \"hasNote\": true,\n        \"hasImages\": false,\n        \"changeKinds\": [\"text\"],\n        \"dirtySince\": 1742547600000,\n        \"lastHandledAt\": null\n      }\n    ],\n    \"total\": 1,\n    \"filters\": {\n      \"status\": [\"pending-dispatch\", \"dirty\"],\n      \"elementKey\": null,\n      \"limit\": 100\n    }\n  }\n}\n```\n\n推荐状态字段：\n\n- `changeState`: `clean` / `dirty` / `handled`\n- `taskState`: `idle` / `editing` / `completed` / `error`\n- `hasNote`\n- `hasImages`\n- `changeKinds`\n- `dirtySince`\n- `lastHandledAt`\n\n推荐状态别名：\n\n- `dirty`\n- `handled`\n- `editing`\n- `completed`\n- `error`\n- `pending-dispatch`\n  定义为 `changeState=dirty && taskState=idle && changeState!=handled`\n\n#### 6.5 节点截图\n\n##### 入站：`integration.editor.node.screenshot.get`\n\n```json\n{\n  \"type\": \"integration.editor.node.screenshot.get\",\n  \"requestId\": \"editor_shot_001\",\n  \"payload\": {\n    \"channel\": \"project-a\",\n    \"targetClientId\": \"figma-123\",\n    \"elementKey\": \"hero-card\",\n    \"downloadPath\": \"/Users/you/tmp\"\n  }\n}\n```\n\n说明：\n\n- `downloadPath` 是服务端本地落盘目录，不是前端页面自己的文件路径\n- 前端页面收到指令后，应将截图内容以 `data:<mime>;base64,...` 的形式回传给服务端\n- 服务端收到 base64/data URL 后负责写入本地文件，再把 `absolutePath` 返回给 CLI / 外部调用方\n\n##### 前端页面回包：`integration.editor.node.screenshot.result`\n\n```json\n{\n  \"type\": \"integration.editor.node.screenshot.result\",\n  \"requestId\": \"editor_shot_001\",\n  \"payload\": {\n    \"elementKey\": \"hero-card\",\n    \"image\": {\n      \"name\": \"hero-card.png\",\n      \"data\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...\",\n      \"width\": 1440,\n      \"height\": 640\n    },\n    \"mimeType\": \"image/png\",\n    \"width\": 1440,\n    \"height\": 640\n  }\n}\n```\n\n兼容说明：\n\n- 前端可以把 `data` 放在 `payload.image.data`\n- 也可以直接放在 `payload.data`\n- 如果前端未来已经具备本地文件访问代理能力，服务端当前也兼容直接回传 `absolutePath`，但推荐协议仍然是回传 data URL，由服务端统一落盘\n\n##### 服务端对外回包：`integration.editor.node.screenshot.result`\n\n```json\n{\n  \"type\": \"integration.editor.node.screenshot.result\",\n  \"requestId\": \"editor_shot_001\",\n  \"payload\": {\n    \"elementKey\": \"hero-card\",\n    \"absolutePath\": \"/Users/you/tmp/hero-card.png\",\n    \"mimeType\": \"image/png\",\n    \"width\": 1440,\n    \"height\": 640,\n    \"size\": 482113\n  }\n}\n```\n\n#### 6.6 上下文图片导出\n\n##### 入站：`integration.editor.context-images.get`\n\n```json\n{\n  \"type\": \"integration.editor.context-images.get\",\n  \"requestId\": \"editor_ctximg_001\",\n  \"payload\": {\n    \"channel\": \"project-a\",\n    \"targetClientId\": \"figma-123\",\n    \"downloadPath\": \"/Users/you/tmp\"\n  }\n}\n```\n\n说明：\n\n- `downloadPath` 同样是服务端本地目录\n- 前端页面应把上下文图片逐项回传为 data URL / base64\n- 服务端负责逐张写入本地，并返回每张图片的 `absolutePath`\n\n##### 前端页面回包：`integration.editor.context-images.result`\n\n```json\n{\n  \"type\": \"integration.editor.context-images.result\",\n  \"requestId\": \"editor_ctximg_001\",\n  \"payload\": {\n    \"items\": [\n      {\n        \"id\": \"img_001\",\n        \"name\": \"clipboard-image-1.png\",\n        \"data\": \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...\",\n        \"mimeType\": \"image/png\",\n        \"createdAt\": 1742547600000,\n        \"source\": \"prompt-context\"\n      }\n    ]\n  }\n}\n```\n\n##### 服务端对外回包：`integration.editor.context-images.result`\n\n```json\n{\n  \"type\": \"integration.editor.context-images.result\",\n  \"requestId\": \"editor_ctximg_001\",\n  \"payload\": {\n    \"items\": [\n      {\n        \"id\": \"img_001\",\n        \"name\": \"clipboard-image-1.png\",\n        \"absolutePath\": \"/Users/you/tmp/clipboard-image-1.png\",\n        \"mimeType\": \"image/png\",\n        \"size\": 90312,\n        \"createdAt\": 1742547600000,\n        \"source\": \"prompt-context\"\n      }\n    ]\n  }\n}\n```\n\n#### 6.7 编辑态设置\n\n##### 入站：`integration.editor.editing.set`\n\n```json\n{\n  \"type\": \"integration.editor.editing.set\",\n  \"requestId\": \"editor_editing_001\",\n  \"payload\": {\n    \"channel\": \"project-a\",\n    \"targetClientId\": \"figma-123\",\n    \"elementKey\": \"hero-card\",\n    \"state\": \"editing\",\n    \"taskRef\": {\n      \"provider\": \"codex\",\n      \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n      \"requestId\": \"req_001\"\n    }\n  }\n}\n```\n\n##### 出站：`integration.editor.editing.result`\n\n```json\n{\n  \"type\": \"integration.editor.editing.result\",\n  \"requestId\": \"editor_editing_001\",\n  \"payload\": {\n    \"elementKey\": \"hero-card\",\n    \"state\": \"editing\",\n    \"applied\": true,\n    \"taskRef\": {\n      \"provider\": \"codex\",\n      \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n      \"requestId\": \"req_001\"\n    }\n  }\n}\n```\n\n#### 6.8 能力声明\n\n服务端会在转发 editor 指令前检查目标前端页面是否声明以下 capability：\n\n| 消息类型 | capability |\n|---|---|\n| `integration.editor.snapshot.get` | `editor.snapshot` |\n| `integration.editor.nodes.list` | `editor.nodes.list` |\n| `integration.editor.node.screenshot.get` | `editor.node.screenshot` |\n| `integration.editor.context-images.get` | `editor.context-images` |\n| `integration.editor.editing.set` | `editor.editing.set` |\n\n若目标页未声明对应 capability，服务端返回：\n\n```json\n{\n  \"type\": \"integration.error\",\n  \"requestId\": \"editor_snapshot_001\",\n  \"payload\": {\n    \"code\": \"UNSUPPORTED_FRONTEND_CAPABILITY\",\n    \"message\": \"Target frontend page does not advertise capability editor.snapshot\"\n  }\n}\n```\n\n#### 6.9 常见错误码\n\n- `FRONTEND_NOT_ONLINE`\n- `INVALID_TARGET`\n- `INVALID_PAYLOAD`\n- `UNSUPPORTED_MESSAGE_TYPE`\n- `UNSUPPORTED_FRONTEND_CAPABILITY`\n- `REQUEST_TIMEOUT`\n\n---\n\n## CLI API\n\n<a id=\"cli-api\"></a>\n\n### 1. 地址发现与状态检查\n\n#### `axhub-genie status`\n\n用于查看：\n\n- 当前服务是否运行\n- PID / 端口\n- `endpoint.frontendUrl`\n- `endpoint.apiBaseUrl`\n\n示例：\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  \"defaultProjectPath\": \"/Users/you/your-project\",\n  \"endpoint\": {\n    \"environment\": \"development\",\n    \"frontendUrl\": \"http://localhost:5173\",\n    \"apiBaseUrl\": \"http://localhost:32123/api\"\n  }\n}\n```\n\n说明：\n\n- 启动服务时可通过 `axhub-genie --cwd /path/to/project` 配置默认工作目录\n- 当开放 API 未显式传 `projectPath` 时，服务端按“默认工作目录配置 > 服务进程启动目录”回退\n\n### 2. Editor 子命令\n\n所有 editor 子命令都默认输出 JSON，并通过 `/api/agent/ws` 与在线 frontend-page 通信。\n\n#### 2.1 通用参数\n\n| 参数 | 说明 |\n|---|---|\n| `--api-base <url>` | 显式指定 API Base，默认自动发现 |\n| `--api-key <key>` | 连接 `/api/agent/ws` 时的 API Key |\n| `--channel <name>` | 目标业务通道 |\n| `--target-client-id <id>` | 目标前端页面实例 |\n| `--timeout-ms <ms>` | 请求超时 |\n| `--json` | 显式声明 JSON 输出 |\n| `--output-dir <path>` | 截图/图片导出目录，默认当前目录 |\n\n统一成功包型：\n\n```json\n{\n  \"ok\": true,\n  \"requestId\": \"editor_001\",\n  \"channel\": \"project-a\",\n  \"targetClientId\": \"figma-123\",\n  \"data\": {}\n}\n```\n\n统一失败包型：\n\n```json\n{\n  \"ok\": false,\n  \"requestId\": \"editor_001\",\n  \"channel\": \"project-a\",\n  \"targetClientId\": \"figma-123\",\n  \"error\": {\n    \"code\": \"FRONTEND_NOT_ONLINE\",\n    \"message\": \"Target frontend page is not connected\"\n  }\n}\n```\n\n失败时 CLI 以非 0 退出码结束。\n\n### 3. 推荐顺序：先列客户端\n\n#### `axhub-genie editor clients list`\n\n作用：列出当前在线的网页编辑器客户端，避免把 editor 请求广播给错误页面。\n\n示例：\n\n```bash\naxhub-genie editor clients list --channel project-a\n```\n\n返回示例：\n\n```json\n{\n  \"ok\": true,\n  \"requestId\": \"editor_xxx\",\n  \"channel\": null,\n  \"targetClientId\": null,\n  \"data\": {\n    \"items\": [\n      {\n        \"channel\": \"project-a\",\n        \"clientId\": \"figma-123\",\n        \"sessionId\": \"019c3263-967f-7ba2-84fe-fc5c694f6316\",\n        \"pageUrl\": \"http://localhost:5173/session/019c...?integrationWs=1...\",\n        \"lastSeenAt\": \"2026-03-21T09:00:00.000Z\",\n        \"connectedAt\": \"2026-03-21T08:58:00.000Z\",\n        \"connectionId\": \"conn_001\",\n        \"capabilities\": [\n          \"editor.snapshot\",\n          \"editor.nodes.list\"\n        ]\n      }\n    ],\n    \"total\": 1,\n    \"filters\": {\n      \"channel\": \"project-a\",\n      \"clientId\": null\n    }\n  }\n}\n```\n\n### 4. Editor 快照与节点\n\n#### `axhub-genie editor snapshot`\n\n```bash\naxhub-genie editor snapshot \\\n  --channel project-a \\\n  --target-client-id figma-123\n```\n\n返回字段覆盖：\n\n- `resource`\n- `selectedElement`\n- `modifiedElements`\n- `textChanges`\n- `styleChanges`\n- `statusSummary`\n\n#### `axhub-genie editor nodes list`\n\n```bash\naxhub-genie editor nodes list \\\n  --channel project-a \\\n  --target-client-id figma-123 \\\n  --status pending-dispatch,dirty \\\n  --limit 100\n```\n\n推荐状态字段：\n\n- `changeState`\n  - `clean`\n  - `dirty`\n  - `handled`\n- `taskState`\n  - `idle`\n  - `editing`\n  - `completed`\n  - `error`\n- `hasNote`\n- `hasImages`\n- `changeKinds`\n- `dirtySince`\n- `lastHandledAt`\n\n推荐状态别名：\n\n- `dirty`\n- `handled`\n- `editing`\n- `completed`\n- `error`\n- `pending-dispatch`\n  定义为 `changeState=dirty && taskState=idle && changeState!=handled`\n\n### 5. 截图与上下文图片\n\n约定：\n\n- 前端页面通过 WS 把截图/图片内容以 data URL / base64 回传给服务端\n- 服务端再把文件写入 `--output-dir` 指向的本地目录\n- CLI 最终返回的是服务端已经落好的绝对路径，而不是前端页面自己的临时路径\n\n#### `axhub-genie editor node screenshot`\n\n```bash\naxhub-genie editor node screenshot \\\n  --channel project-a \\\n  --target-client-id figma-123 \\\n  --element-key hero-card \\\n  --output-dir .\n```\n\n返回：\n\n- `absolutePath`\n- `mimeType`\n- `width`\n- `height`\n- `size`\n\n#### `axhub-genie editor context-images export`\n\n```bash\naxhub-genie editor context-images export \\\n  --channel project-a \\\n  --target-client-id figma-123 \\\n  --output-dir .\n```\n\n返回每张图片的：\n\n- `id`\n- `name`\n- `absolutePath`\n- `mimeType`\n- `size`\n- `createdAt`\n- `source`\n\n### 6. 编辑态设置\n\n#### `axhub-genie editor editing set`\n\n```bash\naxhub-genie editor editing set \\\n  --channel project-a \\\n  --target-client-id figma-123 \\\n  --element-key hero-card \\\n  --state editing \\\n  --provider codex \\\n  --session-id 019c3263-967f-7ba2-84fe-fc5c694f6316 \\\n  --task-request-id req_001\n```\n\n说明：\n\n- `--state` 只允许 `editing` 或 `idle`\n- 可选通过 `--provider` / `--session-id` / `--task-request-id` 传递任务追踪信息\n\n### 7. 常见失败原因\n\n#### 7.1 `FRONTEND_NOT_ONLINE`\n\n表示目标 `channel + targetClientId` 当前没有在线页面。\n\n#### 7.2 `UNSUPPORTED_FRONTEND_CAPABILITY`\n\n表示目标页面已经在线，但还没有升级到支持该 editor 指令的客户端版本。\n\n#### 7.3 `REQUEST_TIMEOUT`\n\n表示服务端已转发请求，但在超时时间内没有收到目标前端的最终 `*.result`。\n";
     const root = document.getElementById('markdown-root');
 
     function scrollToHashAnchor() {