draftgo-cli 3.0.1 → 3.0.33

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DraftGo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,23 +11,25 @@
 
 ## DraftGo Next v3 基线
 
-DraftGo Next 前端基线为 React + Vite + shadcn/ui + Tailwind。draftgo-cli v3 的定位是 DraftGo 工作台 CLI：负责本地运行环境、资源同步、开发检查、push/pull 闭环和 AI 工具 skill 分发。
+DraftGo Next 前端基线为 React + Vite。draftgo-cli v3 的定位是 DraftGo 工作台 CLI：负责本地运行环境、资源同步、开发检查、push/pull 闭环和 AI 工具 skill 分发。
 
-数据库页面仍以 HTML 为核心，`dg-*` 标签是 shadcn/ui 在 DraftGo 页面运行时里的协议表达：AI 看到 `dg-button`、`dg-card`、`dg-form`、`dg-table` 等，必须理解为 shadcn 组件能力，而不是 daisyUI、Bootstrap 或自研组件库。CLI 分发的 skill 已把这条规则写入前端规范。
+数据库页面以 HTML 为核心，默认使用 Tailwind CSS 和页面级 CSS。
 
-已存在的 `draftgo init/update/status/doctor/map/check/connect/local-dev` 保持兼容；首批工作台命令如下：
+核心命令为 `draftgo init/update/status/map/check/connect/local setup`；工作台命令如下：
 
 | 命令 | 说明 |
 |---|---|
-| `draftgo local up` | 启动 `draftgo local-dev` 生成的 `.draftgo/docker/docker-compose.yaml` 本地栈。 |
-| `draftgo local down` | 停止本地栈。 |
+| `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 dev` | 运行当前项目 `package.json` 中的 `scripts.dev`。 |
-| `draftgo build` | 运行当前项目 `package.json` 中的 `scripts.build`。 |
-| `draftgo check` | 本地资源闭环检查，辅助发现入口绑定、缺文件、重复路由和疑似 mock 风险。 |
+| `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`。 |
 
 ## 安装
 
@@ -55,12 +57,14 @@ draftgo init all                         # 所有支持的工具
 | 命令 | 说明 |
 |---|---|
 | `draftgo init [target]...` | 安装 skill。不传 target 时自动识别；`all` 表示全部。 |
-| `draftgo update [target]...` | 把 CLI 内置 skill 覆盖写到每个已安装或项目中检测到的 AI 工具自己的 skill 目录；保留本地 `config / changelog / lessons / Task` 等运行时数据。**若 npm 上存在更新的 CLI 版本，会先自动升级 CLI 再重跑自己**。 |
+| `draftgo update [target]...` | 完整更新：先更新全局 CLI，再用新版原子刷新已安装或检测到的 AI 工具 skill。离线时仍会用当前 CLI 刷新 skill。 |
 | `draftgo uninstall [target]...` | 移除指定 AI 工具的 skill 目录（含入口文件 + 子技能 + scripts）。加 `--purge` 会连 `.draftgo/` 一起删。 |
 | `draftgo status` | 查看当前项目装了哪些 AI 工具入口、skill 版本。 |
-| `draftgo doctor` | 诊断：Python 是否可用、检测到哪些 AI 工具、各入口状态。 |
-| `draftgo map` | 输出本地 DraftGo 资源地图：页面、导航、DB、脚本、AIHub、外部 API、文档、系统配置、入口引用，帮助 AI 快速进入项目。 |
-| `draftgo check` | 本地闭环体检：检查 route、入口绑定、文件存在性、重复路由和疑似 mock/伪功能风险。 |
+| `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` | 查看帮助。 |
@@ -69,24 +73,27 @@ draftgo init all                         # 所有支持的工具
 
 - `--project <dir>`：对指定目录操作（默认当前工作目录）。
 - `--force`：`init/update` 时强制覆盖已存在的 AI 工具 skill 目录。
-- `--skip-update-check`：`update` 时不去 npm 查最新版，直接用当前 CLI 执行。
+- `--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` 的交付级别。
 
-可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭自动升级检查（离线、CI 等场景）。
+版本查询结果缓存 24 小时。可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭版本检查（离线、CI 等场景）。
 
 ### 机器可读输出
 
-`draftgo map --output json` 会输出本地资源地图，适合 Agent 在开发前快速读取上下文；覆盖 pages、navigations、db_meta、custom_scripts、aihub、external_apis、docs、doc_categories、system_config、roles 和入口引用。AIHub 条目会包含常用配置摘要：
+`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`：传输协议、已发现工具数量。
 
-外部 API 会摘要 `code/method/path/base_url/tags/status`，文档会摘要 `slug/category/content_file/status`，系统配置只展示 `config_key/category/value_type/is_sensitive/status`，避免把敏感值直接暴露给 Agent 输出。
+文档会摘要 `slug/category/content_file/status`，系统配置只展示 `config_key/category/value_type/is_sensitive/status`，避免把敏感值直接暴露给 Agent 输出。
 
-`draftgo check --output json` 会输出 `{ map, errors, warnings }`，适合 CI 或开发收尾时作为轻量证据。`--strict` 会把 warnings 也视为失败。
+`draftgo check --output json` 会输出 `{ map, errors, warnings, warningDetails }`，其中 `warningDetails` 带规则编号与置信度。当前只检查页面入口绑定、页面/导航 HTML 解析，以及未登记到 `index.json` 的本地资源文件；`--strict` 会把 warnings 也视为失败。
 
 ## 更新
 
@@ -95,32 +102,54 @@ cd <your-project>
 draftgo update
 ```
 
-就这一条命令。`update` 会自己去 npm 查最新版：
+`update` 是唯一的完整更新命令：
 
-- 如果 CLI 已是最新 → 直接把内置 skill 资源覆盖到每个已安装 AI 工具的 skill 目录
-- 如果 CLI 过时 → 自动执行 `npm install -g draftgo-cli@latest`，然后用新 CLI 重跑一遍 `update`
+- 如果 CLI 已是最新 → 原子替换每个目标的 skill 资源
+- 如果 npm 有新版 → 先全局更新 CLI，再由新版刷新 skill
+- 如果 npm 暂不可达 → 保留当前 CLI，并刷新 skill
 
 整个过程中，你本地的 `.draftgo/config.json`、`changelog.md`、`lessons/`、`Task/` 等运行时数据都不会被动到。
 
 ## 内置 Skill 文档约定
 
+内置 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` 兜底。
 
 前端资源约定：
 
 - 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 时优先使用国内镜像引入。
+
+Go 自定义服务通过 `draftgo.DB.CreateMany(...)` 与 `draftgo.DB.UpdateMany(...)` 批量写入动态数据。
+
+自定义服务（Custom Scripts）约定：
 
-动态 DB SDK 也提供 `sdk.db.create_many(...)` 与 `sdk.db.update_many(...)`，用于脚本内批量写入。
+- 自定义服务使用 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)。
 
 AIHub Agent 用户选模型约定：
 
-- 管理端在 Agent 的 `data.spec.model_selection.user_selectable=true` 后，页面可调用 `DraftGoAI.getSelectableModels(agentId)` 获取 `{ user_selectable, models }`。
+- 新页面的 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 白名单校验。
 
@@ -178,7 +207,7 @@ AIHub Agent JSON 输出约定：
 
 ## 产物结构
 
-每个 AI 工具拿到的是**完整自包含**的 skill 副本（SKILL.md + 子技能 + rules + scripts），写入它自己的目录。`.draftgo/` 只放运行时数据。
+每个 AI 工具拿到完整的核心说明（SKILL.md + 子技能 + rules + scripts）。大型 OpenAPI 快照只在 `.draftgo/skill-shared/` 保存一份，避免多个工具重复复制；也可直接用 `draftgo api <keyword>` 查询。
 
 ```
 <project>/
@@ -189,6 +218,7 @@ AIHub Agent JSON 输出约定：
 │   ├── Task/                         # 每个开发任务一个 md，含需求 / 设计 / 任务标记
 │   ├── lessons/                      # 开发经验、踩坑记录、基座局限场景
 │   ├── pages/  navigations/  ...     # init 拉取的本地缓存
+│   ├── skill-shared/references/api.json # 多 AI 工具共享的 OpenAPI 快照
 │   └── .version                      # CLI 写入：当前已装 skill 的版本
 │
 └── (AI 工具 skill 目录，按需写入；每份都是完整副本)
@@ -202,33 +232,29 @@ AIHub Agent JSON 输出约定：
     .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`。
 
 ---
 
-## v1.2.0 升级要点（高质量开发规范）
+## v3.0.30 升级要点（自定义服务 AI SDK）
 
-CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/dev-workflow.md`），目标是让 AI 在做 DraftGo 项目开发时"小修不拖慢、功能有计划、高风险有门禁、质量靠证据"。
+- 内置 Skill 补齐 AIHub 推理、Embedding、Agent/Prompt/Skill/MCP 资产 CRUD，以及供应商、模型路由和运行记录接口。
+- 增加知识库、文档、Chunk、长期记忆的 Go SDK 说明，包含文件上传、检索、重建索引和管理员同构入口。
+- 记录 `config.aihub` 推理开关与 Agent/模型白名单，并为全部新 SDK 能力增加文档契约测试。
 
-**分级流程**：
+## v3.0.28 升级要点（同步可靠性）
 
-```
-小修：直接定位 → 改 → 轻量证据
-轻功能：范围复述 → 直接做 → 凭证据闭环
-标准功能：轻量确认 → 内部短计划 → 执行闭环
-高风险：完整 Story / 计划 / 验证 / 人工确认
-```
+- 修复导航 pull：列表元数据会逐条获取详情 HTML，避免空内容覆盖本地导航。
+- 指定 ID 的 pull 改为合并索引；请求失败、详情缺失或响应不完整时返回非零，保留本地缓存。
+- `draftgo push` 支持默认全量推送；`deploy --delivery preview` 使用无副作用的 dry-run 预览。
 
-**新增本地目录**：
-- `.draftgo/Task/`：每个开发任务一个 Markdown 文件，含需求纪要 / 设计 / 任务清单 / ⬜🟡✅❌⏸ 标记 / 完成回顾
+## v3.0.27 升级要点（自动推送与索引恢复）
 
-**经验记录（lessons）**：
-- `.draftgo/lessons/` 统一记录开发过程中的阻碍、踩坑、框架运行时问题、基座能力局限和可复用经验。
-- 文件按 `YYYY-MM-DD-主题关键词.md` 命名，便于后续回顾和沉淀为开发规范。
-
-**前端 UI 能力调用**：DraftGo 平台前端默认采用 React + shadcn/ui + Tailwind CSS；数据库 HTML 页面使用 `dg-*` 表达 shadcn 组件能力，`dg-*` 不是自研 UI 协议。若本地 Agent 环境存在 shadcn / 前端 UI 相关 Skills，前端界面开发时优先调用。DraftGo-CLI 提供运行时、资源、数据、路由、入口绑定和验证方法，并在规范中声明 shadcn/Tailwind 已引入。
-
-完整规范见各 AI 工具自身 skill 目录下的 `rules/dev-workflow.md`，例如 `.claude/skills/draftgo/rules/dev-workflow.md`。
+- 新增 `draftgo auto-push`：始终先运行本地 `check`，仅在 `.draftgo/config.json` 的 `auto_push: true` 时继续推送；关闭时保留验证并返回未推送信息。
+- 支持 `draftgo auto-push --batch`，并行任务也受同一开关约束。
+- 指定资源缺少 `index.json` 条目时，push 会回读云端；资源存在则补齐元数据并继续推送本地文件，资源不存在则提示清理本地孤儿文件。
 
 ---
 
@@ -241,7 +267,7 @@ CLI v2.0.3 补充操作型页面的空间模型，重点解决后台管理 / 表
 - **工作台布局原则**：后台管理、表格、列表、审批、配置、内容维护等操作型页面，优先让页面根容器占满可用视口 / iframe 内容区。
 - **稳定控制区**：顶部筛选、搜索、标题操作区保持稳定高度，底部分页、批量操作栏、保存栏等流程控制区保持在工作区底部或稳定位置。
 - **数据区承接剩余空间**：主体数据区使用 `flex:1; min-height:0; overflow:auto` 等结构承接剩余空间，数据少时保留工作区空白，数据多时优先让数据区内部滚动。
-- **工作台结构同步**：`rules/frontend.md` 补充操作型页面的空间方法，基座对应文档为 `docs/frontend/rules.md`，避免分页跟随 1-2 条数据上浮。
+- **工作台结构同步**：`references/frontend.md` 补充操作型页面的空间方法，基座对应文档为 `docs/frontend/rules.md`，避免分页跟随 1-2 条数据上浮。
 
 ---
 
@@ -251,7 +277,7 @@ CLI v2.0.2 进一步完善 `draftgo update` 的目标识别逻辑，避免只修
 
 **核心变化：**
 
-- **平台定义成为单一信号源**：每个 AI 工具的入口文件、skill 目录和项目级探测信号统一维护在 `platforms.js`，`init / update / doctor` 共用同一份识别依据。
+- **平台定义成为单一信号源**：每个 AI 工具的入口文件、skill 目录和项目级探测信号统一维护在 `platforms.js`，`init / update / status` 共用同一份识别依据。
 - **update 覆盖所有检测到的工具**：不传 target 时，`draftgo update` 会合并“已安装 skill 的目标”和“项目中检测到的 AI 工具信号”，并刷新全部命中的工具。
 - **全平台测试覆盖**：单测现在会同时模拟 Claude Code、Cursor、Windsurf、Antigravity、Kiro、GitHub Copilot、Codex、Gemini 的项目级信号，防止后续再出现只命中部分工具的问题。
 
@@ -280,21 +306,6 @@ CLI v2.0.0 删除了内置 `resources/skill/reference/` 基座参考副本，进
 
 ---
 
-## v1.6.2 升级要点（开发效率轻量化）
-
-CLI v1.6.2 进一步降低开发流程摩擦：保留真实落地闭环、页面绑定和平台禁区，同时让小修和轻功能更快进入实现。
-
-**核心变化：**
-
-- **小修渐进读取**：小修优先只读目标资源和最小必要规则，不再默认展开完整规则链路。
-- **新增轻功能档**：简单页面能力、单入口交互、小型数据联动可走“范围复述 → 直接做 → 凭证据闭环”，不强制创建 Task。
-- **计划字段按需**：`depends / resource_lock / wave` 只在多任务、多资源冲突或准备并行时强制；单人串行小计划不再为字段服务。
-- **并行按收益启用**：只有任务数足够、边界清晰、资源不冲突且并行收益大于协调成本时才启用并行。
-- **取消 80 行硬限制**：改为“复杂或高风险代码分段实现并验证”，避免机械分批拖慢前端开发。
-- **验证按影响分层**：小修验证改动点，轻功能验证入口引用和主路径；标准功能按实际影响覆盖四态、数据、跳转和同步证据。
-
----
-
 ## v1.6.1 升级要点（前端规则收敛）
 
 CLI v1.6.1 继续优化开发效果：减少前端规则中过细的“适合 / 不适合”和固定模板描述，让 AI 在满足平台硬约束的前提下，根据页面目标和业务复杂度做实现判断。
@@ -315,12 +326,12 @@ CLI v1.6.0 强化了 skill 对“开发任务规划”的判断力，重点解
 **核心变化：**
 
 - **用户意图翻译**：当用户用非技术语言描述“案例库、新闻中心、产品中心、预约、资料下载”等业务目标时，AI 会先识别它是页面、多页面还是完整功能模块，而不是要求用户说出 CRUD、API、路由等开发术语。
-- **页面默认完整功能**：用户说“做一个页面”时，默认按可真实使用的页面功能处理；只有明确说“静态 / 纯页面 / demo / 先看效果”时，才按静态页处理。
+- **页面默认完整功能**：用户说“做一个页面”时，默认按可真实使用的页面功能处理；只有明确说“静态 / 纯页面 / 原型 / 先看效果”时，才按静态页处理。
 - **用户路径链路**：功能规划从“用户打开官网 / 系统入口 → 看见入口 → 点击进入 → 操作 → 反馈 → 后台维护 → 前台展示更新”这一整条链路倒推页面、导航、数据和权限。
 - **新增页面绑定**：创建页面后必须绑定到导航栏、首页入口、后台菜单或相关页面按钮之一；只创建页面文件、无法从正常路径点击进入，不算完成。
 - **真实落地闭环**：按钮、表单、搜索、筛选、分页、保存、删除、发布等交互默认要真实有效；需要可维护内容时，优先规划后台管理和同一份真实数据，追求高可用。
 
-这些规则保持轻量：小修直接定位 → 改 → 轻量证据；轻功能不强制 Task；普通标准功能使用内部短计划；跨资源、多页面协作、并行或高风险时才落 Task。
+这些规则已改为按事实触发：资源关系不清时 map，页面改动检查入口和 HTML，数据/API/服务只读取对应契约，运行和布局改变才做浏览器验证。Task 和 Story 仅在需要产品决策沉淀或跨资源交接时使用。
 
 ---
 
@@ -340,71 +351,9 @@ python .claude/skills/draftgo/scripts/draftgo_push.py db_meta [meta_id]
 
 更推荐的用法：在 AI 工具里说「初始化 draftgo 项目」或「同步页面 123」，skill 会自动触发对应脚本。
 
-## v1.4.0 升级要点（Story System — 系统灵魂档案）
-
-CLI v1.4.0 引入 **Story System**，解决 Vibe Coding 时代最大的痛点：每次新对话 AI 都不知道"这个系统为什么存在、不做什么、做过什么取舍"。
-
-**核心机制：Story Context / Gate**
-
-开发任务开始时，AI 按任务级别处理 `.draftgo/story.yaml`：
-- 小修 → 不强制触发 Story
-- 功能 → 存在则静默加载，不存在不阻塞开发，收尾提醒补 Story
-- 高风险 → 不存在则暂存请求，进入 Story 构建流程（对话式采集，不是填表）；存在则静默加载并做冲突检测
-
-**Story 文件结构（三层）：**
-
-```yaml
-# .draftgo/story.yaml
-meta:
-  version: 1
-  created: 2026-05-17
-  last_touched: 2026-05-17
-  maturity: seed   # seed | growing | stable
-
-identity:
-  what: "一句话讲清这是什么"
-  why: "解决什么痛点，给谁用"
-  not:
-    - "不是 XX"
-    - "不变成 YY"
-
-design:
-  overview: "核心流转逻辑：用户从哪进来 → 经过什么 → 得到什么价值"
-  modules:
-    - name: "模块名"
-      role: "这个模块在系统里的定位（核心/辅助/基座）"
-decisions:
-  - id: D001
-    date: 2026-05-17
-    chose: "选了什么"
-    over: "拒绝了什么"
-    because: "原因"
-    status: active
-
-now:
-  focus: "当前在做什么"
-  next: "下一步方向"
-  open_questions:
-    - "悬而未决的事"
-```
-
-**运行时行为：**
-- **冲突检测**：当开发请求与 Story 的 `identity.not` 或 active 决策矛盾时，AI 会显式摊牌，给出"想法变了 / 双轨并行 / 只是特例"三个选项
-- **主动沉淀**：检测到方向性决策时，AI 主动提议记入 decisions
-- **now 更新**：对话结束时提议更新 focus/next
-
-**开发流程升级为分级门禁：**
-
-```
-小修：直接定位 → 改 → 轻量证据
-轻功能：范围复述 → 直接做 → 凭证据闭环
-标准功能：轻量确认 → 内部短计划 → 执行闭环
-高风险：Story → 完整确认 → 计划 → 人工确认 / 回读验证
-```
-
-**注意：** `.draftgo/story.yaml` 不在 `draftgo init` 中创建。它由 AI 在首次开发对话时通过与开发者交流后生成，确保内容有意义而不是空模板。
+## Story
 
-完整规范见各 AI 工具自身 skill 目录下的 `story/SKILL.md`，例如 `.claude/skills/draftgo/story/SKILL.md`。
+`.draftgo/story.yaml` 用于沉淀会影响后续取舍的产品定位与决策。已有 Story 且请求触及定位或既有决策时读取；用户要求建立、更新或冲突检查时调用 `story/SKILL.md`。
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.1",
+  "version": "3.0.33",
   "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"
@@ -13,6 +13,9 @@
     "bin/",
     "src/",
     "resources/",
+    "!resources/**/__pycache__/**",
+    "!resources/**/*.py[cod]",
+    "LICENSE",
     "README.md"
   ],
   "keywords": [
@@ -28,11 +31,7 @@
     "gemini",
     "kiro"
   ],
-  "author": {
-    "name": "draftgo",
-    "email": "cabinai@163.com",
-    "url": "https://github.com/draftgo"
-  },
+  "author": "draftgo <cabinai@163.com> (https://github.com/draftgo)",
   "license": "MIT",
   "homepage": "https://github.com/draftgo/draftgo-cli#readme",
   "bugs": {
@@ -43,6 +42,20 @@
     "url": "git+https://github.com/draftgo/draftgo-cli.git"
   },
   "scripts": {
-    "test": "node tests/unit.js"
-  }
+    "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:unit": "node tests/unit.js",
+    "test:e2e": "node tests/e2e.js"
+  },
+  "dependencies": {
+    "@grpc/grpc-js": "1.14.1",
+    "parse5": "6.0.1",
+    "playwright-core": "1.61.1"
+  },
+  "directories": {
+    "test": "tests"
+  },
+  "devDependencies": {}
 }

package/resources/skill/SKILL.md

@@ -1,104 +1,77 @@
----
+---
 name: draftgo
-description: Use this skill when the user is developing, maintaining, or debugging a DraftGo-based application. Activates for tasks involving DraftGo pages, navigation, API calls, roles, DB meta, or any DraftGo-specific development work. ALSO activates when user says "推送", "push", "同步", "sync", "推送到云端", "同步到云端", "push to server", "上传页面", "上传导航", "push pages", "push nav", "push db_meta" — route to /draftgo push skill immediately, do NOT attempt manual API calls.
-version: 2.0.0
+description: Use this skill when developing, maintaining, debugging, synchronizing, or delivering a DraftGo-based application, including DraftGo pages, navigation, dynamic DB, base APIs, Go custom services, AIHub, knowledge bases, Skill/MCP assets, roles, and local resources.
 ---
 
 # DraftGo 开发助手
 
-> 默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。优先交付真实落地闭环；禁止假数据/静态卡片/伪功能充当完成。若本地 Agent 存在前端 UI Skills，前端开发时优先调用。
-
-## 开发前置检查
+## 执行方法
 
-```bash
-# 确认已初始化
-test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
-```
+1. **建立资源图**：从用户路径列出角色、入口、页面、操作、数据、服务、运营维护和验证证据，并标记资源间的依赖。
+2. **确定共享契约**：从当前 `db_meta`、底座 API、自定义服务、权限、路由和导航中确认被多个资源共同依赖的契约，再展开依赖它们的实现。
+3. **并行独立资源**：按依赖关系划分 wave。独立页面、管理页、文档和服务并行处理；共享 schema、导航、HTML 文件或调用链按依赖顺序处理。每个工作单元携带资源范围和验证方式，交付动作由汇总阶段统一执行。具体字段见 `references/parallel.md`。
+4. **汇总接线**：连接入口、页面跳转、真实数据读写、角色可见性、加载/空/错误/成功状态和运营维护路径，随后回放关键用户路径。
+5. **验证与交付**：按资源类型取得证据。完成本地验证后，根据用户交付意图或项目自动同步配置执行 `push`、`deploy` 或 `auto-push`。
 
-服务器地址和 Token 从 `.draftgo/config.json` 读取。
+## CLI 与场景路由
 
-## 命令路由
+调用 `draftgo` CLI 完成工具动作；`scripts/` 下的脚本是 CLI 内部实现，不作为 Agent 的调用入口。
 
-| 用户意图 | 路由 |
+| 场景 | DraftGo 动作 |
 |---|---|
-| 初始化项目 / `/draftgo init` | 调用 `/draftgo init` Skill |
-| 从云端拉取 / `/draftgo pull` | 调用 `/draftgo pull` Skill |
-| 推送到云端 / `/draftgo push` | 调用 `/draftgo push` Skill |
-| 构建 / 查看 Story / `/draftgo story` | 调用 `{{SKILL_DIR}}/story/SKILL.md` |
-| 查看资源地图 / `draftgo map` | 直接运行 CLI |
-| 闭环体检 / `draftgo check` | 直接运行 CLI |
-| 任何开发 / 修改 / 新建 / 修复 / 重构任务 | ↓ 见开发任务路由 |
-
-## 开发任务路由（按任务规模读取）
-
-**第一步：必读** → `{{SKILL_DIR}}/rules/dev-workflow.md`（分级：小修 / 轻功能 / 标准功能 / 高风险）
-
-| 任务类型 | 读取 |
+| 查看 Skill 安装状态或支持目标 | 运行 `draftgo status`；需要目标列表时运行 `draftgo list-targets`。 |
+| 安装、完全更新或移除 Skill | 分别运行 `draftgo init [target...]`、`draftgo update [target...]`、`draftgo uninstall <target\|all>`。 |
+| 连接已有基座 | 运行 `draftgo connect`，写入项目连接并拉取初始上下文。 |
+| 首次建立本地 Docker 基座 | 运行 `draftgo local setup`；后续使用 `draftgo local start\|stop\|logs\|status` 管理。兼容命令：`draftgo local-dev`、`draftgo local up`、`draftgo local down`。 |
+| 陌生项目、跨资源或入口不清 | 运行 `draftgo map`，再读取相关 index 和资源文件。 |
+| 本地资源缺失、过期或需要云端版本 | 使用 `pull/SKILL.md`，运行 `draftgo pull [type] [id...]`。 |
+| 新建资源 | 在对应 index 中登记不带 `id` 的完整条目并创建其引用文件；运行 `draftgo check` 后，通过 `draftgo push <type>` 创建并回读写回的 `id` 和文件路径。 |
+| 删除资源 | 确认目标 `id` 和引用后运行 `draftgo delete <type> <id>`；该命令同时删除云端资源和本地登记，随后重新运行 `map` 与 `check`。 |
+| 页面、导航、交互或布局 | 读取 `references/frontend.md`；页面运行和布局证据使用 `draftgo verify-ui <url> --mobile-check auto`。 |
+| 页面或导航 HTML | 运行 `draftgo check`，验证入口、HTML 解析和资源登记；语法异常读取 `references/debugging-syntax.md`。 |
+| 动态 DB、filters 或 order_by | 先读对应 `db_meta` schema 和 `references/data.md`。 |
+| DraftGo 底座 API | 运行 `draftgo api <keyword>`，确认请求字段、响应结构和鉴权。 |
+| 自定义服务 | 读取 `references/custom-services.md`；其中包含 AIHub、知识库、Memory、Skill/MCP 的完整 Go SDK；端点从 `slug + app.Route` 推导为 `/api/x/<slug><route-path>`。 |
+| App 对象方法 | 读取 `references/app-api.md`。 |
+| AI Agent（配置、调用、工具/子智能体/记忆/持续对话、观测） | 读取 `references/aihub.md`；页面对话 UI、协议、事件与扩展读取 `references/chat-sdk.md`；App 与旧兼容门面见 `references/app-api.md`。 |
+| 平台架构、能力边界或安全限制 | 读取 `references/architecture.md`、`references/modules.md` 或 `references/security.md`。 |
+| 同步已确认的本地改动 | 使用 `push/SKILL.md`，运行 `draftgo push <type> [id...]`。 |
+| 交付前需要结构检查或预演 | 运行 `draftgo deploy [type] [id...] --delivery local\|preview\|deploy`。 |
+| 项目明确启用自动同步 | 运行 `draftgo auto-push [type] [id...]`；批量资源使用 `--batch`，未启用 `config.auto_push` 时命令只检查并跳过推送。 |
+| 项目已有 `.draftgo/story.yaml`，且请求可能改变产品定位或既有决定 | 读取并检查冲突；需要新建或维护 Story 时调用 `story/SKILL.md`。 |
+
+## DraftGo 契约
+
+- **分页**：完整候选集、配置、资源或导出数据同时省略 `page` 和 `page_size`；真实分页列表同时传入 `page` 与 `page_size`。
+- **响应信封**：调用基座 API 时先检查 `res.code !== 200`，再读取 `res.data`。
+- **时间**：用户展示按用户/浏览器时区；存储、统计、定时和自然日边界按 `system_timezone` 计算。
+- **数据 schema**：字段名、类型、必填、searchable 和权限以 `.draftgo/db_meta/index.json` 为准；筛选和排序前确认字段与操作符兼容。
+- **自定义服务**：使用 `package main`、`Register(app *sdk.App)` 和 `func handler(draftgo *sdk.Context) (any, error)`；普通身份使用 `draftgo.Auth.CurrentUser()`，需要管理能力时逐次显式调用 `draftgo.Admin.*`。AI 能力使用 `draftgo.AIHub`、`draftgo.Knowledge`、`draftgo.Memory`；Route 权限和脚本管理权限是两层独立控制。
+- **系统资源**：登录、设置、权限、用户和系统配置属于基座资源；修改前确认影响范围并保留原有系统能力。
+
+## 资源验证
+
+| 资源 | 证据 |
 |---|---|
-| 所有开发任务 | `rules/dev-workflow.md` — 分级与执行流程 |
-| 前端页面开发 | `rules/frontend.md` — 前端规范（小修可只读相关段落） |
-| 页面功能不执行 / 报错 | `rules/debugging-syntax.md` — 排错指南（必读） |
-| 标准功能 / 高风险并行任务 | `rules/parallel.md` — 并行协议 |
-| 不了解项目结构 | 先运行 `draftgo map` |
-| 标准功能 / 高风险 · 意图模糊 | `practices/dev-declaration.md` — 开发声明协议 |
-
-## 快速决策树
-
-```
-要开发什么？
-├── 页面 / 导航 / 交互      → 读 rules/frontend.md
-├── 数据结构 / 动态 DB      → 读 specs/data.md
-├── API 速查               → quickref/api-endpoints.md
-├── App 方法忘了            → quickref/app-api.md
-├── dg-* 组件用法           → quickref/dg-components.md
-├── 了解平台架构            → core/architecture.md
-├── 选择开发方案            → core/modules.md
-└── 查开发禁区             → specs/security.md
-```
+| 页面、导航、新资源 | 运行 `draftgo check`，并确认入口引用。 |
+| 页面运行、交互或布局 | 运行 `draftgo verify-ui <url>`。 |
+| 基座 API、动态 DB | 真实请求或回读关键状态、字段和错误处理。 |
+| 自定义服务 | 调用目标 Route 或无副作用健康端点，确认状态码与响应；涉及管理员调用时确认审计。 |
+| 删除资源 | 重新运行 `draftgo map` 与 `draftgo check`，确认入口、引用和本地文件已闭合。 |
 
-## 连接信息
-
-- 存储于 `.draftgo/config.json`（已加入 .gitignore）
-- 运行 `/draftgo init` 时写入
-
-## 核心原则（硬性）
-
-- **开发分级**：任何任务先读 `rules/dev-workflow.md` 分级，再执行
-- **真实闭环**：不用假数据/伪交互充当完成；无法实现则停止并说明
-- **入口绑定**：新增页面必须绑定导航/首页/菜单至少一处
-- **dg-* = shadcn**：`dg-*` 是 shadcn 的 HTML 协议表达，不是其他 UI 库
-- **Story 冲突**：发现与 `.draftgo/story.yaml` 冲突必须显式提示，不可静默执行
-- **changelog**：影响可见功能/跨资源/已 push 时写入 `.draftgo/changelog.md`
-
-## 本地数据目录
-
-| 目录 | 内容 |
-|---|---|
-| `.draftgo/pages/` | index.json + .html 文件 |
-| `.draftgo/navigations/` | index.json + .html 文件 |
-| `.draftgo/db_meta/` | index.json（含 schema/permission） |
-| `.draftgo/custom_scripts/` | index.json + 脚本文件 |
-| `.draftgo/external_apis/` | index.json（auth_config 已脱敏） |
-| `.draftgo/aihub/` | index.json |
-| `.draftgo/docs/articles/` | index.json + .md 文件 |
-| `.draftgo/system_config/` | index.json |
-| `.draftgo/changelog.md` | 更新日志 |
-| `.draftgo/lessons/` | 开发经验（YYYY-MM-DD-主题.md） |
-| `.draftgo/Task/` | 任务文档（仅跨资源/高风险任务） |
+`draftgo check` 覆盖页面入口、页面/导航 HTML 解析和本地资源登记；运行证据由对应资源的验证动作提供。
 
-## 文档索引
+## 本地资源
 
-| 文档 | 读取时机 |
+| 路径 | 内容 |
 |---|---|
-| `core/architecture.md` | 进入陌生项目·理解平台机制（3分钟） |
-| `core/modules.md` | 评估功能可行性·选择开发路径 |
-| `specs/runtime.md` | 处理 token/路由/事件/全局层问题 |
-| `specs/data.md` | 动态 DB·filters·db_meta 操作 |
-| `specs/ui-protocol.md` | dg-* 完整映射表 |
-| `specs/security.md` | 开发禁区速查 |
-| `practices/dev-declaration.md` | 标准功能/高风险任务开始前 |
-| `practices/best-practices.md` | 开发决策·Code Review |
-| `practices/anti-patterns.md` | 检查反模式 |
-| `quickref/app-api.md` | App API 速查 |
-| `quickref/api-endpoints.md` | 后端端点速查 |
-| `quickref/dg-components.md` | dg-* 组件代码示例 |
+| `.draftgo/pages/` | 页面索引与 HTML |
+| `.draftgo/navigations/` | 导航索引与 HTML |
+| `.draftgo/db_meta/` | 数据 schema 与权限 |
+| `.draftgo/custom_scripts/` | 自定义服务元数据与 Go 代码 |
+| `.draftgo/aihub/` | AIHub 资源 |
+| `.draftgo/docs/articles/` | 文档元数据与 HTML |
+| `.draftgo/doc_categories/` | 文档分类 |
+| `.draftgo/system_config/` | 系统配置 |
+| `.draftgo/roles/`、`.draftgo/users/` | 角色与用户 |
+| `.draftgo/story.yaml` | 产品身份、设计和长期决策 |