draftgo-cli 3.0.56 → 4.0.1

package/resources/skill/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: draftgo
-description: Use this skill to inspect, develop, debug, or deliver a DraftGo application. Read task-specific references before using live MCP discovery, use checkout/commit for complete page, navigation, document, and custom-service bodies, and write the changelog only after all verification and delivery succeed.
+description: Use this skill to inspect, develop, debug, or deliver a DraftGo application. Read task-specific references before live MCP discovery, use checkout/commit for complete page, navigation, document, and custom-service bodies, and track work in the project worklog.
 ---
 
 ## Workflow 2.0 authority
 
 - Treat pages, navigations, docs/articles, and custom services as checkout resources. Never save complete MCP responses, duplicate source snapshots, temporary Go modules, SDK stubs, executables, or build directories by hand.
 - The root Skill loads automatically. Before acting, read the smallest relevant Reference set from the task-routing table, then use MCP only for live project evidence.
-- Custom-service flow: read `references/custom-services.md` -> locate the service through MCP -> `checkout custom-services` -> edit four files -> `commit` cloud draft -> `test` in the server Runner -> `check --remote` -> `publish` -> `refresh`. CLI and admin UI edit the same cloud draft.
-- Do not create Task overhead for a small, single-point change. For cross-module, cross-session, or multi-Agent work, create or resume `.draftgo/Task/[YYYY-MM-DD]<slug>/Task.md`. It is the only task state: preserve both the user's original request and the clarified executable requirement, assign one owner per item/resource, and check an item only with verification evidence. Changelog remains the final delivery record, not a task tracker.
-- Normal delivery uses `draftgo verify`; add `--remote` only when remote comparison is required and `--url` only for browser evidence. UI verification is iframe-aware and defaults to one viewport with no screenshot. Only explicit visual acceptance or regression diagnosis may pass `--viewport both` or `--screenshot on-failure|always`.
+- Custom-service flow: read `references/custom-services.md`, locate and checkout the service, edit four files, then commit and validate the cloud draft. Run a server test or publish only when the task requires it. CLI and admin UI edit the same cloud draft.
+- At task start, run `draftgo work start "<item>"`. Add independent items with `draftgo work add`; mark them active with `start-item` and complete only after verification and delivery. `.draftgo/worklog.md` is the only task and completion record.
+- Normal delivery runs `draftgo verify` once; it already includes the local checks. Never start browser verification or create screenshots unless the user explicitly requests visual acceptance. For explicit visual acceptance, capture and inspect a desktop screenshot first with `--url <url> --screenshot always`; use `--ui always` only when the user also requests interaction or DOM verification, and add mobile/multi-viewport checks only when requested.
 - `.draftgo/tmp/` is entirely disposable. CLI data uses `.draftgo/tmp/<command>/<run-id>/`; AI-created scratch files use `.draftgo/tmp/ai/<run-id>/`. User-facing evidence belongs under registered `.draftgo/artifacts/`. Use `draftgo clean --dry-run` before `draftgo clean --yes`.
 
 # DraftGo 开发助手
@@ -17,9 +17,9 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 ## 核心边界
 
 - 本地 Skill / Reference 提供产品约束、运行机制和实践；MCP 提供当前项目、资源、API、权限与 schema。
-- pages、navigations、docs/articles 的完整正文只通过 `draftgo checkout`、本地 worktree 和 `draftgo commit` 处理，不放进 MCP 参数、结果、日志或聊天上下文。
+- pages、navigations、docs/articles、custom_services 的完整正文只通过 `draftgo checkout`、本地 worktree 和 `draftgo commit` 处理，不放进 MCP 参数、结果、日志或聊天上下文。
 - db_meta、AIHub、system_config、roles、users、doc_categories 和自定义服务元数据直接通过 MCP 读写，不建立本地索引。
-- 根 Skill 会在触发时自动加载。Agent 必须先按任务读取最少必要的 Reference，再通过 MCP 获取实时项目证据；MCP 不可用时报告连接、协议或 SAT 问题，不回退到旧索引或 `pull --all`。
+- 根 Skill 会在触发时自动加载。Agent 必须先按任务读取最少必要的 Reference，再通过 MCP 获取实时项目证据；MCP 不可用时报告连接、协议或 SAT 问题。
 - CLI 不提供页面模板，不预设页面骨架、视觉风格、原生技术或组件库选择。Agent 根据任务、受众、现有产品语言和可用资源自主设计。
 - 本地 Docker、MySQL、Redis、Milvus 与 `draftgo local ...` 独立于 MCP 工作流，必须保留。
 
@@ -44,9 +44,8 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 ## 所有权与执行
 
 - 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；其他 Agent 只读分析并回传建议。
-- 先确定共享 schema、接口、权限和 route，再并行处理无依赖且 owner 不冲突的工作单元。
-- 单页面、强依赖或仍共享主要资源的任务不强行并行。
-- 主 Agent 负责 Reference/MCP 路由、owner 分配、汇总回读、统一验证、交付和完成日志；子 Agent 不单独写 changelog。
+- 不同资源、operation 和 owner 不冲突的工作单元并发执行，不设置客户端并发上限；同一资源的依赖步骤保持串行。
+- 主 Agent 负责 Reference/MCP 路由、owner 分配、汇总回读、统一验证、交付和 worklog 状态。
 - 冲突 owner、接口依赖或验证失败会阻塞依赖项，不影响无关分支继续汇总。
 
 ## 开发与交付
@@ -55,25 +54,26 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 
 1. 确认目标 pages/nav/docs 已存在并通过 MCP 读取 metadata；新增资源先按实时 API 契约创建并取得 ID。
 2. 对需要完整分析或编辑的目标批量 checkout；在 `.draftgo/worktree/` 按唯一 owner 编辑。
-3. 主 Agent 回读全部修改，编辑过程中统一运行一次快速 `draftgo check`。交付前运行 `draftgo verify <type> <id...>`；需要远端证据时加 `--remote`，页面布局或交互变化时加对应 `--url`。
-4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。commit 后需要验证远端页面时运行 `draftgo verify <type> <id> --remote --url <url>`。
+3. 主 Agent 回读全部修改，并按顶部统一验证策略完成交付前验收。
+4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。
 5. 409/412 时停止自动提交，保留 base/local/remote 冲突材料；不得 force、覆盖或自动合并。
 
 完整 manifest、流式传输、哈希和冲突规则见 `references/checkout.md`。
 
 ### 结构化资源
 
-严格按 `references/mcp.md` 的 `draftgo_api_search` → `draftgo_api_describe` → `draftgo_api_call` 流程执行。describe 不完整就停止，不猜参数、响应、权限或风险。按唯一资源 owner 写入，回读结果并验证副作用；结构化资源不 checkout。
+遵循 `references/mcp.md` 的契约缓存：operation 未知才 search，首次使用或 revision 变化时 describe，其他情况复用缓存并直接 call。describe 不完整就停止，不猜参数、响应、权限或风险。独立资源并发读写，回读结果并验证副作用；结构化资源不 checkout。
 
-### 完成日志
+### 工作记录
 
-只有整个任务的检查、UI/API 验证和所有 commit/MCP 写入都成功后，主 Agent 执行一次：
+任务开始即写入开发中状态；独立事项可先以待开发状态加入：
 
 ```bash
-draftgo changelog add "<完成结果>"
+draftgo work start "<事项>"
+draftgo work add "<独立事项>"
 ```
 
-任何验证失败、409/412 或交付失败都不得写 changelog。日志只写完成结果，不写排查过程。
+开始处理待开发项时运行 `draftgo work start-item <编号>`。只有 `draftgo verify` 和所有 commit/MCP 写入成功后，才运行 `draftgo work complete <编号> --note "<结果或证据>"`。用户明确要求视觉验收时还需完成对应截图或浏览器校验。任何验证失败、409/412 或交付失败都不得标记为完成。
 
 ## 安全规则
 
@@ -82,25 +82,26 @@ draftgo changelog add "<完成结果>"
 - 页面通过 `window.parent.App` 使用认证、权限、反馈和主题；登出调用 `await App.logout()`，路由参数读取运行时注入对象。详细规则见 `frontend.md`、`runtime.md` 与 `app-api.md`。
 - 自定义服务普通 SDK 继承调用者权限；仅显式 `draftgo.Admin.*` 提升单次调用并进入审计。Route 权限、脚本管理权限、定时/事件身份和出站限制见 `custom-services.md`。
 - 高风险 MCP operation 仅在用户意图明确且影响范围已核对时设置 `confirm=true`。不要传 SAT、Authorization、tenant override 或自行实现旧式二次认证。
-- 旧 `.draftgo` 缓存不是事实来源；不自动删除。不要隐式 force、自动重试覆盖或自动合并冲突。
+- 不要隐式 force、自动重试覆盖或自动合并冲突。
 
 ## 验证证据
 
 | 范围 | 最低证据 |
 |---|---|
 | MCP 连接 | 失败时用 `draftgo mcp test` 核对 initialize、tools/list 和关键工具；输出不含 SAT |
-| 页面、导航、文档 | checkout manifest、`draftgo check`、交付前 `draftgo verify`、diff、commit 返回版本与哈希 |
-| 结构化资源 | search/describe 契约、call 结果与回读的权限、字段、错误和副作用 |
-| 自定义服务 | 动态 Route describe、无副作用健康请求或目标行为结果，以及管理员调用审计 |
-| 冲突 | `.draftgo/conflicts/` 的 base/local/remote；解决后重新 check、必要的 verify 和 commit |
+| 页面、导航、文档 | checkout manifest、交付前 `draftgo verify`、diff、commit 返回版本与哈希 |
+| 结构化资源 | 缓存或最新 describe 契约、call 结果与必要回读 |
+| 自定义服务 | commit revision、validate 结果；任务涉及运行或发布时再提供 test/publish 结果 |
+| 冲突 | `.draftgo/conflicts/` 的 base/local/remote；解决后重新 `draftgo verify`、diff 和 commit |
 | 本地底座 | `draftgo local status`、日志和相关 local 测试 |
 
-`draftgo deploy`、`auto-push` 和兼容 `push pages|nav|docs` 只能沿用当前 check/commit 语义，不能恢复旧的全量 push。主 Agent 最终明确区分 Skill 约束、MCP 实时状态和 checkout 正文证据。
+`draftgo deploy` 和 `auto-push` 只能沿用当前 check/commit 语义。主 Agent 最终明确区分 Skill 约束、MCP 实时状态和 checkout 正文证据。
 
 ## 本地工作区
 
 - `.draftgo/config.json`：server、SAT 与 CLI 设置，必须 gitignore。
+- `.draftgo/api-contract-cache.json`：按 registry revision 缓存的私有 operation schema，必须 gitignore。
 - `.draftgo/worktree/`、`.base/`、`manifest.json`：checkout 正文及基线，必须 gitignore。
 - `.draftgo/conflicts/`：409/412 材料，必须 gitignore。
-- `.draftgo/story.yaml`、`Task/`、`lessons/`：项目决策、任务和经验。
-- `.draftgo/changelog.md`：仅在整个任务验证和交付成功后写入。
+- `.draftgo/story.yaml`、`lessons/`：项目决策和经验。
+- `.draftgo/worklog.md`：待开发、开发中和已完成事项及备注。

package/resources/skill/init/SKILL.md

@@ -17,30 +17,25 @@ description: Install or refresh the DraftGo skill, connect a project to a DraftG
    - 已有 DraftGo 服务器：运行 draftgo connect。
    - 需要本地 Docker 基座：运行 draftgo local setup。
 6. 连接后运行 draftgo mcp setup（或指定目标），再运行 draftgo mcp test 验证 initialize、tools/list 和关键工具。
-7. 根 Skill 自动加载后，按实际任务读取最少必要的 Reference，并通过 MCP project_overview、resource_search 或 api_search 获取实时信息；需要叠加本地 checkout 状态时运行 `draftgo map`。MCP 不可用时报告原因，不回退到 pull --all。
+7. 根 Skill 自动加载后，按实际任务读取最少必要的 Reference，并通过 MCP project_overview、resource_search 或 api_search 获取实时信息；需要叠加本地 checkout 状态时运行 `draftgo map`。MCP 不可用时报告原因。
 
 draftgo init 只负责 Skill 安装；draftgo connect 负责保存并验证 server/SAT；draftgo mcp setup 负责宿主配置。不要混用职责。
 
-初始化后 `.draftgo/` 只保留已经写入的 `config.json`。不要预建 Task、lessons、changelog、worktree、conflicts 或其他占位文件和目录；首次实际使用对应能力时再创建。
+初始化后 `.draftgo/` 只保留已经写入的 `config.json`。不要预建 worklog、lessons、worktree、conflicts 或其他占位文件和目录；首次实际使用对应能力时再创建。
 
 ## SAT 与配置
 
 - 交互式连接应使用隐藏输入；不要把 SAT 写入宿主配置、Skill 文件、命令行示例或日志。
 - .draftgo/config.json、checkout manifest、base 和冲突目录必须加入项目 .gitignore。
 - bridge 从当前项目配置读取 SAT；宿主配置只引用 draftgo mcp serve。
-- 旧 .draftgo 缓存不自动删除。把它当作 legacy 数据，提示用户使用 MCP 或 checkout 重新建立上下文。
 
 ## 后续动作
 
 - 宿主配置和诊断：draftgo mcp setup/status/test，详见 ../references/mcp.md。
 - 开发准备：根 Skill 自动加载；按任务路由读取最少必要的 Reference，再按需直接调用 MCP。
 - 远端资源补充定位：MCP project_overview、resource_search、resource_list。
-- 正文编辑：自主设计并批量 checkout，不同资源按唯一 owner 并行修改，由主 Agent 统一运行 check、交付前 verify、diff 和 commit。
+- 正文编辑：遵循根 Skill 的 checkout/commit 与统一验证策略。
 - 结构化资源：直接使用 MCP 的 api_search、api_describe、api_call；不 checkout、不生成本地镜像。
-- 完成日志：只有整个任务统一验证且全部 commit/MCP 交付成功后，由主 Agent 执行一次 `draftgo changelog add "<完成结果>"`；验证、冲突或交付失败时不得写入。
-- 管理本地基座：draftgo local start|stop|logs|status；local-dev、local up/down 仍可用。
+- 工作记录：开发开始时运行 `draftgo work start "<事项>"`；只有统一验证且全部 commit/MCP 交付成功后运行 `draftgo work complete <编号> --note "<结果>"`。验证、冲突或交付失败时不得标记为完成。
+- 管理本地基座：draftgo local setup|start|stop|logs|status。
 - 移除指定目标：draftgo uninstall <target>；完整移除所有目标只在用户明确要求时运行 draftgo uninstall all，--purge 会删除 .draftgo/。
-
-## 迁移旧命令
-
-draftgo pull 不再执行同步。它只能给出迁移提示并返回非零，指导使用 MCP 定位资源或 checkout 长正文。不要悄悄恢复全量下载。

package/resources/skill/manifest.json

@@ -2,14 +2,14 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.56",
+  "version": "4.0.1",
   "entry": "SKILL.md",
   "description": "以 Skill/reference 任务路由、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",
   "capabilities": [
     "draftgo-development",
     "reference-routing",
-    "completion-changelog",
+    "worklog-tracking",
     "custom-service-ai-sdk",
     "mcp-bridge",
     "content-checkout-commit",

package/resources/skill/references/aihub.md

@@ -5,7 +5,7 @@ read_when: 创建或调优 AI Agent 时 · 需要工具/子智能体/记忆/多
 # AIHub / Agent 资源
 
 AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先使用 MCP `draftgo_resource_search`/`draftgo_resource_list`
-定位资产，再用 `draftgo_api_search`、`draftgo_api_describe` 获取实时契约，最后通过 `draftgo_api_call` 读写。
+定位资产；未知 operation 才用 `draftgo_api_search`，首次使用或 registry revision 变化时 `draftgo_api_describe`，然后通过 `draftgo_api_call` 读写。
 更新 AIHub 资产时只发送实时契约允许的字段；常见字段包括
 `type, name, data, priority, version, tags, describe, permission, status`。供应商和模型使用各自的实时接口，
 不要经旧 AIHub 资产接口写入。任何输出、工作区文件或调用参数都不得保存 API Key 或 header 值；只可处理
@@ -29,7 +29,7 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 
 页面对话 UI 使用 `<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID">` 或 `DraftGoChat.create()`；
 旧代码/无 UI 文本调用可用 `DraftGoAI.chat(...)`，图片模式使用 `DraftGoAI.images(...)`。调用前都必须加载
-`/assets/draftgo-chat.js`，完整用法见 `references/chat-sdk.md`。后端 operation 与可调用 Agent 列表通过 MCP `draftgo_api_search` → `draftgo_api_describe` 实时确认。
+`/assets/draftgo-chat.js`，完整用法见 `references/chat-sdk.md`。后端 operation 与可调用 Agent 列表通过 MCP 实时确认；已知契约可复用项目缓存。
 
 ## `data.spec` 字段地图
 
@@ -86,7 +86,7 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 ## 观测
 
 每次调用都开一条 AI run，管理台 `/admin/ai-runs` 展示状态、tokens、延迟、`ttft_ms` 与 span 链路。
-运行记录接口通过 MCP `draftgo_api_search` / `draftgo_api_describe` 实时发现，不维护静态路径表。
+运行记录接口通过 MCP 实时发现，不维护静态路径表；已知 operation 复用 registry revision 未变化的契约缓存。
 
 Agent 对外响应（`/api/agents/{id}/chat`、图片接口、Go/Script SDK Agent 调用）不返回内部 `model`、`fallback_models` 或 `upstream_model`；错误也不暴露内部模型名、供应商名称、服务地址或运行时实现名。只有显式启用 `model_selection.user_selectable` 后，`/selectable-models` 才作为授权的模型选择目录返回可选逻辑模型名。运行日志仍在服务端保留真实模型、供应商与链路信息用于定位。
 

package/resources/skill/references/checkout.md

@@ -95,14 +95,14 @@ base 已变化时必须拒绝覆盖。
 ## Commit 流程
 
 1. 读取 manifest 指向的 worktree 文件，计算当前字节数和 SHA-256；未变化时返回 `unchanged`。
-2. 按 content_type 执行本地结构和内联脚本检查；页面布局或交互有变化时运行 `draftgo verify <type> <id> --url <url>`。
+2. 按 content_type 执行本地结构和内联脚本检查。
 3. 通过专用 HTTP 流式上传原始文件，携带 `If-Match`、base version/revision、content_type、长度和 SHA-256。
 4. 完整正文不得作为 MCP tool 参数发送。
 5. 底座确认 hash 和新版本后，CLI 原子更新 `.base` 与 manifest。返回 hash 不一致时不得推进基线。
 
-推荐编辑顺序：主 Agent 按任务读取相关 Reference -> MCP 精确定位 -> Agent 自主设计并批量 checkout -> 独立资源按唯一 owner 并行编辑 -> 主 Agent 汇总回读 -> 统一运行一次 `draftgo check` -> `draftgo diff` -> commit -> 页面变化时用 `draftgo verify <type> <id> --remote --url <url>` 验证远端已提交版本。遇到本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
+本地正文已经等于远端、但 base/manifest 落后时，先用 `draftgo check --remote` 确认 `committed_unrecorded`，再运行 `draftgo reconcile`；不要手改 manifest。
 
-单个 commit 成功不自动写 changelog。只有整个任务统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行一次 `draftgo changelog add "<完成结果>"`。任何检查失败、409/412 或交付失败都不得写入。
+单个 commit 成功不自动完成 worklog 项。只有整个事项统一验证且全部 commit/MCP 交付成功后，主 Agent 才执行 `draftgo work complete <编号> --note "<完成结果>"`。任何检查失败、409/412 或交付失败都不得标记为完成。
 
 ## 409 / 412 冲突
 
@@ -119,7 +119,7 @@ base 已变化时必须拒绝覆盖。
 - `base` 是 checkout 时的内容；`local` 是发生冲突时的本地快照；`remote` 是重新下载并校验的当前远端内容。
 - `conflict.json` 记录三份路径、版本、ETag 和哈希，不嵌入完整正文。
 - Agent 或用户在 worktree local 文件中完成合并；不要手写 HTML 自动合并器，也不要改动保存的三份证据。
-- 合并完成后运行 `draftgo check`、必要时 `draftgo verify`，再执行 `draftgo conflict resolve <type> <id>`。
+- 合并完成后运行 `draftgo verify`，再执行 `draftgo conflict resolve <type> <id>`。
 - resolve 校验 worktree 与 remote，采用 remote 版本作为新的 base，但保留合并后的 worktree；随后运行
   `draftgo diff` 并 `draftgo commit`。
 

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

@@ -1,19 +1,26 @@
 ---
-
 read_when: 编写、修改、调试或评审自定义服务时；使用服务 SDK、路由、事件、定时任务或服务依赖时
 ---
 
 # Go 自定义服务契约
 
-DraftGo 的新自定义服务使用 Go。服务代码是完整的 `package main`，可以使用标准库和 `go.mod` 中声明的第三方库。平台在保存或发布时编译服务、运行 `Register` 并保存触发器清单；执行时在独立子进程中调用选定 handler。
+自定义服务是完整的 Go `package main`。平台构建源码和 `go.mod`/`go.sum`，执行 `Register` 保存触发器清单，并在独立子进程中运行 handler。SDK 固定导入 `draftgo/sdk`；它由构建器注入，不写进 `require` 或 `replace`。
+
+## 开发流程
+
+完整正文使用：
 
-平台 SDK 的固定导入路径是 `draftgo/sdk`。它是 DraftGo 构建器注入的本地 module，不从 GitHub 或其他网络仓库下载，也不要在服务的 `go.mod` 中自行添加或 `replace` 此依赖。
+```bash
+draftgo checkout custom-services <id...>
+draftgo commit custom-services <id...>
+draftgo validate custom-services <id>
+draftgo test custom-services <id> [--handler route:POST:/path]
+draftgo publish custom-services <id...>
+```
 
-## 索引
+checkout 目录包含 `service.go`、`go.mod`、`go.sum`、`service.json` 及对应 base。commit 只保存共享 cloud draft；publish 才切换线上版本。定位、创建、权限和结构化元数据通过 MCP 实时 operation 完成，创建后取得 ID 再 checkout。
 
-- [最小服务](#最小服务)、[本地资源](#本地资源)、[触发器](#触发器)
-- [平台 SDK](#平台-sdk)、[AI 平台 SDK](#ai-平台-sdk)
-- [权限与运行限制](#权限与运行限制)、[实时 API](#实时-api)、[验收清单](#验收清单)
+不同服务可并发处理；同一服务保持 commit -> validate -> test/publish 顺序。草稿 revision 是内容版本，`validated_revision` / `validated_hash` 是该版本的验证凭证。保存会清空凭证；测试和发布必须使用当前 revision。CLI 会复用有效凭证，不重复 commit、checkout 或 validate。
 
 ## 最小服务
 
@@ -23,277 +30,107 @@ package main
 import "draftgo/sdk"
 
 func Register(app *sdk.App) {
-	app.Route("GET", "/health", health)
-	app.On("order.paid", afterPaid)
-	app.Schedule("0 9 * * 1-5", weekdayReport)
+    app.Route("GET", "/health", health)
+    app.On("order.paid", afterPaid)
+    app.Schedule("0 9 * * 1-5", weekdayReport)
 }
 
 func health(draftgo *sdk.Context) (any, error) {
-	return draftgo.Respond(map[string]any{"ok": true}, 200, nil), nil
-}
-
-func afterPaid(draftgo *sdk.Context) (any, error) {
-	draftgo.Log.Info("order paid event received")
-	return nil, nil
+    return draftgo.Respond(map[string]any{"ok": true}, 200, nil), nil
 }
 
+func afterPaid(draftgo *sdk.Context) (any, error) { return nil, nil }
 func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
 ```
 
-`Register` 必须没有业务副作用。它只注册 handler；网络请求、写数据库、发通知等操作放在 handler 内。
-
-## 资源读写
-
-自定义服务是结构化远端资源，不使用 checkout/commit，也没有约定的本地镜像目录。先用
-`draftgo_resource_search` 定位服务，再用 `draftgo_api_search` / `draftgo_api_describe` 获取当前管理接口契约，
-通过 `draftgo_api_call` 读取、创建或更新。Agent 可以在普通工作区文件中编写和检查 Go 源码，但不得把该文件
-误当作远端事实来源；写入时按实时契约显式发送代码和元数据。
-
-常见服务载荷字段如下，实际字段以 `draftgo_api_describe` 为准：
-
-```json
-{
-  "name": "order-service",
-  "slug": "order-service",
-	"mode": "mixed",
-  "code": "package main\n\n// ...\n",
-  "go_mod": "module example.com/order-service\n\ngo 1.26.0\n\nrequire github.com/google/uuid v1.6.0\n",
-  "go_sum": ""
-}
-```
-
-- 新服务使用 `mode=mixed`，允许同一个 `Register` 同时注册 route、event 和 scheduled。旧服务可继续使用单一 `route`、`event` 或 `scheduled` mode。
-- `go_mod` 和可选的 `go_sum` 随服务版本保存，并和代码一起通过实时管理 API 提交。
-- 新依赖应锁定明确版本。构建错误会在保存/发布时返回，不会替换当前有效清单。
+`Register` 只注册 handler，不访问网络、数据库或通知系统。新服务使用 `mode=mixed`；第三方依赖锁定明确版本并写入 `go.mod`，可选校验和写入 `go.sum`。
 
 ## 触发器
 
 ### Route
 
-```go
-func Register(app *sdk.App) {
-	app.Route("POST", "/orders", createOrder)
-}
-
-func createOrder(draftgo *sdk.Context) (any, error) {
-	body, _ := draftgo.Input["body"].(map[string]any)
-	return draftgo.Respond(body, 201, nil), nil
-}
-```
-
-`slug=commerce` 时地址为 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
+`app.Route("POST", "/orders", createOrder)` 在 `slug=commerce` 时对应 `POST /api/x/commerce/orders`。Route 精确匹配，不支持 `/orders/{id}` 模板；ID 使用 query 或 body。
 
-`draftgo.Input` 的 Route 字段：`method`、`headers`、`body`、`query_params`、`path_params`。当前身份通过 `draftgo.Auth.CurrentUser()` 获取，入站请求头通过 `draftgo.Headers.Get("Authorization")` 等读取。
+输入字段为 `method`、`headers`、`body`、`query_params`、`path_params`。身份由 `draftgo.Auth.CurrentUser()` 获取。普通 `draftgo.DB`、`Users` 等调用继承请求调用者权限；管理员创建服务、持有 SAT 或 `RequireAdmin` 都不会自动提升 SDK 调用。
 
-Route 默认以请求调用者身份访问 `draftgo.DB`、`draftgo.Users` 和其他平台能力。服务由管理员创建、拥有 `scripts:*` 管理权限，或在请求中收到 SAT，都不会让普通 SDK 调用自动提升；`draftgo.Auth.RequireAdmin()` 也只检查当前调用者。
-
-可信服务需要管理员权限时，逐次显式使用 `draftgo.Admin.*`。这不是服务配置项，也不需要 `admin_access` 开关：调用 `Admin` 就是管理员调用声明。运行时为**这一次**平台 SDK 调用注入管理员身份，并把服务、版本、真实调用者、操作、资源和结果写进该次执行的审计日志；SAT、数据库连接和管理员凭据不会暴露给服务代码。
-
-```go
-func catalog(draftgo *sdk.Context) (any, error) {
-	// 继承调用者权限
-	owned, err := draftgo.DB.Query("order", sdk.QueryOptions{})
-	if err != nil { return nil, err }
-
-	// 显式管理员权限；仅此调用提升
-	internal, err := draftgo.Admin.DB.Query("internal_catalog", sdk.QueryOptions{})
-	if err != nil { return nil, err }
-
-	return draftgo.Respond(map[string]any{
-		"orders": owned.Items,
-		"catalog": internal.Items, // 生产代码应再按客户端可见字段组装
-	}, 200, nil)
-}
-```
-
-`draftgo.Admin` 提供与普通 SDK 对齐的 `DB`、`Users`、`Auth`、`Notify`、`HTTP`、`Cache`、`Config`、`AIHub`、`Knowledge`、`Memory` 能力。它等价于管理员在平台拥有的权限，不做资源级白名单；因此只能授予可信服务编辑者，并且 Route 返回值仍必须由代码负责脱敏。
+可信服务需要管理员能力时逐次显式调用 `draftgo.Admin.*`。它只提升该次 RPC，并审计服务、版本、真实调用者、操作、资源和结果；服务代码拿不到 SAT、数据库连接或管理员凭据。Route 返回值仍需自行脱敏。
 
 ### Event
 
-```go
-app.On("user.registered", welcome)
-
-func welcome(draftgo *sdk.Context) (any, error) {
-	payload, _ := draftgo.Input["payload"].(map[string]any)
-	draftgo.Log.Info("registered user: " + fmt.Sprint(payload["user_id"]))
-	return nil, nil
-}
-```
-
-事件异步且不阻塞原请求。事件输入含 `event`、`timestamp`、`payload`。
-
-事件 `payload` 含 `user_id` 或 `actor_user_id` 且该用户仍存在时，handler 继承该用户身份；无法解析用户时才以系统身份执行。事件服务应把事件数据视为业务输入，而不是把它当成绕过资源权限的通道。
+`app.On("user.registered", welcome)` 异步执行，不阻塞原请求。输入含 `event`、`timestamp`、`payload`。payload 中可解析的 `user_id` / `actor_user_id` 会作为继承身份；无法解析时才使用系统身份。
 
 ### Scheduled
 
-```go
-app.Schedule("0 2 * * *", cleanup)
-```
-
-cron 使用五字段表达式，也支持 `interval:5m`。定时 handler 的 `draftgo.Input` 为空对象。
+`app.Schedule("0 2 * * *", cleanup)` 使用五字段 cron，也支持 `interval:5m`。定时任务没有调用者，以系统身份执行；仅可信编辑者可维护，并应限制写入范围、记录业务日志。
 
-定时任务没有调用者，会以系统身份执行。因此它只能由可信编辑者维护，写入范围应限制在明确的数据类型，并在 handler 中记录可审计的业务日志。
+## SDK
 
-## 平台 SDK
+所有平台访问通过受控 RPC 返回主服务，不自行读取宿主环境变量、数据库连接或 token。
 
-所有资源访问经受控 RPC 返回 Go 主服务。不要自行读取数据库连接、服务 token 或宿主机环境变量。
+| 入口 | 核心能力 |
+|---|---|
+| `draftgo.DB` | Create/CreateMany/Get/Update/UpdateMany/Delete/Query |
+| `draftgo.Users` | Get/List/Update |
+| `draftgo.Auth` | RequireLogin/RequireAdmin/RequireRole/CurrentUser |
+| `draftgo.Notify` | 站内通知 |
+| `draftgo.HTTP` | Get/Post/Put/Patch/Delete |
+| `draftgo.Cache` / `Config` | 缓存与系统配置 |
+| `draftgo.AIHub` | Agent/模型推理、图片、Embedding、AI 资产与运行记录 |
+| `draftgo.Knowledge` | 知识库、文档、Chunk、上传、检索和重建 |
+| `draftgo.Memory` | 长期记忆与全局检索配置 |
+
+常用示例：
 
 ```go
-record, err := draftgo.DB.Create("order", map[string]any{"title": "DraftGo"})
 records, err := draftgo.DB.Query("order", sdk.QueryOptions{
-	Filters: map[string]any{"status": "paid"},
-	Page: 1, PageSize: 20, OrderBy: "id", Order: "desc",
+    Filters: map[string]any{"status": "paid"}, Page: 1, PageSize: 20,
+})
+reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
+    AgentID: 12, Message: "总结订单",
 })
-
-user, err := draftgo.Users.Get(12)
-err = draftgo.Auth.RequireLogin()
-err = draftgo.Notify.Send(12, "完成", "订单已创建", "info")
-
-cached, err := draftgo.Cache.Get("daily-report")
-err = draftgo.Cache.Set("daily-report", map[string]any{"ok": true}, time.Hour)
-
-value, err := draftgo.Config.Get("feature_flag", false)
 response, err := draftgo.HTTP.Get(draftgo.Context(), "https://api.example.com/health", nil, 10*time.Second)
-
-reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{AgentID: 12, Message: "总结订单"})
-draftgo.Log.Info("service completed")
 ```
 
-`draftgo.DB` 支持 `Create`、`CreateMany`、`Get`、`Update`、`UpdateMany`、`Delete`、`Query`。`Query` 返回 `sdk.QueryResult{Items, Total, Page, PageSize}`。
+HTTP host 可由 `config.http_allowed_hosts` 限制；timeout 最终为 1-30 秒，响应体最大 5 MB。日志每次执行最多 500 条、单条 4096 字符，不记录 token、Cookie、密码或完整个人信息。
 
-`draftgo.Users` 支持 `Get`、`List`、`Update`。`draftgo.Auth` 支持 `RequireLogin`、`RequireAdmin`、`RequireRole`、`CurrentUser`。
+### AI 权限
 
-`draftgo.HTTP` 支持 `Get`、`Post`、`Put`、`Patch`、`Delete`；响应为 `sdk.HTTPResponse{StatusCode, Headers, Data}`。服务可使用 `config.http_allowed_hosts` 限制出站目标；HTTP timeout 最终限制为 1-30 秒，响应体最大 5 MB。
+普通 AIHub/Knowledge/Memory 继承用户身份并经过 `aihub:*` 等权限。`draftgo.Admin.AIHub`、`Admin.Knowledge`、`Admin.Memory` 与普通入口同构，但逐次以管理员执行并审计。
 
-## AI 平台 SDK
-
-| 入口 | 能力 |
-|---|---|
-| `draftgo.AIHub` | Agent/模型推理、图片、Embedding、Agent/Prompt/Skill/MCP 资产 CRUD、供应商、模型路由、Skill 安装与版本、运行记录 |
-| `draftgo.Knowledge` | 知识库、文档、Chunk CRUD，文档上传、检索、重建索引 |
-| `draftgo.Memory` | 长期记忆 CRUD 与全局检索配置 |
-
-普通入口继承调用用户身份，继续经过 `aihub:read/create/update/delete/execute/invoke` 等平台权限检查。`draftgo.Admin.AIHub`、`draftgo.Admin.Knowledge`、`draftgo.Admin.Memory` 提供同构接口，每次调用以管理员身份执行并进入自定义服务执行审计。
-
-### 推理与配置
-
-```go
-reply, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
-	AgentID: 12,
-	Message: "总结订单",
-	SessionID: "optional-conversation-id",
-	RunID: "optional-client-run-id",
-})
-
-direct, err := draftgo.AIHub.Chat(draftgo.Context(), sdk.AIChatRequest{
-	Model: "gpt-4.1-mini",
-	Messages: []map[string]any{{"role": "user", "content": "hello"}},
-})
-
-vectors, err := draftgo.AIHub.Embeddings(draftgo.Context(), sdk.AIEmbeddingRequest{
-	Model: "text-embedding-3-small",
-	Input: []string{"first document", "second document"},
-})
-```
-
-`GenerateImage` 支持 Agent 和直接模型两种调用。普通入口的推理必须在服务 `config.aihub` 中显式开启：
+普通推理还必须在服务配置中启用：
 
 ```json
 {
   "aihub": {
     "enabled": true,
-    "allowed_agents": [12, 18],
+    "allowed_agents": [12],
     "allow_direct_model_call": true,
-    "allowed_models": ["gpt-4.1-mini", "text-embedding-3-small"],
+    "allowed_models": ["gpt-4.1-mini"],
     "allow_images": true
   }
 }
 ```
 
-空白名单表示不额外限制，但用户权限、Agent 调用权限和模型外部调用策略仍然生效。Agent 预览与后续新增的 `/api/v1/*` 推理端点也使用同一组白名单策略。
-
-### AI 资产、Skill 与 MCP
-
-Agent、Prompt、Skill、MCP 使用统一资产 CRUD，通过 `type` 区分：
-
-```go
-skills, err := draftgo.AIHub.ListAssets(draftgo.Context(), map[string]any{
-	"type": "skill", "page": 1, "page_size": 50,
-})
-
-mcp, err := draftgo.AIHub.CreateAsset(draftgo.Context(), map[string]any{
-	"type": "mcp", "name": "internal-tools",
-	"data": map[string]any{"transport": "http", "url": "https://mcp.example.com"},
-	"status": 1,
-})
-
-tools, err := draftgo.AIHub.DiscoverMCPTools(draftgo.Context(), map[string]any{
-	"transport": "http", "url": "https://mcp.example.com",
-})
-```
-
-资产方法包括 `ListAssets/GetAsset/CreateAsset/UpdateAsset/UpdateAssets/DeleteAsset`、`AgentReadiness/PublishAgent`、`DiscoverMCPTools`、`InstallSkill/InstallSkillArchive/ListSkillVersions/RollbackSkill`。供应商使用 `ListProviders/GetProvider/CreateProvider/UpdateProvider/DeleteProvider/DiscoverProvider/SyncProvider`；模型和路由使用 `ListModels/GetModel/CreateModel/UpdateModel/DeleteModel/ProbeModel/UpdateModelRoute/DeleteModelRoute`；运行记录使用 `ListRuns/GetRun/DeleteRuns`。
-
-### 知识库与记忆
-
-```go
-base, err := draftgo.Knowledge.Create(draftgo.Context(), map[string]any{
-	"name": "产品手册", "embedding_model_id": 7,
-})
-
-document, err := draftgo.Knowledge.UploadDocument(draftgo.Context(), baseID,
-	sdk.KnowledgeDocumentUpload{
-		Filename: "manual.pdf", MIMEType: "application/pdf", Content: pdfBytes,
-		Metadata: map[string]any{"product": "DraftGo"},
-	})
-
-matches, err := draftgo.Knowledge.Retrieve(draftgo.Context(), baseID, map[string]any{
-	"query": "如何配置模型供应商？", "mode": "hybrid", "top_k": 6,
-})
-
-memory, err := draftgo.Memory.Create(draftgo.Context(), map[string]any{
-	"scope": "user_agent", "user_id": 42, "agent_id": 12,
-	"content": "用户偏好简洁的中文回答", "importance": 0.8,
-})
-```
-
-`Knowledge` 还提供知识库 `List/Get/Update/Delete`、文档 `ListDocuments/GetDocument/UpdateDocument/DeleteDocument/ReindexDocument`、Chunk `ListChunks/UpdateChunk` 以及 `RebuildIndex`。文档上传受 8 MiB 限制。`Memory` 提供 `List/Get/Create/Update/Delete`，全局配置使用 `draftgo.Memory.GetConfig` 和 `draftgo.Memory.UpdateConfig`。
-
-### 扩展入口
-
-typed helper 尚未覆盖新端点时，使用 `AIHub.Request`：
-
-```go
-value, err := draftgo.AIHub.Request(draftgo.Context(), sdk.AIRequest{
-	Method: "GET",
-	Path: "/api/aihub/types",
-})
-```
-
-`Request` 只接受 `/api/aihub`、`/api/agents`、`/api/v1`、`/api/images`、`/api/knowledge-bases`、`/api/memories`、`/api/skills` 路径；禁止外部 URL、路径穿越和在 `Path` 中拼 query。身份、权限、推理开关与审计规则和 typed helper 相同。
-
-日志每次执行最多 500 条、单条最多 4096 字符。不要记录 token、Cookie、密码或完整个人信息。
+空白名单表示不额外限制，不会绕过用户权限、Agent 调用权限或模型外部调用策略。typed helper 未覆盖的新端点可使用 `AIHub.Request`，但 path 只能位于平台允许的 AI/Knowledge/Memory 前缀，不能传外部 URL、路径穿越或内嵌 query。
 
-## 权限与运行限制
+## 权限与运行
 
-- `scripts:read/create/update/delete/execute` 控制可信人员管理服务。
-- Route 调用者仍由服务 `permission` 与 `config.route_security` 控制；管理权限不绕过 Route 调用权限。
-- Route 的普通 SDK 数据访问继承调用者权限；不要把“管理员创建服务”误写成自动提升。只有显式 `draftgo.Admin.*` 调用才以管理员执行并记录审计；定时任务和无可解析用户的事件是系统身份例外。
-- `config.timeout`、`max_concurrency`、`queue_timeout_ms` 适用于服务执行。Route 饱和时返回 HTTP 429。
-- Go 服务以独立进程运行，超时会终止该进程；它不是为不可信多租户代码准备的安全沙箱。只向可信编辑者授予服务编辑权限。
-- 每个保存版本按源码、依赖、SDK 和 Runner 协议生成不可变构建键。代码或依赖变更会生成新构建产物；旧版本可通过现有版本恢复接口重新激活。
+- `scripts:read/create/update/delete/execute` 控制服务管理。
+- Route 仍受服务 `permission` 与 `config.route_security` 控制。
+- 只有显式 `draftgo.Admin.*`、定时任务和无可解析用户的事件是提升身份例外。
+- `config.timeout`、`max_concurrency`、`queue_timeout_ms` 控制执行；Route 饱和返回 429。
+- 超时会终止独立子进程。运行器不是不可信多租户安全沙箱，只授予可信编辑者服务权限。
+- 构建键覆盖源码、依赖、SDK 和 Runner 协议；有效验证凭证绑定该键，任一部分变化都必须重新验证。
 
 ## 实时 API
 
-服务管理接口使用标准 `{code, data, message}` 信封并受 `scripts:*` 权限控制。具体 operation、参数、请求体、响应和风险必须通过 MCP `draftgo_api_search` → `draftgo_api_describe` 获取后再调用，不维护静态路径表。
+管理接口使用标准 `{code,data,message}` 信封。未知 operation 才 search，首次使用或 registry revision 变化时 describe；完整服务正文不进入 MCP 参数。
 
-有效 `app.Route` 会以实际 method、`/api/x/{slug}/{path}`、权限、风险和输入 schema 动态加入同一 MCP registry；搜索 `resource_type=custom_scripts` 或 `module=scripts_dynamic` 后描述并调用。运行时 Route 返回 handler 自定义响应，不强制使用管理 API 信封；精确匹配、调用身份和运行限制仍以本文件的 Route 与权限章节为准。
+有效 `app.Route` 会按实际 method 和 `/api/x/{slug}/{path}` 动态加入 MCP registry。运行时响应由 handler 决定，不强制管理 API 信封；精确匹配、身份继承和执行限制仍以本文件为准。
 
-## 验收清单
+## 完成条件
 
-- [ ] `package main` 且实现 `Register(app *sdk.App)`。
-- [ ] 服务使用 `mode=mixed`，第三方库写入 `go_mod`。
-- [ ] 路由使用 `app.Route`，事件使用 `app.On`，定时任务使用 `app.Schedule`。
-- [ ] handler 返回 `(any, error)`，需要状态码时使用 `draftgo.Respond`。
-- [ ] Route 显式设置 `permission` 与 `route_security`。
-- [ ] 保存或发布后请求无副作用 GET Route，并记录状态码和响应作为验收证据。
+- `package main` 且实现无业务副作用的 `Register(app *sdk.App)`。
+- trigger 与 handler 签名正确，第三方依赖已锁定。
+- Route 权限、管理员调用和返回脱敏符合真实调用者范围。
+- `draftgo validate` 通过；需要运行行为证据时执行相关 `draftgo test`。发布仅在用户任务包含发布时进行。

package/resources/skill/references/data.md

@@ -152,8 +152,9 @@ await App.patch(`db/order/batch`, [
 
 ## db_meta 实时契约
 
-db_meta 是结构化远端资源，不 checkout，也不生成本地 `index.json`。开发前先通过 MCP
-`draftgo_api_search` / `draftgo_api_describe` 确认接口，再用 `draftgo_api_call` 查询目标 type 和 schema。
+db_meta 是结构化远端资源，不 checkout，也不生成本地索引。未知 operation 才通过 MCP
+`draftgo_api_search` 定位；首次使用或 registry revision 变化时 `draftgo_api_describe`，再用
+`draftgo_api_call` 查询目标 type 和 schema。
 典型返回条目如下：
 
 ```json