draftgo-cli 2.0.3 → 2.0.9

package/resources/skill/scripts/draftgo_push.py

@@ -67,7 +67,14 @@ def _lessons_reminder(cfg):
 
 def api_call(method, server, token, path, body=None):
     data = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
-    headers = {"Authorization": f"Bearer {token}"}
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "User-Agent": (
+            "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+            "(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
+        ),
+        "Accept": "application/json",
+    }
     if data is not None:
         headers["Content-Type"] = "application/json"
     req = urllib.request.Request(
@@ -287,36 +294,81 @@ def sync_nav(server, token, ids=None):
 
 
 def sync_aihub(server, token, ids=None):
-    items = _load_index("aihub/index.json")
+    all_items = _load_index("aihub/index.json")
+    items = all_items
     if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+        items = [it for it in all_items if str(it.get("id")) in ids]
+    dirty = False
     for it in items:
         iid = it.get("id")
-        name = it.get("name", iid)
+        name = it.get("name", iid or "(new)")
         # 服务端 AIHubUpdate 接受的字段子集
         payload = {k: it.get(k) for k in (
             "type", "name", "data", "priority", "version",
             "tags", "describe", "permission", "status",
         ) if it.get(k) is not None}
-        ok, status, body = api_call("PUT", server, token, f"/api/aihub/{iid}", payload)
-        print(f"  {'OK' if ok else 'ERR'} [{name}] aihub_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if iid:
+            ok, status, body = api_call("PUT", server, token, f"/api/aihub/{iid}", payload)
+            if not ok and status == 404:
+                print(f"  WARN [{name}] aihub_id={iid} 不存在，尝试创建")
+                iid = None
+            else:
+                print(f"  {'OK' if ok else 'ERR'} [{name}] aihub_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not iid:
+            create_payload = {k: payload.get(k) for k in (
+                "type", "name", "data", "priority", "version",
+                "tags", "describe", "permission",
+            ) if payload.get(k) is not None}
+            ok, status, body = api_call("POST", server, token, "/api/aihub", create_payload)
+            new_id = _extract_created_id(body) if ok else None
+            if ok and new_id:
+                it["id"] = new_id
+                dirty = True
+                print(f"  OK [{name}] 已创建 aihub_id={new_id}（已回写 index）")
+            else:
+                print(f"  ERR [{name}] 创建失败 -> {_info(ok, status, body)}")
+    if dirty:
+        _writeback_index("aihub/index.json", all_items)
 
 
 def sync_external_apis(server, token, ids=None):
-    items = _load_index("external_apis/index.json")
+    all_items = _load_index("external_apis/index.json")
+    items = all_items
     if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+        items = [it for it in all_items if str(it.get("id")) in ids]
+    dirty = False
     for it in items:
         iid = it.get("id")
-        code = it.get("code", iid)
+        code = it.get("code", iid or "(new)")
         # 服务端 ExternalAPIUpdate 接受字段
         payload = {k: it.get(k) for k in (
             "name", "base_url", "method", "path", "headers",
             "auth_type", "auth_config", "timeout_ms", "permission",
             "param_schema", "tags", "description", "status",
         ) if it.get(k) is not None}
-        ok, status, body = api_call("PUT", server, token, f"/api/external-apis/{iid}", payload)
-        print(f"  {'OK' if ok else 'ERR'} [{code}] api_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if iid:
+            ok, status, body = api_call("PUT", server, token, f"/api/external-apis/{iid}", payload)
+            if not ok and status == 404:
+                print(f"  WARN [{code}] api_id={iid} 不存在，尝试创建")
+                iid = None
+            else:
+                print(f"  {'OK' if ok else 'ERR'} [{code}] api_id={iid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not iid:
+            create_payload = {k: it.get(k) for k in (
+                "code", "name", "base_url", "method", "path", "headers",
+                "auth_type", "auth_config", "timeout_ms", "permission",
+                "param_schema", "tags", "description",
+            ) if it.get(k) is not None}
+            ok, status, body = api_call("POST", server, token, "/api/external-apis", create_payload)
+            new_id = _extract_created_id(body) if ok else None
+            if ok and new_id:
+                it["id"] = new_id
+                dirty = True
+                print(f"  OK [{code}] 已创建 api_id={new_id}（已回写 index）")
+            else:
+                print(f"  ERR [{code}] 创建失败 -> {_info(ok, status, body)}")
+    if dirty:
+        _writeback_index("external_apis/index.json", all_items)
 
 
 def sync_system_config(server, token, keys=None):
@@ -339,7 +391,13 @@ def sync_system_config(server, token, keys=None):
         }
         payload = {k: v for k, v in payload.items() if v is not None}
         ok, status, body = api_call("PUT", server, token, f"/api/system/{ck}", payload)
-        print(f"  {'OK' if ok else 'ERR'} [{ck}]{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not ok and status == 404:
+            print(f"  WARN [{ck}] system_config 不存在，尝试创建")
+            create_payload = {"config_key": ck, **payload}
+            ok, status, body = api_call("POST", server, token, "/api/system/", create_payload)
+            print(f"  {'OK' if ok else 'ERR'} [{ck}] 已创建{'' if ok else ' -> ' + _info(ok, status, body)}")
+        else:
+            print(f"  {'OK' if ok else 'ERR'} [{ck}]{'' if ok else ' -> ' + _info(ok, status, body)}")
 
 
 def sync_roles(server, token, ids=None):
@@ -421,18 +479,48 @@ def sync_docs(server, token, ids=None):
 
 
 def sync_doc_categories(server, token, ids=None):
-    items = _load_index("doc_categories/index.json")
+    all_items = _load_index("doc_categories/index.json")
+    items = all_items
     if ids:
-        items = [it for it in items if str(it.get("id")) in ids]
+        items = [it for it in all_items if str(it.get("id")) in ids]
+    dirty = False
     for it in items:
         cid = it.get("id")
-        name = it.get("name", cid)
+        name = it.get("name", cid or "(new)")
         # CategoryUpdate 字段
         payload = {k: it.get(k) for k in (
             "name", "slug", "description", "icon", "parent_id", "sort_order", "status",
         ) if it.get(k) is not None}
-        ok, status, body = api_call("PUT", server, token, f"/api/docs/categories/{cid}", payload)
-        print(f"  {'OK' if ok else 'ERR'} [{name}] category_id={cid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if cid:
+            ok, status, body = api_call("PUT", server, token, f"/api/docs/categories/{cid}", payload)
+            if not ok and status == 404:
+                print(f"  WARN [{name}] category_id={cid} 不存在，尝试创建")
+                cid = None
+            else:
+                print(f"  {'OK' if ok else 'ERR'} [{name}] category_id={cid}{'' if ok else ' -> ' + _info(ok, status, body)}")
+        if not cid:
+            ok, status, body = api_call("POST", server, token, "/api/docs/categories", payload)
+            new_id = _extract_created_id(body) if ok else None
+            if ok and new_id:
+                it["id"] = new_id
+                dirty = True
+                print(f"  OK [{name}] 已创建 category_id={new_id}（已回写 index）")
+            else:
+                print(f"  ERR [{name}] 创建失败 -> {_info(ok, status, body)}")
+    if dirty:
+        _writeback_index("doc_categories/index.json", all_items)
+
+
+def _normalize_script_triggers(mode, triggers):
+    """归一化 custom_script.triggers。
+
+    - scheduled：实际调度只读代码里的 @scheduled(...)，CLI push 主动回写空 dict，
+      避免把误导性的 cron 元数据继续推回云端。
+    - 其他模式：保留本地 triggers 元数据。
+    """
+    if str(mode or "").lower() == "scheduled":
+        return {}
+    return triggers
 
 
 def sync_custom_scripts(server, token, ids=None):
@@ -451,11 +539,13 @@ def sync_custom_scripts(server, token, ids=None):
             print(f"  SKIP [{name}] code_file not found: {code_rel}")
             continue
         code = code_path.read_text(encoding="utf-8")
+        normalized_triggers = _normalize_script_triggers(it.get("mode"), it.get("triggers"))
         if sid:
             # ScriptUpdate 接受字段（不含 slug/mode，避免误改启停/路由）
             payload = {k: it.get(k) for k in (
-                "name", "description", "triggers", "config", "permission",
+                "name", "description", "config", "permission",
             ) if it.get(k) is not None}
+            payload["triggers"] = normalized_triggers
             payload["code"] = code
             ok, status, body = api_call("PUT", server, token, f"/api/scripts/{sid}", payload)
             if not ok and status == 404:
@@ -464,13 +554,13 @@ def sync_custom_scripts(server, token, ids=None):
             else:
                 print(f"  {'OK' if ok else 'ERR'} [{name}] script_id={sid}{'' if ok else ' -> ' + _info(ok, status, body)}")
         if not sid:
-            # ScriptCreate 必填 name/slug/code/mode/triggers
+            # ScriptCreate 必填 name/slug/code/mode；scheduled 的 cron 以代码装饰器为准
             payload = {
                 "name": it.get("name", ""),
                 "slug": it.get("slug", ""),
                 "code": code,
                 "mode": it.get("mode", "route"),
-                "triggers": it.get("triggers") or {},
+                "triggers": normalized_triggers,
                 "config": it.get("config"),
                 "permission": it.get("permission"),
                 "description": it.get("description"),

package/resources/skill/story/SKILL.md

@@ -57,14 +57,6 @@ design:
   modules:
     - name: "模块名"
       role: "这个模块在系统里的定位（核心/辅助/基座），一句话"
-  style:
-    personality: "系统'说话'像谁？一句话描述调性人格"
-    keywords:
-      - "设计关键词（如：叙事性交互、情感化、微动效、仪式感）"
-    do:
-      - "正面指引（什么该做）"
-    dont:
-      - "禁区（什么绝对不做）"
 
 # === 第三层：决策日志（只增不删）===
 decisions:
@@ -174,7 +166,7 @@ Q5: 第一版能用，最少要包含什么？
 ```
 1. 读取 .draftgo/story.yaml 全文 → 作为最高优先级上下文
 2. 解析 design → 理解系统核心流转和模块定位
-3. 解析 decisions（status: active）→ 提取品味/取舍依据
+3. 解析 decisions（status: active）→ 提取产品取舍依据
 4. 解析 identity.not → 建立硬边界
 5. 解析 now → 知道当前重点
 6. open_questions → 适时主动追问
@@ -217,8 +209,7 @@ AI 在开发过程中检测到"方向性决策"时，主动提议沉淀：
 **触发条件：**
 - 开发者明确拒绝了某个建议（"不要这样做"）
 - 开发者在两个方案中做了选择
-- 开发者表达了对系统调性的偏好
-- 开发者描述了 UI/UX 的感觉、风格、动效、文案语气等审美偏好
+- 开发者表达了对系统定位、功能边界或文案语气的偏好
 
 **AI 行为：**
 
@@ -229,23 +220,6 @@ AI 在开发过程中检测到"方向性决策"时，主动提议沉淀：
 → [是] / [否] / [改改措辞]
 ```
 
-**style 沉淀（渐进式，不单独提问）：**
-
-当开发者在 UI/UX 相关对话中表达了审美偏好时（如描述交互节奏、文案风格、动效喜好、视觉调性），AI 提议：
-
-```
-从你刚才的描述里，我提炼了几个设计偏好：
-- keyword: "叙事性交互"
-- do: "关键流程用动效创造起承转合"
-- dont: "不用系统腔提示语"
-
-要写进 Story 的 design.style 里吗？以后做 UI 我会按这个调性来。
-
-→ [写入] / [调整措辞] / [这次不记]
-```
-
-style 不是一次性采集的，而是在持续开发中不断丰富——每次用户表达审美偏好都是一次沉淀机会。
-
 ---
 
 ## now 的更新
@@ -268,7 +242,6 @@ style 不是一次性采集的，而是在持续开发中不断丰富——每
 | `identity.*` | 极少 | 仅重大方向转向时（冲突检测中确认） |
 | `design.overview` | 里程碑级 | 核心流转发生结构性变化时更新 |
 | `design.modules` | 新增模块时 | 只增/改，不删已有模块（模块下线标注即可） |
-| `design.style` | 渐进沉淀 | 不在初始化时采集；开发过程中从用户的描述、选择、审美反馈中提炼 |
 | `decisions` | 只增不删 | ID 永不复用，supersede 时不删旧的只标记 |
 | `now.focus` | 周/里程碑 | 对话结束时 AI 提议更新 |
 | `now.next` | 周 | 同上 |

package/resources/skill/story/story.example.yaml

@@ -34,27 +34,6 @@ design:
       role: "数据可视化，让开发者快速感知趋势"
     - name: "数据源配置"
       role: "基座模块，连接开发者自己的后端 API"
-  style:
-    personality: "像一个有品味的年轻朋友，不是客服也不是机器"
-    keywords:
-      - "叙事性交互"
-      - "情感化对话"
-      - "微动效驱动节奏"
-      - "仪式感"
-      - "克制的丰富"
-    do:
-      - "用人话跟用户说话，有温度"
-      - "关键流程要有起承转合的时序编排"
-      - "用动效创造记忆点（渐显渐隐、灯亮进度、礼花）"
-      - "重要时刻要有仪式感（注册=相识、完成=庆祝）"
-      - "空态用一句有温度的话引导，不用冷冰冰的'暂无数据'"
-    dont:
-      - "不堆 emoji"
-      - "不用系统腔提示语（如'操作成功'、'请稍后重试'）"
-      - "不极简到无趣"
-      - "不炫技到喧宾夺主"
-      - "敏感场景（支付/删除/错误）不抖机灵"
-
 # === 第三层：决策日志（只增不删）===
 decisions:
   - id: D001

package/src/commands/check.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const log = require('../logger');
+const { analyzeProject } = require('../projectMap');
+
+function check(projectDir, flags = {}) {
+  const result = analyzeProject(projectDir);
+
+  if (flags.output === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    return result.errors.length || (flags.strict && result.warnings.length) ? 1 : 0;
+  }
+
+  log.title('draftgo check');
+  log.info(`项目目录：${projectDir}`);
+
+  console.log('');
+  log.info(`资源概览：pages=${result.map.pages.length}, nav=${result.map.navigations.length}, db=${result.map.db_meta.length}, scripts=${result.map.custom_scripts.length}, aihub=${result.map.aihub.length}, external_apis=${result.map.external_apis.length}, docs=${result.map.docs.length}, doc_categories=${result.map.doc_categories.length}, system_config=${result.map.system_config.length}`);
+
+  if (result.errors.length) {
+    console.log('');
+    console.log(`${log.c.red('x')} 错误：`);
+    result.errors.forEach((msg) => console.log(`  - ${msg}`));
+  }
+
+  if (result.warnings.length) {
+    console.log('');
+    console.log(`${log.c.yellow('!')} 提醒：`);
+    result.warnings.forEach((msg) => console.log(`  - ${msg}`));
+  }
+
+  if (!result.errors.length && !result.warnings.length) {
+    console.log('');
+    log.ok('未发现明显闭环问题。');
+  }
+
+  if (result.errors.length) {
+    console.log('');
+    console.log(`${log.c.red('x')} 检查未通过：请先修复错误。`);
+    return 1;
+  }
+  if (flags.strict && result.warnings.length) {
+    console.log('');
+    console.log(`${log.c.red('x')} strict 模式：存在提醒项，检查未通过。`);
+    return 1;
+  }
+
+  console.log('');
+  log.ok(result.warnings.length ? '检查完成：存在提醒项，建议开发代理处理后再 push。' : '检查通过。');
+  return 0;
+}
+
+module.exports = check;

package/src/commands/help.js

@@ -5,7 +5,11 @@ const { getPackageVersion } = require('../skill');
 
 function help() {
   const targets = all.map((i) => `    ${i.name.padEnd(12)} ${i.displayName}`).join('\n');
-  console.log(`draftgo v${getPackageVersion()} — manage the DraftGo skill across AI coding agents
+  console.log(`draftgo v${getPackageVersion()} — DraftGo Next workbench CLI for AI coding agents
+
+DraftGo Next frontend baseline: React + Vite + shadcn/ui + Tailwind.
+Database pages use dg-* as the shadcn HTML runtime protocol.
+The CLI is the workbench layer for local runtime, resource sync, checks, and push/pull flows.
 
 Usage:
   draftgo init [<target>...]       Install skill. No target = auto-detect.
@@ -19,6 +23,19 @@ Usage:
   draftgo status                   Show installed targets and skill version.
   draftgo doctor                   Diagnose environment (python, targets,
                                     CLI freshness).
+  draftgo map                      Print a local DraftGo project resource map
+                                    for fast AI orientation.
+  draftgo check                    Check local resource closure: routes,
+                                    entry binding, files, obvious mock risks.
+  draftgo dev                      Run this project's npm dev script.
+  draftgo build                    Run this project's npm build script.
+  draftgo pull [type] [id...]      Pull DraftGo resources via the bundled
+                                    sync script. Defaults to --all.
+  draftgo push <type> [id...]      Push DraftGo resources via the bundled
+                                    sync script.
+  draftgo local up|down|logs|status
+                                    Manage .draftgo/docker/docker-compose.yaml
+                                    generated by draftgo local-dev.
   draftgo list-targets             List supported AI tools.
   draftgo connect                  Bind this project to an existing DraftGo
                                     server. Prompts for BaseURL + access
@@ -31,6 +48,11 @@ Usage:
   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 pull|push                First-class resource sync wrappers.
+
 Flags:
   --project <dir>          Operate on <dir> instead of the current directory.
   --force                  Overwrite existing skill body during install/update.
@@ -42,6 +64,8 @@ Flags:
   --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.
+  --output <json>          (map/check) Print machine-readable JSON.
+  --strict                 (check) Treat warnings as failures.
 
 Environment:
   DRAFTGO_NO_UPDATE_CHECK=1     Disable the automatic CLI-freshness check.
@@ -55,6 +79,8 @@ Examples:
   draftgo init claudecode kiro # install for both
   draftgo init all             # install for every supported target
   draftgo update               # upgrade CLI if needed, then refresh skill
+  draftgo map                  # inspect pages/nav/db/scripts before development
+  draftgo check --strict       # fail on closure warnings before push
   draftgo uninstall all --purge # full removal incl. runtime data
 `);
 }

package/src/commands/local.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+const log = require('../logger');
+const { exists } = require('../fsx');
+const { detectDocker } = require('../localdev/detect');
+
+function composeFile(projectDir) {
+  return path.join(projectDir, '.draftgo', 'docker', 'docker-compose.yaml');
+}
+
+function runCompose(projectDir, args, stdio = 'inherit') {
+  const docker = detectDocker();
+  if (!docker.ok) {
+    log.err(docker.reason === 'compose-missing'
+      ? '检测到 Docker，但缺少 compose 插件。'
+      : '未检测到可用 Docker。');
+    return 1;
+  }
+
+  const file = composeFile(projectDir);
+  if (!exists(file)) {
+    log.err('未找到 .draftgo/docker/docker-compose.yaml。');
+    log.dim('  请先运行 `draftgo local-dev` 生成本地 DraftGo stack。');
+    return 1;
+  }
+
+  const r = spawnSync(docker.composeCmd, [...docker.composeArgs, '-f', file, ...args], {
+    cwd: path.dirname(file),
+    stdio,
+    shell: false,
+  });
+  return r.status || 0;
+}
+
+function local(projectDir, positional) {
+  const action = positional[0] || 'status';
+
+  switch (action) {
+    case 'up':
+      return runCompose(projectDir, ['up', '-d']);
+    case 'down':
+      return runCompose(projectDir, ['down']);
+    case 'logs':
+      return runCompose(projectDir, ['logs', ...(positional.slice(1).length ? positional.slice(1) : ['-f', 'app'])]);
+    case 'status':
+    case 'ps':
+      return runCompose(projectDir, ['ps']);
+    default:
+      log.err(`未知 local 子命令：${action}`);
+      log.dim('  可用：draftgo local up | down | logs | status');
+      return 1;
+  }
+}
+
+module.exports = local;

package/src/commands/map.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const log = require('../logger');
+const { buildProjectMap } = require('../projectMap');
+
+function printList(title, rows, render) {
+  console.log('');
+  log.info(`${title}：${rows.length}`);
+  if (rows.length === 0) {
+    log.dim('  （无）');
+    return;
+  }
+  for (const row of rows) log.dim(`  • ${render(row)}`);
+}
+
+function mapCommand(projectDir, flags = {}) {
+  const map = buildProjectMap(projectDir);
+
+  if (flags.output === 'json') {
+    console.log(JSON.stringify(map, null, 2));
+    return 0;
+  }
+
+  log.title('draftgo map');
+  log.info(`项目目录：${projectDir}`);
+
+  printList('页面', map.pages, (p) => {
+    const id = p.id == null ? 'new' : p.id;
+    return `${String(id).padEnd(4)} ${p.route || '（无 route）'}  ${p.title || '未命名'}${p.html_file ? `  ${p.html_file}` : ''}`;
+  });
+
+  printList('导航', map.navigations, (n) => {
+    const id = n.id == null ? 'new' : n.id;
+    return `${String(id).padEnd(4)} ${n.code || 'default'}  ${n.name || '未命名'}${n.html_file ? `  ${n.html_file}` : ''}`;
+  });
+
+  printList('动态 DB', map.db_meta, (m) => {
+    const fields = m.fields.length ? ` (${m.fields.slice(0, 8).join(', ')}${m.fields.length > 8 ? ', ...' : ''})` : '';
+    return `${m.type || '（无 type）'}  ${m.label || ''}${fields}`;
+  });
+
+  printList('自定义脚本', map.custom_scripts, (s) => {
+    return `${s.slug || '（无 slug）'}  ${s.mode || 'mode?'}  ${s.name || ''}${s.code_file ? `  ${s.code_file}` : ''}`;
+  });
+
+  printList('外部 API', map.external_apis, (a) => {
+    const route = `${a.method || 'GET'} ${a.path || '/'}`;
+    const tags = a.tags && a.tags.length ? `  #${a.tags.join(',#')}` : '';
+    return `${a.id || 'new'}  ${a.code || '（无 code）'}  ${route}  ${a.name || ''}${a.base_url ? `  ${a.base_url}` : ''}${tags}`;
+  });
+
+  printList('文档', map.docs, (d) => {
+    return `${d.id || 'new'}  ${d.slug || '（无 slug）'}  ${d.title || '未命名'}${d.content_file ? `  ${d.content_file}` : ''}`;
+  });
+
+  printList('文档分类', map.doc_categories, (c) => {
+    const parent = c.parent_id == null ? 'root' : `parent:${c.parent_id}`;
+    return `${c.id || 'new'}  ${c.slug || '（无 slug）'}  ${c.name || '未命名'}  ${parent}`;
+  });
+
+  printList('系统配置', map.system_config, (c) => {
+    const sensitive = c.is_sensitive ? ' sensitive' : '';
+    return `${c.config_key || '（无 key）'}  ${c.category || 'default'}  ${c.value_type || 'value'}${sensitive}`;
+  });
+
+  printList('AIHub', map.aihub, (a) => {
+    const extra = [];
+    if (a.type === 'agent') {
+      if (a.mode) extra.push(a.mode);
+      if (a.output_format && a.output_format.mode === 'json') extra.push(`json:${a.output_format.json_strategy || 'auto'}`);
+      if (a.model_selection && a.model_selection.user_selectable) extra.push('user-model');
+      if (a.tools && a.tools.sources.length) extra.push(`tools:${a.tools.sources.length}`);
+    } else if (a.type === 'model') {
+      extra.push(`models:${a.models_count || 0}`);
+      if (a.supports_response_format === true) extra.push('response_format');
+      if (a.supports_json_schema === true) extra.push('json_schema');
+    } else if (a.type === 'mcp') {
+      extra.push(a.transport || 'transport?');
+      extra.push(`tools:${a.tools_count || 0}`);
+    }
+    return `${a.id || 'new'}  ${a.type || ''}  ${a.name || ''}${extra.length ? `  [${extra.join(', ')}]` : ''}`;
+  });
+  printList('角色', map.roles, (r) => `${r.code || r.id || 'new'}  ${r.name || ''}`);
+
+  console.log('');
+  log.info('入口引用：');
+  const routes = Object.keys(map.routeRefs).sort();
+  if (routes.length === 0) log.dim('  （未发现 data-page-route / href 引用）');
+  else routes.forEach((route) => log.dim(`  • ${route} ← ${map.routeRefs[route].join(', ')}`));
+
+  return 0;
+}
+
+module.exports = mapCommand;

package/src/commands/projectScript.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const log = require('../logger');
+
+function projectScript(projectDir, scriptName) {
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    log.err(`当前项目没有 package.json，无法运行 draftgo ${scriptName}。`);
+    return 1;
+  }
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  } catch (err) {
+    log.err(`package.json 解析失败：${err.message}`);
+    return 1;
+  }
+
+  if (!pkg.scripts || !pkg.scripts[scriptName]) {
+    log.err(`package.json 中没有 scripts.${scriptName}。`);
+    return 1;
+  }
+
+  const npmCmd = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const r = spawnSync(npmCmd, ['run', scriptName], {
+    cwd: projectDir,
+    stdio: 'inherit',
+    shell: false,
+  });
+  return r.status || 0;
+}
+
+module.exports = projectScript;

package/src/commands/sync.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+const log = require('../logger');
+const { exists } = require('../fsx');
+const { findPython } = require('../python');
+const { platforms } = require('../platforms');
+
+function findSyncScript(projectDir, command) {
+  const scriptName = command === 'pull' ? 'draftgo_pull.py' : 'draftgo_push.py';
+
+  for (const platform of platforms) {
+    const candidate = path.join(projectDir, platform.assetDir, 'scripts', scriptName);
+    if (exists(candidate)) return candidate;
+  }
+
+  const bundled = path.resolve(__dirname, '..', '..', 'resources', 'skill', 'scripts', scriptName);
+  return exists(bundled) ? bundled : null;
+}
+
+function sync(projectDir, command, positional) {
+  const py = findPython();
+  if (!py) {
+    log.err('未检测到 Python，无法运行 DraftGo 同步脚本。');
+    return 1;
+  }
+
+  const script = findSyncScript(projectDir, command);
+  if (!script) {
+    log.err(`未找到 ${command} 同步脚本。`);
+    log.dim('  请先运行 `draftgo init` 安装 DraftGo skill，或重新安装 CLI。');
+    return 1;
+  }
+
+  if (!exists(path.join(projectDir, '.draftgo', 'config.json'))) {
+    log.err('未找到 .draftgo/config.json。');
+    log.dim('  请先运行 `draftgo connect` 或 `/draftgo init`。');
+    return 1;
+  }
+
+  const args = positional.length ? positional : ['--all'];
+  const r = spawnSync(py.bin, [script, ...args], {
+    cwd: projectDir,
+    stdio: 'inherit',
+    shell: false,
+  });
+  return r.status || 0;
+}
+
+module.exports = sync;