@haaaiawd/loom 0.7.0 → 0.8.0

package/README.md

@@ -57,12 +57,14 @@ Keeper 验证（四维度：意图忠实度 / 哲学一致性 / 底线合规 /
 
 ### 步骤 0：诊断当前阶段
 
-```bash
-loom guide
-```
-
-guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
-Agent 每完成一步都跑 guide 确认下一步。
+```bash
+loom guide
+loom guide --dry-run  # 只读诊断，不写 heartbeat
+```
+
+guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
+Agent 每完成一步都跑 guide 确认下一步。
+如果只是审计或探测，不希望产生任何状态写入，用 `loom guide --dry-run`。
 
 ### AUTO 模式
 
@@ -145,24 +147,34 @@ loom intent status
 
 ### 步骤 6：人类预览
 
-```bash
-loom preview
-```
-
-输出提示词，Agent 按提示词读 `.loom/` 文件、拆解信息、生成 HTML 可视化预览。
-人类用浏览器打开 `loom-preview.html` 看全局——哲学、愿景、架构、Intent 进度、验证历史。
-这是只读投影，修改请编辑源文件后重新生成。
+```bash
+loom preview status   # 先检查 preview 是否新鲜
+loom preview          # 新鲜则打开；过期则提示重新生成
+loom preview --regen  # 输出生成提示词，让 Agent 重写 loom-preview.html
+```
+
+preview 是人类总览用的只读投影：哲学、愿景、架构、Intent 进度、验证历史。
+`loom preview` 会用 mtime 检查 `.loom/v{N}` 是否比 `loom-preview.html` 更新：
+- 新鲜：直接打开 `loom-preview.html`
+- 过期：不打开旧投影，提示 `loom preview --regen`
+- 强行打开旧投影：`loom preview --stale`
+
+Agent 在用户说"看看进度 / 打开 preview / 看全局"时，先跑 `loom preview status`。
 
 **CLI 命令一览**：
 
 | 命令 | 用途 |
 |---|---|
-| `loom init` | 初始化项目 |
-| `loom guide` | 诊断当前阶段，输出下一步引导 |
-| `loom auto on\|off\|status` | AUTO 模式开关 |
-| `loom activate <role>` | 输出角色激活提示词 |
-| `loom preview` | 输出提示词，AI 生成 HTML 可视化预览 |
-| `loom help <topic>` | 分层指南（workflow\|concepts\|loop\|version\|doctor） |
+| `loom init` | 初始化项目 |
+| `loom guide` | 诊断当前阶段，输出下一步引导 |
+| `loom guide --dry-run` | 只读诊断当前阶段，不写 heartbeat |
+| `loom auto on\|off\|status` | AUTO 模式开关 |
+| `loom activate <role>` | 输出角色激活提示词 |
+| `loom preview` | 打开新鲜 HTML 预览；过期时提示重新生成 |
+| `loom preview status` | 检查 `loom-preview.html` 是否存在、是否新鲜 |
+| `loom preview --regen` | 输出提示词，让 Agent 重写 HTML 预览 |
+| `loom preview --stale` | 强行打开过期预览 |
+| `loom help <topic>` | 分层指南（workflow\|concepts\|loop\|version\|doctor\|preview） |
 | `loom version list` | 列出所有版本（* 标记当前） |
 | `loom version new` | 创建新版本 + 自动切换（Major 升级） |
 | `loom version use <v>` | 切换当前版本 |

package/cli/bin/loom.js

@@ -11,7 +11,7 @@ import { findLoomRoot, findVersionDir, readCurrentPointer } from '../src/shared/
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 import { getNextIntent, getStatus, getDependencyGraph, getIntent, loadIntentMap, updateIntentStatus, getNarrative } from '../src/intent-map.js';
-import { getPhilosophy, listPhilosophyFiles } from '../src/philosophy.js';
+import { getPhilosophy, listPhilosophyFiles, validateInspirationSources, validatePartDecomposition } from '../src/philosophy.js';
 import { writeVerification, getVerificationHistory, getPendingVerifications, listVerifications, getVerificationContract } from '../src/verify.js';
 import { initProject } from '../src/init.js';
 import { activateRole } from '../src/activate.js';
@@ -20,7 +20,7 @@ import { doctor, contextSummary, traceIntent, reverseDep, reverseRef } from '../
 import { getHelpTopic, listHelpTopics } from '../src/help.js';
 import { guideProject } from '../src/guide.js';
 import { isAutoOn, autoOn, autoOff, autoStatus } from '../src/auto.js';
-import { generatePreviewPrompt } from '../src/preview.js';
+import { generatePreviewPrompt, getPreviewStatus } from '../src/preview.js';
 
 // ─── 路径解析 ──────────────────────────────────────────
 // findLoomRoot / findVersionDir / readCurrentPointer 已提取到 shared/paths.js
@@ -180,8 +180,38 @@ try {
         case 'list':
           output(listPhilosophyFiles(getPhilosophyDir(versionDir)));
           break;
+        case 'check': {
+          const philDir = getPhilosophyDir(versionDir);
+          const inspiration = validateInspirationSources(philDir);
+          const decomposition = validatePartDecomposition(philDir);
+          const allIssues = [...inspiration.issues, ...decomposition.issues];
+          const allPassed = inspiration.passed && decomposition.passed;
+
+          if (allPassed) {
+            console.log('✓ 哲学文档校验通过');
+            console.log('  灵感来源:');
+            for (const { file, sources } of inspiration.sources) {
+              console.log(`    ${file}: ${sources.length} 个源`);
+            }
+            console.log('  实现部分拆解:');
+            for (const part of decomposition.parts) {
+              console.log(`    - ${part}`);
+            }
+          } else {
+            const high = allIssues.filter((i) => i.severity === 'high').length;
+            const medium = allIssues.filter((i) => i.severity === 'medium').length;
+            console.log(`✗ 哲学文档校验未通过（${allIssues.length} 个问题: ${high} high, ${medium} medium）`);
+            for (const issue of allIssues) {
+              const icon = issue.severity === 'high' ? '⚠' : '·';
+              console.log(`  ${icon} [${issue.severity}] ${issue.msg}`);
+            }
+            console.log('\n参见 meta/PHILOSOPHY_WEAVER.md + dimensions/PART_DECOMPOSITION.md + dimensions/SEARCH_METHODOLOGY.md。');
+            exit(1);
+          }
+          break;
+        }
         default:
-          die(`未知子命令: philosophy ${sub}\n用法: loom philosophy [get <anchor>|list]`);
+          die(`未知子命令: philosophy ${sub}\n用法: loom philosophy [get <anchor>|list|check]`);
       }
       break;
     }
@@ -338,12 +368,16 @@ try {
       break;
     }
 
-    case 'guide': {
-      const result = guideProject(cwd());
-      console.log(`阶段 ${result.stage_num}: ${result.stage}`);
-      if (result.auto) {
-        console.log(`模式: AUTO（自动执行，不等确认）`);
-      } else {
+    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(`模式: 手动（每步需用户确认）`);
       }
       console.log(`\n${result.message}`);
@@ -395,15 +429,39 @@ try {
       break;
     }
 
-    case 'preview': {
-      const previewFile = join(cwd(), 'loom-preview.html');
-      const hasPreview = existsSync(previewFile);
-      const regenOnly = argv.includes('--regen') || argv.includes('-r');
-
-      // 已有 HTML 且没指定 --regen：直接打开浏览器
-      if (hasPreview && !regenOnly) {
-        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') {
@@ -412,9 +470,9 @@ try {
           spawn('xdg-open', [target], { detached: true, stdio: 'ignore' }).unref();
         }
         console.log(`已打开浏览器: ${previewFile}`);
-        console.log(`重新生成: loom preview --regen`);
-        break;
-      }
+        console.log(status.fresh ? `重新生成: loom preview --regen` : `已打开旧 preview。重新生成: loom preview --regen`);
+        break;
+      }
 
       // 没有 HTML 或指定 --regen：输出提示词让 AI 生成
       const prompt = generatePreviewPrompt();
@@ -450,9 +508,10 @@ To Human:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 用法:
-  loom init                     初始化项目（创建 .loom/v1/ 骨架 + 模板）
-  loom guide                    诊断当前阶段，输出下一步引导
-  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             列出所有版本（* 标记当前）
@@ -474,12 +533,15 @@ To Human:
 
   loom doctor                   项目健康检查（一致性+孤儿引用+循环依赖+僵尸）
   loom context                  上下文摘要（进度+下一步+待验证+风险）
-  loom preview                  已有 HTML 则打开浏览器，否则输出提示词让 AI 生成
-  loom preview --regen          强制重新输出提示词（让 AI 重新生成 HTML）
-  loom help <topic>             分层指南（workflow|concepts|loop|version|doctor）
+  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          列出哲学文档文件
+  loom philosophy check         校验灵感来源质量（源数量/多样性/理由）
 
   loom verify contract <id>     返回某 Intent 的验收契约（解析引用）
   loom verify history <id>      返回某 Intent 验证历史

package/cli/help/doctor.md

@@ -6,7 +6,7 @@
 loom doctor
 \`\`\`
 
-检测 6 类问题：
+检测 7 类问题：
 
 | 问题类型 | 严重度 | 说明 |
 |---|---|---|
@@ -15,9 +15,41 @@ loom doctor
 | orphan_dependency | high | depends_on 引用不存在的 Intent |
 | completed_no_record | high | completed 但无验证记录 |
 | completed_depends_blocked | high | completed 依赖 blocked 的 Intent |
+| inspiration_source | high/medium | 灵感来源质量不达标（源太少/全是 Wikipedia/缺理由） |
+| part_decomposition | high/medium | 缺少实现部分拆解清单（Weaver 跳过了拆解步骤） |
 | in_progress_no_record | medium | in_progress 但无验证记录（可能中断） |
 | zombie | medium | in_progress/blocked 超过 7 天无活动 |
 
+## 灵感来源校验
+
+\`\`\`bash
+loom philosophy check
+\`\`\`
+
+单独校验哲学文档的灵感来源质量。防止 Weaver 从训练数据"背"几个名字就交差。
+
+校验规则：
+- 至少 3 个独立源
+- 至少 2 个非 Wikipedia 链接
+- 每个源必须有选取理由（萃取/转译/启发关系）
+- Wikipedia 占比不超过 70%
+
+不达标时，需要重新织造哲学——真正走搜索漏斗，找原著、论文、工程博客等深度源。
+
+## 实现部分拆解校验
+
+\`\`\`bash
+loom philosophy check
+\`\`\`
+
+同时校验哲学文档是否包含"实现部分清单"——Weaver 是否按 PART_DECOMPOSITION.md 拆解了项目的实现部分。
+
+校验规则：
+- 哲学文档中必须有"实现部分清单"章节（或"部分拆解""Part Decomposition"等）
+- 至少识别到 2 个实现部分（小项目建议 3-5 个，大项目 6-10 个）
+
+缺少时，说明 Weaver 跳过了拆解步骤，需要重新织造——按 PART_DECOMPOSITION.md 的方法论识别项目的实现部分。
+
 ## 上下文摘要
 
 \`\`\`bash
@@ -25,9 +57,28 @@ loom context
 \`\`\`
 
 一条命令获取：进度 + 下一个 Intent + 待验证 + 不一致项 + 风险。
-Agent 重启后先跑这个，快速知道"我在哪、接下来做什么"。
-
-## 崩溃恢复
+Agent 重启后先跑这个，快速知道"我在哪、接下来做什么"。
+
+## 只读阶段诊断
+
+\`\`\`bash
+loom guide --dry-run
+\`\`\`
+
+用于审计、子代理预演、只读探测。它输出和 `loom guide` 同样的阶段判断，但不写 `.loom/heartbeat.json`。
+
+## Preview 新鲜度诊断
+
+\`\`\`bash
+loom preview status
+\`\`\`
+
+检查 `loom-preview.html` 是否比当前 `.loom/v{N}` 源文件更新。人类要求看 preview 时，Agent 先跑这个命令：
+- `fresh=true`：可以 `loom preview`
+- `fresh=false`：不要打开旧投影，先 `loom preview --regen`
+- 必须看旧投影：`loom preview --stale`
+
+## 崩溃恢复
 
 ### Forge 崩溃（Intent 留在 in_progress）
 
@@ -67,4 +118,4 @@ LOOM 假设项目使用 Git。所有 .loom/ 下的文件都应纳入版本控制
 - 误操作 → 从 Git 回滚
 - 变更追溯 → Git log 就是审计日志
 
-LOOM 不内置备份、审计、回滚——这些是版本控制的职责。
+LOOM 不内置备份、审计、回滚——这些是版本控制的职责。

package/cli/help/preview.md

@@ -0,0 +1,59 @@
+## Preview 指南
+
+preview 是给人看的只读投影。它把 `.loom/v{N}` 的哲学、愿景、架构、Intent Map 和验证记录压缩成 `loom-preview.html`。
+
+## 常用命令
+
+```bash
+loom preview status   # 只读检查 preview 是否存在、是否新鲜
+loom preview          # 新鲜则打开；过期则提示重新生成
+loom preview --regen  # 输出生成提示词，让 Agent 重写 loom-preview.html
+loom preview --stale  # 强行打开过期 preview
+loom preview --help   # 查看 preview 命令用法
+```
+
+## Agent 使用规则
+
+当用户说“看看进度”“打开 preview”“让我看全局”时：
+
+1. 先运行 `loom preview status`
+2. 如果 `fresh=true`，运行 `loom preview`
+3. 如果 `fresh=false`，不要打开旧页面，运行 `loom preview --regen`
+4. 按提示词读取 `.loom/`，重写 `loom-preview.html`
+5. 再运行 `loom preview` 打开
+
+只有用户明确说要看旧版时，才使用 `loom preview --stale`。
+
+## 新鲜度判断
+
+LOOM 使用最小 mtime 机制，不做 hash：
+
+```text
+preview_mtime = loom-preview.html 修改时间
+source_latest_mtime = 当前 .loom/v{N} 核心源文件最新修改时间
+
+preview_mtime >= source_latest_mtime → fresh
+否则 → stale
+```
+
+核心源文件包括：
+- `00_PHILOSOPHY/`
+- `01_VISION.md`
+- `02_ARCHITECTURE.md`
+- `03_DECISIONS/`
+- `04_INTENT_MAP.json`
+- `05_VERIFICATION.md`
+- `06_CHANGELOG.md`
+- `verifications/`
+
+## 为什么不直接打开旧 preview
+
+旧 preview 是假仪表盘风险：`.loom/` 已经进入 blocked、deviated 或完成新 Intent，但 HTML 仍显示旧状态。
+
+所以普通 `loom preview` 在 stale 时会停止并提示 `loom preview --regen`。
+
+## 生成责任
+
+当前 CLI 不直接生成 HTML。`loom preview --regen` 输出提示词，要求 Agent 读取 `.loom/` 后生成 `loom-preview.html`。
+
+CLI 负责判断是否过期和打开文件，Agent 负责把信息做成高质量视觉投影。

package/cli/help/workflow.md

@@ -8,8 +8,9 @@
 loom guide
 \`\`\`
 
-guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
-Agent 每完成一步都跑 guide 确认下一步。
+guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
+Agent 每完成一步都跑 guide 确认下一步。
+审计、预演、子代理探测时用 `loom guide --dry-run`，避免写 `.loom/heartbeat.json`。
 
 ## AUTO 模式
 
@@ -71,15 +72,20 @@ loom context            # 当前状态摘要
 每个 Intent 独立走一圈：选 → 实现 → 验证 → 闭合或修正。
 详细流程见 \`loom help loop\`。
 
-## 阶段 5：人类预览
-
-\`\`\`bash
-loom preview
-\`\`\`
-
-输出提示词，Agent 按提示词读 .loom/ 文件、拆解信息、生成 HTML 可视化预览。
-人类用浏览器打开 HTML 看全局——哲学、愿景、架构、Intent 进度、验证历史。
-这是只读投影，修改请编辑源文件后重新生成。
+## 阶段 5：人类预览
+
+\`\`\`bash
+loom preview status
+loom preview
+loom preview --regen
+\`\`\`
+
+preview 是给人看的只读投影。Agent 应先跑 `loom preview status`：
+- `fresh=true` → 运行 `loom preview` 打开
+- `fresh=false` → 运行 `loom preview --regen`，按提示词重写 `loom-preview.html`，再打开
+- 用户明确要看旧版 → `loom preview --stale`
+
+详细规则见 `loom help preview`。
 
 ## 阶段 6：版本演进（按需）
 
@@ -91,4 +97,4 @@ loom preview
 - **哲学是经线，意图是纬线** — 所有角色共享哲学锚点
 - **底线不可协商** — BASELINE 5 条 + 项目特定底线，角色激活时强制加载
 - **意图可回溯** — 每个 Intent 携带叙事，Keeper 独立验证忠实度
-- **文档开销不超过开发开销** — 小项目可以粗粒度，不必教条
+- **文档开销不超过开发开销** — 小项目可以粗粒度，不必教条