draftgo-cli 4.0.1 → 4.0.22

package/README.md

@@ -9,6 +9,10 @@
 - 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`。
+
+跨板块任务先看[极简方法指南](resources/skill/references/methods.md)：它按 AIHub、知识库/记忆、页面/内容、动态数据、自定义服务、MCP、运行诊断和交付验收给出“适用场景 + 最短正确命令链 + 失败定位 + 完成条件”。动态 operation 不写死；未知契约统一用 `draftgo api search`、`draftgo api describe`、`draftgo api call` 实时发现。
 
 ## 验收策略
 
@@ -39,12 +43,12 @@ draftgo verify --url http://localhost:3000/path --screenshot always --viewport b
 npm install -g draftgo-cli
 cd /path/to/project
 draftgo init
-draftgo connect --server https://draftgo.example --token "$DRAFTGO_SAT"
+draftgo connect --server https://draftgo.example --api-key "$DRAFTGO_API_KEY"
 draftgo mcp setup
 draftgo mcp test
 ```
 
-`connect` 会验证 SAT、MCP initialize、tools/list 和关键工具调用，然后把连接写入项目私有的 `.draftgo/config.json`。宿主 MCP 配置只包含 `draftgo mcp serve`，不会保存 SAT。
+`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 上下文。
 
 本地底座：
 
@@ -69,14 +73,16 @@ draftgo list-targets
 draftgo connect [target...]
 ```
 
+`draftgo status` 会通过只读 MCP/API 诊断显示服务连接健康状态、服务版本和当前用户 API Key 的 `platform`/`space` 上下文；`--output json` 适合读取 `connection.health`、`workspace_id` 与 `space_id`。
+
 ### 发现与正文
 
 ```text
-draftgo map [--type pages|nav|docs]
+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>
+draftgo diff <type> <id> [--stat|--summary] [--output json]
 draftgo commit <type> <id...>
 draftgo refresh <type> <id...>
 draftgo reconcile <type> <id...>
@@ -87,18 +93,48 @@ draftgo conflict resolve <type> <id>
 
 `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 才展开正文。
+
+### Page 组件库
+
+```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>
+```
+
+`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`。
+
 ### Custom service
 
-```text
+最短开发闭环：
+
+```bash
+# 先用 MCP 定位或创建服务并取得 ID
 draftgo checkout custom-services <id...>
-draftgo diff custom-services <id>
+draftgo diff custom-services <id> --stat
 draftgo commit custom-services <id...>
-draftgo validate custom-services <id>
-draftgo test custom-services <id> [--handler route:POST:/path]
-draftgo publish custom-services <id...>
+draftgo test custom-services <id> --source draft --handler route:POST:/path --input request.json
 ```
 
-每个 custom service worktree 只包含 `service.go`、`go.mod`、`go.sum` 和 `service.json`。保存或 commit 草稿会清空验证凭证；validate 把凭证绑定当前 revision、源码、依赖、SDK 和 Runner 协议。publish 只接受当前有效凭证，Runner/SDK 变化造成的 `validation_stale` 会由 CLI 自动重新 validate 一次；revision 冲突仍直接失败。
+每个 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。
+
+`commit custom-services` 会自动完成提交、验证和发布，并输出明确的 published 提示；`validate`、`test`、`publish` 仍可作为单独的兼容入口。`test` 只运行 cloud draft，不调用线上版本；发布后如需再试运行，先修改并提交形成新草稿。默认拒绝外部副作用；外部调用用 `--side-effect-policy mock` 模拟，只有明确需要真实副作用时才组合 `--side-effect-policy live --test-write`。数据库等写操作也必须显式加 `--test-write`。
+
+`--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
 
@@ -112,9 +148,31 @@ 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
 ```
 
-`api call` 对已缓存 operation 直接调用并携带 `registry_revision`。服务端返回 `CONTRACT_CHANGED` 时只 describe、更新缓存并重试一次。调用输入必须是 UTF-8 JSON object；输出包含 HTTP status、服务端 code 和 request ID。
+`api call` 对已缓存 operation 直接调用并携带 `registry_revision`。服务端返回 `CONTRACT_CHANGED` 时重新 describe；只读或 operation 契约未变化时最多重试一次，危险 operation 自身契约变化时阻断调用并提示升级 CLI 后重新确认。调用输入必须是 UTF-8 JSON object；输出包含 HTTP status、服务端 code 和 request ID。
+
+权限快捷命令：
+
+```bash
+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
+```
+
+`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。
 
 ### 交付与记录
 
@@ -129,6 +187,8 @@ draftgo work show|list
 draftgo clean [--dry-run|--yes]
 ```
 
+`draftgo work start <item>` 的文本输出会返回可直接传给后续命令的引用，例如 `Started work item #21 (2026-08-20#21)`。
+
 ## Worklog
 
 `.draftgo/worklog.md` 是任务、进度和完成证据的唯一记录。格式如下：
@@ -165,6 +225,8 @@ draftgo clean [--dry-run|--yes]
 
 Skill 只放稳定的领域知识、项目边界和操作规则；动态 operation schema 由 MCP 提供并缓存在项目运行时。Reference 不拆成更小文件，保留按任务路由、前端运行时、安全、自定义服务、checkout 和 MCP 契约所需的完整上下文，避免过度拆分损失效果。
 
+支持的 Skill target 包括 Claude Code、Cursor、Windsurf、Antigravity、Kiro、GitHub Copilot、Codex CLI、Gemini CLI 和 Pi。Pi 的项目级 Skill 安装到 `.agents/skills/draftgo/`，可被 Pi 按 Agent Skills 标准自动发现。
+
 ## 开发与测试
 
 ```bash
@@ -175,3 +237,17 @@ npm test
 本地开发要求 Node.js `>=20.19`。浏览器依赖仅在显式视觉验收时使用；普通 `npm test` 不会启动浏览器。
 
 许可证：MIT
+
+## Install without npm
+
+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.
+
+```bash
+# macOS / Linux
+curl -fsSL https://draftgo.cn/draftgo-cli/install.sh | sh
+
+# Windows PowerShell
+irm https://draftgo.cn/draftgo-cli/install.ps1 | iex
+```
+
+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": "4.0.1",
-  "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,9 +45,13 @@
   "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:worklog && npm run test:mcp && npm run test:worktree && npm run test:integration && 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: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",