draftgo-cli 3.0.1 → 3.0.33

package/resources/skill/{quickref → references}/app-api.md

@@ -22,9 +22,11 @@ const App = window.parent?.App;
 **响应格式**：`{ code: 200, data: <载荷>, message: "success" }`  
 **消费范式**：
 ```javascript
-const res = await App.get('pages', { page: 1, page_size: 20 });
+const res = await App.get('pages'); // 不传分页参数时全量返回
 if (res.code !== 200) { App.showError(res.message); return; }
-const items = res.data.items;  // 分页列表
+const items = res.data.items;
+
+const paged = await App.get('pages', { page: 1, page_size: 20 }); // 显式分页
 ```
 
 ## 反馈
@@ -80,18 +82,6 @@ App.setColorScheme('custom', customVarsObject);   // 自定义配色
 App.getColorScheme();                             // 获取方案详情
 ```
 
-## 外部 API
-
-```javascript
-App.listApis();                     // 列出可调用 API（含 code/name/schema）
-App.callApi('weather-now', {
-  path_params: { city: 'beijing' },
-  query_params: { unit: 'metric' },
-  // body: {...}                     // POST/PUT/PATCH 才生效
-});
-// 返回：{ status_code, headers, body, duration_ms, error }
-```
-
 ## 其他
 
 ```javascript
@@ -108,3 +98,43 @@ App.t(key, fallback?);              // 国际化文本
 |---|---|
 | `localStorage.dg_access_token` | 访问 token |
 | `localStorage.dg_refresh_token` | 刷新 token |
+
+## AI 对话与兼容门面
+
+新页面的可见对话使用 `<dg-chat>` 或 `DraftGoChat.create()`。两者都由 `/assets/draftgo-chat.js` 注册，壳层不会默认注入：
+
+```html
+<script src="/assets/draftgo-chat.js"></script>
+<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
+```
+
+完整配置、协议、事件和安全约束见 `references/chat-sdk.md`。
+
+### `DraftGoAI` 旧兼容门面
+
+`window.DraftGoAI` 由同一完整版脚本注入，用 Agent id 而非直连模型。它适合旧代码、无 UI 的轻量文本调用和图片生成；新页面不要用它重建对话界面。
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `DraftGoAI.chat` | `(agentId, message, onDelta?, options?)` | 对话；**默认流式**，`onDelta(delta, full)` 每个增量触发一次，Promise resolve 完整文本 |
+| `DraftGoAI.images` | `(agentId, prompt, options?)` | 图片模式 Agent，`POST /api/agents/{id}/images`，返回标准信封 |
+| `DraftGoAI.getSelectableModels` | `(agentId)` | 返回 `{ user_selectable, models }` |
+
+```javascript
+// 流式对话
+const text = await DraftGoAI.chat(agentId, '你好', (delta, full) => render(full));
+
+// 多轮：传 sessionId（→ body.session_id）复用同一会话；Agent 开启“持续对话”后服务端续写历史
+await DraftGoAI.chat(agentId, '接着上一条', onDelta, { sessionId: threadKey });
+
+// 用户选模型 + 覆盖模型
+const { user_selectable, models } = await DraftGoAI.getSelectableModels(agentId);
+await DraftGoAI.chat(agentId, '你好', onDelta, { model: models[0]?.id, sessionId: threadKey });
+
+// 图片生成（不要用 chat）
+const res = await DraftGoAI.images(agentId, '生成主图', { size: '1024x1024', n: 1 });
+```
+
+**`options` 常用键**：`sessionId`（多轮会话键）、`model`（覆盖模型）、`stream`（默认 true）、`context`。
+不传 `sessionId` = 无状态单轮。富交互 UI（附件、模型选择器、推理展示、历史、重生成）用
+`<dg-chat>`，见 `references/chat-sdk.md`；Agent 能力全景见 `references/aihub.md`。

package/resources/skill/{core → references}/architecture.md

@@ -28,27 +28,6 @@ DraftGo **不是传统 SPA**，是「数据库驱动的页面资产运行时」
 
 ---
 
-## dg-* = shadcn（核心认知，最高优先级）
-
-```
-dg-button     →  shadcn <Button>
-dg-card       →  shadcn <Card>
-dg-form       →  shadcn <Form>
-dg-table      →  shadcn <Table>
-dg-dialog     →  shadcn <Dialog>
-dg-sheet      →  shadcn <Sheet>
-dg-tabs       →  shadcn <Tabs>
-dg-dropdown-menu → shadcn <DropdownMenu>
-dg-tooltip    →  shadcn <Tooltip>
-dg-skeleton   →  shadcn <Skeleton>
-```
-
-- `dg-*` = shadcn/ui 的 DraftGo HTML 协议表达，**不是** daisyUI / Bootstrap / 自研库
-- 数据库页面不进入 Vite/React 编译链，所以不能写 TSX；改用对应 `dg-*` 标签
-- 完整映射表见 `{{SKILL_DIR}}/specs/ui-protocol.md`
-
----
-
 ## App 对象是什么（1 分钟）
 
 壳层将能力对象赋值给 `window.App`，页面内通过 `window.parent.App` 访问：
@@ -57,7 +36,8 @@ dg-skeleton   →  shadcn <Skeleton>
 const App = window.parent?.App;
 
 // 请求（自动携带 token）
-await App.get('pages', { page: 1, page_size: 20 });
+await App.get('pages');                         // 全量列表
+await App.get('pages', { page: 1, page_size: 20 }); // 分页列表
 await App.post('db/order', { data: { name: '张三' } });
 
 // 反馈
@@ -75,7 +55,7 @@ App.isAdmin       // 是否管理员
 App.theme         // 'light' | 'dark'
 ```
 
-完整 API 速查表见 `{{SKILL_DIR}}/quickref/app-api.md`
+完整 API 速查表见 `{{SKILL_DIR}}/references/app-api.md`
 
 ---
 
@@ -83,9 +63,9 @@ App.theme         // 'light' | 'dark'
 
 | 层 | 技术 |
 |---|---|
-| 后端 | FastAPI 0.115.0 · SQLAlchemy 2.0.36 · Pydantic 2.10.0 · MySQL · Redis |
-| 壳层前端 | React · Vite · shadcn/ui · Tailwind CSS |
-| 数据库页面 | 原生 HTML · `/assets/tailwindcss.js`（运行时）· FontAwesome · GSAP · 内置 SVG 图标库 |
+| 后端 | Go 1.26 · 标准库 `net/http` · `database/sql`（go-sql-driver/mysql）· MySQL · Redis |
+| 壳层前端 | React · Vite |
+| 数据库页面 | 原生 HTML · `/assets/tailwindcss.js`（运行时）· FontAwesome · GSAP · html2canvas · 内置 SVG 图标库 |
 | CLI | Node.js（draftgo-cli） |
 
 数据库页面**不需要** npm install，也**不进入** React 编译，直接写 HTML + 本地资源路径。

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

@@ -0,0 +1,201 @@
+---
+read_when: 页面需要 AI 对话 UI 时 · 使用 dg-chat 或 DraftGoChat 时 · 接入 Agent/OpenAI/Anthropic/custom transport 时
+---
+
+# DraftGo Chat SDK
+
+DraftGo 页面只使用完整版 `/assets/draftgo-chat.js`。它是原生 Web Component，不依赖 React、JSX 或 npm。不要为单个页面复制消息状态机、流解析、停止、重试或历史逻辑。
+
+## 目录
+
+- [最小接入](#最小接入)
+- [协议](#协议)
+- [配置与布局](#配置与布局)
+- [JavaScript API 与事件](#javascript-api-与事件)
+- [历史与会话](#历史与会话)
+- [扩展](#扩展)
+- [鉴权与安全](#鉴权与安全)
+
+## 最小接入
+
+脚本不是壳层默认全局注入。使用 `<dg-chat>` 或兼容门面 `DraftGoAI` 前必须先加载：
+
+```html
+<script src="/assets/draftgo-chat.js"></script>
+<dg-chat protocol="draftgo-agent" agent-id="AGENT_ID"></dg-chat>
+```
+
+`draftgo-agent` 默认请求 `/api/agents/{id}/chat`，并复用同源 DraftGo App 的 Bearer token 与刷新机制。
+
+需要 JavaScript 配置时：
+
+```html
+<div id="chat-host"></div>
+<script src="/assets/draftgo-chat.js"></script>
+<script>
+  const chat = DraftGoChat.create('#chat-host', {
+    protocol: 'draftgo-agent',
+    agentId: 'AGENT_ID',
+    surface: 'inline',
+    view: 'conversation',
+    stream: true,
+    features: {
+      attachments: true,
+      reasoning: true,
+      history: true,
+      artifacts: true
+    }
+  });
+</script>
+```
+
+新页面优先使用 `<dg-chat>` 或 `DraftGoChat.create()`。`DraftGoAI.chat()` 是同一脚本提供的旧代码兼容门面，内部创建隐藏 `<dg-chat>`，仅适合不需要对话 UI 的轻量文本调用。图片模式继续使用 `DraftGoAI.images()`。
+
+## 协议
+
+| `protocol` | 必需配置 | 说明 |
+|---|---|---|
+| `draftgo-agent` | `agentId` | DraftGo Agent；默认端点 `/api/agents/{id}/chat` |
+| `openai-chat`（alias `openai`） | `endpoint` | OpenAI Chat Completions 兼容协议 |
+| `openai-responses` | `endpoint` | OpenAI Responses 协议 |
+| `anthropic-messages`（alias `anthropic`） | `endpoint` | Anthropic Messages 协议 |
+| `custom` 或注册名 | 已注册 transport | 页面提供 async generator transport |
+
+外部协议必须指向服务端代理：
+
+```html
+<dg-chat protocol="openai-chat" endpoint="/api/ai-proxy/openai" model="MODEL"></dg-chat>
+<dg-chat protocol="openai-responses" endpoint="/api/ai-proxy/responses" model="MODEL"></dg-chat>
+<dg-chat protocol="anthropic-messages" endpoint="/api/ai-proxy/anthropic" model="MODEL"></dg-chat>
+```
+
+这些 `/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` 等事件。
+
+## 配置与布局
+
+简单配置使用属性：
+
+```html
+<dg-chat
+  id="page-assistant"
+  protocol="draftgo-agent"
+  agent-id="AGENT_ID"
+  surface="drawer"
+  view="threads"
+  position="right"
+  title="AI Assistant"
+  placeholder="输入内容"
+  persist="true"
+  stream="true"
+  enable-attachments
+  show-reasoning
+></dg-chat>
+```
+
+| 配置 | 可选值 |
+|---|---|
+| `surface` | `inline`、`floating`、`drawer`、`fullscreen` |
+| `view` | `conversation`、`threads`、`compact`、`workspace` |
+| `position` | `left`、`right` |
+| `theme` | `light`、`dark`；省略时跟随系统 |
+
+复杂的纯数据配置使用 `config-ref`：
+
+```html
+<script type="application/json" id="page-chat-config">
+{
+  "protocol": "draftgo-agent",
+  "agentId": "AGENT_ID",
+  "surface": "inline",
+  "view": "workspace",
+  "storageKey": "dg-chat:PAGE_KEY:INSTANCE_KEY",
+  "features": {
+    "reasoning": true,
+    "attachments": true,
+    "history": true,
+    "feedback": false,
+    "artifacts": true
+  },
+  "suggestions": ["总结当前页面", "生成结构化结果"],
+  "context": { "page": "PAGE_KEY" }
+}
+</script>
+<dg-chat config-ref="page-chat-config"></dg-chat>
+```
+
+函数、DOM Node、renderer、plugin、upload 和 custom transport 只能通过 JavaScript 配置，不能写进 JSON。主题优先使用 `--dg-chat-*` CSS variables、公开 `::part()` 和 slots，不选择 Shadow DOM 内部 class。
+
+## JavaScript API 与事件
+
+```javascript
+const chat = document.querySelector('#page-assistant');
+
+chat.configure({ model: 'MODEL', context: { page: 'PAGE_KEY' } });
+await chat.send('处理当前输入');
+chat.stop();
+chat.regenerate();
+chat.newThread();
+chat.selectThread('THREAD_ID');
+chat.deleteThread('THREAD_ID');
+chat.renameThread('THREAD_ID', '新的会话名称');
+chat.clearThreads();
+chat.setMessages([]);
+chat.clear();
+chat.open();
+chat.close();
+chat.toggle();
+```
+
+全局 API：`DraftGoChat.create()`、`registerTransport()`、`registerRenderer()`、`registerComponent()`、`definePreset()`、`use()`。
+
+常用事件：`dg-chat:ready`、`dg-chat:before-send`、`dg-chat:message`、`dg-chat:run-start`、`dg-chat:stream-event`、`dg-chat:run-finish`、`dg-chat:run-abort`、`dg-chat:error`、`dg-chat:message-action`、`dg-chat:session-change`、`dg-chat:model-change`、`dg-chat:open`、`dg-chat:close`。
+
+```javascript
+chat.addEventListener('dg-chat:run-finish', event => {
+  console.log(event.detail);
+});
+```
+
+页面销毁或离开路由时调用 `stop()`，取消上传、plugin 和在途 transport。
+
+## 历史与会话
+
+- `persist` 默认开启，将 UI thread 历史写入 `localStorage`；敏感或临时页面设为 `false`。
+- 同一路由存在多个实例时，每个实例设置唯一 `storageKey`。
+- 每个 UI thread 自动维护独立 `sessionId`；`draftgo-agent` 将其作为 `session_id` 发送。
+- `newThread()` 创建新的后端会话边界；不要让不同用户共享固定 `storageKey` 或 `sessionId`。
+- `clear()` 和 `setMessages([])` 会重置当前 session，避免视觉清空后恢复旧 checkpoint。
+
+## 扩展
+
+自定义协议通过 async generator 产生统一事件：
+
+```javascript
+DraftGoChat.registerTransport('page-protocol', async function* (request, context) {
+  const response = await fetch('/api/x/page/chat', {
+    method: 'POST',
+    signal: context.signal,
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ messages: request.messages })
+  });
+  const data = await response.json();
+  yield { type: 'text.delta', delta: String(data.text || '') };
+  yield { type: 'message.finish' };
+});
+
+chat.configure({ protocol: 'page-protocol' });
+```
+
+局部定制优先级：属性/JSON → CSS variables、parts、slots → 实例 `components`/`renderers` → plugin/custom transport。全局注册会影响同一 window 的所有实例；页面特有行为优先放在实例配置中。
+
+## 鉴权与安全
+
+- 同源请求优先使用 iframe 可见的 `window.App.fetchAbsolute`，复用 DraftGo token 和刷新机制。
+- 供应商凭证不得自动或手工发送到外部 origin；OpenAI/Anthropic 使用服务端代理。
+- 页面 HTML、JSON config、`headers`、`context` 和 `localStorage` 中不得保存长期供应商密钥。
+- 不把模型输出直接赋给 `innerHTML`；使用 SDK 内置 Markdown/URL 安全渲染或显式净化。
+- 后端始终负责 Agent 调用权限、模型白名单、附件能力和大小限制，前端开关不能越权。
+
+交付前确认：只加载一个完整版脚本；新页面以 `<dg-chat>` 为对话 UI；同页多实例隔离 `storageKey`；外部协议走服务端代理；页面离开时停止在途请求。

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

@@ -0,0 +1,308 @@
+---
+read_when: 编写、修改、调试或评审自定义服务时；使用服务 SDK、路由、事件、定时任务或服务依赖时
+---
+
+# Go 自定义服务契约
+
+DraftGo 的新自定义服务使用 Go。服务代码是完整的 `package main`，可以使用标准库和 `go.mod` 中声明的第三方库。平台在保存或发布时编译服务、运行 `Register` 并保存触发器清单；执行时在独立子进程中调用选定 handler。
+
+平台 SDK 的固定导入路径是 `draftgo/sdk`。它是 DraftGo 构建器注入的本地 module，不从 GitHub 或其他网络仓库下载，也不要在服务的 `go.mod` 中自行添加或 `replace` 此依赖。
+
+## 索引
+
+- [最小服务](#最小服务)、[本地资源](#本地资源)、[触发器](#触发器)
+- [平台 SDK](#平台-sdk)、[AI 平台 SDK](#ai-平台-sdk)
+- [权限与运行限制](#权限与运行限制)、[管理 API](#管理-api)、[验收清单](#验收清单)
+
+## 最小服务
+
+```go
+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)
+}
+
+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
+}
+
+func weekdayReport(draftgo *sdk.Context) (any, error) { return nil, nil }
+```
+
+`Register` 必须没有业务副作用。它只注册 handler；网络请求、写数据库、发通知等操作放在 handler 内。
+
+## 本地资源
+
+```text
+.draftgo/custom_scripts/
+├── index.json
+└── script_<id>_<slug>.go
+```
+
+`index.json` 的 Go 服务字段：
+
+```json
+{
+  "name": "order-service",
+  "slug": "order-service",
+	"mode": "mixed",
+  "code_file": ".draftgo/custom_scripts/script_new_order-service.go",
+  "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` 随服务版本保存并由 `draftgo push custom_scripts` 推送。
+- 新依赖应锁定明确版本。构建错误会在保存/发布时返回，不会替换当前有效清单。
+
+## 触发器
+
+### 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。
+
+`draftgo.Input` 的 Route 字段：`method`、`headers`、`body`、`query_params`、`path_params`。当前身份通过 `draftgo.Auth.CurrentUser()` 获取，入站请求头通过 `draftgo.Headers.Get("Authorization")` 等读取。
+
+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 返回值仍必须由代码负责脱敏。
+
+### 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 继承该用户身份；无法解析用户时才以系统身份执行。事件服务应把事件数据视为业务输入，而不是把它当成绕过资源权限的通道。
+
+### Scheduled
+
+```go
+app.Schedule("0 2 * * *", cleanup)
+```
+
+cron 使用五字段表达式，也支持 `interval:5m`。定时 handler 的 `draftgo.Input` 为空对象。
+
+定时任务没有调用者，会以系统身份执行。因此它只能由可信编辑者维护，写入范围应限制在明确的数据类型，并在 handler 中记录可审计的业务日志。
+
+## 平台 SDK
+
+所有资源访问经受控 RPC 返回 Go 主服务。不要自行读取数据库连接、服务 token 或宿主机环境变量。
+
+```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",
+})
+
+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}`。
+
+`draftgo.Users` 支持 `Get`、`List`、`Update`。`draftgo.Auth` 支持 `RequireLogin`、`RequireAdmin`、`RequireRole`、`CurrentUser`。
+
+`draftgo.HTTP` 支持 `Get`、`Post`、`Put`、`Patch`、`Delete`；响应为 `sdk.HTTPResponse{StatusCode, Headers, Data}`。服务可使用 `config.http_allowed_hosts` 限制出站目标；HTTP timeout 最终限制为 1-30 秒，响应体最大 5 MB。
+
+## 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: "总结订单",
+})
+
+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],
+    "allow_direct_model_call": true,
+    "allowed_models": ["gpt-4.1-mini", "text-embedding-3-small"],
+    "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、密码或完整个人信息。
+
+## 权限与运行限制
+
+- `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 协议生成不可变构建键。代码或依赖变更会生成新构建产物；旧版本可通过现有版本恢复接口重新激活。
+
+## 管理 API
+
+管理 API 使用 `{code, data, message}` 信封并受 `scripts:*` 权限控制：
+
+| 方法 | 路径 |
+|---|---|
+| `POST` / `GET` | `/api/scripts` |
+| `GET` | `/api/scripts/options/roles` |
+| `GET` / `PUT` / `DELETE` | `/api/scripts/{id}` |
+| `GET` | `/api/scripts/{id}/routes` |
+| `POST` | `/api/scripts/{id}/enable`、`/api/scripts/{id}/disable`、`/api/scripts/{id}/execute` |
+| `GET` | `/api/scripts/{id}/versions`、`/api/scripts/{id}/executions` |
+| `POST` | `/api/scripts/{id}/versions/{version_id}/restore` |
+| `GET` | `/api/scripts/{id}/executions/{execution_id}` |
+
+运行时 route 为 `ANY /api/x/{slug}/{path}`，不使用管理 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，必要时运行 `draftgo push custom_scripts --probe-routes`。