draftgo-cli 1.0.0 → 1.1.1

package/README.md

@@ -35,7 +35,7 @@ draftgo init all                         # 所有支持的工具
 | 命令 | 说明 |
 |---|---|
 | `draftgo init [target]...` | 安装 skill。不传 target 时自动识别；`all` 表示全部。 |
-| `draftgo update [target]...` | 覆盖 skill 内容到 CLI 内置版本，同时刷新已安装的入口；保留本地 `config / iteration / bugs / pages` 等运行时数据。 |
+| `draftgo update [target]...` | 覆盖 skill 内容到 CLI 内置版本，同时刷新已安装的入口；保留本地 `config / iteration / bugs / pages` 等运行时数据。**若 npm 上存在更新的 CLI 版本，会先自动升级 CLI 再重跑自己**。 |
 | `draftgo uninstall [target]...` | 移除指定 AI 工具的入口文件；全量卸载时同时删除 `.draftgo/skill/`。加 `--purge` 会连 `.draftgo/` 整个删掉。 |
 | `draftgo status` | 查看当前项目装了哪些 AI 工具入口、skill 版本。 |
 | `draftgo doctor` | 诊断：Python 是否可用、检测到哪些 AI 工具、各入口状态。 |
@@ -47,8 +47,25 @@ draftgo init all                         # 所有支持的工具
 
 - `--project <dir>`：对指定目录操作（默认当前工作目录）。
 - `--force`：`init/update` 时覆盖已存在的 `.draftgo/skill/`。
+- `--skip-update-check`：`update` 时不去 npm 查最新版，直接用当前 CLI 执行。
 - `--purge`：`uninstall` 时连 `.draftgo/`（含 config / 日志 / 本地缓存）一起删。
 
+可以通过环境变量 `DRAFTGO_NO_UPDATE_CHECK=1` 全局关闭自动升级检查（离线、CI 等场景）。
+
+## 更新
+
+```bash
+cd <your-project>
+draftgo update
+```
+
+就这一条命令。`update` 会自己去 npm 查最新版：
+
+- 如果 CLI 已是最新 → 直接把内置 skill 资源覆盖到 `.draftgo/skill/`
+- 如果 CLI 过时 → 自动执行 `npm install -g draftgo-cli@latest`，然后用新 CLI 重跑一遍 `update`
+
+整个过程中，你本地的 `.draftgo/config.json`、`iteration/`、`bugs/`、`pages/` 等运行时数据都不会被动到。
+
 ## 自动识别的依据
 
 | AI 工具 | 探测信号（任一命中即视为在用） |
@@ -73,7 +90,6 @@ draftgo init all                         # 所有支持的工具
 ├── .draftgo/
 │   ├── skill/                        # CLI 管理，不要手动改
 │   │   ├── SKILL.md
-│   │   ├── CLAUDE.md
 │   │   ├── init/SKILL.md
 │   │   ├── sync/SKILL.md
 │   │   ├── bug/SKILL.md

package/bin/draftgo.js

@@ -1,3 +1,3 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 'use strict';
 require('../src/index.js').run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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"

package/resources/skill/SKILL.md

@@ -15,21 +15,337 @@ version: 1.0.0
 | 用户意图 | 执行 |
 |---|---|
 | 初始化项目 / 连接服务器 / `/draftgo init` | 调用 `/draftgo init` Skill |
-| 同步页面或导航 / `/draftgo sync` | 调用 `/draftgo sync` Skill |
-| 开发页面 / 修改页面 / 新建导航 | 读取 `CLAUDE.md` + `.draftgo/rules/frontend.md` + `.draftgo/rules/debugging-syntax.md` 后开始开发，**完成后必须：1) 写迭代记录 2) 自动同步到服务器**（见下方规范） |
+| 同步页面、导航或数据库 / `/draftgo sync` | 调用 `/draftgo sync` Skill |
+| 开发页面 / 修改页面 / 新建导航 | 读取本文件下方"架构认知"及 `.draftgo/rules/frontend.md` + `.draftgo/rules/debugging-syntax.md` 后开始开发，**完成后必须：1) 写迭代记录 2) 自动同步到服务器**（见下方规范） |
 
 ## 开发前置检查
 
-进行任何开发任务前，先确认：
+进行任何开发任务前，先确认 `.draftgo/config.json` 存在：
 
 ```
-!test -f CLAUDE.md && echo "OK" || echo "请先运行 /draftgo init"
+!test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
 ```
 
-`CLAUDE.md` 存在后，读取它获取页面列表、导航列表、服务器地址等上下文。
+存在后，从 `.draftgo/config.json` 读取服务器地址和 token。
 
 开发规范读取：`.draftgo/rules/frontend.md`
 
+---
+
+## 架构认知（必读）
+
+**DraftGo 不是传统 SPA，是"数据库驱动的页面资产运行时"：**
+- 壳层（Vue 3 + Vite）只负责 runtime 编排，源码在 `frontend/src/core/`
+- 业务页面 HTML 存在数据库 `page.value.html`，运行在 `iframe.srcdoc`
+- 导航栏 HTML 存在数据库 `navigation.html`，由壳层按需加载
+- 页面与壳层通过 `window.parent.App` API 通信
+
+**技术栈：**
+- 后端：FastAPI 0.115.0 + SQLAlchemy 2.0.36 + Pydantic 2.10.0 + MySQL + Redis
+- 前端：Vue 3 + Vite + Tailwind CSS（本地 `/assets/tailwindcss.js`）
+
+## 连接信息
+
+- 服务器地址与 Token：存储于 `.draftgo/config.json`（已加入 .gitignore）
+- 运行 `/draftgo init` 时写入
+
+## 开发规范
+
+→ 前端页面开发：读取 `.draftgo/rules/frontend.md`
+→ 页面排错指南：读取 `.draftgo/rules/debugging-syntax.md`（页面功能不执行时必读！）
+- 任何开发，必读！
+
+## 开发禁区（违反必报错）
+
+- ❌ 禁止境外 CDN（googleapis/jsdelivr/cdnjs/unpkg）→ ✅ 允许国内镜像（npmmirror.com/staticfile.net）
+- ❌ 禁止 `App()` 写法（App 是对象不是函数）→ ✅ 正确：`const App = window.parent?.App`
+- ❌ 禁止 `const App = () => window.parent?.App` → ✅ 去掉箭头函数
+- ❌ 禁止 `window.location.search` 读参数 → ✅ 用 `window.__DG_ROUTE_CONTEXT__.query`
+- ❌ 禁止 `App?.user?.role` 判断管理员 → `App.user` 不存在！✅ 用 `App.isAdmin` 或 `App.currentUser?.role_code`
+- ❌ 禁止 `navigate('/login')` 退出 → ✅ 用 `window.location.href = '/login'`
+- ❌ 禁止 `window.alert/confirm/prompt` → ✅ 用 `App.toast()` / `App.confirm()` / `App.showModal()`
+  - `App.showSuccess(msg)` 成功提示（绿色 3s）
+  - `App.showError(msg)` 错误提示（红色 4s）
+  - `App.showWarning(msg)` 警告提示（黄色 3s）
+  - `App.showInfo(msg)` 信息提示（蓝色 3s）
+  - `App.toast(msg, type)` 通用方法 — type: success/error/warning/info
+  - `App.confirm(msg, title?)` 确认弹窗 — 返回 Promise\<boolean\>
+  - `App.showModal(msg, title?)` 信息模态框 — 替代 alert()
+  - `App.showLoading()` / `App.hideLoading()` — 全局 loading
+  - `App.callApi(code, options?)` — 调用已注册的外部 API（Promise→`{status_code, headers, body, duration_ms, error}`）
+  - `App.listApis()` — 列出当前用户可调用的外部 API（含 code / name / method / 各 JSON Schema）
+  - 详见 `.draftgo/rules/frontend.md` App API 章节
+- ⚠️ 尽量避免硬编码颜色 → 优先用 `var(--dg-accent)` 等 token 以适配主题切换
+
+## 主题切换适配
+
+DraftGo 支持多套配色方案 + 亮暗模式，通过 CSS 变量实现。
+
+**概念分层：**
+| 概念 | 存储键 | 取值 |
+|---|---|---|
+| 显示模式 | `dg_theme` | `'light'` \| `'dark'` \| `'system'` |
+| 配色方案 | `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'orange-white'` \| `'custom'` |
+
+**内置配色方案：**
+- `dark-gray-white` 深灰白（默认）— 冷调深灰，干净利落
+- `deep-blue-white` 深蓝白 — 专业稳重，企业风
+- `orange-white` 橙白 — 温暖醒目，创意风
+
+**颜色 Token（优先使用）：**
+- `--dg-bg-base` / `--dg-bg-page` / `--dg-bg-surface` — 背景层级
+- `--dg-text-primary` / `--dg-text-secondary` / `--dg-text-muted` — 文字层级
+- `--dg-accent` / `--dg-accent-hover` / `--dg-accent-subtle` — 主题色
+- `--dg-border` / `--dg-success` / `--dg-error` / `--dg-warning` — 功能色
+
+**App API 切换配色：**
+```javascript
+App.setColorScheme('deep-blue-white');              // 切换为预设方案
+App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
+```
+
+**硬编码颜色的场景（允许但需注意）：**
+- 品牌色（如 Logo 固定色）
+- 数据可视化图表（需保证对比度）
+- 第三方组件库强制要求
+
+**硬编码时的要求：**
+- 同时提供亮色/暗色两套值，通过 `[data-theme="dark"]` 选择器切换
+- 确保对比度符合 WCAG AA 标准（文字至少 4.5:1）
+
+## 本地开发流程
+
+**原则：有功能修改就读本地数据，自主决策是否调用 API 完成高质量修改。**
+
+1. **开发时**：读写 `.draftgo/` 本地文件
+   - 查元数据：读 `index.json`
+   - 查/改 HTML：按 `html_file` 字段路径读对应 `.html` 文件
+2. **修改后**：运行同步脚本推送到服务器（见下方"同步规范"）
+3. **同步成功**：本地与服务器数据一致
+
+**本地数据目录（均在 `.draftgo/` 下）：**
+
+| 目录 | 内容 |
+|---|---|
+| pages/ | index.json（无 html）+ 若干 .html |
+| navigations/ | index.json（无 html）+ 若干 .html |
+| roles/ | index.json |
+| users/ | index.json |
+| db_meta/ | index.json |
+| aihub/ | index.json |
+| external_apis/ | index.json（已注册的外部 API 元信息，`auth_config` 已脱敏） |
+| system_config/ | index.json |
+| iteration/ | YYYY-MM-DD.txt（迭代日志） |
+| error/ | YYYY-MM-DD.txt（错误日志） |
+
+## 数据库 Schema（关键字段）
+
+| 表 | 关键字段 | 说明 |
+|---|---|---|
+| `page` | `id`, `title`, `route`, `permission`, `value` (JSON: `{html: "..."}`) | value.html 存页面完整 HTML |
+| `navigation` | `id`, `code`, `name`, `html`, `order`, `status` | html 字段存导航栏完整 HTML |
+| `user` | `id`, `username`, `email`, `role_id`, `status` | role_id 关联 role 表 |
+| `role` | `id`, `code`, `name`, `permissions` (JSON) | admin 角色拥有所有权限 |
+| `db_meta` | `id`, `type`, `fields` (JSON: `[{name, type, required}]`) | 动态表结构定义 |
+| `db` | `id`, `type`, `data` (JSON), `userid`, `status`, `created_at`, `updated_at` | 动态数据存储（含自动时间戳） |
+| `aihub` | `id`, `name`, `type`, `config` (JSON), `status` | AI 服务配置 |
+| `sys_config` | `config_key`, `config_value`, `value_type`, `category`, `is_sensitive` | 系统配置 KV |
+
+## API 速查与示例
+
+| 模块 | 端点 |
+|---|---|
+| 认证 | POST /api/auth/login, /register, /logout, /refresh, /forgot-password, /reset-password |
+| 微信认证 | POST /api/auth/wechat/mp/oauth, /wechat/mini/login, /wechat/mp/qr/create · GET /wechat/mp/qr/poll |
+| 用户 | GET/PUT /api/users/me · GET/POST /api/users · GET/PUT/DELETE /users/{id} · POST /users/{id}/ban, /unban |
+| 角色 | GET/POST /api/roles · GET/PUT/DELETE /roles/{id} · POST /roles/{id}/assign/{uid} · DELETE /roles/{id}/revoke/{uid} |
+| 页面 | GET/POST /api/pages/ · GET/PUT/DELETE /pages/{id} · POST /pages/{id}/reset-system · GET /pages/by-route · GET /pages/public/{route} |
+| 导航栏 | GET/POST /api/navigations · GET /navigations/{code} · PUT/DELETE /navigations/{id} · POST /navigations/{id}/reset-system |
+| 系统配置 | GET /api/system/config · GET /system/category/{category} · GET/PUT/DELETE /system/{key} · POST /system/ · POST /system/config/ensure |
+| 备份恢复（基础） | GET/POST /api/system/backup · POST /system/restore · POST /system/reset · POST /system/backup/selective · POST /system/restore/selective?mode=replace\|merge\|append · GET /system/backup/logs |
+| 备份恢复（增强） | GET /system/backup/package, POST /system/backup/selective/package（.dgbak）· POST /system/restore/package, /restore/package/inspect（上传 .dgbak）· POST /system/restore/inspect, /restore/dry-run（只读预览/预演）· GET /system/storage/health, POST /system/storage/cleanup-orphans（存储健康）· POST /system/backup/logs/{id}/restore, /undo（回溯/撤销） |
+| ⚠️ 二次密码 | restore / reset / undo / cleanup-orphans / package restore 都需要先 POST `/auth/reauth { password, scope }` 拿一次性 `confirm_token`，在请求头加 `X-Confirm-Token: <token>` 才能调用。SAT 调用方自动豁免。 |
+| 通知公告 | GET/POST /api/notices · GET/PUT/DELETE /notices/{id} |
+| 反馈 | GET/POST /api/feedback · GET /feedback/updates · GET/PUT/DELETE /feedback/{id} · DELETE /feedback/batch |
+| 日志 | GET /api/logs · GET /logs/{id} |
+| 智能体 | GET /api/agents · GET /agents/logs · POST /agents/{id}/chat · POST /agents/{id}/preview-chat |
+| 动态DB | GET/POST /api/db/{type} · GET/PUT/DELETE /db/{type}/{id} |
+| DB Meta | GET/POST /api/db-meta · GET /db-meta/{type} · PUT/DELETE /db-meta/{id} |
+| ⚠️ DB Meta 查询 | GET /db-meta/{type} 用 **type**（如 `patient_profile`），不是 id。用 id 查会返回 "元数据不存在"。PUT/DELETE 才用 id。 |
+| AIHub | GET/POST /api/aihub · GET/PUT/DELETE /aihub/{id} · PATCH /aihub/{id}/basic · POST /aihub/{id}/sync · POST /aihub/discover · GET /aihub/types |
+| AI推理 | GET /api/v1/models · POST /v1/chat/completions |
+| 外部 API（页面调用端） | GET /api/external-apis/available · POST /api/external-apis/call/{code}<br>页面里**优先使用 `App.callApi(code, options)`**，不要直连这两个端点 |
+| 外部 API（管理端，需 admin） | GET/POST /api/external-apis · GET/PUT/DELETE /external-apis/{id} · PATCH /external-apis/{id}/status · POST /external-apis/{id}/test · GET /external-apis/tags · GET /external-apis/logs · POST /external-apis/logs/cleanup?retention_days=N |
+| 文件上传 | POST /api/upload |
+| 通知测试 | POST /api/system/notifications/test-email, /test-sms · GET /system/notifications/logs |
+
+### 高频 API 示例
+
+**创建页面（需 admin）：**
+```
+POST /api/pages/
+Body: { "title": "新页面", "route": "/new", "permission": "public", "value": {"html": "<html>...</html>"} }
+Response: { "id": 123, "title": "新页面", "route": "/new", ... }
+```
+
+**更新页面 HTML（需 admin）：**
+```
+PUT /api/pages/123
+Body: { "value": {"html": "<html>更新后...</html>"} }
+```
+
+**重置系统页面（需 admin）：**
+```
+POST /api/pages/123/reset-system
+Body: 空
+说明：从 backend/init/pages/ 重新加载该页面
+```
+
+**创建动态数据（普通用户自动绑定 userid）：**
+```
+POST /api/db/patient
+Body: { "data": {"name": "张三", "age": 30} }
+Response: { "id": 456, "type": "patient", "data": {...}, "userid": 当前用户id, "status": 1, "created_at": "...", "updated_at": "..." }
+```
+
+**查询动态数据（带分页）：**
+```
+GET /api/db/patient?page=1&page_size=20
+Response: { "items": [...], "total": 100, "page": 1, "page_size": 20 }
+```
+
+**调用外部 API（页面里）：**
+```javascript
+// 在页面 HTML 里：壳层会自动注入认证、做参数校验、写日志
+const r = await App.callApi('weather-now', {
+  path_params: { city: 'beijing' },   // 替换 path 模板里的 {city}
+  query_params: { unit: 'metric' },   // ?unit=metric
+  // body: { ... },                    // POST/PUT/PATCH 才生效
+  // headers: { 'X-Trace': 't1' },     // 不会覆盖后端注入的认证头
+});
+if (r.status_code >= 200 && r.status_code < 300) {
+  console.log(r.body);  // JSON 自动解析
+} else {
+  App.showError(`上游返回 ${r.status_code}`);
+}
+```
+- 不要在页面里写 API Key / Bearer Token，由管理员在「外部 API」管理页注册即可
+- API code 不知道时先 `await App.listApis()` 查询
+- `r.error` 仅在代理层错误时（超时 / 网络 / 校验失败）非空；上游业务错误请看 `r.status_code` + `r.body`
+
+## 用自然语言注册/管理外部 API（SAT 直连管理端）
+
+> 当用户说"帮我接入和风天气"、"注册一个 OpenAI 兼容接口"、"把这个 API 加进来"等，**走管理端 API 注册**，不要让用户去后台手动配置。
+
+### 1. 先查本地缓存
+
+读 `.draftgo/external_apis/index.json` 确认是否已注册过相同 `code`。
+
+### 2. 调用管理端 API（用 SAT，需 admin）
+
+读 `.draftgo/config.json` 拿到 `server` + `token`，按下面字段构造 payload，调用 `POST /api/external-apis`：
+
+```json
+{
+  "code": "weather-now",
+  "name": "和风天气-实时",
+  "base_url": "https://devapi.qweather.com",
+  "method": "GET",
+  "path": "/v7/weather/now",
+  "headers": {},
+  "auth_type": "api_key_query",
+  "auth_config": { "name": "key", "value": "用户提供的 KEY" },
+  "timeout_ms": 30000,
+  "permission": { "default": "login", "roles": [] },
+  "param_schema": {
+    "query": {
+      "type": "object",
+      "properties": { "location": { "type": "string" } },
+      "required": ["location"]
+    }
+  },
+  "tags": ["weather"],
+  "description": "实时天气查询"
+}
+```
+
+**字段约定：**
+- `auth_type`：`none` / `api_key_header` / `api_key_query` / `bearer` / `basic`
+  - `api_key_header` / `api_key_query`：`auth_config = {name, value}`
+  - `bearer`：`auth_config = {token}`
+  - `basic`：`auth_config = {username, password}`
+- `permission.default`：`public`（匿名）/ `login`（登录用户）/ `deny`（仅指定角色）
+- `param_schema.{path,query,body}`：均为 JSON Schema Draft 2020-12，可省略
+- `path` 支持 `{var}` 模板，对应 `param_schema.path` 中字段
+- 认证字段由后端 AES-256-GCM 加密落库；后续 GET 详情会返回脱敏值
+
+### 3. 注册后立即测试 + 写迭代记录
+
+```
+POST /api/external-apis/{id}/test
+Body: { "path_params": {...}, "query_params": {...}, "body": ... }
+返回: { ok, status_code, duration_ms, error }
+```
+
+测试通过后写迭代记录：`[新增] 注册外部 API <code>`
+
+### 4. 常见管理操作
+
+| 用户意图 | API 调用 |
+|---|---|
+| 列出所有 API | `GET /api/external-apis?page=1&page_size=50` |
+| 改名/换地址/换 KEY | `PUT /api/external-apis/{id}`（仅传需要改的字段；不传 `auth_config` 则保留原 KEY） |
+| 启用/禁用 | `PATCH /api/external-apis/{id}/status` body `{status:"active|disabled"}` |
+| 删除 | `DELETE /api/external-apis/{id}` |
+| 查看调用日志 | `GET /api/external-apis/logs?api_code=<code>&page=1&page_size=50` |
+| 清理日志 | `POST /api/external-apis/logs/cleanup?retention_days=30` |
+| 列出已用标签 | `GET /api/external-apis/tags` |
+
+### 5. 用户场景对话样例
+
+- 用户："给我接一个查天气的 API，KEY 是 xxx"
+  → AI 询问：服务商？请求方法？需要哪些参数？  
+  → AI 调用 `POST /api/external-apis` 注册 → 调用 `/test` 验证 → 告知 code  
+  → 用户在页面里直接 `App.callApi('weather-now', { query_params: { location: 'beijing' } })`
+
+- 用户："禁用 weather-now 这个接口"  
+  → AI 先 `GET /api/external-apis?keyword=weather-now` 拿 id → `PATCH /{id}/status` → 写迭代记录
+
+## URL 参数读取
+
+页面运行在 `iframe.srcdoc` 中，`window.location.search` 不可靠。框架通过 `<script data-dg-route-bridge>` 注入路由上下文。
+
+```javascript
+// 标准三阶回落（推荐）
+const routeContext =
+  window.__DG_ROUTE_CONTEXT__
+  || window.__DG_GET_ROUTE_CONTEXT__?.()
+  || window.parent?.App?.getCurrentRouteContext?.()
+  || { query: {} };
+const query = routeContext.query || {};
+
+// 使用示例
+const patientId = query.patientId;  // "42"
+const visitId = query.visitId;      // "7"
+```
+
+禁止：`new URLSearchParams(window.location.search)` — iframe 中取不到壳层 URL。
+
+## 常见问题排查
+
+| 问题 | 排查步骤 |
+|---|---|
+| 同步失败 | 1. 检查 `.draftgo/config.json` token 是否有效<br>2. 检查服务器连接<br>3. 查看 `.draftgo/error/YYYY-MM-DD.txt` 错误日志 |
+| 页面加载空白 | 1. 检查 `permission` 字段与当前用户角色是否匹配<br>2. 检查路由是否正确（`/api/pages/by-route?route=/xxx`）<br>3. 浏览器控制台查看 JS 错误 |
+| API 返回 401 | Token 过期，前端会自动用 refresh token 刷新，无需手动处理 |
+| API 返回 403 | 权限不足，检查当前用户角色是否有对应权限 |
+| DB Meta GET 返回"元数据不存在" | 你用了 id，应该用 **type**（如 `/api/db-meta/patient_profile`）。PUT/DELETE 才用 id。 |
+| 颜色不生效 | 检查是否用了 `var(--dg-*)` 而非硬编码 hex/rgb |
+| URL 参数读取失败 | 检查是否用了 `window.__DG_ROUTE_CONTEXT__.query` 而非 `window.location.search` |
+| 退出登录后导航栏未更新 | 检查是否用了 `window.location.href = '/login'` 而非 `navigate('/login')` |
+
+---
+
 ## 迭代记录规范
 
 每次对系统进行开发/修复/修改/完善/删除/重构等操作后，**必须**在 `.draftgo/iteration/` 目录下按日期写入迭代记录。
@@ -57,19 +373,80 @@ version: 1.0.0
 3. 存在则 Read 后追加新行；不存在则直接 Write
 4. 无需告知用户（静默执行）
 
+## 错误日志规范
+
+**遇到任何开发/运行时错误，必须自动追加到 `.draftgo/error/YYYY-MM-DD.txt`：**
+
+格式：`[HH:MM:SS] [错误类型] 描述`
+
+示例：
+```
+[14:23:45] [同步失败] pages/123 同步到服务器失败：401 Unauthorized
+[14:30:12] [API错误] GET /api/db/patient 返回 500：数据库连接超时
+[15:10:33] [页面错误] admin-users.html 第 42 行：App is not a function
+```
+
+操作流程：
+1. 捕获错误后，获取当前日期和时间
+2. 检查 `.draftgo/error/YYYY-MM-DD.txt` 是否存在
+3. 存在则 Read 后追加新行；不存在则直接 Write
+4. 无需告知用户（静默执行）
+
+---
+
 ## 自动同步规范
 
 > **每次修改页面或导航栏 HTML 后，必须立即自动同步到服务器。这是强制步骤，不得跳过，不得等用户提醒。**
 
+### 同步支持的类型
+
+同步脚本覆盖 init 拉取的全部 8 种类型：
+
+| 类型 | 命令 | 说明 |
+|---|---|---|
+| pages | `python <skill_scripts>/draftgo_sync.py pages [page_id]` | 页面同步 |
+| nav | `python <skill_scripts>/draftgo_sync.py nav [nav_id]` | 导航栏同步 |
+| db_meta | `python <skill_scripts>/draftgo_sync.py db_meta [id]` | 数据库元数据同步 |
+| aihub | `python <skill_scripts>/draftgo_sync.py aihub [id]` | AI 资产同步 |
+| external_apis | `python <skill_scripts>/draftgo_sync.py external_apis [id]` | 外部 API 注册同步 |
+| system_config | `python <skill_scripts>/draftgo_sync.py system_config [config_key]` | 系统配置同步 |
+| roles | `python <skill_scripts>/draftgo_sync.py roles [id]` | ⚠️ 需向用户二次确认 |
+| users | `python <skill_scripts>/draftgo_sync.py users [id]` | ⚠️ 需向用户二次确认（不下发 password / role_ids） |
+
+> `<skill_scripts>` 为同步脚本实际路径，取决于安装方式（`.draftgo/skill/scripts/` 或 `.claude/skills/draftgo/scripts/`）。
+
 ### 同步规则
 
-- 修改了哪个页面的 HTML → 同步该页面：`python .draftgo/skill/scripts/draftgo_sync.py pages <page_id>`
-- 修改了哪个导航栏的 HTML → 同步该导航：`python .draftgo/skill/scripts/draftgo_sync.py nav <nav_id>`
+- 修改了哪个页面的 HTML → 同步该页面：`python <skill_scripts>/draftgo_sync.py pages <page_id>`
+- 修改了哪个导航栏的 HTML → 同步该导航：`python <skill_scripts>/draftgo_sync.py nav <nav_id>`
+- 修改了 DB Meta / AI 资产 / 外部 API / 系统配置 → 用对应模式同步：`python <skill_scripts>/draftgo_sync.py <mode> <id>`
+- 修改了 roles/users → **必须先向用户确认**，确认后再运行 `roles` / `users` 模式
 - 同时修改多个 → 逐个同步
 - 同步失败时告知用户，不得静默忽略
 
+### ⚠️ roles / users 同步注意事项
+
+roles 和 users 涉及权限与账号安全，虽然脚本已支持，**仍必须人工确认后执行**：
+1. 告知用户即将同步的变更内容（角色名/权限变更 或 用户信息变更）
+2. **等待用户明确确认**后，再运行 `draftgo_sync.py roles` / `users`
+3. 用户拒绝则不同步，仅保留本地修改
+
 ### 完整操作顺序（每次开发任务结束时）
 
 1. 写迭代记录（静默）
-2. 运行同步脚本（必须执行）
+2. 运行同步脚本 / 调用 API（必须执行，roles/users 需二次确认）
 3. 告知用户同步结果
+
+---
+
+## 同步命令快捷入口
+
+- `/draftgo sync pages` — 触发 sync skill
+- `/draftgo sync nav` — 触发 sync skill
+- `/draftgo sync db_meta` — 触发 sync skill
+- `/draftgo sync aihub` — 触发 sync skill
+- `/draftgo sync external_apis` — 触发 sync skill
+- `/draftgo sync system_config` — 触发 sync skill
+- `/draftgo sync roles` — 触发 sync skill（需人工确认）
+- `/draftgo sync users` — 触发 sync skill（需人工确认）
+- `/draftgo init` — 触发 init skill

package/resources/skill/init/SKILL.md

@@ -38,12 +38,12 @@ allowed-tools: Bash(python:*), Bash(find:*), Read
 
 ---
 
-## 第三步：读取结果
+## 第三步：确认结果
 
-脚本执行完毕后，只读取 `CLAUDE.md` 确认生成成功：
+脚本执行完毕后，确认 `.draftgo/config.json` 生成成功：
 
 ```
-!test -f CLAUDE.md && echo "OK" || echo "FAIL"
+!test -f .draftgo/config.json && echo "OK" || echo "FAIL"
 ```
 
 ---
@@ -58,6 +58,9 @@ allowed-tools: Bash(python:*), Bash(find:*), Read
 
 ## 完成提示
 
-将脚本的输出摘要（页面数、导航数、服务器地址）告知用户，并提示：
+将脚本的输出摘要（页面数、导航数、外部 API 数、服务器地址）告知用户，并提示：
 - 下一步：描述要开发的功能，或运行 `/draftgo sync` 同步修改
 - 如需刷新数据：重新运行 `/draftgo init`
+- 已拉取的外部 API 列表存于 `.draftgo/external_apis/index.json`（`auth_config` 已脱敏，仅供 AI 了解可调用 API；如需新增/修改请走管理端 API，详见根 SKILL.md "用自然语言注册/管理外部 API"）
+
+> 注意：拉取 `external_apis` 需要 SAT 具备 admin 权限。若该项返回 0 条且用户期望应有数据，提醒用户检查 token 角色。

package/resources/skill/rules/frontend.md

@@ -253,10 +253,29 @@ App.showLoading(); await someAsyncOp(); App.hideLoading();
 
 // 文件上传
 const result = await App.uploadFile(file, progress => console.log(progress));
+
+// 外部 API 调用（已注册到「外部 API 接入」）
+// 认证由后端注入；不要在页面里写 API Key / Bearer
+const r = await App.callApi('weather-now', {
+  path_params: { city: 'beijing' },   // 替换 path 模板里的 {city}
+  query_params: { unit: 'metric' },
+  // body: { ... },                    // POST/PUT/PATCH 才生效
+  // headers: { 'X-Trace': 't1' },     // 不会覆盖后端注入的认证头
+});
+// 返回：{ status_code, headers, body, duration_ms, error }
+// body 已按 Content-Type 自动解析；上游业务错误看 status_code，不是 error
+
+// 列出当前用户可调用的外部 API（含 code / name / 各 JSON Schema）
+const apis = await App.listApis();
 ```
 
 路径解析：`https://...` 直接请求 · `/api/...` 拼接 origin · 其他相对路径拼接 apiBase
 
+**外部 API 注意事项：**
+- code 不知道时先 `await App.listApis()` 查询
+- `r.error` 仅在代理层错误（超时 / 网络 / 校验失败）时非空
+- API 未注册 / 已禁用 / 无权限 → 后端以 4xx 抛错，会被 `App.callApi` 当成异常 throw
+
 ---
 
 ## 颜色 Token（强制）

package/resources/skill/scripts/draftgo_init.py

@@ -104,14 +104,7 @@ def explode_html_field(out_dir, raw, html_field, fname_prefix, rel_prefix):
     return len(index)
 
 
-def build_claude_md(server, script_dir):
-    """复制 skill 的 CLAUDE.md 模板，仅替换服务器地址。"""
-    template_path = script_dir.parent / "CLAUDE.md"
-    if not template_path.exists():
-        return f"# DraftGo 项目上下文\n\n> 由 draftgo-init 自动生成。\n\n## 连接信息\n- 服务器：{server}\n"
-    content = template_path.read_text(encoding="utf-8")
-    content = content.replace("https://dev.draftgo.cn", server)
-    return content
+
 
 
 def main():
@@ -150,6 +143,7 @@ def main():
         "users":         "/api/users?page=1&page_size=500",
         "db_meta":       "/api/db-meta",
         "aihub":         "/api/aihub",
+        "external_apis": "/api/external-apis?page=1&page_size=500",
         "system_config": "/api/system/config",
     }
     raw = {}
@@ -172,8 +166,17 @@ def main():
     )
     print(f"  OK .draftgo/navigations/ ({counts['navigations']} navs)")
 
-    for name in ("roles", "users", "db_meta", "aihub", "system_config"):
+    for name in ("roles", "users", "db_meta", "aihub", "external_apis", "system_config"):
         items = extract_items(raw[name])
+        if name == "external_apis" and items:
+            # 列表接口仅返回 summary，缺 param_schema/headers/auth_config；
+            # 逐个 GET 详情合并，确保 AI 上下文包含调用所需 schema。
+            hydrated = []
+            for it in items:
+                api_id = it.get("id")
+                detail = fetch(server, token, f"/api/external-apis/{api_id}") if api_id else None
+                hydrated.append({**it, **detail} if isinstance(detail, dict) else it)
+            items = hydrated
         write_index(dg_dir / name, items)
         counts[name] = len(items)
         print(f"  OK .draftgo/{name}/ ({counts[name]} items)")
@@ -184,7 +187,6 @@ def main():
 
     # rules 已经由 CLI 安装到 .draftgo/skill/rules/，这里不再重复写入。
 
-    (root / "CLAUDE.md").write_text(build_claude_md(server, SCRIPT_DIR), encoding="utf-8")
     print(f"\nDone: {counts['pages']} pages, {counts['navigations']} navs, server: {server}")