draftgo-cli 3.0.29 → 3.0.35

package/resources/skill/story/SKILL.md

@@ -1,16 +1,11 @@
 ---
 name: draftgo-story
-description: "Use this skill to build, load, evolve, or conflict-check the project's Story file (.draftgo/story.yaml). Required for high-risk development tasks when story.yaml is missing, and used whenever a development decision conflicts with the existing Story."
-version: 1.0.0
-allowed-tools: Read, Write, Glob, Bash(find:*)
+description: "Use this skill to build, load, evolve, or conflict-check the project's Story file (.draftgo/story.yaml). Use it when the user requests product-story work, when an existing Story conflicts with a requested product decision, or when preserving a durable product decision is valuable."
 ---
 
 # DraftGo Story System
 
-> **Story 是系统的灵魂档案。高风险开发必须先确认 Story 存在；功能开发若 Story 已存在则静默加载，小修不强制触发 Story。**
->
-> Story 不是文档，不是规范，是创作者对"这个系统是什么、为什么存在、不做什么"的持续叙述。
-> 文件只是理解的副产品。
+> Story 记录产品身份、设计总述、长期决策和当前方向。项目已有 Story 且请求触及定位或既有决策时加载；用户要求或形成需要长期保留的产品决策时创建或更新。
 
 ---
 
@@ -18,11 +13,11 @@ allowed-tools: Read, Write, Glob, Bash(find:*)
 
 | 原则 | 含义 |
 |------|------|
-| Gate, not Doc | 高风险任务没有 Story 就不开发；普通功能把 Story 作为上下文而不是阻塞器 |
+| Decision record | 记录会影响后续取舍的产品定位与决策 |
 | AI 维护，人确认 | 开发者只聊天，AI 负责提炼和写入 |
 | 三层结构 | 身份(稳) → 决策(只增) → 当前(频变) |
 | 决策日志最值钱 | 取舍依据是代码永远表达不了的信息 |
-| 工具无关 | yaml 文件谁都能读，不绑定任何 AI 生态 |
+| 工具无关 | 使用可移植的 YAML 文件 |
 
 ---
 
@@ -43,7 +38,7 @@ identity:
   what: "一句话讲清这是什么，不超过 30 字"
   why: |
     解决什么具体痛点，给谁用。
-    两三句话，要有画面感，不要空话。
+    用两三句具体描述说明使用者和场景。
   not:
     - "不是 XX"
     - "不变成 YY"
@@ -71,7 +66,7 @@ decisions:
 # === 第四层：当前方向（频繁更新）===
 now:
   focus: "当前阶段在做什么"
-  next: "下一步大致方向（粗粒度，不是 TODO）"
+  next: "下一步的大致方向"
   open_questions:
     - "还没想清楚的事"
 ```
@@ -81,12 +76,12 @@ now:
 ## 触发协议
 
 ```
-任何开发对话开始时：
+需要 Story 时：
 
 1. 静默检查 .draftgo/story.yaml
 2. 分流：
-   ├─ 不存在            → 进入「构建流程」，暂存开发请求
-   ├─ maturity = seed   → 加载 + 提示"Story 还稚嫩，开发中会持续补充"
+   ├─ 不存在            → 用户要求创建或需要沉淀关键决策时，进入「构建流程」
+   ├─ maturity = seed   → 加载并把不确定项作为后续判断背景
    └─ growing / stable  → 静默加载，直接开始
 3. 整个对话期间，Story 作为最高优先级上下文锚定
 ```
@@ -141,9 +136,9 @@ now:
 ```
 输出：[ 检测到全新项目，先聊一下你想做什么 ]
 
-对话式采集（不是问卷，是聊天，问到够用就停）：
+通过简短对话采集，信息足够后即进入提炼：
 
-Q1: 这个系统整体是干嘛的？（存在的理由，不是功能列表）
+Q1: 这个系统的整体定位和存在理由是什么？
 Q2: 谁会用它？什么场景下用？
 Q3: 类似的东西可能有哪些？你想做出什么不同？
 Q4: 大致有哪些模块/功能块？它们之间怎么串起来？

package/src/cli.js

@@ -24,7 +24,7 @@ const VALUE_FLAGS = new Set([
 
 function parse(argv) {
   const args = argv.slice();
-  const out = { command: null, positional: [], flags: {} };
+  const out = { command: null, positional: [], flags: {}, errors: [] };
   while (args.length) {
     const a = args.shift();
     if (a === '--') { out.positional.push(...args); break; }
@@ -32,16 +32,22 @@ function parse(argv) {
       const raw = a.slice(2);
       const eq = raw.indexOf('=');
       if (eq >= 0) {
-        out.flags[raw.slice(0, eq)] = raw.slice(eq + 1);
+        const key = raw.slice(0, eq);
+        const value = raw.slice(eq + 1);
+        if (VALUE_FLAGS.has(key) && !value) {
+          out.errors.push(`选项 --${key} 需要一个值。`);
+        } else {
+          out.flags[key] = value;
+        }
       } else {
         const next = args[0];
-        if (next !== undefined && !next.startsWith('-')) {
-          // Only consume next token as value for a known set of flags.
-          if (VALUE_FLAGS.has(raw)) {
+        if (VALUE_FLAGS.has(raw)) {
+          // A declared value flag must never silently become boolean true.
+          if (next === undefined || next === '--' || next.startsWith('--')) {
+            out.errors.push(`选项 --${raw} 需要一个值。`);
+          } else {
             out.flags[raw] = next;
             args.shift();
-          } else {
-            out.flags[raw] = true;
           }
         } else {
           out.flags[raw] = true;

package/src/commandRegistry.js

@@ -0,0 +1,34 @@
+'use strict';
+
+// Keep command names, aliases, and dispatch behavior in one place. This avoids
+// aliases silently drifting away from the implementation as the CLI grows.
+const commands = [
+  { name: 'init', run: (dir, args, flags) => require('./commands/init')(dir, args, flags) },
+  { name: 'update', run: (dir, args, flags) => require('./commands/update')(dir, args, flags) },
+  { name: 'uninstall', aliases: ['remove'], run: (dir, args, flags) => require('./commands/uninstall')(dir, args, flags) },
+  { name: 'status', run: (dir) => require('./commands/status')(dir) },
+  { 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: '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) },
+  { name: 'pull', run: (dir, args, flags) => require('./commands/sync')(dir, 'pull', args, flags) },
+  { name: 'push', run: (dir, args, flags) => require('./commands/sync')(dir, 'push', args, flags) },
+  { name: 'local', run: (dir, args, flags) => require('./commands/local')(dir, args, flags) },
+  { name: 'list-targets', aliases: ['targets'], run: () => require('./commands/listTargets')() },
+  { name: 'local-dev', aliases: ['localdev'], run: (dir, args, flags) => require('./commands/localDev')(dir, args, flags) },
+  { name: 'connect', aliases: ['login'], run: (dir, args, flags) => require('./commands/connect')(dir, args, flags) },
+];
+
+const aliases = new Map();
+for (const command of commands) {
+  for (const alias of [command.name, ...(command.aliases || [])]) aliases.set(alias, command);
+}
+
+function resolveCommand(name) {
+  return aliases.get(name);
+}
+
+module.exports = { commands, resolveCommand };

package/src/commands/api.js

@@ -4,7 +4,138 @@ const fs = require('fs');
 const path = require('path');
 const log = require('../logger');
 
-const API_FILE = path.resolve(__dirname, '..', '..', 'resources', 'skill', 'quickref', 'api.json');
+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);
+    });
+    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.');
+    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, '        ');
+      }
+    }
+  }
+}
 
 function apiCommand(positional, flags = {}) {
   const keyword = String(positional.join(' ') || '').trim().toLowerCase();
@@ -26,7 +157,7 @@ function apiCommand(positional, flags = {}) {
   const matches = [];
   for (const [route, methods] of Object.entries(spec.paths || {})) {
     for (const [method, operation] of Object.entries(methods || {})) {
-      if (!['get', 'post', 'put', 'patch', 'delete', 'head', 'options'].includes(method.toLowerCase())) continue;
+      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;
@@ -36,23 +167,37 @@ function apiCommand(positional, flags = {}) {
         summary: operation.summary || '',
         operationId: operation.operationId || '',
         tags: operation.tags || [],
+        operation,
       });
     }
   }
 
   if (flags.output === 'json') {
-    console.log(JSON.stringify(matches, null, 2));
+    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 api — ${keyword}`);
-  for (const item of matches.slice(0, 50)) {
-    console.log(`  ${item.method.padEnd(7)} ${item.route}${item.summary ? `  ${item.summary}` : ''}`);
-  }
-  if (matches.length > 50) log.dim(`  仅显示前 50 条，共 ${matches.length} 条；使用 --output json 获取完整结果。`);
+  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.`);
   return 0;
 }
 

package/src/commands/help.js

@@ -14,32 +14,25 @@ The CLI is the workbench layer for local runtime, resource sync, checks, and pus
 Usage:
   draftgo init [<target>...]       Install skill. No target = auto-detect.
                                     Use "all" to install every target.
-  draftgo update [<target>...]     Atomically update skill + entry files.
-                                    Reports newer CLI versions without
-                                    modifying the global installation.
+  draftgo update [<target>...]     Fully update the global CLI, then atomically
+                                    refresh skill + entry files.
   draftgo uninstall <target|all>   Remove entry files for target(s).
                                     Use explicit "all" to remove every target.
                                     --purge also removes .draftgo/ (runtime data).
   draftgo status                   Show installed targets and skill version.
-  draftgo doctor                   Diagnose environment (python, targets,
-                                    CLI freshness).
-  draftgo upgrade                  Explicitly upgrade the global CLI, then
-                                    refresh installed skill files.
   draftgo map                      Print a local DraftGo project resource map
                                     for fast AI orientation.
-  draftgo check                    Check local resource closure: routes,
-                                    entry binding, files, mock/color risks.
+  draftgo check                    Check page entry binding, page/navigation
+                                    HTML parsing, and unregistered local files.
   draftgo verify-ui <url>          Run a deterministic browser smoke check.
                                     Uses one viewport and screenshots on failure.
-  draftgo api <keyword>            Search the bundled OpenAPI specification.
-  draftgo dev                      Run this project's npm dev script.
-  draftgo build                    Run this project's npm build script.
-  draftgo new <type> <slug>        Scaffold a new resource locally (no network).
-                                    Creates template file + index.json entry.
-                                    Types: page | nav | db_meta | script | doc
+  draftgo api <keyword>            Search DraftGo base APIs and show request/
+                                    response/authentication contracts.
+                                    Custom service routes come from app.Route;
+                                    they are not part of the bundled OpenAPI.
   draftgo delete <type> <id>       Delete resource from server + local index.
                                     Types: pages | nav | db_meta | custom_scripts
-                                           | docs | doc_categories
+                                           | docs | doc_categories | aihub
                                     Alias: del, rm. Flags: --yes / -y skip confirm.
   draftgo pull [type] [id...]      Pull DraftGo resources via the bundled
                                     sync script. Defaults to --all.
@@ -50,24 +43,27 @@ Usage:
   draftgo auto-push [type] [id...] Run check, then push only when
                                     config.auto_push is true.
                                     Supports --batch <type> <ids> ... too.
-  draftgo local up|down|logs|status
+  draftgo local setup|start|stop|logs|status
                                     Manage .draftgo/docker/docker-compose.yaml
-                                    generated by draftgo local-dev.
+                                    generated by local setup. up/down remain
+                                    compatible aliases for start/stop.
   draftgo list-targets             List supported AI tools.
   draftgo connect                  Bind this project to an existing DraftGo
                                     server. Prompts for BaseURL + access
                                     token (or pass --server / --token).
-  draftgo local-dev                One-click local DraftGo stack via Docker
-                                    (MySQL + Redis + app). Generates
-                                    <project>/.draftgo/docker/docker-compose.yaml
-                                    with random secrets, then guides you to
-                                    finish setup and paste an access token.
+  draftgo local setup              One-click local DraftGo stack via Docker
+                                    (shared MySQL, Redis, Milvus + app). It
+                                    generates an app-only project compose,
+                                    <project>/.draftgo/docker/docker-compose.yaml,
+                                    then guides you to finish setup and paste
+                                    an access token.
+  draftgo local-dev                Compatibility alias for \`draftgo local setup\`.
   draftgo -v | --version           Print CLI version.
   draftgo -h | --help              Show this help.
 
 v3 Workbench:
-  draftgo local up|down|logs       Local stack lifecycle commands.
-  draftgo dev|build|check          Project workflow gates.
+  draftgo local start|stop|logs    Local stack lifecycle commands.
+  draftgo check                    Local resource closure gate.
   draftgo pull|push                First-class resource sync wrappers.
 
 Flags:
@@ -77,7 +73,7 @@ Flags:
   --skip-update-check      Do not contact npm to check for a newer CLI.
   --yes                    Assume "yes" for interactive prompts.
   --connect                (init) Skip the prompt and run \`draftgo connect\`.
-  --local-dev              (init) Skip the prompt and run \`draftgo local-dev\`.
+  --local-dev              (init) Skip the prompt and run \`draftgo local setup\`.
   --no-setup               (init) Don't offer either flow after installing.
   --server <url>           (connect) Provide the DraftGo BaseURL non-interactively.
   --token <sat>            (connect) Provide the access token non-interactively.
@@ -101,10 +97,9 @@ Examples:
   draftgo init claudecode      # install for Claude Code only
   draftgo init claudecode kiro # install for both
   draftgo init all             # install for every supported target
-  draftgo update               # refresh skill and report newer CLI versions
-  draftgo upgrade              # explicitly upgrade CLI and refresh skill
+  draftgo update               # fully update CLI and installed skills
   draftgo map                  # inspect pages/nav/db/scripts before development
-  draftgo check --strict       # fail on closure warnings before push
+  draftgo check --strict       # fail on any resource-check warning before push
   draftgo verify-ui http://localhost:5173 --mobile-check auto
   draftgo uninstall all --purge # full removal incl. runtime data
 `);

package/src/commands/init.js

@@ -12,8 +12,8 @@ const { ask } = require('../prompt');
 function warnIfNoPython() {
   const py = findPython();
   if (!py) {
-    log.warn('Python 未检测到。DraftGo 的 init/sync 脚本需要 Python 3.9+。');
-    log.dim('  请安装 Python 3.9+ 后再运行 /draftgo init 子技能。');
+    log.warn('Python 未检测到。DraftGo 资源同步需要 Python 3.9+。');
+    log.dim('  安装 Python 3.9+ 后运行 `draftgo pull` 获取项目资源。');
   } else {
     log.dim(`  detected ${py.bin} (${py.version})`);
   }
@@ -47,7 +47,7 @@ async function init(projectDir, positional, flags) {
 
   // 2) Render skill body into each target's own directory (no shared
   //    .draftgo/skill/ indirection anymore — each AI tool gets a real copy).
-  log.step('写入各 AI 工具 skill 目录（含 SKILL.md / 子技能 / rules / scripts）');
+  log.step('写入各 AI 工具 skill 目录（含 SKILL.md / 子技能 / references / scripts）');
   ensureRuntime(projectDir);
   const failures = [];
   let installedCount = 0;
@@ -101,29 +101,28 @@ async function init(projectDir, positional, flags) {
       return await require('./localDev')(projectDir, [], flags);
     }
     if (interactive) {
-      log.title('未检测到 DraftGo 服务器配置');
-      log.plain('选择一种方式完成绑定：');
-      log.plain(`  ${log.c.cyan('[1]')} 连接已有 DraftGo 服务器  ${log.c.gray('（输入 BaseURL + 系统访问令牌）')}`);
-      log.plain(`  ${log.c.cyan('[2]')} 进入本地开发模式          ${log.c.gray('（没部署基座，用 Docker 一键启动）')}`);
-      log.plain(`  ${log.c.cyan('[3]')} 稍后再说`);
-      const choice = (await ask('请选择 [1/2/3]', { default: '1' })).trim();
-      if (choice === '1') {
+      log.title('选择 DraftGo 基座处理方式');
+      log.plain(`  ${log.c.cyan('[A]')} 连接基座服务`);
+      log.dim('      使用已有 DraftGo 服务，接下来输入 BaseURL 和系统访问令牌。');
+      log.plain(`  ${log.c.cyan('[B]')} 本地启动基座`);
+      log.dim('      使用 Docker 启动 DraftGo；按需准备共享的 MySQL、Redis 和 Milvus。');
+      log.plain(`  ${log.c.cyan('[C]')} 稍后自行处理`);
+      log.dim('      仅安装 Skill，不写入服务配置，也不创建容器。');
+      const choice = (await ask('请选择 [A/B/C]', { default: 'C' })).trim().toUpperCase();
+      if (choice === 'A') {
         return await require('./connect')(projectDir, [], flags);
       }
-      if (choice === '2') {
-        return await require('./localDev')(projectDir, [], flags);
+      if (choice === 'B') {
+        return await require('./localDev')(projectDir, [], { ...flags, yes: true });
       }
-      if (choice !== '3') {
-        log.warn('Invalid choice; skipped server setup. Run `draftgo connect` or `draftgo local-dev` later.');
+      if (choice !== 'C') {
+        log.warn('无效选择，已跳过基座处理。');
       }
     }
   }
 
   log.title('完成');
-  log.plain('下一步：在你的 AI 工具里说「初始化 draftgo 项目」，它会引导你配置服务器和 token。');
-  log.dim('或直接运行：');
-  log.dim('  draftgo connect              # 连接已有 DraftGo 服务器');
-  log.dim('  draftgo local-dev            # 本地一键部署 DraftGo');
+  log.plain(hasConfig ? 'Skill 已安装，项目已连接 DraftGo。' : 'Skill 已安装。');
   return 0;
 }
 

package/src/commands/local.js

@@ -5,6 +5,7 @@ const { spawnSync } = require('child_process');
 const log = require('../logger');
 const { exists } = require('../fsx');
 const { detectDocker } = require('../localdev/detect');
+const { runWizard } = require('../localdev');
 
 function composeFile(projectDir) {
   return path.join(projectDir, '.draftgo', 'docker', 'docker-compose.yaml');
@@ -22,7 +23,7 @@ function runCompose(projectDir, args, stdio = 'inherit') {
   const file = composeFile(projectDir);
   if (!exists(file)) {
     log.err('未找到 .draftgo/docker/docker-compose.yaml。');
-    log.dim('  请先运行 `draftgo local-dev` 生成本地 DraftGo stack。');
+    log.dim('  请先运行 `draftgo local setup` 生成本地 DraftGo stack。');
     return 1;
   }
 
@@ -34,13 +35,17 @@ function runCompose(projectDir, args, stdio = 'inherit') {
   return r.status || 0;
 }
 
-function local(projectDir, positional) {
+function local(projectDir, positional, flags = {}) {
   const action = positional[0] || 'status';
 
   switch (action) {
+    case 'setup':
+      return runWizard(projectDir, { yes: !!(flags.yes || flags.y) });
     case 'up':
+    case 'start':
       return runCompose(projectDir, ['up', '-d']);
     case 'down':
+    case 'stop':
       return runCompose(projectDir, ['down']);
     case 'logs':
       return runCompose(projectDir, ['logs', ...(positional.slice(1).length ? positional.slice(1) : ['-f', 'app'])]);
@@ -49,7 +54,8 @@ function local(projectDir, positional) {
       return runCompose(projectDir, ['ps']);
     default:
       log.err(`未知 local 子命令：${action}`);
-      log.dim('  可用：draftgo local up | down | logs | status');
+      log.dim('  可用：draftgo local setup | start | stop | logs | status');
+      log.dim('  兼容别名：up | down');
       return 1;
   }
 }

package/src/commands/sync.js

@@ -35,7 +35,7 @@ function sync(projectDir, command, positional, flags = {}) {
 
   if (!exists(path.join(projectDir, '.draftgo', 'config.json'))) {
     log.err('未找到 .draftgo/config.json。');
-    log.dim('  请先运行 `draftgo connect` 或 `/draftgo init`。');
+    log.dim('  请先运行 `draftgo connect`。');
     return 1;
   }
 

package/src/commands/update.js

@@ -1,35 +1,63 @@
 'use strict';
 
+const { spawnSync } = require('child_process');
 const log = require('../logger');
 const { all, byName, resolveTargets } = require('../installers');
 const { ensureRuntime, writeInstalledVersion, readInstalledVersion, getPackageVersion } = require('../skill');
 const { fetchLatestVersion, cmpSemver } = require('../updateCheck');
 const { detectTargets } = require('../detect');
 
-async function reportAvailableUpgrade(flags) {
-  if (flags['skip-update-check'] || process.env.DRAFTGO_NO_UPDATE_CHECK === '1') return;
+const REENTRY_FLAG = 'DRAFTGO_UPDATE_REENTERED';
+
+async function updateCliIfNeeded(projectDir, positional, flags) {
+  if (process.env[REENTRY_FLAG] === '1' || flags['skip-update-check'] || process.env.DRAFTGO_NO_UPDATE_CHECK === '1') {
+    return null;
+  }
   const current = getPackageVersion();
-  const latest = await fetchLatestVersion();
+  const latest = await fetchLatestVersion(5000, { force: true });
   if (!latest) {
-    log.dim('  （查询最新版失败，按当前 CLI 继续）');
-    return;
+    log.warn('无法查询 npm 最新版本；将用当前 CLI 刷新 skill。');
+    return null;
   }
-  if (cmpSemver(latest, current) > 0) {
-    log.warn(`draftgo-cli 有新版：${current} → ${latest}`);
-    log.dim('  运行 `draftgo upgrade` 可显式升级；本次继续使用当前版本刷新 skill。');
-  } else {
+  if (cmpSemver(latest, current) <= 0) {
     log.dim(`  CLI 已是最新（${current}）`);
+    return null;
+  }
+
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  log.step(`更新 draftgo-cli：${current} → ${latest}`);
+  const install = spawnSync(npm, ['install', '-g', `draftgo-cli@${latest}`], { stdio: 'inherit', shell: false });
+  if (install.error) {
+    log.err(`CLI 更新启动失败：${install.error.message}`);
+    return 1;
   }
+  if (install.status !== 0) {
+    log.err(`npm install 返回码 ${install.status}`);
+    return Number.isInteger(install.status) ? install.status : 1;
+  }
+
+  const command = process.platform === 'win32' ? 'draftgo.cmd' : 'draftgo';
+  const rerun = spawnSync(command, ['update', ...positional, '--project', projectDir, '--skip-update-check'], {
+    stdio: 'inherit',
+    shell: false,
+    env: { ...process.env, [REENTRY_FLAG]: '1' },
+  });
+  if (rerun.error) {
+    log.err(`新版 CLI 刷新 skill 失败：${rerun.error.message}`);
+    return 1;
+  }
+  return Number.isInteger(rerun.status) ? rerun.status : 1;
 }
 
 async function update(projectDir, positional, flags) {
   log.title('draftgo update');
 
+  const reentryCode = await updateCliIfNeeded(projectDir, positional, flags);
+  if (reentryCode !== null) return reentryCode;
+
   const prev = readInstalledVersion(projectDir);
   log.info(`当前已装 skill：${prev || '未安装'}，CLI 版本：${getPackageVersion()}`);
 
-  await reportAvailableUpgrade(flags);
-
   // Determine which entry files to refresh:
   //   - no positional → refresh installed targets plus project-level tool signals
   //   - "all"          → refresh every known target
@@ -84,4 +112,4 @@ async function update(projectDir, positional, flags) {
 }
 
 module.exports = update;
-module.exports.reportAvailableUpgrade = reportAvailableUpgrade;
+module.exports.updateCliIfNeeded = updateCliIfNeeded;