draftgo-cli 3.0.54 → 3.0.56

package/README.md

@@ -55,6 +55,8 @@ DraftGo Skill 不能被 MCP 替代。根 `SKILL.md` 会在 Skill 触发时自动
 
 页面任务读取 `frontend.md`，按需补读 `runtime.md` / `app-api.md`；数据、自定义服务和 AIHub 任务分别读取对应 Reference。目标明确时不要全量枚举无关资源。`mcp test` 是连接诊断，不是每次资源查询的前置步骤。
 
+页面需求先结合用户意图和 MCP 实时资源判断是修改已有页面还是新增页面。已有页面在确认唯一 ID 后 checkout；独立新页面先通过实时 API 创建并取得 ID，再 checkout 完整正文。“做一个功能页面”本身不预设新建或修改，只有不同判断会产生明显不同结果时才需要向用户澄清。
+
 只回答无需实时状态的本地规则问题时，不必调用 MCP。静态资源须先区分：平台内置目录由 `frontend.md` 说明，指定页面依赖经 MCP 定位、checkout 后本地搜索，服务器全量文件不能凭现有 Skill、MCP 摘要或 checkout 声称已枚举。
 
 Skill 说明产品约束、内置能力和操作规则；MCP 说明当前远端状态；checkout 正文才能证明某个页面完整引用了哪些静态资源。汇报时应明确标注这三类证据，不能互相替代。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "draftgo-cli",
-  "version": "3.0.54",
+  "version": "3.0.56",
   "description": "Install and manage the DraftGo skill across AI coding agents (Claude Code, Codex, Cursor, Windsurf, Antigravity, Copilot, Gemini, Kiro).",
   "bin": {
     "draftgo": "bin/draftgo.js"

package/resources/skill/SKILL.md

@@ -29,7 +29,7 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 
 | 任务 | 专题资料与后续动作 |
 |---|---|
-| 页面、导航、交互或 UI | `references/frontend.md`；涉及 iframe、路由、认证或全局层加读 `runtime.md` / `app-api.md`；MCP 定位后 checkout 完整正文 |
+| 页面、导航、交互或 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 为准 |
@@ -39,6 +39,8 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 
 不要用 MCP 摘要代替完整正文，也不要把 Skill 列出的 `/assets/` 能力声称为当前服务器全部文件。业务归属、系统资源或页面类型没有明确元数据时报告证据不足，不凭标题、路径或片段猜测。
 
+页面需求不因出现“页面”二字就默认新建或 checkout。Agent 结合用户意图、现有 route、页面职责和入口自主判断：修改已有页面时定位唯一资源后 checkout；确需独立新页面时先通过 MCP 实时 API 创建并取得 ID，再 checkout 正文。证据足以判断时直接推进；多个候选会导致不同产品结果时再向用户澄清。
+
 ## 所有权与执行
 
 - 同一文件或 DraftGo 资源全程只能由一个 Agent 修改；其他 Agent 只读分析并回传建议。
@@ -51,8 +53,8 @@ description: Use this skill to inspect, develop, debug, or deliver a DraftGo app
 
 ### 长正文
 
-1. MCP 定位 pages/nav/docs 并读取 metadata。
-2. 批量 checkout；在 `.draftgo/worktree/` 按唯一 owner 编辑。
+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>`。
 5. 409/412 时停止自动提交，保留 base/local/remote 冲突材料；不得 force、覆盖或自动合并。

package/resources/skill/manifest.json

@@ -2,7 +2,7 @@
   "schema_version": "1.0",
   "id": "draftgo",
   "name": "DraftGo 开发助手",
-  "version": "3.0.54",
+  "version": "3.0.56",
   "entry": "SKILL.md",
   "description": "以 Skill/reference 任务路由、MCP 实时发现、长正文 checkout/commit、统一验证和完成日志为边界的 DraftGo 工作流。",
   "license": "MIT",

package/resources/skill/references/aihub.md

@@ -44,7 +44,8 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 | `ttft_timeout` | number（秒，1–600，空=不启用） | 首字超时 failover：首个 SSE data 事件超时即跨模型+跨供应商切换，推理模型不误杀 |
 | `sync_request_timeout` | number（秒，1–600，默认 100） | 非流式请求上限 |
 | `stream_ttl` | number（秒，1–3600，默认 600） | 流式请求上限 |
-| `reasoning_effort` | `minimal`/`low`/`medium`/`high` | 纯透传，仅 OpenAI 系模型生效 |
+| `max_tokens` | number / 空 | 最大输出 token；留空时不写入请求，即不由 Agent 额外限制 |
+| `reasoning_effort` | `off`/`minimal`/`low`/`medium`/`high` | `off`/留空均不透传；其它值仅 OpenAI 系模型生效 |
 | `system_prompt_template` | string | 系统提示模板 |
 | `context.max_history` | number（默认 20） | 工作窗口：保留最近 N 条；关闭持续对话时即滑动窗口硬上限 |
 | `output_format.mode` | `text` / `json` | JSON 时按 `output_format.json.{schema,schema_name,strategy}` 约束/校验/降级 |
@@ -68,7 +69,9 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 | `memory.{enabled,scope}` | false / `user_agent` | 长期记忆：对话后自动提炼、下轮召回注入；作用域 `agent`/`user`/`user_agent` |
 | `compaction.{enabled,keep_recent,trigger_messages,trigger_tokens,preset}` | 关闭 | **持续对话/上下文闭环**：见下 |
 | `checkpoint_input_mode` / `checkpoint_max_messages` / `checkpoint_ttl_seconds` | 全量 / 100 / 86400 | 会话历史持久化（配合请求 `session_id`） |
-| `delegation.{max_depth,max_total_calls}` | 2 / 8 | 子智能体委派的深度与调用预算护栏 |
+| `delegation.{max_depth,max_total_calls}` | 2 / 8 | 最大嵌套层数与整棵调用树共享的子 Agent 调用次数；并行分支也从同一预算扣减 |
+
+同一模型步骤返回多个子 Agent 工具调用时，运行时立即按 `tool_concurrency` 并发执行；不同步骤自然串行，由模型自行决定编排方式。委派成功后，子 Agent 的每个模型回合 token 会汇总到入口 run，总量也写入对应委派 span。一次入口请求只创建一条主 run，Agent 列归属入口 Agent，委派链路从 span 查看。
 
 ### 持续对话（上下文闭环）
 
@@ -85,4 +88,6 @@ AIHub 是结构化远端资源，不 checkout，也不生成本地镜像。先
 每次调用都开一条 AI run，管理台 `/admin/ai-runs` 展示状态、tokens、延迟、`ttft_ms` 与 span 链路。
 运行记录接口通过 MCP `draftgo_api_search` / `draftgo_api_describe` 实时发现，不维护静态路径表。
 
+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` 为准；本页是基座开发者视角的字段速查。

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

@@ -165,6 +165,9 @@ chat.addEventListener('dg-chat:run-finish', event => {
 - `persist` 默认开启，将 UI thread 历史写入 `localStorage`；敏感或临时页面设为 `false`。
 - 同一路由存在多个实例时，每个实例设置唯一 `storageKey`。
 - 每个 UI thread 自动维护独立 `sessionId`；`draftgo-agent` 将其作为 `session_id` 发送。
+- 切换会话只改变当前视图，不会停止其它 thread 的在途请求。会话列表标题左侧显示运行中状态；后台完成或失败后显示未读状态，进入该会话即视为已读并清除。
+- 每个请求使用独立 `run_id`。用户停止或 SDK 超时会调用 Agent 取消接口；普通会话切换不会发送取消。
+- 推理片段和工具调用按服务端事件的输出位置保留在消息内，不固定贴在消息底部；思考在正文、工具或结束事件到达后进入完成态，不再闪烁或滚动预览。
 - `newThread()` 创建新的后端会话边界；不要让不同用户共享固定 `storageKey` 或 `sessionId`。
 - `clear()` 和 `setMessages([])` 会重置当前 session，避免视觉清空后恢复旧 checkpoint。
 
@@ -197,5 +200,12 @@ chat.configure({ protocol: 'page-protocol' });
 - 页面 HTML、JSON config、`headers`、`context` 和 `localStorage` 中不得保存长期供应商密钥。
 - 不把模型输出直接赋给 `innerHTML`；使用 SDK 内置 Markdown/URL 安全渲染或显式净化。
 - 后端始终负责 Agent 调用权限、模型白名单、附件能力和大小限制，前端开关不能越权。
+- Agent 协议响应不应包含 Agent 内部模型名。模型选择器只能读取 Agent 明确授权的 `/selectable-models` 目录。
 
 交付前确认：只加载一个完整版脚本；新页面以 `<dg-chat>` 为对话 UI；同页多实例隔离 `storageKey`；外部协议走服务端代理；页面离开时停止在途请求。
+
+## 移动端契约
+
+- `inline`、`floating`、`drawer`、`fullscreen` 四种 surface 均由 SDK 自适应窄屏；`threads`、`workspace` 和 Artifact 会按容器宽度自动收敛为单栏，不要复制 Shadow DOM 内部布局规则。
+- SDK 使用 `VisualViewport` 和 `safe-area-inset-*` 跟随软键盘、浏览器工具栏与横竖屏变化。触摸设备打开面板时不会主动弹出软键盘。
+- 触摸端按钮和行操作具有移动端点击尺寸，输入字号防止 iOS 自动缩放；所有内部滚动区隐藏滚动条，但仍保留触摸、滚轮和键盘滚动能力。

package/resources/skill/references/checkout.md

@@ -24,6 +24,8 @@ The checkout set includes `pages`, `navigations`, `docs/articles`, and `custom_s
 
 db_meta、AIHub、system_config、roles、users、doc_categories 和普通配置使用 MCP 实时 API，不 checkout。
 
+Checkout 只为已存在且已确认 ID 的资源建立本地正文与 base，不创建页面、导航或文档。新增资源先按 MCP 实时 API 契约创建并取得 ID；需要编辑完整正文时再 checkout。只需元数据或正文片段即可完成判断时，不必 checkout。
+
 ## 命令
 
 ```bash

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

@@ -181,6 +181,8 @@ draftgo.Log.Info("service completed")
 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{

package/resources/skill/references/frontend.md

@@ -79,12 +79,22 @@ version: 2.0.0
 - 系统内置页面通常不改；确需修改登录、设置、权限、用户、系统配置等页面时，先说明影响、验证方式和保留的管理员能力。
 - 页面风格不要照搬管理侧内置页面；业务前台按业务用户和品牌语境设计，管理侧按操作效率和信息密度设计。
 
-### 新增页面绑定（强制）
+### 页面身份与创建
+
+业务新页面默认是数据库中的完整 HTML 页面。开始正文工作前，结合用户表达与 MCP 中的标题、route、用途和入口判断目标：
+
+- 用户指定页面、ID、已有 route，或现有页面与需求职责明确一致时，按已有页面修改并 checkout 对应 ID。
+- 用户明确要求新增，或需求需要独立 route/职责且定向搜索后没有合适页面时，按新页面处理。通过 `draftgo_api_search` → `draftgo_api_describe` → `draftgo_api_call` 使用实时创建契约，取得新页面 ID 后再 checkout；完整 HTML 仍只走 checkout/commit。
+- “做一个功能页面”本身不等于新增，也不等于修改。证据足以形成唯一合理方案时 Agent 直接推进；若多个已有候选或新增/修改会产生明显不同的产品结果，再用一个简短问题澄清。
+
+搜索用于确认页面身份和避免重复，按标题、route 或业务用途逐步缩小范围即可，无需枚举无关资源。Checkout 应对应已确认的目标资源；新资源先创建并取得 ID。
+
+### 新增页面入口
 
 - 公开页 → 顶部/侧边导航、首页入口、相关按钮之一
 - 后台页 → 后台导航、管理菜单或现有后台入口
 - 多页面功能：列表/详情/新建/编辑/管理必须互相走通
-- 用户明确要求"隐藏页/草稿页"才可不绑定，并在 Task 记录原因；changelog 只记录最终完成结果
+- 隐藏页、回调页、按链接直达的详情页或草稿页可按产品目的不绑定全局入口；需要入口时优先接入现有导航或业务流程
 
 ### `page_1_root.html` 首页特例（强制）
 
@@ -138,7 +148,7 @@ version: 2.0.0
 - **壳层前端**位于 DraftGo 基座的 `frontend/`，技术栈为 React 19 + Vite 8 + Tailwind CSS 4；这是维护壳层代码时使用的构建链路。
 - **业务页面和导航 HTML**存储在数据库资源中，由壳层以 iframe 运行。它们必须是完整的原生 HTML 文档，不能写入 TSX、ESM import、npm 依赖或 Vite 构建产物。
 - 数据库页面需要 React 时，只能使用下方内置的 React 18 UMD 资源和 `window.React` / `window.ReactDOM`。不要把壳层的 React 19 npm 依赖、外部 CDN 或其他 React 版本混入页面。
-- 新建页面先确认是“壳层源码修改”还是“数据库 HTML 页面”。二者的组件、构建和资源加载方式不同，不能混用。
+- 只有用户明确要求修改 DraftGo 壳层前端时，才处理 `frontend/` 源码。
 
 ### 内置组件库清单
 

package/resources/skill/references/modules.md

@@ -8,7 +8,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 
 | 模块 | 开发方式 | 入口 |
 |---|---|---|
-| 页面 | 数据库 HTML（`page.value.html`） | MCP 定位，`checkout pages` / `commit pages` 编辑正文 |
+| 页面 | 数据库 HTML（`page.value.html`） | 已有页面由 MCP 定位后 `checkout pages` / `commit pages`；新页面先按实时 API 契约创建并取得 ID |
 | 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
 | 动态 DB | db_meta 定义 schema 并操作结构化记录 | MCP `api_search` / `api_describe` / `api_call` |
 | 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | MCP 实时 API；不创建本地镜像 |