@haaaiawd/loom 0.1.0 → 0.7.0

package/cli/src/intent-map.js

@@ -3,85 +3,22 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
-
-/**
- * 从 heading 文本中提取显式锚点（和 philosophy.js 一致的逻辑）。
- */
-function extractExplicitAnchor(headingText) {
-  const match = headingText.match(/\{#([\w-]+)\}\s*$/);
-  return match ? match[1] : null;
-}
-
-/**
- * slugify — strip \r、支持显式锚点、ASCII fallback。
- */
-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 内容中提取指定 section（和 philosophy.js 一致的逻辑）。
- */
-function extractMdSection(content, sectionSlug) {
-  if (!sectionSlug) return content;
-  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();
-}
+import { extractMdSection, readJsonFile } from './shared/md-utils.js';
 
 /** 必填字段（INTENT_LOOP.md 底线） */
-const REQUIRED_FIELDS = ['id', 'narrative_ref', 'depends_on', 'acceptance', 'philosophy_anchors', 'status'];
+const REQUIRED_FIELDS = ['id', 'title', 'narrative_ref', 'depends_on', 'acceptance', 'philosophy_anchors', 'status'];
 
 /** 合法 status 值 */
 const VALID_STATUS = ['pending', 'in_progress', 'completed', 'blocked', 'needs_review'];
 
 /**
  * 加载 Intent Map 文件。
- * @param {string} loomDir — .loom/v{N}/ 目录的绝对路径
+ * @param {string} versionDir — .loom/v{N}/ 目录的绝对路径
  * @returns {{ _meta: object, intents: Record<string, object>, topo_order: string[] }}
  */
-export function loadIntentMap(loomDir) {
-  const filePath = join(loomDir, '04_INTENT_MAP.json');
-  if (!existsSync(filePath)) {
-    throw new Error(`Intent Map 不存在: ${filePath}`);
-  }
-  const raw = readFileSync(filePath, 'utf-8');
-  let data;
-  try {
-    data = JSON.parse(raw);
-  } catch (e) {
-    throw new Error(`Intent Map JSON 解析失败: ${e.message}`);
-  }
+export function loadIntentMap(versionDir) {
+  const filePath = join(versionDir, '04_INTENT_MAP.json');
+  const data = readJsonFile(filePath, 'Intent Map');
   validateIntentMap(data);
   return data;
 }
@@ -126,6 +63,16 @@ export function validateIntentMap(data) {
         }
       }
     }
+    // acceptance 质量底线（IM-2）：必须具体到可验证，不能是占位符
+    if (intent.acceptance && typeof intent.acceptance === 'string') {
+      const acc = intent.acceptance.trim();
+      if (acc === '...' || acc === '' || acc.length < 20) {
+        errors.push(
+          `intents["${id}"].acceptance 太短（${acc.length}字符）——必须是具体可验证的契约，不能是占位符。\n` +
+          `    acceptance 应包含功能承诺 + 防御承诺（见 INTENT_LOOP.md IM-2 "acceptance 承诺分层"）。`
+        );
+      }
+    }
   }
 
   // topo_order 必须覆盖所有 Intent
@@ -148,8 +95,8 @@ export function validateIntentMap(data) {
  * status=pending 且 depends_on 全部 completed，按 topo_order 取第一个。
  * @returns {object|null} Intent 对象，或 null（没有可执行的）
  */
-export function getNextIntent(loomDir) {
-  const { intents, topo_order } = loadIntentMap(loomDir);
+export function getNextIntent(versionDir) {
+  const { intents, topo_order } = loadIntentMap(versionDir);
   for (const id of topo_order) {
     const intent = intents[id];
     if (intent.status !== 'pending') continue;
@@ -164,12 +111,14 @@ export function getNextIntent(loomDir) {
 /**
  * 返回进度概览：各状态的 Intent 数量 + ID 列表。
  */
-export function getStatus(loomDir) {
-  const { intents } = loadIntentMap(loomDir);
+export function getStatus(versionDir) {
+  const { intents } = loadIntentMap(versionDir);
   const summary = { pending: [], in_progress: [], completed: [], blocked: [] };
+  const titles = {};
   for (const [id, intent] of Object.entries(intents)) {
     const s = intent.status;
     if (summary[s]) summary[s].push(id);
+    titles[id] = intent.title || '';
   }
   return {
     counts: {
@@ -180,14 +129,15 @@ export function getStatus(loomDir) {
       total: Object.keys(intents).length,
     },
     ids: summary,
+    titles,
   };
 }
 
 /**
  * 输出 Mermaid 依赖图。
  */
-export function getDependencyGraph(loomDir) {
-  const { intents, topo_order } = loadIntentMap(loomDir);
+export function getDependencyGraph(versionDir) {
+  const { intents, topo_order } = loadIntentMap(versionDir);
   const lines = ['```mermaid', 'graph TD'];
   for (const id of topo_order) {
     const intent = intents[id];
@@ -209,8 +159,8 @@ export function getDependencyGraph(loomDir) {
 /**
  * 按 ID 返回单个 Intent 的完整信息。
  */
-export function getIntent(loomDir, intentId) {
-  const { intents } = loadIntentMap(loomDir);
+export function getIntent(versionDir, intentId) {
+  const { intents } = loadIntentMap(versionDir);
   if (!(intentId in intents)) {
     throw new Error(`Intent 不存在: ${intentId}`);
   }
@@ -220,18 +170,18 @@ export function getIntent(loomDir, intentId) {
 /**
  * 更新 Intent 的运行时 status。
  * 只允许合法的状态转换，防止跳变（如 completed→pending）。
- * @param {string} loomDir — .loom/v{N}/ 目录
+ * @param {string} versionDir — .loom/v{N}/ 目录
  * @param {string} intentId — Intent ID
  * @param {string} newStatus — pending | in_progress | completed | blocked
  * @returns {object} 更新后的 Intent
  */
-export function updateIntentStatus(loomDir, intentId, newStatus) {
+export function updateIntentStatus(versionDir, intentId, newStatus) {
   if (!VALID_STATUS.includes(newStatus)) {
     throw new Error(`非法 status: "${newStatus}" (合法: ${VALID_STATUS.join('|')})`);
   }
 
-  const filePath = join(loomDir, '04_INTENT_MAP.json');
-  const data = JSON.parse(readFileSync(filePath, 'utf-8'));
+  const filePath = join(versionDir, '04_INTENT_MAP.json');
+  const data = readJsonFile(filePath, 'Intent Map');
 
   if (!(intentId in data.intents)) {
     throw new Error(`Intent 不存在: ${intentId}`);
@@ -253,6 +203,13 @@ export function updateIntentStatus(loomDir, intentId, newStatus) {
     );
   }
 
+  // 收敛趟计数：completed → needs_review 时 _meta.pass_count++
+  // 这是变更回流的信号——一个已完成 Intent 需要重新验证，进入新一轮收敛
+  if (oldStatus === 'completed' && newStatus === 'needs_review') {
+    if (!data._meta) data._meta = {};
+    data._meta.pass_count = (data._meta.pass_count || 0) + 1;
+  }
+
   data.intents[intentId].status = newStatus;
   writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
   return data.intents[intentId];
@@ -263,8 +220,8 @@ export function updateIntentStatus(loomDir, intentId, newStatus) {
  * narrative_ref 格式: "01_VISION.md#int-001" 或 "01_VISION.md#int-001"
  * @returns {string} 意图叙事内容
  */
-export function getNarrative(loomDir, intentId) {
-  const { intents } = loadIntentMap(loomDir);
+export function getNarrative(versionDir, intentId) {
+  const { intents } = loadIntentMap(versionDir);
   if (!(intentId in intents)) {
     throw new Error(`Intent 不存在: ${intentId}`);
   }
@@ -275,10 +232,10 @@ export function getNarrative(loomDir, intentId) {
 
   // 解析 "FILE.md#section" 格式
   const [file, section] = ref.split('#');
-  const filePath = join(loomDir, file.trim());
+  const filePath = join(versionDir, file.trim());
   if (!existsSync(filePath)) {
     throw new Error(`愿景文档不存在: ${filePath}`);
   }
   const content = readFileSync(filePath, 'utf-8');
-  return extractMdSection(content, section ? section.trim() : null);
+  return extractMdSection(content, section ? section.trim() : null, '意图叙事');
 }

package/cli/src/philosophy.js

@@ -4,6 +4,7 @@
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { extractMdSection } from './shared/md-utils.js';
 
 /**
  * 解析锚点字符串。
@@ -15,78 +16,6 @@ export function parseAnchor(anchor) {
   return { file: file.trim(), section: section ? section.trim() : null };
 }
 
-/**
- * 从 heading 文本中提取显式锚点。
- * 支持 Pandoc/MDX 风格语法: "## 核心信念 {#core-belief}"
- * @returns {string|null} 显式锚点 slug，或 null（无显式锚点时）
- */
-function extractExplicitAnchor(headingText) {
-  const match = headingText.match(/\{#([\w-]+)\}\s*$/);
-  return match ? match[1] : null;
-}
-
-/**
- * 从 heading 文本生成 slug（fallback，无显式锚点时用）。
- * 规则：小写、去除 \r、空格转连字符、去除非 [a-z0-9_-] 字符。
- * 注意：\w 不匹配中文，所以中文标题的 slug 会是空的——
- * 这就是为什么哲学文档应该用显式锚点 {#anchor} 标注中文标题。
- */
-function slugify(text) {
-  return text
-    .replace(/\r/g, '')           // strip CRLF 的 \r
-    .replace(/\{#[\w-]+\}\s*$/, '') // 去掉显式锚点标记
-    .toLowerCase()
-    .replace(/[^\w\s-]/g, '')     // \w = [a-zA-Z0-9_]
-    .replace(/\s+/g, '-')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '')
-    .trim();
-}
-
-/**
- * 从 MD 内容中提取指定 section 的内容（到下一个同级或更高级 heading 为止）。
- * 如果 section 为 null，返回整个文件。
- * 支持显式锚点 {#slug} 和自动 slugify 两种方式匹配。
- */
-function extractSection(content, sectionSlug) {
-  if (!sectionSlug) return content;
-
-  const lines = content.split('\n');
-  let capturing = false;
-  let targetLevel = 0;
-  const captured = [];
-
-  for (const line of lines) {
-    // strip \r 以兼容 Windows CRLF
-    const cleanLine = line.replace(/\r$/, '');
-    const headingMatch = cleanLine.match(/^(#{1,6})\s+(.+)$/);
-    if (headingMatch) {
-      const level = headingMatch[1].length;
-      const headingText = headingMatch[2];
-      // 优先用显式锚点，没有再 fallback 到 slugify
-      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();
-}
-
 /**
  * 按锚点加载哲学文档内容。
  * @param {string} philosophyDir — 00_PHILOSOPHY/ 目录路径
@@ -102,7 +31,7 @@ export function getPhilosophy(philosophyDir, anchor) {
   }
 
   const content = readFileSync(filePath, 'utf-8');
-  return extractSection(content, section);
+  return extractMdSection(content, section, '哲学');
 }
 
 /**

package/cli/src/preview-prompt.md

@@ -160,6 +160,7 @@ SVG 折线，横轴时间，纵轴剩余数。
 - **不可妥协的价值**：清单，每条一句话 + 一句话理由
 - **反模式**：红色警告卡，每张一句
 - **决策原则**：对比表或清单，遇到冲突时怎么取舍
+- **灵感来源**：哲学文档里的"灵感来源"章节——展示参考的艺术家、机构、流派、著作。这是 LOOM 哲学织造的核心机制：从真实思想体系萃取核心思想。每个来源用卡片或标签展示：名字（如 Dieter Rams / Stripe / Unix Philosophy / Anthropic）+ 一句话说明"从这个体系萃取了什么原则" + 来源引用（著作/URL）。这些名字是"思想压缩包的索引"——人类看到名字就能激活对这套哲学的理解。不要把灵感来源藏在正文里，要作为独立视觉块展示。
 
 ### 愿景区域
 

package/cli/src/shared/md-utils.js

@@ -0,0 +1,125 @@
+// shared/md-utils.js — MD 章节解析的公共工具
+// 提取自 philosophy.js / intent-map.js / verify.js 三处重复实现。
+// 统一 slugify + extractMdSection + 显式锚点逻辑，修中文标题 bug。
+
+import { readFileSync, existsSync } from 'node:fs';
+
+/**
+ * 从 heading 文本中提取显式锚点。
+ * 支持 Pandoc/MDX 风格语法: "## 核心信念 {#core-belief}"
+ * @param {string} headingText — heading 文本（不含 # 前缀）
+ * @returns {string|null} 显式锚点 slug，或 null（无显式锚点时）
+ */
+export function extractExplicitAnchor(headingText) {
+  const match = headingText.match(/\{#([\w-]+)\}\s*$/);
+  return match ? match[1] : null;
+}
+
+/**
+ * 从 heading 文本生成 slug（fallback，无显式锚点时用）。
+ * 规则：小写、去除 \r、空格转连字符、去除非 [a-z0-9_-] 字符。
+ *
+ * 中文标题处理：\w 不匹配中文，所以纯中文标题 slugify 后是空字符串。
+ * 这是设计约束——中文标题必须用显式锚点 {#anchor} 标注。
+ * slugify 返回空字符串时，调用方应给出明确错误提示。
+ *
+ * @param {string} text — heading 文本
+ * @returns {string} slug（可能为空字符串——纯中文标题无显式锚点时）
+ */
+export function slugify(text) {
+  return text
+    .replace(/\r/g, '')           // strip CRLF 的 \r
+    .replace(/\{#[\w-]+\}\s*$/, '') // 去掉显式锚点标记
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')     // \w = [a-zA-Z0-9_]
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .trim();
+}
+
+/**
+ * 从 MD 内容中提取指定 section 的内容（到下一个同级或更高级 heading 为止）。
+ * 如果 sectionSlug 为 null/空，返回整个文件。
+ * 支持显式锚点 {#slug} 和自动 slugify 两种方式匹配。
+ *
+ * @param {string} content — MD 文件内容
+ * @param {string} sectionSlug — 目标 section 的 slug
+ * @param {string} contextLabel — 错误信息里的上下文标签（如 "意图叙事"、"验证契约"）
+ * @returns {string} 提取的章节内容
+ * @throws {Error} 章节未找到时抛错，错误信息包含 contextLabel 和 slug
+ */
+export function extractMdSection(content, sectionSlug, contextLabel = '章节') {
+  if (!sectionSlug) return content;
+
+  const lines = content.split('\n');
+  let capturing = false;
+  let targetLevel = 0;
+  const captured = [];
+
+  for (const line of lines) {
+    // strip \r 以兼容 Windows CRLF
+    const cleanLine = line.replace(/\r$/, '');
+    const headingMatch = cleanLine.match(/^(#{1,6})\s+(.+)$/);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const headingText = headingMatch[2];
+      // 优先用显式锚点，没有再 fallback 到 slugify
+      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(
+      `${contextLabel}章节未找到: #${sectionSlug}\n` +
+      `可能原因：\n` +
+      `  1. 章节标题用了中文但没加显式锚点 {#anchor}\n` +
+      `  2. 锚点 slug 拼写错误\n` +
+      `  3. 引用的文件不存在该章节`
+    );
+  }
+  return captured.join('\n').trim();
+}
+
+/**
+ * 安全读取并解析 JSON 文件。
+ * 统一错误处理——文件不存在、JSON 解析失败时给出明确错误信息。
+ *
+ * @param {string} filePath — JSON 文件绝对路径
+ * @param {string} contextLabel — 错误信息里的上下文标签（如 "Intent Map"、"验证记录"）
+ * @returns {object} 解析后的 JSON 对象
+ * @throws {Error} 文件不存在或 JSON 解析失败时抛错，错误信息包含文件路径和原因
+ */
+export function readJsonFile(filePath, contextLabel = 'JSON 文件') {
+  if (!existsSync(filePath)) {
+    throw new Error(`${contextLabel}文件不存在: ${filePath}`);
+  }
+  let raw;
+  try {
+    raw = readFileSync(filePath, 'utf-8');
+  } catch (e) {
+    throw new Error(`${contextLabel}文件读取失败: ${filePath}\n原因: ${e.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new Error(
+      `${contextLabel}文件 JSON 解析失败: ${filePath}\n` +
+      `原因: ${e.message}\n` +
+      `请检查文件内容是否为合法 JSON（多余逗号、缺少引号等）。`
+    );
+  }
+}

package/cli/src/shared/paths.js

@@ -0,0 +1,73 @@
+// shared/paths.js — LOOM 路径解析的公共工具
+// 统一 getLoomRoot / findLoomRoot / findVersionDir 的命名和实现。
+
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { argv, cwd } from 'node:process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 获取 LOOM 框架根目录（cli/src/shared 的上上上级）。
+ * cli/src/shared/paths.js -> cli/src/shared -> cli/src -> cli -> LOOM root
+ * @returns {string} LOOM 框架根目录绝对路径
+ */
+export function getLoomRoot() {
+  return resolve(__dirname, '..', '..', '..');
+}
+
+/**
+ * 从命令行参数或 cwd 推断 .loom 目录路径。
+ * 优先级：--loom-dir 参数（指向版本目录，反推 .loom root）> cwd/.loom
+ * @returns {string} .loom 目录绝对路径
+ */
+export function findLoomRoot() {
+  const flagIdx = argv.indexOf('--loom-dir');
+  if (flagIdx !== -1 && argv[flagIdx + 1]) {
+    // --loom-dir 直接指向版本目录，反推 .loom root
+    const dir = resolve(argv[flagIdx + 1]);
+    return resolve(dir, '..');
+  }
+  return join(cwd(), '.loom');
+}
+
+/**
+ * 从命令行参数或 .loom/current 指针推断当前版本目录。
+ * @returns {string} .loom/v{N} 目录绝对路径
+ * @throws {Error} .loom 不存在或没有版本目录时抛错
+ */
+export function findVersionDir() {
+  const flagIdx = argv.indexOf('--loom-dir');
+  if (flagIdx !== -1 && argv[flagIdx + 1]) {
+    return resolve(argv[flagIdx + 1]);
+  }
+  const loomRoot = join(cwd(), '.loom');
+  if (!existsSync(loomRoot)) {
+    throw new Error(`找不到 .loom 目录: ${loomRoot}`);
+  }
+  const current = readCurrentPointer(loomRoot);
+  if (!current) {
+    throw new Error(`.loom 下没有版本目录 (v1, v2, ...)`);
+  }
+  return join(loomRoot, 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;
+}