draftgo-cli 1.0.4 → 1.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +4 -4
  2. package/package.json +4 -3
  3. package/resources/skill/SKILL.md +4 -3
  4. package/resources/skill/manifest.json +1 -1
  5. package/resources/skill/references/ai.md +1 -1
  6. package/resources/skill/references/app-api.md +29 -27
  7. package/resources/skill/references/chat-sdk.md +10 -184
  8. package/resources/skill/references/checkout.md +43 -118
  9. package/resources/skill/references/development.md +0 -3
  10. package/resources/skill/references/frontend.md +10 -25
  11. package/resources/skill/references/mcp.md +15 -68
  12. package/resources/skill/references/methods.md +8 -11
  13. package/resources/skill/references/modules.md +24 -35
  14. package/resources/skill/references/runtime.md +11 -102
  15. package/resources/skill/references/services.md +89 -17
  16. package/src/commands/checkout.js +50 -3
  17. package/src/commands/commit.js +1 -1
  18. package/src/commands/conflict.js +1 -1
  19. package/src/commands/diff.js +1 -1
  20. package/src/commands/help.js +125 -125
  21. package/src/commands/map.js +60 -17
  22. package/src/commands/reconcile.js +1 -1
  23. package/src/commands/uninstall.js +16 -9
  24. package/src/mcp/hosts.js +68 -23
  25. package/src/platforms.js +16 -4
  26. package/src/skill.js +26 -6
  27. package/src/targets.js +2 -2
  28. package/src/worktree/backend.js +157 -21
  29. package/src/worktree/index.js +3 -0
  30. package/src/worktree/types.js +22 -18
package/resources/skill/references/frontend.md CHANGED
@@ -60,29 +60,18 @@ draftgo components show <library/component> --output json
60
60
  - 按钮、表单、搜索、筛选、分页、提交和删除等已呈现交互应真实有效；主要流程必须闭环。
61
61
  - 异步流程覆盖相关加载、空数据、错误、成功、无权限和重试状态，不能因请求延迟或失败整页空白。
62
62
  - 数据型页面应让主要操作、分页、批量操作和保存控件在空、短、长列表下都可达；滚动边界明确，横向溢出不能隐藏核心操作。
63
- - 展示可维护内容时判断是否需要管理入口并复用同一份真实数据。列表、详情和编辑结构按任务差异设计，不复制大量同构工作台。
64
- - 按钮、标签、导航项、徽章等视觉整体内部使用 `white-space: nowrap`；整组可换行，但图标与文字不能被拆散。
65
- - 空态需有明确文案和下一步操作；已有固定主操作入口时使用紧凑说明和就近操作，自定义空态用 flex 对齐图标与文字。
66
- - 弹窗和抽屉把滚动放在内容区，避免双滚动条；flex 内容区使用 `min-height: 0` 保持滚动可用。
67
- - 官方页面和交付页面的选择器统一使用 DraftGo 内置 `draftgo/select`（多选使用 `draftgo/multi-select`）；不要使用原生 `<select>` 作为可见控件。组件运行时会把选项 slot 渲染为可访问的自绘面板，并处理键盘、焦点、禁用、空值和错误状态。
68
- - 运营表格可把排序和筛选放在对应表头的弹层中，保持数据列、条件和结果之间的直接关系；具体交互由数据规模与操作频率决定。
69
-
70
- ### 响应式
71
-
72
- 移动端是产品范围，不是固定验收门。公众页面、手机访问场景或已有响应式布局应处理窄屏；明确桌面工作台或仅改数据逻辑时不机械增加多端工作。
73
-
74
- 在目标设备上保证：无整页横向溢出；阅读顺序和核心操作可达；表格/代码等宽内容有可访问滚动边界；弹窗完整可用；文字、导航和操作区不重叠。断点、堆叠和密度由真实内容及现有设计系统决定。
63
+ - 官方页面和交付页面的选择器统一使用 DraftGo 内置 `draftgo/select`（多选使用 `draftgo/multi-select`）；不要使用原生 `<select>` 作为可见控件。
75
64
 
76
65
  ### 动效
77
66
 
78
67
  动效仅用于解释层级、状态、空间关系或操作结果。可用 CSS、Web Animations、组件库或内置 GSAP，并为 `prefers-reduced-motion` 降级；不得阻塞操作、掩盖等待、引发布局跳动或成为唯一状态表达。
79
68
 
80
- GSAP 从 `/assets/vendor/gsap/gsap.min.js` 加载核心；最终版本地额外提供 `/assets/vendor/gsap/Draggable.min.js`，使用时显式 `gsap.registerPlugin(Draggable)`。不要假设存在其他 GSAP 插件。页面卸载时清理 timeline 和 Draggable 实例；同一属性不要同时由 CSS transition 与 GSAP 控制。
69
+ GSAP 从 `/assets/vendor/gsap/gsap.min.js` 加载核心；最终版本地额外提供 `/assets/vendor/gsap/Draggable.min.js`，使用时显式 `gsap.registerPlugin(Draggable)`。不要假设存在其他 GSAP 插件。页面卸载时清理 timeline 和 Draggable 实例。
81
70
 
82
71
  ## 运行形态
83
72
 
84
- - DraftGo 壳层位于 `frontend/`，使用 React 19 + Vite 8 + Tailwind CSS 4。只有用户明确要求修改壳层时才编辑该源码。
85
- - 业务页面与导航存储为数据库中的完整 HTML 文档，由壳层在 iframe 中运行。不得写入 TSX、ESM import、npm 依赖或 Vite 构建产物。
73
+ - 只有用户明确要求修改壳层时才编辑 `frontend/` 源码。
74
+ - 业务页面与导航是数据库中的完整 HTML，在 iframe 中运行。不得写入 TSX、ESM import、npm 依赖或 Vite 构建产物。
86
75
  - 数据库 Page 使用普通 HTML + Tailwind CSS 4 + 原生 JavaScript；官方内置 Page 默认搭配 DraftGo 内置组件库，按需使用下方列出的本地资源。
87
76
  - 页面使用 `const App = window.parent?.App`。参数读取 `window.__DG_ROUTE_CONTEXT__.query`；页面跳转使用父窗口；登出调用 `await App.logout()`。
88
77
 
@@ -93,12 +82,8 @@ GSAP 从 `/assets/vendor/gsap/gsap.min.js` 加载核心；最终版本地额外
93
82
  - 默认使用 `var(--dg-*)` 主题 token，并支持浅色/深色；用户输入或不可信 HTML 经 DOMPurify 净化。
94
83
  - 使用 `App.confirm()`、`App.toast()` 或对应反馈 API；关键状态不能只靠颜色或动画。
95
84
  - 建议调用全局 `App.formatDateTime(value, options)` 来适配系统时间显示；API 时间按 UTC 解析，页面不要直接按浏览器本地时区展示。
96
- - 初始渲染立即显示稳定的加载状态。
97
- - 页面文案使用页面级 `page_i18n`：静态 HTML 可用 `data-i18n-key` / `data-i18n-placeholder`，JavaScript 使用 `App.t(key, fallback, values)`；不要创建公共词条表或自定义 namespace。翻译输入必须保持原 messages key 集合和 ICU 占位符不变。
98
- - 选择器、Toast 等交互控件优先采用项目已有组件或统一封装，使视觉、状态和反馈与页面设计系统保持一致；提示就近呈现并说明下一步操作。
99
- - 外部资源优先使用项目内置文件；品牌图标的明确例外见资源章节。
100
- - 数据库 HTML 保持为可直接运行的页面文档，依赖和构建产物使用平台提供的本地资源。
101
- - 全局浮窗、客服、统计脚本或公共 Toast 统一使用 `frontend_global_*` 槽位和系统配置；组件库状态样式通过其公开 API 或局部作用域进行适配。
85
+ - 页面文案使用页面级 `page_i18n`：静态 HTML 可用 `data-i18n-key` / `data-i18n-placeholder`，JavaScript 使用 `App.t(key, fallback, values)`；不要创建公共词条表或自定义 namespace。
86
+ - 全局浮窗、客服、统计脚本或公共 Toast 统一使用 `frontend_global_*` 槽位和系统配置。
102
87
 
103
88
  ## 组件与资源
104
89
 
@@ -123,7 +108,7 @@ GSAP 从 `/assets/vendor/gsap/gsap.min.js` 加载核心；最终版本地额外
123
108
  | Provider brands | `/assets/providers/{provider}.svg`、`/assets/providers/provider-icons.js` |
124
109
  | Markdown/code | `/assets/vendor/marked/marked.min.js`、`/assets/vendor/highlightjs/highlight.min.js`、`/assets/vendor/highlightjs/styles/github.min.css` |
125
110
  | HTML security | `/assets/vendor/dompurify/purify.min.js` |
126
- | Chat runtime | 完整实现位于 `draftgo/chat` 的 `Definition.JS`，随组件按需解析与发布 |
111
+ | Chat | 组件 `draftgo/chat`，见 `chat-sdk.md` |
127
112
  | Motion | `/assets/vendor/gsap/gsap.min.js`、`/assets/vendor/gsap/Draggable.min.js` |
128
113
 
129
114
  正文使用系统无衬线字体栈，代码使用系统等宽字体栈。通用图标优先使用项目内置 SVG，其他通用图标可使用 Font Awesome。模型/Provider 品牌标识使用本地 `/assets/providers/`；通过 `DraftGoProviderIcons.get(provider.kind)` 查找，未知或加载失败时回退通用图标，不访问 CDN。
@@ -137,9 +122,9 @@ GSAP 从 `/assets/vendor/gsap/gsap.min.js` 加载核心；最终版本地额外
137
122
  | `--dg-accent/hover/subtle` | 主题色 |
138
123
  | `--dg-border/success/error/warning` | 边框与状态 |
139
124
 
140
- 壳层已把变量注入 `<head>`，直接使用即可。默认继承 `App.theme` 与 `App.colorScheme`。品牌或图表需要自主配色时，先定义页面局部变量并提供 light/dark 两套值；正文和交互文字保持 WCAG AA。不要把 hex/rgb 散落在组件样式中。
125
+ 壳层已把变量注入 `<head>`，直接使用即可。默认继承 `App.theme` 与 `App.colorScheme`。品牌或图表需要自主配色时，先定义页面局部变量并提供 light/dark 两套值。不要把 hex/rgb 散落在组件样式中。
141
126
 
142
- ## AI 页面 SDK
127
+ ## AI 对话
143
128
 
144
129
  DraftGo Page 的 AI 对话 UI 使用组件目录中的 `draftgo/chat`，不要手工加载 SDK 或自行实现流式状态：
145
130
 
@@ -155,4 +140,4 @@ DraftGo Page 的 AI 对话 UI 使用组件目录中的 `draftgo/chat`，不要
155
140
 
156
141
  完整 Chat 实现保存在 `draftgo/chat` 组件的 `Definition.JS`，与其他组件统一按需解析；同一 Page iframe 内相同 revision 与 hash 只编译一次。Page 使用 `<dg-chat data-dg-use="draftgo/chat">`，不手工加载第二套脚本。无 UI 的文本、图片或其他模型能力调用统一走服务端 AI Registry。完整组件边界见 `chat-sdk.md`，服务端 AI 能力见 `ai.md`。
157
142
 
158
- 平台请求与反馈见 `app-api.md`；iframe 路由、认证与全局层见 `runtime.md`；动态 DB、筛选和关系见 `data.md`。DraftGo Page 的可序列化 Chat 配置以 `draftgo components show draftgo/chat` 返回的实时契约为准；函数型扩展只用于外部应用的直接 SDK 接入。
143
+ 平台请求与反馈见 `app-api.md`；iframe 路由、认证与全局层见 `runtime.md`；动态 DB、筛选和关系见 `data.md`。DraftGo Page 的可序列化 Chat 配置以 `draftgo components show draftgo/chat` 返回的实时契约为准。
package/resources/skill/references/mcp.md CHANGED
@@ -1,12 +1,10 @@
1
1
  ---
2
- read_when: 配置或诊断 DraftGo MCP 时 · 查询实时资源或 API 契约时 · 判断宿主支持范围时
2
+ read_when: 查询实时资源或 API 契约时 · MCP 连接失败时
3
3
  ---
4
4
 
5
5
  # DraftGo MCP
6
6
 
7
- 根 `SKILL.md` 已负责任务路由。本文件只保留 MCP 的实时契约、调用优化和安全边界，不重复页面、前端或交付规则。
8
-
9
- ## 最短流程
7
+ 根 `SKILL.md` 已负责任务路由。按任务读取最少必要的 Reference。不要增加聚合上下文工具或静态 API 路径表。
10
8
 
11
9
  ```bash
12
10
  draftgo mcp status
@@ -14,47 +12,33 @@ draftgo mcp test
14
12
  draftgo api search "<业务能力>"
15
13
  draftgo api describe <operation_id>
16
14
  draftgo api call <operation_id> --input request.json --output json
17
- draftgo capabilities search <query> --output json
18
- draftgo capabilities show <operation_id> --output json
19
- draftgo capabilities audit --output json
20
-
21
- # 领域快捷命令（仍使用实时 operation describe/cache）
22
- draftgo role list
23
- draftgo group list --input request.json
24
- draftgo api-key status
25
15
  ```
26
16
 
27
- 已配置且连接正常时无需每次运行前两条；只在初次配置、配置变化或 MCP 失败时执行。完成标准是 initialize、tools/list 和关键 tools/call 可用，目标 operation 的 schema 已确认且调用结果可回读。401/403 查用户 API Key 或权限，session/uninitialized 查会话与服务重启，5xx 记录 request ID 后查服务日志；不要用重复写入测试连接。
17
+ 已连接时不必每次 status/test。401/403 查 API Key 与权限；session/uninitialized 重建连接；5xx 记 request ID。
28
18
 
29
19
  ## 边界
30
20
 
31
- MCP 用于实时发现、结构化查询和普通 API 操作。pages、navigations、docs/articles 的完整正文走 `draftgo checkout` / `draftgo commit`；工具返回 `artifact` 或 `omitted` 时保留该语义，不要求模型展开长内容。
32
-
33
- 不要增加聚合上下文工具或静态 API 路径表。按任务读取最少必要的 Reference，再调用精确工具：
21
+ 完整正文走 checkout/commit。工具返回 `artifact` 或 `omitted` 时保留该语义。
34
22
 
35
23
  | 需要 | 工具 |
36
24
  |---|---|
37
- | 项目能力、registry 覆盖和 checkout 类型 | `draftgo_project_overview` |
25
+ | 项目能力、registry、checkout 类型 | `draftgo_project_overview` |
38
26
  | 定位资源 | `draftgo_resource_search` / `draftgo_resource_list` |
39
27
  | 元数据或短片段 | `draftgo_resource_get_metadata` / `draftgo_resource_read_fragment` |
40
- | 定位 API operation | Registry `search`（兼容 `draftgo_api_search`） |
41
- | 读取 operation schema | Registry `describe`（兼容 `draftgo_api_describe`） |
42
- | 结构化读写 | Registry `invoke`（兼容 `draftgo_api_call`） |
28
+ | 定位 / 读取 / 调用 API | Registry `search` / `describe` / `invoke` |
43
29
 
44
- 只在需要对应信息时调用工具，不把 `project_overview` 作为每个任务的固定前置步骤。独立资源或 operation 可并发调用；同一资源的依赖步骤保持顺序。非幂等写入失败后先读状态，不自动重试。
30
+ 不要把 `project_overview` 当每个任务的固定前置。同一资源的依赖步骤串行。非幂等写入失败后先回读，不自动重试。
45
31
 
46
- ## API 契约缓存
32
+ ## 契约缓存
47
33
 
48
- 动态 schema 不写入 Skill。Skill 只保存下面的缓存规则：
34
+ 动态 schema 不写入 Skill。
49
35
 
50
36
  1. operation 未知时才 search；已有精确 `operation_id` 时跳过 search。
51
- 2. 第一次使用 operation 时 describe，检查 method、path、parameters、request body、responses、permission、risk、`destructive`、`idempotent`、`input_schema` 和 `response_policy`。
52
- 3. 同一 server 的 operation 描述按 `registry_revision` 复用。CLI 将缓存写在私有 `.draftgo/api-contract-cache.json`，不把 schema 注入 Skill 或对话上下文。
53
- 4. call 携带缓存的 `registry_revision`。服务返回 `CONTRACT_CHANGED` 时重新 describe；只读或 operation 契约未变化时最多重试一次。危险 operation 自身契约变化或服务端明确报告 CLI/契约不兼容时停止调用，升级 CLI 后重新 describe 和确认；其他工具错误不触发自动重试。
37
+ 2. 第一次使用时 describe，检查 method、path、parameters、request body、responses、permission、risk、`destructive`、`idempotent`、`input_schema` 和 `response_policy`。
38
+ 3. 同一 server 按 `registry_revision` 复用。缓存在 `.draftgo/api-contract-cache.json`，不注入 Skill 或对话。
39
+ 4. call 携带该 revision。`CONTRACT_CHANGED` 时重新 describe；只读或契约未变最多重试一次。危险 operation 自身契约变化或服务端报告 CLI/契约不兼容时停止调用，升级 CLI 后重新 describe 和确认；其他工具错误不重试。
54
40
 
55
- describe 缺少本次调用需要的 schema、权限、风险或响应契约时停止并报告，不猜字段、不拼路径、不绕过 MCP。多个 operation 仍可能匹配时继续缩小 search，而不是任选一个。
56
-
57
- ## 调用形状
41
+ describe 缺本次所需 schema、权限、风险或响应契约时停止，不猜字段、不拼路径、不绕过 MCP。多个匹配时继续缩小 search。
58
42
 
59
43
  ```json
60
44
  {
@@ -68,43 +52,6 @@ describe 缺少本次调用需要的 schema、权限、风险或响应契约时
68
52
  }
69
53
  ```
70
54
 
71
- 只传 operation schema 需要的容器。路径参数放 `path`，查询参数放 `query`，JSON 放 `body`，文件或表单字段放 `multipart`。不得传 tenant override、API Key、Authorization 或其他凭据。
72
-
73
- 高风险 operation 仅在用户意图和影响范围明确时设置 `confirm=true`；不要拼 `X-Confirm-Token` 或调用旧 reauth 流程。按 describe 的 responses 与实际 `status_code` 解释结果，不对自定义 Route、OpenAI 兼容流等强套 `{code,data,message}`。`response_policy.checkout_required=true` 时改走 checkout/commit。
74
-
75
- ## CLI 与宿主
76
-
77
- ```bash
78
- draftgo mcp setup [target...]
79
- draftgo mcp status [target...]
80
- draftgo mcp test
81
- draftgo mcp serve
82
- ```
83
-
84
- - `setup` 写项目级宿主配置，只替换 `draftgo` 条目。
85
- - `status` 检查配置与凭据泄漏风险。
86
- - `test` 建立独立新连接并验证关键工具；它不证明宿主持有的旧 session 仍有效。
87
- - `serve` 是 stdio bridge。远端 session 明确失效时重新 initialize 并重放当前请求一次；普通超时、服务错误和工具错误不重试。
88
-
89
- 支持项目级 setup：Codex、Claude Code、Cursor、Gemini CLI、Kiro、GitHub Copilot。Windsurf 和 Antigravity 没有可靠项目级 MCP 配置，CLI 应明确提示不支持。
90
-
91
- 宿主配置只运行：
92
-
93
- ```json
94
- {"command":"draftgo","args":["mcp","serve"]}
95
- ```
96
-
97
- Codex 使用 `[mcp_servers.draftgo]`；GitHub Copilot 使用 `servers` 且声明 `type="stdio"`；其他支持宿主使用各自 `mcpServers`。配置不得包含 API Key、token、Authorization、headers、远端 `/mcp` URL、`env` 或带凭据命令。bridge 从当前项目 `.draftgo/config.json` 读取 server/API Key。
98
-
99
- `draftgo connect` 只保存并验证连接，不下载业务资源或创建本地镜像。MCP 不可用时运行 `draftgo mcp test` 收集证据。
100
-
101
- ## 安全
102
-
103
- - stdio stdout 只输出 MCP JSON-RPC；日志写 stderr，且不得包含 API Key。
104
- - 代理 initialize、tools/list、tools/call、通知、取消、错误和流式响应，不改写底座结果。
105
- - HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前脱敏 API Key 与 Authorization。
106
- - `.draftgo/config.json`、`.draftgo/api-contract-cache.json`、worktree 和 conflicts 都是私有运行时状态并应 gitignore。
107
-
108
- ## 专用资源命令
55
+ 只传 schema 需要的容器。不得传 API Key、Authorization 或其他凭据。高风险仅在意图明确时 `confirm=true`；不要拼 `X-Confirm-Token`。按 describe 的 responses 与实际 `status_code` 解释结果。describe 或 call 返回 `checkout_commit` 工作流时，改走 `draftgo checkout` / `draftgo commit`，不要把 `api call` 当成本地正文通道。
109
56
 
110
- Agent 通过 components 子命令操作组件。当前这些命令封装底座固定组件 HTTP 协议，组件内容、props 和 slots 仍实时读取；不要声称所有 CLI 请求都经过 MCP。通用 api 命令以 Registry 为唯一契约来源。WORKFLOW_REQUIRED 表示操作未执行，只有匹配的专用 CLI 工作流可完成正文或文件传输。
57
+ 宿主 MCP 配置见 init Skill。`WORKFLOW_REQUIRED` 表示操作未执行；正文、Go 源码和文件只有匹配的 CLI 工作流能传。组件走 `draftgo components`，内容仍以实时目录为准。
package/resources/skill/references/methods.md CHANGED
@@ -62,18 +62,11 @@ draftgo verify pages <id>
62
62
  draftgo commit pages <id>
63
63
  ```
64
64
 
65
- 导航将 `pages` 换为 `nav`，文档文章换为 `docs`。`--route` 与 `--title` 均为精确匹配，同时给出时取交集；CLI 会先用资源搜索缩小候选，再在本地判定精确结果。只需确认范围、数量和 checkout 状态时使用 `map --summary`；必须浏览时使用 `--limit <1-100>`（默认 20），并仅在单一 `--type` 下用返回的 `--cursor <opaque>` 请求下一页。`map --summary` 不含 project overview、资源列表或 hash。`diff --stat` 显示文件与增删行数，`diff --summary` 显示资源、版本和变化概览；只有需要审查正文时才运行不带这两个参数的 `diff`。新资源先发现创建契约并取得 ID：
65
+ `nav`、`docs` 同理。新资源先 search/describe/call 取得 ID 再 checkout。
66
66
 
67
- ```bash
68
- draftgo api search "create <page|navigation|article>"
69
- draftgo api describe <operation_id>
70
- draftgo api call <operation_id> --input request.json --output json
71
- draftgo checkout <pages|nav|docs> <id>
72
- ```
67
+ 关键约束与失败定位：checkout 不创建资源。409/412 时停止，用 `draftgo conflicts` 与 `draftgo conflict show <type> <id>`；不要 force、覆盖或自动合并。
73
68
 
74
- 关键约束与失败定位：checkout 只处理已存在资源的完整正文，不负责创建。409/412 时停止提交，使用 `draftgo conflicts` 和 `draftgo conflict show <type> <id>` 检查保留的 base/local/remote；不要 force、覆盖或自动合并。
75
-
76
- 完成条件：commit 返回新版本/哈希，随后 `draftgo check --remote --output json` 显示本地基线与远端一致。正文和冲突细节再读 `checkout.md`，页面运行规则再读 `frontend.md`。
69
+ 完成条件：commit 返回新版本/哈希，`draftgo check --remote --output json` 显示基线一致。细节见 `checkout.md`、`frontend.md`。
77
70
 
78
71
  ## 动态数据
79
72
 
@@ -92,7 +85,11 @@ draftgo api search "dynamic db record"
92
85
 
93
86
  ## 自定义服务
94
87
 
95
- 需要额外业务逻辑时读 `services.md`：定位/创建服务 → 获取 SDK 与草稿 → 保存源码版本 → 验证和草稿试运行 → 按任务发布及回读。策略独立读取、按版本保存与预览。所有 operation 从实时 Registry 发现。当前 CLI 的源码/SDK workflow 传输尚未接通，先读 services.md 的能力边界；不能将接口可发现等同于开发闭环可执行。
88
+ 适用场景：现有模块和动态 DB 无法表达的事务、事件或定时逻辑。
89
+
90
+ 读 `services.md` 写 `Register` 与 Route/Event/Schedule。源码用 `draftgo checkout services <id>` 编辑 worktree 里检出的 `.go` 文件，再用 `draftgo commit services <id>` 提交。创建、validate、草稿试运行和 publish 用 MCP search/describe/call；不要把草稿或 SDK 的 `api call` 当成本地正文通道。SDK 以 checkout 后的 `.draftgo/worktree/sdk/` 或当前实例 describe 为准。
91
+
92
+ 完成证据：草稿 revision、验证结果、试运行执行 ID；发布时加版本。
96
93
 
97
94
  ## MCP 与实时契约
98
95
 
package/resources/skill/references/modules.md CHANGED
@@ -1,15 +1,15 @@
1
- ---
2
- read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目做全局了解时
3
- ---
4
-
5
- # DraftGo 模块地图
6
-
7
- ## 可开发模块（开发者负责实现）
8
-
9
- | 模块 | 开发方式 | 入口 |
10
- |---|---|---|
1
+ ---
2
+ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目做全局了解时
3
+ ---
4
+
5
+ # DraftGo 模块地图
6
+
7
+ ## 可开发模块（开发者负责实现）
8
+
9
+ | 模块 | 开发方式 | 入口 |
10
+ |---|---|---|
11
11
  | 页面 | 数据库 HTML（`page.value.html`） | 已有页面由 MCP 定位后 `checkout pages` / `commit pages`；新页面先按实时 API 契约创建并取得 ID |
12
- | 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
12
+ | 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
13
13
  | 动态 DB | db_meta 定义 schema 并操作结构化记录 | MCP `api_search` / `api_describe` / `api_call` |
14
14
  | 文件资产 | 文件夹、文件元数据、绑定、下载、回收站和对象存储 | MCP 实时 API；文件字节不进入普通 tool result |
15
15
  | 自定义 Go 服务 | SDK、草稿、验证、试运行、独立策略与发布；按需读 `services.md` | MCP 实时契约与返回的专用传输工作流 |
@@ -17,11 +17,11 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
17
17
  | 文档中心 | Markdown/HTML 系统文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP |
18
18
  | 系统配置 | KV 存储，含全局前端层槽位 | MCP 实时 API；不创建本地镜像 |
19
19
  | 支付与余额 | 账单、支付、退款、余额和资金流水 | 管理任务用 MCP 实时 API；不要用动态 DB 重建金钱状态 |
20
-
21
- ## 平台内置模块（开箱即用，不需实现）
22
-
23
- | 模块 | 能力 | 调用方式 |
24
- |---|---|---|
20
+
21
+ ## 平台内置模块（开箱即用，不需实现）
22
+
23
+ | 模块 | 能力 | 调用方式 |
24
+ |---|---|---|
25
25
  | 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | 页面使用 `App`；服务端操作通过 MCP 实时描述接口 |
26
26
  | 角色权限 | Role 权限模板、用户直接角色与用户组角色 | 页面可用 `App.permissions` 辅助显隐；服务端执行最终授权 |
27
27
  | 用户组 | 用户组成员与角色分配 | MCP 实时 API；CLI 提供 `group` 快捷命令 |
@@ -35,20 +35,9 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
35
35
 
36
36
  用户 API Key 只是一种用户认证方式；它始终代表当前用户，不能创建服务身份或绕过管理员边界。
37
37
 
38
- ## 新模块权限接入检查表
39
-
40
- AI 新建或扩展受保护模块时，按以下最小闭环逐项确认；缺少任一项都不能用页面显隐、角色名或调用来源补洞：
38
+ ## 模块选型决策
41
39
 
42
- - [ ] 在统一 Permission Catalog 注册每个 `resource:action`，不在模块内另建权限字符串或角色分支。
43
- - [ ] HTTP、MCP 和后台任务等所有实际入口复用同一授权路径。
44
- - [ ] 按 ID 操作先加载服务端真实资源；忽略客户端提交的 owner 或调用者替代值。
45
- - [ ] 保留最小拒绝证据：缺少权限、伪造 owner、越权访问他人资源。不要为同一规则复制一套测试框架。
46
-
47
- 实现位置和具体 API 以目标 DraftGo 服务端仓库的现有 Permission Catalog 与 Authorizer 模式为准；本 Skill 不复制服务端动态 schema。
48
-
49
- ## 模块选型决策
50
-
51
- ```
40
+ ```
52
41
  要存储业务数据？
53
42
  → 轻量业务记录 → 动态 DB（db_meta 定义 schema）
54
43
  → 强一致性领域 → 优先复用底座专用模块，确需额外逻辑时评估 Go 服务
@@ -59,17 +48,17 @@ AI 新建或扩展受保护模块时，按以下最小闭环逐项确认；缺
59
48
 
60
49
  要做余额、支付或退款？
61
50
  → 走 payment/wallet 的 MCP 实时契约，不自行实现账本或扣费一致性
62
-
63
- 要调用 AI？
51
+
52
+ 要调用 AI？
64
53
  → DraftGo Page 聊天/问答 UI → AI 能力 + `draftgo/chat`（组件定义按需解析，自动隔离 thread/session）
65
54
  → 无 UI 的文本或媒体调用 → AI 能力 + MCP Registry operation（先 search/describe，再 call）
66
55
  → 图片生成 → AI 能力的 image capability 与当前 Provider readiness
67
56
  → Responses、Embedding、Rerank、TTS、ASR 或 Video → 模型 capability 与 provider readiness；先确认模型的 canonical capability 和 transport
68
57
  → 需要工具、知识、记忆、结构化输出或多模态 → 先读 references/ai.md，再通过实时 Registry 确认当前契约
69
-
70
- 要展示内容文档？
71
- → 文档中心（Markdown + 分类树）
72
-
58
+
59
+ 要展示内容文档？
60
+ → 文档中心（Markdown + 分类树）
61
+
73
62
  要做后台管理页？
74
63
  → 业务页面 + 动态 DB + 角色权限
75
64
  ```
package/resources/skill/references/runtime.md CHANGED
@@ -1,109 +1,18 @@
1
1
  ---
2
- read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问题时
2
+ read_when: 处理 iframe 路由、认证或全局层时
3
3
  ---
4
4
 
5
- # 运行时机制（Runtime）
5
+ # 运行时
6
6
 
7
- ## 壳层启动流程
7
+ 页面在 `iframe.srcdoc` 中运行，不是独立 URL。
8
8
 
9
- 1. `reloadSystemConfig()` — 拉取 `/api/system/config`，填充 `state.config`
10
- 2. `validateToken()` — 验证 `localStorage.dg_access_token`，成功后设置 `currentUser`
11
- 3. `loadSetupStatus()` — 检查系统是否已初始化
12
- 4. `loadPage()` — 根据当前路由拉取页面 HTML，注入 iframe
9
+ - 读参数：`window.__DG_ROUTE_CONTEXT__.query`。禁止 `window.location.search`
10
+ - 能力：`window.parent.App`，见 `app-api.md`
11
+ - 导航：`App.navigate(route)`。`window.location.href = '/path'` 只跳 iframe
12
+ - 登出：`await App.logout()`；会请求服务端登出、清理认证并触发 `dg:auth-changed`
13
+ - 401 由壳层刷新 token，页面不必处理
14
+ - 事件：`window.parent` 上的 `dg:auth-ready`、`dg:auth-changed`
13
15
 
14
- ---
15
-
16
- ## iframe 注入机制
17
-
18
- 壳层通过 `decorateFrameHtml(html, routeContext, theme)` 处理数据库页面 HTML，注入：
19
-
20
- - `window.__DG_ROUTE_CONTEXT__` — 当前路由上下文（含 `query` 参数），冻结对象
21
- - `window.__DG_QUERY__` — `routeContext.query` 快捷方式
22
- - `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式兜底读取
23
- - 主题 CSS 变量（写入 `<head>` 最顶部，DOM 解析时即生效）
24
- - 组件库主题适配器；Tailwind、FontAwesome、GSAP 等其他本地资源由页面按需加载
25
-
26
- 页面以 `iframe.srcdoc` 渲染，**不是独立 URL**，因此：
27
- - `window.location` 指向壳层地址，**不可用于读取路由参数**
28
- - `window.parent.App` 是壳层暴露的能力对象
29
- - `window.location.href = '/path'` 只跳 iframe 自身！导航必须用 `window.parent.location.href`
30
- - 登出必须调用 `await window.parent.App.logout()`；它会请求服务端登出、清理认证状态、触发 `dg:auth-changed`，并跳转系统配置的登录页
31
-
32
- ---
33
-
34
- ## App 对象来源
35
-
36
- 壳层将 `app` 对象赋值给 `window.App`，页面通过 `window.parent.App` 访问。
37
-
38
- `app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme）
39
-
40
- 完整 API 见 `references/app-api.md`
41
-
42
- ---
43
-
44
- ## Token 存储
45
-
46
- | key | 说明 |
47
- |---|---|
48
- | `localStorage.dg_access_token` | 访问 token |
49
- | `localStorage.dg_refresh_token` | 刷新 token |
50
-
51
- 登录后调用 `App.setAuthTokens({ access_token, refresh_token })` 写入并触发验证。
52
- 401 时壳层自动用 refresh token 刷新，无需页面处理。
53
-
54
- ---
55
-
56
- ## URL 参数读取（标准三阶回落）
57
-
58
- ```javascript
59
- const routeContext =
60
- window.__DG_ROUTE_CONTEXT__
61
- || window.__DG_GET_ROUTE_CONTEXT__?.()
62
- || window.parent?.App?.getCurrentRouteContext?.()
63
- || { query: {} };
64
- const query = routeContext.query || {};
65
-
66
- // 路由 /orders?orderId=42
67
- const orderId = query.orderId; // "42"
68
- ```
69
-
70
- **禁止**：`new URLSearchParams(window.location.search)` / 直接读 `window.location.search`
71
-
72
- ---
73
-
74
- ## 全局事件
75
-
76
- | 事件名 | 触发时机 |
77
- |---|---|
78
- | `dg:auth-ready` | token 验证完成（成功或失败） |
79
- | `dg:auth-changed` | token 变更（登录/登出） |
80
-
81
- 监听方式：`window.parent.addEventListener('dg:auth-ready', handler)`
82
-
83
- ---
84
-
85
- ## 前端全局层
86
-
87
- 全局浮窗、客服入口、统计脚本等属于全局层，不属于单个业务页面。
88
-
89
- 存储：`sys_config.category = frontend_global`
90
-
91
- 固定槽位覆盖总开关与安全模式、壳层 head/body/CSS/JS、iframe head、全局挂件、Toast 和滚动条配置。不要凭静态文档猜测全部键名或枚举；修改前通过 MCP 查询当前 `system_config` 契约与目标键。
92
-
93
- 规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**
94
-
95
- ### 修改方法
96
-
97
- system_config 是结构化远端资源。未知 operation 才通过 MCP `draftgo_api_search` 定位；首次使用或
98
- registry revision 变化时 `draftgo_api_describe`，再用 `draftgo_api_call` 读取并更新目标键；不要 checkout
99
- 或维护本地索引。
100
-
101
- 前端全局层是系统默认配置。更新现有全局配置时只发送 `config_value`；不要带 `description`、`category`、
102
- `value_type`、`status` 等元信息，避免触发“系统默认字段不允许修改字段描述/分类/状态”。
16
+ 全局浮窗、客服、统计脚本走 `frontend_global_*` 系统配置，不在业务页重复实现，不新增槽位。改配置前用 MCP 查当前 `system_config` 契约；更新只发 `config_value`。
103
17
 
104
- 页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中
105
- `错误 Toast 时长(s) = 4.5` 对应 `frontend_global_toast_duration_error.config_value = 4500`。
106
-
107
- ## 认证与权限边界
108
-
109
- 页面会话使用访问 token；CLI 与 System MCP 使用当前用户的 API Key。两者都按服务端 Role、用户组角色、资源所有者规则和业务守卫授权。页面中的 `App.permissions` 只适合辅助显隐，不能替代服务端检查；未知权限要求始终读取实时 operation describe。CLI 不创建、导出或伪造服务身份，也不附加契约之外的授权字段。
18
+ `App.permissions` 只辅助显隐，不替代服务端授权。
package/resources/skill/references/services.md CHANGED
@@ -1,32 +1,104 @@
1
+ ---
2
+ read_when: 编写自定义 Go 服务源码、注册入口或使用 SDK 时
3
+ ---
4
+
1
5
  # 自定义 Go 服务
2
6
 
3
- 底座现有操作无法表达所需业务逻辑时读取。通用发现与调用规则见 `mcp.md`；服务管理使用 `draftgo api search "custom service"` 发现能力。
7
+ 现有模块与动态 DB 表达不了的事务、事件、定时逻辑时使用。管理接口用 `draftgo api search "custom service"` 发现；不固化 operation、路径、schema。实时契约以当前实例 `draftgo api describe` 和 `.draftgo/api-contract-cache.json` 为准。
8
+
9
+ ## 源码
10
+
11
+ 单文件 `main.go`。`package main`，实现 `Register`。服务没有 mode；一个服务可同时注册多种入口。`Register` 只声明入口。
12
+
13
+ ```go
14
+ package main
15
+
16
+ import "draftgo/sdk"
17
+
18
+ func Register(app *sdk.App) {
19
+ app.Route("POST", "/orders", createOrder)
20
+ app.On("payment.paid", handlePayment)
21
+ app.Schedule("0 9 * * 1-5", generateReport)
22
+ }
23
+
24
+ func createOrder(ctx *sdk.Context) (any, error) {
25
+ if err := ctx.Auth.RequireLogin(); err != nil {
26
+ return nil, err
27
+ }
28
+ return ctx.DB.Create("order", ctx.Input)
29
+ }
30
+ ```
31
+
32
+ 普通结果 `return body, nil`。要控 HTTP 状态码或响应头：`return ctx.Respond(body, status, headers), nil`。handler 返回前收束 goroutine。依赖走平台锁定，不替换托管 SDK。不要调用自定义 Go 服务自己的管理/执行 API。
33
+
34
+ 已有服务源码：
35
+
36
+ ```bash
37
+ draftgo checkout services <id>
38
+ # 编辑 .draftgo/worktree/services/ 下检出的 .go 文件
39
+ draftgo commit services <id>
40
+ ```
41
+
42
+ CLI 提交 `source` 与读到的 `base_revision`。不要对草稿/SDK 的 MCP `api call` 当成本地正文通道；那类 operation 会要求 `checkout_commit` 工作流，应改用 checkout/commit。
43
+
44
+ ## 入口
45
+
46
+ 按触发来源识别，不按服务名。
47
+
48
+ | 触发 | 注册 | 身份 | 要点 |
49
+ |---|---|---|---|
50
+ | 页面 / 外部 / CLI / 智能体要调 HTTP | `app.Route(method, path, h)` | 调用者 | path 以 `/` 开头，挂在 `/api/x/{slug}` 下；勿覆盖内置 API |
51
+ | 领域事件发生后做事 | `app.On(event, h)` | 平台注入系统身份 | 事件名必须来自平台目录；按事件 ID 或业务键幂等 |
52
+ | 到点执行 | `app.Schedule(expr, h)` | 同 Event | 五字段 cron 或 `interval:5m` / `@every 5m`；时区用系统设置 |
4
53
 
5
- ## 当前 CLI 能力边界
54
+ 智能体只绑定已发布 Route，走同一 HTTP 入口。不要发明 agent/tool 模式。
6
55
 
7
- CLI 能发现服务接口并执行 inline operation。底座将源码和 SDK 接口标为 checkout_commit workflow，但当前 CLI checkout 仅支持 pages/nav/docs，api call 对 workflow 返回 WORKFLOW_REQUIRED，不会执行传输。因此当前 CLI 尚不能独立完成源码/SDK 获取与保存闭环；不要反复调用或声称已实现服务。需要源码传输时明确报告此缺口，保留本地工作，其他 inline 配置和查询可继续。
56
+ ## SDK
8
57
 
9
- ## 底座开发链
58
+ checkout 服务时，SDK 落到 `.draftgo/worktree/sdk/`。读那里的 `sdk.go` / `platform.go` / `ai.go`。若缺失，对当前实例 search/describe SDK operation 并报告，不要猜测文件内容。
10
59
 
60
+ 公开面如下。签名、字段、未列出的能力以当前实例 SDK 为准。
11
61
 
12
- 1. 搜索服务相关能力，确认 SDK、草稿、验证、试运行、策略与发布入口。已有服务先唯一定位，新服务通过创建 operation 获取 ID。
13
- 2. 获取当前实例 SDK 和草稿，完整内容落到本地文件编辑，避免大响应进入对话。源码使用单文件 main.go，通过 Register 注册入口；签名、支持方法与依赖方式以当前 SDK 为准。
14
- 3. 保存源码仅提交 source 和读取的 base_revision；策略独立版本管理，不能随源码携带空 config 重置权限。保存后回读草稿 revision。
15
- 4. 验证准确草稿版本，再通过草稿执行检查业务结果和日志。发布使用已验证的 revision，回读发布版本；仅要求草稿时不扩大为上线。
16
- 5. 按任务范围验证实际入口与权限，记录执行 ID、版本和结果。
62
+ `ctx.*` 跟随当前入口身份。显式提权用 `ctx.Admin.*`（同一套方法）。`ctx.Admin.Auth` 不能当 Route 门禁。尚未类型化的稳定能力：`ctx.Invoke(operation, input)`。
17
63
 
18
- 源码和 SDK 使用专用 API，不传给只支持 pages/nav/docs 的 checkout。MCP 对长响应返回 workflow 指引时，沿其允许流程获取完整文件；缺少可执行传输入口时报告具体 operation 和响应，不用摘要代替源码或声称完成。
64
+ | 面 | 方法 |
65
+ |---|---|
66
+ | `ctx.Auth` | `RequireLogin` `RequireAdmin` `RequireRole` `CurrentUser` |
67
+ | `ctx.Users` | `Get` `List` `Update` |
68
+ | `ctx.DB` | `Create` `CreateMany` `Get` `Update` `UpdateMany` `Delete` `Query` |
69
+ | `ctx.Notify` | `Send` |
70
+ | `ctx.Config` | `Get(key, default)` |
71
+ | `ctx.Cache` | `Get` `Set` `Delete` |
72
+ | `ctx.HTTP` | `Get` `Post` `Put` `Patch` `Delete`；头用 `http.Header` |
73
+ | `ctx.Wallet` | `Balance` `Journals` `Adjust` `Reverse`；金额用显示单位字符串 `amount`，禁止 `amount_minor` |
74
+ | `ctx.Payment` | `List` `Get` `Start` `Close` `Query` `Refunds` `Refund` |
75
+ | `ctx.AI` | `Chat` `GenerateImage` `Responses` `CompactResponse` `Embeddings` `Rerank` `TextToSpeech` `Transcribe` `Request`；插件 `InstallPluginArchive` `ListPluginVersions` `RestorePlugin` |
76
+ | `ctx.Knowledge` | `List` `Get` `Create` `Update` `Delete`；文档 `ListDocuments` `GetDocument` `UploadDocument` `UpdateDocument` `DeleteDocument` `ReindexDocument`；`ListChunks` `UpdateChunk` `Retrieve` `RebuildIndex` |
77
+ | `ctx.Memory` | `List` `Get` `Create` `Update` `Delete` `IndexStatus` `Reindex` |
78
+ | `ctx.Log` | `Debug` `Info` `Warn` `Error` |
79
+ | `ctx` | `Respond` `Invoke` `Context` |
19
80
 
20
- ## 策略与运行
81
+ 页面、组件、备份、服务管理接口不进入 SDK。
21
82
 
22
- 服务默认要求登录，公开访问依据明确产品需求。先读取策略与版本，使用 base_version 保存；平台共享配置走独立接口。访问范围、角色顺序、个人限制和服务运行限制按实时 schema 配置，以后端预览核对匿名、目标用户和多角色结果。
83
+ ## 保存与验收
23
84
 
24
- 入口允许调用不代表业务数据全部可访问。SDK 使用调用者身份；受信任服务有明确业务需要并验证条件后才显式使用 ctx.Admin.*。CLI 不注入系统身份。
85
+ 1. 已有服务先唯一定位并 checkout；新建用 `draftgo api search "custom service"` → describe → call（结构化创建）拿 ID，再 checkout 源码。
86
+ 2. 保存只交 `source` 和读到的 `base_revision`（由 `draftgo commit services <id>` 提交）。策略独立读、按版本写；禁止随源码带空 config 重置权限。
87
+ 3. validate / 草稿试运行 / publish 都对当前实例 search → describe → call。不要把 operation_id 清单写死；需要时用一个例子，并同时 describe 当前实例。禁止用已发布 execute 冒充草稿结果。
88
+ 4. 用户要求上线时 publish 已验证的 revision，并回读版本。
25
89
 
26
- 每次执行独立子进程。goroutine、channel 与请求内并行在 handler 返回前收束；持久任务使用底座可靠执行机制。依赖通过平台声明、验证和锁定流程获取，不替换托管 SDK。
90
+ 完成证据：草稿 revision、验证结果、试运行执行 ID；发布时加版本和真实调用结果。
27
91
 
28
- ## 失败与完成证据
92
+ ## 失败
29
93
 
30
- 401/403 检查身份、操作权限和策略；409 检查版本或幂等冲突并保留源码；429 检查调用限制；503 检查服务和容量；504 检查超时。执行结果不明先查记录，不重复有副作用调用。
94
+ | HTTP | 先查 |
95
+ |---|---|
96
+ | 401 / 403 | 登录、操作权限、服务策略 |
97
+ | 409 | 草稿 revision 或幂等键，保留源码 |
98
+ | 413 | 输入过大 |
99
+ | 429 | 频率 / 用户并发 |
100
+ | 500 | 执行失败或输出超限；查执行记录。SDK HTTP 远程 500 不是平台 500 |
101
+ | 503 | 未发布、停用、队列或运行时 |
102
+ | 504 | 超时 |
31
103
 
32
- 完成证据：草稿 revision、验证结果、试运行执行 ID；涉及发布时补充发布版本和真实调用结果。HTTP 路由存在而 MCP 搜不到时检查 OpenAPI/Registry 登记，不据此断言模块不存在。
104
+ 结果不明先回读执行记录，不重复有副作用调用。