@haaaiawd/loom 0.7.0 → 0.9.0

package/cli/src/guide.js

@@ -36,17 +36,17 @@ 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) {
-  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)) {
-    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 auto = isAutoOn(loomRoot);
+  const result = diagnoseStage(cwd, loomRoot, auto);
+  // 统一后处理：写心跳 + 加 AUTO 提示词 + 判断是否需要人类 review
+  if (existsSync(loomRoot) && !options.dryRun) {
+    try {
+      writeHeartbeat(loomRoot, {
         stage: result.stage,
         stage_num: result.stage_num,
         next_command: result.next_command,
@@ -145,9 +145,11 @@ function diagnoseStage(cwd, loomRoot, auto) {
   }
 
   // 状态 4-7: Intent Map 已设计，根据 Intent 状态判断
-  let intents;
-  try {
-    intents = loadIntentMap(versionDir).intents;
+  let intentMap;
+  let intents;
+  try {
+    intentMap = loadIntentMap(versionDir);
+    intents = intentMap.intents;
   } catch (e) {
     return {
       stage: 'intent_map_broken',
@@ -218,7 +220,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 = intents._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

@@ -1,6 +1,7 @@
 // philosophy.js — 按锚点加载哲学文档的特定章节
 // 哲学文档是 MD，锚点格式: "PRODUCT_PHILOSOPHY.md#core-belief"
 // 这个库按锚点提取对应章节，不返回整个文件。
+// 另含灵感来源校验——防止 Weaver 从训练数据"背"几个名字就交差。
 
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
@@ -44,3 +45,262 @@ export function listPhilosophyFiles(philosophyDir) {
   const dir = readdirSync(philosophyDir);
   return dir.filter((f) => f.endsWith('.md'));
 }
+
+// ─── 灵感来源校验 ───────────────────────────────────────
+// 防止 Weaver 从训练数据"背"几个名字就交差。
+// 校验规则：
+//   1. 至少 3 个独立源
+//   2. 至少 2 个非 Wikipedia 链接（Wikipedia 是常识入口，不是深度源）
+//   3. 每个源必须有"为什么选它"的理由（萃取/理由/为什么 等关键词）
+//   4. 源不能全是同一类型（如全是 Wikipedia、全是博客）
+
+const MIN_SOURCES = 3;
+const MIN_NON_WIKI = 2;
+const REASON_KEYWORDS = ['萃取', '理由', '为什么', '因为', '启发', '借鉴', '参考理由', '选取理由', '转译'];
+
+/**
+ * 从哲学文档内容中提取"灵感来源"章节的条目。
+ * @param {string} content — MD 全文
+ * @returns {Array<{ raw: string, name: string, urls: string[], hasReason: boolean }>}
+ *   如果返回空数组，调用方需区分"没有章节"和"有章节但没条目"——
+ *   用 hasInspirationSection() 单独判断。
+ */
+function parseInspirationSources(content) {
+  // 匹配 "## 灵感来源" 或 "## Inspiration Sources" 等章节
+  // 支持 {#anchor} 后缀和多种标题变体
+  const sectionMatch = content.match(/^##\s+(?:灵感来源|Inspiration|参考来源|References?|参考文献|参考资料|Sources|Bibliography)/m);
+  if (!sectionMatch) return [];
+
+  const startIdx = sectionMatch.index + sectionMatch[0].length;
+  // 找到下一个 ## 或文件末尾
+  const nextSection = content.slice(startIdx).match(/\n##\s/m);
+  const sectionText = nextSection
+    ? content.slice(startIdx, startIdx + nextSection.index)
+    : content.slice(startIdx);
+
+  // 解析每个 list item（- / * / 1. / 2. 等开头的无序或有序列表）
+  const items = [];
+  const lines = sectionText.split('\n');
+  let currentItem = null;
+
+  // 匹配 - xxx / * xxx / 1. xxx / 2. xxx 等
+  const ITEM_RE = /^\s*(?:[-*]|\d+\.)\s+/;
+
+  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 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]);
+      currentItem.urls.push(...newUrls);
+      if (REASON_KEYWORDS.some((kw) => line.includes(kw))) {
+        currentItem.hasReason = true;
+      }
+    }
+  }
+  if (currentItem) items.push(currentItem);
+  return items;
+}
+
+/**
+ * 检查哲学文档是否有"灵感来源"章节（不管有没有条目）。
+ * 用来区分"没有章节"和"有章节但没条目"两种情况。
+ */
+function hasInspirationSection(content) {
+  return /^##\s+(?:灵感来源|Inspiration|参考来源|References?|参考文献|参考资料|Sources|Bibliography)/m.test(content);
+}
+
+/**
+ * 判断 URL 是否为 Wikipedia 链接。
+ */
+function isWikipediaUrl(url) {
+  return /wikipedia\.org/i.test(url);
+}
+
+/**
+ * 校验哲学文档的灵感来源质量。
+ * @param {string} philosophyDir — 00_PHILOSOPHY/ 目录路径
+ * @returns {{ passed: boolean, issues: Array<{severity: string, msg: string}>, sources: Array }}
+ */
+export function validateInspirationSources(philosophyDir) {
+  const issues = [];
+  const allSources = [];
+
+  // 扫描目录下所有 .md 文件，找"灵感来源"章节
+  const files = listPhilosophyFiles(philosophyDir);
+
+  for (const file of files) {
+    const content = readFileSync(join(philosophyDir, file), 'utf-8');
+    const sources = parseInspirationSources(content);
+    if (sources.length === 0) continue;
+
+    allSources.push({ file, sources });
+
+    // 校验每个文件的灵感来源
+    if (sources.length < MIN_SOURCES) {
+      issues.push({
+        severity: 'high',
+        msg: `${file}: 灵感来源仅 ${sources.length} 条，要求至少 ${MIN_SOURCES} 条。可能从训练数据"背"了几个名字就交差。`,
+      });
+    }
+
+    const nonWikiUrls = sources.filter((s) => s.urls.length > 0 && !s.urls.every(isWikipediaUrl));
+    if (nonWikiUrls.length < MIN_NON_WIKI) {
+      issues.push({
+        severity: 'high',
+        msg: `${file}: 非 Wikipedia 链接仅 ${nonWikiUrls.length} 个，要求至少 ${MIN_NON_WIKI} 个。Wikipedia 是常识入口，不是深度源——需要原著、论文、工程博客、标准文档等。`,
+      });
+    }
+
+    for (const src of sources) {
+      if (!src.hasReason) {
+        issues.push({
+          severity: 'medium',
+          msg: `${file}: 灵感来源 "${src.name}" 缺乏选取理由。必须说明"为什么选这个源"——萃取/转译/启发关系。`,
+        });
+      }
+      if (src.urls.length === 0) {
+        issues.push({
+          severity: 'medium',
+          msg: `${file}: 灵感来源 "${src.name}" 没有 URL。必须附可验证的来源链接。`,
+        });
+      }
+    }
+  }
+
+  // 全局校验：所有文件的灵感来源加起来，源类型不能单一
+  const totalUrls = allSources.flatMap((s) => s.sources).flatMap((s) => s.urls);
+  if (totalUrls.length > 0) {
+    const wikiCount = totalUrls.filter(isWikipediaUrl).length;
+    if (wikiCount / totalUrls.length > 0.7) {
+      issues.push({
+        severity: 'medium',
+        msg: `全部灵感来源中 Wikipedia 占比 ${Math.round((wikiCount / totalUrls.length) * 100)}%——源类型过于单一。需要原著、论文、标准文档、工程博客等多元源。`,
+      });
+    }
+  }
+
+  // 如果没有任何文件提取到灵感来源条目
+  if (allSources.length === 0) {
+    // 区分两种情况：完全没有章节 vs 有章节但没条目
+    const filesWithSection = [];
+    for (const file of files) {
+      const content = readFileSync(join(philosophyDir, file), 'utf-8');
+      if (hasInspirationSection(content)) filesWithSection.push(file);
+    }
+
+    if (filesWithSection.length > 0) {
+      issues.push({
+        severity: 'high',
+        msg: `${filesWithSection.join(', ')} 有"灵感来源"章节但没有可识别的条目。章节里可能是模板占位符。需要 Weaver 真正走搜索漏斗，填入至少 ${MIN_SOURCES} 个源（- **源名** — 理由。来源：URL 格式）。`,
+      });
+    } else {
+      issues.push({
+        severity: 'high',
+        msg: '所有哲学文档都没有"灵感来源"章节。PHILOSOPHY_WEAVER.md 要求哲学文档必须包含灵感来源（参考了哪些机构、人物、流派——附 URL 和理由）。支持的标题：灵感来源 / Inspiration / 参考来源 / References / 参考文献 / 参考资料 / Sources / Bibliography。',
+      });
+    }
+  }
+
+  return {
+    passed: issues.length === 0,
+    issues,
+    sources: allSources,
+  };
+}
+
+// ─── 实现部分清单校验 ───────────────────────────────────
+// 检查哲学文档是否包含"实现部分清单"——Weaver 是否走了拆解流程。
+// PHILOSOPHY_WEAVER.md Step 2 要求产出"实现部分清单"。
+
+/**
+ * 校验哲学文档是否包含实现部分拆解清单。
+ * Weaver 按 PART_DECOMPOSITION.md 拆解后，必须在哲学文档里显式列出拆解出的部分。
+ * @param {string} philosophyDir — 00_PHILOSOPHY/ 目录路径
+ * @returns {{ passed: boolean, issues: Array<{severity: string, msg: string}>, parts: string[] }}
+ */
+export function validatePartDecomposition(philosophyDir) {
+  const issues = [];
+  const parts = [];
+
+  const files = listPhilosophyFiles(philosophyDir);
+
+  // 搜索"实现部分"相关章节——支持 {#anchor} 后缀和多种标题变体
+  const PART_SECTION_PATTERNS = [
+    /^##\s+实现部分清单/m,
+    /^##\s+部分拆解/m,
+    /^##\s+实现部分/m,
+    /^##\s+Part Decomposition/m,
+    /^##\s+Implementation Parts/m,
+    /^##\s+拆解出的部分/m,
+    /^##\s+Implementation Decomposition/m,
+    /^##\s+Parts? /m,
+  ];
+
+  // 搜索部分条目——支持无序列表、有序列表、树形符号
+  const PART_ITEM_PATTERNS = [
+    /^\s*[-*]\s+\*\*(.+?)\*\*/gm,    // - **CLI 交互设计**
+    /^\s*\d+\.\s+\*\*(.+?)\*\*/gm,   // 1. **CLI 交互设计**
+    /^\s*\d+\.\s+(.+)/gm,            // 1. CLI 交互设计
+    /^\s*├──\s+(.+)/gm,              // ├── CLI 交互设计
+    /^\s*└──\s+(.+)/gm,              // └── 产物设计
+  ];
+
+  let foundSection = false;
+
+  for (const file of files) {
+    const content = readFileSync(join(philosophyDir, file), 'utf-8');
+
+    // 检查是否有实现部分章节
+    for (const pattern of PART_SECTION_PATTERNS) {
+      if (pattern.test(content)) {
+        foundSection = true;
+        // 提取该章节的部分条目
+        const sectionMatch = content.match(pattern);
+        if (sectionMatch) {
+          const startIdx = sectionMatch.index + sectionMatch[0].length;
+          const nextSection = content.slice(startIdx).match(/\n##\s/m);
+          const sectionText = nextSection
+            ? content.slice(startIdx, startIdx + nextSection.index)
+            : content.slice(startIdx);
+
+          for (const itemPattern of PART_ITEM_PATTERNS) {
+            const matches = [...sectionText.matchAll(itemPattern)];
+            for (const m of matches) {
+              const partName = m[1].trim().replace(/[—\-–].*$/, '').trim();
+              if (partName && !parts.includes(partName)) {
+                parts.push(partName);
+              }
+            }
+          }
+        }
+        break;
+      }
+    }
+  }
+
+  if (!foundSection) {
+    issues.push({
+      severity: 'high',
+      msg: '哲学文档没有"实现部分清单"章节。PHILOSOPHY_WEAVER.md Step 2 要求按 PART_DECOMPOSITION.md 拆解实现部分，并在哲学文档中显式列出。支持的标题：实现部分清单 / 部分拆解 / 实现部分 / Part Decomposition / Implementation Parts / 拆解出的部分。',
+    });
+  } else if (parts.length < 2) {
+    issues.push({
+      severity: 'medium',
+      msg: `找到"实现部分清单"章节但仅识别到 ${parts.length} 个部分。可能章节里是模板占位符，或条目格式不被识别（用 - **部分名** 或 ├── 部分名 格式）。PART_DECOMPOSITION.md 建议小项目 3-5 个部分，大项目 6-10 个。`,
+    });
+  }
+
+  return {
+    passed: issues.length === 0,
+    issues,
+    parts,
+  };
+}

package/cli/src/preview.js

@@ -1,15 +1,72 @@
-// 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 — 输出提示词，让 AI 读 .loom/ 文件并生成 HTML，并检查投影新鲜度。
+// CLI 不生成 HTML。AI 自己读文件、重组信息、生成 HTML。
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { readCurrentPointer } from './shared/paths.js';
+
+const PROMPT_PATH = new URL('./preview-prompt.md', import.meta.url);
+const SOURCE_FILE_NAMES = new Set([
+  '01_VISION.md',
+  '02_ARCHITECTURE.md',
+  '04_INTENT_MAP.json',
+  '05_VERIFICATION.md',
+  '06_CHANGELOG.md',
+]);
 
 /**
  * 输出 preview 提示词。
  * @returns {string}
  */
-export function generatePreviewPrompt() {
-  return readFileSync(PROMPT_PATH, 'utf-8');
-}
+export function generatePreviewPrompt() {
+  return readFileSync(PROMPT_PATH, 'utf-8');
+}
+
+function shouldIncludeSource(filePath) {
+  const normalized = filePath.replace(/\\/g, '/');
+  const fileName = normalized.split('/').pop();
+  if (SOURCE_FILE_NAMES.has(fileName)) return true;
+  return normalized.includes('/00_PHILOSOPHY/')
+    || normalized.includes('/03_DECISIONS/')
+    || normalized.includes('/verifications/');
+}
+
+function collectSourceFiles(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectSourceFiles(fullPath, files);
+    } else if (shouldIncludeSource(fullPath)) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+export function getPreviewStatus(projectDir) {
+  const previewPath = join(projectDir, 'loom-preview.html');
+  const loomRoot = join(projectDir, '.loom');
+  const current = readCurrentPointer(loomRoot);
+  const versionDir = current ? join(loomRoot, current) : null;
+  const sourceFiles = versionDir ? collectSourceFiles(versionDir) : [];
+  const latestSource = sourceFiles
+    .map((filePath) => ({ filePath, mtimeMs: statSync(filePath).mtimeMs }))
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)[0] || null;
+
+  const exists = existsSync(previewPath);
+  const previewMtimeMs = exists ? statSync(previewPath).mtimeMs : null;
+  const sourceLatestMtimeMs = latestSource?.mtimeMs ?? null;
+  const fresh = exists && sourceLatestMtimeMs !== null && previewMtimeMs >= sourceLatestMtimeMs;
+
+  return {
+    exists,
+    fresh,
+    version: current,
+    preview_path: previewPath,
+    preview_mtime: previewMtimeMs ? new Date(previewMtimeMs).toISOString() : null,
+    source_latest_mtime: sourceLatestMtimeMs ? new Date(sourceLatestMtimeMs).toISOString() : null,
+    latest_source_file: latestSource ? relative(projectDir, latestSource.filePath).replace(/\\/g, '/') : null,
+    next_command: fresh ? 'loom preview' : 'loom preview --regen',
+  };
+}

package/cli/src/verify.js

@@ -92,10 +92,14 @@ export function writeVerification(verificationsDir, record) {
     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({

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` 的领域形态判断走对应路径。