@haaaiawd/loom 0.1.0 → 0.8.0

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;
+}

package/cli/src/verify.js

@@ -3,10 +3,19 @@
 
 import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
+import { extractMdSection, readJsonFile } from './shared/md-utils.js';
 
 /** 合法判定结果 */
 const VALID_VERDICTS = ['passed', 'deviated', 'blocked', 'pending_human'];
 
+/** 四个必须覆盖的验证维度 */
+const REQUIRED_DIMENSIONS = [
+  'intent_fidelity',
+  'philosophy_consistency',
+  'baseline_compliance',
+  'acceptance_achievement',
+];
+
 /**
  * 写入一条验证记录（追加模式——同一 Intent 多次验证保留完整历史）。
  * 文件格式: { intent_id, records: [{ round, verdict, timestamp, ... }] }
@@ -17,6 +26,7 @@ const VALID_VERDICTS = ['passed', 'deviated', 'blocked', 'pending_human'];
  * @param {string} record.timestamp — ISO 8601
  * @param {string} record.summary — 验证摘要
  * @param {object} record.dimensions — 四个维度的验证结果
+ * @param {string} [record.reproduction_command] — 复现验证的命令（如 "LLM_API_KEY=mock npm test"）
  * @param {string} [record.deviation_detail] — 偏离说明（deviated 时）
  * @param {boolean} [record.reset_suggested] — 是否建议重置上下文
  * @returns {{ filePath: string, round: number, deviated_count: number, should_escalate: boolean }}
@@ -29,6 +39,36 @@ export function writeVerification(verificationsDir, record) {
   }
   if (!record.timestamp) errors.push('缺少 timestamp');
   if (!record.dimensions) errors.push('缺少 dimensions（四个维度结果）');
+  // dimensions 结构校验：每个维度必须是 { verdict, evidence } 对象
+  if (record.dimensions) {
+    for (const dim of REQUIRED_DIMENSIONS) {
+      const v = record.dimensions[dim];
+      if (v === undefined) {
+        errors.push(`dimensions.${dim} 缺失（四个维度必须全覆盖）`);
+      } else if (typeof v === 'string') {
+        errors.push(`dimensions.${dim} 是旧格式（枚举值），必须改成 { verdict, evidence } 对象`);
+      } else if (typeof v !== 'object' || v === null) {
+        errors.push(`dimensions.${dim} 必须是 { verdict, evidence } 对象`);
+      } else {
+        if (!VALID_VERDICTS.includes(v.verdict)) {
+          errors.push(`dimensions.${dim}.verdict 非法: "${v.verdict}" (合法: ${VALID_VERDICTS.join('|')})`);
+        }
+        if (!v.evidence || typeof v.evidence !== 'string' || v.evidence.trim() === '') {
+          errors.push(`dimensions.${dim}.evidence 缺失——必须给出具体证据，不能只写"合规"`);
+        } else {
+          // evidence 质量校验：长度 + 废话检测
+          const ev = v.evidence.trim();
+          if (ev.length < 10) {
+            errors.push(`dimensions.${dim}.evidence 太短（${ev.length}字符 < 10）——必须给出具体证据，不能只写"合规"`);
+          }
+          const NONSENSE = ['合规', '通过', 'OK', 'ok', '没问题', '符合要求', '已检查', 'pass', 'passed', 'done'];
+          if (NONSENSE.includes(ev)) {
+            errors.push(`dimensions.${dim}.evidence "${ev}" 是通用评价而非具体证据——必须写"对照了什么 + 在代码哪里看到/没看到"`);
+          }
+        }
+      }
+    }
+  }
   if (errors.length > 0) {
     throw new Error(`验证记录校验失败:\n  - ${errors.join('\n  - ')}`);
   }
@@ -38,15 +78,28 @@ export function writeVerification(verificationsDir, record) {
   // 读取已有记录（如果有）
   let data;
   if (existsSync(filePath)) {
-    data = JSON.parse(readFileSync(filePath, 'utf-8'));
+    data = readJsonFile(filePath, '验证记录');
+    // 结构校验：已有文件必须是 { intent_id, records: [] } 格式
+    if (!data || typeof data !== 'object' || !Array.isArray(data.records)) {
+      throw new Error(
+        `已有验证记录格式错误: ${filePath}\n` +
+        `期望格式: { intent_id, records: [...] }\n` +
+        `实际格式: ${JSON.stringify(data).slice(0, 200)}\n` +
+        `修复: 删除或修正该文件后重试。`
+      );
+    }
   } 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);
+  // 计算轮次和连续 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({
@@ -55,6 +108,7 @@ export function writeVerification(verificationsDir, record) {
     timestamp: record.timestamp,
     summary: record.summary,
     dimensions: record.dimensions,
+    reproduction_command: record.reproduction_command,
     deviation_detail: record.deviation_detail,
     reset_suggested: record.reset_suggested,
   });
@@ -77,18 +131,15 @@ export function getVerificationHistory(verificationsDir, intentId) {
   if (!existsSync(filePath)) {
     return null;
   }
-  const raw = readFileSync(filePath, 'utf-8');
-  return JSON.parse(raw);
+  return readJsonFile(filePath, '验证记录');
 }
 
 /**
  * 返回所有待验证的 Intent（有实现产物但还没验证记录的）。
  * 需要传入 Intent Map 来判断哪些 Intent 是 in_progress。
  */
-export function getPendingVerifications(loomDir, verificationsDir) {
-  const intentMap = JSON.parse(
-    readFileSync(join(loomDir, '04_INTENT_MAP.json'), 'utf-8')
-  );
+export function getPendingVerifications(versionDir, verificationsDir) {
+  const intentMap = readJsonFile(join(versionDir, '04_INTENT_MAP.json'), 'Intent Map');
   const pending = [];
   for (const [id, intent] of Object.entries(intentMap.intents)) {
     if (intent.status === 'in_progress') {
@@ -101,11 +152,14 @@ export function getPendingVerifications(loomDir, verificationsDir) {
 
 /**
  * 列出所有验证记录文件。
+ * 只列出正式验证记录——文件名匹配 INT-XXX 格式且内容含 records 字段。
+ * 过滤掉用户写入的临时输入文件（如 INT-001.verify.json、_tmp_*.json）。
  */
 export function listVerifications(verificationsDir) {
   if (!existsSync(verificationsDir)) return [];
   return readdirSync(verificationsDir)
     .filter((f) => f.endsWith('.json'))
+    .filter((f) => /^INT-\d+\.json$/.test(f))
     .map((f) => f.replace('.json', ''));
 }
 
@@ -113,12 +167,12 @@ export function listVerifications(verificationsDir) {
  * 获取某 Intent 的验证契约（acceptance 字段的解析结果）。
  * 如果 acceptance 是内联定义，直接返回。
  * 如果是引用（如 "see 05_VERIFICATION.md#int-001"），解析引用并返回对应章节内容。
- * @param {string} loomDir — .loom/v{N}/ 目录
+ * @param {string} versionDir — .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'));
+export function getVerificationContract(versionDir, intentId) {
+  const intentMap = readJsonFile(join(versionDir, '04_INTENT_MAP.json'), 'Intent Map');
   if (!(intentId in intentMap.intents)) {
     throw new Error(`Intent 不存在: ${intentId}`);
   }
@@ -128,72 +182,14 @@ export function getVerificationContract(loomDir, intentId) {
   const refMatch = acceptance.match(/(?:see\s+)?(\w+\.md)#([\w-]+)/i);
   if (refMatch) {
     const [, file, section] = refMatch;
-    const filePath = join(loomDir, file);
+    const filePath = join(versionDir, file);
     if (!existsSync(filePath)) {
       throw new Error(`验证契约引用的文件不存在: ${filePath}`);
     }
     const content = readFileSync(filePath, 'utf-8');
-    return extractMdSection(content, section);
+    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

@@ -122,7 +122,7 @@ function listFilesRelative(dir, base = '') {
   if (!existsSync(dir)) return result;
   for (const entry of readdirSync(dir)) {
     const full = join(dir, entry);
-    const rel = base ? `${base}/${entry}` : entry;
+    const rel = base ? join(base, entry) : entry;
     if (statSync(full).isDirectory()) {
       result.push(...listFilesRelative(full, rel));
     } else {

package/dimensions/PART_DECOMPOSITION.md

@@ -0,0 +1,203 @@
+# 实现部分拆解方法论
+
+> 这份文档给 Agent 一套拆解方法，让它自己识别"这个项目由哪些实现部分组成"，
+> 然后对每个部分走搜索漏斗，织造该部分的哲学约束。
+>
+> 项目千变万化，预填维度文件覆盖不了所有情况。方法不会过时，清单会。
+
+---
+
+## 核心思路
+
+传统维度库靠预填——CLI 工具该有哪些维度、Agent 系统该有哪些维度、Web 前端该有哪些维度，全部写死在文件里。这样有三个问题：
+
+1. 项目类型太多，预填永远追不上
+2. 新项目类型出现时，维度库来不及更新
+3. 预设的"UX 哲学"对 CLI 工具没意义，预设的"CLI 美学"对 Agent 系统也没意义——错配
+
+LOOM 换了个方向：预设"怎么拆部分"，不预设"有哪些部分"。Agent 拿到项目特征后，自己拆解出实现部分，每个部分独立织造哲学。
+
+---
+
+## 拆解流程
+
+### Step 1：识别项目类型
+
+先判断项目属于哪个大类。判断结果用来确定拆解的起点，不用来查预设清单。
+
+常见类型（非穷举——Agent 自行判断）：
+
+| 类型 | 特征 | 用户接触面 |
+|---|---|---|
+| CLI 工具 | 命令行交互，输入→输出 | 终端输出、参数、退出码 |
+| Agent 系统 | 自主决策，工具调用 | 对话、工具调用结果、状态反馈 |
+| Web 前端 | 浏览器渲染，用户交互 | 页面、交互、视觉 |
+| 后端服务 | API 驱动，多客户端 | API 响应、错误码、文档 |
+| 游戏引擎 | 实时渲染，物理模拟 | 画面、操作反馈、性能 |
+| 嵌入式系统 | 资源受限，硬件交互 | 设备行为、指示灯、串口 |
+| 数据管道 | ETL/流处理，数据变换 | 数据质量、吞吐量、延迟 |
+| 混合型 | 以上多种组合 | 按子系统拆分，各走各的类型 |
+
+**判断方法**：看项目的用户接触面和核心交互方式。如果项目跨多个类型（如 Agent 系统 + Web 前端），按子系统分别判断。
+
+**用户提到的特殊类型**：上面这张表只列了常见类型。用户可能提出表里没有的系统——编译器、数据库、操作系统内核、游戏引擎、实时渲染管线、分布式共识系统、密码学库、嵌入式固件、区块链协议、消息队列、时序数据库……遇到表里没有的类型，按 Step 2 的三个问题自己拆，不要硬套。`examples/` 目录下有参考案例的才几个，没参考案例的类型更要认真走搜索漏斗——这类系统的实践知识往往在论文、标准文档、源码注释里，不在博客里。
+
+### Step 2：拆解实现部分
+
+对项目类型，问三个问题，每个答案是一个"实现部分"：
+
+**问题 A：用户接触面是什么？**
+- CLI 工具 → 终端输出、参数解析、帮助信息、错误呈现
+- Agent 系统 → 对话格式、工具调用展示、状态反馈、进度提示
+- Web 前端 → 页面布局、交互反馈、视觉风格、动效
+
+**问题 B：内部由哪些子系统组成？**
+- CLI 工具 → 转换引擎、文件 IO、配置管理（如果有）
+- Agent 系统 → 编排器、工具调度、上下文管理、提示词构造、验证器
+- Web 前端 → 路由、状态管理、组件层、数据获取、样式系统
+
+**问题 C：每个子系统的职责边界在哪？**
+- 问的是"每个模块该怎么做、什么标准"——"有哪些模块"是架构的事，不是哲学的事
+- 职责边界 = 这个部分"做什么"和"不做什么"的划分
+
+**拆解原则**：
+1. **按职责拆，不按文件拆**——"CLI 输出美学"是一个部分，"cli.js 这个文件"不是
+2. **粒度适中**——太粗（"整个 CLI"）没有约束力，太细（"每个函数"）变成架构了
+3. **每个部分能独立回答"该怎么做"**——如果一个部分的"怎么做"完全依赖另一个部分，合并它们
+4. **用户接触面优先**——用户能看到、能感知的部分，哲学约束最重要
+
+### Step 3：对每个部分走搜索漏斗
+
+每个识别出的实现部分，独立走"搜索 → 萃取 → 转译 → 落地"漏斗（见 PHILOSOPHY_WEAVER.md "织造漏斗"章节）。
+
+搜索时问的问题要具体：**"这个部分该怎么做、什么标准、有什么好实践"**。别问"这个领域的哲学是什么"——实践领域的知识很少叫"哲学"。
+
+例如对 CLI 工具的"帮助信息"部分：
+- 搜 "CLI help text design best practices"
+- 搜 "ripgrep --help output design"
+- 搜 "clap help formatting conventions"
+- 搜 "POSIX utility argument syntax conventions"
+- 从结果中萃取：帮助信息的结构、示例的放法、链接的放法、退出码的说明
+
+### Step 4：产出部分哲学文档
+
+每个实现部分产出一个哲学文档（或融入通用层文档的对应章节）。文档必须包含：
+
+1. **部分北极星**：这个部分的判断基准——"遇到冲突时，拿这句话量一下"
+2. **该做什么**：可执行原则，不是口号
+3. **不该做什么**：反模式清单，每条有"为什么"
+4. **参考实践**：至少 2 个真实工具/系统是怎么做这个部分的（要一手实践——源码、文档、工程博客，不要 Wikipedia）
+5. **灵感来源**：满足 LOOM 的源多样性校验
+
+---
+
+## 拆解示例
+
+### 示例 1：CLI 工具（md2html）
+
+```
+项目类型：CLI 工具
+用户接触面：终端
+
+拆解出的实现部分：
+├── CLI 交互设计 — 参数解析、--help、--version、用法提示
+├── CLI 输出美学 — 成功反馈格式、颜色策略、Rule of Silence 的正确理解
+├── CLI 错误呈现 — 错误结构、修复建议、退出码语义
+├── 转换引擎 — 纯函数、子集策略、透传 vs 报错
+└── 产物设计 — HTML 结构、CSS 内联、可预测性
+```
+
+每个部分独立搜索：
+- CLI 交互设计 → 搜 POSIX 参数约定、clap/cobra 设计、ripgrep/fd 的 --help
+- CLI 输出美学 → 搜 "CLI output design color"、bat/exa 的输出风格、Unix Rule of Silence 原文
+- CLI 错误呈现 → 搜 "CLI error message design"、Rust 的 error message 传统、Go 的 error-as-value
+- 转换引擎 → 搜 Markdown 解析策略、纯函数设计、子集 vs 全集
+- 产物设计 → 搜 "self-contained HTML"、CSS 内联策略、可预测输出
+
+### 示例 2：Agent 系统
+
+```
+项目类型：Agent 系统
+用户接触面：对话 + 工具调用结果
+
+拆解出的实现部分：
+├── 系统架构 — 编排 vs 控制、进程边界、IPC 机制
+├── 工具调用哲学 — 委托边界、失控收回、工具描述怎么写
+├── 上下文压缩 — 什么时候压缩、压缩什么、保留什么
+├── 提示词工程 — 角色激活、约束注入、上下文窗口管理
+├── 验证哲学 — 怎么信、怎么验、自动化 vs 人类
+└── 失败与恢复 — 崩溃恢复、状态一致性、回滚策略
+```
+
+每个部分独立搜索：
+- 系统架构 → 搜 "agent orchestration architecture"、LangChain/AutoGPT/CrewAI 架构设计
+- 工具调用 → 搜 "tool calling philosophy"、OpenAI function calling 设计、MCP 协议
+- 上下文压缩 → 搜 "LLM context window management"、conversation summarization 策略
+- 提示词工程 → 搜 "prompt engineering philosophy"、system prompt 设计、role activation
+- 验证哲学 → 搜 "AI agent verification"、human-in-the-loop 设计、automated verification
+- 失败与恢复 → 搜 "agent failure recovery"、state management、checkpoint 设计
+
+### 示例 3：Web 前端
+
+```
+项目类型：Web 前端
+用户接触面：浏览器
+
+拆解出的实现部分：
+├── 视觉设计哲学 — 排版、色彩、留白、层次
+├── 交互反馈哲学 — 加载状态、错误提示、成功反馈、动效
+├── 数据获取哲学 — 缓存策略、乐观更新、错误重试、loading 边界
+├── 组件设计哲学 — 组件粒度、状态边界、复用策略
+└── 性能哲学 — 首屏速度、包体积、渲染策略
+```
+
+---
+
+## 拆解的元原则
+
+1. **不预设结果**——拆解出的部分由 Agent 根据项目特征判断，不是查表
+2. **用户接触面优先**——用户能看到的部分，哲学约束最重要
+3. **每个部分独立可搜索**——"CLI 输出美学"能独立搜到好实践，"整个 CLI 的哲学"太泛搜不到有用的
+4. **部分之间可以有依赖**——"CLI 错误呈现"依赖"CLI 交互设计"的参数约定，这是正常的
+5. **部分数量适中**——小项目 3-5 个部分，大项目 6-10 个，超过 10 个考虑合并
+6. **拆解结果要记录**——在哲学文档里显式列出"本项目拆解出哪些实现部分"，供 Architect 和 Forge 引用
+
+---
+
+## 与通用层的关系
+
+通用层（产品哲学 / 工程哲学 / 协作哲学）回答"**为什么**"——产品为什么存在、代码怎么写、团队怎么协作。
+
+实现部分层回答"**怎么做**"——CLI 的帮助信息怎么做、Agent 的工具调用怎么做、前端的交互反馈怎么做。
+
+两层正交，缺一不可：
+- 通用层是地基。没有产品哲学，实现部分的哲学就没有判断基准
+- 实现部分层是落地。没有部分哲学，通用层就飘在空中，Forge 实现时不知道该对照什么
+
+---
+
+## 与 Architect 的接口
+
+Weaver 拆解出的实现部分，是 Architect 设计架构的输入：
+
+1. Weaver 产出"实现部分清单"（在哲学文档里显式列出）
+2. Architect 读这个清单，为每个部分设计对应的模块/子系统
+3. 每个模块的接口设计，对照该部分的哲学约束
+4. Forge 实现某个模块时，引用该部分的哲学文档作为约束
+
+从哲学到架构到实现，每个环节都有约束传递链。
+
+---
+
+## 搜索时的关键提醒
+
+对每个实现部分搜索时，别只搜"哲学"——实践领域的知识很少叫"哲学"，但就是哲学：
+
+- 搜 "best practices"
+- 搜 "design conventions"
+- 搜 具体工具名 + "design"（如 "ripgrep output design"）
+- 搜 具体库的文档（如 clap 的 README、cobra 的 design doc）
+- 搜 标准文档（如 POSIX、IEEE）
+- 搜 工程博客（如 Stripe engineering blog、Cloudflare blog）
+
+实践驱动的领域，知识在工具和标准里，在论文里的反而少。按 `SEARCH_METHODOLOGY.md` 的领域形态判断走对应路径。