draftgo-cli 4.0.22 → 4.0.24

package/resources/skill/references/checkout.md

@@ -1,7 +1,7 @@
----
-read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manifest 时 · 处理 409/412 冲突时
----
-
+---
+read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manifest 时 · 处理 409/412 冲突时
+---
+
 # Checkout / Commit
 
 ## 页面与内容最短流程
@@ -21,120 +21,120 @@ draftgo commit pages 42
 The checkout set includes `pages`, `navigations`, `docs/articles`, and `custom_services`. A custom-service checkout contains exactly `service.go` and `service.json`, plus one complete `.base` directory. Runner-managed `go.mod/go.sum` never participate in diff or commit. `draftgo commit custom-services <id>` performs the complete delivery (`commit -> validate -> publish`) and prints an explicit published confirmation. Use `draftgo test custom-services <id>` for server Runner validation/execution; `draftgo publish custom-services <id>` remains as a direct compatibility entry point. DB Meta remains a live MCP/API resource and is never checked out.
 
 `draftgo refresh <type> <id...>` is a safe checkout shortcut. It updates only a clean local worktree; local changes stop it. A successful commit keeps current local files and one base only. Cloud version storage is the sole history source.
-
-> 根 `SKILL.md` 在 Skill 触发时会自动加载。使用本文件前，先完成根 Skill 的“强制预读：Reference 优先于 MCP”任务路由。本文件只说明长正文的传输、版本和冲突规则，不能替代页面、前端、运行时或安全资料。
-
-## 适用范围
-
-只有长正文使用 worktree：
-
-| 输入类型 | 规范类型 | 本地目录 | 文件前缀 |
-|---|---|---|---|
-| `page` / `pages` | `pages` | `.draftgo/worktree/pages/` | `page_` |
-| `nav` / `navigation` / `navigations` | `navigations` | `.draftgo/worktree/navigations/` | `nav_` |
-| `doc` / `docs` / `article(s)` / `docs/articles` | `docs` | `.draftgo/worktree/docs/` | `article_` |
-
+
+> 根 `SKILL.md` 在 Skill 触发时会自动加载。使用本文件前，先完成根 Skill 的“强制预读：Reference 优先于 MCP”任务路由。本文件只说明长正文的传输、版本和冲突规则，不能替代页面、前端、运行时或安全资料。
+
+## 适用范围
+
+只有长正文使用 worktree：
+
+| 输入类型 | 规范类型 | 本地目录 | 文件前缀 |
+|---|---|---|---|
+| `page` / `pages` | `pages` | `.draftgo/worktree/pages/` | `page_` |
+| `nav` / `navigation` / `navigations` | `navigations` | `.draftgo/worktree/navigations/` | `nav_` |
+| `doc` / `docs` / `article(s)` / `docs/articles` | `docs` | `.draftgo/worktree/docs/` | `article_` |
+
 db_meta、AIHub、system_config、roles、users、doc_categories 和普通配置使用 MCP 实时 API，不 checkout。
 
 Checkout 只为已存在且已确认 ID 的资源建立本地正文与 base，不创建页面、导航或文档。新增资源先按 MCP 实时 API 契约创建并取得 ID；需要编辑完整正文时再 checkout。只需元数据或正文片段即可完成判断时，不必 checkout。
-
-## 命令
-
-```bash
-draftgo checkout <pages|nav|docs> <id...>
+
+## 命令
+
+```bash
+draftgo checkout <pages|nav|docs> <id...>
 draftgo commit <pages|nav|docs> <id...>
 draftgo reconcile <pages|nav|docs> <id...>
 draftgo diff <pages|nav|docs|custom-services> <id> [--stat|--summary]
-draftgo conflicts
-draftgo conflict show <pages|nav|docs> <id>
-draftgo conflict resolve <pages|nav|docs> <id>
-```
-
+draftgo conflicts
+draftgo conflict show <pages|nav|docs> <id>
+draftgo conflict resolve <pages|nav|docs> <id>
+```
+
 `checkout --force` 只用于用户明确允许丢弃未提交本地修改的情况。默认 checkout 检测到 worktree 文件相对
 base 已变化时必须拒绝覆盖。
 
 `diff --stat` 只显示文件与增删行数；`diff --summary` 显示资源、基线版本和变化概要。两者均不输出正文 diff，先用它们确认范围，再按需展开完整 `diff`。`--output json` 时 stdout 只包含 UTF-8 JSON，诊断走 stderr。
-
-## Checkout 流程
-
-1. CLI 通过 MCP `draftgo_resource_get_metadata` 取得规范类型、content_type、SHA-256、大小、版本/revision、
-   ETag 和受信任的下载/提交 URL。
+
+## Checkout 流程
+
+1. CLI 通过 MCP `draftgo_resource_get_metadata` 取得规范类型、content_type、SHA-256、大小、版本/revision、
+   ETag 和受信任的下载/提交 URL。
 2. CLI 使用 `.draftgo/config.json` 中的用户 API Key 通过专用 HTTP 下载完整正文；API Key 不进入 MCP 参数或日志。
-3. 响应体直接流式写入同目录临时文件，校验 content_type、字节数和 SHA-256。
-4. 校验成功后原子重命名到 worktree 文件，并保存相同字节的 `.base` 文件。
-5. 最后原子更新 `.draftgo/worktree/manifest.json`。失败时不得留下半截正式文件或推进 manifest。
-
-正文不做 HTML/Markdown 转换，也不改变编码。扩展名规则：
-
-- `text/html`、`application/xhtml+xml` -> `.html`
-- `text/markdown`、`text/x-markdown` -> `.md`
-- `text/plain` -> `.txt`
-- 其他类型只接受底座返回的安全扩展名；缺失或不安全时拒绝 checkout
-
-## Manifest
-
-路径固定为 `.draftgo/worktree/manifest.json`，schema version 当前为 `1`。条目键使用规范类型和 id：
-
-```json
-{
-  "schema_version": 1,
-  "updated_at": "2026-07-30T12:00:00.000Z",
-  "entries": {
-    "pages:42": {
-      "server": "https://draftgo.example",
-      "resource_type": "pages",
-      "resource_id": "42",
-      "title": "Example",
-      "route": "/example",
-      "code": null,
-      "slug": null,
-      "local_path": ".draftgo/worktree/pages/page_42.html",
-      "content_type": "text/html",
-      "file_extension": ".html",
-      "content_size": 123,
-      "base_path": ".draftgo/worktree/.base/pages/page_42.html",
-      "base_version": "7",
-      "base_revision": null,
-      "base_etag": null,
-      "base_hash": "<sha256>",
-      "checked_out_at": "2026-07-30T12:00:00.000Z"
-    }
-  }
-}
-```
-
-`server` 必须和当前连接一致。`local_path`、`base_path` 必须是项目内相对路径。manifest、worktree `.base`
-和冲突目录必须 gitignore；不要手工伪造版本或哈希。
-
-## Commit 流程
-
-1. 读取 manifest 指向的 worktree 文件，计算当前字节数和 SHA-256；未变化时返回 `unchanged`。
+3. 响应体直接流式写入同目录临时文件，校验 content_type、字节数和 SHA-256。
+4. 校验成功后原子重命名到 worktree 文件，并保存相同字节的 `.base` 文件。
+5. 最后原子更新 `.draftgo/worktree/manifest.json`。失败时不得留下半截正式文件或推进 manifest。
+
+正文不做 HTML/Markdown 转换，也不改变编码。扩展名规则：
+
+- `text/html`、`application/xhtml+xml` -> `.html`
+- `text/markdown`、`text/x-markdown` -> `.md`
+- `text/plain` -> `.txt`
+- 其他类型只接受底座返回的安全扩展名；缺失或不安全时拒绝 checkout
+
+## Manifest
+
+路径固定为 `.draftgo/worktree/manifest.json`，schema version 当前为 `1`。条目键使用规范类型和 id：
+
+```json
+{
+  "schema_version": 1,
+  "updated_at": "2026-07-30T12:00:00.000Z",
+  "entries": {
+    "pages:42": {
+      "server": "https://draftgo.example",
+      "resource_type": "pages",
+      "resource_id": "42",
+      "title": "Example",
+      "route": "/example",
+      "code": null,
+      "slug": null,
+      "local_path": ".draftgo/worktree/pages/page_42.html",
+      "content_type": "text/html",
+      "file_extension": ".html",
+      "content_size": 123,
+      "base_path": ".draftgo/worktree/.base/pages/page_42.html",
+      "base_version": "7",
+      "base_revision": null,
+      "base_etag": null,
+      "base_hash": "<sha256>",
+      "checked_out_at": "2026-07-30T12:00:00.000Z"
+    }
+  }
+}
+```
+
+`server` 必须和当前连接一致。`local_path`、`base_path` 必须是项目内相对路径。manifest、worktree `.base`
+和冲突目录必须 gitignore；不要手工伪造版本或哈希。
+
+## Commit 流程
+
+1. 读取 manifest 指向的 worktree 文件，计算当前字节数和 SHA-256；未变化时返回 `unchanged`。
 2. 按 content_type 执行本地结构和内联脚本检查。
-3. 通过专用 HTTP 流式上传原始文件，携带 `If-Match`、base version/revision、content_type、长度和 SHA-256。
-4. 完整正文不得作为 MCP tool 参数发送。
-5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
-
+3. 通过专用 HTTP 流式上传原始文件，携带 `If-Match`、base version/revision、content_type、长度和 SHA-256。
+4. 完整正文不得作为 MCP tool 参数发送。
+5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
+
 本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
 
 单个 commit 成功不自动完成 worklog 项。只有整个事项统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行 `draftgo work complete <编号> --note "<完成结果>"`。任何检查失败、409/412 或交付失败都不得标记为完成。
-
-## 409 / 412 冲突
-
-版本冲突时 CLI 返回非零，不自动重试、不 force、不覆盖 worktree local，并写入：
-
-```text
-.draftgo/conflicts/<pages|navigations|docs>/<id>/
-├── conflict.json
-├── base.<ext>
-├── local.<ext>
-└── remote.<ext>
-```
-
-- `base` 是 checkout 时的内容；`local` 是发生冲突时的本地快照；`remote` 是重新下载并校验的当前远端内容。
-- `conflict.json` 记录三份路径、版本、ETag 和哈希，不嵌入完整正文。
-- Agent 或用户在 worktree local 文件中完成合并；不要手写 HTML 自动合并器，也不要改动保存的三份证据。
+
+## 409 / 412 冲突
+
+版本冲突时 CLI 返回非零，不自动重试、不 force、不覆盖 worktree local，并写入：
+
+```text
+.draftgo/conflicts/<pages|navigations|docs>/<id>/
+├── conflict.json
+├── base.<ext>
+├── local.<ext>
+└── remote.<ext>
+```
+
+- `base` 是 checkout 时的内容；`local` 是发生冲突时的本地快照；`remote` 是重新下载并校验的当前远端内容。
+- `conflict.json` 记录三份路径、版本、ETag 和哈希，不嵌入完整正文。
+- Agent 或用户在 worktree local 文件中完成合并；不要手写 HTML 自动合并器，也不要改动保存的三份证据。
 - 合并完成后运行 `draftgo verify`，再执行 `draftgo conflict resolve <type> <id>`。
-- resolve 校验 worktree 与 remote，采用 remote 版本作为新的 base，但保留合并后的 worktree；随后运行
-  `draftgo diff` 并 `draftgo commit`。
-
-存在 unresolved conflict 时 commit、deploy 或 auto-commit 必须停止。
+- resolve 校验 worktree 与 remote，采用 remote 版本作为新的 base，但保留合并后的 worktree；随后运行
+  `draftgo diff` 并 `draftgo commit`。
+
+存在 unresolved conflict 时 commit、deploy 或 auto-commit 必须停止。

package/resources/skill/references/custom-services.md

@@ -62,7 +62,7 @@ func health(ctx *sdk.Context) (any, error) {
 
 输入字段为 `method`、`headers`、`body`、`query_params`、`path_params`。身份由 `ctx.Auth.CurrentUser()` 获取。普通 `ctx.DB`、`ctx.Users`、`ctx.Billing` 等调用继承请求调用者权限；管理员创建服务、持有服务凭据或 `RequireAdmin` 都不会自动提升 SDK 调用。
 
-`ctx.Admin.*` 是可信服务显式选择的单次管理提升：保持服务主体与已验证执行上下文，但可执行平台级或跨用户/空间管理操作；每次调用都会进入审计，提升不会泄漏到后续普通调用。服务代码仍拿不到服务凭据、数据库连接或管理员凭据。公开 Route 不应无条件调用 Admin；先完成业务鉴权、参数校验和幂等设计，返回值仍需自行脱敏。
+`ctx.Admin.*` 是自定义服务显式选择的单次系统内部授权：该次 RPC 使用 system actor_id=0，按 `*:*:all` 全权限执行，可跨用户/空间，不检查 AccessGrant；每次调用进入审计，内部授权不会泄漏到后续普通调用。Event/Scheduled 没有调用者，普通 `ctx.xxx` 返回 403。服务代码仍拿不到服务凭据、数据库连接或管理员凭据。公开 Route 不应无条件调用 Admin；先完成业务鉴权、参数校验和幂等设计，返回值仍需自行脱敏。
 
 ### Event
 
@@ -70,7 +70,7 @@ func health(ctx *sdk.Context) (any, error) {
 
 ### Scheduled
 
-`app.Schedule("0 2 * * *", cleanup)` 使用五字段 cron，也支持 `interval:5m`。定时任务没有用户调用者；执行空间来自服务持久化的 ResourceOwnership，服务 principal 还必须有覆盖目标资源的 AccessGrant。运行时不会猜测用户或回退到 platform。
+`app.Schedule("0 2 * * *", cleanup)` 使用五字段 cron，也支持 `interval:5m`。定时任务没有用户调用者；执行空间来自服务持久化的 ResourceOwnership，普通 SDK 调用必须改用 `ctx.Admin.*`，运行时不会猜测用户或回退到 platform。
 
 ## 试运行
 
@@ -126,7 +126,7 @@ response, err := ctx.HTTP.Get(ctx.Context(), "https://api.example.com/health", n
 | 场景 | 方法 |
 |---|---|
 | 当前调用者操作服务归属内账务 | `ctx.Billing.*` |
-| 可信服务执行需要管理员权限的账务管理 | `ctx.Admin.Billing.*`；目标仍由服务端资源归属决定 |
+| 自定义服务执行系统级账务管理 | `ctx.Admin.Billing.*`；单次调用按系统全权限执行并审计 |
 | 金额已确定且应立即扣除 | `DebitAccount` |
 | 最终金额不确定或业务可能失败 | `HoldFunds` -> `SettleHold`；失败时 `ReleaseHold` |
 | 更正已入账流水 | `ReverseJournal`，不要用反向充值伪造冲正 |
@@ -179,9 +179,9 @@ typed helper 未覆盖的新端点可使用 `ctx.AIHub.Request`，但 path 只
 - Role 不带作用域；服务必须通过覆盖持久化 ResourceOwnership 的有效 AccessGrant 授权。工作区成员关系不能单独授权。
 - platform Grant 可跨空间但只能使用显式权限；space Grant 不能跨根。请求中的范围不能覆盖服务已保存的归属。
 - 普通服务调用访问动态 DB 时仍受目标 DB 的 DataRange（`none` / `own` / `all`）限制；`ctx.Admin.*` 只应用于源码明确选择的单次可信管理操作，不能从请求参数隐式开启。
-- Route 仍受服务 `permission` 与 `config.route_security` 控制。
-- 定时任务和无可解析用户的事件默认使用服务主体及其持久化空间；需要平台级或跨归属管理时必须在对应单次调用显式使用 `ctx.Admin.*`。
-- 服务 principal 由平台运行时注入；不要在 `service.json`、源码、测试参数或日志中保存/模拟服务身份凭据。Route/Event 取调用者与服务 Grant 的权限交集，Scheduled 使用服务持久化 ownership，而不是假造用户 API Key。
+- Route 不接受服务级 `permission`；入口由宿主认证、服务 ownership 和调用者 `scripts:execute` AccessGrant 控制，业务级公开/登录规则在 handler 内显式实现。
+- 定时任务和事件没有调用者，普通 `ctx.xxx` 直接返回 403；必须在对应单次调用显式使用 `ctx.Admin.*`。服务归属仍由持久化 ResourceOwnership 提供，不创建服务主体授权。
+- 平台运行时注入真实 user 或 system principal；不要在 `service.json`、源码、测试参数或日志中保存/模拟服务身份凭据。Route 普通调用按用户 AccessGrant，Event/Scheduled 仅允许 Admin RPC。
 - `config.timeout`、`max_concurrency`、`queue_timeout_ms` 控制执行；Route 饱和返回 429。
 - 超时会终止独立子进程。运行器不是不可信多租户安全沙箱，只授予可信编辑者服务权限。
 - 构建键覆盖源码、依赖、SDK 和 Runner 协议；有效验证凭证绑定该键，任一部分变化都必须重新验证。

package/resources/skill/references/data.md

@@ -1,7 +1,7 @@
----
-read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检索时 · 定义关联关系时
----
-
+---
+read_when: 操作动态 DB 之前 · 设计数据结构时 · 使用 filters 检索时 · 定义关联关系时
+---
+
 # 动态 DB & 数据层
 
 ## 最短管理流程
@@ -20,180 +20,180 @@ draftgo api search "dynamic db record"
 完成条件：schema 可按 `type` 回读，目标角色的最小 CRUD 与筛选行为通过；批量写入还要验证失败时整批回滚。
 
 ## DB Meta 结构
-
-```json
-{
-  "type": "order",
-  "label": "订单",
-  "schema": {
-    "type": "object",
-    "properties": {
-      "name":   { "type": "string",  "title": "姓名",   "required": true,  "searchable": "fuzzy" },
-      "status": { "type": "string",  "title": "状态",   "required": false, "searchable": "exact" },
-      "amount": { "type": "number",  "title": "金额",   "required": false, "searchable": "range" },
-      "paid_at": { "type": "datetime", "title": "支付时间", "required": false, "searchable": "range" },
-      "tags":   { "type": "array",   "title": "标签",   "required": false, "searchable": "contains" },
-      "note":   { "type": "string",  "title": "备注",   "required": false, "searchable": false }
-    }
-  },
-  "permission": {
-    "public":  { "read": "none",  "create": "none",  "update": "none",  "delete": "none" },
-    "login":   { "read": "all",   "create": "all",   "update": "owner", "delete": "owner" },
-    "admin":   { "read": "all",   "create": "all",   "update": "all",   "delete": "all" }
-  }
-}
-```
-
-**searchable 模式**：`false`（不可检索）/ `"exact"`（精确）/ `"fuzzy"`（模糊）/ `"range"`（数值/时间范围）/ `"contains"`（数组包含）
-
-`date` 字段保存为 `YYYY-MM-DD`；`datetime` 字段保存为 ISO 8601 字符串，带时区的输入会规范化为 UTC。`searchable: true` 对 `number` / `date` / `datetime` 会自动推断为 `range`。
-
-**系统字段**：以下系统字段**无需在 schema 中定义**，可直接用于检索和排序：
-
-| 字段 | 类型 | 检索模式 | 说明 |
-|---|---|---|---|
-| `id` | number | range | 记录 ID，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
-| `userid` | number | range | 所属用户 ID，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
-| `created_at` | datetime | range | 创建时间，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
-| `updated_at` | datetime | range | 更新时间，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
-
-⚠️ **注意**：虽然 DB 表有 `status` 系统列（1=正常 0=禁用 -1=删除），但由于业务常用此字段名，**需在 schema 中显式声明 `status` 的 searchable 才可检索**。
-
----
-
+
+```json
+{
+  "type": "order",
+  "label": "订单",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name":   { "type": "string",  "title": "姓名",   "required": true,  "searchable": "fuzzy" },
+      "status": { "type": "string",  "title": "状态",   "required": false, "searchable": "exact" },
+      "amount": { "type": "number",  "title": "金额",   "required": false, "searchable": "range" },
+      "paid_at": { "type": "datetime", "title": "支付时间", "required": false, "searchable": "range" },
+      "tags":   { "type": "array",   "title": "标签",   "required": false, "searchable": "contains" },
+      "note":   { "type": "string",  "title": "备注",   "required": false, "searchable": false }
+    }
+  },
+  "permission": {
+    "public":  { "read": "none",  "create": "none",  "update": "none",  "delete": "none" },
+    "login":   { "read": "all",   "create": "all",   "update": "owner", "delete": "owner" },
+    "admin":   { "read": "all",   "create": "all",   "update": "all",   "delete": "all" }
+  }
+}
+```
+
+**searchable 模式**：`false`（不可检索）/ `"exact"`（精确）/ `"fuzzy"`（模糊）/ `"range"`（数值/时间范围）/ `"contains"`（数组包含）
+
+`date` 字段保存为 `YYYY-MM-DD`；`datetime` 字段保存为 ISO 8601 字符串，带时区的输入会规范化为 UTC。`searchable: true` 对 `number` / `date` / `datetime` 会自动推断为 `range`。
+
+**系统字段**：以下系统字段**无需在 schema 中定义**，可直接用于检索和排序：
+
+| 字段 | 类型 | 检索模式 | 说明 |
+|---|---|---|---|
+| `id` | number | range | 记录 ID，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+| `userid` | number | range | 所属用户 ID，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+| `created_at` | datetime | range | 创建时间，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+| `updated_at` | datetime | range | 更新时间，支持 `eq` / `gte` / `lte` / `gt` / `lt` / `in` |
+
+⚠️ **注意**：虽然 DB 表有 `status` 系统列（1=正常 0=禁用 -1=删除），但由于业务常用此字段名，**需在 schema 中显式声明 `status` 的 searchable 才可检索**。
+
+---
+
 ## 自定义服务内的 ctx.DB.Query
 
 Go 自定义服务使用 `ctx.DB.Query(type, sdk.QueryOptions{...})` 操作动态 DB，返回 `sdk.QueryResult`：
 
 ```go
 result, err := ctx.DB.Query("order", sdk.QueryOptions{
-    Filters: map[string]any{"status": "paid"},
-    Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
-})
-items := result.Items
-```
-
-| 参数 | 说明 |
-|---|---|
-| `filters` | 字典形式结构化过滤；默认 `{field: value}` 是 `eq` 精确匹配 |
-| `Page` / `PageSize` | 分页参数；零值交由平台使用默认列表行为 |
-| `order_by` / `order` | 按 searchable 字段排序，`order` 为 `asc` / `desc` |
-
-⚠️ 返回结构为 `sdk.QueryResult{Items, Total, Page, PageSize}`。需要完整数据时必须按 `Total` 分页读取，不能用超大 `PageSize` 假装全量。
-
-普通用户调用时只读 `status=1` 数据；系统身份/管理员脚本可读全部状态数据，但仍受 db_meta permission 约束。不要把“拿不到禁用数据”和分页截断混在一起排查。
-
-`filters` 操作符示例：
-
-```go
+    Filters: map[string]any{"status": "paid"},
+    Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
+})
+items := result.Items
+```
+
+| 参数 | 说明 |
+|---|---|
+| `filters` | 字典形式结构化过滤；默认 `{field: value}` 是 `eq` 精确匹配 |
+| `Page` / `PageSize` | 分页参数；零值交由平台使用默认列表行为 |
+| `order_by` / `order` | 按 searchable 字段排序，`order` 为 `asc` / `desc` |
+
+⚠️ 返回结构为 `sdk.QueryResult{Items, Total, Page, PageSize}`。需要完整数据时必须按 `Total` 分页读取，不能用超大 `PageSize` 假装全量。
+
+普通用户调用时只读 `status=1` 数据；系统身份/管理员脚本可读全部状态数据，但仍受 db_meta permission 约束。不要把“拿不到禁用数据”和分页截断混在一起排查。
+
+`filters` 操作符示例：
+
+```go
 ctx.DB.Query("order", sdk.QueryOptions{Filters: map[string]any{
-    "status": "paid",
-    "customer_name": map[string]any{"op": "like", "value": "张"},
-    "amount": map[string]any{"op": "gte", "value": 100},
-    "id": map[string]any{"op": "in", "value": []int{1, 2, 3}},
-}})
-```
-
-字段必须在 db_meta schema 中标记 `searchable`，系统字段 `id/userid/created_at/updated_at` 可直接检索和排序。`status` 若作为业务字段检索，仍需在 schema 中显式声明。
-
----
-
+    "status": "paid",
+    "customer_name": map[string]any{"op": "like", "value": "张"},
+    "amount": map[string]any{"op": "gte", "value": 100},
+    "id": map[string]any{"op": "in", "value": []int{1, 2, 3}},
+}})
+```
+
+字段必须在 db_meta schema 中标记 `searchable`，系统字段 `id/userid/created_at/updated_at` 可直接检索和排序。`status` 若作为业务字段检索，仍需在 schema 中显式声明。
+
+---
+
 ## 关联关系（ref）
 
 关系只在需要时读取 `references/db-relations.md`。核心不变量：`many-to-one` 与 `many-to-many` 在真实持有引用 ID 的字段上配置 `ref` 和 `onDelete`；`one-to-many` 是用于 `populate` 的虚拟反向关系。级联继承当前用户权限并在同一事务中执行，不要在前端用多次 DELETE 模拟。
-
----
-
-## CRUD 操作范式
-
-```javascript
-// 查询（分页 + 结构化检索）
-const res = await App.get(`db/order`, {
-  page: 1, page_size: 20,
-  filters: ['name:like:张', 'status:eq:paid', 'amount:gte:100'],
-  order_by: 'amount', order: 'desc',
-});
-const { items, total } = res.data;
-
-// 非后台管理页面读取业务列表时，如果当前用户含 admin 角色，带 scope=mine
-// 这只影响 GET /api/db/{type} 列表，让管理员业务视角只看自己的 owner 数据
-const ownOrders = await App.get(`db/order`, {
-  page: 1,
-  page_size: 20,
-  scope: 'mine',
-});
-
-// 系统字段检索和排序（无需在 schema 中定义）
-const res = await App.get(`db/order`, {
-  filters: ['created_at:gte:2024-01-01', 'userid:eq:123'],
-  order_by: 'created_at', order: 'desc',
-});
-
-// 创建（业务字段必须放在 data 包裹里）
-await App.post(`db/order`, { data: { name: '张三', amount: 200 }, status: 1 });
-
-// 更新
-await App.put(`db/order/${id}`, { data: { amount: 250 } });
-
-// 删除
-await App.delete(`db/order/${id}`);
-
-// 批量更新（原子事务，任一失败全批回滚）
-await App.patch(`db/order/batch`, [
-  { id: 1, data: { status: 'paid' } },
-  { id: 2, data: { status: 'paid' } },
-]);
-```
-
----
-
-## filters 操作符
-
-| 操作符 | 含义 | 适用 searchable 模式 |
-|---|---|---|
-| `eq` | 精确等于 | exact / fuzzy / range |
-| `like` | 模糊包含 | fuzzy |
-| `gte` / `lte` / `gt` / `lt` | 数值/时间范围 | range |
-| `in` | 枚举命中（值逗号分隔：`status:in:paid,pending`） | exact / fuzzy / range |
-| `contains` | 数组字段包含某值 | contains |
-
-- 省略操作符（`filters: ['name:张三']`）默认 `like`
-- 多个 filters 为 AND
-- 字段未标 searchable 或操作符不匹配 → 后端返回 400
-- **系统字段**（`id` / `userid` / `created_at` / `updated_at`）无需在 schema 中声明，可直接使用
-- `scope=mine` 只对拥有 admin 角色的用户在 `GET /api/db/{type}` 列表请求中生效；非后台管理页面若当前用户是管理员，读取动态 DB 业务列表时应带该参数；后台管理页不要带，详情和写操作也不要带
-
----
-
-## db_meta 实时契约
-
+
+---
+
+## CRUD 操作范式
+
+```javascript
+// 查询（分页 + 结构化检索）
+const res = await App.get(`db/order`, {
+  page: 1, page_size: 20,
+  filters: ['name:like:张', 'status:eq:paid', 'amount:gte:100'],
+  order_by: 'amount', order: 'desc',
+});
+const { items, total } = res.data;
+
+// 非后台管理页面读取业务列表时，如果当前用户含 admin 角色，带 scope=mine
+// 这只影响 GET /api/db/{type} 列表，让管理员业务视角只看自己的 owner 数据
+const ownOrders = await App.get(`db/order`, {
+  page: 1,
+  page_size: 20,
+  scope: 'mine',
+});
+
+// 系统字段检索和排序（无需在 schema 中定义）
+const res = await App.get(`db/order`, {
+  filters: ['created_at:gte:2024-01-01', 'userid:eq:123'],
+  order_by: 'created_at', order: 'desc',
+});
+
+// 创建（业务字段必须放在 data 包裹里）
+await App.post(`db/order`, { data: { name: '张三', amount: 200 }, status: 1 });
+
+// 更新
+await App.put(`db/order/${id}`, { data: { amount: 250 } });
+
+// 删除
+await App.delete(`db/order/${id}`);
+
+// 批量更新（原子事务，任一失败全批回滚）
+await App.patch(`db/order/batch`, [
+  { id: 1, data: { status: 'paid' } },
+  { id: 2, data: { status: 'paid' } },
+]);
+```
+
+---
+
+## filters 操作符
+
+| 操作符 | 含义 | 适用 searchable 模式 |
+|---|---|---|
+| `eq` | 精确等于 | exact / fuzzy / range |
+| `like` | 模糊包含 | fuzzy |
+| `gte` / `lte` / `gt` / `lt` | 数值/时间范围 | range |
+| `in` | 枚举命中（值逗号分隔：`status:in:paid,pending`） | exact / fuzzy / range |
+| `contains` | 数组字段包含某值 | contains |
+
+- 省略操作符（`filters: ['name:张三']`）默认 `like`
+- 多个 filters 为 AND
+- 字段未标 searchable 或操作符不匹配 → 后端返回 400
+- **系统字段**（`id` / `userid` / `created_at` / `updated_at`）无需在 schema 中声明，可直接使用
+- `scope=mine` 只对拥有 admin 角色的用户在 `GET /api/db/{type}` 列表请求中生效；非后台管理页面若当前用户是管理员，读取动态 DB 业务列表时应带该参数；后台管理页不要带，详情和写操作也不要带
+
+---
+
+## db_meta 实时契约
+
 db_meta 是结构化远端资源，不 checkout，也不生成本地索引。未知 operation 才通过 MCP
 `draftgo_api_search` 定位；首次使用或 registry revision 变化时 `draftgo_api_describe`，再用
 `draftgo_api_call` 查询目标 type 和 schema。
-典型返回条目如下：
-
-```json
-[
-  {
-    "id": 1,
-    "type": "order",
-    "label": "订单",
-    "schema": { ... }
-  }
-]
-```
-
-⚠️ **GET `/api/db-meta/{type}` 用 type（如 `order`），不是 id。PUT/DELETE 才用 id。**
-
----
-
-## 通用筛选参数（非动态 DB）
-
-用于 users / roles / pages / navigations / feedback 等标准资源：
-
-| 参数 | 说明 |
-|---|---|
-| `page` / `page_size` | 分页（不传返回全量且无上限；任一传入则分页，缺失项按 `page=1` / `page_size=20` 兜底） |
-| `search` | 全文搜索（动态 DB 不用此参数） |
-| `status` | 状态过滤 |
-| `type` / `tag` | 类型/标签过滤 |
+典型返回条目如下：
+
+```json
+[
+  {
+    "id": 1,
+    "type": "order",
+    "label": "订单",
+    "schema": { ... }
+  }
+]
+```
+
+⚠️ **GET `/api/db-meta/{type}` 用 type（如 `order`），不是 id。PUT/DELETE 才用 id。**
+
+---
+
+## 通用筛选参数（非动态 DB）
+
+用于 users / roles / pages / navigations / feedback 等标准资源：
+
+| 参数 | 说明 |
+|---|---|
+| `page` / `page_size` | 分页（不传返回全量且无上限；任一传入则分页，缺失项按 `page=1` / `page_size=20` 兜底） |
+| `search` | 全文搜索（动态 DB 不用此参数） |
+| `status` | 状态过滤 |
+| `type` / `tag` | 类型/标签过滤 |