draftgo-cli 4.0.1 → 4.0.23

package/resources/custom-service-sdk/sdk.go

@@ -0,0 +1,208 @@
+// Package sdk is the public contract for DraftGo Go custom services.
+//
+// A service implements Register and calls App.Route, App.On and App.Schedule.
+// The isolated script runner invokes Register once at publish time to discover
+// handlers, then invokes the selected Handler for each execution.
+package sdk
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+)
+
+// Handler is a user supplied custom-service function.
+type Handler func(*Context) (any, error)
+
+// Registration is an immutable description of one platform trigger.
+type Registration struct {
+	Kind    string  `json:"kind"`
+	Method  string  `json:"method,omitempty"`
+	Path    string  `json:"path,omitempty"`
+	Event   string  `json:"event,omitempty"`
+	Cron    string  `json:"cron,omitempty"`
+	Name    string  `json:"name,omitempty"`
+	Handler Handler `json:"-"`
+}
+
+// App is supplied to Register. It is safe to inspect registrations after
+// Register returns; registration itself is intentionally limited to startup.
+type App struct {
+	mu            sync.RWMutex
+	registrations []Registration
+}
+
+// NewApp creates the registration collector used by a script runner.
+func NewApp() *App { return &App{} }
+
+// Route registers an HTTP endpoint. Path is relative to the custom-service
+// mount point and must start with '/'.
+func (app *App) Route(method, path string, handler Handler) {
+	method, path = strings.ToUpper(strings.TrimSpace(method)), strings.TrimSpace(path)
+	if method == "" || path == "" || !strings.HasPrefix(path, "/") || handler == nil {
+		panic("sdk.Route requires method, absolute path and handler")
+	}
+	trimmed := strings.Trim(path, "/")
+	if trimmed == "" {
+		path = "/"
+	} else {
+		path = "/" + trimmed
+	}
+	app.add(Registration{Kind: "route", Method: method, Path: path, Handler: handler})
+}
+
+// On registers a named DraftGo event handler.
+func (app *App) On(event string, handler Handler) {
+	event = strings.TrimSpace(event)
+	if event == "" || handler == nil {
+		panic("sdk.On requires event and handler")
+	}
+	app.add(Registration{Kind: "event", Event: event, Handler: handler})
+}
+
+// Schedule registers a five-field cron expression or a DraftGo interval
+// expression (for example "interval:5m").
+func (app *App) Schedule(cron string, handler Handler) {
+	cron = strings.TrimSpace(cron)
+	if cron == "" || handler == nil {
+		panic("sdk.Schedule requires cron and handler")
+	}
+	app.add(Registration{Kind: "scheduled", Cron: cron, Handler: handler})
+}
+
+func (app *App) add(registration Registration) {
+	app.mu.Lock()
+	defer app.mu.Unlock()
+	for _, existing := range app.registrations {
+		if registration.Kind == "route" && existing.Kind == "route" && existing.Method == registration.Method && existing.Path == registration.Path {
+			panic(fmt.Sprintf("duplicate route %s %s", registration.Method, registration.Path))
+		}
+	}
+	// Function names are not a stable Go runtime API. A deterministic ID based
+	// on registration order is therefore persisted in the published manifest.
+	registration.Name = fmt.Sprintf("%s-%d", registration.Kind, len(app.registrations)+1)
+	app.registrations = append(app.registrations, registration)
+}
+
+// Registrations returns a copy, so callers cannot mutate the published
+// registration set.
+func (app *App) Registrations() []Registration {
+	app.mu.RLock()
+	defer app.mu.RUnlock()
+	result := make([]Registration, len(app.registrations))
+	copy(result, app.registrations)
+	return result
+}
+
+// Context is passed to a handler. Input and User are JSON-compatible values
+// supplied by DraftGo; platform resource methods will be added by the runner
+// RPC client rather than by exposing database handles to scripts.
+type Context struct {
+	Input       map[string]any `json:"input"`
+	User        map[string]any `json:"user,omitempty"`
+	Headers     http.Header    `json:"headers,omitempty"`
+	Platform    bool           `json:"platform"`
+	WorkspaceID int64          `json:"workspace_id,omitempty"`
+	SpaceID     int64          `json:"space_id,omitempty"`
+	Principal   ScopePrincipal `json:"principal"`
+
+	DB        Database   `json:"-"`
+	Users     Users      `json:"-"`
+	Auth      Auth       `json:"-"`
+	Notify    Notifier   `json:"-"`
+	HTTP      HTTPClient `json:"-"`
+	Cache     Cache      `json:"-"`
+	Config    Config     `json:"-"`
+	AIHub     AIHub      `json:"-"`
+	Knowledge Knowledge  `json:"-"`
+	Memory    Memory     `json:"-"`
+	Files     FileStore  `json:"-"`
+	Scope     ScopeAPI   `json:"-"`
+	Billing   BillingAPI `json:"-"`
+	// Admin groups explicitly elevated operations for trusted custom services.
+	// Elevation applies to one RPC call, is audited, and never exposes credentials.
+	Admin Admin   `json:"-"`
+	Log   *Logger `json:"-"`
+
+	context context.Context
+}
+
+// NewContext constructs the platform facade used by the isolated runner. The
+// client is intentionally a narrow RPC interface rather than a database or
+// HTTP-server handle.
+func NewContext(draftgo context.Context, input, user map[string]any, headers http.Header, client Client) *Context {
+	return NewContextWithResource(draftgo, input, user, headers, client, ResourceContext{}, ScopePrincipal{})
+}
+
+// NewContextWithResource constructs a handler context with persisted resource
+// ownership and the service principal supplied by DraftGo. Custom services
+// cannot override these values through Input or request headers.
+func NewContextWithResource(draftgo context.Context, input, user map[string]any, headers http.Header, client Client, resource ResourceContext, principal ScopePrincipal) *Context {
+	if draftgo == nil {
+		draftgo = context.Background()
+	}
+	if input == nil {
+		input = map[string]any{}
+	}
+	platform := platformClient{client: client, context: draftgo}
+	adminPlatform := platformClient{client: client, context: draftgo, admin: true}
+	return &Context{
+		Input: input, User: user, Headers: headers, context: draftgo,
+		Platform: resource.ScopeType == ScopePlatform, WorkspaceID: resource.WorkspaceID, SpaceID: resource.SpaceID, Principal: principal,
+		DB: dbClient{platform}, Users: usersClient{platform}, Auth: authClient{platformClient: platform, user: user}, Notify: notifierClient{platform},
+		HTTP: httpClient{platform}, Cache: cacheClient{platform}, Config: configClient{platform}, AIHub: aiHubClient{platform},
+		Knowledge: knowledgeClient{platform}, Memory: memoryClient{platform}, Files: fileStoreClient{platform}, Scope: scopeClient{platform}, Billing: billingClient{platform},
+		Admin: Admin{
+			DB: dbClient{adminPlatform}, Users: usersClient{adminPlatform}, Auth: authClient{platformClient: adminPlatform, user: user}, Notify: notifierClient{adminPlatform},
+			HTTP: httpClient{adminPlatform}, Cache: cacheClient{adminPlatform}, Config: configClient{adminPlatform}, AIHub: aiHubClient{adminPlatform},
+			Knowledge: knowledgeClient{adminPlatform}, Memory: memoryClient{adminPlatform},
+			Files: fileStoreClient{adminPlatform}, Scope: scopeClient{adminPlatform}, Billing: billingClient{adminPlatform},
+		},
+		Log: &Logger{},
+	}
+}
+
+// Admin exposes explicitly elevated platform capabilities to trusted custom
+// services. The runtime preserves the service subject, scopes elevation to one
+// audited RPC call, and never exposes platform credentials.
+type Admin struct {
+	DB        Database
+	Users     Users
+	Auth      Auth
+	Notify    Notifier
+	HTTP      HTTPClient
+	Cache     Cache
+	Config    Config
+	AIHub     AIHub
+	Knowledge Knowledge
+	Memory    Memory
+	Files     FileStore
+	Scope     ScopeAPI
+	Billing   BillingAPI
+}
+
+// Context returns the invocation deadline/cancellation context supplied by
+// DraftGo. Pass it to SDK calls that accept a context.Context.
+func (draftgo *Context) Context() context.Context {
+	if draftgo == nil || draftgo.context == nil {
+		return context.Background()
+	}
+	return draftgo.context
+}
+
+// Response allows handlers to explicitly control an HTTP response.
+type Response struct {
+	Body       any         `json:"body"`
+	StatusCode int         `json:"status_code"`
+	Headers    http.Header `json:"headers,omitempty"`
+}
+
+// Respond creates a response result. A status of zero defaults to 200.
+func (draftgo *Context) Respond(body any, status int, headers http.Header) Response {
+	if status == 0 {
+		status = http.StatusOK
+	}
+	return Response{Body: body, StatusCode: status, Headers: headers}
+}

package/resources/skill/SKILL.md

@@ -1,107 +1,55 @@
 ---
 name: draftgo
-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.
+description: Use this skill to inspect, develop, debug, or deliver a DraftGo application. Read only the task-specific references, locate long-content resources precisely, and use checkout/commit with a 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 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 开发助手
 
-## 核心边界
+## 开始前
 
-- 本地 Skill / Reference 提供产品约束、运行机制和实践；MCP 提供当前项目、资源、API、权限与 schema。
-- 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 问题。
-- CLI 不提供页面模板，不预设页面骨架、视觉风格、原生技术或组件库选择。Agent 根据任务、受众、现有产品语言和可用资源自主设计。
-- 本地 Docker、MySQL、Redis、Milvus 与 `draftgo local ...` 独立于 MCP 工作流，必须保留。
+- 任务开始即运行 `draftgo work start "<事项>"`；记录 CLI 返回的工作项引用。独立事项用 `draftgo work add`，仅在验证和交付成功后运行 `draftgo work complete <ref> --note "<证据>"`。
+- 根 Skill 会在触发时自动加载；先读取下表中最少必要的 Reference，再用 MCP 查询当前项目。不要预先读取所有 Reference，也不要把动态 operation schema 写入 Skill 或聊天上下文。
+- pages、navigations、docs/articles 与 custom services 的完整正文只能通过 `draftgo checkout`、worktree、`draftgo diff`、`draftgo verify` 和 `draftgo commit` 处理；MCP 只用于定位、元数据和结构化资源。不要把完整正文、响应快照、临时 Go 模块、SDK 副本或构建目录写入聊天上下文或手工归档。
+- 已知页面 route 或标题时，用 `draftgo map --type pages --route <path>` 或 `--title <title>` 精确定位；两个筛选条件取交集。只需范围或状态时加 `--summary`；需要浏览时使用 `--limit`（默认 20）和后续 `--cursor`，绝不默认全量枚举。
+- `--output json` 的 stdout 是单一 UTF-8 JSON；诊断和进度走 stderr。不要依赖终端截断来控制上下文。
+- 正常交付只运行 `draftgo verify`。默认跳过 UI；只有用户明确要求视觉验收时才使用截图，要求交互或 DOM 验证时才使用 `--ui always`。
 
-## 任务路由
+不要用 MCP 摘要代替完整正文，也不要把 Skill 中列出的 `/assets/` 能力声称为当前服务器全部文件。CLI 不提供页面模板；页面根据任务、受众、现有产品语言和可用资源设计。
 
-根 Skill 自动加载后，Agent 根据用户任务先读取下表中最少必要的 Reference，再用 MCP 查询当前项目。不要预先读取所有 Reference，也不要在目标明确时全量枚举无关资源：
+## 任务路由
 
-| 任务 | 专题资料与后续动作 |
+| 任务 | 先读 |
 |---|---|
-| 页面、导航、交互或 UI | `references/frontend.md`；涉及 iframe、路由、认证或全局层加读 `runtime.md` / `app-api.md`；先结合需求与 MCP 资源判断新增或修改，已有资源按需 checkout |
-| 动态 DB、筛选或关系 | `references/data.md`；需要关系完整示例时读 `db-relations.md`；API 调用遵循 `mcp.md` |
-| AIHub、聊天或图片 | `references/aihub.md`、`references/chat-sdk.md`；资产与 operation 以 MCP 为准 |
-| 自定义服务、权限、外部调用 | `references/custom-services.md`；管理和动态 Route operation 以 MCP 为准 |
-| MCP 配置、API 契约或故障 | `references/mcp.md`；配置变更或调用失败时运行 `draftgo mcp test` |
-| pages/nav/docs 全文、版本或冲突 | `references/checkout.md`；MCP 只定位和读取元数据 |
-| 架构、模块选型或陌生项目 | `references/architecture.md`、`references/modules.md`；存在 `.draftgo/story.yaml` 时一并读取 |
-
-不要用 MCP 摘要代替完整正文，也不要把 Skill 列出的 `/assets/` 能力声称为当前服务器全部文件。业务归属、系统资源或页面类型没有明确元数据时报告证据不足，不凭标题、路径或片段猜测。
-
-页面需求不因出现“页面”二字就默认新建或 checkout。Agent 结合用户意图、现有 route、页面职责和入口自主判断：修改已有页面时定位唯一资源后 checkout；确需独立新页面时先通过 MCP 实时 API 创建并取得 ID，再 checkout 正文。证据足以判断时直接推进；多个候选会导致不同产品结果时再向用户澄清。
-
-## 所有权与执行
-
-- 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；其他 Agent 只读分析并回传建议。
-- 不同资源、operation 和 owner 不冲突的工作单元并发执行，不设置客户端并发上限；同一资源的依赖步骤保持串行。
-- 主 Agent 负责 Reference/MCP 路由、owner 分配、汇总回读、统一验证、交付和 worklog 状态。
-- 冲突 owner、接口依赖或验证失败会阻塞依赖项，不影响无关分支继续汇总。
-
-## 开发与交付
+| 页面、导航、交互或 UI | `references/frontend.md`；涉及 iframe、路由、认证或全局层加读 `runtime.md` / `app-api.md` |
+| pages/nav/docs 正文、版本或冲突 | `references/checkout.md` |
+| 动态 DB、筛选或关系 | `references/data.md`；复杂关系再读 `db-relations.md` |
+| AIHub、知识库、记忆、聊天或图片 | `references/aihub.md`；页面调用再读 `chat-sdk.md` |
+| 自定义服务、权限、外部调用、余额扣款或订阅 | `references/custom-services.md` |
+| MCP 配置、API 契约或故障 | `references/mcp.md`；连接或调用失败时运行 `draftgo mcp test` |
+| 运行失败、日志或请求链路 | `references/diagnostics.md` |
+| 验证、发布或交付验收 | `references/delivery.md` |
+| 跨领域任务且不确定最短链路 | `references/methods.md`，再打开所需领域资料 |
+| 架构、模块选型或陌生项目 | `references/architecture.md`、`references/modules.md`；存在时一并读 `.draftgo/story.yaml` |
 
-### 长正文
+业务归属、系统资源或页面类型没有元数据时，报告证据不足，不凭标题、路径或片段猜测。页面需求不因出现“页面”二字就默认新建或 checkout：修改已有资源时先唯一定位，确需独立新页面时先通过 MCP 实时 API 创建并取得 ID，再 checkout 正文；多个候选会导致不同产品结果时再向用户澄清。
 
-1. 确认目标 pages/nav/docs 已存在并通过 MCP 读取 metadata；新增资源先按实时 API 契约创建并取得 ID。
-2. 对需要完整分析或编辑的目标批量 checkout；在 `.draftgo/worktree/` 按唯一 owner 编辑。
-3. 主 Agent 回读全部修改，并按顶部统一验证策略完成交付前验收。
-4. 用 `draftgo diff <type> <id>` 检查 base/local 差异，再按类型运行 `draftgo commit ...`。
-5. 409/412 时停止自动提交，保留 base/local/remote 冲突材料；不得 force、覆盖或自动合并。
+## 长正文与结构化资源
 
-完整 manifest、流式传输、哈希和冲突规则见 `references/checkout.md`。
+1. 精确定位目标后再 checkout；对需要完整分析或编辑的目标批量 checkout，并在 `.draftgo/worktree/` 由唯一 owner 编辑。
+2. 先用 `draftgo diff <type> <id> --stat` 或 `--summary` 判断范围；只有需要审查内容时才展开完整 diff。
+3. 运行所需的 `draftgo verify`，再 commit。409/412 时停止，保留 base/local/remote；不得 force、覆盖或自动合并。
+4. 结构化资源不 checkout：未知 operation 才 search，首次使用或 registry revision 变化时 describe，其余使用缓存后 call；describe 不完整就停止，不猜字段、权限或风险。
 
-### 结构化资源
+完整传输、manifest 和冲突规则见 `references/checkout.md`；交付证据见 `references/delivery.md`。
 
-遵循 `references/mcp.md` 的契约缓存：operation 未知才 search，首次使用或 revision 变化时 describe，其他情况复用缓存并直接 call。describe 不完整就停止，不猜参数、响应、权限或风险。独立资源并发读写，回读结果并验证副作用；结构化资源不 checkout。
-
-### 工作记录
-
-任务开始即写入开发中状态；独立事项可先以待开发状态加入：
-
-```bash
-draftgo work start "<事项>"
-draftgo work add "<独立事项>"
-```
-
-开始处理待开发项时运行 `draftgo work start-item <编号>`。只有 `draftgo verify` 和所有 commit/MCP 写入成功后，才运行 `draftgo work complete <编号> --note "<结果或证据>"`。用户明确要求视觉验收时还需完成对应截图或浏览器校验。任何验证失败、409/412 或交付失败都不得标记为完成。
-
-## 安全规则
-
-- SAT 只保存在 `.draftgo/config.json`；不得进入宿主配置、命令行参数、Skill、日志、manifest 或错误消息。宿主只配置 `draftgo mcp serve`。
-- 页面优先使用可信本地资源；禁止境外 CDN。用户输入或不可信 HTML 在渲染前净化，关键状态不能只靠颜色或动效表达。
-- 页面通过 `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 或自行实现旧式二次认证。
-- 不要隐式 force、自动重试覆盖或自动合并冲突。
-
-## 验证证据
-
-| 范围 | 最低证据 |
-|---|---|
-| MCP 连接 | 失败时用 `draftgo mcp test` 核对 initialize、tools/list 和关键工具；输出不含 SAT |
-| 页面、导航、文档 | 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` 只能沿用当前 check/commit 语义。主 Agent 最终明确区分 Skill 约束、MCP 实时状态和 checkout 正文证据。
+- 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；不同资源、operation 和 owner 不冲突的单元可以并发，不设置客户端并发上限；同一资源的依赖步骤保持串行。主 Agent 负责 owner 分配、汇总、验证、交付和 worklog 状态。
+- 用户 API Key 只保存在 `.draftgo/config.json`，不得进入宿主配置、命令参数、Skill、日志、manifest 或错误消息。宿主 MCP 配置只运行 `draftgo mcp serve`。
+- 页面优先使用可信本地资源；禁止境外 CDN。净化不可信 HTML，关键状态不能只靠颜色或动效表达。页面通过 `window.parent.App` 使用认证、权限、反馈和主题；详细规则见前端与运行时 Reference。
+- 普通自定义服务 SDK 调用继承调用者、服务归属和 AccessGrant；`ctx.Admin.*` 是仅供自定义服务显式选择的单次系统内部授权，按 `*:*:all` 全权限执行并进入审计，不会泄漏到后续调用。高风险 MCP operation 仅在用户意图明确且影响范围已核对时设置 `confirm=true`。
+- `.draftgo/tmp/` 可清理；先运行 `draftgo clean --dry-run`，再在需要时使用 `--yes`。用户可查验的证据放入已注册的 `.draftgo/artifacts/`。
 
-## 本地工作区
+## 完成条件
 
-- `.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`、`lessons/`：项目决策和经验。
-- `.draftgo/worklog.md`：待开发、开发中和已完成事项及备注。
+每个目标均有与其类型相符的证据：正文有 checkout、验证、commit 返回的版本/哈希及必要远端回读；结构化资源有 describe、写入结果和回读；自定义服务的 `commit` 会完成 validate/publish，按需补充 test。任何验证失败、409/412 或交付失败都不得标记为完成；任何 verify、写入、回读或要求的视觉验收失败时，工作项保持 active。

package/resources/skill/init/SKILL.md

@@ -19,15 +19,15 @@ description: Install or refresh the DraftGo skill, connect a project to a DraftG
 6. 连接后运行 draftgo mcp setup（或指定目标），再运行 draftgo mcp test 验证 initialize、tools/list 和关键工具。
 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 init 只负责 Skill 安装；draftgo connect 负责保存并验证 server/API Key；draftgo mcp setup 负责宿主配置。不要混用职责。
 
 初始化后 `.draftgo/` 只保留已经写入的 `config.json`。不要预建 worklog、lessons、worktree、conflicts 或其他占位文件和目录；首次实际使用对应能力时再创建。
 
-## SAT 与配置
+## API Key 与配置
 
-- 交互式连接应使用隐藏输入；不要把 SAT 写入宿主配置、Skill 文件、命令行示例或日志。
+- 交互式连接使用当前用户的 DraftGo API Key 和隐藏输入；不要把 API Key 写入宿主配置、Skill 文件、命令行示例或日志。
 - .draftgo/config.json、checkout manifest、base 和冲突目录必须加入项目 .gitignore。
-- bridge 从当前项目配置读取 SAT；宿主配置只引用 draftgo mcp serve。
+- bridge 从当前项目配置读取 API Key；宿主配置只引用 draftgo mcp serve。
 
 ## 后续动作
 

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "4.0.1",
+  "version": "4.0.23",
   "entry": "SKILL.md",
   "description": "以 Skill/reference 任务路由、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",
@@ -11,8 +11,12 @@
     "reference-routing",
     "worklog-tracking",
     "custom-service-ai-sdk",
+    "minimal-method-guides",
+    "aihub-knowledge-memory",
     "mcp-bridge",
     "content-checkout-commit",
+    "runtime-diagnostics",
+    "delivery-acceptance",
     "conflict-safe-delivery",
     "project-validation",
     "skill-installation"

package/resources/skill/references/aihub.md

@@ -4,6 +4,24 @@ read_when: 创建或调优 AI Agent 时 · 需要工具/子智能体/记忆/多
 
 # AIHub / Agent 资源
 
+## 最短管理流程
+
+AIHub、知识库与记忆都是结构化远端资源。先按领域搜索实时 operation，再描述契约并调用；`request.json` 只包含 describe 允许的字段：
+
+```bash
+draftgo api search "AIHub Agent"
+draftgo api search "knowledge base"
+draftgo api search "agent memory"
+draftgo api describe <operation_id>
+draftgo api call <operation_id> --input request.json --output json
+```
+
+已有精确 `operation_id` 时跳过 search。写入后用对应 get/list operation 回读目标 ID；需要验证运行行为时，再查调用 operation 和 AI run 日志，不把配置成功当成推理成功。知识库存放可检索资料，长期记忆存放 Agent 运行时按作用域提炼的用户/Agent 记忆，两者不要互相代替。
+
+AIHub 与知识库是独立权限域：Agent、模型和 AI 运行使用 `aihub:*`，知识库、文档、上传、检索和重建使用 `knowledge:*`。配置了 `aihub:*` 不会自动获得知识库权限，反之亦然；具体动作仍以实时 operation 契约为准。
+
+完成条件：目标资产可回读，状态与调用权限符合预期；任务涉及调用时，运行成功且日志能按入口 Agent/模型定位。任何文件和输出都不得包含供应商密钥。
+
 AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先使用 MCP `draftgo_resource_search`/`draftgo_resource_list`
 定位资产；未知 operation 才用 `draftgo_api_search`，首次使用或 registry revision 变化时 `draftgo_api_describe`，然后通过 `draftgo_api_call` 读写。
 更新 AIHub 资产时只发送实时契约允许的字段；常见字段包括
@@ -37,7 +55,7 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 
 | 字段 | 类型 / 取值 | 说明 |
 |---|---|---|
-| `mode` | `chat` / `image_generation` | 决定走 `/chat` 还是 `/images`；调错接口会被后端拒绝 |
+| `mode` | `chat` / `image_generation` | 决定主要交互形态；具体 Responses、Embedding、Rerank、TTS、ASR、Video operation 以 MCP 和模型 capability 为准 |
 | `model` | string | 主模型（逻辑模型名，映射到供应商路由） |
 | `fallback_models` | string[] | 主模型失败后按序回退（跨模型 failover） |
 | `model_selection.user_selectable` | bool | 是否允许调用方在请求里覆盖 `model`（配合 `selectable-models`） |
@@ -57,6 +75,7 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 | `skills` | 见运行时 | 绑定 Skill |
 | `sub_agent_ids` | int[] | 子智能体：为每个 id 生成 `agent_{id}` 委派工具（用法同 `knowledge_base_ids`） |
 | `call_permissions` | 角色配置 | 哪些角色可以调用此 Agent；调用接口与筛选条件以 MCP 实时契约为准 |
+| `billing_mode` | `disabled` / `inherit_model` / `per_call` / `usage` | Agent 零售计费；公开 Agent 强制 `disabled`，订阅/会员额度由业务服务管理 |
 
 ### `orchestration.*`（编排开关）
 
@@ -88,6 +107,10 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 每次调用都开一条 AI run，管理台 `/admin/ai-runs` 展示状态、tokens、延迟、`ttft_ms` 与 span 链路。
 运行记录接口通过 MCP 实时发现，不维护静态路径表；已知 operation 复用 registry revision 未变化的契约缓存。
 
+模型价格使用 `disabled`、`per_call`、`usage`。模型能否调用某项能力必须同时满足模型声明、Provider
+profile、transport readiness 和实际 route；不要只根据供应商名称推断支持音频、视频或其他能力。
+能力名大小写敏感，使用实时 describe 返回的 canonical 值，不使用历史别名。
+
 Agent 对外响应（`/api/agents/{id}/chat`、图片接口、Go/Script SDK Agent 调用）不返回内部 `model`、`fallback_models` 或 `upstream_model`；错误也不暴露内部模型名、供应商名称、服务地址或运行时实现名。只有显式启用 `model_selection.user_selectable` 后，`/selectable-models` 才作为授权的模型选择目录返回可选逻辑模型名。运行日志仍在服务端保留真实模型、供应商与链路信息用于定位。
 
-> 权威细节以 DraftGo 后端 `docs/backend/modules/agent-runtime.md` 为准；本页是基座开发者视角的字段速查。
+> 权威细节以 DraftGo `docs/modules/ai-platform/agent-runtime.md` 和实时 MCP schema 为准；本页是基座开发者视角的字段速查。

package/resources/skill/references/app-api.md

@@ -12,11 +12,11 @@ const App = window.parent?.App;
 
 | 方法 | 签名 | 说明 |
 |---|---|---|
-| `App.get` | `(path, params?)` | GET，params 为 query 参数 |
-| `App.post` | `(path, body?)` | POST |
-| `App.put` | `(path, body?)` | PUT |
-| `App.patch` | `(path, body?)` | PATCH |
-| `App.delete` | `(path)` | DELETE |
+| `App.get` | `(path, params?, headers?)` | GET，params 为 query 参数 |
+| `App.post` | `(path, body?, headers?)` | POST |
+| `App.put` | `(path, body?, headers?)` | PUT |
+| `App.patch` | `(path, body?, headers?)` | PATCH |
+| `App.delete` | `(path, params?, headers?)` | DELETE |
 | `App.uploadFile` | `(file, onProgress?)` | 文件上传，返回标准信封 |
 
 **响应格式**：`{ code: 200, data: <载荷>, message: "success" }`  
@@ -67,11 +67,57 @@ const { patientId, visitId } = routeContext.query;
 |---|---|---|
 | `App.currentUser` | object \| null | 当前用户，未登录为 null |
 | `App.isAdmin` | boolean | 是否管理员 |
+| `App.permissions` | string[] | 当前用户有效 permission grant 的展示投影；仅用于页面显隐，不替代服务端授权 |
 | `App.isAuthenticated` | boolean | 是否已认证 |
 | `App.hasToken` | boolean | 是否有 token（含未验证） |
 | `App.config` | object | 系统配置 KV |
 | `App.theme` | `'light'` \| `'dark'` | 当前显示模式 |
 | `App.colorScheme` | string | 当前配色方案 |
+| `App.scopeContext` | object | null | 当前候选范围；`scope_type` 为 `platform` / `space` |
+| `App.availableSpaces` | object[] | 当前用户可选择的工作区与递归空间 |
+
+### 空间上下文
+
+空间业务请求使用运行时当前上下文。页面先显示加载状态，再等待有效空间；返回 `null` 时呈现紧凑的工作空间状态和重试入口，本轮不发送业务请求。
+
+```javascript
+function currentSpace() {
+  const scope = App.getScopeContext?.() || App.scopeContext;
+  return scope?.scope_type === 'space' && scope.space_id ? scope : null;
+}
+
+async function waitForSpace(timeout = 4000) {
+  if (currentSpace()) return currentSpace();
+  return new Promise(resolve => {
+    const host = window.parent;
+    const done = value => {
+      clearTimeout(timer);
+      host?.removeEventListener('dg:scope-changed', check);
+      host?.removeEventListener('dg:scope-spaces-changed', check);
+      resolve(value);
+    };
+    const check = () => { if (currentSpace()) done(currentSpace()); };
+    const timer = setTimeout(() => done(null), timeout);
+    host?.addEventListener('dg:scope-changed', check);
+    host?.addEventListener('dg:scope-spaces-changed', check);
+    check();
+  });
+}
+
+const scope = await waitForSpace();
+if (!scope) {
+  renderWorkspaceState();
+  return;
+}
+await App.get('business-items', { page: 1 });
+```
+
+平台管理接口按接口契约显式传入平台范围：
+
+```javascript
+const platformHeaders = { 'X-DraftGo-Scope-Type': 'platform' };
+await App.get('roles', {}, platformHeaders);
+```
 
 ## 主题
 
@@ -89,7 +135,11 @@ await App.logout();                 // 服务端登出、清理状态并跳转
 App.setAuthTokens({ access_token, refresh_token });  // 登录后写入 token
 App.reloadGlobalLayer();            // 重载全局层
 App.openGlobalWidget(name);         // 触发全局挂件打开
-App.t(key, fallback?);              // 国际化文本
+App.getScopeContext();              // 读取当前作用域
+App.setScopeContext({ scope_type: 'space', space_id: '120' });
+App.clearScopeContext();             // 清除手工选择，恢复服务端默认
+App.t(key, fallback?, values?);      // 页面级国际化文本，values 保留 ICU 占位符
+App.formatDateTime(value, options?); // 按 system_timezone 格式化 API 返回的 UTC 时间
 ```
 
 Token、刷新、路由上下文和认证事件见 `references/runtime.md`。AI 对话、图片和兼容门面的完整契约见 `references/chat-sdk.md`，Agent 能力见 `references/aihub.md`。

package/resources/skill/references/architecture.md

@@ -40,7 +40,7 @@ DraftGo **不是传统 SPA**，是「数据库驱动的页面资产运行时」
 |---|---|
 | 后端 | Go 1.26 · 标准库 `net/http` · `database/sql`（go-sql-driver/mysql）· MySQL · Redis |
 | 壳层前端 | React · Vite |
-| 数据库页面 | HTML 文档运行时 · 内置组件库 · Tailwind CSS · FontAwesome · GSAP · html2canvas · 内置 SVG 图标库 |
+| 数据库页面 | HTML 文档运行时 · Tailwind CSS 4 · Basecoat UI（默认）· Oat UI（可选）· Font Awesome · GSAP · 内置 SVG 图标库 |
 | CLI | Node.js（draftgo-cli） |
 
-数据库页面**不需要** npm install，也**不进入**壳层编译；页面可在 HTML 文档中按任务加载平台提供的浏览器组件库和本地资源。
+数据库页面以完整 HTML 文档运行，直接加载平台提供的本地资源；壳层源码按 React + Vite 工程构建。开发时按目标所属层使用上表对应技术栈。

package/resources/skill/references/chat-sdk.md

@@ -4,7 +4,7 @@ read_when: 页面需要 AI 对话 UI 时 · 使用 dg-chat 或 DraftGoChat 时
 
 # DraftGo Chat SDK
 
-DraftGo 页面只使用完整版 `/assets/draftgo-chat.js`。它是原生 Web Component，不依赖 React、JSX 或 npm。不要为单个页面复制消息状态机、流解析、停止、重试或历史逻辑。
+DraftGo 页面使用完整版 `/assets/draftgo-chat.js` 原生 Web Component。SDK 统一提供消息状态机、流解析、停止、重试和历史逻辑。
 
 ## 目录
 
@@ -71,7 +71,7 @@ DraftGo 页面只使用完整版 `/assets/draftgo-chat.js`。它是原生 Web Co
 
 这些 `/api/ai-proxy/*` 是接入方实现的占位路由，不是 DraftGo 自动提供的默认代理。不要将供应商密钥或长期 token 写入页面。
 
-内置 transport 支持 SSE、NDJSON 和普通 JSON，并把上游响应归一化为 `text.delta`、`reasoning.delta`、`tool.start`、`tool.delta`、`tool.finish`、`artifact.complete`、`source`、`usage`、`message.finish`、`error` 等事件。
+内置 transport 支持 SSE、NDJSON 和普通 JSON，并把上游响应归一化为 `text.delta`、`reasoning.delta`、`tool.start`、`tool.delta`、`tool.finish`、`step.finish`、`artifact.complete`、`source`、`usage`、`message.finish`、`error` 等事件。配置 JSON 以 DraftGo 当前 `contracts/chat-sdk.schema.json` 为准；不要猜测字段或把函数、DOM、renderer、plugin、transport 写入 JSON。
 
 ## 配置与布局
 
@@ -160,6 +160,8 @@ chat.addEventListener('dg-chat:run-finish', event => {
 
 页面销毁或离开路由时调用 `stop()`，取消上传、plugin 和在途 transport。
 
+`requestTimeoutMs` 和 `streamTimeoutMs` 分别控制客户端非流式/流式总时限，默认 120000/610000 毫秒，`0` 表示禁用。两者只处理客户端半开连接，不替代 Agent 的服务端超时。
+
 ## 历史与会话
 
 - `persist` 默认开启，将 UI thread 历史写入 `localStorage`；敏感或临时页面设为 `false`。

package/resources/skill/references/checkout.md

@@ -4,9 +4,21 @@ read_when: 编辑 pages、navigation 或 docs 正文时 · 查看 checkout manif
 
 # Checkout / Commit
 
+## 页面与内容最短流程
+
+```bash
+draftgo map --type pages --route /admin/channel-ops --output json
+draftgo checkout pages 42
+draftgo diff pages 42 --stat
+draftgo verify pages 42
+draftgo commit pages 42
+```
+
+导航和文档分别替换为 `nav`、`docs`。route/title 为精确匹配，两个条件取交集；只需确认范围或 checkout 状态时使用 `map --summary`，必须浏览时使用 `--limit <1-100>`（默认 20），并仅在单一 `--type` 下用 `--cursor <opaque>` 翻页。新资源先用 `draftgo api search "create page"` 或对应内容类型定位创建 operation，describe/call 取得 ID 后再 checkout；不要用 checkout 创建资源。`verify` 通过不等于已交付，commit 返回新版本与哈希才算正文写入成功。发生 409/412 时保留冲突材料并停止提交。
+
 ## Workflow 2.0 scope
 
-The checkout set includes `pages`, `navigations`, `docs/articles`, and `custom_services`. A custom-service checkout is a directory containing exactly `service.go`, `go.mod`, `go.sum`, and `service.json`, plus one complete `.base` directory. `draftgo commit custom-services <id>` saves a cloud draft; it does not publish. Use `draftgo test custom-services <id>` for server Runner validation/execution and `draftgo publish custom-services <id>` for explicit publication. DB Meta remains a live MCP/API resource and is never checked out.
+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.
 
@@ -32,7 +44,7 @@ Checkout 只为已存在且已确认 ID 的资源建立本地正文与 base，
 draftgo checkout <pages|nav|docs> <id...>
 draftgo commit <pages|nav|docs> <id...>
 draftgo reconcile <pages|nav|docs> <id...>
-draftgo diff <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>
@@ -41,11 +53,13 @@ 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。
-2. CLI 使用 `.draftgo/config.json` 中的 SAT 通过专用 HTTP 下载完整正文；SAT 不进入 MCP 参数或日志。
+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。