draftgo-cli 3.0.29 → 3.0.35

package/resources/skill/SKILL.md

@@ -1,200 +1,77 @@
 ---
 name: draftgo
-description: Use this skill when the user is developing, maintaining, or debugging a DraftGo-based application. Activates for tasks involving DraftGo pages, navigation, API calls, roles, DB meta, or any DraftGo-specific development work. ALSO activates when user says "推送", "push", "同步", "sync", "推送到云端", "同步到云端", "push to server", "上传页面", "上传导航", "push pages", "push nav", "push db_meta" — route to /draftgo push skill immediately, do NOT attempt manual API calls.
+description: Use this skill when developing, maintaining, debugging, synchronizing, or delivering a DraftGo-based application, including DraftGo pages, navigation, dynamic DB, base APIs, Go custom services, AIHub, knowledge bases, Skill/MCP assets, roles, and local resources.
 ---
 
 # DraftGo 开发助手
 
-> 默认追求：**开发的急速感、逻辑与实现的完整、迭代性强**。优先交付真实落地闭环；禁止假数据/静态卡片/伪功能充当完成；禁止用很大的 `page_size` 冒充全量获取；设计页面开发，强制先读取rules/frontend.md。
+## 执行方法
 
-## ⚠️ 高权重硬规则：禁止“假获取”/伪全量分页
+1. **建立资源图**：从用户路径列出角色、入口、页面、操作、数据、服务、运营维护和验证证据，并标记资源间的依赖。
+2. **确定共享契约**：从当前 `db_meta`、底座 API、自定义服务、权限、路由和导航中确认被多个资源共同依赖的契约，再展开依赖它们的实现。
+3. **并行独立资源**：按依赖关系划分 wave。独立页面、管理页、文档和服务并行处理；共享 schema、导航、HTML 文件或调用链按依赖顺序处理。每个工作单元携带资源范围和验证方式，交付动作由汇总阶段统一执行。具体字段见 `references/parallel.md`。
+4. **汇总接线**：连接入口、页面跳转、真实数据读写、角色可见性、加载/空/错误/成功状态和运营维护路径，随后回放关键用户路径。
+5. **验证与交付**：按资源类型取得证据。完成本地验证后，根据用户交付意图或项目自动同步配置执行 `push`、`deploy` 或 `auto-push`。
 
-DraftGo 列表接口的分页语义是硬约定：**只有同时不传 `page` 和 `page_size` 才是全量返回**。只要传了 `page` 或 `page_size` 任意一个参数，就进入分页模式。
+## CLI 与场景路由
 
-- 需要完整候选集、完整配置、完整权限/角色、完整页面/导航、完整文档树、完整 AIHub 资产、完整 DB meta、完整导出/同步数据时，必须不传 `page` / `page_size`。
-- 严禁写 `{ page: 1, page_size: 500 }`、`{ page_size: 9999 }`、`?page_size=500` 这类“拿大页当全量”的假获取。数据量超过上限时一定会漏数据。
-- 只有真实的分页表格、日志列表、搜索结果页、预览卡片、首页公告等明确限量场景，才允许显式传 `page` + `page_size` 或业务 `limit`。
-- 如果既需要全量又担心数据量太大，应改成后端聚合/专门端点/逐页循环并校验 `total`，不要假装一次大分页就是全量。
-- Go 自定义服务通过 `ctx.DB.Query(type, sdk.QueryOptions{...})` 访问动态数据；完整筛选和分页契约见 `specs/custom-services.md`。
+调用 `draftgo` CLI 完成工具动作；`scripts/` 下的脚本是 CLI 内部实现，不作为 Agent 的调用入口。
 
-## ⚠️ 高权重硬规则：日期/时间分层处理
-
-任何涉及日期、时间、日历、排期、统计区间、日志时间、倒计时、到期时间、创建/更新时间展示或计算的页面、后端、自定义脚本、定时任务和文案生成，必须区分展示层与存储/业务层，避免不同时区用户看到或写入错误日期。
-
-- **展示层按用户时区显示**：面向终端用户展示 `datetime` 时，优先使用用户个人时区/浏览器时区；如果产品要求统一展示平台时间，必须在文案中标明时区。不要硬编码 `Asia/Shanghai` 或默认 UTC 直接展示给全球用户。
-- **存储层和业务规则按系统时区处理**：系统时区配置键为 `system_timezone`，运行时后端以该配置为准；未配置时才回退 `APP_TIMEZONE` / `TZ` / 默认时区。写入、统计、定时任务、账期、活动边界、自然日归属等业务规则优先按系统时区计算。
-- 生成“今天/昨天/本周/本月/到期日/开始结束日期”等相对日期时，必须先判断语义：用户视角的显示用用户时区，平台/业务视角的存储、筛选和统计用系统时区，避免跨时区导致日期早一天或晚一天。
-- 写入或查询 `date` / `datetime` 字段、构造 filters 范围、统计自然日区间时，边界必须按系统时区计算；不要用 UTC 零点、浏览器零点或本机时区零点直接当业务日期边界。
-- 后端代码优先复用统一时区工具；自定义服务和页面脚本若需要当前业务时间，也必须显式考虑系统时区，不要裸用 `new Date()` / `datetime.utcnow()` 作为业务日期依据。
-
-## ⚠️ 使用此 Skill 前必读
-
-1. **每次激活都先完整读此文件（SKILL.md）**。这里承载高频、高代价和跨任务的核心规则，不能只读摘要或凭记忆执行
-2. 根据任务场景查"快速决策树"，找到需要读的文件
-3. 不要凭记忆猜测语法，**遇到陌生 API 必读对应 spec**
-4. 涉及 filters/order_by 查询时，必须先读 `specs/data.md` 的操作符表
-5. 涉及页面、导航、管理端、DB、custom_script、AIHub 时，优先先读对应规则文档，再开始实现；已明确的小修可只读最小必要部分
-
-
-## 开发前置检查
-
-```bash
-# 确认已初始化
-test -f .draftgo/config.json && echo "OK" || echo "请先运行 /draftgo init"
-```
-
-服务器地址和 Token 从 `.draftgo/config.json` 读取。
-
-## 命令路由
-
-| 用户意图 | 路由 |
+| 场景 | DraftGo 动作 |
 |---|---|
-| 初始化项目 / `/draftgo init` | 调用 `/draftgo init` Skill |
-| 从云端拉取 / `/draftgo pull` | 调用 `/draftgo pull` Skill |
-| 推送到云端 / `/draftgo push` | 调用 `/draftgo push` Skill |
-| 构建 / 查看 Story / `/draftgo story` | 调用 `{{SKILL_DIR}}/story/SKILL.md` |
-| 查看资源地图 / `draftgo map` | 直接运行 CLI |
-| 闭环体检 / `draftgo check` | 直接运行 CLI |
-| 任何开发 / 修改 / 新建 / 修复 / 重构任务 | ↓ 见开发任务路由 |
-
-## 开发任务路由（按任务规模读取）
-
-**第一步：必读** → `{{SKILL_DIR}}/rules/dev-workflow.md`（分级：小修 / 轻功能 / 标准功能 / 高风险）
-
-**页面/业务任务额外默认动作：**
-- 做顶部导航前，通常先读 `.draftgo/navigations/index.json` 与现有导航 HTML；需要新导航时优先复制/复刻一份内置导航再改造，而不是直接破坏内置导航
-- 做导航栏时，通常同时考虑未登录/已登录/管理员三种状态，以及移动端或窄屏下的收起/展开体验；普通用户不显示管理后台入口，管理员额外显示
-- 做管理端侧边栏前，通常先读现有管理侧导航 HTML；业务管理路由优先追加到对应业务域，系统内置路由优先保留，除非用户明确要求且已确认影响范围
-- 做业务模块前，先判断是否需要管理端页面、角色路径地图和同一份真实数据；简单纯展示场景可明确降级
-- 做运营管理功能时，通常按业务域提供专门后台页面并注册到后台侧边栏；`/admin/db` 保留为底层通用数据能力，不默认承担日常运营页面
-- 做新系统 / 新板块 / 新模块前，通常先在 `.draftgo/Task/` 产出轻量 PRD，清点页面清单、功能清单、数据、入口和管理端，再继续开发
-- 修改系统内置页面前，先确认是否真的必要；非必要不触碰系统页，确需修改时说明原因和影响
-- 做首页时，通常按官网介绍、品牌门面和业务入口设计；只有用户需求或产品定位明确“进入即使用”时，才把首页设计成实际工作台
-- 做弹窗、抽屉、下拉选择器和前端动效时，优先读 `rules/frontend.md` 的交互体验规则：弹窗尽量无外层滚动条；所有可展开选择控件（Select / Dropdown / Combobox / Autocomplete / Cascader 等）禁止使用浏览器或操作系统默认的原生 `<select><option>` 展开菜单样式，必须使用自定义弹层菜单或 Ant Design 等组件库的下拉层，确保选项层、hover、selected、disabled、滚动条、边框、阴影、圆角、字号与页面视觉一致；页面体验可合理植入本地 GSAP
-- **按页面目标和改动影响决定多端适配**：面向公众、用户可能从手机访问、已有响应式断点，或本次修改涉及布局/CSS/导航/弹窗时，应考虑窄屏体验；明确的桌面工作台、仅改文案/数据逻辑、后端或脚本任务，不要机械追加移动端验收。需要浏览器证据时优先运行 `draftgo verify-ui <url> --mobile-check auto`，使用单视口 smoke check，默认仅失败时截图；不要为了收尾默认调用 computer use、手动拖动浏览器或遍历多个视口。详见 `rules/frontend.md §移动端与多端适配`
-
-| 任务类型 | 读取 |
+| 查看 Skill 安装状态或支持目标 | 运行 `draftgo status`；需要目标列表时运行 `draftgo list-targets`。 |
+| 安装、完全更新或移除 Skill | 分别运行 `draftgo init [target...]`、`draftgo update [target...]`、`draftgo uninstall <target\|all>`。 |
+| 连接已有基座 | 运行 `draftgo connect`，写入项目连接并拉取初始上下文。 |
+| 首次建立本地 Docker 基座 | 运行 `draftgo local setup`；后续使用 `draftgo local start\|stop\|logs\|status` 管理。兼容命令：`draftgo local-dev`、`draftgo local up`、`draftgo local down`。 |
+| 陌生项目、跨资源或入口不清 | 运行 `draftgo map`，再读取相关 index 和资源文件。 |
+| 本地资源缺失、过期或需要云端版本 | 使用 `pull/SKILL.md`，运行 `draftgo pull [type] [id...]`。 |
+| 新建资源 | 在对应 index 中登记不带 `id` 的完整条目并创建其引用文件；运行 `draftgo check` 后，通过 `draftgo push <type>` 创建并回读写回的 `id` 和文件路径。 |
+| 删除资源 | 确认目标 `id` 和引用后运行 `draftgo delete <type> <id>`；该命令同时删除云端资源和本地登记，随后重新运行 `map` 与 `check`。 |
+| 页面、导航、交互或布局 | 读取 `references/frontend.md` 的“前端底座与组件库清单”，确认壳层源码或数据库 HTML 页面及资源加载方式；页面运行和布局证据使用 `draftgo verify-ui <url> --mobile-check auto`。 |
+| 页面或导航 HTML | 运行 `draftgo check`，验证入口、HTML 解析和资源登记；语法异常读取 `references/debugging-syntax.md`。 |
+| 动态 DB、filters 或 order_by | 先读对应 `db_meta` schema 和 `references/data.md`。 |
+| DraftGo 底座 API | 运行 `draftgo api <keyword>`，确认请求字段、响应结构和鉴权。 |
+| 自定义服务 | 读取 `references/custom-services.md`；其中包含 AIHub、知识库、Memory、Skill/MCP 的完整 Go SDK；端点从 `slug + app.Route` 推导为 `/api/x/<slug><route-path>`。 |
+| App 对象方法 | 读取 `references/app-api.md`。 |
+| AI Agent（配置、调用、工具/子智能体/记忆/持续对话、观测） | 读取 `references/aihub.md`；页面对话 UI、协议、事件与扩展读取 `references/chat-sdk.md`；App 与旧兼容门面见 `references/app-api.md`。 |
+| 平台架构、能力边界或安全限制 | 读取 `references/architecture.md`、`references/modules.md` 或 `references/security.md`。 |
+| 同步已确认的本地改动 | 使用 `push/SKILL.md`，运行 `draftgo push <type> [id...]`。 |
+| 交付前需要结构检查或预演 | 运行 `draftgo deploy [type] [id...] --delivery local\|preview\|deploy`。 |
+| 项目明确启用自动同步 | 运行 `draftgo auto-push [type] [id...]`；批量资源使用 `--batch`，未启用 `config.auto_push` 时命令只检查并跳过推送。 |
+| 项目已有 `.draftgo/story.yaml`，且请求可能改变产品定位或既有决定 | 读取并检查冲突；需要新建或维护 Story 时调用 `story/SKILL.md`。 |
+
+## DraftGo 契约
+
+- **分页**：完整候选集、配置、资源或导出数据同时省略 `page` 和 `page_size`；真实分页列表同时传入 `page` 与 `page_size`。
+- **响应信封**：调用基座 API 时先检查 `res.code !== 200`，再读取 `res.data`。
+- **时间**：用户展示按用户/浏览器时区；存储、统计、定时和自然日边界按 `system_timezone` 计算。
+- **数据 schema**：字段名、类型、必填、searchable 和权限以 `.draftgo/db_meta/index.json` 为准；筛选和排序前确认字段与操作符兼容。
+- **自定义服务**：使用 `package main`、`Register(app *sdk.App)` 和 `func handler(draftgo *sdk.Context) (any, error)`；普通身份使用 `draftgo.Auth.CurrentUser()`，需要管理能力时逐次显式调用 `draftgo.Admin.*`。AI 能力使用 `draftgo.AIHub`、`draftgo.Knowledge`、`draftgo.Memory`；Route 权限和脚本管理权限是两层独立控制。
+- **系统资源**：登录、设置、权限、用户和系统配置属于基座资源；修改前确认影响范围并保留原有系统能力。
+
+## 资源验证
+
+| 资源 | 证据 |
 |---|---|
-| 所有开发任务 | `rules/dev-workflow.md` — 分级与执行流程 |
-| 前端页面开发 | `rules/frontend.md` — 前端规范（小修可只读相关段落） |
-| 页面功能不执行 / 报错 | `rules/debugging-syntax.md` — 排错指南（必读） |
-| 标准功能 / 高风险 / 多资源任务 | 先判断是否可并行；可并行时读 `rules/parallel.md` — 并行协议 |
-| 不了解项目结构 | 先运行 `draftgo map` |
-| 标准功能 / 高风险 · 意图模糊 | `practices/dev-declaration.md` — 开发声明协议 |
-
-## 并行开发默认策略
-
-标准功能、高风险、多页面、多资源任务开始后，主代理必须先做一次并行可行性判断：
+| 页面、导航、新资源 | 运行 `draftgo check`，并确认入口引用。 |
+| 页面运行、交互或布局 | 运行 `draftgo verify-ui <url>`。 |
+| 基座 API、动态 DB | 真实请求或回读关键状态、字段和错误处理。 |
+| 自定义服务 | 调用目标 Route 或无副作用健康端点，确认状态码与响应；涉及管理员调用时确认审计。 |
+| 删除资源 | 重新运行 `draftgo map` 与 `draftgo check`，确认入口、引用和本地文件已闭合。 |
 
-- 如果存在 2 个及以上无依赖任务，且 `resource_lock` 不冲突，读取 `rules/parallel.md` 并按 wave 并行执行
-- 如果任务共享同一页面、导航、schema、侧边栏或核心入口，先串行完成共享基础，再并行下游任务
-- 主代理负责需求判断、依赖图、资源锁、结果合并、验证和最终 push
-- 子代理只执行单个 Task，只修改声明的 `resource_lock`，不 push、不改 Task 文档、不做范围外优化
-- 并行结束后统一写 changelog、统一检查、统一 batch push
+`draftgo check` 覆盖页面入口、页面/导航 HTML 解析和本地资源登记；运行证据由对应资源的验证动作提供。
 
-优先并行的 DraftGo 任务：多个独立页面、前台页面与后台管理页面、页面与 custom_script、docs/pages/db_meta 中互不依赖的资源。
+## 本地资源
 
-禁止或谨慎并行：同一 HTML 文件、同一导航或管理侧边栏、共享 DB schema 未定型前的页面开发、需要统一视觉/交互决策的首屏/首页/核心工作台。
-
-## 快速决策树
-
-```
-要开发什么？
-├── 页面 / 导航 / 交互      → 读 rules/frontend.md
-├── 数据结构 / 动态 DB      → 读 specs/data.md
-├── 定义关联关系 / 级联删除
-│   → 读 specs/data.md §关联关系（ref）
-│   → 需要完整示例时读 specs/db-relations.md
-├── 数据检索 / 使用 filters / order_by
-│   → 先读 specs/data.md §filters操作符
-│   → 再读 quickref/api-endpoints.md 看接口契约
-├── 关联查询 / populate 填充
-│   → 读 specs/data.md §关联查询（populate）
-├── 自定义服务 / custom_script
-│   → 强制先读 specs/custom-services.md（语言、ctx、SDK、权限、运行限制）
-│   → 推送时再读 push/SKILL.md §推送自定义脚本
-│   → 涉及 ctx.DB.Query / filters 时读 specs/data.md §自定义服务内的 ctx.DB.Query
-├── API 速查               → quickref/api-endpoints.md
-├── App 方法忘了            → quickref/app-api.md
-├── 了解平台架构            → core/architecture.md
-├── 选择开发方案            → core/modules.md
-└── 查开发禁区             → specs/security.md
-```
-
-## 连接信息
-
-- 存储于 `.draftgo/config.json`（已加入 .gitignore）
-- 运行 `/draftgo init` 时写入
-
-## 收尾提醒
-
-开发 / 修改 / 修复后默认先完成本地证据，然后运行 `draftgo auto-push [type] [id...]` 作为收尾门。它始终先执行本地检查：当 `.draftgo/config.json` 的 `auto_push` 为 `true` 时自动执行 `check → push`；未设或为 `false` 时输出“已验证、未推送”的提示，不修改云端。用户明确要求 push/同步/部署时，仍可直接运行 `draftgo deploy` 或对应 push；需要预演时用 `draftgo deploy --delivery preview`。
-
-## 核心原则（硬性）
-
-- **开发分级**：任何任务先读 `rules/dev-workflow.md` 分级，再执行
-- **真实闭环**：不用假数据/伪交互充当完成；无法实现则停止并说明
-- **禁止伪全量分页**：需要全量数据时不传 `page` / `page_size`；不得用 `{ page: 1, page_size: 500 }`、`?page_size=9999` 等“大分页”假装全量。传任意分页参数都会截断为分页窗口，必须按真实全量、真实分页或逐页拉取处理
-- **日期/时间分层**：展示层面向用户时按用户个人时区/浏览器时区显示；存储层、业务规则、统计区间、定时任务和平台相对日期必须优先使用系统配置 `system_timezone`，避免日期不正确
-- **自定义服务注册闭环**：新 Go 服务实现 `Register(app *sdk.App)`；可混合 `app.Route` / `app.On` / `app.Schedule`。旧 `triggers` 字段不参与注册，route 推送后必须真实请求无副作用的 GET 端点验证不是 404
-- **自定义服务代码契约**：新服务使用 `package main` 与 `func handler(ctx *sdk.Context) (any, error)`；route 身份用 `ctx.Auth.CurrentUser()`，完整契约见 `specs/custom-services.md`
-- **自定义服务权限分层**：管理面按角色 `scripts:*` 权限授权可信编辑者；调用面仍按每个 Route 的 `permission` / `route_security` 判断，任何一层都不能替代另一层
-- **自定义服务执行身份**：Route 默认继承调用者身份；含 `user_id` / `actor_user_id` 的事件继承该用户，定时任务与无可解析用户的事件才以系统身份执行。需要管理员权限时，可信服务代码必须逐次显式调用 `draftgo.Admin.*`；该调用本身就是提升声明，会以管理员身份执行并自动写入执行审计。不得在服务源码、`go_mod`、页面或请求中嵌入 SAT。
-- **导航优先复用**：顶部导航、管理端侧边栏优先复刻/改造现有内置导航资源；仅当现有结构无法承载需求时再调整方案
-- **导航状态完整**：导航通常覆盖未登录/已登录/管理员可见性和收起/展开；普通用户不显示管理后台入口，管理员额外显示后台入口
-- **系统页谨慎修改**：登录、设置、权限、用户、系统配置等内置系统页非必要不改；确需修改时先确认影响范围
-- **业务优先考虑管理端**：案例、新闻、产品、订单、预约、资料等可维护业务内容，优先考虑前台 + 管理端 + 同一份真实数据；若明确不需要，可按更轻路径处理
-- **业务后台专页**：运营日常使用的后台能力优先做业务域管理页并注册后台侧边栏；`/admin/db` 仅作为底层通用数据入口，不默认替代业务管理页
-- **首页定位清晰**：首页通常是官网/产品介绍和入口聚合，不默认当实际工作台；用户进入即使用型产品可例外
-- **入口绑定**：新增页面必须绑定导航/首页/菜单至少一处
-- **角色路径闭环**：标准功能优先明确前台用户和管理员/运营的访问路径；极小范围改动不必强行补全完整地图
-- **规则先读再写**：页面、导航、DB、custom_script、AIHub 开发前优先读对应规则/规格；范围清晰的小修读最小必要内容即可
-- **验证按影响选择**：静态检查、结构检查和真实数据/API 回读优先；浏览器验证只在改动影响真实页面运行或布局时启用。移动端不是所有页面的固定门禁，computer use 不是默认验收工具
-- **Story 冲突**：发现与 `.draftgo/story.yaml` 冲突必须显式提示，不可静默执行
-- **changelog**：影响可见功能/跨资源/已 push 时写入 `.draftgo/changelog.md`
-- **UI 组件库**：DraftGo 已内置 Ant Design 5.29.3 UMD（`window.antd`），使用时须按顺序加载完整依赖链，仅加载同版本 `reset.css`，禁止额外引入 `antd.min.css`；强烈建议跟随 DraftGo 系统主题、弹窗走 `App.confirm/showModal`；详见 `rules/frontend.md §Ant Design 使用规范`
-- **下拉选择器硬规则**：所有“点击后展开选项”的控件都不得呈现系统默认下拉选项样式（如原生 `<select>` 的灰色/白色系统菜单）。只给 `<select>` 改边框、圆角或 `appearance: none` 不算合格，因为展开后的 `<option>` 仍是系统样式。必须改用自定义浮层菜单或 Ant Design `Select` / `Dropdown` / `TreeSelect` / `Cascader` / `DatePicker` 等组件，并完整处理 hover、选中态、禁用态、键盘可达、滚动和移动端适配。
-- **表格分页钉底硬规则**：使用固定高度 flex column 骨架；toolbar `flex-shrink:0`，中间数据区 `flex:1; min-height:0; overflow:auto`，分页栏独立放底部并 `flex-shrink:0; margin-top:auto`。禁止分页随数据内容高度下移，禁止整页滚动替代表格内部滚动。详见 `rules/frontend.md §表格数据区与分页钉底`。
-- **图标优先级**：页面需要图标时，按以下顺序选择：① 优先用内置 SVG 图标库（`/assets/icons/{name}.svg`，约 100+ 个，清单见 `manifest.json`）→ ② 其次用 FontAwesome（`/assets/fontawesome/css/all.min.css`，已内置 6.x 全套）→ ③ 两者都没有合适的，再自行解决（内联 SVG、emoji 或其他方案）
-- 页面开发优先使用内置的UI 组件库，若用户有指定命令/无法满足用户开发需求，可自主处理前端决策。
-## 本地数据目录
-
-| 目录 | 内容 |
+| 路径 | 内容 |
 |---|---|
-| `.draftgo/pages/` | index.json + .html 文件 |
-| `.draftgo/navigations/` | index.json + .html 文件 |
-| `.draftgo/db_meta/` | index.json（含 schema/permission） |
-| `.draftgo/custom_scripts/` | index.json + 脚本文件 |
-| `.draftgo/aihub/` | index.json |
-| `.draftgo/docs/articles/` | index.json + .md 文件 |
-| `.draftgo/system_config/` | index.json |
-| `.draftgo/changelog.md` | 更新日志 |
-| `.draftgo/lessons/` | 开发经验（YYYY-MM-DD-主题.md） |
-| `.draftgo/Task/` | 任务文档（仅跨资源/高风险任务） |
-
-## 文档索引
-
-| 文档 | 用途 | 优先读的场景 |
-|---|---|---|
-| `core/architecture.md` | 平台机制 | 进入陌生项目·理解平台机制（3分钟） |
-| `core/modules.md` | 功能可行性 | 评估功能可行性·选择开发路径 |
-| `specs/runtime.md` | 运行时机制 | 处理 token/路由/事件/全局层问题 |
-| `specs/data.md` | 动态 DB·filters·db_meta·关联关系 | ✅ 使用 filters 查询<br>✅ 设计 searchable 字段<br>✅ 需要范围/模糊/精确检索<br>✅ 定义关联关系和级联删除<br>✅ 使用 populate 填充关联数据 |
-| `specs/db-relations.md` | DB 关联长示例 | 需要 many-to-one / one-to-many / many-to-many、populate、onDelete 的完整示例 |
-| `specs/custom-services.md` | 自定义服务完整契约 | 编写或调试 Go 服务、handler ctx、SDK、权限、Agent 工具、事件/定时任务 |
-| `specs/security.md` | 开发禁区 | 开发禁区速查 |
-| `practices/dev-declaration.md` | 开发声明 | 标准功能/高风险任务开始前 |
-| `practices/best-practices.md` | 最佳实践 | 开发决策·Code Review |
-| `practices/anti-patterns.md` | 反模式 | 检查反模式 |
-| `quickref/app-api.md` | App API | App API 速查 |
-| `quickref/api-endpoints.md` | 后端端点 | 后端端点速查 |
-
-## 文档读取策略
-
-把规则按“漏读代价”分层，不要默认指望 AI 主动翻到正确文件：
-
-- **高频 + 高代价**：内联到 `SKILL.md`、`rules/dev-workflow.md`、`practices/dev-declaration.md` 这类必经路径
-- **低频 + 明确触发**：保留外链，但必须写清触发条件
-- **低频 + 低代价**：继续保持外链，只在需要时读
-
-结论：如果某条规则一旦漏掉就会直接影响闭环、入口、数据、权限或验证，它就不该只躺在按需阅读文件里。
+| `.draftgo/pages/` | 页面索引与 HTML |
+| `.draftgo/navigations/` | 导航索引与 HTML |
+| `.draftgo/db_meta/` | 数据 schema 与权限 |
+| `.draftgo/custom_scripts/` | 自定义服务元数据与 Go 代码 |
+| `.draftgo/aihub/` | AIHub 资源 |
+| `.draftgo/docs/articles/` | 文档元数据与 HTML |
+| `.draftgo/doc_categories/` | 文档分类 |
+| `.draftgo/system_config/` | 系统配置 |
+| `.draftgo/roles/`、`.draftgo/users/` | 角色与用户 |
+| `.draftgo/story.yaml` | 产品身份、设计和长期决策 |

package/resources/skill/init/SKILL.md

@@ -1,76 +1,28 @@
 ---
 name: draftgo-init
-description: Use this skill when the user runs "/draftgo init", wants to initialize a DraftGo development project, connect to a DraftGo server, or set up DraftGo development context for the first time.
-version: 1.0.0
-allowed-tools: Bash(python:*), Bash(find:*), Read
+description: Install or refresh the DraftGo skill in a project, inspect supported AI-tool targets, and bind the project to an existing or local DraftGo base.
 ---
 
-# DraftGo 项目初始化
+# DraftGo 初始化
 
-## 第一步：收集连接信息
+使用公开 CLI 完成安装和连接，不直接调用 `scripts/` 下的内部脚本。
 
-检查是否已有配置：
+## 执行
 
-```
-!test -f .draftgo/config.json && cat .draftgo/config.json || echo "NOT_FOUND"
-```
+1. 运行 `draftgo status` 查看已安装目标和 Skill 版本。
+2. 需要查看支持的 AI 工具时，运行 `draftgo list-targets`。
+3. 尚未安装时运行 `draftgo init [target...]`；不指定 target 时由 CLI 自动识别。
+4. 已安装但需要刷新时运行 `draftgo update [target...]`，该命令同时完全更新全局 CLI 与已安装 Skill。
+5. 项目缺少 `.draftgo/config.json` 时选择基座：
+   - 已有 DraftGo 服务器：运行 `draftgo connect`。
+   - 需要本地 Docker 基座：运行 `draftgo local setup`。
+6. 连接完成后运行 `draftgo map`，确认页面、导航、数据、自定义服务和系统资源已进入本地上下文。
 
-- **已存在**：询问用户是否覆盖，确认后继续
-- **不存在**：向用户询问：
-  1. DraftGo 服务器地址（如 `https://your-server.com`）
-  2. 系统访问令牌（SAT，管理后台 → 系统设置 → API Token）
+`draftgo init` 负责安装 Skill；`draftgo connect` 负责写入服务器连接并拉取初始上下文。不要混用两者的职责。
 
----
-
-## 第二步：执行初始化脚本
-
-脚本位于 `{{SKILL_SCRIPTS}}/draftgo_init.py`，直接运行（**不要读取脚本内容**）：
-
-```
-# 默认：项目根由脚本自动推导（向上查找含 .draftgo/ 的目录）
-!DRAFTGO_TOKEN="<token>" python {{SKILL_SCRIPTS}}/draftgo_init.py --server "<server>"
-
-# 用户明确指定了项目路径时，作为位置参数传入
-!DRAFTGO_TOKEN="<token>" python {{SKILL_SCRIPTS}}/draftgo_init.py --server "<server>" "<project_path>"
-```
-
-脚本会自动完成所有工作并输出摘要，**不要读取任何中间 JSON 文件**。
-
----
-
-## 第三步：确认结果
-
-脚本执行完毕后，确认 `.draftgo/config.json` 生成成功：
-
-```
-!test -f .draftgo/config.json && echo "OK" || echo "FAIL"
-```
-
----
-
-## 初始化目录
-
-脚本执行完毕后，确保以下目录存在（不存在则创建）：
-
-```
-!mkdir -p .draftgo/lessons .draftgo/Task
-```
-
-- `.draftgo/changelog.md`：更新日志（单文件，按日期分节）
-- `.draftgo/lessons/`：开发经验与问题记录（按 `YYYY-MM-DD-主题.md` 命名）
-- `.draftgo/Task/`：每个开发任务一个 Markdown 文件，含需求纪要 / 设计 / 任务清单 / 进度标记
-
-> **注意：`.draftgo/story.yaml` 不在 init 流程中创建。** Story 文件由 AI 在首次开发对话时通过 Story 门禁流程自动构建（见 `{{SKILL_DIR}}/story/SKILL.md`），确保它是基于与开发者对话理解后生成的，而不是空模板。
-
-## 完成提示
-
-将脚本的输出摘要（页面数、导航数、文档数、自定义脚本数、服务器地址）告知用户，并提示：
-- 下一步：描述要开发的功能，或运行 `/draftgo push` 推送修改
-- 如需刷新数据：运行 `/draftgo pull`（按类型增量拉取）或 `/draftgo pull --all`（全量刷新）
-- 已拉取的资源分布：
-  - `.draftgo/pages/`、`.draftgo/navigations/`：页面与导航 HTML
-  - `.draftgo/docs/articles/`：文档中心文章正文（Markdown），分类索引在 `.draftgo/doc_categories/index.json`
-  - `.draftgo/custom_scripts/`：Go 自定义服务代码（`.go`），meta 在同目录 `index.json`
-- 修改这些资源后通过 `/draftgo push <类型>` 推回云端，类型见根 SKILL.md。
+## 后续动作
 
-> 注意：拉取 `docs` (admin 列表) / `custom_scripts` 需要令牌具备对应读取权限（自定义服务为 `scripts:read`，admin 自动通过）。若任一项返回 0 条但用户期望应有数据，提醒用户检查 token 角色权限。
+- 刷新云端资源：`draftgo pull [type] [id...]`
+- 管理本地基座：`draftgo local start|stop|logs|status`
+- 移除指定目标：`draftgo uninstall <target>`
+- 完整移除所有目标：仅在用户明确要求时运行 `draftgo uninstall all`；`--purge` 还会删除项目的 `.draftgo/` 数据。

package/resources/skill/manifest.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": "1.0",
+  "id": "draftgo",
+  "name": "DraftGo 开发助手",
+  "version": "3.0.35",
+  "entry": "SKILL.md",
+  "description": "DraftGo 应用的开发、资源同步、验证与交付工作流。",
+  "license": "MIT",
+  "capabilities": [
+    "draftgo-development",
+    "custom-service-ai-sdk",
+    "resource-sync",
+    "project-validation",
+    "skill-installation"
+  ],
+  "permissions": [
+    "workspace:read",
+    "workspace:write",
+    "process:run",
+    "network:explicit"
+  ],
+  "resources": {
+    "references": [
+      "references"
+    ],
+    "scripts": "scripts",
+    "subskills": [
+      "init",
+      "pull",
+      "push",
+      "story"
+    ]
+  }
+}

package/resources/skill/pull/SKILL.md

@@ -1,67 +1,33 @@
 ---
 name: draftgo-pull
-description: Use this skill when the user says "拉取页面", "拉取数据库", "拉取导航", "拉取全部", "pull pages", "pull db_meta", "pull nav", "pull all", "/draftgo pull", or wants to refresh local .draftgo files from the DraftGo server.
-version: 1.0.0
-allowed-tools: Bash(python:*), Read, Glob
+description: Pull all or selected DraftGo resources from the connected server into local .draftgo indexes and referenced files before inspection or modification.
 ---
 
-# DraftGo 拉取（云端 → 本地）
+# DraftGo 拉取
 
-> **STOP — 禁止用 curl、禁止自己写 Python 拉取逻辑。**
-> 唯一正确方式：运行下方 Python 脚本。
+使用 `draftgo pull`；内部 Python 脚本由 CLI 定位和执行。
 
-脚本位于：`{{SKILL_SCRIPTS}}/draftgo_pull.py`
+## 命令
 
-## 拉取全部（"拉取全部" / "pull all"）
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py --all
+```bash
+draftgo pull
+draftgo pull <type> [id...]
 ```
 
-## 按类型拉取
-
-```
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py pages          [page_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py nav            [nav_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py db_meta        [db_meta_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py aihub          [aihub_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py system_config  [config_key ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py docs           [article_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py doc_categories [category_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py custom_scripts [script_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py roles          [role_id ...]
-!python {{SKILL_SCRIPTS}}/draftgo_pull.py users          [user_id ...]
-```
-
-脚本会自动读取 `.draftgo/config.json` 获取 server 和 token。
-
-## 使用场景
+不带参数时拉取全部资源。支持的类型：
 
-- 通过 API / 后台管理界面直接创建了资源（如 db_meta），本地 index.json 没更新
-- 多人协作时需要同步其他人的修改
-- 本地文件损坏或过期，需要刷新
+`pages`、`nav`、`db_meta`、`aihub`、`system_config`、`docs`、`doc_categories`、`custom_scripts`、`roles`、`users`。
 
-## 拉取自定义服务后的身份契约检查
+## 执行
 
-`draftgo pull custom_scripts` 会把云端服务的 `code`、`go_mod`、`go_sum` 写回 `.draftgo/custom_scripts/`。其中 `draftgo.Admin.*` 只是 Go 源码中的显式管理员 SDK 调用：
-
-- 不会生成 `admin_access`、`system_capabilities` 或 SAT 配置；不要手动补这些字段。
-- `draftgo.DB` 等普通 SDK 调用仍继承 Route 调用者权限；只有 `draftgo.Admin.*` 的那一项调用以平台管理员身份执行并进入执行审计。
-- 拉取后如需修改含 `draftgo.Admin.*` 的服务，先阅读 `../specs/custom-services.md`，保留字段脱敏逻辑，再执行 `draftgo push custom_scripts <id>`。
-- 推送后回读服务执行详情，确认存在 `Admin SDK call` 审计日志；不要把 SAT、管理员 cookie 或数据库连接复制进 `code_file` / `go_mod`。
-
-## 与 init 的区别
-
-| 命令 | 功能 |
-|------|------|
-| `/draftgo init` | 首次配置（写 config.json + .gitignore）+ 全量拉取 |
-| `/draftgo pull` | 仅拉取，不改配置，支持按类型增量拉取 |
+1. 在本地资源缺失、过期、损坏，或用户明确要求同步云端版本时运行 pull。
+2. 只拉取当前工作需要的类型或 id；需要建立完整项目上下文时运行无参数的 `draftgo pull`。
+3. 拉取后重新读取对应 `index.json` 以及其中 `html_file`、`content_file`、`code_file` 指向的文件。
+4. 修改自定义服务前，确认 `code_file`、`go_mod`、`go_sum` 已同步，并读取 `../references/custom-services.md`。
+5. 运行 `draftgo map` 确认跨资源入口或依赖已更新。
 
 ## 失败处理
 
-如果报错 `未找到 .draftgo/config.json`，提示用户先运行 `/draftgo init`。
-
-如果报错 HTTP 401，提示：
-```
-⚠️ Token 无效，请重新运行 /draftgo init 更新 token。
-```
+- 缺少 `.draftgo/config.json`：运行 `draftgo connect`。
+- HTTP 401：连接令牌无效，重新运行 `draftgo connect`。
+- 返回空列表但预期存在资源：检查令牌是否具备对应读取权限，不把空结果直接当成资源不存在。