draftgo-cli 3.0.56 → 4.0.22

package/README.md

@@ -1,381 +1,253 @@
-# draftgo-cli
+# DraftGo CLI 4
 
-## Workflow 2.0
+面向 AI 编码工具的 DraftGo 工作台 CLI。它负责 Skill 安装、项目连接、MCP 发现、长正文 checkout/commit、自定义服务草稿、统一本地验收和 worklog 记录。
 
-The root DraftGo Skill loads automatically in supported AI hosts. Agents read the smallest task-specific Reference set first, then query current project state through precise MCP tools instead of generating an aggregate context bundle.
+## 核心规则
 
-Pages, navigations, documents, and custom services are long-content resources. Custom services use `draftgo checkout custom-services <id>` and a four-file worktree (`service.go`, `go.mod`, `go.sum`, `service.json`). `commit` saves the shared cloud draft, `test` validates or executes it in the DraftGo Runner, and `publish` explicitly promotes a validated draft without interrupting the current live version. Start later work with `refresh`; it stops when local edits exist. Cloud versions are the only history, while local storage keeps only current content and one base.
+- 根 Skill 自动加载；Agent 只读取当前任务需要的 Reference。
+- pages、navigations、docs/articles 和 custom services 的完整正文使用 `checkout`、worktree、`diff`、`commit`；结构化资源使用 MCP/API。
+- MCP schema 是服务端实时契约。已知 operation 优先使用项目私有缓存；首次使用或 `registry_revision` 变化时 describe。schema 不写入 Skill 或聊天上下文。
+- 不同资源、operation 和 owner 的工作全部并发；同一资源的依赖步骤保持串行。
+- 每个任务开始记录到 `.draftgo/worklog.md`，验证和交付成功后再标记完成。
+- 已知页面使用 `draftgo map --type pages --route <path>` 或 `--title <title>` 精确定位；只需范围和状态时使用 `--summary`，浏览列表时使用 `--limit`（默认 20）/`--cursor`，不默认全量 map。
+- `--output json` 的 stdout 只包含 UTF-8 JSON；诊断和进度写入 stderr。大变更先用 `draftgo diff --stat` 或 `--summary`。
 
-Small, single-point changes do not need Task overhead. Cross-module, cross-session, or multi-Agent work uses one authoritative `.draftgo/Task/[YYYY-MM-DD]<slug>/Task.md` and `draftgo task create|add|claim|start|complete|block|reopen|accept|finish`. The file keeps the user's original request, the clarified executable requirement, expected effects, scope, checklist, decisions, blockers, and final acceptance together. Legacy `task.yaml + plan.md + items/` tasks remain readable and migrate only through an explicit `draftgo task migrate`. `.draftgo/tmp/` is entirely disposable; user-facing evidence belongs in registered `.draftgo/artifacts/`, and `draftgo clean` removes all tmp plus registered artifacts. UI smoke checks remain single viewport and use `--screenshot never` by default. Supply `on-failure` or `always` only for explicit strong visual verification.
+跨板块任务先看[极简方法指南](resources/skill/references/methods.md)：它按 AIHub、知识库/记忆、页面/内容、动态数据、自定义服务、MCP、运行诊断和交付验收给出“适用场景 + 最短正确命令链 + 失败定位 + 完成条件”。动态 operation 不写死；未知契约统一用 `draftgo api search`、`draftgo api describe`、`draftgo api call` 实时发现。
 
-面向 AI 编码工具的 DraftGo 工作台 CLI：分发 DraftGo Skill，通过 MCP 发现和操作实时资源，并为页面、导航和文档提供可校验的 `checkout` / `commit` 工作流。
+## 验收策略
 
-DraftGo Next 壳层使用 React + Vite；数据库页面可按任务使用原生 Web 技术、Tailwind CSS 或平台内置组件库。CLI 仍提供 Docker 本地运行、项目检查和浏览器验证能力。
+普通交付只运行：
 
-支持安装 Skill 的宿主：Claude Code、Codex CLI、Cursor、Windsurf、Antigravity、GitHub Copilot、Gemini CLI、Kiro。
-
-## 前置条件
-
-- Node.js >=20.19
-- 使用 `draftgo local ...` 时需要 Docker 和 Docker Compose
-
-CLI 不再依赖 Python 同步脚本，也不会创建 DraftGo 业务资源的全量本地镜像。
-
-## 工作模型
-
-```text
-根 SKILL.md -> Agent 按任务读取最少必要的 Reference
-AI 宿主 -> draftgo mcp serve -> DraftGo /mcp
-                                     |
-                                     +-> 结构化资源、元数据、搜索和正文片段
-
-draftgo checkout/commit -> DraftGo 专用 HTTP 正文端点
-                           （完整 HTML/Markdown 不经过 MCP 上下文）
+```bash
+draftgo verify
 ```
 
-- Agent 负责理解任务语义、选择 Reference，并通过精确 MCP 工具逐步定位相关资源；CLI 不生成聚合上下文包。
-- 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。
-- CLI 不提供页面模板，也不替 Agent 选择页面结构或视觉风格。
+默认验收只做本地检查，不启动浏览器，也不生成截图。只有用户明确要求视觉验收时才访问浏览器或截图；两者同时要求时先截图并查看结果，再做交互或 DOM 检查。
 
-## Agent 阅读顺序
+```bash
+# 截图验收，默认 desktop 1440x900
+draftgo verify --url http://localhost:3000/path --screenshot always
 
-DraftGo Skill 不能被 MCP 替代。根 `SKILL.md` 会在 Skill 触发时自动加载；Agent 按任务路由渐进读取相关 Reference：
+# 用户明确要求交互或 DOM 验收
+draftgo verify --url http://localhost:3000/path --ui always
 
-```text
-已加载的 SKILL.md
--> 读取任务所需的最少 Reference
--> 用 resource_search / api_search 精确定位
--> 按需 describe、读取 metadata 或片段
--> 必要时 checkout 正文
+# 仅在用户要求时增加移动端
+draftgo verify --url http://localhost:3000/path --screenshot always --viewport both
 ```
 
-页面任务读取 `frontend.md`，按需补读 `runtime.md` / `app-api.md`；数据、自定义服务和 AIHub 任务分别读取对应 Reference。目标明确时不要全量枚举无关资源。`mcp test` 是连接诊断，不是每次资源查询的前置步骤。
-
-页面需求先结合用户意图和 MCP 实时资源判断是修改已有页面还是新增页面。已有页面在确认唯一 ID 后 checkout；独立新页面先通过实时 API 创建并取得 ID，再 checkout 完整正文。“做一个功能页面”本身不预设新建或修改，只有不同判断会产生明显不同结果时才需要向用户澄清。
-
-只回答无需实时状态的本地规则问题时，不必调用 MCP。静态资源须先区分：平台内置目录由 `frontend.md` 说明，指定页面依赖经 MCP 定位、checkout 后本地搜索，服务器全量文件不能凭现有 Skill、MCP 摘要或 checkout 声称已枚举。
-
-Skill 说明产品约束、内置能力和操作规则；MCP 说明当前远端状态；checkout 正文才能证明某个页面完整引用了哪些静态资源。汇报时应明确标注这三类证据，不能互相替代。
+`--ui` 和 `--screenshot` 的默认值都是 `never`；截图模式只有 `always` 和 `never`。默认视口是 desktop `1440x900`，移动端为 `390x844`。
 
 ## 安装与连接
 
 ```bash
 npm install -g draftgo-cli
-
-cd /path/to/your/project
-draftgo init                 # 自动识别宿主并安装 DraftGo Skill
-draftgo connect codex        # 输入 server 和 SAT，验证 MCP，并配置 Codex
+cd /path/to/project
+draftgo init
+draftgo connect --server https://draftgo.example --api-key "$DRAFTGO_API_KEY"
+draftgo mcp setup
+draftgo mcp test
 ```
 
-也可以非交互连接：
+`connect` 会验证当前用户的 DraftGo API Key、MCP initialize、tools/list 和关键工具调用，然后把连接写入项目私有的 `.draftgo/config.json`。宿主 MCP 配置只包含 `draftgo mcp serve`，不会保存 API Key。需要开发 space 资源时增加 `--scope-type space --space-id <id>`；平台组件和系统配置仍按 operation 契约使用 platform 上下文。
+
+本地底座：
 
 ```bash
-draftgo connect codex --server https://draftgo.example --token "$DRAFTGO_SAT"
+draftgo local setup
+draftgo local start
+draftgo local status
+draftgo local logs app
+draftgo local stop
 ```
 
-`--server` 始终表示 DraftGo 基础地址。直接连接 MCP endpoint 时使用 `--mcp-url https://draftgo.example/mcp`；CLI 会显式保存 `mcp_url`，若未同时传 `--server`，则从标准 `/mcp` 后缀推导基础地址，避免猜测已有 base URL 的语义。
-
-`connect` 会先验证 SAT、MCP `initialize`、`tools/list` 和关键 `tools/call`，成功后写入项目私有配置 `.draftgo/config.json`，并尝试为指定或自动检测到的宿主执行 MCP setup。`init` / `connect` 不会预建 Task、lessons、changelog、worktree、conflicts 等运行时内容；这些文件和目录只在对应能力首次使用时按需创建。它不会 pull 页面、导航、文档或任何其他业务资源。
+## 命令
 
-远端暂不可用时，只有显式传入 `--allow-offline` 才会保存配置；恢复后运行 `draftgo mcp test`。使用 `--no-mcp-setup` 可跳过宿主配置。
-
-`connect` 会把以下运行时路径加入项目 `.gitignore`：
+### 项目与 Skill
 
 ```text
-.draftgo/config.json
-.draftgo/token
-.draftgo/worktree/
-.draftgo/conflicts/
+draftgo init [target...]
+draftgo update [target...]
+draftgo uninstall <target|all> [--purge]
+draftgo status
+draftgo list-targets
+draftgo connect [target...]
 ```
 
-SAT 只从 `.draftgo/config.json` 读取。宿主 MCP 配置、命令输出和错误信息都不应包含 SAT。
+`draftgo status` 会通过只读 MCP/API 诊断显示服务连接健康状态、服务版本和当前用户 API Key 的 `platform`/`space` 上下文；`--output json` 适合读取 `connection.health`、`workspace_id` 与 `space_id`。
 
-## MCP 命令
+### 发现与正文
 
-```bash
-draftgo mcp setup [target...]   # 写入或合并项目级 MCP 配置
-draftgo mcp status [target...]  # 检查配置是否存在且不含敏感连接参数
-draftgo mcp test                # 验证 initialize、tools/list、项目/正文/API 三条调用路径
-draftgo mcp serve               # 启动 stdio -> 远端 Streamable HTTP bridge
+```text
+draftgo map [--type pages|nav|docs|custom-services] [--route <path>] [--title <title>] [--summary] [--limit <1-100>] [--cursor <opaque>] [--output json]
+draftgo checkout <pages|nav|docs|custom-services> <id...> [--force]
+draftgo check [custom-services <id...>] [--remote]
+draftgo verify [<type> <id...>] [visual flags]
+draftgo diff <type> <id> [--stat|--summary] [--output json]
+draftgo commit <type> <id...>
+draftgo refresh <type> <id...>
+draftgo reconcile <type> <id...>
+draftgo conflicts [--all]
+draftgo conflict show <type> <id>
+draftgo conflict resolve <type> <id>
 ```
 
-`mcp serve` 会保留远端 `Mcp-Session-Id`。服务重启或 session 过期后，它会自动重新 initialize，并只重试一次被明确拒绝为 session 无效的当前请求；普通工具失败、超时和 5xx 不会自动重试。`mcp test` 使用独立的新连接，只证明当前配置能够建立新 session，不能直接证明宿主此前持有的 session 仍有效。
+`checkout` 下载正文和经过 hash 校验的 base。`commit` 先并发完成所有目标的本地与远端 preflight，全部通过后再并发上传；任何 409/412 都保留 base/local/remote 冲突材料，不 force、不覆盖、不自动合并。
+
+`--route`、`--title` 为精确匹配，同时给出时取交集。CLI 可用资源搜索缩小候选，但最终在本地做精确判定；服务端 `resource_search` 只接受通用 `query`，不能传 route/title。`map --summary` 不输出 project overview、资源列表或 hash。`diff --stat` 输出文件与增删行数，`--summary` 输出资源、版本和变更概要；只有不带这两个参数的 diff 才展开正文。
 
-`setup` 不传 target 时自动检测当前项目的宿主。可用 `--target codex,cursor` 传入多个目标。
+### Page 组件库
 
-当前 MCP 宿主支持：
+```bash
+draftgo components search <query> --output json
+draftgo components show <library/component> --output json
+draftgo components expand --page <id> --instance <data-dg-instance>
+draftgo verify pages <id>
+
+# 开发组件：commit 保存草稿，publish 显式上线
+draftgo components checkout <library/component>
+draftgo components diff <library/component>
+draftgo components verify <library/component>
+draftgo components commit <library/component>
+draftgo components publish <library/component>
+
+# 库管理和标准 ZIP 迁移
+draftgo components libraries list|show|create|update|delete
+draftgo components import <archive.zip> --dry-run
+draftgo components export <library> --file <archive.zip>
+```
 
-| 宿主 | 项目配置 | 状态 |
-|---|---|---|
-| 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 |
+`search` 和 `show` 始终读取当前 DraftGo 实例的组件目录，AI 不得按名称猜写 props/slots。Page 以真实根标签和 `data-dg-use="library/component"` 保存活引用，发布新 revision 后刷新自动升级。高度个性化时先 checkout Page，再用 `expand` 固化当前 props、slots、组件/库 CSS、公共资产和 mount 初始化；展开实例变成普通 HTML/CSS/JavaScript，不再随组件升级，仍需经过 `diff -> verify -> commit`。
 
-Codex 配置由 `draftgo mcp setup codex` 合并为：
+### Custom service
 
-```toml
-[mcp_servers.draftgo]
-command = "draftgo"
-args = ["mcp", "serve"]
-```
+最短开发闭环：
 
-其他支持的宿主同样只保存 stdio 命令。例如 Claude Code、Cursor、Gemini 和 Kiro 使用 `mcpServers.draftgo`：
-
-```json
-{
-  "mcpServers": {
-    "draftgo": {
-      "command": "draftgo",
-      "args": ["mcp", "serve"]
-    }
-  }
-}
+```bash
+# 先用 MCP 定位或创建服务并取得 ID
+draftgo checkout custom-services <id...>
+draftgo diff custom-services <id> --stat
+draftgo commit custom-services <id...>
+draftgo test custom-services <id> --source draft --handler route:POST:/path --input request.json
 ```
 
-GitHub Copilot 使用 `.vscode/mcp.json` 的 `servers.draftgo`，并额外写入 `"type": "stdio"`。这些文件不包含 server、SAT、header 或环境变量；bridge 在运行时从当前项目读取私有配置。
+每个 worktree 只有 `service.go` 与 `service.json` 是用户内容；Route/Event/Scheduled handler 仅由 `Register` 自动发现。CLI 另生成带 `DO NOT EDIT` 标记的 `go.mod/go.sum`、本地编译入口和 SDK 副本，供 gopls、`go build` 使用；它们会在 checkout 和 commit 时重建，且永不进入 diff、hash、归档、冲突材料或云端。第三方依赖只在源码顶部用 `//draftgo:require module@version` 固定。旧四文件 worktree 不受支持，请删除后用当前 CLI 重新 checkout。
 
-DraftGo MCP 预期提供以下工具：
+`commit custom-services` 会自动完成提交、验证和发布，并输出明确的 published 提示；`validate`、`test`、`publish` 仍可作为单独的兼容入口。`test` 只运行 cloud draft，不调用线上版本；发布后如需再试运行，先修改并提交形成新草稿。默认拒绝外部副作用；外部调用用 `--side-effect-policy mock` 模拟，只有明确需要真实副作用时才组合 `--side-effect-policy live --test-write`。数据库等写操作也必须显式加 `--test-write`。
 
-- `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`
+`--source` 支持 `draft`（默认）、`auto`、`published`。Selector 支持 `route:METHOD:/path`、`event:name`、`scheduled:name` 或 handler 名；`--input`、`--headers`、`--user` 都读取 UTF-8 JSON object。普通 SDK 调用继承已验证的 `platform` 或 `space` 上下文；可信服务可对单次操作显式使用 `ctx.Admin.*`，该提升会审计且不会泄漏到后续调用。余额扣款、权益、支付和订阅使用 `ctx.Billing` / `ctx.Admin.Billing`，精确签名查看 checkout 后只读的 `.draftgo-sdk/billing.go`。完整字段与规则见[自定义服务方法指南](resources/skill/references/custom-services.md)。
 
-## 标准工作流
+### MCP/API
 
 ```text
-Agent 按任务读取相关 Reference
-→ MCP 精确定位
-→ Agent 自主设计并批量 checkout
-→ 独立资源按需并行开发
-→ 主 Agent 一次统一验证
-→ commit
-→ draftgo changelog add "<完成结果>"
+draftgo mcp setup [target...]
+draftgo mcp status [target...]
+draftgo mcp test
+draftgo mcp serve
+draftgo api <query>
+draftgo api search <query>
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input <json-file>
+draftgo delete <operation_id> [id] [--params JSON]
+draftgo capabilities list [--module <name>] [--type <resource>] [--method <method>]
+draftgo capabilities search <query> [--risk <level>] [--permission <permission>]
+draftgo capabilities show <operation_id>
+draftgo capabilities audit --output json
 ```
 
-无依赖且修改不同资源的工作可以并行；同一文件或 DraftGo 资源全程只分配给一个 Agent。开始并行实现前先确定共享 schema、接口、权限和路由。单页面、强依赖或仍共享主要资源的任务由一个 Agent 完成。主 Agent 负责 Reference/MCP 路由、资源 owner、汇总回读、统一验证、commit 和最终 changelog。
-
-前端任务先读取 `references/frontend.md`，涉及 iframe、路由、认证或全局层时补读 `runtime.md` / `app-api.md`，再通过 MCP 定位目标资源。
+`api call` 对已缓存 operation 直接调用并携带 `registry_revision`。服务端返回 `CONTRACT_CHANGED` 时重新 describe；只读或 operation 契约未变化时最多重试一次，危险 operation 自身契约变化时阻断调用并提示升级 CLI 后重新确认。调用输入必须是 UTF-8 JSON object；输出包含 HTTP status、服务端 code 和 request ID。
 
-确定全部正文资源后批量 checkout，自主设计并按唯一 owner 编辑，最后统一验证和交付：
+权限快捷命令：
 
 ```bash
-draftgo checkout pages 42 43
-# 独立资源可并行编辑；同一资源只由一个 Agent 修改
-draftgo check
-draftgo verify pages 42 --remote --url http://localhost:5173/example
-draftgo diff pages 42
-draftgo diff pages 43
-draftgo commit pages 42 43
-draftgo changelog add "完成文档管理系统及角色权限"
+draftgo role list
+draftgo space list
+draftgo space members list --input request.json
+draftgo group members add --input request.json
+draftgo grant create --input request.json
+draftgo api-key status
+draftgo api-key rotate
+draftgo data-range list
 ```
 
-只查询长内容时，优先使用 MCP 搜索和片段工具；需要全文分析或编辑时才 checkout。不要要求 MCP 返回完整 HTML 或 Markdown。
-
-结构化资源使用 `draftgo_api_search` / `draftgo_api_describe` 查实时契约，再用 `draftgo_api_call` 操作。AIHub Agent、Prompt、MCP、Skill、供应商和模型路由也属于实时结构化资源，不写本地快照；供应商密钥或 header 值不得出现在 Agent 输出中。
-
-只有整个任务统一验证并且所有 commit/MCP 写入成功后才执行一次 `changelog add`。验证失败、409/412 或任一交付失败时不得写入。
-
-## 命令清单
+`role` 管理无作用域的 Role 模板；授权使用 `grant` 创建带 `platform` 或 `space` 范围的 AccessGrant。工作区成员关系不直接授予权限。资源归属由服务端持久化 ResourceOwnership 决定，DB 的 DataRange
+只在该范围内应用 `none`、`owner` 或 `all` 记录策略。交互式 CLI、MCP 和普通 HTTP API 均使用当前用户的
+API Key，并始终按该用户的 AccessGrant 授权；API Key 不能创建或伪造服务身份。CI、定时任务和共享服务等
+无人值守自动化使用平台提供的独立服务凭据通道及服务主体 AccessGrant，不复用个人 API Key。
 
-### Skill 与连接
+### 交付与记录
 
-| 命令 | 说明 |
-|---|---|
-| `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 宿主。 |
-
-### 发现、正文和冲突
-
-| 命令 | 说明 |
-|---|---|
-| `draftgo map` | 并行读取 pages、navigations、docs/articles 元数据，再叠加本地 checkout 状态；`--type` 可限制一种类型。 |
-| `draftgo checkout <pages|nav|docs> <id...>` | 下载完整正文和 base，校验 hash 后原子落盘；`--force` 可显式覆盖已修改的本地正文。 |
-| `draftgo check` | 默认只检查本地 checkout；`--remote` 额外对比 local/base/manifest/remote 的版本和 hash。 |
-| `draftgo verify [<type> <id...>]` | 统一执行静态检查；`--remote` 增加远端比较，`--url` 增加 iframe-aware 浏览器验证。 |
-| `draftgo diff <pages|nav|docs> <id>` | 显示 checkout base 与当前本地正文的差异。 |
-| `draftgo commit <pages|nav|docs> <id...>` | 本地校验后，通过专用 HTTP 上传完整正文并更新 base/manifest。 |
-| `draftgo reconcile <pages|nav|docs> <id...>` | 仅当 local 与经校验的 remote 字节一致时，安全修复落后的 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>` | `verify --url <url> --ui always` 的弃用兼容入口。 |
-
-`pages`、`page`，`nav`、`navigation`、`navigations`，以及 `docs`、`doc`、`article`、`articles`、`docs/articles` 都会规范化到三个支持的正文类型。
-
-### 实时 API 与交付
-
-| 命令 | 说明 |
-|---|---|
-| `draftgo api <query>` | 通过 MCP `api_search` 查询实时 API 契约。 |
-| `draftgo api search <query>` | `draftgo api <query>` 的显式搜索形式。 |
-| `draftgo api describe <operation_id>` | 通过 MCP `api_describe` 查看指定操作。 |
-| `draftgo api call <operation_id> --input <file>` | 描述后调用实时 operation；JSON 文件严格按 UTF-8 解码并输出状态码、服务端 code 和 request ID。 |
-| `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 changelog add "<完成结果>"` | 在整个任务统一验证并全部交付成功后追加一条完成结果。 |
-| `draftgo pull` | 仅输出迁移提示并返回非零；永不下载资源。 |
-| `draftgo push <type> <id...>` | 已弃用；仅对 pages/nav/docs 显示提示后转发到 `commit`。不支持 push-all 或结构化资源。 |
-
-`deploy` 的 `--delivery local` 只运行检查，`preview` 运行检查并显示 diff，`deploy` 运行检查后 commit 指定正文。它不会遍历旧索引。`push --dry-run` 只显示指定正文的 diff。
+```text
+draftgo deploy <type> <id...> [--delivery local|preview|deploy]
+draftgo auto-push [<type> <id...>]
+draftgo work start <item>
+draftgo work add <item>
+draftgo work start-item <number|date#number>
+draftgo work complete <number|date#number> [--note <evidence>]
+draftgo work show|list
+draftgo clean [--dry-run|--yes]
+```
 
-`auto-push` 不传 id 时只处理 manifest 中已修改的 checkout；项目未连接或 `auto_push` 未启用时安全跳过。
+`draftgo work start <item>` 的文本输出会返回可直接传给后续命令的引用，例如 `Started work item #21 (2026-08-20#21)`。
 
-### 更新日志
+## Worklog
 
-`draftgo changelog add` 写入 `.draftgo/changelog.md`。同一天继续编号；本地日期变化后追加新区块并从 `1` 开始。命令只接受单行、非空的完成结果；现有文件不符合固定格式时拒绝改写。
+`.draftgo/worklog.md` 是任务、进度和完成证据的唯一记录。格式如下：
 
 ```markdown
-2026-07-31
-===
-1. 完成文档管理系统及角色权限
-2. 修复文档编辑权限问题
-
-2026-08-01
-===
-1. 增加文档分类功能
+[ 2026-08-09 ]
+1. [ ● ] 实现页面权限
+// 正在开发
+2. [ ] 补充验收
+
+[ 2026-08-10 ]
+1. [ √ ] 完成文档
+// draftgo verify、commit 已通过
 ```
 
-只记录已完成结果，不记录排查过程。统一验证、409/412 或任一交付失败时不运行该命令。
-
-### 本地 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
+├── api-contract-cache.json
+├── worklog.md
 ├── worktree/
-│   ├── manifest.json
-│   ├── pages/
-│   ├── navigations/
-│   ├── docs/
-│   └── .base/
-└── conflicts/
+├── conflicts/
+├── artifacts/
+└── tmp/
 ```
 
-`.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 后还会记录更新时间
-
-已知正文类型保持原始字节和语义：`text/html` 使用 `.html`，Markdown 使用 `.md`，纯文本使用 `.txt`，其他类型使用底座返回且通过安全校验的扩展名。CLI 不转换 HTML、Markdown 或正文编码。
-
-checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时文件，同时校验 content type、大小和 SHA-256，再原子安装 local/base 并写 manifest。commit 会校验本地结构，携带 checkout 时的 version/revision/ETag，通过专用 HTTP 上传原始正文；完整正文不会成为 MCP tool 参数。
+连接配置、契约缓存、worktree、冲突材料和截图都属于项目运行时数据并写入 `.gitignore`。`.draftgo/tmp/` 可由 `draftgo clean` 清理；需要用户查看的证据放在已注册的 `.draftgo/artifacts/` 下。
 
-## 冲突处理
+## Skill 与 Reference
 
-远端对 commit 返回 HTTP 409/412 时，CLI 不重试、不 force，也不会覆盖 worktree local。它会在以下目录保存冲突材料并返回非零：
+Skill 只放稳定的领域知识、项目边界和操作规则；动态 operation schema 由 MCP 提供并缓存在项目运行时。Reference 不拆成更小文件，保留按任务路由、前端运行时、安全、自定义服务、checkout 和 MCP 契约所需的完整上下文，避免过度拆分损失效果。
 
-```text
-.draftgo/conflicts/<pages|navigations|docs>/<id>/
-├── conflict.json
-├── base.<ext>
-├── local.<ext>
-└── remote.<ext>
-```
-
-处理流程：
-
-1. `draftgo conflict show <type> <id>` 定位三份材料和 worktree 文件。
-2. 在 worktree 文件中人工或借助可靠的三方合并工具完成合并。
-3. `draftgo conflict resolve <type> <id>` 校验 worktree，并把冲突时保存的 remote 版本设为新 base。
-4. 重新运行 `draftgo check`、必要时 `draftgo verify`、`draftgo diff`，最后 `draftgo commit`。
+支持的 Skill target 包括 Claude Code、Cursor、Windsurf、Antigravity、Kiro、GitHub Copilot、Codex CLI、Gemini CLI 和 Pi。Pi 的项目级 Skill 安装到 `.agents/skills/draftgo/`，可被 Pi 按 Agent Skills 标准自动发现。
 
-## map 与 check 输出
+## 开发与测试
 
-`draftgo map --output json` 返回：
-
-```json
-{
-  "server": "https://draftgo.example",
-  "overview": {},
-  "resources": [],
-  "checkouts": [],
-  "legacy_cache": { "ignored": true, "detected": [] }
-}
+```bash
+npm run validate:skill
+npm test
 ```
 
-`draftgo check --output json` 返回结构化的本地、远端和工作区检查结果。它以声明的 charset（默认 UTF-8）严格解码 HTML，并在内存中检查内联 JavaScript，错误直接映射到原 HTML 行列，不生成 `.draftgo/tmp/syntax/*.js`。`--strict` 会把 warnings 也视为失败。默认 `check` 不访问远端；显式使用 `--remote` 时读取实时 metadata，并把 `committed_unrecorded` 等可恢复状态指向 `draftgo reconcile`。
-
-`draftgo verify` 是交付前统一入口。无参数时只运行快速本地 `check`；`--remote` 才联网，`--url` 才启动浏览器。浏览器检查默认使用 `--frame auto`，同时检查顶层页面和可见 iframe，因此 `--selector` 可匹配 `iframe.srcdoc` 中的业务 DOM。`--viewport mobile|desktop|both` 控制目标视口，截图默认关闭。
+本地开发要求 Node.js `>=20.19`。浏览器依赖仅在显式视觉验收时使用；普通 `npm test` 不会启动浏览器。
 
-`.draftgo/tmp/` 是统一临时区，CLI 和 AI 产生的可丢弃中间文件必须位于 `.draftgo/tmp/<owner>/<run-id>/`；AI 自建文件使用 `.draftgo/tmp/ai/<run-id>/`。`draftgo clean --dry-run` 会列出全部 tmp 文件和已注册 artifacts，`draftgo clean --yes` 负责回收并删除空运行目录。需要保留供用户查看的截图或报告应进入 `.draftgo/artifacts/`，而不是 tmp。
+许可证：MIT
 
-## Skill 与领域约定
+## Install without npm
 
-安装到每个宿主的 DraftGo Skill 包含主 `SKILL.md`、`init` / `story` 子技能和按需 references。实时 API 契约以 MCP `api_search` / `api_describe` 为准；references 只保留 API 无法表达的领域知识和实践约束。
+DraftGo can be installed from the China download endpoint. The installer falls back to a GitHub mirror and the official GitHub Release when the primary endpoint is unavailable.
 
-前端和自定义服务的关键约定仍然适用：
-
-- 壳层源码使用 React 19 + Vite 8 + Tailwind CSS 4；数据库页面和导航以 HTML 文档运行，可加载平台内置组件库，但不进入壳层的 TSX、ESM 或 npm 构建链。
-- 内置 UI、图标、Chat SDK、AIHub 结构化输出以及前端运行、交互和验收规则见 `resources/skill/references/`；CLI 和 Skill 不提供页面模板。
-- 自定义服务使用 Go `draftgo/sdk`，通过 `Register(app *sdk.App)` 注册 Route、事件和定时任务；管理权限、调用权限、并发和出站请求约束见 `resources/skill/references/custom-services.md`。
-- 自定义服务、数据、AIHub、权限和系统配置通过实时 MCP/API 操作，不从 `.draftgo/*/index.json` 推断远端状态。
-
-`draftgo update` 只刷新 CLI 和 Skill 资源，不覆盖项目的 `.draftgo/config.json`、worktree、冲突材料、Task、lessons 或 changelog。渲染 Skill 时，`{{SKILL_DIR}}` / `{{SKILL_SCRIPTS}}` 会替换为当前宿主目录；CLI 不改写项目的 `AGENTS.md` 或 `GEMINI.md`。
-
-## 常用选项
-
-- `--project <dir>`：操作指定项目目录，默认当前目录。
-- `--output json`：为 map、check、checkout、commit、diff、conflicts、conflict、api 或 delete 输出 JSON。
-- `--type <type>`：限制 `map` 查询一种正文资源类型；支持 pages、nav/navigations、docs/articles 及其别名。
-- `--strict`：check/deploy/auto-push 将 warnings 视为失败。
-- `--remote`：让 check 按需对比 checkout 的远端版本和 hash；默认仍为快速离线检查。
-- `--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；不传时安全提示输入。
-- `--mcp-url <url>`：为 connect 显式指定完整 MCP endpoint；标准 `/mcp` 可自动推导基础地址，自定义路径需同时传 `--server`。
-- `--allow-offline` / `--no-mcp-setup`：允许 connect 在 MCP 暂不可用时保存，或跳过宿主配置。
-- `--yes`：跳过支持该选项的交互确认。
-- `--ui auto|always|never`：控制 verify 的浏览器验证；默认 auto，只在提供 `--url` 时运行。
-- `--viewport mobile|desktop|both`：控制 verify 的目标视口；不传时使用 `--width/--height` 或 390x844。
-- `--frame auto|top|all|<iframe-selector>`：控制 verify 检查哪些 frame；默认检查顶层与可见 iframe。
-- `--resource <type:id>`：兼容入口使用；推荐直接写 `draftgo verify pages 42 --url ...`。
-- `--browser-path <file>`：verify 显式使用浏览器可执行文件；也可设置 `DRAFTGO_BROWSER_PATH`，否则自动查找系统浏览器和 Playwright 缓存。
-- `--token auto|never`：verify 默认读取 `.draftgo/config.json`，对与 `server` 同源的地址自动附加 `token=<SAT>`；配置无 SAT、跨源地址或 `never` 模式均不附加。
-- `--screenshot on-failure|always|never`：控制 UI 截图。
-- `--delivery local|preview|deploy`：控制 deploy 行为。
-- `--timeout <ms>`：控制 connect 或 MCP test 的远端请求超时。
-
-设置 `DRAFTGO_NO_UPDATE_CHECK=1` 可关闭 npm 版本检查，适用于离线或 CI 环境。
+```bash
+# macOS / Linux
+curl -fsSL https://draftgo.cn/draftgo-cli/install.sh | sh
 
-## 许可证
+# Windows PowerShell
+irm https://draftgo.cn/draftgo-cli/install.ps1 | iex
+```
 
-MIT
+The download source can be overridden with `DRAFTGO_INSTALL_BASE_URL`, the GitHub Release mirror with `DRAFTGO_GITHUB_MIRROR`, and the version with `DRAFTGO_VERSION`. The CLI archive includes its npm dependencies but currently requires Node.js >=20.19.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.56",
-  "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
+  "version": "4.0.22",
+  "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro, Pi).",
   "bin": {
     "draftgo": "bin/draftgo.js"
   },
@@ -29,7 +29,8 @@
     "antigravity",
     "copilot",
     "gemini",
-    "kiro"
+    "kiro",
+    "pi"
   ],
   "author": "draftgo <cabinai@163.com> (https://github.com/draftgo)",
   "license": "MIT",
@@ -44,14 +45,18 @@
   "scripts": {
     "lint": "node scripts/check-syntax.js",
     "validate:skill": "node scripts/validate-skill.js",
+    "sync:custom-service-sdk": "node scripts/sync-custom-service-sdk.js",
+    "build:release": "node scripts/build-release.js",
     "verify:package": "node scripts/verify-package.js",
-    "test": "npm run lint && npm run validate:skill && npm run verify:package && npm run test:unit && npm run test:workflow && npm run test:changelog && npm run test:mcp && npm run test:worktree && npm run test:migration && npm run test:local && npm run test:e2e",
+    "test": "npm run lint && npm run validate:skill && npm run verify:package && npm run test:unit && npm run test:components && npm run test:capabilities && npm run test:workflow && npm run test:worklog && npm run test:mcp && npm run test:worktree && npm run test:integration && npm run test:local && npm run test:e2e",
     "test:unit": "node tests/unit.js",
-    "test:workflow": "node tests/workflow-upgrade.test.js",
-    "test:changelog": "node tests/changelog.test.js",
+    "test:components": "node --test tests/components.test.js",
+    "test:capabilities": "node --test tests/capabilities.test.js",
+    "test:workflow": "node tests/workflow.test.js",
+    "test:worklog": "node tests/worklog.test.js",
     "test:mcp": "node tests/mcp.test.js",
     "test:worktree": "node tests/worktree.test.js",
-    "test:migration": "node tests/migration.test.js",
+    "test:integration": "node tests/integration.test.js",
     "test:local": "node tests/local-runtime.js",
     "test:e2e": "node tests/e2e.js"
   },