draftgo-cli 2.0.3 → 2.0.9

package/README.md

@@ -6,9 +6,29 @@
 
 ## 前置条件
 
-- Node.js 14+（运行 CLI）
+- Node.js >=20.19（运行 CLI）
 - Python 3.9+（运行 DraftGo init/sync 脚本；CLI 本身不需要）
 
+## DraftGo Next v3 基线
+
+DraftGo Next 前端基线为 React + Vite + shadcn/ui + Tailwind。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 已把这条规则写入前端规范。
+
+已存在的 `draftgo init/update/status/doctor/map/check/connect/local-dev` 保持兼容；首批工作台命令如下：
+
+| 命令 | 说明 |
+|---|---|
+| `draftgo local up` | 启动 `draftgo local-dev` 生成的 `.draftgo/docker/docker-compose.yaml` 本地栈。 |
+| `draftgo local down` | 停止本地栈。 |
+| `draftgo local logs` | 查看本地栈日志，默认跟随 `app` 服务。 |
+| `draftgo local status` | 查看本地栈容器状态。 |
+| `draftgo dev` | 运行当前项目 `package.json` 中的 `scripts.dev`。 |
+| `draftgo build` | 运行当前项目 `package.json` 中的 `scripts.build`。 |
+| `draftgo check` | 本地资源闭环检查，辅助发现入口绑定、缺文件、重复路由和疑似 mock 风险。 |
+| `draftgo pull` | 包装随 skill 分发的 `draftgo_pull.py`，默认 `--all` 拉取资源。 |
+| `draftgo push` | 包装随 skill 分发的 `draftgo_push.py`，推送页面、导航、DB meta 等资源。 |
+
 ## 安装
 
 ```bash
@@ -39,6 +59,8 @@ draftgo init all                         # 所有支持的工具
 | `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 list-targets` | 列出支持的 AI 工具名。 |
 | `draftgo --version` | 打印 CLI 版本。 |
 | `draftgo --help` | 查看帮助。 |
@@ -49,9 +71,23 @@ draftgo init all                         # 所有支持的工具
 - `--force`：`init/update` 时强制覆盖已存在的 AI 工具 skill 目录。
 - `--skip-update-check`：`update` 时不去 npm 查最新版，直接用当前 CLI 执行。
 - `--purge`：`uninstall` 时连 `.draftgo/`（含 config / 日志 / 本地缓存）一起删。
+- `--output json`：`map/check` 输出机器可读 JSON。
+- `--strict`：`check` 将提醒项也视为失败。
 
 可以通过环境变量 `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 条目会包含常用配置摘要：
+
+- `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 输出。
+
+`draftgo check --output json` 会输出 `{ map, errors, warnings }`，适合 CI 或开发收尾时作为轻量证据。`--strict` 会把 warnings 也视为失败。
+
 ## 更新
 
 ```bash
@@ -76,6 +112,49 @@ CLI 随包分发的 DraftGo skill 会同步基座 API 约定。集合写入统
 
 动态 DB SDK 也提供 `sdk.db.create_many(...)` 与 `sdk.db.update_many(...)`，用于脚本内批量写入。
 
+AIHub Agent 用户选模型约定：
+
+- 管理端在 Agent 的 `data.spec.model_selection.user_selectable=true` 后，页面可调用 `DraftGoAI.getSelectableModels(agentId)` 获取 `{ user_selectable, models }`。
+- `models` 是该 Agent 的主模型 + 备用模型白名单，不是供应商全量模型列表。
+- 调用 `DraftGoAI.chat(...)` 或 `DraftGoAI.images(...)` 时，可在 `options.model` 中传入用户选择的模型；后端会继续按 Agent 白名单校验。
+
+AIHub Agent JSON 输出约定：
+
+- Agent 的结构化输出写在 `data.spec.output_format` 中；`mode="json"` 表示要求 JSON 输出。
+- `data.spec.output_format.json.strategy` 支持 `auto`、`native`、`prompt`：`auto` 会优先使用模型资产的 `supports_response_format/supports_json_schema` 诊断结果，必要时降级为提示词约束。
+- `data.spec.output_format.json.schema` 可传 JSON Schema；后端会尽量构造 OpenAI 兼容 `response_format`，流式响应结束时会追加 `json.validation` 事件。
+- 模型资产可通过 `POST /api/aihub/{id}/test-response-format` 探测并写回 `supports_response_format` 与 `supports_json_schema`。
+
+示例：
+
+```json
+{
+  "data": {
+    "schema_version": "agent.v3",
+    "spec": {
+      "model_id": 1,
+      "model": "gpt-4.1",
+      "output_format": {
+        "mode": "json",
+        "json": {
+          "strategy": "auto",
+          "schema_name": "summary",
+          "schema": {
+            "type": "object",
+            "properties": {
+              "title": { "type": "string" },
+              "tags": { "type": "array", "items": { "type": "string" } }
+            },
+            "required": ["title", "tags"],
+            "additionalProperties": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## 自动识别的依据
 
 | AI 工具 | 探测信号（任一命中即视为在用） |
@@ -128,9 +207,9 @@ CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/
 **分级流程**：
 
 ```
-小修：直接定位 → 改 → check → push
-轻功能：范围复述 → 直接做 → 主路径验证 → push
-标准功能：轻量确认 → Task → TDR
+小修：直接定位 → 改 → 轻量证据
+轻功能：范围复述 → 直接做 → 凭证据闭环
+标准功能：轻量确认 → 内部短计划 → 执行闭环
 高风险：完整 Story / 计划 / 验证 / 人工确认
 ```
 
@@ -141,7 +220,7 @@ CLI v1.2.0 在 skill 包里追加了一套**分级开发流程规范**（`rules/
 - `.draftgo/lessons/` 统一记录开发过程中的阻碍、踩坑、框架运行时问题、基座能力局限和可复用经验。
 - 文件按 `YYYY-MM-DD-主题关键词.md` 命名，便于后续回顾和沉淀为开发规范。
 
-**前端审美方向**：现代工艺 + 艺术风 + 用户体验三个方向，不立细则只立锚点（参考 Linear / Vercel / Apple HIG / Notion）。
+**前端 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`。
 
@@ -156,7 +235,7 @@ CLI v2.0.3 补充操作型页面的空间模型，重点解决后台管理 / 表
 - **工作台布局原则**：后台管理、表格、列表、审批、配置、内容维护等操作型页面，优先让页面根容器占满可用视口 / iframe 内容区。
 - **稳定控制区**：顶部筛选、搜索、标题操作区保持稳定高度，底部分页、批量操作栏、保存栏等流程控制区保持在工作区底部或稳定位置。
 - **数据区承接剩余空间**：主体数据区使用 `flex:1; min-height:0; overflow:auto` 等结构承接剩余空间，数据少时保留工作区空白，数据多时优先让数据区内部滚动。
-- **数据表规则同步**：`data-table.md` 新增工作台空间模型和 CSS 骨架参考，避免分页跟随 1-2 条数据上浮。
+- **工作台结构同步**：`rules/frontend.md` 补充操作型页面的空间方法，基座对应文档为 `docs/frontend/rules.md`，避免分页跟随 1-2 条数据上浮。
 
 ---
 
@@ -197,29 +276,29 @@ CLI v2.0.0 删除了内置 `resources/skill/reference/` 基座参考副本，进
 
 ## v1.6.2 升级要点（开发效率轻量化）
 
-CLI v1.6.2 进一步降低开发流程摩擦：保留真实功能闭环、页面绑定、平台禁区和推送验证这些硬约束，同时让小修和轻功能更快进入实现。
+CLI v1.6.2 进一步降低开发流程摩擦：保留真实落地闭环、页面绑定和平台禁区，同时让小修和轻功能更快进入实现。
 
 **核心变化：**
 
 - **小修渐进读取**：小修优先只读目标资源和最小必要规则，不再默认展开完整规则链路。
-- **新增轻功能档**：简单页面能力、单入口交互、小型数据联动可走“范围复述 → 直接做 → 主路径验证 → push”，不强制创建 Task。
+- **新增轻功能档**：简单页面能力、单入口交互、小型数据联动可走“范围复述 → 直接做 → 凭证据闭环”，不强制创建 Task。
 - **计划字段按需**：`depends / resource_lock / wave` 只在多任务、多资源冲突或准备并行时强制；单人串行小计划不再为字段服务。
 - **并行按收益启用**：只有任务数足够、边界清晰、资源不冲突且并行收益大于协调成本时才启用并行。
 - **取消 80 行硬限制**：改为“复杂或高风险代码分段实现并验证”，避免机械分批拖慢前端开发。
-- **验证按等级分层**：小修验证改动点，轻功能验证入口和主路径，标准功能 / 高风险再完整覆盖四态、数据、跳转和影响范围。
+- **验证按影响分层**：小修验证改动点，轻功能验证入口引用和主路径；标准功能按实际影响覆盖四态、数据、跳转和同步证据。
 
 ---
 
-## v1.6.1 升级要点（前端规则去模板化）
+## v1.6.1 升级要点（前端规则收敛）
 
-CLI v1.6.1 继续优化开发效果：减少前端规则中过细的“适合 / 不适合”和固定模板描述，让 AI 在满足平台硬约束的前提下，更主动地根据页面目标、业务复杂度和用户体验做设计判断。
+CLI v1.6.1 继续优化开发效果：减少前端规则中过细的“适合 / 不适合”和固定模板描述，让 AI 在满足平台硬约束的前提下，根据页面目标和业务复杂度做实现判断。
 
 **核心变化：**
 
-- **GSAP 优先体验原则**：开发前端页面时优先考虑使用 GSAP 提升体验，不再用固定场景清单限制是否引入。
-- **数据表规则改为参考**：数据列表 / 表格规范从“必须按模板实现”调整为参考指南，避免无差别套搜索、高级筛选、列配置、分页。
-- **空态与圆角更灵活**：空态保留稳定布局要求，写法不再唯一；圆角默认保持系统一致，但允许按品牌感、卡片层级和营销视觉适度放开。
-- **审美方向更开放**：保留现代工艺、艺术风、用户体验三轴，但减少反例式限制，让 AI 可以根据项目气质探索更鲜明的视觉语言。
+- **前端规则收敛**：DraftGo 规则关注本地资源、运行时 API、入口绑定、真实数据和验证方法。
+- **GSAP 资源改为按需使用**：本地 GSAP 资源仍可用，但 CLI 不再给出使用场景判断。
+- **表格规则去模板化**：不再要求固定搜索、高级筛选、列配置、分页结构，具体界面由 Agent 和本地 UI Skills 判断。
+- **状态规则保留方法约束**：空态、加载态、错误态、成功态必须存在，但具体呈现不由 CLI 指定。
 
 ---
 
@@ -233,9 +312,9 @@ CLI v1.6.0 强化了 skill 对“开发任务规划”的判断力，重点解
 - **页面默认完整功能**：用户说“做一个页面”时，默认按可真实使用的页面功能处理；只有明确说“静态 / 纯页面 / demo / 先看效果”时，才按静态页处理。
 - **用户路径链路**：功能规划从“用户打开官网 / 系统入口 → 看见入口 → 点击进入 → 操作 → 反馈 → 后台维护 → 前台展示更新”这一整条链路倒推页面、导航、数据和权限。
 - **新增页面绑定**：创建页面后必须绑定到导航栏、首页入口、后台菜单或相关页面按钮之一；只创建页面文件、无法从正常路径点击进入，不算完成。
-- **真实功能闭环**：按钮、表单、搜索、筛选、分页、保存、删除、发布等交互默认要真实有效；需要可维护内容时，主动规划后台管理和同一份真实数据。
+- **真实落地闭环**：按钮、表单、搜索、筛选、分页、保存、删除、发布等交互默认要真实有效；需要可维护内容时，优先规划后台管理和同一份真实数据，追求高可用。
 
-这些规则保持轻量：小修仍然直接定位 → 改 → check → push；轻功能不强制 Task；标准功能只做必要确认；高风险任务才进入完整 Story / 人工确认流程。
+这些规则保持轻量：小修直接定位 → 改 → 轻量证据；轻功能不强制 Task；普通标准功能使用内部短计划；跨资源、多页面协作、并行或高风险时才落 Task。
 
 ---
 
@@ -288,12 +367,6 @@ design:
   modules:
     - name: "模块名"
       role: "这个模块在系统里的定位（核心/辅助/基座）"
-  style:
-    personality: "系统说话像谁"
-    keywords: ["设计关键词"]
-    do: ["正面指引"]
-    dont: ["禁区"]
-
 decisions:
   - id: D001
     date: 2026-05-17
@@ -317,10 +390,10 @@ now:
 **开发流程升级为分级门禁：**
 
 ```
-小修：直接定位 → 改 → check → push
-轻功能：范围复述 → 直接做 → 主路径验证 → 凭证据闭环
-标准功能：轻量确认 → Task → TDR → 凭证据闭环
-高风险：Story → 完整确认 → 计划 → TDR → 人工确认 / 回读验证
+小修：直接定位 → 改 → 轻量证据
+轻功能：范围复述 → 直接做 → 凭证据闭环
+标准功能：轻量确认 → 内部短计划 → 执行闭环
+高风险：Story → 完整确认 → 计划 → 人工确认 / 回读验证
 ```
 
 **注意：** `.draftgo/story.yaml` 不在 `draftgo init` 中创建。它由 AI 在首次开发对话时通过与开发者交流后生成，确保内容有意义而不是空模板。

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "draftgo-cli",
-  "version": "2.0.3",
+  "version": "2.0.9",
   "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"
   },
   "main": "src/index.js",
   "engines": {
-    "node": ">=14"
+    "node": ">=20.19"
   },
   "files": [
     "bin/",