draftgo-cli 3.0.49 → 3.0.52

package/README.md

@@ -1,5 +1,13 @@
 # draftgo-cli
 
+## Workflow 2.0
+
+`draftgo context` outputs schema `2.0` with separate `bundled_references`, `live_project`, `live_resources`, `live_apis`, `live_db_meta`, and `live_session` sections. It writes to stdout by default, uses current cloud data on every run, and does not create a persistent context cache. Frontend and custom-service tasks always retain complete live DB Meta.
+
+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.
+
+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.
+
 面向 AI 编码工具的 DraftGo 工作台 CLI：分发 DraftGo Skill，通过 MCP 发现和操作实时资源，并为页面、导航和文档提供可校验的 `checkout` / `commit` 工作流。
 
 DraftGo Next 壳层使用 React + Vite；数据库页面可按任务使用原生 Web 技术、Tailwind CSS 或平台内置组件库。CLI 仍提供 Docker 本地运行、项目检查和浏览器验证能力。
@@ -72,7 +80,7 @@ draftgo connect codex --server https://draftgo.example --token "$DRAFTGO_SAT"
 
 `--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。它不会 pull 页面、导航、文档或任何其他业务资源。
+`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` 可跳过宿主配置。
 
@@ -170,8 +178,7 @@ draftgo context --task frontend --output json
 draftgo checkout pages 42 43
 # 独立资源可并行编辑；同一资源只由一个 Agent 修改
 draftgo check
-draftgo check --remote                  # 交付前按需对比远端版本/hash
-draftgo verify-ui http://localhost:5173       # UI 变更时
+draftgo verify pages 42 --remote --url http://localhost:5173/example
 draftgo diff pages 42
 draftgo diff pages 43
 draftgo commit pages 42 43
@@ -205,13 +212,14 @@ draftgo changelog add "完成文档管理系统及角色权限"
 | `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>` | 使用 Playwright 执行确定性的浏览器 smoke check。 |
+| `draftgo verify-ui <url>` | `verify --url <url> --ui always` 的弃用兼容入口。 |
 
 `pages`、`page`，`nav`、`navigation`、`navigations`，以及 `docs`、`doc`、`article`、`articles`、`docs/articles` 都会规范化到三个支持的正文类型。
 
@@ -308,7 +316,7 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 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`。
+4. 重新运行 `draftgo check`、必要时 `draftgo verify`、`draftgo diff`，最后 `draftgo commit`。
 
 ## map 与 check 输出
 
@@ -324,7 +332,11 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 }
 ```
 
-`draftgo check --output json` 返回 `{ map, errors, warnings, warningDetails, remote, remote_error, legacy_cache_ignored }`。`--strict` 会把 warnings 也视为失败。默认 `check` 不访问远端；显式使用 `--remote` 时读取每个 checkout 的实时 metadata，并把 `committed_unrecorded` 等可恢复状态指向 `draftgo reconcile`。它始终不会读取旧全量资源索引。
+`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` 控制目标视口，截图默认关闭。
+
+`.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。
 
 ## Skill 与领域约定
 
@@ -356,10 +368,12 @@ checkout 会通过 MCP 获取元数据和专用下载地址，流式写入临时
 - `--mcp-url <url>`：为 connect 显式指定完整 MCP endpoint；标准 `/mcp` 可自动推导基础地址，自定义路径需同时传 `--server`。
 - `--allow-offline` / `--no-mcp-setup`：允许 connect 在 MCP 暂不可用时保存，或跳过宿主配置。
 - `--yes`：跳过支持该选项的交互确认。
-- `--mobile-check auto|always|never`：控制 `verify-ui` 是否执行。
-- `--resource <type:id>`：verify-ui 打开 URL 前对比本地 checkout 与远端已提交版本，并明确报告实际验证来源。
-- `--browser-path <file>`：verify-ui 显式使用浏览器可执行文件；也可设置 `DRAFTGO_BROWSER_PATH`，否则自动查找系统浏览器和 Playwright 缓存。
-- `--token auto|never`：`verify-ui` 默认读取 `.draftgo/config.json`，对与 `server` 同源的地址自动附加 `token=<SAT>`；配置无 SAT、跨源地址或 `never` 模式均不附加。
+- `--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 或 context 的远端请求超时。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.49",
+  "version": "3.0.52",
   "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,9 +45,10 @@
     "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 && npm run test:unit && npm run test:context && 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:context && 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:unit": "node tests/unit.js",
     "test:context": "node tests/context.test.js",
+    "test:workflow": "node tests/workflow-upgrade.test.js",
     "test:changelog": "node tests/changelog.test.js",
     "test:mcp": "node tests/mcp.test.js",
     "test:worktree": "node tests/worktree.test.js",
@@ -57,11 +58,11 @@
   },
   "dependencies": {
     "@grpc/grpc-js": "1.14.1",
+    "adm-zip": "0.5.16",
     "parse5": "6.0.1",
     "playwright-core": "1.61.1"
   },
   "directories": {
     "test": "tests"
-  },
-  "devDependencies": {}
+  }
 }

package/resources/skill/SKILL.md

@@ -3,6 +3,15 @@ name: draftgo
 description: Use this skill to inspect, develop, debug, or deliver a DraftGo application. Use draftgo context for task-specific references and live MCP discovery, checkout/commit for complete page, navigation, and document bodies, and write the changelog only after all verification and delivery succeed.
 ---
 
+## Workflow 2.0 authority
+
+- Treat pages, navigations, docs/articles, and custom services as checkout resources. Never save complete MCP responses, duplicate source snapshots, temporary Go modules, SDK stubs, executables, or build directories by hand.
+- `context` schema 2.0 separates `bundled_references` from `live_project`, `live_resources`, `live_apis`, and complete `live_db_meta`. It is stdout-only by default and has no persistent or delta cache.
+- Custom-service flow: `context --task custom-service` -> `checkout custom-services` -> edit four files -> `commit` cloud draft -> `test` in the server Runner -> `check --remote` -> `publish` -> `refresh`. CLI and admin UI edit the same cloud draft.
+- Do not create Task overhead for a small, single-point change. For cross-module, cross-session, or multi-Agent work, create or resume `.draftgo/Task/[YYYY-MM-DD]<slug>/Task.md`. It is the only task state: preserve both the user's original request and the clarified executable requirement, assign one owner per item/resource, and check an item only with verification evidence. Changelog remains the final delivery record, not a task tracker.
+- Normal delivery uses `draftgo verify`; add `--remote` only when remote comparison is required and `--url` only for browser evidence. UI verification is iframe-aware and defaults to one viewport with no screenshot. Only explicit visual acceptance or regression diagnosis may pass `--viewport both` or `--screenshot on-failure|always`.
+- `.draftgo/tmp/` is entirely disposable. CLI data uses `.draftgo/tmp/<command>/<run-id>/`; AI-created scratch files use `.draftgo/tmp/ai/<run-id>/`. User-facing evidence belongs under registered `.draftgo/artifacts/`. Use `draftgo clean --dry-run` before `draftgo clean --yes`.
+
 # DraftGo 开发助手
 
 ## 核心边界
@@ -50,8 +59,8 @@ context 会校验本地 Reference，返回逐字章节、来源、实时项目/
 
 1. MCP 定位 pages/nav/docs 并读取 metadata。
 2. 批量 checkout；在 `.draftgo/worktree/` 按唯一 owner 编辑。
-3. 主 Agent 回读全部修改，统一运行 `draftgo check`；交付前需要核对远端版本时运行 `draftgo check --remote`。
-4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。页面布局或交互变化时在 commit 后用 `draftgo verify-ui <url> --resource <type:id>` 验证远端已提交版本。
+3. 主 Agent 回读全部修改，编辑过程中统一运行一次快速 `draftgo check`。交付前运行 `draftgo verify <type> <id...>`；需要远端证据时加 `--remote`，页面布局或交互变化时加对应 `--url`。
+4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。commit 后需要验证远端页面时运行 `draftgo verify <type> <id> --remote --url <url>`。
 5. 409/412 时停止自动提交，保留 base/local/remote 冲突材料；不得 force、覆盖或自动合并。
 
 完整 manifest、流式传输、哈希和冲突规则见 `references/checkout.md`。
@@ -84,10 +93,10 @@ draftgo changelog add "<完成结果>"
 | 范围 | 最低证据 |
 |---|---|
 | MCP 连接 | 失败时用 `draftgo mcp test` 核对 initialize、tools/list 和关键工具；输出不含 SAT |
-| 页面、导航、文档 | checkout manifest、`draftgo check`、必要的 `verify-ui`、diff、commit 返回版本与哈希 |
+| 页面、导航、文档 | checkout manifest、`draftgo check`、交付前 `draftgo verify`、diff、commit 返回版本与哈希 |
 | 结构化资源 | search/describe 契约、call 结果与回读的权限、字段、错误和副作用 |
 | 自定义服务 | 动态 Route describe、无副作用健康请求或目标行为结果，以及管理员调用审计 |
-| 冲突 | `.draftgo/conflicts/` 的 base/local/remote；解决后重新 check、必要的 verify-ui 和 commit |
+| 冲突 | `.draftgo/conflicts/` 的 base/local/remote；解决后重新 check、必要的 verify 和 commit |
 | 本地底座 | `draftgo local status`、日志和相关 local 测试 |
 
 `draftgo deploy`、`auto-push` 和兼容 `push pages|nav|docs` 只能沿用当前 check/commit 语义，不能恢复旧的全量 push。主 Agent 最终明确区分 Skill 约束、MCP 实时状态和 checkout 正文证据。

package/resources/skill/init/SKILL.md

@@ -21,6 +21,8 @@ description: Install or refresh the DraftGo skill, connect a project to a DraftG
 
 draftgo init 只负责 Skill 安装；draftgo connect 负责保存并验证 server/SAT；draftgo mcp setup 负责宿主配置。不要混用职责。
 
+初始化后 `.draftgo/` 只保留已经写入的 `config.json`。不要预建 Task、lessons、changelog、worktree、conflicts 或其他占位文件和目录；首次实际使用对应能力时再创建。
+
 ## SAT 与配置
 
 - 交互式连接应使用隐藏输入；不要把 SAT 写入宿主配置、Skill 文件、命令行示例或日志。
@@ -33,7 +35,7 @@ draftgo init 只负责 Skill 安装；draftgo connect 负责保存并验证 serv
 - 宿主配置和诊断：draftgo mcp setup/status/test，详见 ../references/mcp.md。
 - 开发上下文：先运行匹配领域的 `draftgo context --task <task> --output json`；context 后仍可按需直接调用 MCP。
 - 远端资源补充定位：MCP project_overview、resource_search、resource_list。
-- 正文编辑：自主设计并批量 checkout，不同资源按唯一 owner 并行修改，由主 Agent 统一运行 check/必要的 verify-ui、diff 和 commit。
+- 正文编辑：自主设计并批量 checkout，不同资源按唯一 owner 并行修改，由主 Agent 统一运行 check、交付前 verify、diff 和 commit。
 - 结构化资源：直接使用 MCP 的 api_search、api_describe、api_call；不 checkout、不生成本地镜像。
 - 完成日志：只有整个任务统一验证且全部 commit/MCP 交付成功后，由主 Agent 执行一次 `draftgo changelog add "<完成结果>"`；验证、冲突或交付失败时不得写入。
 - 管理本地基座：draftgo local start|stop|logs|status；local-dev、local up/down 仍可用。

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.49",
+  "version": "3.0.52",
   "entry": "SKILL.md",
   "description": "以 context 聚合编排、Skill/reference 原文、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",

package/resources/skill/references/checkout.md

@@ -4,6 +4,12 @@ read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manif
 
 # Checkout / Commit
 
+## Workflow 2.0 scope
+
+The checkout set includes `pages`, `navigations`, `docs/articles`, and `custom_services`. A custom-service checkout is a directory containing exactly `service.go`, `go.mod`, `go.sum`, and `service.json`, plus one complete `.base` directory. `draftgo commit custom-services <id>` saves a cloud draft; it does not publish. Use `draftgo test custom-services <id>` for server Runner validation/execution and `draftgo publish custom-services <id>` for explicit publication. DB Meta remains a live MCP/API resource and is never checked out.
+
+`draftgo refresh <type> <id...>` is a safe checkout shortcut. It updates only a clean local worktree; local changes stop it. A successful commit keeps current local files and one base only. Cloud version storage is the sole history source.
+
 > 根 `SKILL.md` 在 Skill 触发时会自动加载。使用本文件前，先完成根 Skill 的“强制预读：Reference 优先于 MCP”任务路由。本文件只说明长正文的传输、版本和冲突规则，不能替代页面、前端、运行时或安全资料。
 
 ## 适用范围
@@ -87,12 +93,12 @@ base 已变化时必须拒绝覆盖。
 ## Commit 流程
 
 1. 读取 manifest 指向的 worktree 文件，计算当前字节数和 SHA-256；未变化时返回 `unchanged`。
-2. 按 content_type 执行本地结构检查；页面布局或交互有变化时另外运行 `draftgo verify-ui`。
+2. 按 content_type 执行本地结构和内联脚本检查；页面布局或交互有变化时运行 `draftgo verify <type> <id> --url <url>`。
 3. 通过专用 HTTP 流式上传原始文件，携带 `If-Match`、base version/revision、content_type、长度和 SHA-256。
 4. 完整正文不得作为 MCP tool 参数发送。
 5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
 
-推荐编辑顺序：主 Agent 执行一次 context -> MCP 按需补充定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` -> `draftgo diff` -> commit -> 页面变化时用 `draftgo verify-ui <url> --resource <type:id>` 验证远端已提交版本。遇到本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
+推荐编辑顺序：主 Agent 执行一次 context -> MCP 按需补充定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` -> `draftgo diff` -> commit -> 页面变化时用 `draftgo verify <type> <id> --remote --url <url>` 验证远端已提交版本。遇到本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
 
 单个 commit 成功不自动写 changelog。只有整个任务统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行一次 `draftgo changelog add "<完成结果>"`。任何检查失败、409/412 或交付失败都不得写入。
 
@@ -111,7 +117,7 @@ base 已变化时必须拒绝覆盖。
 - `base` 是 checkout 时的内容；`local` 是发生冲突时的本地快照；`remote` 是重新下载并校验的当前远端内容。
 - `conflict.json` 记录三份路径、版本、ETag 和哈希，不嵌入完整正文。
 - Agent 或用户在 worktree local 文件中完成合并；不要手写 HTML 自动合并器，也不要改动保存的三份证据。
-- 合并完成后运行 `draftgo check`、必要时 `draftgo verify-ui`，再执行 `draftgo conflict resolve <type> <id>`。
+- 合并完成后运行 `draftgo check`、必要时 `draftgo verify`，再执行 `draftgo conflict resolve <type> <id>`。
 - resolve 校验 worktree 与 remote，采用 remote 版本作为新的 base，但保留合并后的 worktree；随后运行
   `draftgo diff` 并 `draftgo commit`。
 

package/resources/skill/references/custom-services.md

@@ -1,4 +1,5 @@
 ---
+
 read_when: 编写、修改、调试或评审自定义服务时；使用服务 SDK、路由、事件、定时任务或服务依赖时
 ---
 

package/resources/skill/references/frontend.md

@@ -68,7 +68,7 @@ version: 2.0.0
 - 表格、代码和其他超宽内容应在合理边界内可访问，不能让核心操作因溢出而不可达。
 - 弹窗和抽屉在目标视口内完整可用，长内容有明确滚动边界。
 
-需要浏览器证据时按页面受众和现有断点运行 `draftgo verify-ui <url> --mobile-check auto`；不要机械遍历与任务无关的视口。
+需要浏览器证据时按页面受众和现有断点运行 `draftgo verify <type> <id> --url <url>`；只有验收确实覆盖多端时加 `--viewport both`，不要机械遍历与任务无关的视口。业务 HTML 位于 iframe 时默认 `--frame auto` 会检查顶层和可见 iframe，`--selector` 可直接定位业务 DOM。
 
 ### 导航与系统页边界（强制）
 

package/src/cli.js

@@ -15,6 +15,9 @@ const VALUE_FLAGS = new Set([
   'browser-path',
   'resource',
   'mobile-check',
+  'ui',
+  'frame',
+  'viewport',
   'screenshot',
   'selector',
   'width',
@@ -29,6 +32,30 @@ const VALUE_FLAGS = new Set([
   'input',
   'type',
   'task',
+  'title',
+  'description',
+  'item-id',
+  'id',
+  'owner',
+  'original',
+  'original-requirement',
+  'clarified',
+  'clarified-requirement',
+  'expected-effect',
+  'effect',
+  'scope',
+  'out-of-scope',
+  'content',
+  'acceptance',
+  'module-logic',
+  'user-journey',
+  'item',
+  'date',
+  'handler',
+  'headers',
+  'user',
+  'side-effect-policy',
+  'evidence',
 ]);
 
 function parse(argv) {
@@ -36,24 +63,24 @@ function parse(argv) {
   const out = { command: null, positional: [], flags: {}, errors: [] };
   while (args.length) {
     const a = args.shift();
-    if (a === '--') { out.positional.push(...args); break; }
+    if (a === '--') {
+      out.positional.push(...args);
+      break;
+    }
     if (a.startsWith('--')) {
       const raw = a.slice(2);
       const eq = raw.indexOf('=');
       if (eq >= 0) {
         const key = raw.slice(0, eq);
         const value = raw.slice(eq + 1);
-        if (VALUE_FLAGS.has(key) && !value) {
-          out.errors.push(`选项 --${key} 需要一个值。`);
-        } else {
-          out.flags[key] = value;
-        }
+        if (VALUE_FLAGS.has(key) && !value) out.errors.push(`Option --${key} requires a value.`);
+        else out.flags[key] = value;
       } else {
         const next = args[0];
         if (VALUE_FLAGS.has(raw)) {
           // A declared value flag must never silently become boolean true.
           if (next === undefined || next === '--' || next.startsWith('--')) {
-            out.errors.push(`选项 --${raw} 需要一个值。`);
+            out.errors.push(`Option --${raw} requires a value.`);
           } else {
             out.flags[raw] = next;
             args.shift();
@@ -63,8 +90,7 @@ function parse(argv) {
         }
       }
     } else if (a.startsWith('-') && a.length > 1) {
-      const key = a.slice(1);
-      out.flags[key] = true;
+      out.flags[a.slice(1)] = true;
     } else if (!out.command) {
       out.command = a;
     } else {

package/src/commandRegistry.js

@@ -9,12 +9,19 @@ const commands = [
   { name: 'status', run: (dir) => require('./commands/status')(dir) },
   { name: 'context', run: (dir, args, flags) => require('./commands/context')(dir, args, flags) },
   { name: 'changelog', run: (dir, args, flags) => require('./commands/changelog')(dir, args, flags) },
+  { name: 'task', run: (dir, args, flags) => require('./commands/task')(dir, args, flags) },
+  { name: 'clean', run: (dir, args, flags) => require('./commands/clean')(dir, args, flags) },
   { name: 'map', run: (dir, _args, flags) => require('./commands/map')(dir, flags) },
-  { name: 'check', run: (dir, _args, flags) => require('./commands/check')(dir, flags) },
-  { name: 'verify-ui', aliases: ['verifyui'], run: (dir, args, flags) => require('./commands/verifyUi')(dir, args, flags) },
+  { name: 'check', run: (dir, args, flags) => require('./commands/check')(dir, args, flags) },
+  { name: 'verify', run: (dir, args, flags) => require('./commands/verify')(dir, args, flags) },
+  { name: 'verify-ui', aliases: ['verifyui'], run: (dir, args, flags) => require('./commands/verifyUiCompat')(dir, args, flags) },
   { name: 'mcp', run: (dir, args, flags) => require('./commands/mcp')(dir, args, flags) },
   { name: 'checkout', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
+  { name: 'refresh', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
   { name: 'commit', run: (dir, args, flags) => require('./commands/commit')(dir, args, flags) },
+  { name: 'validate', run: (dir, args, flags) => require('./commands/customService').validate(dir, args, flags) },
+  { name: 'test', run: (dir, args, flags) => require('./commands/customService').test(dir, args, flags) },
+  { name: 'publish', run: (dir, args, flags) => require('./commands/customService').publish(dir, args, flags) },
   { name: 'reconcile', run: (dir, args, flags) => require('./commands/reconcile')(dir, args, flags) },
   { name: 'diff', run: (dir, args, flags) => require('./commands/diff')(dir, args, flags) },
   { name: 'conflicts', run: (dir, args, flags) => require('./commands/conflicts')(dir, args, flags) },

package/src/commands/check.js

@@ -5,19 +5,75 @@ const path = require('path');
 const log = require('../logger');
 const { analyzeProject } = require('../projectMap');
 const { inspectRemoteCheckouts } = require('../worktree/status');
+const customServices = require('../customServices');
+const { workspaceHealth } = require('../workspaceHealth');
 
 function legacyCacheDetected(projectDir) {
   return ['pages', 'navigations', 'docs', 'db_meta', 'custom_scripts', 'aihub', 'roles', 'users', 'system_config']
     .some((name) => fs.existsSync(path.join(projectDir, '.draftgo', name, 'index.json')));
 }
 
-async function check(projectDir, flags = {}) {
-  const result = analyzeProject(projectDir);
+async function check(projectDir, positional = [], flags = {}) {
+  if (!Array.isArray(positional)) {
+    flags = positional || {};
+    positional = [];
+  }
+  const [requestedType, ...requestedIds] = positional;
+  if (requestedType && !customServicesCommand().isServiceType(requestedType)) {
+    log.err('Usage: draftgo check [custom-services <id...>] [--remote]');
+    return 1;
+  }
+  if (requestedType && !requestedIds.length) {
+    log.err('Usage: draftgo check custom-services <id...> [--remote]');
+    return 1;
+  }
+  const resourceKeys = flags.resourceKeys || null;
+  const result = analyzeProject(projectDir, { resourceKeys });
+  if (resourceKeys) {
+    const manifestKeys = new Set(Object.keys(result.map.checkouts.reduce((entries, entry) => {
+      entries[`${entry.resource_type}:${entry.resource_id}`] = true;
+      return entries;
+    }, {})));
+    for (const key of resourceKeys) if (!manifestKeys.has(key)) result.errors.push(`${key}: resource is not checked out`);
+  }
+  const hygiene = workspaceHealth(projectDir);
+  hygiene.warnings.forEach((warning) => result.warningDetails.push({ code: warning.code, confidence: 'high', message: `${warning.path}${warning.size ? ` (${warning.size} bytes)` : ''}` }));
+  hygiene.warnings.forEach((warning) => result.warnings.push(`${warning.code}: ${warning.path}`));
+  const serviceManifest = customServices.loadManifest(projectDir);
+  const customServiceChecks = [];
+  const requested = new Set(requestedIds.map(String));
+  const serviceEntries = Object.values(serviceManifest.entries)
+    .filter((entry) => !resourceKeys && (!requestedType || requested.has(String(entry.resource_id))));
+  if (requestedType) {
+    for (const id of requested) {
+      if (!serviceEntries.some((entry) => String(entry.resource_id) === id)) {
+        result.errors.push(`custom_services ${id}: resource is not checked out`);
+      }
+    }
+  }
+  for (const entry of serviceEntries) {
+    try {
+      const state = customServices.diff(projectDir, entry.resource_id);
+      customServiceChecks.push({ resource_type: 'custom_services', resource_id: entry.resource_id, state: state.changed ? 'local_modified' : 'clean_local', files: state.files });
+    } catch (error) {
+      result.errors.push(`custom_services ${entry.resource_id}: ${error.message}`);
+    }
+  }
   let remote = null;
   let remoteError = null;
   if (flags.remote) {
     try {
-      remote = await inspectRemoteCheckouts(projectDir);
+      const [contentRemote, serviceRemote] = await Promise.all([
+        inspectRemoteCheckouts(projectDir, resourceKeys ? {
+          entries: result.map.checkouts.filter((entry) => resourceKeys.includes(`${entry.resource_type}:${entry.resource_id}`)),
+        } : {}),
+        resourceKeys
+          ? Promise.resolve([])
+          : customServices.inspectRemote(projectDir, requestedType ? { ids: [...requested] } : {}),
+      ]);
+      remote = requestedType
+        ? serviceRemote.filter((entry) => requested.has(String(entry.resource_id)))
+        : [...contentRemote, ...serviceRemote];
       for (const entry of remote) {
         if (!['clean', 'clean_local', 'local_modified'].includes(entry.state)) {
           const detail = `${entry.resource_type} ${entry.resource_id}: ${entry.state}`
@@ -32,16 +88,26 @@ async function check(projectDir, flags = {}) {
       result.errors.push(`Remote checkout check failed: ${error.message}`);
     }
   }
-  const output = { ...result, remote, remote_error: remoteError };
+  const output = {
+    content_validation: { map: result.map, errors: result.errors, warnings: result.warnings, warning_details: result.warningDetails, custom_services: customServiceChecks },
+    remote_validation: { resources: remote, error: remoteError },
+    workspace_hygiene: hygiene,
+  };
   if (flags.output === 'json') {
     console.log(JSON.stringify({ ...output, legacy_cache_ignored: legacyCacheDetected(projectDir) }, null, 2));
     return result.errors.length || (flags.strict && result.warnings.length) ? 1 : 0;
   }
 
   log.title('draftgo check');
-  log.info(`Checked-out pages: ${result.map.pages.length}`);
-  log.info(`Checked-out navigations: ${result.map.navigations.length}`);
-  log.info(`Checked-out docs: ${result.map.docs.length}`);
+  const selectedCount = (type, entries) => resourceKeys
+    ? entries.filter((entry) => resourceKeys.includes(`${type}:${entry.resource_id}`)).length
+    : entries.length;
+  log.info(`Checked-out pages: ${selectedCount('pages', result.map.pages)}`);
+  log.info(`Checked-out navigations: ${selectedCount('navigations', result.map.navigations)}`);
+  log.info(`Checked-out docs: ${selectedCount('docs', result.map.docs)}`);
+  log.info(`Checked-out custom services: ${customServiceChecks.length}`);
+  log.info(`Workspace: ${hygiene.managed_files} managed, ${hygiene.unknown_files} unknown, ${hygiene.temporary_files} temporary, ${hygiene.artifact_files} artifact file(s)`);
+  log.info(`Workspace size: ${hygiene.total_bytes} bytes; reclaimable: ${hygiene.reclaimable_bytes} bytes`);
   if (remote) log.info(`Remote checkout comparison: ${remote.length} resource(s)`);
   for (const message of result.errors) log.err(message);
   for (const detail of result.warningDetails) log.warn(`[${detail.code}/${detail.confidence}] ${detail.message}`);
@@ -52,4 +118,8 @@ async function check(projectDir, flags = {}) {
   return 0;
 }
 
+function customServicesCommand() {
+  return require('./customService');
+}
+
 module.exports = check;

package/src/commands/checkout.js

@@ -9,6 +9,9 @@ async function checkout(projectDir, positional, flags = {}) {
     log.err('Usage: draftgo checkout <pages|nav|docs> <id...>');
     return 1;
   }
+  if (require('./customService').isServiceType(resourceType)) {
+    return require('./customService').checkout(projectDir, ids, flags);
+  }
   const results = await checkoutResources(projectDir, resourceType, ids, { force: Boolean(flags.force) });
   if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
   else for (const entry of results) log.ok(`Checked out ${entry.resource_type} ${entry.resource_id} -> ${entry.local_path}`);

package/src/commands/clean.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const log = require('../logger');
+const runtime = require('../runtimeFiles');
+
+const MANAGED_PREFIXES = ['tmp/', 'artifacts/ui/', 'artifacts/api/', 'artifacts/custom-services/'];
+function fileSize(file) { try { const stat = fs.statSync(file); return stat.isFile() ? stat.size : 0; } catch { return 0; } }
+function olderThan(value) {
+  if (value == null || value === '') return 0;
+  const match = String(value).match(/^(\d+)([dhm])$/i); if (!match) throw new Error('--older-than must use <number>d, <number>h, or <number>m.');
+  const unit = { d: 86400000, h: 3600000, m: 60000 }[match[2].toLowerCase()]; return Number(match[1]) * unit;
+}
+function plan(projectDir, flags = {}) {
+  const root = runtime.draftgoRoot(projectDir); const manifest = runtime.load(projectDir); const age = olderThan(flags['older-than']); const now = Date.now();
+  const types = new Set(String(flags.type || '').split(',').map((item) => item.trim()).filter(Boolean)); const candidates = [];
+  for (const entry of manifest.entries) {
+    if (!entry.cleanable || (types.size && !types.has(entry.type))) continue;
+    const relative = String(entry.path).replace(/\\/g, '/');
+    if (!MANAGED_PREFIXES.some((prefix) => relative.startsWith(prefix))) continue;
+    const absolute = path.resolve(root, relative); if (!runtime.inside(root, absolute) || !fs.existsSync(absolute)) continue;
+    const stat = fs.statSync(absolute); if (age && now - stat.mtimeMs < age) continue;
+    candidates.push({ ...entry, absolute, size: stat.isFile() ? stat.size : 0, reason: 'runtime_manifest' });
+  }
+  const tmp = path.resolve(root, 'tmp');
+  if (fs.existsSync(tmp) && runtime.inside(root, tmp) && (!types.size || types.has('tmp') || types.has('ai'))) {
+    const visitTmp = (current) => {
+      for (const child of fs.readdirSync(current, { withFileTypes: true })) {
+        const absolute = path.join(current, child.name);
+        if (child.isDirectory()) visitTmp(absolute);
+        else if (child.isFile() && !candidates.some((entry) => entry.absolute === absolute)) {
+          const stat = fs.statSync(absolute);
+          if (!age || now - stat.mtimeMs >= age) candidates.push({
+            path: path.relative(root, absolute).replace(/\\/g, '/'), absolute,
+            type: path.relative(tmp, absolute).replace(/\\/g, '/').startsWith('ai/') ? 'ai' : 'tmp',
+            size: stat.size, reason: 'temporary_area',
+          });
+        }
+      }
+    };
+    visitTmp(tmp);
+  }
+  if (flags['all-artifacts']) {
+    for (const prefix of MANAGED_PREFIXES.filter((item) => item.startsWith('artifacts/'))) {
+      const directory = path.resolve(root, prefix); if (!runtime.inside(root, directory) || !fs.existsSync(directory)) continue;
+      const visit = (current) => { for (const child of fs.readdirSync(current, { withFileTypes: true })) { const absolute = path.join(current, child.name); if (child.isDirectory()) visit(absolute); else if (child.isFile() && !candidates.some((entry) => entry.absolute === absolute)) candidates.push({ path: path.relative(root, absolute).replace(/\\/g, '/'), absolute, type: 'artifact', size: fileSize(absolute), reason: 'all_artifacts' }); } };
+      visit(directory);
+    }
+  }
+  return { entries: candidates, count: candidates.length, bytes: candidates.reduce((sum, entry) => sum + entry.size, 0) };
+}
+async function clean(projectDir, _positional, flags = {}) {
+  const result = plan(projectDir, flags); const output = { count: result.count, bytes: result.bytes, entries: result.entries.map(({ absolute, ...entry }) => entry) };
+  if (flags.output === 'json') console.log(JSON.stringify({ ...output, deleted: Boolean(flags.yes && !flags['dry-run']) }, null, 2));
+  else { log.title('draftgo clean'); result.entries.forEach((entry) => log.info(`${entry.path} (${entry.size} bytes)`)); log.info(`Reclaimable: ${result.bytes} bytes in ${result.count} file(s).`); }
+  if (!flags.yes || flags['dry-run']) { if (!flags.output) log.dim('Run with --yes to delete this plan.'); return 0; }
+  const manifest = runtime.load(projectDir); const removed = new Set();
+  for (const entry of result.entries) { if (!runtime.inside(runtime.draftgoRoot(projectDir), entry.absolute)) throw new Error('Clean target escaped .draftgo.'); fs.rmSync(entry.absolute, { force: true }); removed.add(entry.path); }
+  const tmp = path.join(runtime.draftgoRoot(projectDir), 'tmp');
+  if (fs.existsSync(tmp)) {
+    const removeEmpty = (directory) => {
+      for (const child of fs.readdirSync(directory, { withFileTypes: true })) if (child.isDirectory()) removeEmpty(path.join(directory, child.name));
+      if (directory !== tmp && fs.readdirSync(directory).length === 0) fs.rmdirSync(directory);
+    };
+    removeEmpty(tmp);
+  }
+  manifest.entries = manifest.entries.filter((entry) => !removed.has(entry.path)); runtime.save(projectDir, manifest);
+  if (!flags.output) log.ok(`Deleted ${result.count} managed file(s).`); return 0;
+}
+clean.plan = plan;
+module.exports = clean;

package/src/commands/commit.js

@@ -9,6 +9,9 @@ async function commit(projectDir, positional, flags = {}) {
     log.err('Usage: draftgo commit <pages|nav|docs> <id...>');
     return 1;
   }
+  if (require('./customService').isServiceType(resourceType)) {
+    return require('./customService').commit(projectDir, ids, flags);
+  }
   const streamed = [];
   const printStatus = (result) => {
     streamed.push(result);

package/src/commands/conflict.js

@@ -18,9 +18,11 @@ async function conflict(projectDir, positional, flags = {}) {
     log.err('Usage: draftgo conflict <show|resolve> <pages|nav|docs> <id>');
     return 1;
   }
-  const record = action === 'show'
-    ? showConflict(projectDir, resourceType, resourceId)
-    : await resolveConflict(projectDir, resourceType, resourceId);
+  const custom = require('./customService').isServiceType(resourceType);
+  const services = custom ? require('../customServices') : null;
+  const record = custom
+    ? (action === 'show' ? services.showConflict(projectDir, resourceId) : services.resolveConflict(projectDir, resourceId))
+    : (action === 'show' ? showConflict(projectDir, resourceType, resourceId) : await resolveConflict(projectDir, resourceType, resourceId));
   if (flags.output === 'json') console.log(JSON.stringify(record, null, 2));
   else printRecord(record);
   if (action === 'resolve') log.info('The remote revision is now the base; run check, diff, and commit the merged worktree file.');

package/src/commands/conflicts.js

@@ -2,9 +2,10 @@
 
 const log = require('../logger');
 const { listConflicts } = require('../worktree');
+const { serviceConflicts } = require('../customServices');
 
 function conflicts(projectDir, _positional, flags = {}) {
-  const records = listConflicts(projectDir, { all: Boolean(flags.all) });
+  const records = [...listConflicts(projectDir, { all: Boolean(flags.all) }), ...serviceConflicts(projectDir, { all: Boolean(flags.all) })];
   if (flags.output === 'json') console.log(JSON.stringify(records, null, 2));
   else if (!records.length) log.ok('No unresolved DraftGo conflicts.');
   else for (const record of records) {

package/src/commands/context.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const log = require('../logger');
-const { collectContext, TASK_PROFILES } = require('../context');
+const { collectContext, compactContext, TASK_PROFILES } = require('../context');
 const { parseTimeout } = require('../timeout');
 
 function printUsage() {
@@ -17,7 +17,7 @@ async function contextCommand(projectDir, positional = [], flags = {}) {
   const result = await collectContext(projectDir, flags.task, {
     timeoutMs: parseTimeout(flags.timeout),
   });
-  console.log(JSON.stringify(result, null, 2));
+  console.log(JSON.stringify(flags.compact ? compactContext(result) : result, null, 2));
   return 0;
 }