draftgo-cli 4.0.22 → 4.0.24

package/resources/skill/references/methods.md

@@ -60,6 +60,7 @@ DataRange     = 作用域内记录策略：none / own / all
 
 platform AccessGrant 可跨空间，但只覆盖角色中显式列出的权限；space Grant 只能覆盖同根的 self/subtree。请求 header 只是候选上下文。
 创建、读取、更新、删除都必须由服务端同时校验动作权限、持久化 ResourceOwnership 和 DataRange。
+用户注册成功时，服务端会授予所有启用的注册默认平台 Role，并将用户加入系统默认工作区及其 `default_members` 用户组；前者创建 AccessGrant，后者创建成员关系，两者互不替代。
 
 ### 空间化最短流程
 
@@ -84,6 +85,8 @@ platform AccessGrant 可跨空间，但只覆盖角色中显式列出的权限
 
 适用场景：修改已有 page/navigation/article 完整正文，或创建后继续编辑正文。
 
+`docs/articles` 是系统说明使用的平台资源，只接受 platform scope；不要为文档传 `scope_type=space` 或 `space_id`。
+
 ```bash
 draftgo map --type pages --route /admin/channel-ops --output json
 draftgo checkout pages <id>

package/resources/skill/references/modules.md

@@ -1,27 +1,27 @@
----
-read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目做全局了解时
----
-
-# DraftGo 模块地图
-
-## 可开发模块（开发者负责实现）
-
-| 模块 | 开发方式 | 入口 |
-|---|---|---|
+---
+read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目做全局了解时
+---
+
+# DraftGo 模块地图
+
+## 可开发模块（开发者负责实现）
+
+| 模块 | 开发方式 | 入口 |
+|---|---|---|
 | 页面 | 数据库 HTML（`page.value.html`） | 已有页面由 MCP 定位后 `checkout pages` / `commit pages`；新页面先按实时 API 契约创建并取得 ID |
-| 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
+| 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
 | 动态 DB | db_meta 定义 schema 并操作结构化记录 | MCP `api_search` / `api_describe` / `api_call` |
 | 文件资产 | 文件夹、文件元数据、绑定、下载、回收站和对象存储 | MCP 实时 API；文件字节不进入普通 tool result |
 | 自定义服务 | 单一 Go `Register` 服务；后端从注册代码自动发现 Route/Event/Scheduled handler | MCP 定位/创建；正文用 `checkout custom-services` / `commit custom-services` |
-| AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | MCP 实时 API；不创建本地镜像 |
-| 文档中心 | Markdown/HTML 文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP |
+| AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | MCP 实时 API；不创建本地镜像 |
+| 文档中心 | 平台级 Markdown/HTML 系统文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP；不传 space scope |
 | 系统配置 | KV 存储，含全局前端层槽位 | MCP 实时 API；不创建本地镜像 |
 | 商业与计费 | 账本、余额、权益、支付订单、退款、套餐、订阅和 AI 计费 | 管理任务用 MCP 实时 API；自定义服务用 `ctx.Billing` / `ctx.Admin.Billing`；不要用动态 DB 重建金钱状态 |
-
-## 平台内置模块（开箱即用，不需实现）
-
-| 模块 | 能力 | 调用方式 |
-|---|---|---|
+
+## 平台内置模块（开箱即用，不需实现）
+
+| 模块 | 能力 | 调用方式 |
+|---|---|---|
 | 认证 | 注册/登录/刷新/找回密码/微信登录/手机邮箱验证 | 页面使用 `App`；服务端操作通过 MCP 实时描述接口 |
 | 角色权限 | 无作用域 Role 模板 + 带 `platform` / `space` 范围的 AccessGrant | 页面可用 `App.permissions` 辅助显隐；服务端按资源授权 |
 | 工作区与空间 | 根工作区成员、用户组和递归 Space；成员关系本身不授权 | `App.scopeContext` + MCP space/group/grant operations；资源保存直接归属 |
@@ -33,7 +33,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 
 `App.currentUser.role_code` 是展示投影，不是用户表中的可写字段。真正的资源/API 授权由服务端根据 ResourceOwnership 与有效 AccessGrant 决定；platform Grant 也只能使用角色中显式声明的权限。
 
-用户 API Key 只是一种用户认证方式；它不改变 AccessGrant、ResourceOwnership、DataRange 或管理员边界。服务身份是平台运行时主体。
+用户 API Key 只是一种用户认证方式；它不改变 AccessGrant、ResourceOwnership、DataRange 或管理员边界。无人值守任务由平台运行时以 system 身份执行。
 
 ## 新模块权限接入检查表
 
@@ -47,12 +47,12 @@ AI 新建或扩展受保护模块时，按以下最小闭环逐项确认；缺
 - [ ] 保留最小拒绝证据：无 Grant、space Grant 跨根、伪造归属；支持 own/all 时再覆盖他人记录拒绝。不要为同一规则复制一套测试框架。
 
 实现位置和具体 API 以目标 DraftGo 服务端仓库的现有 Catalog、ResourceOwnership 与 WorkspaceAuthorizer 模式为准；本 Skill 不复制服务端动态 schema。
-
-## 模块选型决策
-
-```
+
+## 模块选型决策
+
+```
 要存储业务数据？
-  → 有固定结构 → 动态 DB（db_meta 定义 schema）
+  → 有固定结构 → 动态 DB（db_meta 定义 schema）
   → 仅需 KV → sys_config（category 自定义）
 
 要保存文件？
@@ -60,35 +60,35 @@ AI 新建或扩展受保护模块时，按以下最小闭环逐项确认；缺
 
 要做余额、支付、会员或订阅？
   → 管理操作走 money/payment/subscription/billing 的 MCP 实时契约；自定义服务读 `.draftgo-sdk/billing.go` 并使用 Billing SDK，不自行实现账本或扣费一致性
-
-要调用 AI？
-  → 聊天/问答 UI → AIHub + `<dg-chat>`（自动隔离 thread/session）
-  → 无 UI 的旧代码文本调用 → AIHub + DraftGoAI.chat()（兼容门面）
+
+要调用 AI？
+  → 聊天/问答 UI → AIHub + `<dg-chat>`（自动隔离 thread/session）
+  → 无 UI 的旧代码文本调用 → AIHub + DraftGoAI.chat()（兼容门面）
   → 图片生成 → AIHub + DraftGoAI.images()
   → Responses、Embedding、Rerank、TTS、ASR 或 Video → AIHub capability 与 provider readiness；先确认模型的 canonical capability 和 transport
-  → 需要工具/子智能体/记忆/结构化输出/多模态 → 都是 Agent spec 开关，见 references/aihub.md
-
-要调用第三方服务？
+  → 需要工具/子智能体/记忆/结构化输出/多模态 → 都是 Agent spec 开关，见 references/aihub.md
+
+要调用第三方服务？
   → 自定义服务（用 `ctx.HTTP` 请求；在同一 Go 服务中按需注册 Route/Event/Scheduled handler）
-
-要展示内容文档？
-  → 文档中心（Markdown + 分类树）
-
-要做定时任务或事件响应？
+
+要展示内容文档？
+  → 文档中心（Markdown + 分类树）
+
+要做定时任务或事件响应？
   → 自定义服务（用 `app.Schedule` / `app.On` 注册；后端自动识别定时任务和事件 handler）
-
-要做后台管理页？
-  → 业务页面 + 动态 DB + 角色权限
-```
-
-## 自定义服务边界
-
-- 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
+
+要做后台管理页？
+  → 业务页面 + 动态 DB + 角色权限
+```
+
+## 自定义服务边界
+
+- 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
 - `Route`：对外暴露 HTTP 端点；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，实际路径通过 MCP 实时发现，草稿行为先用 `draftgo test custom-services` 验证。
 - `Event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
 - `Scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
-- 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。
-- 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 调用面继续由每个服务的 `permission` / `route_security` 独立控制，不要把两层权限混为一谈。
-- Go 服务在独立子进程中构建/运行；只有可信角色才能获得 `scripts:create` / `scripts:update`。
-- 自定义服务适合服务端加工、鉴权后聚合、第三方回调、定时任务和事件响应；普通 CRUD 管理界面优先用“页面 + 动态 DB”，不要把所有业务后台都塞进 route 脚本。
+- 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。
+- 管理面由角色 RBAC 的 `scripts:*` 动作控制；Route 不再读取服务级 `permission`，由宿主认证、持久化 ownership 和 `scripts:execute` AccessGrant 统一控制。
+- Go 服务在独立子进程中构建/运行；只有可信角色才能获得 `scripts:create` / `scripts:update`。
+- 自定义服务适合服务端加工、鉴权后聚合、第三方回调、定时任务和事件响应；普通 CRUD 管理界面优先用“页面 + 动态 DB”，不要把所有业务后台都塞进 route 脚本。
 - 脚本内读动态 DB 用 `ctx.DB.Query(type, sdk.QueryOptions{...})`；返回 `sdk.QueryResult`，分页和筛选见 `references/custom-services.md`。

package/resources/skill/references/runtime.md

@@ -1,113 +1,113 @@
----
-read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问题时
----
-
-# 运行时机制（Runtime）
-
-## 壳层启动流程
-
-1. `reloadSystemConfig()` — 拉取 `/api/system/config`，填充 `state.config`
-2. `validateToken()` — 验证 `localStorage.dg_access_token`，成功后设置 `currentUser`
-3. `loadSetupStatus()` — 检查系统是否已初始化
-4. `loadPage()` — 根据当前路由拉取页面 HTML，注入 iframe
-
----
-
-## iframe 注入机制
-
-壳层通过 `decorateFrameHtml(html, routeContext, theme)` 处理数据库页面 HTML，注入：
-
-- `window.__DG_ROUTE_CONTEXT__` — 当前路由上下文（含 `query` 参数），冻结对象
-- `window.__DG_QUERY__` — `routeContext.query` 快捷方式
-- `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式兜底读取
-- 主题 CSS 变量（写入 `<head>` 最顶部，DOM 解析时即生效）
+---
+read_when: 需要理解运行时机制时 · 处理 token/路由/事件相关问题时
+---
+
+# 运行时机制（Runtime）
+
+## 壳层启动流程
+
+1. `reloadSystemConfig()` — 拉取 `/api/system/config`，填充 `state.config`
+2. `validateToken()` — 验证 `localStorage.dg_access_token`，成功后设置 `currentUser`
+3. `loadSetupStatus()` — 检查系统是否已初始化
+4. `loadPage()` — 根据当前路由拉取页面 HTML，注入 iframe
+
+---
+
+## iframe 注入机制
+
+壳层通过 `decorateFrameHtml(html, routeContext, theme)` 处理数据库页面 HTML，注入：
+
+- `window.__DG_ROUTE_CONTEXT__` — 当前路由上下文（含 `query` 参数），冻结对象
+- `window.__DG_QUERY__` — `routeContext.query` 快捷方式
+- `window.__DG_GET_ROUTE_CONTEXT__()` — 函数形式兜底读取
+- 主题 CSS 变量（写入 `<head>` 最顶部，DOM 解析时即生效）
 - 组件库主题适配器；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`，并跳转系统配置的登录页
-
----
-
-## App 对象来源
-
-壳层将 `app` 对象赋值给 `window.App`，页面通过 `window.parent.App` 访问。
-
+
+---
+
+## App 对象来源
+
+壳层将 `app` 对象赋值给 `window.App`，页面通过 `window.parent.App` 访问。
+
 `app` 组成：`api.js`（请求）+ `feedback.js`（弹窗/Toast）+ `runtime.js`（路由/主题/作用域）+ `i18n.js`（国际化）+ state（currentUser/isAdmin/config/theme/scopeContext）
-
+
 完整 API 见 `references/app-api.md`
-
----
-
-## Token 存储
-
-| key | 说明 |
-|---|---|
-| `localStorage.dg_access_token` | 访问 token |
-| `localStorage.dg_refresh_token` | 刷新 token |
-
-登录后调用 `App.setAuthTokens({ access_token, refresh_token })` 写入并触发验证。  
-401 时壳层自动用 refresh token 刷新，无需页面处理。
-
----
-
-## URL 参数读取（标准三阶回落）
-
-```javascript
-const routeContext =
-  window.__DG_ROUTE_CONTEXT__
-  || window.__DG_GET_ROUTE_CONTEXT__?.()
-  || window.parent?.App?.getCurrentRouteContext?.()
-  || { query: {} };
-const query = routeContext.query || {};
-
-// 路由 /orders?orderId=42
-const orderId = query.orderId;  // "42"
-```
-
-**禁止**：`new URLSearchParams(window.location.search)` / 直接读 `window.location.search`
-
----
-
-## 全局事件
-
-| 事件名 | 触发时机 |
-|---|---|
-| `dg:auth-ready` | token 验证完成（成功或失败） |
-| `dg:auth-changed` | token 变更（登录/登出） |
-
-监听方式：`window.parent.addEventListener('dg:auth-ready', handler)`
-
----
-
-## 前端全局层
-
-全局浮窗、客服入口、统计脚本等属于全局层，不属于单个业务页面。
-
-存储：`sys_config.category = frontend_global`
-
+
+---
+
+## Token 存储
+
+| key | 说明 |
+|---|---|
+| `localStorage.dg_access_token` | 访问 token |
+| `localStorage.dg_refresh_token` | 刷新 token |
+
+登录后调用 `App.setAuthTokens({ access_token, refresh_token })` 写入并触发验证。  
+401 时壳层自动用 refresh token 刷新，无需页面处理。
+
+---
+
+## URL 参数读取（标准三阶回落）
+
+```javascript
+const routeContext =
+  window.__DG_ROUTE_CONTEXT__
+  || window.__DG_GET_ROUTE_CONTEXT__?.()
+  || window.parent?.App?.getCurrentRouteContext?.()
+  || { query: {} };
+const query = routeContext.query || {};
+
+// 路由 /orders?orderId=42
+const orderId = query.orderId;  // "42"
+```
+
+**禁止**：`new URLSearchParams(window.location.search)` / 直接读 `window.location.search`
+
+---
+
+## 全局事件
+
+| 事件名 | 触发时机 |
+|---|---|
+| `dg:auth-ready` | token 验证完成（成功或失败） |
+| `dg:auth-changed` | token 变更（登录/登出） |
+
+监听方式：`window.parent.addEventListener('dg:auth-ready', handler)`
+
+---
+
+## 前端全局层
+
+全局浮窗、客服入口、统计脚本等属于全局层，不属于单个业务页面。
+
+存储：`sys_config.category = frontend_global`
+
 固定槽位覆盖总开关与安全模式、壳层 head/body/CSS/JS、iframe head、全局挂件、Toast 和滚动条配置。不要凭静态文档猜测全部键名或枚举；修改前通过 MCP 查询当前 `system_config` 契约与目标键。
-
-规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**
-
-### 修改方法
-
+
+规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**
+
+### 修改方法
+
 system_config 是结构化远端资源。未知 operation 才通过 MCP `draftgo_api_search` 定位；首次使用或
 registry revision 变化时 `draftgo_api_describe`，再用 `draftgo_api_call` 读取并更新目标键；不要 checkout
 或维护本地索引。
-
-前端全局层是系统默认配置。更新现有全局配置时只发送 `config_value`；不要带 `description`、`category`、
-`value_type`、`status` 等元信息，避免触发“系统默认字段不允许修改字段描述/分类/状态”。
-
-页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中
+
+前端全局层是系统默认配置。更新现有全局配置时只发送 `config_value`；不要带 `description`、`category`、
+`value_type`、`status` 等元信息，避免触发“系统默认字段不允许修改字段描述/分类/状态”。
+
+页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中
 `错误 Toast 时长(s) = 4.5` 对应 `frontend_global_toast_duration_error.config_value = 4500`。
 
 ## 统一作用域
 
 DraftGo 的资源归属和授权范围只有 `platform`、`space`。`Role` 是无作用域权限模板；`AccessGrant`
-定义 user/group/service 主体在哪个范围拥有该角色。工作区成员与用户组成员关系本身不授予权限。
+定义 user/group 主体在哪个范围拥有该角色。运行时 `system/0` 调用不是 AccessGrant 主体；工作区成员与用户组成员关系本身不授予权限。
 
 `platform` Grant 可跨全部空间，但只能使用 Role 中显式列出的权限。`space` Grant 仅覆盖同一根工作区内的
 目标空间或 subtree；所有授权为 allow-only 并集，DataRange 使用 `all > own > none`。
@@ -122,6 +122,5 @@ API 请求只使用 `X-DraftGo-Scope-Type` 与 `X-DraftGo-Space-Id`；workspace_
 `owner_user_id` 只有在服务端契约明确提供后才能使用。
 
 认证边界：交互式 CLI、MCP 和普通 HTTP API 使用当前用户的 API Key；该凭据始终代表该用户，权限来自
-用户及用户组的 AccessGrant，TokenScope 只能收窄，不能变成管理员或服务身份。CI、定时任务和共享服务等
-无人值守自动化使用平台的独立服务凭据通道；service principal 由平台内部注入，CLI 不生成、导出或伪造
-服务身份凭据。
+用户及用户组的 AccessGrant，TokenScope 只能收窄，不能变成管理员或 system 身份。CI、定时任务和共享服务等
+无人值守自动化由平台运行时使用 system 身份；CLI 不生成、导出或伪造服务主体凭据。Event/Scheduled 代码必须显式使用 `ctx.Admin.*`。