draftgo-cli 3.0.44 → 3.0.48

package/resources/skill/references/frontend.md

@@ -12,7 +12,7 @@ version: 2.0.0
 > 架构原理 → `references/architecture.md`
 > App API / Token / 路由 / 运行时 → `references/runtime.md` · `references/app-api.md`
 > 动态 DB / filters → `references/data.md`
-> 开发禁区 → `references/security.md`
+> 安全边界 → 本文件“必须 / 禁止”与 `references/runtime.md`；自定义服务权限与审计见 `references/custom-services.md`
 
 ---
 
@@ -57,7 +57,7 @@ version: 2.0.0
 
 ### 移动端与多端适配（按页面目标与影响范围）
 
-移动端适配是产品与受众判断，不是所有页面的固定验收门。公众页面、用户可能从手机访问的业务页面、已有响应式断点，或本次修改涉及布局/CSS/导航/弹窗时，应认真处理窄屏；明确的桌面工作台、仅改文案/数据逻辑、后端或脚本任务，不要机械增加移动端检查。需要窄屏布局时，可以先保证小屏可用，再在宽屏增强信息密度。
+移动端适配是产品与受众判断，不是所有页面的固定验收门。公众页面、可能从手机访问的业务页面、已有响应式断点，或本次修改涉及布局、导航和弹窗时，应认真处理窄屏；明确的桌面工作台、仅改文案或数据逻辑时，不要机械增加移动端检查。
 
 响应式实现只规定结果，不提供固定配方：
 
@@ -68,9 +68,7 @@ version: 2.0.0
 - 表格、代码和其他超宽内容应在合理边界内可访问，不能让核心操作因溢出而不可达。
 - 弹窗和抽屉在目标视口内完整可用，长内容有明确滚动边界。
 
-CLI 与 Skill 不预选容器宽度、断点、侧栏尺寸、卡片列数、标题字号、页面间距或弹窗宽度。不要为了收尾机械遍历无关视口；需要浏览器证据时按页面受众和现有断点运行 `draftgo verify-ui <url> --mobile-check auto`。只有必须依赖用户现有登录会话、浏览器扩展或真实桌面状态时才考虑 computer use。
-
----
+需要浏览器证据时按页面受众和现有断点运行 `draftgo verify-ui <url> --mobile-check auto`；不要机械遍历与任务无关的视口。
 
 ### 导航与系统页边界（强制）
 
@@ -96,6 +94,20 @@ CLI 与 Skill 不预选容器宽度、断点、侧栏尺寸、卡片列数、标
 
 ---
 
+## 页面实践经验
+
+任何前端页面的开发都应从用户体验出发，而不是只完成静态结构或功能清单。先理解用户、核心任务、使用频率、数据规模和目标设备，再自主选择信息架构、组件库、视觉语言与实现方式。
+
+- 让主要任务形成真实闭环，并为加载、空数据、错误、成功、无权限和重试等状态提供清晰反馈。
+- 主动考虑适量动效能否帮助用户理解层级、状态变化、空间关系和操作结果。没有明确体验收益时可以不用，不为动效而动效。
+- 动效可按场景使用 CSS transition/animation、Web Animations API、组件库能力或 GSAP；具体方案由 Agent 根据页面需要决定。
+- 动效不能阻塞操作、掩盖等待或造成明显布局跳动；关键状态不能只靠动画表达，并为 `prefers-reduced-motion` 提供降级。
+- 修改既有页面时尊重原有产品语言和交互习惯；新增体验应与页面目标一致，而不是机械套用统一模板。
+
+具体 GSAP 资源、插件加载和生命周期处理见下方“GSAP 动效规范”。
+
+---
+
 ## 必须 / 禁止
 
 ### 必须
@@ -107,12 +119,12 @@ CLI 与 Skill 不预选容器宽度、断点、侧栏尺寸、卡片列数、标
 - 页面初始渲染展示默认状态（骨架屏），不能因请求延迟空白
 
 ### 禁止
-- 需要 CDN 时优先使用国内镜像引入；已有本地资源时优先使用 `/assets/` 本地路径
+- ❌ 境外 CDN（googleapis / jsdelivr / cdnjs / unpkg）；优先使用 `/assets/` 本地资源，确需外部资源时使用可信的国内镜像并固定版本
 - ❌ `window.alert/confirm/prompt`
 - ❌ `App()` 写法 → ✅ `const App = window.parent?.App`
 - ❌ `window.location.search` 读参数 → ✅ `window.__DG_ROUTE_CONTEXT__.query`
 - ❌ 页面内 `window.location.href=...` 跳转 → ✅ `window.parent.location.href=...`
-- ❌ TSX/React 版组件写进数据库 HTML（数据库页面不支持 React）
+- ❌ 把 TSX、ESM import、npm 依赖或构建产物直接写进数据库 HTML；需要 React 时使用基座内置的 React UMD 与兼容组件库
 - ❌ 硬编码颜色值 → ✅ `var(--dg-*)`
 - ❌ 在业务页面实现全局浮窗/客服/统计脚本 → ✅ `frontend_global_*` 固定槽位
 - ❌ 在业务页面重写 Toast 组件 → ✅ 使用 `App.toast()`，视觉、位置、大小、透明度、时长通过 `frontend_global_toast_*` 系统配置统一调整
@@ -505,54 +517,22 @@ App.setColorScheme('deep-blue-white');
 
 ## AIHub 页面 SDK
 
-新页面需要 AI 对话 UI 时，加载完整版脚本并使用原生 `<dg-chat>`：
+新页面需要 AI 对话 UI 时，加载完整版脚本并使用 `<dg-chat>`：
 
 ```html
 <script src="/assets/draftgo-chat.js"></script>
 <dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
 ```
 
-需要动态创建时使用 `DraftGoChat.create()`：
-
-```javascript
-const chat = DraftGoChat.create('#chat-host', {
-  protocol: 'draftgo-agent',
-  agentId,
-  surface: 'inline',
-  view: 'conversation'
-});
-```
-
-完整配置、协议、事件、历史、扩展与安全约束见 `references/chat-sdk.md`。
-
-`DraftGoAI` 是同一脚本提供的旧代码兼容门面，只用于没有对话 UI 的轻量调用或图片生成：
-
-```javascript
-// 聊天（默认流式；onDelta(delta, full) 每个增量触发，Promise resolve 完整文本）
-const text = await DraftGoAI.chat(agentId, '你好', (delta, full) => render(full));
-
-// 多轮：传 sessionId 复用会话（→ body.session_id）；Agent 开启“持续对话”后服务端续写历史。不传 = 无状态单轮
-await DraftGoAI.chat(agentId, '接着上一条', handler, { sessionId: threadKey });
-
-// 图片生成（必须用 /images 接口，不要用 /chat）
-const result = await DraftGoAI.images(agentId, '生成主图', { size: '1024x1024', n: 1 });
-
-// 用户选模型
-const { user_selectable, models } = await DraftGoAI.getSelectableModels(agentId);
-await DraftGoAI.chat(agentId, '你好', handler, { model: selectedModel, sessionId: threadKey });
-```
-
-- 使用 `DraftGoAI` 前同样必须先加载 `/assets/draftgo-chat.js`；壳层不会默认注入。
-- `DraftGoAI.chat` 内部创建隐藏 `<dg-chat>`，始终流式。新页面的可见对话、附件、模型选择器、推理、历史和重生成直接使用 `<dg-chat>`。
-- Agent 的能力与 `spec` 字段（工具/子智能体/记忆/结构化输出/多模态/持续对话/ttft failover）见 `references/aihub.md`。
+动态创建使用 `DraftGoChat.create()`；无 UI 的旧代码文本调用或图片生成可使用同一脚本提供的 `DraftGoAI` 兼容门面。完整配置、事件、会话、安全约束和示例见 `references/chat-sdk.md`，Agent 能力与 `spec` 字段见 `references/aihub.md`。
 
 ---
 
 ## 退出登录
 
 ```javascript
-window.parent.location.href = '/login';  // ✅ 完整刷新，导航栏重新加载
-// App.navigate('/login') ❌ 导航栏不会更新
+const App = window.parent?.App;
+await App.logout(); // 请求服务端登出、清理认证状态、触发 auth 事件并跳转配置的登录页
 ```
 
 ---
@@ -567,29 +547,7 @@ window.parent.location.href = '/login';  // ✅ 完整刷新，导航栏重新
 
 ## 选择器与表单体验
 
-- 涉及下拉选项样式时，优先做自定义弹层菜单，确保触发态、浮层、选中态和禁用态都与页面风格一致
-- 若确实使用原生控件，只能作为退化方案，不作为首选风格；不要把系统默认下拉样式当作最终交付
-
----
-
-## 平台能力调用快速参考
-
-```javascript
-const App = window.parent?.App;
-
-// 响应信封：{ code: 200, data: <载荷>, message: "success" }
-const res = await App.get('pages'); // 全量列表；表格/后台列表建议显式传 page + page_size
-if (res.code !== 200) { App.showError(res.message); return; }
-const items = res.data.items;
-
-// 非后台管理页面读取动态 DB 业务列表：
-// 当前用户是管理员时带 scope=mine，避免业务视角拿到全量 owner 数据。
-const params = { page: 1, page_size: 20 };
-if (App.isAdmin && !App.getCurrentRoute?.()?.startsWith('/admin')) params.scope = 'mine';
-const dbRes = await App.get('db/order', params);
-
-// URL 参数（三阶回落）
-const q = (window.__DG_ROUTE_CONTEXT__ || window.__DG_GET_ROUTE_CONTEXT__?.() || App?.getCurrentRouteContext?.() || { query: {} }).query;
-```
+- 严禁使用浏览器默认的 `<select>` 控件；下拉选择必须使用组件库提供的选择器或自定义弹层菜单
+- 确保触发态、浮层、选中态、禁用态和键盘操作都与页面风格及可访问性要求一致
 
-完整 API 表 → `references/app-api.md`
+平台请求与反馈 API 见 `references/app-api.md`；iframe 路由、认证与全局层见 `references/runtime.md`；动态 DB、`scope=mine`、筛选和关系见 `references/data.md`。

package/resources/skill/references/mcp.md

@@ -25,6 +25,53 @@ MCP tool result 或参数传输；需要全文时使用 `draftgo checkout`，提
 结构化资源包括 db_meta、AIHub、system_config、roles、users、doc_categories 和自定义服务元数据。
 这些资源不 checkout，也不生成 `.draftgo/*/index.json` 镜像。
 
+## API 发现与调用
+
+静态 API 路径表不是事实来源。每次调用都按 `draftgo_api_search` → `draftgo_api_describe` → `draftgo_api_call` 执行，不能从旧文档、经验或相似 operation 猜参数。
+
+### 1. 搜索 operation
+
+```json
+{
+  "query": "需要查找的能力或路径片段",
+  "module": "可选模块",
+  "resource_type": "可选资源类型",
+  "limit": 100,
+  "cursor": "下一页游标"
+}
+```
+
+`query`、`module`、`resource_type` 可组合筛选。结果提供 `operation_id`、method、path、module、resource type、permission、risk、`destructive` 和 `idempotent`。需要完整候选集时持续读取 `next_cursor`，直到没有下一页；不要因首批搜索结果为空或同名 operation 较多就猜测端点。
+
+动态 Go 自定义服务也在同一 registry：有效的 `app.Route` 会实时物化为实际 method 与 `/api/x/{slug}/{path}` operation，module 为 `scripts_dynamic`、resource type 为 `custom_scripts`。SDK、身份继承、精确匹配和运行限制仍以 `references/custom-services.md` 为准。
+
+### 2. 描述唯一 operation
+
+```json
+{ "operation_id": "search 返回的精确 operation_id" }
+```
+
+调用前必须检查 describe 返回的 method、path、parameters、request body、responses、examples、permission、risk、`destructive`、`idempotent`、完整 `input_schema` 和 `response_policy`。路径参数放 `path`，查询参数放 `query`，JSON 请求体放 `body`，文件或表单字段放 `multipart`；只发送 schema 允许的字段。
+
+describe 缺少与本次调用有关的参数、请求体、responses、permission、risk、`input_schema` 或 `response_policy` 时停止并报告契约不完整，不得自行补字段、改走猜测路径或绕过 MCP。若多个 operation 仍可能匹配，继续缩小搜索范围，而不是任选一个。
+
+### 3. 调用
+
+```json
+{
+  "operation_id": "精确 operation_id",
+  "path": {},
+  "query": {},
+  "body": null,
+  "multipart": {},
+  "confirm": false
+}
+```
+
+仅传需要的容器。`draftgo_api_call` 会按该 operation 的 `input_schema` 拒绝未知字段，并以当前 MCP principal 执行权限检查；不要传 tenant override、SAT、Authorization 或其他凭据。高风险 operation 只有在用户意图明确、影响范围已核对时才把 `confirm` 设为 `true`；`confirm` 是 MCP 的风险确认字段，不要自行拼接 `X-Confirm-Token` 或调用旧式 reauth 流程。
+
+按 describe 的 responses 与实际 `status_code` 解析结果。标准管理 API 通常使用 `{code, data, message}`，但 OpenAI 兼容流、模型列表和自定义 Route 等响应可不同；不得对所有 operation 强套统一信封。`response_policy.checkout_required=true` 或长正文资源的完整内容必须转用 `draftgo checkout` / `draftgo commit`，不能塞进 `body`、`multipart` 或工具结果。
+
 ## CLI
 
 ```bash

package/resources/skill/references/modules.md

@@ -10,7 +10,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 |---|---|---|
 | 页面 | 数据库 HTML（`page.value.html`） | MCP 定位，`checkout pages` / `commit pages` 编辑正文 |
 | 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
-| 动态 DB | db_meta 定义 schema + `/api/db/{type}` 操作数据 | MCP `api_search` / `api_describe` / `api_call` |
+| 动态 DB | db_meta 定义 schema 并操作结构化记录 | MCP `api_search` / `api_describe` / `api_call` |
 | 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | MCP 实时 API；不创建本地镜像 |
 | AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | MCP 实时 API；不创建本地镜像 |
 | 文档中心 | Markdown/HTML 文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP |
@@ -20,12 +20,12 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 
 | 模块 | 能力 | 调用方式 |
 |---|---|---|
-| 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | `POST /api/auth/*` |
+| 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | 页面使用 `App`；服务端操作通过 MCP 实时描述接口 |
 | 角色权限 | 多角色 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/*` |
+| 通知公告 | 发布公告，支持类型/状态/分页 | MCP 实时 API |
+| 工单反馈 | 用户提交问题，支持类型/状态跟踪 | MCP 实时 API |
+| 备份恢复 | 完整/选择性备份，JSON/.dgbak 格式，支持 dry-run | MCP 实时 API |
+| 系统管理 | 系统配置 KV、存储健康、全局前端层、通知测试 | MCP 实时 API |
 
 ## 模块选型决策
 
@@ -56,7 +56,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 ## 自定义服务边界
 
 - 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
-- `route`：对外暴露 HTTP 端点，运行时路径为 `/api/x/{slug}/{path}`；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，保存或发布后要真实请求验证。
+- `route`：对外暴露 HTTP 端点；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，实际路径通过 MCP 实时发现，保存或发布后要真实请求验证。
 - `event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
 - `scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
 - 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。

package/resources/skill/references/runtime.md

@@ -21,12 +21,13 @@ read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问
 - `window.__DG_QUERY__` — `routeContext.query` 快捷方式
 - `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式兜底读取
 - 主题 CSS 变量（写入 `<head>` 最顶部，DOM 解析时即生效）
-- 静态资源（Tailwind runtime、FontAwesome、GSAP 等）
+- 组件库主题适配器；Tailwind、FontAwesome、GSAP 等其他本地资源由页面按需加载
 
 页面以 `iframe.srcdoc` 渲染，**不是独立 URL**，因此：
 - `window.location` 指向壳层地址，**不可用于读取路由参数**
 - `window.parent.App` 是壳层暴露的能力对象
 - `window.location.href = '/path'` 只跳 iframe 自身！导航必须用 `window.parent.location.href`
+- 登出必须调用 `await window.parent.App.logout()`；它会请求服务端登出、清理认证状态、触发 `dg:auth-changed`，并跳转系统配置的登录页
 
 ---
 
@@ -87,29 +88,7 @@ const orderId = query.orderId;  // "42"
 
 存储：`sys_config.category = frontend_global`
 
-| 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 |
+固定槽位覆盖总开关与安全模式、壳层 head/body/CSS/JS、iframe head、全局挂件、Toast 和滚动条配置。不要凭静态文档猜测全部键名或枚举；修改前通过 MCP 查询当前 `system_config` 契约与目标键。
 
 规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**
 

package/src/commands/help.js

@@ -14,7 +14,7 @@ function help() {
   console.log(`draftgo v${getPackageVersion()} - DraftGo workbench CLI for AI coding agents
 
 DraftGo Next frontend baseline: React + Vite.
-Database pages use standard HTML + Tailwind CSS.
+Database pages may use native web technologies or bundled component libraries.
 MCP handles live discovery and structured resources; complete page, navigation,
 and document bodies use checkout/commit outside MCP context.
 The context command combines exact local Reference sections with live MCP data;

package/src/commands/init.js

@@ -41,7 +41,7 @@ async function init(projectDir, positional, flags) {
 
   // 2) Render skill body into each target's own directory (no shared
   //    .draftgo/skill/ indirection anymore — each AI tool gets a real copy).
-  log.step('写入各 AI 工具 skill 目录（含 SKILL.md / 子技能 / references / scripts）');
+  log.step('写入各 AI 工具 skill 目录（含 SKILL.md / 子技能 / references）');
   ensureRuntime(projectDir);
   const failures = [];
   let installedCount = 0;

package/src/context/index.js

@@ -18,14 +18,6 @@ const LONG_CONTENT_RESOURCE_TYPES = Object.freeze([
 ]);
 const DB_META_LIST_PATH = '/api/db-meta';
 const DB_META_PAGE_SIZE = 100;
-const ROOT_SECTIONS = [
-  '核心边界',
-  '强制预读：Reference 优先于 MCP',
-  '并行开发与所有权',
-  '标准工作流',
-  '安全规则',
-  '验证与交付',
-];
 
 const TASK_PROFILES = Object.freeze({
   frontend: {
@@ -35,38 +27,96 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'db' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/architecture.md' },
-      { file: 'references/modules.md' },
-      { file: 'references/frontend.md' },
-      { file: 'references/runtime.md' },
-      { file: 'references/app-api.md' },
-      { file: 'references/security.md' },
-      { file: 'references/checkout.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/architecture.md',
+        headings: ['核心概念（30 秒）', 'App 对象是什么（1 分钟）', '技术栈（30 秒）'],
+      },
+      {
+        file: 'references/modules.md',
+        headings: ['可开发模块（开发者负责实现）', '平台内置模块（开箱即用，不需实现）'],
+      },
+      {
+        file: 'references/frontend.md',
+        headings: [
+          '页面开发强制规则',
+          '页面实践经验',
+          '必须 / 禁止',
+          '前端底座与组件库清单',
+          '本地静态资源清单',
+          'GSAP 动效规范',
+          '颜色 Token（强制）',
+          '导航栏开发',
+          '退出登录',
+          '加载体验',
+          '选择器与表单体验',
+        ],
+      },
+      {
+        file: 'references/runtime.md',
+        headings: [
+          'iframe 注入机制',
+          'App 对象来源',
+          'URL 参数读取（标准三阶回落）',
+          '全局事件',
+          '前端全局层',
+        ],
+      },
+      {
+        file: 'references/app-api.md',
+        headings: ['请求', '反馈', '路由', '状态', '主题', '其他'],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用'] },
+      {
+        file: 'references/checkout.md',
+        headings: ['适用范围', '命令', 'Commit 流程', '409 / 412 冲突'],
+      },
     ],
   },
   data: {
     apiQueries: [{ resource_type: 'db' }],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/modules.md' },
-      { file: 'references/data.md' },
-      { file: 'references/db-relations.md' },
-      { file: 'references/security.md' },
-      { file: 'references/mcp.md', headings: ['边界', '协议与安全'] },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/modules.md',
+        headings: ['可开发模块（开发者负责实现）', '模块选型决策'],
+      },
+      {
+        file: 'references/data.md',
+        headings: [
+          'DB Meta 结构',
+          '关联关系（ref）',
+          'CRUD 操作范式',
+          'filters 操作符',
+          'db_meta 实时契约',
+          '通用筛选参数（非动态 DB）',
+        ],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用', '协议与安全'] },
     ],
   },
   'custom-service': {
     apiQueries: [{ resource_type: 'custom_scripts' }],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/modules.md' },
-      { file: 'references/custom-services.md' },
-      { file: 'references/data.md' },
-      { file: 'references/security.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/modules.md',
+        headings: ['可开发模块（开发者负责实现）', '模块选型决策', '自定义服务边界'],
+      },
+      {
+        file: 'references/custom-services.md',
+        headings: [
+          '最小服务',
+          '资源读写',
+          '触发器',
+          '平台 SDK',
+          '权限与运行限制',
+          '实时 API',
+          '验收清单',
+        ],
+      },
+      {
+        file: 'references/data.md',
+        headings: ['自定义服务内的 draftgo.DB.Query', 'filters 操作符'],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用', '协议与安全'] },
     ],
   },
   aihub: {
@@ -75,11 +125,22 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'agents' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/aihub.md' },
-      { file: 'references/chat-sdk.md' },
-      { file: 'references/security.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/aihub.md',
+        headings: ['条目骨架', '`data.spec` 字段地图', '观测'],
+      },
+      {
+        file: 'references/chat-sdk.md',
+        headings: [
+          '最小接入',
+          '协议',
+          '配置与布局',
+          'JavaScript API 与事件',
+          '历史与会话',
+          '鉴权与安全',
+        ],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用', '协议与安全'] },
     ],
   },
   content: {
@@ -89,12 +150,12 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'docs/articles' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/architecture.md' },
-      { file: 'references/modules.md' },
-      { file: 'references/checkout.md' },
-      { file: 'references/security.md' },
-      { file: 'references/parallel.md' },
+      { file: 'references/architecture.md', headings: ['核心概念（30 秒）'] },
+      { file: 'references/modules.md', headings: ['可开发模块（开发者负责实现）'] },
+      {
+        file: 'references/checkout.md',
+        headings: ['适用范围', '命令', 'Checkout 流程', 'Commit 流程', '409 / 412 冲突'],
+      },
     ],
   },
   project: {
@@ -105,12 +166,21 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'db' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/architecture.md' },
-      { file: 'references/modules.md' },
-      { file: 'references/mcp.md' },
-      { file: 'references/checkout.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/architecture.md',
+        headings: ['核心概念（30 秒）', '为什么这样设计（1 分钟）', '技术栈（30 秒）'],
+      },
+      {
+        file: 'references/modules.md',
+        headings: [
+          '可开发模块（开发者负责实现）',
+          '平台内置模块（开箱即用，不需实现）',
+          '模块选型决策',
+          '自定义服务边界',
+        ],
+      },
+      { file: 'references/mcp.md', headings: ['边界', 'API 发现与调用', '协议与安全'] },
+      { file: 'references/checkout.md', headings: ['适用范围'] },
     ],
   },
 });

package/resources/skill/push/SKILL.md

@@ -1,62 +0,0 @@
----
-name: draftgo-commit
-description: Commit checked-out DraftGo pages, navigation, and documentation content with base-version protection, local validation, and explicit conflict handling; route structured resources through MCP and explain the limited pages/nav/docs legacy push alias.
----
-
-# DraftGo Checkout / Commit
-
-commit 是长正文的唯一正式交付动作。push pages/nav/docs 仅是兼容入口，应显示弃用提示后转发到对应的 commit；其他资源不从本地索引推送。
-
-## 选择动作
-
-| 意图 | 命令 |
-|---|---|
-| 下载页面正文 | draftgo checkout pages <id...> |
-| 下载导航正文 | draftgo checkout nav <id...> |
-| 下载文档正文 | draftgo checkout docs <id...> |
-| 检查当前工作区 | draftgo check |
-| 查看 base/local 差异 | draftgo diff <type> <id> |
-| 提交页面、导航或文档 | draftgo commit pages|nav|docs <id...> |
-| 列出冲突 | draftgo conflicts |
-| 查看冲突材料 | draftgo conflict show <type> <id> |
-| 明确解决冲突 | draftgo conflict resolve <type> <id> |
-| 只查询正文片段 | MCP search/fragment 工具 |
-| 操作结构化资源 | MCP api_search/api_describe/api_call |
-
-## Checkout
-
-1. 通过 MCP 取得元数据、content_type、base version/revision 和 base_hash。
-2. CLI 使用项目 SAT 通过专用 HTTP 流下载完整正文；正文不进入 MCP tool result。
-3. 直接流式写入同目录临时文件，完成后计算 SHA-256 并验证底座哈希。
-4. 校验成功后原子重命名到 .draftgo/worktree/ 正式路径，同时保存 .base/ 内容和 manifest。
-5. 不转换 HTML、Markdown 或原始编码；扩展名由 content_type 和底座安全扩展名决定。
-
-不得通过 MCP get、聊天上下文或 Python 旧脚本请求整篇正文。
-
-## Commit
-
-1. 读取 checkout manifest 指向的正文，计算 current_hash。
-2. 执行 draftgo check；页面改变时按需执行 draftgo verify-ui。
-3. 通过专用 HTTP 流上传正文，并携带 checkout 时的 base_version/revision 或 If-Match。
-4. 完整正文不作为 MCP tool 参数发送。
-5. 成功后原子更新 manifest、base、版本和哈希，并回读清晰的提交结果。
-6. 发生 409/412 时返回非零，停止重试和 auto-commit，保留 local/base 并生成 remote 及冲突 manifest。
-
-单个 commit 成功不自动写 changelog。主 Agent 只有在全部资源统一验证和交付成功后，才显式执行一次 `draftgo changelog add "<完成结果>"`；409/412、验证失败或其他交付失败时不得写入。
-
-## 冲突
-
-冲突目录必须包含可定位的 base、local、remote 三份材料。不要覆盖任一份，也不要手写不可靠的 HTML 合并器。Agent 或用户完成合并后，重新运行 check/verify-ui，确认最新 base，再执行 commit。
-
-## 结构化资源与兼容命令
-
-db_meta、AIHub、系统配置、角色、用户、分类和自定义服务元数据直接由 Agent 通过 MCP 操作。它们没有本地镜像、checkout manifest 或隐式 push 流程。
-
-draftgo push pages/nav/docs 可以保留为迁移兼容别名；draftgo push <other> 必须停止并提示使用 MCP。deploy 和 auto-push 若保留，只能调用当前 check + commit 语义，冲突时必须停止。
-
-## 失败处理
-
-- 缺少配置或 MCP 不可用：运行 draftgo mcp test，报告连接/SAT/底座问题；不要回退 pull。
-- 指定资源未 checkout：先通过 MCP 定位元数据，再运行 checkout；不要猜测 id。
-- 内容类型或编码未知：保留底座返回值并停止，不能强制改成 HTML/Markdown。
-- 提交返回 409/412：保留冲突状态，禁止自动覆盖、隐式 force 或自动重试。