@haaaiawd/loom 0.1.0

package/cli/src/preview-prompt.md

@@ -0,0 +1,329 @@
+# LOOM Preview 生成提示词
+
+你的任务：读 `.loom/` 目录下当前版本的所有文件，把信息**拆解成关键要点**，用最合适的视觉和交互手段呈现成一份 HTML 页面，写到 `loom-preview.html`。
+
+## 核心原则：信息密度靠视觉手段，不靠文字堆砌
+
+类比 PPT——PPT 不是把报告文字排成幻灯片，是用图表、图示、对比、交互把信息密度压缩到人类一眼能消化的程度。能用图就不表，能交互就不静态，能一句话就不写一段。
+
+### 错误 vs 正确
+
+| 错误（文字堆砌） | 正确（视觉手段） |
+|---|---|
+| 哲学全文渲染成 HTML | 北极星一句话 + 信念用图标网格 + 反模式用红色警告卡 |
+| Intent 列表表格 | SVG 依赖图，节点颜色=状态，一眼看出阻塞链 |
+| 验证记录 JSON 列表 | 时间轴，通过绿色偏离红色，点击节点看证据 |
+| 进度用文字描述 | 环形进度图 + 大数字仪表盘 |
+| 状态分布用表格 | 堆叠条形图，一段横条按状态颜色分段 |
+| 决策原则用列表 | 对比表，两列并排突出差异 |
+| 意图叙事全文展示 | 卡片网格，每张卡片一句话，点击展开详情 |
+
+### 拆解粒度
+
+每个信息块回答一个问题，人类 3 秒内能消化：
+- 产品为什么存在？→ 北极星一句话
+- 产品信什么？→ 3-5 个图标 + 关键句
+- 什么绝对不做？→ 红色警告卡，每张一句
+- 项目推进到哪了？→ 环形进度图 + 数字仪表盘
+- 谁阻塞谁？→ SVG 依赖图
+- 这个 Intent 为什么存在？→ 一句话叙事
+- 验证历史怎么样？→ 时间轴
+
+如果一个块需要读超过 3 行文字才能理解，它太长了——换一种视觉形式。
+
+---
+
+## 去读哪些文件
+
+当前版本目录在 `.loom/current` 指针里（通常是 `.loom/v1/`）。读：
+
+| 文件 | 拆解出什么 |
+|---|---|
+| `00_PHILOSOPHY/*.md` | 北极星、核心信念、反模式、决策原则 |
+| `01_VISION.md` | 北极星、问题空间、意图叙事、不做什么 |
+| `02_ARCHITECTURE.md` | 关键决策、trade-offs |
+| `04_INTENT_MAP.json` | 依赖关系、状态分布、验收契约 |
+| `verifications/*.json` | 验证时间轴、通过/偏离、证据 |
+
+文件还是模板（含 `<!-- LOOM_TEMPLATE -->` 标记）时，对应区域显示提示："等待 {角色} 填充"。
+
+---
+
+## 一、视觉手段库——什么信息用什么呈现
+
+不同信息适合不同视觉手段。不要什么都用卡片或列表——选最能压缩信息密度的方式。
+
+### 图表类（数据可视化）
+
+**环形进度图** — 适合：整体完成度
+一个圆环，填充比例 = completed/total。中心显示百分比。比横条进度条更紧凑、更视觉化。纯 SVG 实现。
+
+**堆叠条形图** — 适合：状态分布
+一段横条，按状态颜色分段（完成绿/进行中黄/待执行灰/阻塞红）。一段条形展示所有状态比例，比 4 个数字卡片更紧凑。
+
+**柱状图** — 适合：各 Intent 的验证轮数、各系统的 Intent 数量
+SVG 矩形，高度=数值。适合比较多个项的数量。
+
+**燃尽图风格折线** — 适合：剩余 Intent 随时间变化（如果有历史数据）
+SVG 折线，横轴时间，纵轴剩余数。
+
+### 图示类（关系和结构）
+
+**SVG 依赖图** — 适合：Intent 之间的依赖关系
+节点是 Intent，边是 depends_on。拓扑排序布局，无依赖的在左，依赖链向右。节点颜色按状态编码。节点可点击，点击后侧边面板显示详情。
+
+**热力图网格** — 适合：Intent × 验证轮次的通过/偏离矩阵
+行是 Intent，列是验证轮次，格子颜色=通过(绿)/偏离(红)/未验证(灰)。一眼看出哪个 Intent 反复偏离。
+
+**树状图** — 适合：架构的系统层级、Intent 的依赖树
+展开/折叠的树形结构，点击节点展开子项。
+
+### 交互类（探索和筛选）
+
+**过滤面板** — 适合：Intent 列表、验证记录
+复选框按状态过滤（全部/待执行/进行中/完成/阻塞），输入框模糊搜索。过滤后实时更新视图。
+
+**点击下钻** — 适合：从概览到详情
+概览页点击某个 Intent → 展开详情面板或跳到详情区。不在一页摊开所有详情，按需展开。
+
+**Hover 工具提示** — 适合：图表上的额外信息
+鼠标悬停在依赖图节点上 → 显示 tooltip（ID + 状态 + 一句话叙事）。不点击就能预览。
+
+**Tab 切换** — 适合：大板块切换
+概览 / Intent Map / 哲学 / 愿景 / 架构。所有内容先渲染堆叠，JS 切换显示。
+
+**可折叠面板** — 适合：分层信息
+默认折叠显示标题，点击展开内容。用 `max-height` 过渡，不要 `display: none`。
+
+### 布局类（组织和对比）
+
+**仪表盘** — 适合：关键指标概览
+大数字 + 颜色编码。数字 24-32px，标签 12-13px。一眼看到状态。
+
+**对比表** — 适合：trade-offs、做什么 vs 不做什么
+两列或三列并排，突出差异。每列一个方向，行是对比维度。
+
+**卡片网格** — 适合：核心信念、意图叙事
+每张卡片一个要点，标题 + 一句话。网格排列，大小一致。卡片内不超过 3 行。
+
+**时间轴** — 适合：验证历史、项目演进
+横向或纵向，每个节点一个事件。通过绿色偏离红色，附证据摘要。
+
+**看板列** — 适合：按状态分组的 Intent
+四列：待执行 / 进行中 / 完成 / 阻塞。每列下面是该状态的 Intent 卡片。一眼看出分布。
+
+**清单** — 适合：反模式、不做什么、决策原则
+每条一行 + 一句话理由。反模式用红色警告样式。
+
+### 标记类（状态和强调）
+
+**状态徽章** — 适合：Intent 状态
+颜色 + 图标 + 文字（不只靠颜色，色盲友好）：
+- 完成 = 绿色 + ✓
+- 进行中 = 黄色 + ◐
+- 待执行 = 灰色 + ○
+- 阻塞 = 红色 + ✕
+- 需复审 = 蓝色 + ?
+
+**高亮引用** — 适合：北极星、关键宣言
+大字号 + 左侧色条 + 引用样式。视觉上从周围内容跳出来。
+
+---
+
+## 二、页面结构
+
+### 顶部：一屏概览
+
+人类打开第一眼看到全局：
+
+- 项目名 + 版本号
+- 北极星一句话（高亮引用样式，最醒目）
+- **环形进度图**：完成 X/Y（百分比）
+- **堆叠条形图**：状态分布（一段条形展示所有状态比例）
+- **数字仪表盘**：进行中 N、阻塞 M（大数字 + 颜色）
+
+### Intent Map 区域
+
+项目推进到哪了——用多种手段呈现不同维度：
+
+- **SVG 依赖图**：依赖链和阻塞点
+- **看板列**：按状态分组的 Intent 卡片（待执行/进行中/完成/阻塞）
+- **过滤面板**：状态过滤 + 模糊搜索（Intent 多时）
+- **点击下钻**：点击节点或卡片 → 侧边详情面板（叙事、验收契约、哲学锚点、验证历史）
+
+### 哲学区域
+
+"我们信什么"——拆解成视觉块：
+
+- **北极星**：高亮引用，一句话
+- **核心信念**：卡片网格，每张一个图标 + 关键句
+- **不可妥协的价值**：清单，每条一句话 + 一句话理由
+- **反模式**：红色警告卡，每张一句
+- **决策原则**：对比表或清单，遇到冲突时怎么取舍
+
+### 愿景区域
+
+"我们要去哪"——拆解：
+
+- **北极星**：和哲学呼应
+- **问题空间**：一段话
+- **意图叙事**：卡片网格，每个意图一张卡片，一句话"为什么存在"，点击展开详情
+- **不做什么**：清单，和"做什么"同样醒目
+
+### 架构区域（如果有）
+
+"怎么实现"——拆解：
+
+- **关键决策对比表**：每个决策两列对比（选了什么 / 放弃了什么）
+- **trade-offs 清单**：每条一句话
+
+### 验证历史区域（如果有）
+
+"质量怎么样"——拆解：
+
+- **时间轴**：每次验证一个节点，通过/偏离用颜色区分，点击看证据
+- **热力图网格**（Intent 多时）：Intent × 验证轮次矩阵，一眼看出哪个反复偏离
+- **偏离清单**：哪些 Intent 偏离了，证据是什么
+
+### 底部
+
+- 提醒：这是只读投影，修改请编辑源文件后运行 `loom preview` 重新生成
+- 可选：一个"复制项目状态"按钮
+
+---
+
+## 三、符合人类直觉
+
+### 视觉权重
+
+最重要的信息最大、最醒目。次要信息小、灰、退后：
+- 北极星 → 全页最大字号
+- 进度数字 → 大数字 + 颜色
+- Intent ID → 中等字号，等宽字体
+- 验收契约正文 → 小字，可展开才显示
+- 辅助说明 → 最小字，灰色
+
+不要所有文字一样大。人类靠大小判断重要性。
+
+### 渐进披露
+
+不要一次把所有信息摊开。先给摘要，想看详情再展开：
+- Intent 卡片默认折叠，只显示 ID + 状态 + 一句话
+- 点击展开后显示：意图叙事、验收契约、哲学锚点、验证历史
+- 图表上 Hover 显示 tooltip 预览，点击才展开完整详情
+
+### 信息分组
+
+相关信息放一起，不相关的用空间分隔：
+- 进度概览自成一个区块
+- Intent 依赖图 + 详情面板自成一个区块
+- 哲学、愿景、架构各自独立区块
+- 区块之间用足够留白分隔（32-48px），不要挤
+
+---
+
+## 四、视觉设计原则
+
+参考 Anthropic 和 CopilotKit 的 Generative UI 设计系统：
+
+### 平面克制
+
+- **无渐变**：纯色背景
+- **无阴影**：用边框区分层次
+- **无模糊**：不要 filter: blur
+- **无发光**：不要 text-shadow 或 glow
+- **无装饰性 emoji**：用 CSS 形状或 SVG 路径做图标
+
+### 字体克制
+
+- 只用两种字重：400（正文）和 500（标题/强调）
+- 不要 600、700——太重，破坏平面感
+- 标题用句首大写，不要全大写
+- 正文不要句中加粗，用 `code style` 标记实体名
+- 最小字号 12px
+
+### 边框和间距
+
+- 边框 `1px solid`
+- 卡片圆角 8-12px
+- 卡片内边距 16-20px
+- 卡片之间间距 16-24px
+- 区块之间间距 32-48px——大间距区分大板块
+
+### CSS 变量
+
+```css
+:root {
+  --bg: ...;
+  --surface: ...;
+  --border: ...;
+  --text: ...;
+  --text-muted: ...;
+  --accent: ...;
+  --success: ...;
+  --warning: ...;
+  --danger: ...;
+}
+```
+
+不要在 HTML 里硬编码颜色。所有颜色引用变量。
+
+### 配色自定
+
+不要求暗色也不要求亮色。选你觉得让信息最易读的方案。关键是：
+- 背景和文字对比度足够（WCAG AA 标准）
+- 状态颜色区分明显
+- 不要花哨——信息是主角，视觉是配角
+
+---
+
+## 五、技术约束
+
+- **单文件**：所有 HTML/CSS/JS 内联，零外部依赖
+- **零构建**：双击即可在浏览器打开
+- **内联 SVG**：图表和依赖图直接写 `<svg>`，不用 `<img>` 或外部库
+- **语义化 HTML**：用 `<section>` `<nav>` `<article>` `<button>`
+- **响应式**：手机宽度下布局不崩（`@media (max-width: 768px)`）
+
+---
+
+## 六、质量检查清单
+
+生成前逐项确认：
+
+**信息密度**
+- [ ] 每个信息块用最合适的视觉手段，不是什么都用卡片或列表
+- [ ] 能用图表展示的数据不用表格
+- [ ] 能用图示展示的关系不用文字描述
+- [ ] 每个块 3 秒内能消化，不超过 3 行文字
+
+**功能**
+- [ ] 双击能在浏览器打开，不需要任何外部资源
+- [ ] SVG 依赖图节点颜色按状态编码
+- [ ] 点击 Intent 能展开详情
+- [ ] Tab 切换正常
+- [ ] 图表 Hover 有 tooltip（如果适用）
+
+**视觉**
+- [ ] 无渐变、无阴影、无模糊、无发光
+- [ ] 字重只有 400 和 500
+- [ ] 所有颜色用 CSS 变量
+- [ ] 边框统一 1px
+- [ ] 信息层次清晰（大字重要，小字次要）
+
+**可访问性**
+- [ ] `@media (prefers-reduced-motion: reduce)` 禁用动画
+- [ ] 对比度足够
+- [ ] 点击区域 ≥ 44px
+- [ ] 不仅靠颜色传达信息（颜色 + 图标 + 文字）
+
+**响应式**
+- [ ] 手机宽度下布局不崩
+- [ ] SVG 依赖图横向滚动
+- [ ] Tab 导航横向滚动
+
+---
+
+## 输出
+
+把 HTML 写到 `loom-preview.html`。完成后告诉用户文件路径。

package/cli/src/preview.js

@@ -0,0 +1,15 @@
+// preview — 输出提示词，让 AI 读 .loom/ 文件并生成 HTML
+// CLI 不收集数据、不生成 HTML。AI 自己读文件、重组信息、生成 HTML。
+// 因为都是同一个 Agent 负责的，它就在项目目录里，能直接读文件。
+
+import { readFileSync } from 'node:fs';
+
+const PROMPT_PATH = new URL('./preview-prompt.md', import.meta.url);
+
+/**
+ * 输出 preview 提示词。
+ * @returns {string}
+ */
+export function generatePreviewPrompt() {
+  return readFileSync(PROMPT_PATH, 'utf-8');
+}

package/cli/src/verify.js

@@ -0,0 +1,199 @@
+// verify.js — 验证记录的读写和查询
+// 验证记录存放在 .loom/v{N}/verifications/ 下，每个 Intent 一份 JSON + 一份 MD。
+
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** 合法判定结果 */
+const VALID_VERDICTS = ['passed', 'deviated', 'blocked', 'pending_human'];
+
+/**
+ * 写入一条验证记录（追加模式——同一 Intent 多次验证保留完整历史）。
+ * 文件格式: { intent_id, records: [{ round, verdict, timestamp, ... }] }
+ * @param {string} verificationsDir — verifications/ 目录路径
+ * @param {object} record — 验证记录
+ * @param {string} record.intent_id — 如 "INT-001"
+ * @param {string} record.verdict — passed | deviated | blocked
+ * @param {string} record.timestamp — ISO 8601
+ * @param {string} record.summary — 验证摘要
+ * @param {object} record.dimensions — 四个维度的验证结果
+ * @param {string} [record.deviation_detail] — 偏离说明（deviated 时）
+ * @param {boolean} [record.reset_suggested] — 是否建议重置上下文
+ * @returns {{ filePath: string, round: number, deviated_count: number, should_escalate: boolean }}
+ */
+export function writeVerification(verificationsDir, record) {
+  const errors = [];
+  if (!record.intent_id) errors.push('缺少 intent_id');
+  if (!record.verdict || !VALID_VERDICTS.includes(record.verdict)) {
+    errors.push(`verdict 非法: "${record.verdict}" (合法: ${VALID_VERDICTS.join('|')})`);
+  }
+  if (!record.timestamp) errors.push('缺少 timestamp');
+  if (!record.dimensions) errors.push('缺少 dimensions（四个维度结果）');
+  if (errors.length > 0) {
+    throw new Error(`验证记录校验失败:\n  - ${errors.join('\n  - ')}`);
+  }
+
+  const filePath = join(verificationsDir, `${record.intent_id}.json`);
+
+  // 读取已有记录（如果有）
+  let data;
+  if (existsSync(filePath)) {
+    data = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } else {
+    data = { intent_id: record.intent_id, records: [] };
+  }
+
+  // 计算轮次和 deviated 计数
+  const round = data.records.length + 1;
+  const deviatedCount = data.records.filter(r => r.verdict === 'deviated').length
+    + (record.verdict === 'deviated' ? 1 : 0);
+
+  // 追加新记录
+  data.records.push({
+    round,
+    verdict: record.verdict,
+    timestamp: record.timestamp,
+    summary: record.summary,
+    dimensions: record.dimensions,
+    deviation_detail: record.deviation_detail,
+    reset_suggested: record.reset_suggested,
+  });
+
+  writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+
+  // 检查是否应该升级 blocked（连续 3 轮 deviated，默认值）
+  const DEVIATED_LIMIT = 3;
+  const shouldEscalate = record.verdict === 'deviated' && deviatedCount >= DEVIATED_LIMIT;
+
+  return { filePath, round, deviated_count: deviatedCount, should_escalate: shouldEscalate };
+}
+
+/**
+ * 读取某 Intent 的验证历史。
+ * @returns {{ intent_id: string, records: array } | null}
+ */
+export function getVerificationHistory(verificationsDir, intentId) {
+  const filePath = join(verificationsDir, `${intentId}.json`);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  const raw = readFileSync(filePath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+/**
+ * 返回所有待验证的 Intent（有实现产物但还没验证记录的）。
+ * 需要传入 Intent Map 来判断哪些 Intent 是 in_progress。
+ */
+export function getPendingVerifications(loomDir, verificationsDir) {
+  const intentMap = JSON.parse(
+    readFileSync(join(loomDir, '04_INTENT_MAP.json'), 'utf-8')
+  );
+  const pending = [];
+  for (const [id, intent] of Object.entries(intentMap.intents)) {
+    if (intent.status === 'in_progress') {
+      const hasRecord = existsSync(join(verificationsDir, `${id}.json`));
+      if (!hasRecord) pending.push(id);
+    }
+  }
+  return pending;
+}
+
+/**
+ * 列出所有验证记录文件。
+ */
+export function listVerifications(verificationsDir) {
+  if (!existsSync(verificationsDir)) return [];
+  return readdirSync(verificationsDir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace('.json', ''));
+}
+
+/**
+ * 获取某 Intent 的验证契约（acceptance 字段的解析结果）。
+ * 如果 acceptance 是内联定义，直接返回。
+ * 如果是引用（如 "see 05_VERIFICATION.md#int-001"），解析引用并返回对应章节内容。
+ * @param {string} loomDir — .loom/v{N}/ 目录
+ * @param {string} intentId — Intent ID
+ * @returns {string} 验收契约内容
+ */
+export function getVerificationContract(loomDir, intentId) {
+  const intentMap = JSON.parse(readFileSync(join(loomDir, '04_INTENT_MAP.json'), 'utf-8'));
+  if (!(intentId in intentMap.intents)) {
+    throw new Error(`Intent 不存在: ${intentId}`);
+  }
+  const acceptance = intentMap.intents[intentId].acceptance;
+
+  // 检测是否是引用格式: "see 05_VERIFICATION.md#section" 或 "05_VERIFICATION.md#section"
+  const refMatch = acceptance.match(/(?:see\s+)?(\w+\.md)#([\w-]+)/i);
+  if (refMatch) {
+    const [, file, section] = refMatch;
+    const filePath = join(loomDir, file);
+    if (!existsSync(filePath)) {
+      throw new Error(`验证契约引用的文件不存在: ${filePath}`);
+    }
+    const content = readFileSync(filePath, 'utf-8');
+    return extractMdSection(content, section);
+  }
+
+  // 内联定义，直接返回
+  return acceptance;
+}
+
+/**
+ * 从 heading 文本中提取显式锚点。
+ * 支持 Pandoc/MDX 风格语法: "## INT-003 {#int-003}"
+ */
+function extractExplicitAnchor(headingText) {
+  const match = headingText.match(/\{#([\w-]+)\}\s*$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * slugify — 和 philosophy.js 保持一致的逻辑。
+ */
+function slugify(text) {
+  return text
+    .replace(/\r/g, '')
+    .replace(/\{#[\w-]+\}\s*$/, '')
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .trim();
+}
+
+/**
+ * 从 MD 内容中按 heading slug 提取章节。
+ * 支持显式锚点 {#slug} 和自动 slugify。
+ */
+function extractMdSection(content, sectionSlug) {
+  const lines = content.split('\n');
+  let capturing = false;
+  let targetLevel = 0;
+  const captured = [];
+
+  for (const line of lines) {
+    const cleanLine = line.replace(/\r$/, '');
+    const headingMatch = cleanLine.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const headingText = headingMatch[2];
+      const slug = extractExplicitAnchor(headingText) || slugify(headingText);
+      if (capturing && level <= targetLevel) break;
+      if (slug === sectionSlug) {
+        capturing = true;
+        targetLevel = level;
+        captured.push(cleanLine);
+        continue;
+      }
+    }
+    if (capturing) captured.push(cleanLine);
+  }
+
+  if (captured.length === 0) {
+    throw new Error(`验证契约章节未找到: #${sectionSlug}`);
+  }
+  return captured.join('\n').trim();
+}

package/cli/src/version.js

@@ -0,0 +1,133 @@
+// version — LOOM 版本管理
+// 提供 list / current / new / use / diff 五个原子操作。
+// CLI 只做数据操作，演进决策（Minor/Major）由 Agent + 用户对话完成。
+
+import { existsSync, readdirSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createVersionStructure } from './init.js';
+
+/**
+ * 列出所有版本目录。
+ * @param {string} loomRoot — .loom 目录路径
+ * @returns {{ versions: string[], current: string|null }}
+ */
+export function listVersions(loomRoot) {
+  if (!existsSync(loomRoot)) {
+    throw new Error(`找不到 .loom 目录: ${loomRoot}`);
+  }
+  const versions = readdirSync(loomRoot)
+    .filter((d) => /^v\d+$/.test(d) && statSync(join(loomRoot, d)).isDirectory())
+    .sort((a, b) => parseInt(a.slice(1)) - parseInt(b.slice(1)));
+  const current = readCurrentPointer(loomRoot);
+  return { versions, current };
+}
+
+/**
+ * 读取当前版本指针。
+ * 优先读 .loom/current 文件；不存在则回退到自动探测最新版本。
+ * @param {string} loomRoot — .loom 目录路径
+ * @returns {string|null} 版本号如 'v1'，或 null（无版本）
+ */
+export function readCurrentPointer(loomRoot) {
+  const pointerPath = join(loomRoot, 'current');
+  if (existsSync(pointerPath)) {
+    const v = readFileSync(pointerPath, 'utf-8').trim();
+    if (/^v\d+$/.test(v) && existsSync(join(loomRoot, v))) return v;
+  }
+  // 回退：自动探测最新版本
+  if (!existsSync(loomRoot)) return null;
+  const versions = readdirSync(loomRoot)
+    .filter((d) => /^v\d+$/.test(d) && statSync(join(loomRoot, d)).isDirectory())
+    .sort((a, b) => parseInt(b.slice(1)) - parseInt(a.slice(1)));
+  return versions[0] ?? null;
+}
+
+/**
+ * 创建新版本 v{N+1}，自动切换为当前版本。
+ * 不复制旧版本内容——空目录 + 模板强制 Agent 重新思考。
+ * @param {string} projectDir — 项目根目录
+ * @returns {{ version: string, created: string[], skipped: string[] }}
+ */
+export function newVersion(projectDir) {
+  const loomRoot = join(projectDir, '.loom');
+  const { versions } = listVersions(loomRoot);
+  const nextNum = versions.length === 0
+    ? 1
+    : parseInt(versions[versions.length - 1].slice(1)) + 1;
+  const nextV = `v${nextNum}`;
+  const result = createVersionStructure(projectDir, nextV);
+  // 自动切换为当前版本
+  writeFileSync(join(loomRoot, 'current'), nextV, 'utf-8');
+  result.created.push('.loom/current');
+  return { version: nextV, created: result.created, skipped: result.skipped };
+}
+
+/**
+ * 切换当前版本指针。
+ * @param {string} loomRoot — .loom 目录路径
+ * @param {string} version — 目标版本号如 'v1'
+ */
+export function useVersion(loomRoot, version) {
+  const v = version.startsWith('v') ? version : `v${version}`;
+  if (!existsSync(join(loomRoot, v))) {
+    throw new Error(`版本不存在: ${v}`);
+  }
+  writeFileSync(join(loomRoot, 'current'), v, 'utf-8');
+  return v;
+}
+
+/**
+ * 对比两个版本的文件差异。
+ * 只对比文件存在性和大小，不做内容 diff（内容 diff 用 Git）。
+ * @param {string} loomRoot — .loom 目录路径
+ * @param {string} v1 — 版本 A
+ * @param {string} v2 — 版本 B
+ * @returns {{ only_in_a: string[], only_in_b: string[], different_size: string[], same: string[] }}
+ */
+export function diffVersions(loomRoot, v1, v2) {
+  const a = v1.startsWith('v') ? v1 : `v${v1}`;
+  const b = v2.startsWith('v') ? v2 : `v${v2}`;
+  const dirA = join(loomRoot, a);
+  const dirB = join(loomRoot, b);
+  if (!existsSync(dirA)) throw new Error(`版本不存在: ${a}`);
+  if (!existsSync(dirB)) throw new Error(`版本不存在: ${b}`);
+
+  const filesA = listFilesRelative(dirA);
+  const filesB = listFilesRelative(dirB);
+  const setA = new Set(filesA);
+  const setB = new Set(filesB);
+
+  const onlyInA = filesA.filter((f) => !setB.has(f));
+  const onlyInB = filesB.filter((f) => !setA.has(f));
+  const common = filesA.filter((f) => setB.has(f));
+  const differentSize = common.filter((f) => {
+    const sa = statSync(join(dirA, f)).size;
+    const sb = statSync(join(dirB, f)).size;
+    return sa !== sb;
+  });
+  const same = common.filter((f) => {
+    const sa = statSync(join(dirA, f)).size;
+    const sb = statSync(join(dirB, f)).size;
+    return sa === sb;
+  });
+
+  return { only_in_a: onlyInA, only_in_b: onlyInB, different_size: differentSize, same };
+}
+
+/**
+ * 递归列出目录下所有文件的相对路径。
+ */
+function listFilesRelative(dir, base = '') {
+  const result = [];
+  if (!existsSync(dir)) return result;
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    const rel = base ? `${base}/${entry}` : entry;
+    if (statSync(full).isDirectory()) {
+      result.push(...listFilesRelative(full, rel));
+    } else {
+      result.push(rel);
+    }
+  }
+  return result.sort();
+}