draftgo-cli 1.0.0

package/resources/skill/rules/frontend.md

@@ -0,0 +1,462 @@
+---
+name: draftgo-frontend-rules
+description: DraftGo frontend page development rules.
+version: 1.0.0
+---
+
+# DraftGo 前端开发规范
+
+## 架构认知
+
+DraftGo 前端**不是传统 SPA**：
+- 业务页面 HTML 存在数据库，运行在 `iframe.srcdoc`
+- 导航栏 HTML 存在数据库，由壳层按需加载
+- 页面通过 `window.parent.App` 调用平台能力
+
+---
+
+## 运行时机制（Runtime）
+
+### 壳层启动流程
+
+壳层入口（`frontend/src/core/runtime.js`）调用 `createAppRuntime()` 完成以下初始化：
+
+1. `reloadSystemConfig()` — 拉取 `/api/system/config`，填充 `state.config`
+2. `validateToken()` — 验证 `localStorage.dg_access_token`，成功后设置 `currentUser`
+3. `loadSetupStatus()` — 检查系统是否已初始化（`/api/system/setup/status`）
+4. `loadPage()` — 根据当前路由拉取页面 HTML，注入 iframe
+
+### iframe 注入机制
+
+壳层通过 `decorateFrameHtml(html, routeContext, theme)` 处理页面 HTML，注入：
+- `window.__DG_ROUTE_CONTEXT__` — 当前路由上下文（含 `query` 参数）
+- 主题 CSS 变量
+- 静态资源（Tailwind、FontAwesome 等）
+
+页面 HTML 以 `iframe.srcdoc` 方式渲染，**不是独立 URL**，因此：
+- `window.location` 指向壳层地址，不可用于读取路由参数
+- `window.parent.App` 是壳层暴露的能力对象
+
+### App 对象来源
+
+壳层将 `app` 对象赋值给 `window.App`（通过 `Object.assign(app, ...)`），页面内通过 `window.parent.App` 访问。
+
+`app` 对象包含以下模块（均已合并到顶层）：
+
+| 属性/方法 | 来源模块 | 说明 |
+|---|---|---|
+| `get/post/put/patch/delete` | `api.js` | HTTP 请求，自动携带 token |
+| `uploadFile(file, onProgress)` | `api.js` | 文件上传 |
+| `toast(msg, type?, duration?)` | `feedback.js` | Toast 通知（type: success/error/warning/info，默认 info） |
+| `showSuccess(msg)` | `feedback.js` | 成功 Toast 3000ms ✓ |
+| `showError(msg)` | `feedback.js` | 错误 Toast 4000ms ✕ |
+| `showWarning(msg)` | `feedback.js` | 警告 Toast 3000ms ⚠ |
+| `showInfo(msg)` | `feedback.js` | 信息 Toast 3000ms ℹ |
+| `confirm(msg, title?)` | `feedback.js` | 确认弹窗，返回 Promise\<boolean\> |
+| `showModal(msg, title?)` | `feedback.js` | 信息模态框，带确定按钮 |
+| `showLoading() / hideLoading()` | `feedback.js` | 全局 loading 蒙层 |
+| `navigate(route)` | `runtime.js` | 路由跳转（pushState） |
+| `getCurrentRoute()` | `runtime.js` | 当前路径字符串 |
+| `getCurrentRouteContext()` | `runtime.js` | 完整路由上下文（含 query） |
+| `logout()` | `runtime.js` | 登出并跳转登录页 |
+| `setAuthTokens({access_token, refresh_token})` | `runtime.js` | 登录后写入 token |
+| `applyTheme(theme)` | `runtime.js` | 切换主题（light/dark），同步写 localStorage + iframe |
+| `t(key, fallback?)` | `i18n.js` | 国际化文本 |
+| `currentUser` | state | 当前用户对象（未登录为 null） |
+| `isAdmin` | state | 是否管理员 |
+| `isAuthenticated` | state | 是否已认证 |
+| `hasToken` | state | 是否有 token（含未验证） |
+| `config` | state | 系统配置键值对 |
+| `theme` | state | 当前主题名（`'light'` \| `'dark'`） |
+
+### Token 存储
+
+| key | 说明 |
+|---|---|
+| `localStorage.dg_access_token` | 访问 token |
+| `localStorage.dg_refresh_token` | 刷新 token |
+
+登录成功后调用 `App.setAuthTokens({ access_token, refresh_token })` 写入并触发验证。
+
+### 全局事件
+
+| 事件名 | 触发时机 |
+|---|---|
+| `dg:auth-ready` | token 验证完成（成功或失败） |
+| `dg:auth-changed` | token 变更（登录/登出） |
+
+页面内监听：`window.parent.addEventListener('dg:auth-ready', handler)`
+
+### API 请求路径解析规则
+
+`App.get/post/...` 的路径参数解析（来自 `api.js`）：
+
+| 传入值 | 实际请求 |
+|---|---|
+| `'pages'` | `{apiBase}/api/pages` |
+| `'pages/123'` | `{apiBase}/api/pages/123` |
+| `'/api/pages'` | `{apiBase}/api/pages` |
+| `'https://...'` | 直接请求（绝对 URL） |
+
+### GET 请求筛选范式
+
+**分页**（绝大多数列表接口）：
+
+```javascript
+App.get('users', { page: 1, page_size: 20 })
+App.get('pages/', { page: 1, page_size: 20 })
+```
+
+> 分页参数统一使用 `page` 与 `page_size`。GET 列表请求若不携带这两个参数，则返回全量数据；当数据量超过 10000 条时后端会拒绝并返回 400，此时必须传入 `page` 与 `page_size`。
+
+**通用筛选参数**：
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `page` | int | 页码，从 1 开始 |
+| `page_size` | int | 每页条数 |
+| `search` | string | 全文搜索（users/roles/pages/navigations/feedback/db） |
+| `status` | string | 状态过滤（`active`/`inactive`/`published` 等，按资源而定） |
+| `type` | string | 类型过滤（notices/feedback/aihub） |
+| `tag` | string | 标签过滤（pages/aihub） |
+
+**典型示例**：
+
+```javascript
+// 用户列表，带搜索+状态+角色过滤
+App.get('users', { page: 1, page_size: 20, search: 'alice', status: 'active', role_id: 3 })
+
+// 页面列表，带标签+状态过滤
+App.get('pages/', { page: 1, page_size: 20, search: 'home', tag: 'blog', status: 'published' })
+
+// 动态 DB 数据
+App.get(`db/${type}`, { page: 1, page_size: 20, search: 'keyword' })
+```
+
+**DB Meta 说明**：涉及动态数据库操作前，先读取 `db_meta/index.json` 了解当前项目有哪些 DB 类型（`type` 字段），再调用 `/api/db/{type}` 进行 CRUD。不要硬编码 type 值。
+
+---
+
+---
+
+## 页面资产开发
+
+### 必须
+- 完整 HTML 文档结构（`<html><head><body>`）
+- 静态资源优先使用本地路径：
+  ```html
+  <script src="/assets/tailwindcss.js"></script>
+  <link href="/assets/fontawesome/css/all.min.css" rel="stylesheet">
+  ```
+- 颜色全部用语义 token（见下方"颜色 Token"）
+- 弹窗用 `App.confirm()` / `App.toast()`
+- 页面初始渲染必须展示默认状态，不能因网络请求延迟导致空白
+
+### 禁止
+- 禁止引用境外 CDN（`fonts.googleapis.com`、`cdn.jsdelivr.net`、`cdnjs.cloudflare.com`、`unpkg.com` 等）
+- 如需外部 CDN，只允许国内镜像（`npmmirror.com`、`staticfile.net`），且优先用本地资源
+- 禁止 `window.alert()` / `window.confirm()` / `window.prompt()`
+- 禁止在页面内渲染系统 Header、Logo、用户头像下拉等全局导航元素
+- 禁止 `App()` 写法（`App` 是对象不是函数）
+- 禁止 `const App = () => window.parent?.App`（正确：`const App = window.parent?.App`）
+
+### 本地静态资源清单
+
+| 路径 | 说明 |
+|---|---|
+| `/assets/tailwindcss.js` | Tailwind CSS 运行时 |
+| `/assets/fontawesome/css/all.min.css` | FontAwesome 6 图标库 |
+| `/assets/fonts/inter.css` | Inter 字体 |
+| `/assets/fonts/lexend.css` | Lexend 字体 |
+| `/assets/fonts/plus-jakarta-sans.css` | Plus Jakarta Sans 字体 |
+| `/assets/fonts/plus-jakarta-sans-jetbrains-mono.css` | Plus Jakarta Sans + JetBrains Mono 等宽 |
+| `/assets/vendor/marked/marked.min.js` | Markdown 解析 |
+| `/assets/vendor/prism/prism.min.js` | 代码语法高亮 |
+| `/assets/vendor/prism/themes/prism-tomorrow.min.css` | Prism 主题 |
+| `/assets/vendor/prism/components/prism-python.min.js` | Prism Python 语言支持 |
+| `/assets/vendor/prism/components/prism-json.min.js` | Prism JSON 语言支持 |
+| `/assets/vendor/prism/components/prism-yaml.min.js` | Prism YAML 语言支持 |
+
+---
+
+## URL 参数读取
+
+页面运行在 `iframe.srcdoc` 中，`window.location.search` 不可靠——它指向壳层地址，不是页面路由。
+
+### 注入机制
+
+壳层通过 `decorateFrameHtml()` 向每个页面注入 `<script data-dg-route-bridge>`，该脚本将路由上下文写入 iframe 的 `window`：
+
+- `window.__DG_ROUTE_CONTEXT__` — 完整路由上下文（冻结对象），含 `query`、`route`、`params` 等
+- `window.__DG_QUERY__` — `routeContext.query` 的快捷方式
+- `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式的兜底读取
+
+### 标准读取方式（三阶回落）
+
+```javascript
+const routeContext =
+  window.__DG_ROUTE_CONTEXT__        // 首选：bridge 注入的主变量
+  || window.__DG_GET_ROUTE_CONTEXT__?.()  // 备选：函数兜底
+  || window.parent?.App?.getCurrentRouteContext?.()  // 三选：壳层 API
+  || { query: {} };                  // 兜底：空对象防崩溃
+const query = routeContext.query || {};
+
+// 使用示例
+// 路由 /doctor/prescription-estimate?patientId=42&visitId=7
+const patientId = query.patientId;  // "42"
+const visitId = query.visitId;      // "7"
+```
+
+### 禁止
+
+- `new URLSearchParams(window.location.search)` — iframe 中取不到壳层 URL
+- `window.location.search` 直接解析 — 同上
+
+### 常见陷阱
+
+页面 JS 中引用 `window.__DG_ROUTE_CONTEXT__` 是**读取**操作。框架注入 bridge 的检测基于 `<script data-dg-route-bridge>` 标记，不会因页面代码读取该变量而误判跳过注入。
+
+---
+
+## 平台能力调用（App API）
+
+```javascript
+const App = window.parent?.App;
+
+// GET（第二参数为 query params）
+const data = await App.get('pages', { page: 1, page_size: 20 });
+
+// POST / PUT / PATCH / DELETE
+await App.post('feedback', { type: 'bug', title: '标题' });
+await App.put('pages/123', { title: '新标题' });
+await App.delete('pages/123');
+
+// Toast（推荐用便捷方法，默认时长更合理）
+App.toast('操作成功', 'success');            // 通用方法，type 默认 'info'
+App.showSuccess('操作成功');                  // 绿色 ✓ 3000ms
+App.showError('操作失败');                    // 红色 ✕ 4000ms
+App.showWarning('请注意');                    // 黄色 ⚠ 3000ms
+App.showInfo('提示信息');                     // 蓝色 ℹ 3000ms
+// 特性：玻璃质感、顶部居中弹入、进度条倒计时、hover 暂停、× 按钮关闭、明暗适配
+
+// 确认弹窗（玻璃蒙层 + 弹跳动画入、动画出，⚠ 图标，两个按钮）
+const ok = await App.confirm('确认删除？', '删除确认');
+if (!ok) return;
+// App.confirm(msg, title?) — 返回 Promise<boolean>，取消/点击蒙层返回 false
+
+// 信息模态框（玻璃蒙层 + 弹跳动画，i 图标，单按钮）
+App.showModal('Token 详情内容', 'Token 明细');
+// App.showModal(msg, title?) — 替代 window.alert()
+
+// Loading 蒙层
+App.showLoading(); await someAsyncOp(); App.hideLoading();
+
+// 文件上传
+const result = await App.uploadFile(file, progress => console.log(progress));
+```
+
+路径解析：`https://...` 直接请求 · `/api/...` 拼接 origin · 其他相对路径拼接 apiBase
+
+---
+
+## 颜色 Token（强制）
+
+禁止硬编码任何 hex / rgb / rgba / hsl 值。
+
+| Token | 用途 |
+|---|---|
+| `--dg-bg-base` | 页面底色 |
+| `--dg-bg-page` | 内容区背景 |
+| `--dg-bg-surface` | 卡片/面板背景 |
+| `--dg-text-primary` | 主文字 |
+| `--dg-text-secondary` | 次要文字 |
+| `--dg-text-muted` | 弱化文字 |
+| `--dg-accent` | 主题色 |
+| `--dg-accent-hover` | 主题色 hover |
+| `--dg-border` | 边框 |
+| `--dg-success/error/warning/info` | 状态色 |
+
+例外：SVG 的 `fill`/`stroke` 可用 `currentColor` 或 `var(--dg-accent)`。
+
+---
+
+## 主题机制（App.theme / App.colorScheme）
+
+### 概念分层
+
+| 概念 | 键 | 取值 | 说明 |
+|---|---|---|---|
+| 显示模式 | `App.theme` / `dg_theme` | `'light'` \| `'dark'` | 亮色/暗色 |
+| 配色方案 | `App.colorScheme` / `dg_color_scheme` | `'dark-gray-white'` \| `'deep-blue-white'` \| `'orange-white'` \| `'custom'` | light 模式下的色彩搭配 |
+
+### 内置配色方案
+
+| 方案 | 键 | 主题色 | 特点 |
+|---|---|---|---|
+| 深灰白（默认） | `dark-gray-white` | #27272a 深灰 | 冷调深灰，干净利落 |
+| 深蓝白 | `deep-blue-white` | #1e3a5f 深蓝 | 专业稳重，企业风格 |
+| 橙白 | `orange-white` | #ea580c 活力橙 | 温暖醒目，创意风格 |
+| 自定义 | `custom` | 用户自选 | 基于预设微调配色 |
+
+### 入场主题
+
+页面以 `iframe.srcdoc` 渲染，壳层在注入 HTML 时已将当前主题的 CSS 变量写入 `<head>` 最顶部。
+
+**页面无需任何初始化代码**，CSS 变量在 DOM 解析时已生效，直接用 `var(--dg-*)` 即可。
+
+### 读取当前主题
+
+```javascript
+const App = window.parent?.App;
+const theme = App?.theme;          // 'light' | 'dark'
+const scheme = App?.colorScheme;   // 'dark-gray-white' | 'deep-blue-white' | 'orange-white' | 'custom'
+```
+
+仅在需要**按主题做 JS 逻辑分支**时才读取，纯样式差异用 CSS 变量解决。
+
+### 切换主题
+
+```javascript
+App.applyTheme('dark');                             // 切换显示模式
+App.setColorScheme('deep-blue-white');              // 切换为预设方案
+App.setColorScheme('custom', customVarsObject);     // 应用自定义配色
+```
+
+调用后：壳层更新 CSS 变量 → 写入 localStorage → 同步注入当前 iframe。
+
+### 获取方案详情
+
+```javascript
+const info = App.getColorScheme();
+// { name: 'dark-gray-white', vars: { ... }, schemes: { ... } }
+```
+
+### 监听主题变化
+
+壳层不广播主题变更事件。如果页面需要响应用户切换主题，用 `MutationObserver` 监听根元素 CSS 变量变化，或在切换按钮的回调里手动处理。
+
+### 禁止
+
+- 禁止在页面内读取 `localStorage.dg_theme`（通过 `App.theme` 获取）
+- 禁止在页面内读取 `localStorage.dg_color_scheme`（通过 `App.colorScheme` 获取）
+- 禁止在页面内调用 `document.documentElement.style.setProperty` 设置主题变量
+- 禁止硬编码任何颜色值作为主题分支的输出
+
+---
+
+## 样式规范
+
+- 圆角统一 `rounded-md`（6px），禁止 `rounded-lg` 或更大
+- 自定义组件类名以 `-dg` 结尾（如 `input-dg`、`btn-dg-primary`）
+
+| 组件 | 类名 |
+|---|---|
+| 输入框 | `.input-dg` — `rounded-md border-slate-200 text-[13px] h-8 px-3` |
+| 主按钮 | `.btn-dg-primary` — Slate-900 风格 |
+| 次按钮 | `.btn-dg-secondary` — White/Slate-200 风格 |
+| 危险按钮 | `.btn-dg-danger` — White/Red-50 hover 风格 |
+
+---
+
+## 导航栏开发
+
+导航栏是**数据库资产**，HTML 存储在 `navigation.html` 字段，由前端 runtime 动态挂载。
+
+### 导航类型
+
+| 类型 | 根元素 | 必填属性 | 布局 |
+|---|---|---|---|
+| 顶栏 | `<header>` | `data-nav-position="top"` | 顶部，高度 64px |
+| 侧边 | `<aside>` | `data-nav-position="side"` | 左侧，宽度 260px |
+
+### 必须
+- 根元素加 `data-nav-position="top|side"`
+- 所有导航链接必须用 `data-page-route`：
+  ```html
+  <a href="/dashboard" data-page-route="/dashboard">仪表盘</a>
+  ```
+
+### 导航专用颜色 Token
+
+| 变量 | 用途 |
+|---|---|
+| `var(--dg-bg-topnav, #fff)` | 导航背景色 |
+| `var(--dg-bg-topnav-hover, #f3f4f6)` | 悬停背景色 |
+| `var(--dg-text-topnav, #111827)` | 主文字 |
+| `var(--dg-text-topnav-muted, #6b7280)` | 次要文字 |
+| `var(--dg-border-topnav, #e5e7eb)` | 边框 |
+| `var(--dg-bg-nav, #fff)` | 侧边栏背景（side 专用） |
+
+### 顶栏模板
+
+```html
+<header data-nav-position="top" style="
+  width:100%; height:64px; box-sizing:border-box;
+  display:flex; align-items:center; justify-content:space-between;
+  padding:0 24px;
+  background:var(--dg-bg-topnav,#fff);
+  border-bottom:1px solid var(--dg-border-topnav,#e5e7eb);
+  position:sticky; top:0; z-index:50;
+">
+  <div style="display:flex;align-items:center;gap:16px;">
+    <span style="font-size:18px;font-weight:700;color:var(--dg-text-topnav,#111827);">应用名称</span>
+    <nav style="display:flex;align-items:center;gap:4px;">
+      <a href="/dashboard" data-page-route="/dashboard"
+         style="padding:8px 14px;border-radius:6px;color:var(--dg-text-topnav-muted,#6b7280);text-decoration:none;font-size:14px;font-weight:500;">
+        仪表盘
+      </a>
+    </nav>
+  </div>
+  <div style="display:flex;align-items:center;gap:8px;"><!-- 右侧操作区 --></div>
+</header>
+```
+
+### 侧边栏模板
+
+```html
+<aside data-nav-position="side" style="
+  width:100%; height:100%; box-sizing:border-box;
+  background:var(--dg-bg-nav,#fff);
+  display:flex; flex-direction:column;
+  border-right:1px solid var(--dg-border-topnav,#e2e8f0);
+">
+  <div style="padding:20px;border-bottom:1px solid var(--dg-border-topnav,#e2e8f0);">
+    <span style="font-size:16px;font-weight:700;color:var(--dg-text-topnav,#111827);">应用名称</span>
+  </div>
+  <nav style="flex:1;padding:12px;display:flex;flex-direction:column;gap:4px;overflow-y:auto;">
+    <a href="/dashboard" data-page-route="/dashboard" style="
+      display:flex;align-items:center;gap:10px;
+      padding:10px 12px;border-radius:6px;
+      color:var(--dg-text-topnav-muted,#6b7280);
+      text-decoration:none;font-size:14px;font-weight:500;">
+      仪表盘
+    </a>
+  </nav>
+</aside>
+```
+
+### 常见错误
+
+| 错误 | 原因 | 修复 |
+|---|---|---|
+| 导航不显示 | `status` 为 `inactive` | 改为 `active` |
+| 布局错乱 | 缺少 `data-nav-position` | 在根元素加上该属性 |
+| 链接点击无效 | 缺少 `data-page-route` | 在 `<a>` 上加该属性 |
+| 主题切换后颜色异常 | 使用了硬编码颜色 | 改用 `var(--dg-*)` 变量 |
+
+---
+
+## 退出登录
+
+```javascript
+window.location.href = '/login';  // 正确：完整刷新，导航栏重新加载
+// 错误：navigate('/login')  — 导航栏不会更新
+```
+
+---
+
+## 加载体验
+
+- 推荐骨架屏占位（`bg-slate-100`）
+- 禁止因网络请求失败导致整个页面空白
+- 页面初始化必须先渲染默认状态，再异步填充数据

package/resources/skill/scripts/draftgo_init.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+DraftGo Init Script
+拉取云端数据，生成本地开发上下文文件。
+
+用法：
+  python draftgo_init.py --server https://xxx --token yyy [project_dir]
+
+默认项目根：从脚本所在目录向上查找第一个包含 `.draftgo/` 的目录，
+兼容新旧两种安装位置（.draftgo/skill/scripts/ 与 .claude/skills/draftgo/scripts/）。
+"""
+import argparse, json, sys
+from pathlib import Path
+import urllib.request, urllib.error
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+
+def find_project_root(start: Path) -> Path:
+    """向上查找包含 `.draftgo/` 的目录作为项目根。找不到则回退到原有层级（parents[3]）。"""
+    cur = start
+    for _ in range(10):
+        if (cur / ".draftgo").is_dir():
+            return cur
+        if cur.parent == cur:
+            break
+        cur = cur.parent
+    # Fallback：旧安装位置 .claude/skills/draftgo/scripts/ → parents[3]
+    return start.parents[3] if len(start.parents) >= 4 else start
+
+
+DEFAULT_ROOT = find_project_root(SCRIPT_DIR)
+
+
+def fetch(server, token, path):
+    url = f"{server}{path}"
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    try:
+        with urllib.request.urlopen(req, timeout=15) as r:
+            return json.loads(r.read())
+    except urllib.error.HTTPError as e:
+        print(f"  ✗ {path} → HTTP {e.code}", file=sys.stderr)
+        return None
+    except Exception as e:
+        print(f"  ✗ {path} → {e}", file=sys.stderr)
+        return None
+
+
+def extract_items(raw):
+    if isinstance(raw, list):
+        return raw
+    if isinstance(raw, dict):
+        for key in ("items", "results"):
+            v = raw.get(key)
+            if isinstance(v, list):
+                return v
+        d = raw.get("data")
+        if isinstance(d, list):
+            return d
+        if isinstance(d, dict):
+            return d.get("items", [])
+    return []
+
+
+def safe_slug(s):
+    return str(s).strip("/").replace("/", "_") or "root"
+
+
+def write_index(folder, items):
+    folder.mkdir(parents=True, exist_ok=True)
+    (folder / "index.json").write_text(
+        json.dumps(items, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+
+def explode_pages(out_dir, raw):
+    items = extract_items(raw)
+    index = []
+    for p in items:
+        pid = p.get("id", "x")
+        fname = f"page_{pid}_{safe_slug(p.get('route', pid))}.html"
+        html = (p.get("value") or {}).get("html", "")
+        (out_dir / fname).write_text(html, encoding="utf-8")
+        meta = {k: v for k, v in p.items() if k != "value"}
+        # 相对项目根的路径，供 sync 脚本读取
+        meta["html_file"] = f".draftgo/pages/{fname}"
+        index.append(meta)
+    write_index(out_dir, index)
+    return len(index)
+
+
+def explode_html_field(out_dir, raw, html_field, fname_prefix, rel_prefix):
+    items = extract_items(raw)
+    index = []
+    for item in items:
+        iid = item.get("id", "x")
+        name_slug = safe_slug(item.get("code") or item.get("route") or iid)
+        fname = f"{fname_prefix}_{iid}_{name_slug}.html"
+        (out_dir / fname).write_text(item.get(html_field, ""), encoding="utf-8")
+        meta = {k: v for k, v in item.items() if k != html_field}
+        meta["html_file"] = f"{rel_prefix}/{fname}"
+        index.append(meta)
+    write_index(out_dir, index)
+    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():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--server", required=True)
+    parser.add_argument("--token", required=True)
+    parser.add_argument(
+        "project_dir",
+        nargs="?",
+        default=None,
+        help="项目根目录（可选），默认自动推导",
+    )
+    args = parser.parse_args()
+
+    server = args.server.rstrip("/")
+    token = args.token
+    root = Path(args.project_dir).resolve() if args.project_dir else DEFAULT_ROOT
+    dg_dir = root / ".draftgo"
+    dg_dir.mkdir(parents=True, exist_ok=True)
+
+    (dg_dir / "config.json").write_text(
+        json.dumps({"server": server, "token": token}, indent=2),
+        encoding="utf-8",
+    )
+
+    gi = root / ".gitignore"
+    content = gi.read_text(encoding="utf-8") if gi.exists() else ""
+    if ".draftgo/config.json" not in content:
+        with gi.open("a", encoding="utf-8") as f:
+            f.write("\n.draftgo/config.json\n")
+
+    endpoints = {
+        "pages":         "/api/pages/?page=1&page_size=500",
+        "navigations":   "/api/navigations",
+        "roles":         "/api/roles",
+        "users":         "/api/users?page=1&page_size=500",
+        "db_meta":       "/api/db-meta",
+        "aihub":         "/api/aihub",
+        "system_config": "/api/system/config",
+    }
+    raw = {}
+    for name, path in endpoints.items():
+        print(f"  fetching {name}...")
+        result = fetch(server, token, path)
+        raw[name] = result if result is not None else []
+
+    counts = {}
+
+    out_pages = dg_dir / "pages"
+    out_pages.mkdir(parents=True, exist_ok=True)
+    counts["pages"] = explode_pages(out_pages, raw["pages"])
+    print(f"  OK .draftgo/pages/ ({counts['pages']} pages)")
+
+    out_navs = dg_dir / "navigations"
+    out_navs.mkdir(parents=True, exist_ok=True)
+    counts["navigations"] = explode_html_field(
+        out_navs, raw["navigations"], "html", "nav", ".draftgo/navigations"
+    )
+    print(f"  OK .draftgo/navigations/ ({counts['navigations']} navs)")
+
+    for name in ("roles", "users", "db_meta", "aihub", "system_config"):
+        items = extract_items(raw[name])
+        write_index(dg_dir / name, items)
+        counts[name] = len(items)
+        print(f"  OK .draftgo/{name}/ ({counts[name]} items)")
+
+    (dg_dir / "bugs").mkdir(parents=True, exist_ok=True)
+    (dg_dir / "iteration").mkdir(parents=True, exist_ok=True)
+    print("  OK .draftgo/bugs/ .draftgo/iteration/")
+
+    # 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}")
+
+
+if __name__ == "__main__":
+    main()