draftgo-cli 3.0.44 → 3.0.49

package/src/commands/commit.js

@@ -9,11 +9,37 @@ async function commit(projectDir, positional, flags = {}) {
     log.err('Usage: draftgo commit <pages|nav|docs> <id...>');
     return 1;
   }
-  const results = await commitResources(projectDir, resourceType, ids);
-  if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
-  else for (const result of results) {
-    if (result.status === 'unchanged') log.dim(`${result.resource_type} ${result.resource_id}: unchanged`);
-    else log.ok(`Committed ${result.resource_type} ${result.resource_id}`);
+  const streamed = [];
+  const printStatus = (result) => {
+    streamed.push(result);
+    if (flags.output === 'json') return;
+    if (result.status === 'committed') log.ok(`${result.resource_type} ${result.resource_id}: committed`);
+    else if (result.status === 'unchanged') log.dim(`${result.resource_type} ${result.resource_id}: unchanged`);
+    else if (result.status === 'failed') log.err(`${result.resource_type} ${result.resource_id}: failed (${result.code}) - ${result.message}`
+      + (result.remote_change_possible ? ' Remote change is possible; run draftgo check --remote.' : ''));
+    else log.warn(`${result.resource_type} ${result.resource_id}: not started`);
+  };
+  try {
+    const results = await commitResources(projectDir, resourceType, ids, { onStatus: printStatus });
+    if (flags.output === 'json') console.log(JSON.stringify({
+      completed: results.filter((item) => ['committed', 'unchanged'].includes(item.status)),
+      failed: [],
+      not_started: [],
+    }, null, 2));
+  } catch (error) {
+    const batch = error.details && (error.details.batch || error.details);
+    const summary = batch && Array.isArray(batch.completed) ? batch : {
+      completed: streamed.filter((item) => ['committed', 'unchanged'].includes(item.status)),
+      failed: streamed.filter((item) => item.status === 'failed'),
+      not_started: streamed.filter((item) => item.status === 'not_started'),
+    };
+    if (flags.output === 'json') console.log(JSON.stringify({ error: {
+      code: error.code || 'COMMIT_FAILED', message: error.message,
+    }, ...summary }, null, 2));
+    else log.err(`Commit batch stopped: ${summary.completed.length} completed, `
+      + `${summary.failed.length} failed, ${summary.not_started.length} not started. `
+      + `${summary.completed.length ? 'Remote changes already occurred for completed resources.' : 'No remote content was changed.'}`);
+    return 1;
   }
   return 0;
 }

package/src/commands/deploy.js

@@ -11,7 +11,7 @@ async function deploy(projectDir, positional, flags = {}) {
   }
 
   log.step('deploy: validating checked-out content...');
-  const checkCode = check(projectDir, { strict: flags.strict });
+  const checkCode = await check(projectDir, { strict: flags.strict });
   if (checkCode !== 0) {
     log.err('Deploy stopped because local validation failed.');
     return checkCode;

package/src/commands/help.js

@@ -14,7 +14,7 @@ function help() {
   console.log(`draftgo v${getPackageVersion()} - DraftGo workbench CLI for AI coding agents
 
 DraftGo Next frontend baseline: React + Vite.
-Database pages use standard HTML + Tailwind CSS.
+Database pages may use native web technologies or bundled component libraries.
 MCP handles live discovery and structured resources; complete page, navigation,
 and document bodies use checkout/commit outside MCP context.
 The context command combines exact local Reference sections with live MCP data;
@@ -45,8 +45,10 @@ Usage:
   draftgo checkout <type> <id...>  Download pages/nav/docs body + verified base.
                                     --force explicitly replaces local changes.
   draftgo check                    Validate checked-out worktree/base files only.
+                                    --remote also compares remote hash/version.
   draftgo diff <type> <id>         Show checkout base versus local body.
   draftgo commit <type> <id...>    Validate and upload complete checked-out bodies.
+  draftgo reconcile <type> <id...> Repair stale metadata only when local equals remote.
   draftgo conflicts                List unresolved conflicts; --all includes resolved.
   draftgo conflict show <type> <id>
                                     Show preserved base/local/remote paths.
@@ -58,6 +60,8 @@ Usage:
   draftgo api <query>              Search the live API contract through MCP.
   draftgo api describe <operation_id>
                                     Describe one live API operation through MCP.
+  draftgo api call <operation_id> --input <json-file>
+                                    Call one described operation with UTF-8 JSON.
   draftgo delete <operation_id> [id]
                                     Confirm and call a live delete operation.
                                     Legacy <type> <id> works only when unambiguous.
@@ -106,10 +110,11 @@ Important flags:
                            content | project.
   --type <type>            (map) pages | nav/navigations | docs/articles.
   --strict                 Treat check warnings as failures.
+  --remote                 (check) Compare checkout hashes/versions with remote.
   --yes                    Skip supported confirmation prompts.
   --operation-id <id>      (delete) Select an operation explicitly.
-  --params <json>          (delete) Pass an API parameter object.
-  --input <file>           (delete) Read the parameter object from JSON.
+  --params <json>          (api call/delete) Pass an API parameter object.
+  --input <file>           (api call/delete) Read a UTF-8 JSON parameter object.
   --delivery <mode>        (deploy) local | preview | deploy.
   --dry-run                (push) Show diffs without committing.
   --mobile-check <mode>    (verify-ui) auto | always | never.
@@ -117,6 +122,9 @@ Important flags:
                            SAT to same-origin URLs as the token query parameter.
   --screenshot <mode>      (verify-ui) on-failure | always | never.
   --browser <name>         (verify-ui) chromium | chrome | msedge.
+  --browser-path <file>    (verify-ui) Explicit browser executable; environment
+                           fallback: DRAFTGO_BROWSER_PATH.
+  --resource <type:id>     (verify-ui) Compare local and remote content first.
   --selector <css>         (verify-ui) Require a visible key element.
   --width/--height <px>    (verify-ui) Override the default 390x844 viewport.
 

package/src/commands/init.js

@@ -41,7 +41,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 / 子技能 / references / scripts）');
+  log.step('写入各 AI 工具 skill 目录（含 SKILL.md / 子技能 / references）');
   ensureRuntime(projectDir);
   const failures = [];
   let installedCount = 0;

package/src/commands/map.js

@@ -4,11 +4,10 @@ const fs = require('fs');
 const path = require('path');
 const log = require('../logger');
 const { loadProjectConfig } = require('../projectConfig');
-const { loadManifest, absolutePath } = require('../worktree/manifest');
-const { hashFile } = require('../worktree/streams');
 const { canonicalResourceType } = require('../worktree/types');
 const { TOOL_NAMES, openToolSession, callStructured } = require('../mcp/tools');
 const { allWithAbort } = require('../mcp/parallel');
+const { inspectRemoteCheckouts } = require('../worktree/status');
 
 const REMOTE_RESOURCE_TYPES = Object.freeze({
   pages: 'pages',
@@ -82,23 +81,6 @@ async function listRemoteResources(session, resourceTypes = DEFAULT_REMOTE_RESOU
   return groups.flat();
 }
 
-async function localCheckouts(projectDir) {
-  const manifest = loadManifest(projectDir);
-  const entries = [];
-  for (const entry of Object.values(manifest.entries)) {
-    const local = absolutePath(projectDir, entry.local_path);
-    let currentHash = null;
-    if (fs.existsSync(local)) currentHash = (await hashFile(local)).hash;
-    entries.push({
-      ...entry,
-      exists: currentHash !== null,
-      current_hash: currentHash,
-      changed: currentHash !== null && currentHash !== entry.base_hash,
-    });
-  }
-  return entries;
-}
-
 function legacyCaches(projectDir) {
   return ['pages', 'navigations', 'docs', 'db_meta', 'custom_scripts', 'aihub', 'roles', 'users', 'system_config']
     .filter((name) => fs.existsSync(path.join(projectDir, '.draftgo', name, 'index.json')));
@@ -113,7 +95,20 @@ async function mapCommand(projectDir, flags = {}) {
       (options) => callStructured(session, TOOL_NAMES.projectOverview, {}, options),
       (options) => listRemoteResources(session, resourceTypes, options),
     ], options),
-    () => localCheckouts(projectDir),
+    async (options) => {
+      const remoteStatus = await inspectRemoteCheckouts(projectDir, {
+        config,
+        client: session.client,
+        tools: session.tools,
+        signal: options.signal,
+      });
+      return remoteStatus.map((entry) => ({
+        ...entry,
+        exists: entry.local_hash !== null,
+        current_hash: entry.local_hash,
+        changed: entry.local_hash !== null && entry.local_hash !== entry.base_hash,
+      }));
+    },
   ]);
   const [overview, resources] = remote;
   const result = {
@@ -138,8 +133,11 @@ async function mapCommand(projectDir, flags = {}) {
   for (const [type, count] of [...counts.entries()].sort()) log.plain(`  ${type}: ${count}`);
   log.info(`Local checkouts: ${checkouts.length}`);
   for (const entry of checkouts) {
-    const state = !entry.exists ? 'missing' : entry.changed ? 'modified' : 'clean';
-    log.plain(`  ${entry.resource_type} ${entry.resource_id}: ${state} (${entry.local_path})`);
+    const state = entry.state || (!entry.exists ? 'missing' : entry.changed ? 'modified' : 'clean');
+    log.plain(`  ${entry.resource_type} ${entry.resource_id}: ${state}`
+      + ` local=${entry.local_hash || entry.current_hash || '-'} base=${entry.manifest_hash || entry.base_hash || '-'} remote=${entry.remote_hash || '-'} `
+      + `version=${entry.manifest_version ?? '-'}->${entry.remote_version ?? '-'} `
+      + `(${entry.local_path})`);
   }
   if (result.legacy_cache.detected.length) {
     log.warn(`Ignored legacy cache indexes: ${result.legacy_cache.detected.join(', ')}`);

package/src/commands/mcp.js

@@ -13,6 +13,20 @@ const {
 const { serveStdio } = require('../mcp/stdio');
 const { parseTimeout } = require('../timeout');
 
+function classifyMcpFailure(error) {
+  const message = String(error && error.message || error || '');
+  const code = error && error.code;
+  const status = error && error.status;
+  if (status === 401 || status === 403) return 'SAT authentication or authorization failed.';
+  if (/session|uninitialized|initialize first|not initialized/i.test(message)
+      || ['SESSION_EXPIRED', 'MCP_SESSION_EXPIRED', -32002].includes(code)) {
+    return 'The MCP session was lost or the server rejected the initialized state; check sticky sessions and service restarts.';
+  }
+  if (status >= 500) return 'The MCP service returned a server error; inspect the service request ID and logs.';
+  if (/tools\/call|tool/i.test(message)) return 'Tool invocation failed after protocol setup; inspect the tool contract and server handler.';
+  return 'Connection or MCP protocol negotiation failed.';
+}
+
 function targetArgs(positional, flags) {
   const values = positional.slice();
   if (flags.target) values.push(...String(flags.target).split(','));
@@ -87,19 +101,27 @@ function status(projectDir, positional = [], flags = {}) {
 
 async function test(projectDir, _positional = [], flags = {}) {
   let config;
+  const stages = [];
   try {
     config = loadProjectConfig(projectDir);
     const result = await testConnection(config, {
       timeoutMs: parseTimeout(flags.timeout),
+      onStage(stage, status) {
+        stages.push({ stage, status });
+        if (status === 'succeeded') log.ok(`MCP ${stage} succeeded.`);
+        else if (status === 'failed') log.err(`MCP ${stage} failed.`);
+        else log.step(`MCP ${stage}...`);
+      },
     });
-    log.ok('DraftGo MCP initialize succeeded.');
-    log.ok(`tools/list returned ${result.tools.length} tools.`);
-    log.ok(`tools/call succeeded: ${result.testedCalls.join(', ')}`);
+    log.ok(`MCP diagnostic completed: ${result.testedCalls.length} tools/call checks passed.`);
     log.dim(`  protocol: ${result.protocolVersion}`);
     return 0;
   } catch (error) {
     const token = config && String(config.token || config.sat || '');
     log.err(redactText(error && error.message ? error.message : error, [token]));
+    const last = stages[stages.length - 1];
+    if (last) log.info(`MCP diagnostic stopped at ${last.stage} (${last.status}).`);
+    log.info(classifyMcpFailure(error));
     return 1;
   }
 }
@@ -125,3 +147,4 @@ mcp.serve = serve;
 mcp.printUsage = printUsage;
 
 module.exports = mcp;
+module.exports.classifyMcpFailure = classifyMcpFailure;

package/src/commands/reconcile.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const log = require('../logger');
+const { reconcileResources } = require('../worktree');
+
+async function reconcile(projectDir, positional, flags = {}) {
+  const [resourceType, ...ids] = positional;
+  if (!resourceType || !ids.length) {
+    log.err('Usage: draftgo reconcile <pages|nav|docs> <id...>');
+    return 1;
+  }
+  const results = await reconcileResources(projectDir, resourceType, ids);
+  if (flags.output === 'json') console.log(JSON.stringify(results, null, 2));
+  else for (const result of results) {
+    log.ok(`Reconciled ${result.resource_type} ${result.resource_id} -> ${result.base_version ?? result.base_revision}`);
+  }
+  return 0;
+}
+
+module.exports = reconcile;

package/src/commands/verifyUi.js

@@ -5,6 +5,10 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const log = require('../logger');
 const { configPath, loadProjectConfig } = require('../projectConfig');
+const { loadManifest, getEntry } = require('../worktree/manifest');
+const { canonicalResourceType } = require('../worktree/types');
+const { resolveMetadata } = require('../worktree/backend');
+const { inspectEntry, openMetadataSession } = require('../worktree/status');
 
 const UI_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.html', '.htm', '.jsx', '.tsx', '.vue', '.svelte']);
 
@@ -77,6 +81,7 @@ function redactUrlTokens(message) {
 }
 
 function executableCandidates() {
+  const explicit = process.env.DRAFTGO_BROWSER_PATH ? [process.env.DRAFTGO_BROWSER_PATH] : [];
   if (process.platform === 'win32') {
     const roots = [process.env.PROGRAMFILES, process.env['PROGRAMFILES(X86)'], process.env.LOCALAPPDATA].filter(Boolean);
     const rels = [
@@ -84,23 +89,47 @@ function executableCandidates() {
       ['Google', 'Chrome', 'Application', 'chrome.exe'],
       ['Chromium', 'Application', 'chrome.exe'],
     ];
-    return roots.flatMap((root) => rels.map((parts) => path.join(root, ...parts)));
+    return [...explicit, ...roots.flatMap((root) => rels.map((parts) => path.join(root, ...parts)))];
   }
   if (process.platform === 'darwin') {
-    return [
+    return [...explicit,
       '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
       '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
       '/Applications/Chromium.app/Contents/MacOS/Chromium',
     ];
   }
-  return ['/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/microsoft-edge', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
+  return [...explicit, '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/microsoft-edge', '/usr/bin/chromium', '/usr/bin/chromium-browser'];
 }
 
-async function launchBrowser(chromium, requested) {
+function playwrightCacheCandidates() {
+  const root = process.env.PLAYWRIGHT_BROWSERS_PATH
+    || (process.platform === 'win32'
+      ? path.join(process.env.LOCALAPPDATA || '', 'ms-playwright')
+      : path.join(process.env.HOME || '', '.cache', 'ms-playwright'));
+  if (!root || !fs.existsSync(root)) return [];
+  const candidates = [];
+  const visit = (directory, depth) => {
+    if (depth > 3) return;
+    let entries;
+    try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isFile() && /^(?:chrome(?:-headless-shell)?|chromium|msedge|headless_shell)(?:\.exe)?$/i.test(entry.name)) candidates.push(absolute);
+      else if (entry.isDirectory()) visit(absolute, depth + 1);
+    }
+  };
+  visit(root, 0);
+  return candidates;
+}
+
+async function launchBrowser(chromium, requested, requestedPath) {
   const attempts = [];
+  if (requestedPath) attempts.push({ executablePath: requestedPath, label: `path:${requestedPath}` });
   if (requested && requested !== 'chromium') attempts.push({ channel: requested });
-  for (const executablePath of executableCandidates().filter((candidate) => fs.existsSync(candidate))) {
-    attempts.push({ executablePath });
+  for (const executablePath of [...executableCandidates(), ...playwrightCacheCandidates()].filter((candidate) => fs.existsSync(candidate))) {
+    if (!attempts.some((attempt) => attempt.executablePath === executablePath)) {
+      attempts.push({ executablePath, label: `path:${executablePath}` });
+    }
   }
   if (!requested || requested === 'chromium') attempts.push({});
   for (const channel of ['msedge', 'chrome']) {
@@ -108,14 +137,42 @@ async function launchBrowser(chromium, requested) {
   }
 
   let lastError = null;
+  const attempted = [];
   for (const options of attempts) {
     try {
-      return await chromium.launch({ headless: true, ...options });
+      const { label, ...launchOptions } = options;
+      const browser = await chromium.launch({ headless: true, ...launchOptions });
+      return { browser, selected: label || options.channel || 'playwright-managed', attempted };
     } catch (err) {
       lastError = err;
+      attempted.push(`${options.label || options.channel || 'playwright-managed'}: ${String(err.message || err).split('\n')[0]}`);
     }
   }
-  throw new Error(`未找到可用的 Chromium/Chrome/Edge。${lastError ? ` ${lastError.message.split('\n')[0]}` : ''}`);
+  throw new Error(`未找到可用的 Chromium/Chrome/Edge。请使用 --browser-path <executable> 或 DRAFTGO_BROWSER_PATH。`
+    + `尝试记录：${attempted.join('; ')}`
+    + (lastError ? `；最后错误：${lastError.message.split('\n')[0]}` : ''));
+}
+
+function parseResourceSpec(value) {
+  const raw = String(value || '');
+  const separator = raw.indexOf(':');
+  if (separator <= 0 || separator === raw.length - 1) {
+    throw new Error('--resource 格式必须是 <pages|nav|docs>:<id>。');
+  }
+  return { resourceType: canonicalResourceType(raw.slice(0, separator)), resourceId: raw.slice(separator + 1) };
+}
+
+async function verifyRemoteResource(projectDir, spec) {
+  const { resourceType, resourceId } = parseResourceSpec(spec);
+  const entry = getEntry(loadManifest(projectDir), resourceType, resourceId);
+  if (!entry) throw new Error(`${resourceType} ${resourceId} 未 checkout。`);
+  const config = loadProjectConfig(projectDir);
+  const session = await openMetadataSession(config);
+  const remote = await resolveMetadata(config, resourceType, resourceId, {
+    ...session,
+    clientInitialized: true,
+  });
+  return inspectEntry(projectDir, entry, remote);
 }
 
 async function verifyUi(projectDir, positional, flags = {}) {
@@ -136,7 +193,9 @@ async function verifyUi(projectDir, positional, flags = {}) {
     log.err('--mobile-check 只支持 auto、always、never。');
     return 1;
   }
-  const decision = decideMobileCheck(projectDir, mode);
+  const decision = flags.resource
+    ? { run: true, reason: `resource=${flags.resource}` }
+    : decideMobileCheck(projectDir, mode);
   if (!decision.run) {
     log.ok(`跳过 UI smoke check：${decision.reason}`);
     return 0;
@@ -169,7 +228,26 @@ async function verifyUi(projectDir, positional, flags = {}) {
 
   let browser;
   try {
-    browser = await launchBrowser(chromium, flags.browser && String(flags.browser));
+    if (flags.resource) {
+      const resource = await verifyRemoteResource(projectDir, flags.resource);
+      log.info(`UI source: remote committed ${resource.resource_type} ${resource.resource_id}`);
+      log.info(`Remote version: ${resource.remote_version || '-'}; remote hash: ${resource.remote_hash || '-'}`);
+      if (['local_modified', 'diverged'].includes(resource.state)) {
+        log.warn(`Local worktree is not committed (${resource.state}); verify-ui will test the remote version.`);
+      }
+      if (!resource.local_matches_remote && resource.state !== 'local_modified') {
+        throw new Error(`Local and remote content differ (${resource.state}); UI verification stopped.`);
+      }
+    } else {
+      log.info('UI source: remote URL response; no local worktree version was asserted.');
+    }
+    const launch = await launchBrowser(
+      chromium,
+      flags.browser && String(flags.browser),
+      flags['browser-path'] && String(flags['browser-path']),
+    );
+    browser = launch.browser;
+    log.info(`Browser: ${launch.selected}`);
     const page = await browser.newPage({ viewport: { width, height } });
     const consoleErrors = [];
     const pageErrors = [];
@@ -240,3 +318,7 @@ module.exports.gitChangedFiles = gitChangedFiles;
 module.exports.isUiFile = isUiFile;
 module.exports.configuredUiUrl = configuredUiUrl;
 module.exports.redactUrlTokens = redactUrlTokens;
+module.exports.executableCandidates = executableCandidates;
+module.exports.playwrightCacheCandidates = playwrightCacheCandidates;
+module.exports.parseResourceSpec = parseResourceSpec;
+module.exports.verifyRemoteResource = verifyRemoteResource;

package/src/context/index.js

@@ -18,14 +18,6 @@ const LONG_CONTENT_RESOURCE_TYPES = Object.freeze([
 ]);
 const DB_META_LIST_PATH = '/api/db-meta';
 const DB_META_PAGE_SIZE = 100;
-const ROOT_SECTIONS = [
-  '核心边界',
-  '强制预读：Reference 优先于 MCP',
-  '并行开发与所有权',
-  '标准工作流',
-  '安全规则',
-  '验证与交付',
-];
 
 const TASK_PROFILES = Object.freeze({
   frontend: {
@@ -35,38 +27,96 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'db' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/architecture.md' },
-      { file: 'references/modules.md' },
-      { file: 'references/frontend.md' },
-      { file: 'references/runtime.md' },
-      { file: 'references/app-api.md' },
-      { file: 'references/security.md' },
-      { file: 'references/checkout.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/architecture.md',
+        headings: ['核心概念（30 秒）', 'App 对象是什么（1 分钟）', '技术栈（30 秒）'],
+      },
+      {
+        file: 'references/modules.md',
+        headings: ['可开发模块（开发者负责实现）', '平台内置模块（开箱即用，不需实现）'],
+      },
+      {
+        file: 'references/frontend.md',
+        headings: [
+          '页面开发强制规则',
+          '页面实践经验',
+          '必须 / 禁止',
+          '前端底座与组件库清单',
+          '本地静态资源清单',
+          'GSAP 动效规范',
+          '颜色 Token（强制）',
+          '导航栏开发',
+          '退出登录',
+          '加载体验',
+          '选择器与表单体验',
+        ],
+      },
+      {
+        file: 'references/runtime.md',
+        headings: [
+          'iframe 注入机制',
+          'App 对象来源',
+          'URL 参数读取（标准三阶回落）',
+          '全局事件',
+          '前端全局层',
+        ],
+      },
+      {
+        file: 'references/app-api.md',
+        headings: ['请求', '反馈', '路由', '状态', '主题', '其他'],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用'] },
+      {
+        file: 'references/checkout.md',
+        headings: ['适用范围', '命令', 'Commit 流程', '409 / 412 冲突'],
+      },
     ],
   },
   data: {
     apiQueries: [{ resource_type: 'db' }],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/modules.md' },
-      { file: 'references/data.md' },
-      { file: 'references/db-relations.md' },
-      { file: 'references/security.md' },
-      { file: 'references/mcp.md', headings: ['边界', '协议与安全'] },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/modules.md',
+        headings: ['可开发模块（开发者负责实现）', '模块选型决策'],
+      },
+      {
+        file: 'references/data.md',
+        headings: [
+          'DB Meta 结构',
+          '关联关系（ref）',
+          'CRUD 操作范式',
+          'filters 操作符',
+          'db_meta 实时契约',
+          '通用筛选参数（非动态 DB）',
+        ],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用', '协议与安全'] },
     ],
   },
   'custom-service': {
     apiQueries: [{ resource_type: 'custom_scripts' }],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/modules.md' },
-      { file: 'references/custom-services.md' },
-      { file: 'references/data.md' },
-      { file: 'references/security.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/modules.md',
+        headings: ['可开发模块（开发者负责实现）', '模块选型决策', '自定义服务边界'],
+      },
+      {
+        file: 'references/custom-services.md',
+        headings: [
+          '最小服务',
+          '资源读写',
+          '触发器',
+          '平台 SDK',
+          '权限与运行限制',
+          '实时 API',
+          '验收清单',
+        ],
+      },
+      {
+        file: 'references/data.md',
+        headings: ['自定义服务内的 draftgo.DB.Query', 'filters 操作符'],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用', '协议与安全'] },
     ],
   },
   aihub: {
@@ -75,11 +125,22 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'agents' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/aihub.md' },
-      { file: 'references/chat-sdk.md' },
-      { file: 'references/security.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/aihub.md',
+        headings: ['条目骨架', '`data.spec` 字段地图', '观测'],
+      },
+      {
+        file: 'references/chat-sdk.md',
+        headings: [
+          '最小接入',
+          '协议',
+          '配置与布局',
+          'JavaScript API 与事件',
+          '历史与会话',
+          '鉴权与安全',
+        ],
+      },
+      { file: 'references/mcp.md', headings: ['API 发现与调用', '协议与安全'] },
     ],
   },
   content: {
@@ -89,12 +150,12 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'docs/articles' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/architecture.md' },
-      { file: 'references/modules.md' },
-      { file: 'references/checkout.md' },
-      { file: 'references/security.md' },
-      { file: 'references/parallel.md' },
+      { file: 'references/architecture.md', headings: ['核心概念（30 秒）'] },
+      { file: 'references/modules.md', headings: ['可开发模块（开发者负责实现）'] },
+      {
+        file: 'references/checkout.md',
+        headings: ['适用范围', '命令', 'Checkout 流程', 'Commit 流程', '409 / 412 冲突'],
+      },
     ],
   },
   project: {
@@ -105,12 +166,21 @@ const TASK_PROFILES = Object.freeze({
       { resource_type: 'db' },
     ],
     references: [
-      { file: 'SKILL.md', headings: ROOT_SECTIONS },
-      { file: 'references/architecture.md' },
-      { file: 'references/modules.md' },
-      { file: 'references/mcp.md' },
-      { file: 'references/checkout.md' },
-      { file: 'references/parallel.md' },
+      {
+        file: 'references/architecture.md',
+        headings: ['核心概念（30 秒）', '为什么这样设计（1 分钟）', '技术栈（30 秒）'],
+      },
+      {
+        file: 'references/modules.md',
+        headings: [
+          '可开发模块（开发者负责实现）',
+          '平台内置模块（开箱即用，不需实现）',
+          '模块选型决策',
+          '自定义服务边界',
+        ],
+      },
+      { file: 'references/mcp.md', headings: ['边界', 'API 发现与调用', '协议与安全'] },
+      { file: 'references/checkout.md', headings: ['适用范围'] },
     ],
   },
 });