draftgo-cli 3.0.35 → 3.0.39

package/resources/skill/references/data.md

@@ -267,9 +267,11 @@ await App.patch(`db/order/batch`, [
 
 ---
 
-## db_meta 本地文件
+## db_meta 实时契约
 
-开发前先读 `.draftgo/db_meta/index.json` 了解可用 type 和字段：
+db_meta 是结构化远端资源，不 checkout，也不生成本地 `index.json`。开发前先通过 MCP
+`draftgo_api_search` / `draftgo_api_describe` 确认接口，再用 `draftgo_api_call` 查询目标 type 和 schema。
+典型返回条目如下：
 
 ```json
 [

package/resources/skill/references/frontend.md

@@ -343,7 +343,7 @@ antd Modal：`width="min(90vw, 520px)"`；抽屉窄屏优先 `placement="bottom"
 
 ### 导航与系统页边界（强制）
 
-- 顶部导航已有内置资源时，通常先读 `.draftgo/navigations/index.json` 和对应 HTML；需要新导航时优先复制/复刻一份再改造，而不是直接改坏内置导航。
+- 顶部导航已有内置资源时，先通过 MCP 查询导航元数据；需要分析或编辑完整 HTML 时执行 `draftgo checkout nav <id>`，读取 worktree 文件。需要新导航时优先基于现有结构创建或复刻，而不是直接改坏内置导航。
 - 导航栏通常要同时考虑未登录 / 已登录 / 管理员三种状态，以及收起 / 展开状态；普通用户不显示管理后台入口，管理员额外显示管理后台入口。
 - 管理端侧边栏通常基于现有内置侧边栏修改，新增业务管理路由优先追加或局部调整；删除系统内置页面入口前先确认影响。
 - 业务页面内可以做局部二级导航或侧边栏，但必须考虑外部导航已存在且可单独配置，避免重复渲染全局导航。

package/resources/skill/references/mcp.md

@@ -0,0 +1,101 @@
+---
+read_when: 配置或诊断 DraftGo MCP 时 · 查询实时资源或 API 契约时 · 判断宿主支持范围时
+---
+
+# DraftGo MCP
+
+> 根 `SKILL.md` 在 Skill 触发时会自动加载。使用本文件前，先完成根 Skill 的“强制预读：Reference 优先于 MCP”任务路由。本文件只说明实时 MCP 的边界和调用顺序，不能替代页面、前端、运行时、安全或模块资料。
+
+## 边界
+
+DraftGo MCP 用于实时发现、结构化查询和普通 API 操作。完整 pages、navigations、docs/articles 正文不通过
+MCP tool result 或参数传输；需要全文时使用 `draftgo checkout`，提交时使用 `draftgo commit`。MCP 返回
+`artifact` / `omitted` 时保留该语义，不要尝试重新展开长内容。
+
+标准发现顺序：
+
+1. `draftgo_project_overview`
+2. `draftgo_resource_search` 或 `draftgo_resource_list`
+3. 按需调用 `draftgo_resource_get_metadata` 或 `draftgo_resource_read_fragment`
+4. 需要实时 API 契约时调用 `draftgo_api_search`、`draftgo_api_describe`
+5. 结构化资源读写使用 `draftgo_api_call`
+
+结构化资源包括 db_meta、AIHub、system_config、roles、users、doc_categories 和自定义服务元数据。
+这些资源不 checkout，也不生成 `.draftgo/*/index.json` 镜像。
+
+## CLI
+
+```bash
+draftgo mcp setup [target...]
+draftgo mcp status [target...]
+draftgo mcp test
+draftgo mcp serve
+```
+
+- `setup` 写入项目级宿主配置，只替换 `draftgo` MCP 条目并保留其他配置。
+- `status` 检查配置是否存在、格式是否有效，以及是否误写了凭据或远端 URL。
+- `test` 从 `.draftgo/config.json` 读取连接，验证 initialize、tools/list 和关键 tools/call。
+- `serve` 启动 stdio bridge，把宿主请求代理到当前项目配置的远端 Streamable HTTP `/mcp`。
+
+`draftgo connect` 保存并验证 server/SAT、探测 `/mcp` 和关键工具，并可提示宿主 setup；它不下载业务资源，
+也不创建 pages、navigation、docs、db_meta 等本地镜像。底座仍在开发或暂不可达时，报告诊断结果即可，
+不得回退到 `pull --all`。
+
+## 宿主配置
+
+| 宿主 | 项目配置 | MCP setup |
+|---|---|---|
+| Codex | `.codex/config.toml` | 支持 |
+| Claude Code | `.mcp.json` | 支持 |
+| Cursor | `.cursor/mcp.json` | 支持 |
+| Gemini CLI | `.gemini/settings.json` | 支持 |
+| Kiro | `.kiro/settings/mcp.json` | 支持 |
+| GitHub Copilot | `.vscode/mcp.json` | 支持 |
+| Windsurf | 无可靠的项目级适配 | 不支持，CLI 必须明确提示 |
+| Antigravity | 无可靠的项目级适配 | 不支持，CLI 必须明确提示 |
+
+Codex 配置：
+
+```toml
+[mcp_servers.draftgo]
+command = "draftgo"
+args = ["mcp", "serve"]
+```
+
+Claude Code、Cursor、Gemini CLI 和 Kiro 使用各自文件中的 `mcpServers`：
+
+```json
+{
+  "mcpServers": {
+    "draftgo": {
+      "command": "draftgo",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+GitHub Copilot 使用 `servers`，并声明 stdio：
+
+```json
+{
+  "servers": {
+    "draftgo": {
+      "type": "stdio",
+      "command": "draftgo",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+配置中不得出现 SAT、token、Authorization、headers、远端 `/mcp` URL、`env` 或带凭据的命令行。
+bridge 必须从当前工作目录的 `.draftgo/config.json` 读取 server/SAT。
+
+## 协议与安全
+
+- stdio 只输出 MCP JSON-RPC 帧；普通日志写入 stderr，且不得包含 SAT。
+- 代理 initialize、tools/list、tools/call、通知、取消、错误和流式响应，不改写底座 schema 或结构化错误。
+- HTTP 401/403、协议错误和工具缺失必须清晰失败；输出前对 SAT 和 Authorization 值做脱敏。
+- `.draftgo/config.json`、`.draftgo/worktree/` 和 `.draftgo/conflicts/` 必须加入 `.gitignore`。
+- MCP 不可用时运行 `draftgo mcp test` 收集证据；不要读取旧索引作为替代事实来源。

package/resources/skill/references/modules.md

@@ -8,13 +8,13 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 
 | 模块 | 开发方式 | 入口 |
 |---|---|---|
-| 页面 | 数据库 HTML（`page.value.html`） | `.draftgo/pages/` |
-| 导航栏 | 数据库 HTML（`navigation.html`） | `.draftgo/navigations/` |
-| 动态 DB | db_meta 定义 schema + `/api/db/{type}` 操作数据 | `.draftgo/db_meta/` |
-| 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | `.draftgo/custom_scripts/` |
-| AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | `.draftgo/aihub/` |
-| 文档中心 | Markdown 文章 + 分类树 | `.draftgo/docs/articles/` |
-| 系统配置 | KV 存储，含全局前端层槽位 | `.draftgo/system_config/` |
+| 页面 | 数据库 HTML（`page.value.html`） | MCP 定位，`checkout pages` / `commit pages` 编辑正文 |
+| 导航栏 | 数据库 HTML（`navigation.html`） | MCP 定位，`checkout nav` / `commit nav` 编辑正文 |
+| 动态 DB | db_meta 定义 schema + `/api/db/{type}` 操作数据 | MCP `api_search` / `api_describe` / `api_call` |
+| 自定义服务 | Go `Register` 服务，支持 route/event/scheduled 混合注册 | MCP 实时 API；不创建本地镜像 |
+| AIHub | 配置 AI Agent（模型/编排/能力/子智能体/记忆）；页面对话使用 `<dg-chat>`，图片模式使用 `DraftGoAI.images`；见 `references/chat-sdk.md` 与 `references/aihub.md` | MCP 实时 API；不创建本地镜像 |
+| 文档中心 | Markdown/HTML 文章 + 分类树 | 正文用 `checkout docs` / `commit docs`；分类用 MCP |
+| 系统配置 | KV 存储，含全局前端层槽位 | MCP 实时 API；不创建本地镜像 |
 
 ## 平台内置模块（开箱即用，不需实现）
 
@@ -56,7 +56,7 @@ read_when: 评估功能可行性时 · 选择开发路径时 · 进入新项目
 ## 自定义服务边界
 
 - 新服务使用 Go `Register(app *sdk.App)` 自动注册路由、事件和定时任务；完整语言、`draftgo` 和 SDK 契约见 `references/custom-services.md`。
-- `route`：对外暴露 HTTP 端点，运行时路径为 `/api/x/{slug}/{path}`；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，推送后要真实请求验证。
+- `route`：对外暴露 HTTP 端点，运行时路径为 `/api/x/{slug}/{path}`；同一 Go 服务可用多个 `app.Route(method, path, handler)` 注册多个端点，保存或发布后要真实请求验证。
 - `event`：响应平台事件，如 `db.created` / `db.updated` / `user.registered`；用 `app.On(event, handler)` 注册，可为同一事件注册多个 handler。
 - `scheduled`：用 `app.Schedule("分 时 日 月 周", handler)` 注册 cron；同一服务可声明多个定时 handler。
 - 新 Go 服务的 `Register` 是唯一触发器事实来源；旧 `triggers` 字段不参与注册。

package/resources/skill/references/parallel.md

@@ -37,12 +37,15 @@ delivery_owner: main
 2. 将 `depends` 已满足且 `resource_lock` 不冲突的工作单元放入同一 wave。
 3. 并行执行当前 wave，汇总后回读所有变更资源。
 4. 处理接口接线和入口绑定，再启动依赖已满足的下一 wave。
-5. 统一运行 `draftgo check`、必要的 API/UI 验证，并按交付意图执行批量推送。
+5. 统一运行 `draftgo check`、必要的 API/UI 验证；只对已 checkout 的 pages/nav/docs 执行 commit，结构化资源通过 MCP 实时 API 交付。
 
 某个工作单元失败时，其依赖项等待处理；其余独立分支继续汇总。发现资源锁冲突时，将冲突单元合并或移到后续 wave。
 
-批量交付示例：
+已 checkout 长正文的批量交付示例：
 
 ```bash
-draftgo auto-push --batch pages 1,2,3 nav 4 custom_scripts 7
+draftgo commit pages 1 2 3
+draftgo commit nav 4
 ```
+
+不同类型分开提交。发生 409/412 时当前 wave 必须停止并保留冲突材料，不得继续自动提交后续依赖项。

package/resources/skill/references/runtime.md

@@ -113,16 +113,13 @@ const orderId = query.orderId;  // "42"
 
 规则：**不能在业务页面内重复实现全局层能力；不允许新增槽位，只能编辑内置槽位。**
 
-### 修改和推送方法
+### 修改方法
 
-本地修改来自 `.draftgo/system_config/index.json`。修改前先执行 `/draftgo pull system_config` 获取最新值，改完后执行：
+system_config 是结构化远端资源。修改前通过 MCP `draftgo_api_search` / `draftgo_api_describe` 获取实时契约，
+再用 `draftgo_api_call` 读取并更新目标键；不要 checkout、pull 或维护本地索引。
 
-```bash
-python {{SKILL_SCRIPTS}}/draftgo_push.py system_config frontend_global_toast_opacity
-```
-
-也可以通过 skill 命令使用 `/draftgo push system_config frontend_global_toast_opacity`。
-
-前端全局层是系统默认配置。通过 API 或脚本更新现有全局配置时，只发送 `config_value`；不要带 `description`、`category`、`value_type`、`status` 等元信息，否则旧基座或旧索引容易触发“系统默认字段不允许修改字段描述/分类/状态”。`draftgo_push.py system_config` 已对 `frontend_global_*` 自动只推值。
+前端全局层是系统默认配置。更新现有全局配置时只发送 `config_value`；不要带 `description`、`category`、
+`value_type`、`status` 等元信息，避免触发“系统默认字段不允许修改字段描述/分类/状态”。
 
-页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中 `错误 Toast 时长(s) = 4.5`，本地索引应写 `frontend_global_toast_duration_error.config_value = 4500`。
+页面管理中 Toast 时长以秒输入，`sys_config` 中仍以毫秒存储。例如 UI 中
+`错误 Toast 时长(s) = 4.5` 对应 `frontend_global_toast_duration_error.config_value = 4500`。

package/resources/skill/scripts/README.md

@@ -0,0 +1,8 @@
+# Skill scripts
+
+DraftGo execution is provided by the installed `draftgo` CLI. Legacy Python pull, push, init, and delete helpers were
+removed because they depended on full local mirrors and bypassed the MCP plus checkout/commit safety model.
+
+Do not add a script that downloads `.draftgo/*/index.json`, embeds SAT credentials, sends full pages/nav/docs content
+through MCP, or retries version conflicts with force. Reusable helpers added here must preserve the workflows in
+`references/mcp.md` and `references/checkout.md`.

package/resources/skill/story/SKILL.md

@@ -93,9 +93,9 @@ now:
 ### 路径选择（先判断再走）
 
 ```
-扫描 .draftgo/ 下的数据，判断走哪条路径：
+通过 MCP 实时摘要和项目内可保留的决策记录判断走哪条路径：
 
-├─ 存在用户自建内容（非 tag="系统" 的页面、db_meta、custom_scripts）→ 路径 A
+├─ MCP 显示存在用户自建内容（非 tag="系统" 的页面、db_meta、custom_scripts）→ 路径 A
 ├─ 用户提供了设计文档（PRD、原型图描述、需求文档等）→ 路径 A（以文档为分析素材）
 └─ 只有内置系统页面，无用户自建内容，无设计文档 → 路径 B（对话采集）
 ```
@@ -105,11 +105,11 @@ now:
 ```
 输出：[ Story 文件生成中...正在分析项目 ]
 
-1. 扫描项目结构（以及用户提供的设计文档，如有）：
-   - .draftgo/pages/index.json → 现有页面（跳过 tag="系统" 的内置页）
-   - .draftgo/navigations/index.json → 导航结构
-   - .draftgo/db_meta/index.json → 数据模型
-   - .draftgo/custom_scripts/index.json → 自定义脚本
+1. 查询项目结构（以及读取用户提供的设计文档，如有）：
+   - MCP project_overview/resource_list → 资源总览
+   - MCP resource_search/get_metadata → 页面与导航元数据（跳过 tag="系统" 的内置页）
+   - MCP api_search/api_describe/api_call → db_meta 与自定义服务结构
+   - 只有必须分析完整 pages/nav/docs 正文时才 checkout；不要要求 MCP 返回全文
    - .draftgo/changelog.md → 更新日志
    - .draftgo/lessons/ → 开发经验记录
    - .draftgo/Task/ → 历史任务文档
@@ -248,7 +248,7 @@ AI 在开发过程中检测到"方向性决策"时，主动提议沉淀：
 ### 构建 Story
 
 1. 检查 `.draftgo/story.yaml` 是否存在
-2. 不存在 → 判断路径 A 还是 B（看 `.draftgo/pages/index.json` 是否有数据）
+2. 不存在 → 根据 MCP project_overview/resource_list 和用户提供的设计材料判断路径 A 还是 B
 3. 走对应构建流程
 4. 落盘 → 回到用户原始请求
 

package/src/cli.js

@@ -20,6 +20,11 @@ const VALUE_FLAGS = new Set([
   'delivery',
   'assignee',
   'assignee-id',
+  'timeout',
+  'operation-id',
+  'params',
+  'input',
+  'type',
 ]);
 
 function parse(argv) {

package/src/commandRegistry.js

@@ -10,7 +10,13 @@ const commands = [
   { name: 'map', run: (dir, _args, flags) => require('./commands/map')(dir, flags) },
   { name: 'check', run: (dir, _args, flags) => require('./commands/check')(dir, flags) },
   { name: 'verify-ui', aliases: ['verifyui'], run: (dir, args, flags) => require('./commands/verifyUi')(dir, args, flags) },
-  { name: 'api', run: (_dir, args, flags) => require('./commands/api')(args, flags) },
+  { name: 'mcp', run: (dir, args, flags) => require('./commands/mcp')(dir, args, flags) },
+  { name: 'checkout', run: (dir, args, flags) => require('./commands/checkout')(dir, args, flags) },
+  { name: 'commit', run: (dir, args, flags) => require('./commands/commit')(dir, args, flags) },
+  { name: 'diff', run: (dir, args, flags) => require('./commands/diff')(dir, args, flags) },
+  { name: 'conflicts', run: (dir, args, flags) => require('./commands/conflicts')(dir, args, flags) },
+  { name: 'conflict', run: (dir, args, flags) => require('./commands/conflict')(dir, args, flags) },
+  { name: 'api', run: (dir, args, flags) => require('./commands/api')(dir, args, flags) },
   { name: 'delete', aliases: ['del', 'rm'], run: (dir, args, flags) => require('./commands/delete')(dir, args, flags) },
   { name: 'deploy', run: (dir, args, flags) => require('./commands/deploy')(dir, args, flags) },
   { name: 'auto-push', aliases: ['autopush'], run: (dir, args, flags) => require('./commands/autoPush')(dir, args, flags) },

package/src/commands/api.js

@@ -1,203 +1,40 @@
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
 const log = require('../logger');
+const { loadProjectConfig } = require('../projectConfig');
+const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
 
-const API_FILE = path.resolve(__dirname, '..', '..', 'resources', 'skill', 'references', 'api.json');
-const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
-const AUTH_HEADER_NAMES = new Set(['authorization', 'proxy-authorization', 'x-api-key']);
-
-function resolveRef(spec, ref) {
-  if (!ref || !ref.startsWith('#/')) return null;
-  return ref.slice(2).split('/').reduce((value, part) => value && value[part], spec);
-}
-
-function schemaType(schema, spec) {
-  if (!schema || !Object.keys(schema).length) return 'unspecified';
-  if (schema.$ref) {
-    const target = resolveRef(spec, schema.$ref);
-    return target && (target.title || schema.$ref.split('/').pop()) || schema.$ref;
-  }
-  if (schema.anyOf) return schema.anyOf.map((item) => schemaType(item, spec)).join(' | ');
-  if (schema.oneOf) return schema.oneOf.map((item) => schemaType(item, spec)).join(' | ');
-  if (schema.allOf) return schema.allOf.map((item) => schemaType(item, spec)).join(' & ');
-  if (schema.type === 'array') return `${schemaType(schema.items, spec)}[]`;
-  if (schema.type) return schema.format ? `${schema.type} (${schema.format})` : schema.type;
-  if (schema.properties) return 'object';
-  return 'unspecified';
-}
-
-function schemaNotes(schema) {
-  const notes = [];
-  if (schema.description) notes.push(schema.description);
-  if (schema.default !== undefined) notes.push(`default: ${JSON.stringify(schema.default)}`);
-  if (schema.enum) notes.push(`enum: ${schema.enum.map((item) => JSON.stringify(item)).join(', ')}`);
-  return notes.length ? ` (${notes.join('; ')})` : '';
-}
-
-function printSchema(schema, spec, indent = '      ', seen = new Set()) {
-  if (!schema || !Object.keys(schema).length) {
-    console.log(`${indent}schema: unspecified`);
-    return;
-  }
-
-  let resolved = schema;
-  let refName = '';
-  if (schema.$ref) {
-    refName = schema.$ref.split('/').pop();
-    if (seen.has(schema.$ref)) {
-      console.log(`${indent}${refName} (recursive)`);
-      return;
-    }
-    resolved = resolveRef(spec, schema.$ref) || schema;
-    seen = new Set(seen).add(schema.$ref);
-  }
-
-  console.log(`${indent}schema: ${refName ? `${refName} (${schemaType(resolved, spec)})` : schemaType(resolved, spec)}${schemaNotes(resolved)}`);
-  const variants = resolved.anyOf || resolved.oneOf || resolved.allOf;
-  if (variants) {
-    variants.forEach((variant, index) => {
-      console.log(`${indent}  variant ${index + 1}:`);
-      printSchema(variant, spec, `${indent}    `, seen);
-    });
+function printResult(title, result) {
+  log.title(title);
+  if (Array.isArray(result)) {
+    for (const item of result) log.plain(`  ${JSON.stringify(item)}`);
     return;
   }
-  const required = new Set(resolved.required || []);
-  for (const [name, property] of Object.entries(resolved.properties || {})) {
-    const fieldSchema = property.$ref ? resolveRef(spec, property.$ref) || property : property;
-    const marker = required.has(name) ? ' required' : ' optional';
-    console.log(`${indent}  ${name}: ${schemaType(property, spec)}${marker}${schemaNotes(fieldSchema)}`);
-  }
-  if (resolved.additionalProperties === true) console.log(`${indent}  additional properties: allowed`);
-  if (resolved.items && !resolved.properties) printSchema(resolved.items, spec, `${indent}  `, seen);
-}
-
-function authenticationFor(operation, spec) {
-  const security = operation.security === undefined ? spec.security : operation.security;
-  const schemes = (security || []).flatMap((requirement) => Object.keys(requirement).map((name) => {
-    const definition = spec.components && spec.components.securitySchemes && spec.components.securitySchemes[name] || {};
-    return { name, type: definition.type || 'unknown', scheme: definition.scheme, bearerFormat: definition.bearerFormat };
-  }));
-  const headers = (operation.parameters || []).filter((parameter) =>
-    parameter.in === 'header' && AUTH_HEADER_NAMES.has(String(parameter.name).toLowerCase())
-  );
-  return { schemes, headers };
-}
-
-function printAuthentication(operation, spec) {
-  const auth = authenticationFor(operation, spec);
-  if (!auth.schemes.length && !auth.headers.length) {
-    console.log('  Authentication: no requirement declared in the bundled OpenAPI.');
+  if (result && Array.isArray(result.items)) {
+    for (const item of result.items) log.plain(`  ${JSON.stringify(item)}`);
     return;
   }
-  console.log('  Authentication:');
-  for (const scheme of auth.schemes) {
-    const detail = [scheme.type, scheme.scheme, scheme.bearerFormat].filter(Boolean).join(', ');
-    console.log(`    security scheme ${scheme.name}${detail ? ` (${detail})` : ''}`);
-  }
-  for (const header of auth.headers) {
-    console.log(`    header ${header.name}: ${schemaType(header.schema, spec)}${header.required ? ' (required)' : ' (optional)'}${schemaNotes(header)}`);
-  }
-}
-
-function printOperation(item, spec) {
-  console.log(`\n${item.method} ${item.route}${item.summary ? `  ${item.summary}` : ''}`);
-  if (item.operationId) console.log(`  Operation: ${item.operationId}`);
-  printAuthentication(item.operation, spec);
-
-  const parameters = (item.operation.parameters || []).filter((parameter) =>
-    !(parameter.in === 'header' && AUTH_HEADER_NAMES.has(String(parameter.name).toLowerCase()))
-  );
-  if (parameters.length) {
-    console.log('  Parameters:');
-    for (const parameter of parameters) {
-      console.log(`    ${parameter.in} ${parameter.name}: ${schemaType(parameter.schema, spec)}${parameter.required ? ' (required)' : ' (optional)'}${schemaNotes(parameter)}`);
-    }
-  }
-
-  if (item.operation.requestBody) {
-    console.log(`  Request body: ${item.operation.requestBody.required ? 'required' : 'optional'}`);
-    for (const [contentType, media] of Object.entries(item.operation.requestBody.content || {})) {
-      console.log(`    ${contentType}:`);
-      printSchema(media.schema, spec, '      ');
-    }
-  }
-
-  const responses = Object.entries(item.operation.responses || {});
-  if (responses.length) {
-    console.log('  Responses:');
-    for (const [status, response] of responses) {
-      console.log(`    ${status}${response.description ? ` ${response.description}` : ''}`);
-      for (const [contentType, media] of Object.entries(response.content || {})) {
-        console.log(`      ${contentType}:`);
-        printSchema(media.schema, spec, '        ');
-      }
-    }
-  }
+  console.log(JSON.stringify(result, null, 2));
 }
 
-function apiCommand(positional, flags = {}) {
-  const keyword = String(positional.join(' ') || '').trim().toLowerCase();
-  if (!keyword) {
-    log.err('用法：draftgo api <keyword>');
-    log.dim('  示例：draftgo api pages batch');
+async function apiCommand(projectDir, positional, flags = {}) {
+  const first = String(positional[0] || '').toLowerCase();
+  const describe = first === 'describe';
+  const queryParts = first === 'search' || describe ? positional.slice(1) : positional;
+  const query = queryParts.join(' ').trim();
+  if (!query) {
+    log.err('Usage: draftgo api <query> | draftgo api search <query> | draftgo api describe <operation_id>');
     return 1;
   }
 
-  let spec;
-  try {
-    spec = JSON.parse(fs.readFileSync(API_FILE, 'utf8'));
-  } catch (err) {
-    log.err(`无法读取 OpenAPI：${err.message}`);
-    return 1;
-  }
-
-  const words = keyword.split(/\s+/).filter(Boolean);
-  const matches = [];
-  for (const [route, methods] of Object.entries(spec.paths || {})) {
-    for (const [method, operation] of Object.entries(methods || {})) {
-      if (!HTTP_METHODS.has(method.toLowerCase())) continue;
-      const haystack = [route, method, operation.summary, operation.operationId, ...(operation.tags || [])]
-        .filter(Boolean).join(' ').toLowerCase();
-      if (!words.every((word) => haystack.includes(word))) continue;
-      matches.push({
-        method: method.toUpperCase(),
-        route,
-        summary: operation.summary || '',
-        operationId: operation.operationId || '',
-        tags: operation.tags || [],
-        operation,
-      });
-    }
-  }
-
-  if (flags.output === 'json') {
-    console.log(JSON.stringify({
-      source: {
-        kind: 'DraftGo bundled base OpenAPI',
-        openapi: spec.openapi || null,
-        version: spec.info && spec.info.version || null,
-        customServiceRoutes: {
-          included: false,
-          reason: 'Custom service routes are registered dynamically from local app.Route calls.',
-          derive: '<METHOD> /api/x/<slug><route-path>',
-        },
-      },
-      query: keyword,
-      matches,
-    }, null, 2));
-    return matches.length ? 0 : 1;
-  }
-  if (!matches.length) {
-    log.warn(`未找到包含“${keyword}”的 API。`);
-    return 1;
-  }
-  log.title(`DraftGo base API — ${keyword}`);
-  log.dim(`Source: bundled DraftGo base OpenAPI v${spec.info && spec.info.version || 'unknown'}; these are platform APIs, not project-defined APIs.`);
-  log.dim('Custom service routes are not indexed here: derive them from local app.Route calls as <METHOD> /api/x/<slug><route-path>.');
-  for (const item of matches.slice(0, 50)) printOperation(item, spec);
-  if (matches.length > 50) log.dim(`\nOnly the first 50 of ${matches.length} matches are shown; use --output json for all contracts.`);
+  const config = loadProjectConfig(projectDir);
+  const expected = describe ? TOOL_NAMES.apiDescribe : TOOL_NAMES.apiSearch;
+  const session = await openToolSession(config, [expected]);
+  const result = await callStructured(session, expected, describe
+    ? { operation_id: query }
+    : { query });
+  if (flags.output === 'json') console.log(JSON.stringify(result, null, 2));
+  else printResult(describe ? `DraftGo API ${query}` : `DraftGo API search: ${query}`, result);
   return 0;
 }
 

package/src/commands/autoPush.js

@@ -1,41 +1,72 @@
 'use strict';
 
 const fs = require('fs');
-const path = require('path');
 const log = require('../logger');
 const check = require('./check');
-const sync = require('./sync');
+const { loadProjectConfig } = require('../projectConfig');
+const { loadManifest, absolutePath } = require('../worktree/manifest');
+const { hashFile } = require('../worktree/streams');
+const { listConflicts, commitResources } = require('../worktree');
 
-function autoPush(projectDir, positional, flags = {}) {
-  const configPath = path.join(projectDir, '.draftgo', 'config.json');
-  if (!fs.existsSync(configPath)) {
-    log.dim('自动推送未执行：未连接 DraftGo 服务器（缺少 .draftgo/config.json）。');
-    return 0;
+async function changedEntries(projectDir, manifest) {
+  const changed = [];
+  for (const entry of Object.values(manifest.entries)) {
+    const local = absolutePath(projectDir, entry.local_path);
+    if (!fs.existsSync(local)) continue;
+    if ((await hashFile(local)).hash !== entry.base_hash) changed.push(entry);
   }
+  return changed;
+}
 
+async function autoPush(projectDir, positional, flags = {}) {
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-  } catch (err) {
-    log.err(`自动推送未执行：config.json 解析失败：${err.message}`);
+    config = loadProjectConfig(projectDir);
+  } catch {
+    log.dim('auto-push skipped: this project is not connected to DraftGo.');
+    return 0;
+  }
+
+  if (config.auto_push !== true) {
+    log.dim('auto-push skipped: .draftgo/config.json does not set auto_push to true.');
+    return 0;
+  }
+  const conflicts = listConflicts(projectDir);
+  if (conflicts.length) {
+    log.err(`auto-push stopped: ${conflicts.length} unresolved DraftGo conflict(s).`);
     return 1;
   }
 
-  log.step('auto-push: 先执行 check …');
   const checkCode = check(projectDir, { strict: flags.strict });
   if (checkCode !== 0) {
-    log.err('自动推送终止：check 未通过，请修复后重试。');
+    log.err('auto-push stopped because local validation failed.');
     return checkCode;
   }
 
-  if (config.auto_push !== true) {
-    log.dim('自动推送已跳过：check 已通过，但 .draftgo/config.json 的 auto_push 不为 true。');
+  const groups = new Map();
+  if (positional.length) {
+    const [resourceType, ...ids] = positional;
+    if (!resourceType || !ids.length) {
+      log.err('Usage: draftgo auto-push [<pages|nav|docs> <id...>]');
+      return 1;
+    }
+    groups.set(resourceType, ids);
+  } else {
+    for (const entry of await changedEntries(projectDir, loadManifest(projectDir))) {
+      if (!groups.has(entry.resource_type)) groups.set(entry.resource_type, []);
+      groups.get(entry.resource_type).push(entry.resource_id);
+    }
+  }
+  if (!groups.size) {
+    log.dim('auto-push: no checked-out content changed.');
     return 0;
   }
 
-  log.step('auto_push=true：开始 push …');
-  const pushArgs = flags.batch ? ['--batch', ...positional] : positional;
-  return sync(projectDir, 'push', pushArgs, flags);
+  for (const [resourceType, ids] of groups) {
+    await commitResources(projectDir, resourceType, ids, { config });
+  }
+  log.ok('auto-push committed all changed checked-out content.');
+  return 0;
 }
 
 module.exports = autoPush;