draftgo-cli 3.0.1 → 3.0.29

package/resources/skill/specs/runtime.md

@@ -89,10 +89,40 @@ const orderId = query.orderId;  // "42"
 
 | config_key | 用途 |
 |---|---|
+| `frontend_global_enabled` | 前端全局层总开关 |
+| `frontend_global_safe_mode` | 全局层安全模式；开启后仅保留平台内置反馈能力，不执行自定义全局注入 |
 | `frontend_global_head_html` | 注入壳层 head |
 | `frontend_global_body_html` | 注入壳层 body 末尾 |
 | `frontend_global_css` / `_js` | 壳层全局 CSS/JS |
 | `frontend_global_iframe_head_html` | 注入每个业务页面 iframe head |
 | `frontend_global_widget_html/css/js` | 全局挂件层 |
+| `frontend_global_toast_position` | Toast 位置：`top-center` / `top-right` / `top-left` / `bottom-center` / `bottom-right` / `bottom-left` / `center` |
+| `frontend_global_toast_scale` | Toast 大小比例，范围 `0.5-3`，文字、图标、间距、圆角等同比例缩放 |
+| `frontend_global_toast_opacity` | Toast 背景透明度，范围 `0-100`，只影响背景，不影响文字和按钮 |
+| `frontend_global_toast_duration_success` | 成功 Toast 默认停留时间，存储单位：毫秒 |
+| `frontend_global_toast_duration_error` | 错误 Toast 默认停留时间，存储单位：毫秒 |
+| `frontend_global_toast_duration_warning` | 警告 Toast 默认停留时间，存储单位：毫秒 |
+| `frontend_global_toast_duration_info` | 信息 Toast 默认停留时间，存储单位：毫秒 |
+| `frontend_global_toast_css` | Toast 自定义 CSS，只建议调整视觉，不要破坏 `.dg-toast` 基础结构 |
+| `frontend_global_scrollbar_color_mode` | 滚动条颜色模式：`theme` 跟随系统主题 / `custom` 自定义颜色 |
+| `frontend_global_scrollbar_color` | 自定义滚动条颜色，建议使用 `#RRGGBB` |
+| `frontend_global_scrollbar_buttons` | 是否显示滚动条两端按钮；不支持的浏览器会自动退化 |
+| `frontend_global_scrollbar_opacity` | 滚动条滑块透明度，范围 `0-100` |
+| `frontend_global_scrollbar_radius` | 滚动条圆角，单位 px |
+| `frontend_global_scrollbar_width` | 滚动条宽度，单位 px |
 
 规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**
+
+### 修改和推送方法
+
+本地修改来自 `.draftgo/system_config/index.json`。修改前先执行 `/draftgo pull system_config` 获取最新值，改完后执行：
+
+```bash
+python {{SKILL_SCRIPTS}}/draftgo_push.py system_config frontend_global_toast_opacity
+```
+
+也可以通过 skill 命令使用 `/draftgo push system_config frontend_global_toast_opacity`。
+
+前端全局层是系统默认配置。通过 API 或脚本更新现有全局配置时，只发送 `config_value`；不要带 `description`、`category`、`value_type`、`status` 等元信息，否则旧基座或旧索引容易触发“系统默认字段不允许修改字段描述/分类/状态”。`draftgo_push.py system_config` 已对 `frontend_global_*` 自动只推值。
+
+页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中 `错误 Toast 时长(s) = 4.5`，本地索引应写 `frontend_global_toast_duration_error.config_value = 4500`。

package/resources/skill/specs/security.md

@@ -47,9 +47,7 @@ read_when: 开发前检查合规性时 · Code Review 时
 
 | ❌ 禁止 | ✅ 替代 |
 |---|---|
-| 把 React/TSX 版 shadcn 组件写进数据库 HTML | 用对应 `dg-*` 标签 |
-| 把 `dg-*` 当 daisyUI / Bootstrap / Ant Design | `dg-*` 只能是 shadcn 的 HTML 协议形态 |
-| 硬编码 hex / rgb / rgba 颜色 | 用 `var(--dg-*)` 语义 token |
+| 硬编码 hex / rgb / rgba 颜色 | 优先用系统主题 `var(--dg-*)` 语义 token；品牌/图表/用户指定配色必须同时适配浅色与深色 |
 | 在页面内读 `localStorage.dg_theme` | `App.theme` |
 
 ---
@@ -66,6 +64,8 @@ read_when: 开发前检查合规性时 · Code Review 时
 
 ## 颜色 Token 参考
 
+默认优先采用系统主题配色：页面直接引用 `var(--dg-*)`，跟随壳层当前浅色 / 深色模式。只有页面不搭配、品牌要求、用户明确指定或图表多系列等场景才允许自主配色；自主配色必须提供浅色与深色两套变量或 `[data-theme="light"]` / `[data-theme="dark"]` 覆盖，并满足 WCAG AA 对比度。
+
 | Token | 用途 |
 |---|---|
 | `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` | 背景层级 |

package/resources/skill/specs/ui-protocol.md

@@ -1,68 +1,99 @@
 ---
-read_when: 开发数据库页面时需要 dg-* 组件 · 了解 shadcn 映射关系时
+read_when: 开发数据库页面时需要真实 shadcn/Radix 组件能力 · 了解 data-ui bridge 协议时
 ---
 
-# dg-* 完整映射表
+# shadcn Page Runtime Bridge 协议
 
 ## 核心认知
 
-```
-dg-* ≠ 自研组件库
-dg-* = shadcn/ui 在数据库 HTML 页面里的协议化表达
-```
+数据库页面不进入 Vite/React 编译链，不能写 TSX、React import 或 shadcn 组件源码。
 
-数据库页面不进入 Vite/React 编译链，不能写 TSX；改用 `dg-*` 标签，runtime 解析并渲染对应 shadcn 语义。
+DraftGo 页面默认写普通 HTML + Tailwind CSS + 页面级 CSS。只有显式带 `data-ui` 的节点会交给 shadcn page runtime bridge 接管，普通 `<table>`、`<button>`、自定义 HTML 不会被强制改造成 shadcn。
 
----
+```
+普通 HTML / Tailwind / CSS  → 页面作者完全控制
+data-ui 节点               → DraftGo bridge 挂载真实 shadcn/Radix
+```
 
-## shadcn → dg-* 完整映射
+## 当前稳定协议
 
-| shadcn 组件 | dg-* 标签 | 说明 |
+| 能力 | HTML 写法 | 底层 |
 |---|---|---|
-| Button | `dg-button` | variant/size/disabled 属性对齐 |
-| Card | `dg-card` + `dg-card-header/title/description/content/footer` | |
-| Badge | `dg-badge` | variant: default/secondary/destructive/outline |
-| Skeleton | `dg-skeleton` | 骨架屏 |
-| Input | `dg-input` | type/placeholder/value/disabled |
-| Textarea | `dg-textarea` | |
-| Select | `dg-select` + `dg-select-item` | |
-| Checkbox | `dg-checkbox` | |
-| Switch | `dg-switch` | |
-| RadioGroup | `dg-radio-group` + `dg-radio-item` | |
-| Form | `dg-form` + `dg-form-item` + `dg-form-message` | |
-| Table | `dg-table` | source 属性拉取数据，columns via data-dg-props |
-| Tabs | `dg-tabs` + `dg-tabs-list/trigger/content` | default-value 属性 |
-| Dialog | `dg-dialog` + `dg-dialog-trigger/content/header/title/footer` | |
-| Sheet | `dg-sheet` + `dg-sheet-trigger/content/header/title` | side: right/left/top/bottom |
-| DropdownMenu | `dg-dropdown-menu` + `dg-dropdown-menu-trigger/content/item/separator` | |
-| Tooltip | `dg-tooltip` | content 属性 |
-| Popover | `dg-popover` + `dg-popover-trigger/content` | |
-| Alert | `dg-alert` + `dg-alert-title/description` | variant: default/destructive |
-| Progress | `dg-progress` | value/max 属性 |
-| Separator | `dg-separator` | orientation: horizontal/vertical |
-| ScrollArea | `dg-scroll-area` | |
-| Avatar | `dg-avatar` + `dg-avatar-image/fallback` | |
+| Button | `<button data-ui="button">` | shadcn Button |
+| Static Table | `<div data-ui="table"><table>...</table></div>` | shadcn Table 样式增强 |
+| DropdownMenu | `data-ui="dropdown-menu-trigger/content/item/separator"` | Radix DropdownMenu |
+| DataTable | `<div data-ui="data-table" data-source="pages">` | DraftGo 数据源 + shadcn Table |
+
+## 示例
+
+```html
+<div data-ui="table">
+  <table>
+    <thead>
+      <tr>
+        <th>Product</th>
+        <th>Price</th>
+        <th data-align="right">Actions</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td data-weight="medium">Wireless Mouse</td>
+        <td>$29.99</td>
+        <td data-align="right">
+          <button data-ui="dropdown-menu-trigger" data-variant="ghost" data-size="icon">
+            <span data-icon="more-horizontal"></span>
+            <span class="sr-only">Open menu</span>
+          </button>
+          <div data-ui="dropdown-menu-content" data-align="end">
+            <button data-ui="dropdown-menu-item">Edit</button>
+            <button data-ui="dropdown-menu-item">Duplicate</button>
+            <div data-ui="dropdown-menu-separator"></div>
+            <button data-ui="dropdown-menu-item" data-variant="destructive">Delete</button>
+          </div>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
 
----
+```html
+<div
+  data-ui="data-table"
+  data-source="pages"
+  data-page-size="12"
+  data-columns='[
+    {"key":"id","title":"ID"},
+    {"key":"title","title":"标题"},
+    {"key":"route","title":"路由"},
+    {"key":"status","title":"状态","type":"badge"}
+  ]'>
+</div>
+```
 
-## 属性约定
+## Tailwind 规则
 
-`dg-*` 属性命名跟随 shadcn 语义：
-- `variant`、`size`、`disabled`、`default-value`、`data-state`、`aria-*` 保持原意
-- 复杂组件使用 `data-dg-props='{"key":"value"}'` 传递结构化配置
+Page 资产仍然以 Tailwind HTML 为主。完整页面需要任意 Tailwind 原子类时，继续使用本地 `/assets/tailwindcss.js` 或已有页面模板；禁止外部 CDN。
 
----
+bridge 注入的 CSS 只保证 `data-ui` 组件需要的 shadcn/Tailwind 样式，不负责动态编译数据库 HTML 中任意 Tailwind class。
 
-## 禁止混淆
+## 主题规则
 
-- ❌ `dg-*` 不是 daisyUI
-- ❌ `dg-*` 不是 Bootstrap
-- ❌ `dg-*` 不是 Ant Design / Element Plus
-- ❌ `dg-*` 不是任意相似样式的泛称
-- ✅ `dg-*` 只能是 shadcn 的 DraftGo HTML 协议形态
+DraftGo 主题变量是唯一主题源头。bridge 组件只消费由 DraftGo token 映射出的 shadcn CSS variables：
 
----
+- `--dg-bg-page` -> `--background`
+- `--dg-text-primary` -> `--foreground`
+- `--dg-bg-surface` -> `--card`
+- `--dg-modal-bg` -> `--popover`
+- `--dg-border` -> `--border`
+- `--dg-action` / `--dg-brand` / `--dg-accent` -> `--primary`
+- `--dg-action-fg` -> `--primary-foreground`
+- `--dg-error` -> `--destructive`
+- `--dg-radius` -> `--radius`
 
-## 使用示例速查
+## 禁止
 
-完整带代码的示例见 `{{SKILL_DIR}}/quickref/dg-components.md`
+- 不要把 `data-ui` 当成 Bootstrap、daisyUI、Ant Design 或 Element Plus。
+- 不要在数据库 HTML 里写 JSX/TSX/React import。
+- 不要把普通 HTML 强制包成 shadcn；只有用户明确需要组件能力时才加 `data-ui`。

package/resources/skill/story/SKILL.md

@@ -91,8 +91,6 @@ now:
 3. 整个对话期间，Story 作为最高优先级上下文锚定
 ```
 
-**Gate 不可妥协**：开发者说"加个页面"，AI 必须先确保 Story 存在，再动手。
-
 ---
 
 ## 构建流程
@@ -102,7 +100,7 @@ now:
 ```
 扫描 .draftgo/ 下的数据，判断走哪条路径：
 
-├─ 存在用户自建内容（非 tag="系统" 的页面、db_meta、custom_scripts、外部API）→ 路径 A
+├─ 存在用户自建内容（非 tag="系统" 的页面、db_meta、custom_scripts）→ 路径 A
 ├─ 用户提供了设计文档（PRD、原型图描述、需求文档等）→ 路径 A（以文档为分析素材）
 └─ 只有内置系统页面，无用户自建内容，无设计文档 → 路径 B（对话采集）
 ```
@@ -117,7 +115,6 @@ now:
    - .draftgo/navigations/index.json → 导航结构
    - .draftgo/db_meta/index.json → 数据模型
    - .draftgo/custom_scripts/index.json → 自定义脚本
-   - .draftgo/external_apis/index.json → 外部 API
    - .draftgo/changelog.md → 更新日志
    - .draftgo/lessons/ → 开发经验记录
    - .draftgo/Task/ → 历史任务文档
@@ -242,15 +239,13 @@ AI 在开发过程中检测到"方向性决策"时，主动提议沉淀：
 | `identity.*` | 极少 | 仅重大方向转向时（冲突检测中确认） |
 | `design.overview` | 里程碑级 | 核心流转发生结构性变化时更新 |
 | `design.modules` | 新增模块时 | 只增/改，不删已有模块（模块下线标注即可） |
-| `decisions` | 只增不删 | ID 永不复用，supersede 时不删旧的只标记 |
+| `decisions` | 只增不删 | supersede 时不删旧的只标记 |
 | `now.focus` | 周/里程碑 | 对话结束时 AI 提议更新 |
 | `now.next` | 周 | 同上 |
 | `now.open_questions` | 随时 | 出现新的悬而未决事项 |
 | `meta.last_touched` | 每次更新 | 自动 |
 | `meta.maturity` | 手动 | seed→growing: 首次确认后; growing→stable: 决策≥5条且identity不再变 |
 
-**decisions ID 编号规则：** D001 起递增，永不复用，永不删除。
-
 ---
 
 ## 操作流程汇总

package/src/cli.js

@@ -9,6 +9,15 @@ const VALUE_FLAGS = new Set([
   'server',
   'token',
   'output',
+  'url',
+  'browser',
+  'mobile-check',
+  'screenshot',
+  'selector',
+  'width',
+  'height',
+  'wait-ms',
+  'delivery',
   'assignee',
   'assignee-id',
 ]);

package/src/commands/api.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const log = require('../logger');
+
+const API_FILE = path.resolve(__dirname, '..', '..', 'resources', 'skill', 'quickref', 'api.json');
+
+function apiCommand(positional, flags = {}) {
+  const keyword = String(positional.join(' ') || '').trim().toLowerCase();
+  if (!keyword) {
+    log.err('用法：draftgo api <keyword>');
+    log.dim('  示例：draftgo api pages batch');
+    return 1;
+  }
+
+  let spec;
+  try {
+    spec = JSON.parse(fs.readFileSync(API_FILE, 'utf8'));
+  } catch (err) {
+    log.err(`无法读取 OpenAPI：${err.message}`);
+    return 1;
+  }
+
+  const words = keyword.split(/\s+/).filter(Boolean);
+  const matches = [];
+  for (const [route, methods] of Object.entries(spec.paths || {})) {
+    for (const [method, operation] of Object.entries(methods || {})) {
+      if (!['get', 'post', 'put', 'patch', 'delete', 'head', 'options'].includes(method.toLowerCase())) continue;
+      const haystack = [route, method, operation.summary, operation.operationId, ...(operation.tags || [])]
+        .filter(Boolean).join(' ').toLowerCase();
+      if (!words.every((word) => haystack.includes(word))) continue;
+      matches.push({
+        method: method.toUpperCase(),
+        route,
+        summary: operation.summary || '',
+        operationId: operation.operationId || '',
+        tags: operation.tags || [],
+      });
+    }
+  }
+
+  if (flags.output === 'json') {
+    console.log(JSON.stringify(matches, null, 2));
+    return matches.length ? 0 : 1;
+  }
+  if (!matches.length) {
+    log.warn(`未找到包含“${keyword}”的 API。`);
+    return 1;
+  }
+  log.title(`draftgo api — ${keyword}`);
+  for (const item of matches.slice(0, 50)) {
+    console.log(`  ${item.method.padEnd(7)} ${item.route}${item.summary ? `  ${item.summary}` : ''}`);
+  }
+  if (matches.length > 50) log.dim(`  仅显示前 50 条，共 ${matches.length} 条；使用 --output json 获取完整结果。`);
+  return 0;
+}
+
+module.exports = apiCommand;

package/src/commands/autoPush.js

@@ -0,0 +1,41 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const log = require('../logger');
+const check = require('./check');
+const sync = require('./sync');
+
+function autoPush(projectDir, positional, flags = {}) {
+  const configPath = path.join(projectDir, '.draftgo', 'config.json');
+  if (!fs.existsSync(configPath)) {
+    log.dim('自动推送未执行：未连接 DraftGo 服务器（缺少 .draftgo/config.json）。');
+    return 0;
+  }
+
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    log.err(`自动推送未执行：config.json 解析失败：${err.message}`);
+    return 1;
+  }
+
+  log.step('auto-push: 先执行 check …');
+  const checkCode = check(projectDir, { strict: flags.strict });
+  if (checkCode !== 0) {
+    log.err('自动推送终止：check 未通过，请修复后重试。');
+    return checkCode;
+  }
+
+  if (config.auto_push !== true) {
+    log.dim('自动推送已跳过：check 已通过，但 .draftgo/config.json 的 auto_push 不为 true。');
+    return 0;
+  }
+
+  log.step('auto_push=true：开始 push …');
+  const pushArgs = flags.batch ? ['--batch', ...positional] : positional;
+  return sync(projectDir, 'push', pushArgs, flags);
+}
+
+module.exports = autoPush;

package/src/commands/check.js

@@ -14,39 +14,49 @@ function check(projectDir, flags = {}) {
   log.title('draftgo check');
   log.info(`项目目录：${projectDir}`);
 
+  const m = result.map;
   console.log('');
-  log.info(`资源概览：pages=${result.map.pages.length}, nav=${result.map.navigations.length}, db=${result.map.db_meta.length}, scripts=${result.map.custom_scripts.length}, aihub=${result.map.aihub.length}, external_apis=${result.map.external_apis.length}, docs=${result.map.docs.length}, doc_categories=${result.map.doc_categories.length}, system_config=${result.map.system_config.length}`);
+  const overview = [
+    ['pages', m.pages.length],
+    ['nav', m.navigations.length],
+    ['db', m.db_meta.length],
+    ['scripts', m.custom_scripts.length],
+    ['aihub', m.aihub.length],
+    ['docs', m.docs.length],
+  ];
+  console.log('  ' + overview.map(([k, v]) => `${log.c.cyan(k)} ${v}`).join('  '));
+  const pageAreas = [
+    ['home', m.pageGroups.home.length],
+    ['admin', m.pageGroups.admin.length],
+    ['business', m.pageGroups.business.length],
+    ['system', m.pageGroups.system.length],
+  ];
+  console.log('  ' + pageAreas.map(([k, v]) => `${log.c.cyan(k)} ${v}`).join('  '));
 
   if (result.errors.length) {
     console.log('');
-    console.log(`${log.c.red('x')} 错误：`);
-    result.errors.forEach((msg) => console.log(`  - ${msg}`));
+    result.errors.forEach((msg) => console.log(`  ${log.c.red('x')} ${msg}`));
   }
 
   if (result.warnings.length) {
     console.log('');
-    console.log(`${log.c.yellow('!')} 提醒：`);
-    result.warnings.forEach((msg) => console.log(`  - ${msg}`));
-  }
-
-  if (!result.errors.length && !result.warnings.length) {
-    console.log('');
-    log.ok('未发现明显闭环问题。');
+    result.warnings.forEach((msg) => {
+      const detail = (result.warningDetails || []).find((item) => item.message === msg);
+      const prefix = detail ? `[${detail.code}/${detail.confidence}] ` : '';
+      console.log(`  ${log.c.yellow('!')} ${prefix}${msg}`);
+    });
   }
 
+  console.log('');
   if (result.errors.length) {
-    console.log('');
-    console.log(`${log.c.red('x')} 检查未通过：请先修复错误。`);
+    log.err('检查未通过：请先修复错误。');
     return 1;
   }
   if (flags.strict && result.warnings.length) {
-    console.log('');
-    console.log(`${log.c.red('x')} strict 模式：存在提醒项，检查未通过。`);
+    log.err('strict 模式：存在提醒项，检查未通过。');
     return 1;
   }
-
-  console.log('');
-  log.ok(result.warnings.length ? '检查完成：存在提醒项，建议开发代理处理后再 push。' : '检查通过。');
+  log.ok(result.warnings.length ? '检查完成（有提醒项）。' : '检查通过。');
   return 0;
 }
 

package/src/commands/delete.js

@@ -30,8 +30,6 @@ const TYPE_ALIASES = {
   docs: 'docs',
   doc_category: 'doc_categories',
   doc_categories: 'doc_categories',
-  external_api: 'external_apis',
-  external_apis: 'external_apis',
   aihub: 'aihub',
 };
 
@@ -40,7 +38,7 @@ async function deleteResource(projectDir, positional, flags) {
 
   if (!typeRaw || !id) {
     log.err('用法：draftgo delete <type> <id>');
-    log.dim('  支持类型：pages | nav | db_meta | custom_scripts | docs | doc_categories | external_apis | aihub');
+    log.dim('  支持类型：pages | nav | db_meta | custom_scripts | docs | doc_categories | aihub');
     return 1;
   }
 
@@ -80,7 +78,11 @@ async function deleteResource(projectDir, positional, flags) {
     stdio: 'inherit',
     shell: false,
   });
-  return r.status || 0;
+  if (r.error) {
+    log.err(`删除脚本启动失败：${r.error.message}`);
+    return 1;
+  }
+  return Number.isInteger(r.status) ? r.status : 1;
 }
 
 module.exports = deleteResource;

package/src/commands/deploy.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const log = require('../logger');
+const check = require('./check');
+const sync = require('./sync');
+
+function deploy(projectDir, positional, flags = {}) {
+  const delivery = String(flags.delivery || 'deploy').toLowerCase();
+  if (!['local', 'preview', 'deploy'].includes(delivery)) {
+    log.err('--delivery 只支持 local、preview、deploy。');
+    return 1;
+  }
+  log.step('deploy: 先执行 check …');
+  const checkCode = check(projectDir, { strict: flags.strict });
+  if (checkCode !== 0) {
+    log.err('deploy 终止：check 未通过，请修复后重试。');
+    return checkCode;
+  }
+  if (delivery === 'local') {
+    log.ok('delivery=local：本地检查通过，未修改云端。');
+    return 0;
+  }
+  if (delivery === 'preview') {
+    log.step('delivery=preview：执行 push dry-run …');
+    return sync(projectDir, 'push', positional, { ...flags, 'dry-run': true });
+  }
+  log.step('delivery=deploy：开始 push …');
+  return sync(projectDir, 'push', positional, flags);
+}
+
+module.exports = deploy;

package/src/commands/doctor.js

@@ -28,7 +28,7 @@ async function doctor(projectDir, flags = {}) {
       log.dim('CLI 最新版查询失败（可能离线或 registry 不可达）');
     } else if (cmpSemver(latest, current) > 0) {
       log.warn(`CLI 有新版：${current} → ${latest}`);
-      log.dim('  下次运行 `draftgo update` 时会自动升级。');
+      log.dim('  运行 `draftgo upgrade` 可显式升级。');
     } else {
       log.ok(`CLI 已是最新：${current}`);
     }

package/src/commands/help.js

@@ -7,26 +7,31 @@ function help() {
   const targets = all.map((i) => `    ${i.name.padEnd(12)} ${i.displayName}`).join('\n');
   console.log(`draftgo v${getPackageVersion()} — DraftGo Next workbench CLI for AI coding agents
 
-DraftGo Next frontend baseline: React + Vite + shadcn/ui + Tailwind.
-Database pages use dg-* as the shadcn HTML runtime protocol.
+DraftGo Next frontend baseline: React + Vite.
+Database pages use standard HTML + Tailwind CSS.
 The CLI is the workbench layer for local runtime, resource sync, checks, and push/pull flows.
 
 Usage:
   draftgo init [<target>...]       Install skill. No target = auto-detect.
                                     Use "all" to install every target.
-  draftgo update [<target>...]     Update skill + entry files. If a newer CLI
-                                    version exists on npm, upgrades the CLI
-                                    automatically then reruns itself.
+  draftgo update [<target>...]     Atomically update skill + entry files.
+                                    Reports newer CLI versions without
+                                    modifying the global installation.
   draftgo uninstall <target|all>   Remove entry files for target(s).
                                     Use explicit "all" to remove every target.
                                     --purge also removes .draftgo/ (runtime data).
   draftgo status                   Show installed targets and skill version.
   draftgo doctor                   Diagnose environment (python, targets,
                                     CLI freshness).
+  draftgo upgrade                  Explicitly upgrade the global CLI, then
+                                    refresh installed skill files.
   draftgo map                      Print a local DraftGo project resource map
                                     for fast AI orientation.
   draftgo check                    Check local resource closure: routes,
-                                    entry binding, files, obvious mock risks.
+                                    entry binding, files, mock/color risks.
+  draftgo verify-ui <url>          Run a deterministic browser smoke check.
+                                    Uses one viewport and screenshots on failure.
+  draftgo api <keyword>            Search the bundled OpenAPI specification.
   draftgo dev                      Run this project's npm dev script.
   draftgo build                    Run this project's npm build script.
   draftgo new <type> <slug>        Scaffold a new resource locally (no network).
@@ -34,12 +39,17 @@ Usage:
                                     Types: page | nav | db_meta | script | doc
   draftgo delete <type> <id>       Delete resource from server + local index.
                                     Types: pages | nav | db_meta | custom_scripts
-                                           | docs | doc_categories | external_apis
+                                           | docs | doc_categories
                                     Alias: del, rm. Flags: --yes / -y skip confirm.
   draftgo pull [type] [id...]      Pull DraftGo resources via the bundled
                                     sync script. Defaults to --all.
   draftgo push <type> [id...]      Push DraftGo resources via the bundled
                                     sync script.
+  draftgo deploy [type] [id...]    Run check, then push explicitly.
+                                    --delivery local|preview|deploy
+  draftgo auto-push [type] [id...] Run check, then push only when
+                                    config.auto_push is true.
+                                    Supports --batch <type> <ids> ... too.
   draftgo local up|down|logs|status
                                     Manage .draftgo/docker/docker-compose.yaml
                                     generated by draftgo local-dev.
@@ -73,9 +83,15 @@ Flags:
   --token <sat>            (connect) Provide the access token non-interactively.
   --output <json>          (map/check) Print machine-readable JSON.
   --strict                 (check) Treat warnings as failures.
+  --mobile-check <mode>    (verify-ui) auto | always | never. Default: auto.
+  --screenshot <mode>      (verify-ui) on-failure | always | never.
+  --browser <name>         (verify-ui) chromium | chrome | msedge.
+  --selector <css>         (verify-ui) Require a key element to be visible.
+  --width/--height <px>    (verify-ui) Override the default 390x844 viewport.
+  --delivery <mode>        (deploy) local | preview | deploy.
 
 Environment:
-  DRAFTGO_NO_UPDATE_CHECK=1     Disable the automatic CLI-freshness check.
+  DRAFTGO_NO_UPDATE_CHECK=1     Disable the cached CLI version check.
 
 Targets:
 ${targets}
@@ -85,9 +101,11 @@ Examples:
   draftgo init claudecode      # install for Claude Code only
   draftgo init claudecode kiro # install for both
   draftgo init all             # install for every supported target
-  draftgo update               # upgrade CLI if needed, then refresh skill
+  draftgo update               # refresh skill and report newer CLI versions
+  draftgo upgrade              # explicitly upgrade CLI and refresh skill
   draftgo map                  # inspect pages/nav/db/scripts before development
   draftgo check --strict       # fail on closure warnings before push
+  draftgo verify-ui http://localhost:5173 --mobile-check auto
   draftgo uninstall all --purge # full removal incl. runtime data
 `);
 }

package/src/commands/init.js

@@ -49,15 +49,30 @@ async function init(projectDir, positional, flags) {
   //    .draftgo/skill/ indirection anymore — each AI tool gets a real copy).
   log.step('写入各 AI 工具 skill 目录（含 SKILL.md / 子技能 / rules / scripts）');
   ensureRuntime(projectDir);
+  const failures = [];
+  let installedCount = 0;
+  let skippedCount = 0;
   for (const t of resolved) {
     try {
       const r = t.install(projectDir, { force: !!flags.force });
-      log.ok(`${t.displayName.padEnd(16)} → ${r.path}`);
+      if (r.skipped) {
+        skippedCount += 1;
+        log.warn(`${t.displayName.padEnd(16)} 已存在，未覆盖；使用 draftgo update 或 --force 更新。`);
+      } else {
+        installedCount += 1;
+        log.ok(`${t.displayName.padEnd(16)} → ${r.path}`);
+      }
     } catch (e) {
       log.err(`${t.displayName} 安装失败：${e.message}`);
+      failures.push(t.displayName);
     }
   }
-  writeInstalledVersion(projectDir);
+  if (failures.length) {
+    log.err(`安装未完成，失败目标：${failures.join(', ')}`);
+    return 1;
+  }
+  if (installedCount > 0 && skippedCount === 0) writeInstalledVersion(projectDir);
+  if (skippedCount > 0) log.dim('  存在未覆盖目标，未更新全局 skill 版本标记；运行 draftgo update 可统一刷新。');
   log.dim(`  CLI 版本：${getPackageVersion()}`);
 
   // 3) Environment check (advisory).