draftgo-cli 3.0.35 → 3.0.38

package/README.md

@@ -1,364 +1,312 @@
 # draftgo-cli
 
-跨 AI 编码工具一键安装 / 更新 / 卸载 DraftGo 开发助手 skill 的命令行工具。
+面向 AI 编码工具的 DraftGo 工作台 CLI：分发 DraftGo Skill，通过 MCP 发现和操作实时资源，并为页面、导航和文档提供可校验的 `checkout` / `commit` 工作流。
 
-支持的 AI 工具：Claude Code、Codex CLI、Cursor、Windsurf、Antigravity、GitHub Copilot、Gemini CLI、Kiro。
+DraftGo Next 前端基线为 React + Vite；数据库页面以标准 HTML + Tailwind CSS 为核心。CLI 仍提供 Docker 本地运行、项目检查和浏览器验证能力。
 
-## 前置条件
-
-- Node.js >=20.19（运行 CLI）
-- Python 3.9+（运行 DraftGo init/sync 脚本；CLI 本身不需要）
+支持安装 Skill 的宿主：Claude Code、Codex CLI、Cursor、Windsurf、Antigravity、GitHub Copilot、Gemini CLI、Kiro。
 
-## DraftGo Next v3 基线
+## 前置条件
 
-DraftGo Next 前端基线为 React + Vite。draftgo-cli v3 的定位是 DraftGo 工作台 CLI：负责本地运行环境、资源同步、开发检查、push/pull 闭环和 AI 工具 skill 分发。
+- Node.js >=20.19
+- 使用 `draftgo local ...` 时需要 Docker 和 Docker Compose
 
-数据库页面以 HTML 为核心，默认使用 Tailwind CSS 和页面级 CSS。
+CLI 不再依赖 Python 同步脚本，也不会创建 DraftGo 业务资源的全量本地镜像。
 
-核心命令为 `draftgo init/update/status/map/check/connect/local setup`；工作台命令如下：
+## 工作模型
 
-| 命令 | 说明 |
-|---|---|
-| `draftgo local setup` | 生成 `.draftgo/docker/docker-compose.yaml`，初始化并启动本地 DraftGo 栈。`draftgo local-dev` 保留为兼容入口。 |
-| `draftgo local start` | 启动本地栈。`up` 是兼容别名。 |
-| `draftgo local stop` | 停止本地栈。`down` 是兼容别名。 |
-| `draftgo local logs` | 查看本地栈日志，默认跟随 `app` 服务。 |
-| `draftgo local status` | 查看本地栈容器状态。 |
-| `draftgo check` | 本地资源检查：发现页面未绑定入口、页面/导航 HTML 解析问题、未登记到 `index.json` 的本地资源文件；不启动或构建底座。 |
-| `draftgo verify-ui <url>` | 使用 Playwright 执行单视口 UI smoke check；默认按 Git 变更判断，失败时才截图。 |
-| `draftgo api <keyword>` | 检索 DraftGo 底座内置 OpenAPI，并展示请求字段、响应结构与鉴权信息。自定义服务端点由 `app.Route` 动态注册，不在此索引中。 |
-| `draftgo pull` | 包装随 skill 分发的 `draftgo_pull.py`，默认 `--all` 拉取资源。 |
-| `draftgo push` | 包装随 skill 分发的 `draftgo_push.py`，推送页面、导航、DB meta 等资源。 |
-| `draftgo deploy` | 显式执行 check → push；支持 `--delivery local|preview|deploy`。 |
-
-## 安装
+```text
+AI 宿主 -> draftgo mcp serve -> DraftGo /mcp
+                                     |
+                                     +-> 结构化资源、元数据、搜索和正文片段
 
-```bash
-npm install -g draftgo-cli
+draftgo checkout/commit -> DraftGo 专用 HTTP 正文端点
+                           （完整 HTML/Markdown 不经过 MCP 上下文）
 ```
 
-## 快速开始
+- MCP 用于项目概览、资源搜索/列表、元数据、正文片段和实时 API 调用。
+- `pages`、`navigations` 和 `docs/articles` 的完整正文使用 `checkout` / `commit`。
+- `db_meta`、AIHub、`system_config`、角色、用户、文档分类、自定义服务等结构化资源直接通过 MCP/API 操作，不生成本地索引。
+- `.draftgo/pages/`、`.draftgo/navigations/` 等旧 `index.json` 缓存只视为 legacy 数据；CLI 不删除它们，但 `map` 和 `check` 会忽略它们。
+- DraftGo Skill 继续提供资源关系、页面规范、数据和权限、安全规则、自定义服务经验以及验证流程；MCP 不替代 Skill。
 
-```bash
-cd /path/to/your/project
-draftgo init                 # 自动识别当前项目在用的 AI 工具并安装
-```
+## Agent 阅读顺序
 
-也可以手动指定要安装到哪些 AI 工具：
+DraftGo Skill 不能被 MCP 替代。根 `SKILL.md` 会在 Skill 触发时自动加载；Agent 随后按任务读取相关领域资料，再查询实时状态：
 
-```bash
-draftgo init claudecode                  # 只装 Claude Code
-draftgo init claudecode kiro cursor      # 多选
-draftgo init all                         # 所有支持的工具
+```text
+已加载的 SKILL.md -> 按任务读取 references/ 中的领域规则 -> MCP 查询当前状态 -> 必要时 checkout 正文
 ```
 
-## 命令清单
-
-| 命令 | 说明 |
-|---|---|
-| `draftgo init [target]...` | 安装 skill。不传 target 时自动识别；`all` 表示全部。 |
-| `draftgo update [target]...` | 完整更新：先更新全局 CLI，再用新版原子刷新已安装或检测到的 AI 工具 skill。离线时仍会用当前 CLI 刷新 skill。 |
-| `draftgo uninstall [target]...` | 移除指定 AI 工具的 skill 目录（含入口文件 + 子技能 + scripts）。加 `--purge` 会连 `.draftgo/` 一起删。 |
-| `draftgo status` | 查看当前项目装了哪些 AI 工具入口、skill 版本。 |
-| `draftgo map` | 输出本地 DraftGo 资源地图：页面、导航、DB、脚本、AIHub、文档、系统配置、入口引用，帮助 AI 快速进入项目。 |
-| `draftgo check` | 本地资源检查：页面未绑定入口、页面/导航 HTML 解析问题、未登记到 `index.json` 的本地资源文件。 |
-| `draftgo verify-ui <url>` | 浏览器 smoke check；支持 `--mobile-check auto|always|never` 和失败截图。 |
-| `draftgo api <keyword>` | 查询 DraftGo 底座内置 OpenAPI 端点，输出请求字段、响应结构与鉴权信息；自定义服务端点需从 `app.Route` 推导。 |
-| `draftgo deploy [type] [id...]` | 显式交付；`local` 只检查，`preview` dry-run，`deploy` 推送。 |
-| `draftgo list-targets` | 列出支持的 AI 工具名。 |
-| `draftgo --version` | 打印 CLI 版本。 |
-| `draftgo --help` | 查看帮助。 |
-
-### 全局选项
+例如，盘点页面或判断业务模块前先读 `references/architecture.md` 和 `references/modules.md`。页面或导航的分析、修改、交互和 UI 任务先读 `references/frontend.md`；只有涉及路由、会话、`App` API、iframe/全局注入或运行时行为时才追加 `references/runtime.md`，涉及外部资产/CDN、认证、用户输入或不可信内容、敏感数据或配置时才追加 `references/security.md`。静态资源须先区分：平台内置目录直接由 `frontend.md` 说明，指定页面依赖经 MCP 定位、checkout 后本地搜索，服务器全量文件则不能凭现有 Skill、MCP 摘要或 checkout 声称已枚举。`mcp test` 是连接诊断，不是每次资源查询的前置步骤。
 
-- `--project <dir>`：对指定目录操作（默认当前工作目录）。
-- `--force`：`init/update` 时强制覆盖已存在的 AI 工具 skill 目录。
-- `--skip-update-check`：`update` 时不去 npm 查最新版，直接用当前 CLI 刷新 skill。
-- `--purge`：`uninstall` 时连 `.draftgo/`（含 config / 日志 / 本地缓存）一起删。
-- `--output json`：`map/check` 输出机器可读 JSON。
-- `--strict`：`check` 将提醒项也视为失败。
-- `--mobile-check auto|always|never`：控制 `verify-ui` 是否执行，默认 `auto`。
-- `--screenshot on-failure|always|never`：控制 UI 截图，默认仅失败时生成。
-- `--delivery local|preview|deploy`：控制 `deploy` 的交付级别。
+Skill 说明产品约束、内置能力和操作规则；MCP 说明当前远端状态；checkout 正文才能证明某个页面完整引用了哪些静态资源。汇报时应明确标注这三类证据，不能互相替代。
 
-版本查询结果缓存 24 小时。可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭版本检查（离线、CI 等场景）。
+## 安装与连接
 
-### 机器可读输出
-
-`draftgo map --output json` 会输出本地资源地图，适合 Agent 在开发前快速读取上下文；覆盖 pages、navigations、db_meta、custom_scripts、aihub、docs、doc_categories、system_config、roles 和入口引用。AIHub 条目会包含常用配置摘要：
-
-- `type=model`：模型数量、`supports_response_format`、`supports_json_schema`、图片生成诊断摘要。
-- `type=agent`：`mode`、主模型/备用模型、`output_format`、用户选模型配置、工具来源摘要。
-- `type=mcp`：传输协议、已发现工具数量。
-
-文档会摘要 `slug/category/content_file/status`，系统配置只展示 `config_key/category/value_type/is_sensitive/status`，避免把敏感值直接暴露给 Agent 输出。
+```bash
+npm install -g draftgo-cli
 
-`draftgo check --output json` 会输出 `{ map, errors, warnings, warningDetails }`，其中 `warningDetails` 带规则编号与置信度。当前只检查页面入口绑定、页面/导航 HTML 解析，以及未登记到 `index.json` 的本地资源文件；`--strict` 会把 warnings 也视为失败。
+cd /path/to/your/project
+draftgo init                 # 自动识别宿主并安装 DraftGo Skill
+draftgo connect codex        # 输入 server 和 SAT，验证 MCP，并配置 Codex
+```
 
-## 更新
+也可以非交互连接：
 
 ```bash
-cd <your-project>
-draftgo update
+draftgo connect codex --server https://draftgo.example --token "$DRAFTGO_SAT"
 ```
 
-`update` 是唯一的完整更新命令：
-
-- 如果 CLI 已是最新 → 原子替换每个目标的 skill 资源
-- 如果 npm 有新版 → 先全局更新 CLI，再由新版刷新 skill
-- 如果 npm 暂不可达 → 保留当前 CLI，并刷新 skill
+`connect` 会先验证 SAT、MCP `initialize`、`tools/list` 和关键 `tools/call`，成功后写入项目私有配置 `.draftgo/config.json`，并尝试为指定或自动检测到的宿主执行 MCP setup。它不会 pull 页面、导航、文档或任何其他业务资源。
 
-整个过程中，你本地的 `.draftgo/config.json`、`changelog.md`、`lessons/`、`Task/` 等运行时数据都不会被动到。
+远端暂不可用时，只有显式传入 `--allow-offline` 才会保存配置；恢复后运行 `draftgo mcp test`。使用 `--no-mcp-setup` 可跳过宿主配置。
 
-## 内置 Skill 文档约定
+`connect` 会把以下运行时路径加入项目 `.gitignore`：
 
-内置 Skill 同时提供 `resources/skill/manifest.json`：这是 DraftGo 的机器可读元数据（版本、入口、能力和声明权限），为自研宿主或未来平台适配提供统一入口；各 AI 工具仍使用各自的安装入口文件。
-
-CLI 随包分发的 DraftGo skill 会同步基座 API 约定。集合写入统一为：
-
-- 创建：`POST /api/<resource>` 支持单个对象或对象数组。
-- 批量更新：`PATCH /api/<resource>/batch`，请求体为带 `id` 的对象数组。
-- 动态 DB 因为资源带 `type`，批量更新路径是 `PATCH /api/db/{type}/batch`。
-- GET 列表请求不传 `page` / `page_size` 时全量返回且无数量上限；任一分页参数传入时正常分页，缺失项按 `page=1` / `page_size=20` 兜底。
-
-前端资源约定：
+```text
+.draftgo/config.json
+.draftgo/token
+.draftgo/worktree/
+.draftgo/conflicts/
+```
 
-- 壳层源码使用 React 19 + Vite 8 + Tailwind CSS 4；数据库页面和导航使用原生 HTML，不可写入 TSX、ESM import 或 npm 构建产物。数据库页面需要 React 时使用内置 React 18 UMD。
-- 内置组件库：Ant Design 5.29.3（React 18 UMD）、Basecoat UI 1.0.2（HTML + CSS/JS）、Oat UI 0.7.0（Web Components）。组件清单、运行方式和资源路径见 `resources/skill/references/frontend.md`；该文档不规定选型。
-- `/assets/adapters/draftgo-ui.js` 提供 `window.DraftGoUI` 和 `DraftGoUI.load(name)`；Basecoat/Oat 的主题适配资源为 `/assets/adapters/draftgo-theme.css`，加载顺序见 `resources/skill/references/frontend.md`。
-- DraftGo 基座内置 SVG 图标库，运行时路径为 `/assets/icons/{name}.svg`。
-- 图标文件统一使用 `kebab-case.svg` 命名；完整映射见 `/assets/icons/manifest.json`。
-- 页面或导航栏需要单色图标时，优先用 CSS mask + `currentColor`，可自动适配深浅主题。
-- html2canvas 1.4.1 已内置，页面需要截图 / 导出图片时优先使用本地路径 `/assets/vendor/html2canvas/html2canvas.min.js`；确需 CDN 时优先使用国内镜像引入。
+SAT 只从 `.draftgo/config.json` 读取。宿主 MCP 配置、命令输出和错误信息都不应包含 SAT。
 
-Go 自定义服务通过 `draftgo.DB.CreateMany(...)` 与 `draftgo.DB.UpdateMany(...)` 批量写入动态数据。
+## MCP 命令
 
-自定义服务（Custom Scripts）约定：
+```bash
+draftgo mcp setup [target...]   # 写入或合并项目级 MCP 配置
+draftgo mcp status [target...]  # 检查配置是否存在且不含敏感连接参数
+draftgo mcp test                # 验证 initialize、tools/list、关键 tools/call
+draftgo mcp serve               # 启动 stdio -> 远端 Streamable HTTP bridge
+```
 
-- 自定义服务使用 Go：导入内置 `draftgo/sdk`，实现 `Register(app *sdk.App)`，调用 `app.Route`、`app.On` 或 `app.Schedule` 后即可自动注册。服务在独立 Go 子进程中构建和执行；标准库与 `go.mod` 中声明的兼容依赖可用。
-- 本地资源在 `.draftgo/custom_scripts/`；元数据写在 `index.json`，代码文件以每条记录的 `code_file` 为准。推送时 `draftgo_push.py custom_scripts` 只读取 `code_file` 指向的文件。
-- 新服务使用 `mode=mixed`，`Register` 内的 `app.Route`、`app.On`、`app.Schedule` 会自动形成完整触发器清单；旧 `triggers` 字段不参与 Go 注册。
-- `slug=<slug>` 是服务命名空间；`app.Route("GET", "/items", handler)` 映射为 `GET /api/x/<slug>/items`。一个服务可同时注册多个路由、事件和定时任务。
-- Go handler 签名为 `func handler(draftgo *sdk.Context) (any, error)`；普通值直接返回，需要状态码或响应头时使用 `draftgo.Respond(...)`。
-- 第三方依赖写在同一条 index 元数据的 `go_mod` / `go_sum`；推送后应真实请求无副作用 GET 端点验证，不要只看 `OK script_id=...`。
-- `app.On("user.registered", handler)` 可重复声明；同一服务既能监听多个事件，也能为同一事件注册多个 handler。
-- Route 输入在 `draftgo.Input`（`body`、`query_params`、`headers`、`method`、`path_params`）；当前用户用 `draftgo.Auth.CurrentUser()` 获取。普通值可直接返回，需要状态码或响应头时用 `draftgo.Respond(...)`。
-- 动态数据使用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；完整 Go SDK 见 `references/custom-services.md`。
-- 管理面按 `scripts:read/create/update/delete/execute` 接入角色 RBAC；获得创建/编辑权限的用户属于可信代码编辑者。调用面仍由每个 route 的 `permission` 与 `config.route_security` 独立控制，管理权限不会绕过调用权限。
-- 服务可用 `config.max_concurrency` / `queue_timeout_ms` 设置并发退避；出站请求使用 `draftgo.HTTP`，饱和 Route 返回 HTTP 429。
-- 完整 SDK（users/db/auth/notify/http/cache/config/log，以及 AIHub/知识库/Memory/Skill/MCP 的推理与 CRUD）、各触发类型 `draftgo`、管理 API 和部署限制见 [`resources/skill/references/custom-services.md`](resources/skill/references/custom-services.md)。
+`setup` 不传 target 时自动检测当前项目的宿主。可用 `--target codex,cursor` 传入多个目标。
 
-AIHub Agent 用户选模型约定：
+当前 MCP 宿主支持：
 
-- 新页面的 AI 对话 UI 先引入 `/assets/draftgo-chat.js`，再使用 `<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID">` 或 `DraftGoChat.create()`；完整规则见 `resources/skill/references/chat-sdk.md`。
-- `DraftGoAI.chat/images/getSelectableModels` 是同一脚本提供的旧兼容门面，不由壳层默认注入，也不应替代新页面的 `<dg-chat>` 对话 UI。
-- 管理端在 Agent 的 `data.spec.model_selection.user_selectable=true` 后，页面可通过 Chat SDK 模型选择器，或兼容接口 `DraftGoAI.getSelectableModels(agentId)` 获取 `{ user_selectable, models }`。
-- `models` 是该 Agent 的主模型 + 备用模型白名单，不是供应商全量模型列表。
-- 调用 `DraftGoAI.chat(...)` 或 `DraftGoAI.images(...)` 时，可在 `options.model` 中传入用户选择的模型；后端会继续按 Agent 白名单校验。
+| 宿主 | 项目配置 | 状态 |
+|---|---|---|
+| Codex CLI | `.codex/config.toml` | 支持 |
+| Claude Code | `.mcp.json` | 支持 |
+| Cursor | `.cursor/mcp.json` | 支持 |
+| Gemini CLI | `.gemini/settings.json` | 支持 |
+| Kiro | `.kiro/settings/mcp.json` | 支持 |
+| GitHub Copilot | `.vscode/mcp.json` | 支持 |
+| Windsurf | - | 不支持项目级 MCP setup |
+| Antigravity | - | 不支持项目级 MCP setup |
 
-AIHub Agent JSON 输出约定：
+Codex 配置由 `draftgo mcp setup codex` 合并为：
 
-- Agent 的结构化输出写在 `data.spec.output_format` 中；`mode="json"` 表示要求 JSON 输出。
-- `data.spec.output_format.json.strategy` 支持 `auto`、`native`、`prompt`：`auto` 会优先使用模型资产的 `supports_response_format/supports_json_schema` 诊断结果，必要时降级为提示词约束。
-- `data.spec.output_format.json.schema` 可传 JSON Schema；后端会尽量构造 OpenAI 兼容 `response_format`，流式响应结束时会追加 `json.validation` 事件。
-- 模型资产可通过 `POST /api/aihub/{id}/test-response-format` 探测并写回 `supports_response_format` 与 `supports_json_schema`。
+```toml
+[mcp_servers.draftgo]
+command = "draftgo"
+args = ["mcp", "serve"]
+```
 
-示例：
+其他支持的宿主同样只保存 stdio 命令。例如 Claude Code、Cursor、Gemini 和 Kiro 使用 `mcpServers.draftgo`：
 
 ```json
 {
-  "data": {
-    "schema_version": "agent.v3",
-    "spec": {
-      "model_id": 1,
-      "model": "gpt-4.1",
-      "output_format": {
-        "mode": "json",
-        "json": {
-          "strategy": "auto",
-          "schema_name": "summary",
-          "schema": {
-            "type": "object",
-            "properties": {
-              "title": { "type": "string" },
-              "tags": { "type": "array", "items": { "type": "string" } }
-            },
-            "required": ["title", "tags"],
-            "additionalProperties": false
-          }
-        }
-      }
+  "mcpServers": {
+    "draftgo": {
+      "command": "draftgo",
+      "args": ["mcp", "serve"]
     }
   }
 }
 ```
 
-## 自动识别的依据
+GitHub Copilot 使用 `.vscode/mcp.json` 的 `servers.draftgo`，并额外写入 `"type": "stdio"`。这些文件不包含 server、SAT、header 或环境变量；bridge 在运行时从当前项目读取私有配置。
 
-| AI 工具 | 探测信号（任一命中即视为在用） |
-|---|---|
-| Claude Code | `.claude/` 或 `CLAUDE.md` |
-| Kiro | `.kiro/` |
-| Cursor | `.cursor/` |
-| Windsurf | `.windsurf/` |
-| Antigravity | `.agent/` |
-| GitHub Copilot | `.github/prompts/` 或 `.github/copilot-instructions.md` |
-| Codex CLI | `.codex/` 或 `AGENTS.md` |
-| Gemini CLI | `.gemini/` 或 `GEMINI.md` |
+DraftGo MCP 预期提供以下工具：
 
-若未命中任何信号，请用 `draftgo init all` 或 `draftgo init <target>` 手动指定。
+- `draftgo_project_overview`
+- `draftgo_resource_list`
+- `draftgo_resource_search`
+- `draftgo_resource_get_metadata`
+- `draftgo_resource_read_fragment`
+- `draftgo_api_search`
+- `draftgo_api_describe`
+- `draftgo_api_call`
 
-## 产物结构
+## 标准工作流
 
-每个 AI 工具拿到完整的核心说明（SKILL.md + 子技能 + rules + scripts）。大型 OpenAPI 快照只在 `.draftgo/skill-shared/` 保存一份，避免多个工具重复复制；也可直接用 `draftgo api <keyword>` 查询。
+陌生项目先通过 MCP 获取概览，再按需搜索、列出或读取资源元数据：
 
+```text
+project_overview -> resource_search/resource_list -> get_metadata/read_fragment
 ```
-<project>/
-├── .draftgo/                         # 运行时数据（CLI 不会覆盖你这里的内容）
-│   ├── config.json                   # init / connect 后生成（已加入 .gitignore）
-│   ├── token                         # connect 后生成（已加入 .gitignore）
-│   ├── changelog.md                  # 更新日志（按日期分节）
-│   ├── Task/                         # 每个开发任务一个 md，含需求 / 设计 / 任务标记
-│   ├── lessons/                      # 开发经验、踩坑记录、基座局限场景
-│   ├── pages/  navigations/  ...     # init 拉取的本地缓存
-│   ├── skill-shared/references/api.json # 多 AI 工具共享的 OpenAPI 快照
-│   └── .version                      # CLI 写入：当前已装 skill 的版本
-│
-└── (AI 工具 skill 目录，按需写入；每份都是完整副本)
-    .claude/skills/draftgo/{SKILL.md, init/, push/, pull/, story/, rules/, scripts/}
-    .codex/skills/draftgo/{SKILL.md, ...}
-    .gemini/skills/draftgo/{SKILL.md, ...}
-    .cursor/commands/draftgo.md           +  .cursor/commands/draftgo/{...}
-    .windsurf/workflows/draftgo.md        +  .windsurf/workflows/draftgo/{...}
-    .agent/workflows/draftgo.md           +  .agent/workflows/draftgo/{...}
-    .kiro/steering/draftgo.md             +  .kiro/steering/draftgo/{...}
-    .github/prompts/draftgo.prompt.md     +  .github/prompts/draftgo/{...}
-```
-
-`config.json` 的 `auto_push` 默认是 `false`。AI 在每次完成本地验证后调用 `draftgo auto-push`；仅当你将该值改为 `true` 时，命令才会继续执行 `check → push`。直接执行 `draftgo push` 或 `draftgo deploy` 仍属于显式推送，不受此开关限制。
-
-> 渲染时 SKILL.md 中的 `{{SKILL_DIR}}` / `{{SKILL_SCRIPTS}}` 会被替换成当前 AI 工具自身的目录，确保子技能、rules、scripts 引用永远指向同一个工具的副本。CLI **不会** 改写你的 `AGENTS.md` / `GEMINI.md`。
-
----
-
-## v3.0.30 升级要点（自定义服务 AI SDK）
-
-- 内置 Skill 补齐 AIHub 推理、Embedding、Agent/Prompt/Skill/MCP 资产 CRUD，以及供应商、模型路由和运行记录接口。
-- 增加知识库、文档、Chunk、长期记忆的 Go SDK 说明，包含文件上传、检索、重建索引和管理员同构入口。
-- 记录 `config.aihub` 推理开关与 Agent/模型白名单，并为全部新 SDK 能力增加文档契约测试。
-
-## v3.0.28 升级要点（同步可靠性）
-
-- 修复导航 pull：列表元数据会逐条获取详情 HTML，避免空内容覆盖本地导航。
-- 指定 ID 的 pull 改为合并索引；请求失败、详情缺失或响应不完整时返回非零，保留本地缓存。
-- `draftgo push` 支持默认全量推送；`deploy --delivery preview` 使用无副作用的 dry-run 预览。
 
-## v3.0.27 升级要点（自动推送与索引恢复）
+编辑完整页面、导航或文档正文：
 
-- 新增 `draftgo auto-push`：始终先运行本地 `check`，仅在 `.draftgo/config.json` 的 `auto_push: true` 时继续推送；关闭时保留验证并返回未推送信息。
-- 支持 `draftgo auto-push --batch`，并行任务也受同一开关约束。
-- 指定资源缺少 `index.json` 条目时，push 会回读云端；资源存在则补齐元数据并继续推送本地文件，资源不存在则提示清理本地孤儿文件。
-
----
-
-## v2.0.3 升级要点（操作型页面空间利用）
-
-CLI v2.0.3 补充操作型页面的空间模型，重点解决后台管理 / 表格 / 列表页面按普通文档流布局时，数据少导致分页、保存栏、批量操作区上浮，页面空间利用不足的问题。
-
-**核心变化：**
-
-- **工作台布局原则**：后台管理、表格、列表、审批、配置、内容维护等操作型页面，优先让页面根容器占满可用视口 / iframe 内容区。
-- **稳定控制区**：顶部筛选、搜索、标题操作区保持稳定高度，底部分页、批量操作栏、保存栏等流程控制区保持在工作区底部或稳定位置。
-- **数据区承接剩余空间**：主体数据区使用 `flex:1; min-height:0; overflow:auto` 等结构承接剩余空间，数据少时保留工作区空白，数据多时优先让数据区内部滚动。
-- **工作台结构同步**：`references/frontend.md` 补充操作型页面的空间方法，基座对应文档为 `docs/frontend/rules.md`，避免分页跟随 1-2 条数据上浮。
+```bash
+draftgo checkout pages 42
+# 编辑 .draftgo/worktree/pages/page_42.html
+draftgo check
+draftgo verify-ui http://localhost:5173       # UI 变更时
+draftgo diff pages 42
+draftgo commit pages 42
+```
 
----
+只查询长内容时，优先使用 MCP 搜索和片段工具；需要全文分析或编辑时才 checkout。不要要求 MCP 返回完整 HTML 或 Markdown。
 
-## v2.0.2 升级要点（统一目标识别信号）
+结构化资源使用 `draftgo_api_search` / `draftgo_api_describe` 查实时契约，再用 `draftgo_api_call` 操作。AIHub Agent、Prompt、MCP、Skill、供应商和模型路由也属于实时结构化资源，不写本地快照；供应商密钥或 header 值不得出现在 Agent 输出中。
 
-CLI v2.0.2 进一步完善 `draftgo update` 的目标识别逻辑，避免只修到单个工具而遗漏其他 AI 工具。
+## 命令清单
 
-**核心变化：**
+### Skill 与连接
 
-- **平台定义成为单一信号源**：每个 AI 工具的入口文件、skill 目录和项目级探测信号统一维护在 `platforms.js`，`init / update / status` 共用同一份识别依据。
-- **update 覆盖所有检测到的工具**：不传 target 时，`draftgo update` 会合并“已安装 skill 的目标”和“项目中检测到的 AI 工具信号”，并刷新全部命中的工具。
-- **全平台测试覆盖**：单测现在会同时模拟 Claude Code、Cursor、Windsurf、Antigravity、Kiro、GitHub Copilot、Codex、Gemini 的项目级信号，防止后续再出现只命中部分工具的问题。
+| 命令 | 说明 |
+|---|---|
+| `draftgo init [target]...` | 安装 Skill；不传 target 时自动识别，`all` 表示全部。 |
+| `draftgo update [target]...` | 更新全局 CLI，并原子刷新已安装或检测到的 Skill。 |
+| `draftgo uninstall <target|all>` | 移除指定宿主的 Skill；`--purge` 还会删除整个 `.draftgo/`。 |
+| `draftgo status` | 显示已安装宿主和 Skill 版本。 |
+| `draftgo connect [target]...` | 验证并保存 server/SAT，随后配置宿主 MCP；不下载业务资源。 |
+| `draftgo list-targets` | 列出可安装 Skill 的 AI 宿主。 |
 
----
+### 发现、正文和冲突
 
-## v2.0.1 升级要点（update 目标识别修复）
+| 命令 | 说明 |
+|---|---|
+| `draftgo map` | 通过 MCP 读取远端项目概览和资源列表，再叠加本地 checkout 状态。 |
+| `draftgo checkout <pages|nav|docs> <id...>` | 下载完整正文和 base，校验 hash 后原子落盘；`--force` 可显式覆盖已修改的本地正文。 |
+| `draftgo check` | 只检查 checkout manifest、worktree 文件、base/hash、扩展名、HTML 结构和已 checkout 导航引用。 |
+| `draftgo diff <pages|nav|docs> <id>` | 显示 checkout base 与当前本地正文的差异。 |
+| `draftgo commit <pages|nav|docs> <id...>` | 本地校验后，通过专用 HTTP 上传完整正文并更新 base/manifest。 |
+| `draftgo conflicts` | 列出未解决冲突；存在冲突时返回非零。`--all` 包括已解决记录。 |
+| `draftgo conflict show <type> <id>` | 显示冲突的 base/local/remote/worktree 路径。 |
+| `draftgo conflict resolve <type> <id>` | 确认 worktree 已合并，把保留的 remote 设为新 base；随后重新 check、diff、commit。 |
+| `draftgo verify-ui <url>` | 使用 Playwright 执行确定性的浏览器 smoke check。 |
 
-CLI v2.0.1 修复 `draftgo update` 空参数时只刷新部分工具的问题。
+`pages`、`page`，`nav`、`navigation`、`navigations`，以及 `docs`、`doc`、`article`、`articles`、`docs/articles` 都会规范化到三个支持的正文类型。
 
-**核心变化：**
+### 实时 API 与交付
 
-- **update 合并识别目标**：不传 target 时，`draftgo update` 会同时刷新“已安装 skill 的目标”和项目中可检测到的 AI 工具信号（如 `.claude`、`.codex`、`AGENTS.md`）。
-- **Codex 项目级目录不再漏刷**：项目里已有 `.codex` 但 Codex skill 尚未落地时，update 也会主动写入 `.codex/skills/draftgo/`。
+| 命令 | 说明 |
+|---|---|
+| `draftgo api <query>` | 通过 MCP `api_search` 查询实时 API 契约。 |
+| `draftgo api search <query>` | `draftgo api <query>` 的显式搜索形式。 |
+| `draftgo api describe <operation_id>` | 通过 MCP `api_describe` 查看指定操作。 |
+| `draftgo delete <operation_id> [id]` | 描述并确认后调用实时 MCP `api_call`；支持 `--params JSON`、`--input file` 和 `--yes`。 |
+| `draftgo deploy [<type> <id...>]` | 先 `check`，再按 delivery 模式检查 diff 或 commit。仅 `--delivery local` 可省略 type/id。 |
+| `draftgo auto-push [<type> <id...>]` | `auto_push: true` 时检查并 commit 已 checkout 的变更；有冲突立即停止。 |
+| `draftgo pull` | 仅输出迁移提示并返回非零；永不下载资源。 |
+| `draftgo push <type> <id...>` | 已弃用；仅对 pages/nav/docs 显示提示后转发到 `commit`。不支持 push-all 或结构化资源。 |
 
----
+`deploy` 的 `--delivery local` 只运行检查，`preview` 运行检查并显示 diff，`deploy` 运行检查后 commit 指定正文。它不会遍历旧索引。`push --dry-run` 只显示指定正文的 diff。
 
-## v2.0.0 升级要点（精简 skill 包体）
+`auto-push` 不传 id 时只处理 manifest 中已修改的 checkout；项目未连接或 `auto_push` 未启用时安全跳过。
 
-CLI v2.0.0 删除了内置 `resources/skill/reference/` 基座参考副本，进一步精简安装到各 AI 工具中的 DraftGo skill 包体。
+### 本地 DraftGo
 
-**核心变化：**
+| 命令 | 说明 |
+|---|---|
+| `draftgo local setup` | 生成 `.draftgo/docker/docker-compose.yaml`，初始化并启动本地 DraftGo 栈。 |
+| `draftgo local start` | 启动本地栈；`up` 是兼容别名。 |
+| `draftgo local stop` | 停止本地栈；`down` 是兼容别名。 |
+| `draftgo local logs [service...]` | 查看日志；不传服务时跟随 `app`。 |
+| `draftgo local status` | 显示容器状态；`ps` 是兼容别名。 |
+| `draftgo local-dev` | `draftgo local setup` 的兼容入口。 |
+
+本地 Docker、MySQL、Redis、Milvus 和 app 生命周期与 MCP/checkout 工作流相互独立。
+
+## Worktree 与 manifest
+
+```text
+.draftgo/
+├── config.json
+├── worktree/
+│   ├── manifest.json
+│   ├── pages/
+│   ├── navigations/
+│   ├── docs/
+│   └── .base/
+└── conflicts/
+```
 
-- **移除 reference 目录**：不再随 CLI 分发 OpenAPI 与前端 runtime 源码副本，减少安装体积和过期参考带来的误导。
-- **规则以当前 skill 为准**：开发时优先依据 `SKILL.md`、`rules/`、`init/pull/push/story` 子技能和本地 `.draftgo/` 数据推进。
-- **避免源码级参考漂移**：基座能力变化时，不再依赖 CLI 内置快照推断行为，降低旧 reference 与真实运行时不一致的风险。
+`.draftgo/worktree/manifest.json` 使用 `schema_version: 1`，条目键为规范化类型和 id，例如 `pages:42`。每个条目记录：
 
----
+- `server`、`resource_type`、`resource_id`
+- `title`、`route` / `code` / `slug`
+- `local_path`、`base_path`
+- `content_type`、`file_extension`、`content_size`
+- `base_version`、`base_revision`、`base_etag`、`base_hash`
+- `checked_out_at`，commit 后还会记录更新时间
 
-## v1.6.1 升级要点（前端规则收敛）
+已知正文类型保持原始字节和语义：`text/html` 使用 `.html`，Markdown 使用 `.md`，纯文本使用 `.txt`，其他类型使用底座返回且通过安全校验的扩展名。CLI 不转换 HTML、Markdown 或正文编码。
 
-CLI v1.6.1 继续优化开发效果：减少前端规则中过细的“适合 / 不适合”和固定模板描述，让 AI 在满足平台硬约束的前提下，根据页面目标和业务复杂度做实现判断。
+checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时文件，同时校验 content type、大小和 SHA-256，再原子安装 local/base 并写 manifest。commit 会校验本地结构，携带 checkout 时的 version/revision/ETag，通过专用 HTTP 上传原始正文；完整正文不会成为 MCP tool 参数。
 
-**核心变化：**
+## 冲突处理
 
-- **前端规则收敛**：DraftGo 规则关注本地资源、运行时 API、入口绑定、真实数据和验证方法。
-- **GSAP 资源改为按需使用**：本地 GSAP 资源仍可用，但 CLI 不再给出使用场景判断。
-- **表格规则去模板化**：不再要求固定搜索、高级筛选、列配置、分页结构，具体界面由 Agent 和本地 UI Skills 判断。
-- **状态规则保留方法约束**：空态、加载态、错误态、成功态必须存在，但具体呈现不由 CLI 指定。
+远端对 commit 返回 HTTP 409/412 时，CLI 不重试、不 force，也不会覆盖 worktree local。它会在以下目录保存冲突材料并返回非零：
 
----
+```text
+.draftgo/conflicts/<pages|navigations|docs>/<id>/
+├── conflict.json
+├── base.<ext>
+├── local.<ext>
+└── remote.<ext>
+```
 
-## v1.6.0 升级要点（开发任务规划升级）
+处理流程：
 
-CLI v1.6.0 强化了 skill 对“开发任务规划”的判断力，重点解决新页面 / 新功能只做成静态展示页、漏后台管理、漏真实数据、漏导航入口的问题。
+1. `draftgo conflict show <type> <id>` 定位三份材料和 worktree 文件。
+2. 在 worktree 文件中人工或借助可靠的三方合并工具完成合并。
+3. `draftgo conflict resolve <type> <id>` 校验 worktree，并把冲突时保存的 remote 版本设为新 base。
+4. 重新运行 `draftgo check`、必要时 `verify-ui`、`draftgo diff`，最后 `draftgo commit`。
 
-**核心变化：**
+## map 与 check 输出
 
-- **用户意图翻译**：当用户用非技术语言描述“案例库、新闻中心、产品中心、预约、资料下载”等业务目标时，AI 会先识别它是页面、多页面还是完整功能模块，而不是要求用户说出 CRUD、API、路由等开发术语。
-- **页面默认完整功能**：用户说“做一个页面”时，默认按可真实使用的页面功能处理；只有明确说“静态 / 纯页面 / 原型 / 先看效果”时，才按静态页处理。
-- **用户路径链路**：功能规划从“用户打开官网 / 系统入口 → 看见入口 → 点击进入 → 操作 → 反馈 → 后台维护 → 前台展示更新”这一整条链路倒推页面、导航、数据和权限。
-- **新增页面绑定**：创建页面后必须绑定到导航栏、首页入口、后台菜单或相关页面按钮之一；只创建页面文件、无法从正常路径点击进入，不算完成。
-- **真实落地闭环**：按钮、表单、搜索、筛选、分页、保存、删除、发布等交互默认要真实有效；需要可维护内容时，优先规划后台管理和同一份真实数据，追求高可用。
+`draftgo map --output json` 返回：
 
-这些规则已改为按事实触发：资源关系不清时 map，页面改动检查入口和 HTML，数据/API/服务只读取对应契约，运行和布局改变才做浏览器验证。Task 和 Story 仅在需要产品决策沉淀或跨资源交接时使用。
+```json
+{
+  "server": "https://draftgo.example",
+  "overview": {},
+  "resources": [],
+  "checkouts": [],
+  "legacy_cache": { "ignored": true, "detected": [] }
+}
+```
 
----
+`draftgo check --output json` 返回 `{ map, errors, warnings, warningDetails, legacy_cache_ignored }`。`--strict` 会把 warnings 也视为失败。`check` 不访问远端，也不会读取旧全量资源索引。
 
-## init / push 的正确运行方式
+## Skill 与领域约定
 
-skill 内置两个 Python 脚本。**不要用 curl / npx 代替**，脚本会处理 token、字段结构、错误日志。脚本被复制到每个 AI 工具自己的 skill 目录下，例如 Claude Code 是 `.claude/skills/draftgo/scripts/`。
+安装到每个宿主的 DraftGo Skill 包含主 `SKILL.md`、`init` / `push` / `story` 子技能、references，以及 scripts 扩展约束。实时 API 契约以 MCP `api_search` / `api_describe` 为准；references 保留 API 无法表达的领域知识和实践约束。
 
-```bash
-# 以 Claude Code 安装位置为例（其它工具替换路径前缀即可）
-python .claude/skills/draftgo/scripts/draftgo_init.py --server <url>
-python .claude/skills/draftgo/scripts/draftgo_push.py pages   [page_id]
-python .claude/skills/draftgo/scripts/draftgo_push.py nav     [nav_id]
-python .claude/skills/draftgo/scripts/draftgo_push.py db_meta [meta_id]
-```
+前端和自定义服务的关键约定仍然适用：
 
-> token 通过环境变量 `DRAFTGO_TOKEN` 传入，脚本不接受命令行 `--token`。
+- 壳层源码使用 React 19 + Vite 8 + Tailwind CSS 4；数据库页面和导航使用原生 HTML，不写入 TSX、ESM import 或 npm 构建产物。
+- 内置 UI、图标、Chat SDK、AIHub 结构化输出和页面布局规则见 `resources/skill/references/`。
+- 自定义服务使用 Go `draftgo/sdk`，通过 `Register(app *sdk.App)` 注册 Route、事件和定时任务；管理权限、调用权限、并发和出站请求约束见 `resources/skill/references/custom-services.md`。
+- 自定义服务、数据、AIHub、权限和系统配置通过实时 MCP/API 操作，不从 `.draftgo/*/index.json` 推断远端状态。
 
-更推荐的用法：在 AI 工具里说「初始化 draftgo 项目」或「同步页面 123」，skill 会自动触发对应脚本。
+`draftgo update` 只刷新 CLI 和 Skill 资源，不覆盖项目的 `.draftgo/config.json`、worktree、冲突材料、Task、lessons 或 changelog。渲染 Skill 时，`{{SKILL_DIR}}` / `{{SKILL_SCRIPTS}}` 会替换为当前宿主目录；CLI 不改写项目的 `AGENTS.md` 或 `GEMINI.md`。
 
-## Story
+## 常用选项
 
-`.draftgo/story.yaml` 用于沉淀会影响后续取舍的产品定位与决策。已有 Story 且请求触及定位或既有决策时读取；用户要求建立、更新或冲突检查时调用 `story/SKILL.md`。
+- `--project <dir>`：操作指定项目目录，默认当前目录。
+- `--output json`：为 map、check、checkout、commit、diff、conflicts、conflict、api 或 delete 输出 JSON。
+- `--strict`：check/deploy/auto-push 将 warnings 视为失败。
+- `--force`：init 覆盖已有 Skill；checkout 显式覆盖已修改的本地正文。update 始终刷新目标 Skill。
+- `--purge`：uninstall 时同时删除整个 `.draftgo/` 运行时目录。
+- `--skip-update-check`：update 不访问 npm，直接用当前 CLI 刷新 Skill。
+- `--connect` / `--local-dev` / `--no-setup`：控制 init 安装 Skill 后的基座处理流程。
+- `--target <name,...>`：为 MCP setup/status 指定一个或多个宿主。
+- `--server <url>` / `--token <sat>`：非交互 connect；不传时安全提示输入。
+- `--allow-offline` / `--no-mcp-setup`：允许 connect 在 MCP 暂不可用时保存，或跳过宿主配置。
+- `--yes`：跳过支持该选项的交互确认。
+- `--mobile-check auto|always|never`：控制 `verify-ui` 是否执行。
+- `--screenshot on-failure|always|never`：控制 UI 截图。
+- `--delivery local|preview|deploy`：控制 deploy 行为。
+- `--timeout <ms>`：控制 connect/MCP test 超时。
 
----
+设置 `DRAFTGO_NO_UPDATE_CHECK=1` 可关闭 npm 版本检查，适用于离线或 CI 环境。
 
 ## 许可证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.35",
+  "version": "3.0.38",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"
@@ -45,8 +45,12 @@
     "lint": "node scripts/check-syntax.js",
     "validate:skill": "node scripts/validate-skill.js",
     "verify:package": "node scripts/verify-package.js",
-    "test": "npm run lint && npm run validate:skill && npm run verify:package && node tests/unit.js && node tests/e2e.js",
+    "test": "npm run lint && npm run validate:skill && npm run verify:package && npm run test:unit && npm run test:mcp && npm run test:worktree && npm run test:migration && npm run test:local && npm run test:e2e",
     "test:unit": "node tests/unit.js",
+    "test:mcp": "node tests/mcp.test.js",
+    "test:worktree": "node tests/worktree.test.js",
+    "test:migration": "node tests/migration.test.js",
+    "test:local": "node tests/local-runtime.js",
     "test:e2e": "node tests/e2e.js"
   },
   "dependencies": {