draftgo-cli 3.0.1 → 3.0.33

package/resources/skill/references/modules.md

@@ -0,0 +1,66 @@
+---
+read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目做全局了解时
+---
+
+# DraftGo 模块地图
+
+## 可开发模块（开发者负责实现）
+
+| 模块 | 开发方式 | 入口 |
+|---|---|---|
+| 页面 | 数据库 HTML（`page.value.html`） | `.draftgo/pages/` |
+| 导航栏 | 数据库 HTML（`navigation.html`） | `.draftgo/navigations/` |
+| 动态 DB | db_meta 定义 schema + `/api/db/{type}` 操作数据 | `.draftgo/db_meta/` |
+| 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | `.draftgo/custom_scripts/` |
+| AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | `.draftgo/aihub/` |
+| 文档中心 | Markdown 文章 + 分类树 | `.draftgo/docs/articles/` |
+| 系统配置 | KV 存储，含全局前端层槽位 | `.draftgo/system_config/` |
+
+## 平台内置模块（开箱即用，不需实现）
+
+| 模块 | 能力 | 调用方式 |
+|---|---|---|
+| 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | `POST /api/auth/*` |
+| 角色权限 | 多角色 RBAC，页面/DB/API 均支持角色级权限 | `App.isAdmin` / `App.currentUser.role_code` |
+| 通知公告 | 发布公告，支持类型/状态/分页 | `GET/POST /api/notices` |
+| 工单反馈 | 用户提交问题，支持类型/状态跟踪 | `GET/POST /api/feedback` |
+| 备份恢复 | 完整/选择性备份，JSON/.dgbak 格式，支持 dry-run | `POST /api/system/backup` |
+| 系统管理 | 系统配置 KV、存储健康、全局前端层、通知测试 | `GET/PUT /api/system/*` |
+
+## 模块选型决策
+
+```
+要存储业务数据？
+  → 有固定结构 → 动态 DB（db_meta 定义 schema）
+  → 仅需 KV → sys_config（category 自定义）
+
+要调用 AI？
+  → 聊天/问答 UI → AIHub + `<dg-chat>`（自动隔离 thread/session）
+  → 无 UI 的旧代码文本调用 → AIHub + DraftGoAI.chat()（兼容门面）
+  → 图片生成 → AIHub + DraftGoAI.images()
+  → 需要工具/子智能体/记忆/结构化输出/多模态 → 都是 Agent spec 开关，见 references/aihub.md
+
+要调用第三方服务？
+  → 自定义服务（用 `draftgo.HTTP` 请求；需要时可用 route/event/scheduled 加工）
+
+要展示内容文档？
+  → 文档中心（Markdown + 分类树）
+
+要做定时任务或事件响应？
+  → 自定义服务（mode: scheduled / event）
+
+要做后台管理页？
+  → 业务页面 + 动态 DB + 角色权限
+```
+
+## 自定义服务边界
+
+- 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
+- `route`：对外暴露 HTTP 端点，运行时路径为 `/api/x/{slug}/{path}`；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，推送后要真实请求验证。
+- `event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
+- `scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
+- 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。
+- 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 调用面继续由每个服务的 `permission` / `route_security` 独立控制，不要把两层权限混为一谈。
+- Go 服务在独立子进程中构建/运行；只有可信角色才能获得 `scripts:create` / `scripts:update`。
+- 自定义服务适合服务端加工、鉴权后聚合、第三方回调、定时任务和事件响应；普通 CRUD 管理界面优先用“页面 + 动态 DB”，不要把所有业务后台都塞进 route 脚本。
+- 脚本内读动态 DB 用 `draftgo.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `references/custom-services.md`。

package/resources/skill/references/parallel.md

@@ -0,0 +1,48 @@
+# DraftGo 并行执行
+
+## 资源依赖
+
+先为每个工作单元记录：
+
+- `depends`：开始前必须完成的工作单元。
+- `resource_lock`：本单元会修改的文件或 DraftGo 资源。
+- `evidence`：完成后返回的验证证据。
+
+按以下关系建立依赖：
+
+| 资源关系 | 执行顺序 |
+|---|---|
+| 多个实现依赖同一 schema、API、权限或路由 | 先确定共享契约，再并行实现消费者。 |
+| 两个工作单元修改同一文件或资源 | 合并为一个单元，或安排到连续 wave。 |
+| 页面与对应导航入口 | 页面 route 确定后接入导航。 |
+| 不同文件且没有数据或接口依赖 | 放入同一 wave 并行执行。 |
+
+## 工作单元
+
+分发内容包括：
+
+```yaml
+objective: 要完成的结果
+inputs: 当前资源和共享契约
+resource_lock: [允许修改的文件或资源]
+evidence: 返回的检查或运行证据
+delivery_owner: main
+```
+
+工作单元返回修改结果、验证证据和阻塞信息。主代理维护共享契约、推进 wave、汇总资源并执行交付。
+
+## Wave 执行
+
+1. 确定 schema、服务端点、权限、route 和导航结构等共享契约。
+2. 将 `depends` 已满足且 `resource_lock` 不冲突的工作单元放入同一 wave。
+3. 并行执行当前 wave，汇总后回读所有变更资源。
+4. 处理接口接线和入口绑定，再启动依赖已满足的下一 wave。
+5. 统一运行 `draftgo check`、必要的 API/UI 验证，并按交付意图执行批量推送。
+
+某个工作单元失败时，其依赖项等待处理；其余独立分支继续汇总。发现资源锁冲突时，将冲突单元合并或移到后续 wave。
+
+批量交付示例：
+
+```bash
+draftgo auto-push --batch pages 1,2,3 nav 4 custom_scripts 7
+```

package/resources/skill/{specs → references}/runtime.md

@@ -36,7 +36,7 @@ read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问
 
 `app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme）
 
-完整 API 见 `{{SKILL_DIR}}/quickref/app-api.md`
+完整 API 见 `{{SKILL_DIR}}/references/app-api.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 → references}/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/references/ui-protocol.md

@@ -0,0 +1,99 @@
+---
+read_when: 开发数据库页面时需要真实 shadcn/Radix 组件能力 · 了解 data-ui bridge 协议时
+---
+
+# shadcn Page Runtime Bridge 协议
+
+## 核心认知
+
+数据库页面不进入 Vite/React 编译链，不能写 TSX、React import 或 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
+```
+
+## 当前稳定协议
+
+| 能力 | HTML 写法 | 底层 |
+|---|---|---|
+| 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 规则
+
+Page 资产仍然以 Tailwind HTML 为主。完整页面需要任意 Tailwind 原子类时，继续使用本地 `/assets/tailwindcss.js` 或已有页面模板；禁止外部 CDN。
+
+bridge 注入的 CSS 只保证 `data-ui` 组件需要的 shadcn/Tailwind 样式，不负责动态编译数据库 HTML 中任意 Tailwind class。
+
+## 主题规则
+
+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`
+
+## 禁止
+
+- 不要把 `data-ui` 当成 Bootstrap、daisyUI、Ant Design 或 Element Plus。
+- 不要在数据库 HTML 里写 JSX/TSX/React import。
+- 不要把普通 HTML 强制包成 shadcn；只有用户明确需要组件能力时才加 `data-ui`。

package/resources/skill/scripts/draftgo_delete.py

@@ -10,7 +10,6 @@ DraftGo Delete Script
   python draftgo_delete.py custom_scripts  <id>
   python draftgo_delete.py docs            <id>
   python draftgo_delete.py doc_categories  <id>
-  python draftgo_delete.py external_apis   <id>
   python draftgo_delete.py aihub           <id>
 """
 import json, sys
@@ -92,7 +91,6 @@ TYPE_MAP = {
     "custom_scripts": ("/api/scripts",          "custom_scripts/index.json",          "id", "code_file"),
     "docs":           ("/api/docs/articles",    "docs/articles/index.json",           "id", "content_file"),
     "doc_categories": ("/api/docs/categories",  "doc_categories/index.json",          "id", None),
-    "external_apis":  ("/api/external-apis",    "external_apis/index.json",           "id", None),
     "aihub":          ("/api/aihub",            "aihub/index.json",                   "id", None),
 }
 

package/resources/skill/scripts/draftgo_init.py

@@ -38,9 +38,21 @@ def main():
     dg_dir = root / ".draftgo"
     dg_dir.mkdir(parents=True, exist_ok=True)
 
-    # 写入配置
-    cfg = {"server": server, "token": token, "lessons_on_push": True}
-    (dg_dir / "config.json").write_text(
+    # 写入配置。重复初始化时保留用户明确启用的自动推送开关。
+    config_path = dg_dir / "config.json"
+    old_cfg = {}
+    if config_path.exists():
+        try:
+            old_cfg = json.loads(config_path.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    cfg = {
+        "server": server,
+        "token": token,
+        "lessons_on_push": old_cfg.get("lessons_on_push", True),
+        "auto_push": old_cfg.get("auto_push", False) is True,
+    }
+    config_path.write_text(
         json.dumps(cfg, indent=2),
         encoding="utf-8",
     )