@haaaiawd/loom 0.9.0 → 0.10.0

package/cli/bin/loom.js

@@ -12,15 +12,15 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 import { getNextIntent, getStatus, getDependencyGraph, getIntent, loadIntentMap, updateIntentStatus, getNarrative } from '../src/intent-map.js';
 import { getPhilosophy, listPhilosophyFiles, validateInspirationSources, validatePartDecomposition } from '../src/philosophy.js';
-import { writeVerification, getVerificationHistory, getPendingVerifications, listVerifications, getVerificationContract } from '../src/verify.js';
+import { writeVerification, createQuickVerification, getVerificationHistory, getPendingVerifications, listVerifications, getVerificationContract } from '../src/verify.js';
 import { initProject } from '../src/init.js';
 import { activateRole } from '../src/activate.js';
 import { listVersions, newVersion, useVersion, diffVersions } from '../src/version.js';
 import { doctor, contextSummary, traceIntent, reverseDep, reverseRef } from '../src/diagnostics.js';
 import { getHelpTopic, listHelpTopics } from '../src/help.js';
 import { guideProject } from '../src/guide.js';
-import { isAutoOn, autoOn, autoOff, autoStatus } from '../src/auto.js';
-import { generatePreviewPrompt, getPreviewStatus } from '../src/preview.js';
+import { isAutoOn, autoOn, autoOff, autoStatus, getAutoMode } from '../src/auto.js';
+import { generatePreviewPrompt, getPreviewStatus } from '../src/preview.js';
 
 // ─── 路径解析 ──────────────────────────────────────────
 // findLoomRoot / findVersionDir / readCurrentPointer 已提取到 shared/paths.js
@@ -126,8 +126,37 @@ try {
           console.log(`${id} status 已更新为 ${newStatus}`);
           break;
         }
+        case 'done': {
+          // loom intent done <id> — 自动走 pending→in_progress→completed，检查验证记录
+          const id = rest[0];
+          if (!id) die('用法: loom intent done <id>');
+          const verificationsDir = getVerificationsDir(versionDir);
+          // 检查有没有验证记录
+          const history = getVerificationHistory(verificationsDir, id);
+          if (!history || history.records.length === 0) {
+            die(`${id} 没有验证记录。先跑: loom verify pass ${id} --summary "..."`);
+          }
+          // 检查最新验证记录是否 passed
+          const latest = history.records[history.records.length - 1];
+          if (latest.verdict !== 'passed') {
+            die(`${id} 最新验证记录是 ${latest.verdict}（非 passed）。只有 passed 的 Intent 才能 done。`);
+          }
+          // 获取当前状态，自动走两步
+          const intent = getIntent(versionDir, id);
+          const currentStatus = intent.status;
+          if (currentStatus === 'completed') {
+            console.log(`${id} 已经是 completed，无需操作`);
+            break;
+          }
+          if (currentStatus === 'pending') {
+            updateIntentStatus(versionDir, id, 'in_progress');
+          }
+          updateIntentStatus(versionDir, id, 'completed');
+          console.log(`${id} 已完成（${currentStatus} → completed）`);
+          break;
+        }
         default:
-          die(`未知子命令: intent ${sub}\n用法: loom intent [next|status|graph|get <id>|narrative <id>|validate|trace <id>|reverse-dep <id>|reverse-ref <anchor>|update <id> --status <...>]`);
+          die(`未知子命令: intent ${sub}\n用法: loom intent [next|status|graph|get <id>|narrative <id>|validate|trace <id>|reverse-dep <id>|reverse-ref <anchor>|update <id> --status <...>|done <id>]`);
       }
       break;
     }
@@ -135,11 +164,10 @@ try {
     case 'init': {
       const result = initProject(cwd());
       console.log('LOOM 项目已初始化');
-      console.log(`  创建: ${result.created.length} 项`);
-      for (const c of result.created) console.log(`    + ${c}`);
-      if (result.skipped.length) {
-        console.log(`  跳过（已存在）: ${result.skipped.length} 项`);
-        for (const s of result.skipped) console.log(`    - ${s}`);
+      for (const c of result.created) console.log(`  [created] ${c}`);
+      for (const s of result.skipped) console.log(`  [skipped] ${s} (already exists)`);
+      if (result.created.length === 0 && result.skipped.length > 0) {
+        console.log('  所有文件已存在，无需操作。');
       }
       console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
       console.log('To Agent: 运行 loom guide 诊断当前阶段，按引导执行');
@@ -187,6 +215,17 @@ try {
           const allIssues = [...inspiration.issues, ...decomposition.issues];
           const allPassed = inspiration.passed && decomposition.passed;
 
+          // --json: 结构化输出，供 Agent 程序化消费
+          if (argv.includes('--json')) {
+            output({
+              passed: allPassed,
+              issues: allIssues,
+              sources: inspiration.sources.map(({ file, sources }) => ({ file, count: sources.length })),
+              parts: decomposition.parts,
+            });
+            exit(allPassed ? 0 : 1);
+          }
+
           if (allPassed) {
             console.log('✓ 哲学文档校验通过');
             console.log('  灵感来源:');
@@ -271,8 +310,34 @@ try {
           }
           break;
         }
+        case 'pass':
+        case 'fail': {
+          // loom verify pass <id> --summary "..." [--reproduction-command "..."]
+          // loom verify fail <id> --summary "..." [--deviation "..."] [--reproduction-command "..."]
+          const id = rest[0];
+          if (!id) die(`用法: loom verify ${sub} <id> --summary "..." [--reproduction-command "..."]${sub === 'fail' ? ' [--deviation "..."]' : ''}`);
+          const summaryIdx = argv.indexOf('--summary');
+          const reproIdx = argv.indexOf('--reproduction-command');
+          const deviationIdx = argv.indexOf('--deviation');
+          const summary = summaryIdx !== -1 ? argv[summaryIdx + 1] : null;
+          if (!summary) die(`缺少 --summary: loom verify ${sub} ${id} --summary "..."`);
+          const extras = {};
+          if (reproIdx !== -1 && argv[reproIdx + 1]) extras.reproduction_command = argv[reproIdx + 1];
+          if (sub === 'fail' && deviationIdx !== -1 && argv[deviationIdx + 1]) extras.deviation_detail = argv[deviationIdx + 1];
+          const verdict = sub === 'pass' ? 'passed' : 'deviated';
+          const result = createQuickVerification(verificationsDir, id, verdict, summary, extras);
+          console.log(`验证记录已写入: ${result.filePath}`);
+          console.log(`  轮次: ${result.round}, verdict: ${verdict}`);
+          if (verdict === 'deviated') {
+            console.log(`  deviated 累计: ${result.deviated_count} 轮`);
+            if (result.should_escalate) {
+              console.log(`  ⚠ 达到 3 轮上限，应升级为 blocked——Keeper 应执行: loom intent update ${id} --status blocked`);
+            }
+          }
+          break;
+        }
         default:
-          die(`未知子命令: verify ${sub}\n用法: loom verify [contract <id>|history <id>|pending|list|write --json-file <path>|--json <string>]`);
+          die(`未知子命令: verify ${sub}\n用法: loom verify [contract <id>|history <id>|pending|list|write --json-file <path>|--json <string>|pass <id> --summary "..."|fail <id> --summary "..."]`);
       }
       break;
     }
@@ -337,7 +402,11 @@ try {
         for (const issue of issues) {
           const icon = issue.severity === 'fatal' ? '☠' : issue.severity === 'high' ? '⚠' : '·';
           console.log(`  ${icon} [${issue.severity}] ${issue.type}: ${issue.msg}`);
+          if (issue.fix_hint) {
+            console.log(`    → 修复: ${issue.fix_hint}`);
+          }
         }
+        console.log(`\n参见 meta/PHILOSOPHY_WEAVER.md + dimensions/PART_DECOMPOSITION.md + dimensions/SEARCH_METHODOLOGY.md。`);
       }
       break;
     }
@@ -368,22 +437,39 @@ try {
       break;
     }
 
-    case 'guide': {
-      const dryRun = argv.includes('--dry-run');
-      const result = guideProject(cwd(), { dryRun });
-      console.log(`阶段 ${result.stage_num}: ${result.stage}`);
-      if (dryRun) {
-        console.log('诊断: dry-run（不写 heartbeat）');
-      }
-      if (result.auto) {
-        console.log(`模式: AUTO（自动执行，不等确认）`);
-      } else {
-        console.log(`模式: 手动（每步需用户确认）`);
+    case 'guide': {
+      const dryRun = argv.includes('--dry-run');
+      const jsonOut = argv.includes('--json');
+      const result = guideProject(cwd(), { dryRun });
+      if (jsonOut) {
+        output(result);
+        break;
+      }
+      console.log(`阶段 ${result.stage_num}: ${result.stage}`);
+      if (dryRun) {
+        console.log('诊断: dry-run（不写 heartbeat）');
       }
+      const modeDesc = {
+        'manual': '手动（每步需确认）',
+        'auto-loop': 'AUTO auto-loop（设计阶段需 review，Intent Loop 自动）',
+        'auto-design': 'AUTO auto-design（全部自动）',
+      };
+      console.log(`模式: ${modeDesc[result.auto_mode] || result.auto_mode}`);
       console.log(`\n${result.message}`);
       console.log(`\n下一步: ${result.next_action}`);
       console.log(`  → ${result.next_command}`);
-      if (!result.auto && result.stage_num > 0 && result.stage_num < 6) {
+      if (result.inputs && result.inputs.length > 0) {
+        console.log(`\n需要读取:`);
+        for (const f of result.inputs) console.log(`  - ${f}`);
+      }
+      if (result.outputs && result.outputs.length > 0) {
+        console.log(`\n需要产出:`);
+        for (const f of result.outputs) console.log(`  - ${f}`);
+      }
+      if (result.verify_command) {
+        console.log(`\n完成后校验: ${result.verify_command}`);
+      }
+      if (result.auto_mode === 'manual' && result.stage_num > 0 && result.stage_num < 6) {
         console.log(`\n提示: 开启 AUTO 模式可自动连续执行 — loom auto on`);
       }
       break;
@@ -392,76 +478,93 @@ try {
     case 'auto': {
       const loomRoot = findLoomRoot();
       switch (sub) {
-        case 'on':
-          autoOn(loomRoot);
-          console.log('AUTO 模式已开启。Agent 将自动连续执行，不等用户确认。');
+        case 'on': {
+          // loom auto on → auto-loop（默认）
+          // loom auto on --design → auto-design
+          const wantDesign = argv.includes('--design');
+          const mode = wantDesign ? 'auto-design' : 'auto-loop';
+          autoOn(loomRoot, mode);
+          if (mode === 'auto-design') {
+            console.log('AUTO 模式: auto-design（全部自动，含哲学/愿景/架构）');
+            console.log('Agent 自动连续执行所有阶段，不等人类确认。');
+          } else {
+            console.log('AUTO 模式: auto-loop（Intent Loop 自动，设计阶段需 review）');
+            console.log('  - stage 1-3（哲学/愿景/架构）：自动执行但需人类 review');
+            console.log('  - stage 4+（Intent Loop）：自动连续执行');
+          }
           console.log('核心契约: 持续运行，除非出意外否则不允许私自停止。');
           console.log('  - L3 human_review 由 Keeper 自主判定，不停下等人类');
           console.log('  - 唯一允许停下的情况: blocked（依赖阻塞/契约无法判定/连续 3 轮 deviated 升级）');
-          console.log('关闭: loom auto off');
+          console.log('切换: loom auto on --design | loom auto off');
           break;
+        }
         case 'off':
           autoOff(loomRoot);
-          console.log('AUTO 模式已关闭。每步需要用户确认。');
+          console.log('AUTO 模式: manual（每步需人类确认）');
           break;
         case 'status': {
           const status = autoStatus(loomRoot);
-          if (status.on) {
-            console.log(`AUTO 模式: 开启（自 ${status.since}）`);
-            console.log('  规则: stage 1-3（哲学/愿景/架构）需人类 review，stage 4+（Intent Loop）自动执行');
-            if (status.heartbeat) {
-              const hb = status.heartbeat;
-              console.log(`  心跳: ${hb.timestamp}`);
-              console.log(`    阶段: ${hb.stage} (stage ${hb.stage_num})`);
-              console.log(`    下一步: ${hb.next_action}`);
-              console.log(`    命令: ${hb.next_command}`);
-            } else {
-              console.log('  心跳: 尚未记录（运行 loom guide 后生成）');
-            }
-          } else {
-            console.log('AUTO 模式: 关闭（所有阶段都需人类确认）');
+          const modeDesc = {
+            'manual': 'manual（每步需人类确认）',
+            'auto-loop': 'auto-loop（Intent Loop 自动，设计阶段需 review）',
+            'auto-design': 'auto-design（全部自动，含哲学/愿景/架构）',
+          };
+          console.log(`AUTO 模式: ${modeDesc[status.mode] || status.mode}`);
+          if (status.mode === 'auto-loop') {
+            console.log('  规则: stage 1-3 需人类 review，stage 4+ 自动执行');
+          } else if (status.mode === 'auto-design') {
+            console.log('  规则: 全部阶段自动执行，不需人类 review');
+          }
+          if (status.heartbeat) {
+            const hb = status.heartbeat;
+            console.log(`  心跳: ${hb.timestamp}`);
+            console.log(`    阶段: ${hb.stage} (stage ${hb.stage_num})`);
+            console.log(`    下一步: ${hb.next_action}`);
+            console.log(`    命令: ${hb.next_command}`);
+          } else if (status.mode !== 'manual') {
+            console.log('  心跳: 尚未记录（运行 loom guide 后生成）');
           }
           break;
         }
         default:
-          die(`未知子命令: auto ${sub}\n用法: loom auto [on|off|status]`);
+          die(`未知子命令: auto ${sub}\n用法: loom auto [on [--design]|off|status]`);
       }
       break;
     }
 
-    case 'preview': {
-      const previewFile = join(cwd(), 'loom-preview.html');
-      if (argv.includes('--help') || argv.includes('-h')) {
-        console.log(`用法:
-  loom preview              打开新鲜 preview；过期时提示重新生成
-  loom preview --regen      输出生成提示词，让 Agent 重写 loom-preview.html
-  loom preview status       检查 preview 是否存在、是否新鲜
-  loom preview --stale      强行打开过期 preview
-  loom preview --help       显示本帮助`);
-        break;
-      }
-      const status = getPreviewStatus(cwd());
-      const hasPreview = status.exists;
-      const regenOnly = argv.includes('--regen') || argv.includes('-r');
-      const openStale = argv.includes('--stale');
-
-      if (sub === 'status') {
-        output(status);
-        break;
-      }
-
-      // 已有 HTML 且没指定 --regen：直接打开浏览器
-      if (hasPreview && !regenOnly) {
-        if (!status.fresh && !openStale) {
-          console.log('preview 已过期：.loom 源文件比 loom-preview.html 更新。');
-          console.log(`  preview: ${status.preview_mtime || '未知'}`);
-          console.log(`  最新源: ${status.source_latest_mtime || '未知'} ${status.latest_source_file ? `(${status.latest_source_file})` : ''}`);
-          console.log('\n下一步: loom preview --regen');
-          console.log('强行打开旧 preview: loom preview --stale');
-          break;
-        }
-        const { spawn } = await import('node:child_process');
-        const target = previewFile.replace(/\\/g, '/');
+    case 'preview': {
+      const previewFile = join(cwd(), 'loom-preview.html');
+      if (argv.includes('--help') || argv.includes('-h')) {
+        console.log(`用法:
+  loom preview              打开新鲜 preview；过期时提示重新生成
+  loom preview --regen      输出生成提示词，让 Agent 重写 loom-preview.html
+  loom preview status       检查 preview 是否存在、是否新鲜
+  loom preview --stale      强行打开过期 preview
+  loom preview --help       显示本帮助`);
+        break;
+      }
+      const status = getPreviewStatus(cwd());
+      const hasPreview = status.exists;
+      const regenOnly = argv.includes('--regen') || argv.includes('-r');
+      const openStale = argv.includes('--stale');
+
+      if (sub === 'status') {
+        output(status);
+        break;
+      }
+
+      // 已有 HTML 且没指定 --regen：直接打开浏览器
+      if (hasPreview && !regenOnly) {
+        if (!status.fresh && !openStale) {
+          console.log('preview 已过期：.loom 源文件比 loom-preview.html 更新。');
+          console.log(`  preview: ${status.preview_mtime || '未知'}`);
+          console.log(`  最新源: ${status.source_latest_mtime || '未知'} ${status.latest_source_file ? `(${status.latest_source_file})` : ''}`);
+          console.log('\n下一步: loom preview --regen');
+          console.log('强行打开旧 preview: loom preview --stale');
+          break;
+        }
+        const { spawn } = await import('node:child_process');
+        const target = previewFile.replace(/\\/g, '/');
         if (process.platform === 'win32') {
           spawn('cmd', ['/c', 'start', target], { detached: true, stdio: 'ignore' }).unref();
         } else if (process.platform === 'darwin') {
@@ -470,9 +573,9 @@ try {
           spawn('xdg-open', [target], { detached: true, stdio: 'ignore' }).unref();
         }
         console.log(`已打开浏览器: ${previewFile}`);
-        console.log(status.fresh ? `重新生成: loom preview --regen` : `已打开旧 preview。重新生成: loom preview --regen`);
-        break;
-      }
+        console.log(status.fresh ? `重新生成: loom preview --regen` : `已打开旧 preview。重新生成: loom preview --regen`);
+        break;
+      }
 
       // 没有 HTML 或指定 --regen：输出提示词让 AI 生成
       const prompt = generatePreviewPrompt();
@@ -508,10 +611,10 @@ To Human:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 用法:
-  loom init                     初始化项目（创建 .loom/v1/ 骨架 + 模板）
-  loom guide                    诊断当前阶段，输出下一步引导
-  loom guide --dry-run          只读诊断当前阶段，不写 heartbeat
-  loom auto on|off|status       AUTO 模式开关（on 时 Agent 自动连续执行）
+  loom init                     初始化项目（创建 .loom/v1/ 骨架 + 模板）
+  loom guide                    诊断当前阶段，输出下一步引导
+  loom guide --dry-run          只读诊断当前阶段，不写 heartbeat
+  loom auto on|off|status       AUTO 模式开关（on 时 Agent 自动连续执行）
   loom activate <role>          输出角色激活提示词（weaver|visionary|architect|forge|keeper）
 
   loom version list             列出所有版本（* 标记当前）
@@ -533,11 +636,11 @@ To Human:
 
   loom doctor                   项目健康检查（一致性+孤儿引用+循环依赖+僵尸）
   loom context                  上下文摘要（进度+下一步+待验证+风险）
-  loom preview                  打开新鲜 HTML；过期则提示重新生成
-  loom preview status           检查 preview 是否存在、是否新鲜
-  loom preview --regen          强制重新输出提示词（让 AI 重新生成 HTML）
-  loom preview --stale          强行打开过期 preview
-  loom help <topic>             分层指南（workflow|concepts|loop|version|doctor|preview）
+  loom preview                  打开新鲜 HTML；过期则提示重新生成
+  loom preview status           检查 preview 是否存在、是否新鲜
+  loom preview --regen          强制重新输出提示词（让 AI 重新生成 HTML）
+  loom preview --stale          强行打开过期 preview
+  loom help <topic>             分层指南（workflow|concepts|loop|version|doctor|preview）
 
   loom philosophy get <anchor>  按锚点加载哲学章节
   loom philosophy list          列出哲学文档文件

package/cli/src/auto.js

@@ -1,31 +1,54 @@
 // auto — AUTO 模式开关 + 心跳机制
-// 存储机制：.loom/auto 文件存在 = on，不存在 = off
+// 存储机制：.loom/auto 文件内容 = 模式名（auto-loop / auto-design），不存在 = manual
 // 心跳：每次 guide 调用时写 .loom/heartbeat.json（时间戳 + stage + next_command）
-// AUTO on（默认）：stage 4+（Intent Loop）自动跑，stage 1-3（哲学/愿景/架构）仍需人类 review
-// AUTO off：所有阶段都需人类确认，每步拆得更碎
+//
+// 三种模式：
+//   manual      — 每步停，所有阶段需人类 review
+//   auto-loop   — 只 Intent Loop（stage 4+）自动，stage 1-3 仍需人类 review（默认）
+//   auto-design — 哲学/愿景/架构也自动，全部阶段不需人类 review
 
 import { existsSync, writeFileSync, unlinkSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+const VALID_MODES = ['auto-loop', 'auto-design'];
+
 /**
- * 检查 AUTO 模式是否开启。
+ * 读取 .loom/auto 文件内容，返回模式名。
+ * 向后兼容：空文件 / 旧时间戳 / 未知内容 → auto-loop
+ * @param {string} loomRoot — .loom 目录路径
+ * @returns {string} 'manual' | 'auto-loop' | 'auto-design'
+ */
+export function getAutoMode(loomRoot) {
+  const path = join(loomRoot, 'auto');
+  if (!existsSync(path)) return 'manual';
+  const content = readFileSync(path, 'utf-8').trim();
+  if (VALID_MODES.includes(content)) return content;
+  return 'auto-loop'; // 旧格式兼容
+}
+
+/**
+ * 检查 AUTO 模式是否开启（非 manual）。
  * @param {string} loomRoot — .loom 目录路径
  * @returns {boolean}
  */
 export function isAutoOn(loomRoot) {
-  return existsSync(join(loomRoot, 'auto'));
+  return getAutoMode(loomRoot) !== 'manual';
 }
 
 /**
  * 开启 AUTO 模式。
  * @param {string} loomRoot — .loom 目录路径
+ * @param {string} mode — 'auto-loop' | 'auto-design'
  */
-export function autoOn(loomRoot) {
-  writeFileSync(join(loomRoot, 'auto'), new Date().toISOString(), 'utf-8');
+export function autoOn(loomRoot, mode = 'auto-loop') {
+  if (!VALID_MODES.includes(mode)) {
+    throw new Error(`非法 AUTO 模式: "${mode}" (合法: ${VALID_MODES.join(' | ')})`);
+  }
+  writeFileSync(join(loomRoot, 'auto'), mode, 'utf-8');
 }
 
 /**
- * 关闭 AUTO 模式。
+ * 关闭 AUTO 模式（切换到 manual）。
  * @param {string} loomRoot — .loom 目录路径
  */
 export function autoOff(loomRoot) {
@@ -36,14 +59,12 @@ export function autoOff(loomRoot) {
 /**
  * 获取 AUTO 状态描述。
  * @param {string} loomRoot — .loom 目录路径
- * @returns {{ on: boolean, since: string|null, heartbeat: object|null }}
+ * @returns {{ mode: string, heartbeat: object|null }}
  */
 export function autoStatus(loomRoot) {
-  const path = join(loomRoot, 'auto');
-  if (!existsSync(path)) return { on: false, since: null, heartbeat: null };
-  const since = readFileSync(path, 'utf-8').trim();
+  const mode = getAutoMode(loomRoot);
   const heartbeat = readHeartbeat(loomRoot);
-  return { on: true, since, heartbeat };
+  return { mode, heartbeat };
 }
 
 /**
@@ -79,15 +100,17 @@ export function readHeartbeat(loomRoot) {
 
 /**
  * 判断当前阶段是否需要人类 review。
- * AUTO on 时：stage 1-3（哲学/愿景/架构）需要人类 review，stage 4+ 自动跑
- * AUTO off 时：所有阶段都需要人类 review
+ * manual：全部需 review
+ * auto-loop：stage 1-3 需 review，stage 4+ 自动
+ * auto-design：全部自动
  * @param {string} loomRoot — .loom 目录路径
  * @param {number} stageNum — 阶段号
  * @returns {boolean} 是否需要人类 review
  */
 export function needsHumanReview(loomRoot, stageNum) {
-  const autoOn = isAutoOn(loomRoot);
-  if (!autoOn) return true; // AUTO off：所有阶段都需人类 review
-  // AUTO on：stage 1-3 需人类 review，stage 4+ 自动
+  const mode = getAutoMode(loomRoot);
+  if (mode === 'manual') return true;
+  if (mode === 'auto-design') return false;
+  // auto-loop：stage 1-3 需 review，stage 4+ 自动
   return stageNum > 0 && stageNum < 4;
 }

package/cli/src/diagnostics.js

@@ -59,7 +59,7 @@ function intentMapDiagnostics(versionDir) {
 
   const isTemplate = raw._meta?._template === true;
   if (isTemplate) {
-    issues.push({ id: 'intent_map', type: 'intent_map_template', severity: 'high', msg: 'Intent Map 仍是模板，尚未由 Architect 产出真实意图图' });
+    issues.push({ id: 'intent_map', type: 'intent_map_template', severity: 'high', msg: 'Intent Map 仍是模板，尚未由 Architect 产出真实意图图', is_template: true });
   }
 
   try {
@@ -69,7 +69,7 @@ function intentMapDiagnostics(versionDir) {
     valid = false;
     // 模板状态下字段缺失是预期的，降级为 high 而非 fatal
     // 非模板状态下字段缺失是真正的损坏，保持 fatal
-    issues.push({ id: 'intent_map', type: 'intent_map_invalid', severity: isTemplate ? 'high' : 'fatal', msg: e.message });
+    issues.push({ id: 'intent_map', type: 'intent_map_invalid', severity: isTemplate ? 'high' : 'fatal', msg: e.message, is_template: isTemplate });
   }
 
   return { raw, valid, issues, validMap };
@@ -87,6 +87,34 @@ function normalizeVerificationCommand(command) {
     .trim();
 }
 
+// 包管理器别名——npm test / pnpm test / bun test / yarn test 互相等价
+const PM_ALIASES = ['npm', 'pnpm', 'bun', 'yarn'];
+
+/**
+ * 把命令里的包管理器名归一化成 token，方便比较。
+ * "pnpm test" → "<PM> test"，"npm run build" → "<PM> run build"
+ */
+function normalizePackageManager(command) {
+  let result = command;
+  for (const pm of PM_ALIASES) {
+    result = result.replace(new RegExp(`\\b${pm}\\b`, 'g'), '<PM>');
+  }
+  return result;
+}
+
+/**
+ * 检测项目使用的包管理器。
+ * 优先级：锁文件存在性
+ * @param {string} projectDir — 项目根目录
+ * @returns {string} 'pnpm' | 'bun' | 'yarn' | 'npm'
+ */
+export function detectPackageManager(projectDir) {
+  if (existsSync(join(projectDir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(join(projectDir, 'bun.lockb'))) return 'bun';
+  if (existsSync(join(projectDir, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
 function commandCoversMethod(actualCommand, expectedMethod) {
   const actual = normalizeVerificationCommand(actualCommand);
   const expected = normalizeVerificationCommand(expectedMethod);
@@ -96,8 +124,12 @@ function commandCoversMethod(actualCommand, expectedMethod) {
     const expectedPart = normalizeVerificationCommand(part);
     if (!expectedPart) return true;
     if (actual.includes(expectedPart)) return true;
+    // 包管理器别名归一化：pnpm test = npm test = bun test = yarn test
+    const actualNorm = normalizePackageManager(actual);
+    const expectedNorm = normalizePackageManager(expectedPart);
+    if (actualNorm.includes(expectedNorm)) return true;
     // npm test is an acceptable broader reproduction for node --test based methods.
-    if (expectedPart.startsWith('node --test') && actual.includes('npm test')) return true;
+    if (expectedPart.startsWith('node --test') && actualNorm.includes('<PM> test')) return true;
     return false;
   });
 }
@@ -105,6 +137,42 @@ function commandCoversMethod(actualCommand, expectedMethod) {
 // ─── doctor ────────────────────────────────────────────
 // 全面健康检查：一致性 + 孤儿引用 + 循环依赖 + 僵尸 Intent
 
+// 每种 issue 类型的修复提示——给 Agent 行动化建议
+const FIX_HINTS = {
+  intent_map_unreadable: '检查 .loom/v{N}/04_INTENT_MAP.json 是否合法 JSON（jsonlint.com 或 node -e "JSON.parse(require(\'fs\').readFileSync(\'04_INTENT_MAP.json\'))"）',
+  intent_map_missing: '运行 loom init 或 loom activate architect 产出 04_INTENT_MAP.json',
+  intent_map_template: '运行 loom activate architect，Architect 填充真实 Intent Map 后删除 _meta._template 标记',
+  intent_map_invalid: '按报错信息修正 04_INTENT_MAP.json 里对应字段（补 title / 加长 acceptance / 填必填字段）',
+  completed_no_record: '在 .loom/v{N}/verifications/ 下补验证记录，或运行 loom verify pass {id} --summary "..."',
+  in_progress_no_record: '运行 loom verify pass {id} --summary "..." 写入验证记录，或 loom intent update {id} --status pending 回退',
+  orphan_philosophy_ref: '检查 04_INTENT_MAP.json 里 {id} 的 philosophy_anchors，移除或修正不存在的哲学文件引用',
+  orphan_dependency: '检查 04_INTENT_MAP.json 里 {id} 的 depends_on，移除或修正不存在的 Intent ID',
+  cycle: '打破循环：把循环链中某个 Intent 的 depends_on 里去掉前驱，或拆成更小的 Intent',
+  zombie: '检查 {id} 是否还需要——不需要就 loom intent update {id} --status completed 或 blocked',
+  completed_depends_blocked: '检查依赖 {dep} 为什么 blocked——解决阻塞或把 {id} 回退到 in_progress',
+  test_script_missing: '在 package.json 里加 test 脚本，或修正 verification_method 指向实际存在的测试命令',
+  verification_method_unverified: '运行 loom verify pass {id} --summary "..." --reproduction-command "..." 覆盖声明的验证方式',
+  verification_method_drift: '验证记录的 reproduction_command 要覆盖 verification_method 声明的命令（支持 npm/pnpm/bun 互相等价）',
+  inspiration_source: '在哲学文档的"灵感来源"章节填入至少 3 个源（- **源名** — 理由。来源：URL 或 file:// 或 local:./path）',
+  part_decomposition: '在哲学文档加"实现部分清单"章节，按 PART_DECOMPOSITION.md 拆解实现部分（- **部分名** 格式）',
+};
+
+/**
+ * 给 issue 补 fix_hint——把 {id} {dep} 等占位符替换成实际值。
+ */
+function addFixHint(issue) {
+  const template = FIX_HINTS[issue.type];
+  if (!template) return issue;
+  let hint = template;
+  // 提取 id 里的实际 Intent ID（issue.id 可能是 "INT-001" 或 "INT-002→INT-001" 等）
+  const idMatch = String(issue.id).match(/(INT-\d+)/);
+  if (idMatch) hint = hint.replace(/\{id\}/g, idMatch[1]);
+  // 提取 dep（从 msg 里找 depends_on 后的 Intent ID）
+  const depMatch = issue.msg && issue.msg.match(/依赖.*?(INT-\d+)/);
+  if (depMatch) hint = hint.replace(/\{dep\}/g, depMatch[1]);
+  return { ...issue, fix_hint: hint };
+}
+
 /**
  * 项目健康检查。
  * @param {string} versionDir — 当前版本目录
@@ -118,7 +186,8 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
 
   if (!mapState.validMap) {
     appendPhilosophyDiagnostics(issues, philosophyDir);
-    return { issues, summary: summarizeIssues(issues) };
+    const issuesWithHints = issues.map(addFixHint);
+    return { issues: issuesWithHints, summary: summarizeIssues(issuesWithHints) };
   }
 
   const { intents } = mapState.validMap;
@@ -193,28 +262,29 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
 
   // 7. 验证脚本可执行性：检查 verification_method 引用的脚本/目录是否存在
   const projectDir = join(versionDir, '..', '..');
+  const pm = detectPackageManager(projectDir);
   for (const [id, intent] of Object.entries(intents)) {
     const vm = getIntentVerificationMethod(intent);
     if (!vm) continue;
-    // 检测 npm test 引用
-    if (vm.includes('npm test') || vm.includes('npm run test')) {
+    // 检测任意包管理器的 test 引用（npm/pnpm/bun/yarn）
+    const pmTestRe = new RegExp(`(?:${PM_ALIASES.join('|')})\\s+(?:run\\s+)?test`);
+    if (pmTestRe.test(vm)) {
       const pkgPath = join(projectDir, 'package.json');
       if (!existsSync(pkgPath)) {
-        issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 npm test 但项目根没有 package.json` });
+        issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 test 但项目根没有 package.json` });
       } else {
         try {
           const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
           const testScript = pkg.scripts && pkg.scripts.test;
           if (!testScript) {
-            issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 npm test 但 package.json 没有 test 脚本` });
+            issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 test 但 package.json 没有 test 脚本` });
           } else {
             // 检查 test 脚本引用的目录/文件是否存在
-            // 常见模式: "node --test test/" / "mocha test/" / "jest" 等
             const testDirMatch = testScript.match(/(?:--test|test)\s+(\S+)/);
             if (testDirMatch) {
               const testTarget = testDirMatch[1].replace(/['"]/g, '');
               if (!existsSync(join(projectDir, testTarget))) {
-                issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 npm test 但 test 脚本引用的 ${testTarget} 不存在` });
+                issues.push({ id, type: 'test_script_missing', severity: 'medium', msg: `${id} verification_method 要求 test 但 test 脚本引用的 ${testTarget} 不存在` });
               }
             }
           }
@@ -248,7 +318,8 @@ export function doctor(versionDir, verificationsDir, philosophyDir) {
   }
 
   appendPhilosophyDiagnostics(issues, philosophyDir);
-  return { issues, summary: summarizeIssues(issues) };
+  const issuesWithHints = issues.map(addFixHint);
+  return { issues: issuesWithHints, summary: summarizeIssues(issuesWithHints) };
 }
 
 function appendPhilosophyDiagnostics(issues, philosophyDir) {
@@ -331,11 +402,16 @@ export function contextSummary(versionDir, verificationsDir, philosophyDir) {
   const pending = mapState.valid ? getPendingVerifications(versionDir, verificationsDir) : [];
   const { issues } = doctor(versionDir, verificationsDir, philosophyDir);
 
+  // 区分模板阶段问题（待填充）和真实损坏
+  const templateIssues = issues.filter((i) => i.is_template || i.type === 'intent_map_template' || i.type === 'inspiration_source' || i.type === 'part_decomposition');
+  const realIssues = issues.filter((i) => !templateIssues.includes(i));
+
   const risks = [];
-  const fatalCount = issues.filter((i) => i.severity === 'fatal').length;
-  const highCount = issues.filter((i) => i.severity === 'high').length;
+  const fatalCount = realIssues.filter((i) => i.severity === 'fatal').length;
+  const highCount = realIssues.filter((i) => i.severity === 'high').length;
   if (fatalCount > 0) risks.push(`${fatalCount} 个致命问题（Intent Map 损坏/循环依赖）`);
   if (highCount > 0) risks.push(`${highCount} 个高严重度问题（状态不一致/孤儿引用）`);
+  if (templateIssues.length > 0) risks.push(`${templateIssues.length} 个待填充（模板未产出，需 Weaver/Architect 填充）`);
   if (status.counts.blocked > 0) risks.push(`${status.counts.blocked} 个阻塞 Intent`);
 
   return {
@@ -349,7 +425,7 @@ export function contextSummary(versionDir, verificationsDir, philosophyDir) {
     pending_verifications: pending,
     inconsistent_states: issues.filter((i) => i.type === 'in_progress_no_record' || i.type === 'completed_no_record').map((i) => i.id),
     risks,
-    healthy: issues.length === 0,
+    healthy: realIssues.length === 0,
   };
 }
 

package/cli/src/guide.js

@@ -6,7 +6,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { readCurrentPointer } from './version.js';
 import { loadIntentMap } from './intent-map.js';
-import { isAutoOn, writeHeartbeat, needsHumanReview } from './auto.js';
+import { isAutoOn, getAutoMode, writeHeartbeat, needsHumanReview } from './auto.js';
 
 /**
  * 检测文件是否还是模板（未填充真实内容）。
@@ -36,17 +36,78 @@ function isTemplate(filePath) {
 /**
  * 诊断项目当前阶段。
  * @param {string} projectDir — 项目根目录
- * @returns {{ stage: string, stage_num: number, details: object, auto: boolean, next_action: string, next_command: string, message: string, needs_human_review: boolean }}
- */
-export function guideProject(projectDir, options = {}) {
-  const cwd = projectDir || process.cwd();
-  const loomRoot = join(cwd, '.loom');
-  const auto = isAutoOn(loomRoot);
-  const result = diagnoseStage(cwd, loomRoot, auto);
-  // 统一后处理：写心跳 + 加 AUTO 提示词 + 判断是否需要人类 review
-  if (existsSync(loomRoot) && !options.dryRun) {
-    try {
-      writeHeartbeat(loomRoot, {
+ * @returns {{ stage: string, stage_num: number, details: object, auto: boolean, next_action: string, next_command: string, message: string, needs_human_review: boolean }}
+ */
+export function guideProject(projectDir, options = {}) {
+  const cwd = projectDir || process.cwd();
+  const loomRoot = join(cwd, '.loom');
+  const autoMode = getAutoMode(loomRoot);
+  const auto = autoMode !== 'manual'; // 向后兼容 boolean
+  const result = diagnoseStage(cwd, loomRoot, auto);
+  result.auto_mode = autoMode;
+
+  // 按 stage 补充可执行信息：要读什么、要产出什么、完成后跑什么校验
+  const current = result.details.version || 'v1';
+  const stageMeta = {
+    not_initialized: {
+      inputs: [],
+      outputs: ['.loom/v1/'],
+      verify_command: 'loom guide',
+    },
+    no_version: {
+      inputs: [],
+      outputs: ['.loom/v1/'],
+      verify_command: 'loom guide',
+    },
+    need_philosophy: {
+      inputs: ['meta/PHILOSOPHY_WEAVER.md', 'meta/BASELINE.md', 'dimensions/PART_DECOMPOSITION.md', 'dimensions/SEARCH_METHODOLOGY.md'],
+      outputs: [`.loom/${current}/00_PHILOSOPHY/PRODUCT_PHILOSOPHY.md`, `.loom/${current}/00_PHILOSOPHY/ENGINEERING_CREED.md`, `.loom/${current}/00_PHILOSOPHY/DECISION_RUBRIC.md`],
+      verify_command: 'loom philosophy check',
+    },
+    need_vision: {
+      inputs: ['roles/visionary.md', `.loom/${current}/00_PHILOSOPHY/`],
+      outputs: [`.loom/${current}/01_VISION.md`],
+      verify_command: 'loom guide',
+    },
+    need_architecture: {
+      inputs: ['roles/architect.md', `.loom/${current}/01_VISION.md`],
+      outputs: [`.loom/${current}/02_ARCHITECTURE.md`, `.loom/${current}/04_INTENT_MAP.json`],
+      verify_command: 'loom doctor',
+    },
+    intent_map_broken: {
+      inputs: [`.loom/${current}/04_INTENT_MAP.json`],
+      outputs: [`.loom/${current}/04_INTENT_MAP.json`],
+      verify_command: 'loom intent validate',
+    },
+    in_loop: {
+      inputs: ['roles/forge.md', 'roles/keeper.md', `.loom/${current}/04_INTENT_MAP.json`],
+      outputs: ['代码文件', `.loom/${current}/verifications/INT-*.json`],
+      verify_command: 'loom verify pending',
+    },
+    ready_for_loop: {
+      inputs: ['roles/forge.md', 'roles/keeper.md', `.loom/${current}/04_INTENT_MAP.json`],
+      outputs: ['代码文件', `.loom/${current}/verifications/INT-*.json`],
+      verify_command: 'loom verify pending',
+    },
+    all_done: {
+      inputs: [],
+      outputs: [],
+      verify_command: 'loom doctor',
+    },
+    unknown: {
+      inputs: [],
+      outputs: [],
+      verify_command: 'loom doctor',
+    },
+  };
+  const meta = stageMeta[result.stage] || {};
+  result.inputs = meta.inputs || [];
+  result.outputs = meta.outputs || [];
+  result.verify_command = meta.verify_command || null;
+  // 统一后处理：写心跳 + 加 AUTO 提示词 + 判断是否需要人类 review
+  if (existsSync(loomRoot) && !options.dryRun) {
+    try {
+      writeHeartbeat(loomRoot, {
         stage: result.stage,
         stage_num: result.stage_num,
         next_command: result.next_command,
@@ -57,13 +118,19 @@ export function guideProject(projectDir, options = {}) {
   result.needs_human_review = needsHumanReview(loomRoot, result.stage_num);
   // 在 message 末尾加 AUTO 提示
   if (result.stage_num > 0 && result.stage_num < 4) {
-    result.message += auto
-      ? '\n\n> ⚠ 这是设计阶段（哲学/愿景/架构），即使 AUTO 模式开启也需要人类 review 后再继续。'
-      : '\n\n> ⚠ AUTO 模式关闭——每步都需要人类确认后再继续。';
-  } else if (result.stage_num >= 4 && !auto) {
-    result.message += '\n\n> ⚠ AUTO 模式关闭——执行 next_command 后等人类确认再继续。';
-  } else if (result.stage_num >= 4 && auto) {
-    result.message += '\n\n> AUTO 模式开启——直接执行 next_command，无需人类确认。';
+    if (autoMode === 'auto-design') {
+      result.message += '\n\n> AUTO 模式 auto-design——设计阶段也自动执行，无需人类确认。';
+    } else if (autoMode === 'auto-loop') {
+      result.message += '\n\n> ⚠ 这是设计阶段（哲学/愿景/架构），auto-loop 模式下需要人类 review 后再继续。';
+    } else {
+      result.message += '\n\n> ⚠ AUTO 模式 manual——每步都需要人类确认后再继续。';
+    }
+  } else if (result.stage_num >= 4) {
+    if (auto) {
+      result.message += '\n\n> AUTO 模式开启——直接执行 next_command，无需人类确认。';
+    } else {
+      result.message += '\n\n> ⚠ AUTO 模式关闭——执行 next_command 后等人类确认再继续。';
+    }
   }
   return result;
 }
@@ -145,11 +212,11 @@ function diagnoseStage(cwd, loomRoot, auto) {
   }
 
   // 状态 4-7: Intent Map 已设计，根据 Intent 状态判断
-  let intentMap;
-  let intents;
-  try {
-    intentMap = loadIntentMap(versionDir);
-    intents = intentMap.intents;
+  let intentMap;
+  let intents;
+  try {
+    intentMap = loadIntentMap(versionDir);
+    intents = intentMap.intents;
   } catch (e) {
     return {
       stage: 'intent_map_broken',
@@ -220,7 +287,7 @@ function diagnoseStage(cwd, loomRoot, auto) {
   if (counts.needs_review > 0) {
     const reviewIds = allIntents.filter((i) => i.status === 'needs_review').map((i) => i.id);
     // 读 _meta.pass_count 收敛趟计数（最大 3 趟）
-    const passCount = intentMap._meta?.pass_count || 1;
+    const passCount = intentMap._meta?.pass_count || 1;
     const MAX_PASSES = 3;
     const isOverLimit = passCount > MAX_PASSES;
     const passMsg = ` [Pass ${passCount}/${MAX_PASSES}]`;

package/cli/src/philosophy.js

@@ -85,20 +85,22 @@ function parseInspirationSources(content) {
 
   // 匹配 - xxx / * xxx / 1. xxx / 2. xxx 等
   const ITEM_RE = /^\s*(?:[-*]|\d+\.)\s+/;
+  // URL 匹配：https:// / file:// / local:./path / local:/abs/path
+  const URL_RE = /(?:https?:|file:)[\/]+[^\s）)]+|local:[^\s）)]+/g;
 
   for (const line of lines) {
     if (ITEM_RE.test(line)) {
       // 新条目
       if (currentItem) items.push(currentItem);
       const raw = line.replace(ITEM_RE, '').trim();
-      const urls = [...raw.matchAll(/https?:\/\/[^\s）)]+/g)].map((m) => m[0]);
+      const urls = [...raw.matchAll(URL_RE)].map((m) => m[0]);
       const name = raw.replace(/\*\*/g, '').split(/[（(——]/)[0].trim();
       const hasReason = REASON_KEYWORDS.some((kw) => raw.includes(kw));
       currentItem = { raw, name, urls, hasReason };
     } else if (currentItem && line.trim()) {
       // 多行条目的续行
       currentItem.raw += ' ' + line.trim();
-      const newUrls = [...line.matchAll(/https?:\/\/[^\s）)]+/g)].map((m) => m[0]);
+      const newUrls = [...line.matchAll(URL_RE)].map((m) => m[0]);
       currentItem.urls.push(...newUrls);
       if (REASON_KEYWORDS.some((kw) => line.includes(kw))) {
         currentItem.hasReason = true;

package/cli/src/verify.js

@@ -92,14 +92,14 @@ export function writeVerification(verificationsDir, record) {
     data = { intent_id: record.intent_id, records: [] };
   }
 
-  // 计算轮次和连续 deviated 计数。规范要求中间出现 passed/blocked 后重置。
-  const round = data.records.length + 1;
-  const recordsWithCurrent = [...data.records, record];
-  let deviatedCount = 0;
-  for (let i = recordsWithCurrent.length - 1; i >= 0; i--) {
-    if (recordsWithCurrent[i].verdict !== 'deviated') break;
-    deviatedCount++;
-  }
+  // 计算轮次和连续 deviated 计数。规范要求中间出现 passed/blocked 后重置。
+  const round = data.records.length + 1;
+  const recordsWithCurrent = [...data.records, record];
+  let deviatedCount = 0;
+  for (let i = recordsWithCurrent.length - 1; i >= 0; i--) {
+    if (recordsWithCurrent[i].verdict !== 'deviated') break;
+    deviatedCount++;
+  }
 
   // 追加新记录
   data.records.push({
@@ -134,6 +134,36 @@ export function getVerificationHistory(verificationsDir, intentId) {
   return readJsonFile(filePath, '验证记录');
 }
 
+/**
+ * 快捷创建验证记录——Agent 不用手动构造完整 JSON。
+ * 内部用 summary 填充四个维度的 evidence，生成标准记录格式。
+ * @param {string} verificationsDir — verifications/ 目录路径
+ * @param {string} intentId — 如 "INT-001"
+ * @param {string} verdict — 'passed' | 'deviated' | 'blocked'
+ * @param {string} summary — 验证摘要（也会作为四个维度的 evidence）
+ * @param {object} [extras]
+ * @param {string} [extras.reproduction_command] — 复现命令
+ * @param {string} [extras.deviation_detail] — 偏离说明（deviated 时）
+ * @returns {{ filePath: string, round: number, deviated_count: number, should_escalate: boolean }}
+ */
+export function createQuickVerification(verificationsDir, intentId, verdict, summary, extras = {}) {
+  const timestamp = new Date().toISOString();
+  // 用 summary 填充四个维度的 evidence——快捷命令不要求 Agent 逐维度写
+  const dimensions = {};
+  for (const dim of REQUIRED_DIMENSIONS) {
+    dimensions[dim] = { verdict, evidence: summary };
+  }
+  return writeVerification(verificationsDir, {
+    intent_id: intentId,
+    verdict,
+    timestamp,
+    summary,
+    dimensions,
+    reproduction_command: extras.reproduction_command || null,
+    deviation_detail: extras.deviation_detail || null,
+  });
+}
+
 /**
  * 返回所有待验证的 Intent（有实现产物但还没验证记录的）。
  * 需要传入 Intent Map 来判断哪些 Intent 是 in_progress。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/loom",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "LOOM — 哲学驱动开发框架。Agent 通过 CLI 访问 Intent Map / 哲学 / 验证记录，不直接读文件",
   "type": "module",
   "bin": {