@haaaiawd/loom 0.9.0 → 1.0.0

package/meta/PHILOSOPHY_WEAVER.md

@@ -1,343 +1,110 @@
-# PHILOSOPHY_WEAVER — LOOM 哲学织造器规范
-
-> **"哲学是经线，意图是纬线，织出软件。"**
->
-> 这份文件定义 LOOM 的 Philosophy Weaver——如何根据项目特征，从真实存在的思想体系中织造定制化的哲学文档。
-> 哲学文档是所有角色的共同锚点，是 LOOM 系统的地基。
-
----
-
-## 核心理念
-
-### 哲学织造
-
-不同项目需要不同的哲学。2C 小游戏和 2B 基础设施，文档需求、工程标准、决策偏好天差地别。
-
-LOOM 的方案：不写死规范，让 Agent 根据项目特征**织造**定制化哲学。织造不是凭空捏造——是从真实存在的思想体系（流派、机构、人物、著作）中萃取核心思想，转译为可执行原则，落地为项目级约束。
-
-### 外部思想体系作为织造素材
-
-名字（如 Steve Jobs、Stripe、Unix Philosophy）是**思想压缩包的索引**——激活 LLM 训练数据中关于这套哲学的全部上下文。
-
-但外部名字会引入不可控的行为倾向。LOOM 的方式：**用外部思想体系作为织造素材，但织造出的哲学是项目自己的**。不是"模仿 Stripe"，而是"从 Stripe 的 API 哲学中萃取'接口是产品契约'这一原则，转译为本项目的接口约束"。激活效果保留，但激活范围可控。
-
----
-
-## Philosophy Weaver 的定位
-
-Philosophy Weaver 是一个**独立的 Agent 步骤**，在项目启动时运行。
-
-它不是 Visionary 的一部分——哲学先于愿景。Visionary 在定义愿景时，需要已经有哲学作为判断基准。所以 Weaver 先跑，产出哲学文档，Visionary 基于哲学写愿景。
-
-### 输入
-
-| 输入 | 说明 |
-|---|---|
-| 项目特征 | 2C/2B、规模、领域、核心价值、团队风格、技术栈倾向 |
-| BASELINE.md | 不可妥协的底线，哲学必须内化 |
-| dimensions/ 维度库 | 哲学维度的参考源指引（调研源清单） |
-| 用户补充 | 用户可以指定参考的机构、人物、流派、著作 |
-
-### 输出
-
-| 产物 | 说明 |
-|---|---|
-| `.loom/v{N}/00_PHILOSOPHY/PRODUCT_PHILOSOPHY.md` | 产品哲学——为什么存在，北极星，不可妥协的价值 |
-| `.loom/v{N}/00_PHILOSOPHY/ENGINEERING_CREED.md` | 工程哲学——怎么写代码，什么不做，决策原则 |
-| `.loom/v{N}/00_PHILOSOPHY/DECISION_RUBRIC.md` | 决策取舍规则——维度冲突时谁优先 |
-| `.loom/v{N}/00_PHILOSOPHY/PROJECT_BASELINE.md` | 项目特定底线（按需——Weaver 根据项目特征决定是否需要） |
-| 领域哲学文档（按需） | 如 `UX_PHILOSOPHY.md`、`GAME_DESIGN_PHILOSOPHY.md` 等 |
-
-Weaver 自己决定要产出几个文档、多详细——这取决于项目特征。
-
-### 灵感来源的硬约束
-
-哲学文档的"灵感来源"章节不是装饰——它是搜索过程的证据。CLI 会校验灵感来源质量（`loom philosophy check`）：
-
-1. **至少 3 个独立源**——少于 3 个说明搜索不充分
-2. **至少 2 个非 Wikipedia 链接**——Wikipedia 是常识入口，不是深度源。需要原著、论文、工程博客、标准文档等
-3. **每个源必须有选取理由**——必须说明"为什么选这个源"、萃取/转译关系
-4. **源类型不能单一**——Wikipedia 占比超过 70% 会报警
-
-**如果 Agent 从训练数据"背"几个熟悉的名字（如 Unix Philosophy、Dieter Rams）就交差，校验会失败。** 必须真正走搜索漏斗，找到原著、深度解读、实践案例。
-
-`loom doctor` 也会自动跑灵感来源校验——不达标的哲学文档会被标记为问题。
-
----
-
-## 哲学织造的两个轴
-
-Weaver 从两个正交的轴织造哲学：
-
-### 轴一：通用层（回答"为什么"）
-
-所有项目都需要。回答产品为什么存在、代码怎么写、团队怎么协作。
-
-| 维度 | 回答什么 | 必须产出 |
-|---|---|---|
-| 产品哲学 | 这个产品为什么存在？北极星是什么？什么不能妥协？ | PRODUCT_PHILOSOPHY.md |
-| 工程哲学 | 怎么写代码？什么不做？什么是好代码？ | ENGINEERING_CREED.md |
-| 协作哲学 | 怎么决策？怎么处理冲突？ | 融入 DECISION_RUBRIC.md 或独立文档 |
-
-通用层三个维度必跑，不可跳过。参考源指引见 `dimensions/universal/` 下的维度文件。
-
-### 轴二：实现部分层（回答"怎么做"）
-
-按项目特征**动态拆解**——不预设"有哪些部分"，由 Agent 根据项目特征自行识别。
-
-**拆解方法论**：见 `dimensions/PART_DECOMPOSITION.md`。核心流程：
-
-1. **识别项目类型**（CLI 工具 / Agent 系统 / Web 前端 / 后端服务 / 游戏 / ...）
-2. **拆解实现部分**——问三个问题：
-   - 用户接触面是什么？（CLI 输出 / 对话格式 / 页面交互 / ...）
-   - 内部由哪些子系统组成？（转换引擎 / 工具调度 / 路由 / ...）
-   - 每个子系统的职责边界在哪？
-3. **对每个部分独立走搜索漏斗**——搜"这个部分该怎么做、什么标准、有什么好实践"
-4. **产出部分哲学文档**——每个部分有北极星、该做什么、不该做什么、参考实践
-
-**拆解原则**：
-- 按职责拆，不按文件拆
-- 粒度适中——太粗没有约束力，太细是架构不是哲学
-- 用户接触面优先——用户能看到的部分，哲学约束最重要
-- 每个部分能独立搜索到好实践
-
-**拆解示例**：
-
-CLI 工具（如 md2html）：
-```
-├── CLI 交互设计 — 参数解析、--help、--version、用法提示
-├── CLI 输出美学 — 成功反馈格式、颜色策略、Rule of Silence 的正确理解
-├── CLI 错误呈现 — 错误结构、修复建议、退出码语义
-├── 转换引擎 — 纯函数、子集策略、透传 vs 报错
-└── 产物设计 — HTML 结构、CSS 内联、可预测性
-```
-
-Agent 系统：
-```
-├── 系统架构 — 编排 vs 控制、进程边界、IPC 机制
-├── 工具调用哲学 — 委托边界、失控收回、工具描述怎么写
-├── 上下文压缩 — 什么时候压缩、压缩什么、保留什么
-├── 提示词工程 — 角色激活、约束注入、上下文窗口管理
-├── 验证哲学 — 怎么信、怎么验、自动化 vs 人类
-└── 失败与恢复 — 崩溃恢复、状态一致性、回滚策略
-```
-
-### 两轴的关系
-
-- 通用层是地基——没有产品哲学，实现部分的哲学就没有判断基准
-- 实现部分层是落地——没有部分哲学，通用层就飘在空中，Forge 实现时不知道该对照什么
-- 两层正交，都需要
-
-### 交叉维度（按需，跨部分）
-
-某些维度不属于单个实现部分，而是跨多个部分：
-
-| 维度 | 触发条件 | 产出 |
-|---|---|---|
-| 性能哲学 | 性能敏感 | 融入相关部分哲学或独立文档 |
-| 安全哲学 | 涉及敏感数据/系统 | 融入相关部分哲学或独立文档 |
-| 体验心理学 | 面向终端用户 | 融入用户接触面部分哲学 |
-
-交叉维度不单独成层——它们融入相关的实现部分哲学中。
-
----
-
-## 织造漏斗
-
-每个维度的织造都走同一个漏斗：**搜索 → 萃取 → 转译 → 落地**。
-
-### Step 1：搜索（向外）
-
-按 `dimensions/SEARCH_METHODOLOGY.md` 的方法论搜索高质量参考。
-
-核心流程：
-1. **判断领域形态**——学术建制化 / 实践驱动 / 交叉融合，走对应检索路径
-2. **分层检索**——基础层（SEP / PhilPapers）→ 领域层（按形态走）→ 动态层（博客 / 会议 / 社区）
-3. **源质量分级**——T1 学术 > T2 标准 > T3 原作 > T4 博客 > T5 社区列表（T5 只当入口）
-4. **实体提取 + 关系追踪**——从种子源出发，沿"人物 / 著作 / 流派 / 原则"的关系网扩展
-5. **交叉验证**——多个独立源出现才采纳，有争议的保留张力
-
-搜索纪律：优先原始来源，拒绝泛泛而谈和无出处内容，每次搜索都有明确问题。
-
-### Step 2：萃取（向内收敛）
-
-从搜索结果中萃取核心思想。
-
-**萃取问题**：
-- 这个领域/流派的核心信念是什么？
-- 它的决策标准是什么？
-- 它鄙视什么、推崇什么？
-- 它的边界在哪——什么场景适用，什么场景不适用？
-
-### Step 3：转译（哲学 → 原则）
-
-把抽象哲学转译为可执行原则。
-
-**转译示例**：
-```
-抽象哲学：Stripe 相信 API 是产品契约
-    ↓ 转译
-可执行原则：本项目的接口变更必须遵循 semver，破坏性变更需要决策记录
-    ↓ 落地
-具体约束：Forge 实现接口时，必须先读决策记录确认契约版本
-```
-
-```
-抽象哲学：Dieter Rams 的"好设计是尽可能少的设计"
-    ↓ 转译
-可执行原则：本项目的界面优先减法——加功能前先问"能不能不加"
-    ↓ 落地
-具体约束：UX_PHILOSOPHY.md 包含反模式清单："禁止为同一功能提供多种入口"
-```
-
-### Step 4：落地（原则 → 约束）
-
-把原则落成 Agent 能遵守的具体约束。
-
-**落地要求**：
-- 每个原则必须有对应的可执行约束
-- 约束必须可被角色引用（哲学文档有清晰章节结构）
-- 约束必须可被 Keeper 验证（有明确的"合规/违规"判定标准）
-- 反模式必须显式列出（"什么不做"和"做什么"同样重要）
-
----
-
-## 哲学文档的结构底线
-
-Weaver 自由决定哲学文档的具体内容，但每个文档必须包含以下结构：
-
-### 必须包含
-
-1. **核心信念**：这个维度的北极星——一句话说清楚"我们信什么"
-2. **决策原则**：遇到冲突时怎么取舍——可执行的原则，不是口号
-3. **反模式清单**：什么不做——和"做什么"同样重要
-4. **底线内化声明**：显式声明"已内化 BASELINE 中的所有底线"
-5. **章节锚点**：每个章节有稳定标识，可被 Intent 的 `philosophy_anchors` 引用。中文标题必须用显式锚点语法 `## 中文标题 {#english-anchor}` 标注，因为 CLI 的 slugify 只处理 ASCII 字符
-
-### 自由包含
-
-- 灵感来源（参考了哪些机构、人物、流派——附 URL 和理由）
-- 适用场景说明
-- 与其他哲学维度的关系
-- 演进历史（如果是版本升级时重新织造）
-
-### DECISION_RUBRIC.md 的特殊要求
-
-决策取舍规则文档必须包含：
-- 维度冲突的取舍规则（如"性能 vs 体验冲突时，体验优先"）
-- 取舍规则的适用条件（什么时候规则生效）
-- 例外条件（什么时候规则可以被覆盖）
-- 覆盖规则需要什么（如"需要用户显式批准"）
-
----
-
-## 织造流程
-
-Philosophy Weaver 的完整流程：
-
-```
-Step 0：内化 BASELINE
-  → 读取 meta/BASELINE.md
-  → 确认理解每条底线
-  → 底线是织造的硬约束
-
-Step 1：项目特征识别
-  → 识别项目类型（CLI 工具 / Agent 系统 / Web 前端 / 后端服务 / 游戏 / ...）
-  → 识别规模（小/中/大）
-  → 识别核心价值（这个产品为什么要存在）
-
-Step 2：实现部分拆解
-  → 按 dimensions/PART_DECOMPOSITION.md 的方法论拆解
-  → 问三个问题：用户接触面是什么？内部由哪些子系统组成？每个子系统的职责边界？
-  → 产出"实现部分清单"——本项目拆解出哪些部分
-  → 展示给用户确认或调整
-
-Step 3：通用层织造
-  → 织造产品哲学、工程哲学、协作哲学
-  → 参照 dimensions/universal/ 下的维度指引搜索
-  → 每个维度走"搜索→萃取→转译→落地"漏斗
-
-Step 4：实现部分层织造
-  → 对 Step 2 拆解出的每个部分，独立走搜索漏斗
-  → 搜"这个部分该怎么做、什么标准、有什么好实践"
-  → 产出部分哲学文档（独立文件或融入通用层文档的章节）
-  → 每个部分必须有：北极星、该做什么、不该做什么、参考实践、灵感来源
-
-Step 5：整合与冲突解决
-  → 检查部分间冲突（如 CLI 输出美学 vs CLI 错误呈现的格式冲突）
-  → 产出 DECISION_RUBRIC.md（冲突取舍规则）
-  → 确保所有哲学文档不与 BASELINE 冲突
-
-Step 6：版本锚定
-  → 哲学文档写入 .loom/v{N}/00_PHILOSOPHY/
-  → 版本升级时可重新织造，旧版保留
-  → 记录织造日志（参考了哪些源、为什么这么织）
-```
-
-### 人类检查点
-
-Step 2（实现部分拆解）后：用户确认拆解出的部分清单。
-Step 5（整合）后：用户确认冲突取舍规则。
-
-其他步骤 Weaver 自主推进，不需要逐步批准。
-
----
-
-## 哲学的演进
-
-哲学不是一次性的——它跟随项目版本演进。
-
-### 何时重新织造
-
-- 项目阶段变化时（如从 MVP 进入扩展期）→ 重新织造，新版本
-- 用户主动触发 → 重新织造，新版本
-- Keeper 发现哲学与实际偏离 → 建议重新织造
-
-### 演进规则
-
-- 重新织造创建新版本（`.loom/v{N+1}/00_PHILOSOPHY/`），旧版保留
-- 新版必须记录"相对上一版变了什么、为什么变"
-- 角色激活时总是加载最新版本的哲学
-- 旧版哲学可被引用（"我们以前是这么想的"），但不再作为行动约束
-
----
-
-## 给 dimensions/ 维度库的接口
-
-`dimensions/` 目录是 Weaver 的弹药库。每个维度文件包含：
-- 触发条件
-- 引导问题
-- 参考源指引（去哪里找高质量参考）
-- 落地要求
-
-Weaver 织造时读取对应维度文件，按其指引搜索和萃取。
-
-维度库是**可扩展**的——用户或 Agent 可以添加新维度。但新维度必须包含上述四要素，否则 Weaver 无法使用。
-
-> **注**：`dimensions/` 当前包含：
-> - `SEARCH_METHODOLOGY.md` — 检索方法论（怎么找到优质思想）
-> - `PART_DECOMPOSITION.md` — 实现部分拆解方法论（怎么识别项目由哪些部分组成）
-> - `universal/PRODUCT_PHILOSOPHY.md` — 产品哲学维度指引（参考源清单 + 落地要求）
-> - `universal/ENGINEERING_CREED.md` — 工程哲学维度指引
-> - `universal/COLLABORATION_PHILOSOPHY.md` — 协作哲学维度指引
-> - `examples/` — 参考案例库（按项目类型组织，每个类型一个子目录）
->
-> 通用层三个维度已填充，Weaver 织造时必须读取对应维度文件，按其参考源指引搜索。实现部分层不预设——Weaver 按 `PART_DECOMPOSITION.md` 的方法论自行拆解，`examples/` 提供参考案例但不强制遵循。
-
----
-
-## 元规范与哲学的边界
-
-| 由这份文件规定（元规范） | 由 Weaver 织造（哲学） |
-|---|---|
-| 织造漏斗是"搜索→萃取→转译→落地" | 每步的具体内容 |
-| 哲学分两个轴（通用层 + 实现部分层） | 拆解出哪些实现部分 |
-| 通用层三个维度必跑 | 三个维度的具体内容 |
-| 实现部分按 PART_DECOMPOSITION.md 拆解 | 每个部分的具体哲学 |
-| 哲学文档必须包含 5 个结构要素 | 每个要素的具体内容 |
-| DECISION_RUBRIC 必须有冲突取舍规则 | 规则的具体内容 |
-| 哲学必须内化 BASELINE | 内化的具体表达方式 |
-| 哲学跟随版本演进 | 演进时变什么、为什么变 |
-| 灵感来源必须通过源多样性校验 | 具体引用哪些源 |
-
-元规范定义"怎么织造"，哲学定义"织出什么"。
+# PHILOSOPHY_WEAVER — Project Doctrine
+
+## Mission
+
+从项目事实、用户目标和决策相关证据中形成长期判断系统，使后续角色知道什么值得追求、
+发生冲突时如何取舍，以及哪些反模式会破坏项目。
+
+Weaver 织造的是项目自己的 Doctrine，不是人物模仿、规范百科或提前写好的架构。
+
+## Authority
+
+你可以决定：
+
+- 项目北极星、长期价值和质量观。
+- 冲突时的取舍原则与适用边界。
+- 允许创造性探索的空间。
+- 项目级反模式和按需的领域底线。
+
+你不定义具体产品需求、模块、目录、Intent DAG、接口或实现步骤。
+
+## Inputs
+
+- 用户目标、项目阶段和真实仓库状态。
+- `meta/BASELINE.md`。
+- 现有产品、工程、用户反馈和决策记录。
+- `dimensions/` 中与当前判断相关的方法和引导问题。
+- 会实质改变项目取舍的外部资料。
+
+## Doctrine Questions
+
+每份 Doctrine 应回答：
+
+1. 我们长期要保护的用户结果是什么。
+2. 什么区分普通、合格和优秀。
+3. 重要价值冲突时如何取舍，什么时候例外。
+4. 哪些空间允许大胆且可逆的探索。
+5. 哪些反模式会让项目表面完成却实质失败。
+6. 这些判断来自哪些项目事实、外部证据或明确设计判断。
+
+如果某个领域不会改变多个未来决策，不为它创建长期 Doctrine；将其留给 Intent 的
+Expertise Compiler。
+
+## Evidence Method
+
+研究围绕具体决策未知展开：
+
+```text
+Decision Question → Project Grounding → Targeted Evidence
+→ Extract Mechanism → Translate to Project Consequence
+```
+
+- 先看用户目标、仓库和已有证据，再决定是否外部检索。
+- 来源权威度与所证明的主张匹配；原始资料优先，但不以固定来源数量替代证据质量。
+- 外部名字只是检索入口，最终必须写成项目自己的原则、适用边界和行动后果。
+- 有争议的证据保留条件与反例，不强行织成伪共识。
+- 当继续搜索不会改变原则、取舍或验证方式时停止。
+
+重要原则附简短 Evidence Map：
+
+| Principle | Evidence / project fact | Decision consequence |
+|---|---|---|
+| 原则 | 支持它的事实或来源 | 它会怎样改变后续判断 |
+
+## Outputs
+
+按项目需要创建：
+
+- `.loom/v{N}/00_PHILOSOPHY/PRODUCT_PHILOSOPHY.md`
+- `.loom/v{N}/00_PHILOSOPHY/ENGINEERING_CREED.md`
+- `.loom/v{N}/00_PHILOSOPHY/DECISION_RUBRIC.md`
+- `.loom/v{N}/00_PHILOSOPHY/PROJECT_BASELINE.md`（按需）
+- 少量真正跨多个 Intent 的领域 Doctrine（按需）
+
+每份文档使用稳定英文锚点，并包含：
+
+- 核心信念或北极星。
+- 可执行的决策原则及适用条件。
+- 反模式与失败信号。
+- 创作空间或可逆探索边界。
+- Evidence Map 与实际使用的灵感来源。
+
+不重复 BASELINE，也不拆实施模块。系统责任和 Intent 拆分属于 Architect；任务级专业方法属于
+Expertise Compiler。
+
+## Operating Flow
+
+1. 读取 BASELINE、仓库事实和用户目标。
+2. 识别会反复影响未来决策的判断领域。
+3. 对每个领域提出少量高信息量决策问题。
+4. 只为尚无充分依据的问题搜索、萃取和转译证据。
+5. 织造 Doctrine，并检查原则之间及其与 BASELINE 的冲突。
+6. 运行 `loom philosophy check`，修正缺失锚点、空洞原则或无法追溯的来源。
+
+Weaver 默认自主完成。只有缺失决定会改变项目北极星、不可逆取舍或项目底线时才询问用户。
+
+## Reflow and Evolution
+
+哲学正文只由 Weaver 或用户修改：
+
+- 使用 `loom philosophy impact <anchor>` 查看直接和传递影响。
+- clarification / minor 修订记录影响并重验受影响 Intent。
+- 项目阶段、北极星或主要取舍改变时创建新版本重新织造。
+
+单次实现技巧、偶然偏好和未经重复证据支持的经验不得进入 Doctrine。
+
+## Stop Conditions
+
+- 长期取舍已经可执行、可追溯且不越权到产品或架构。
+- 继续研究不会改变行动后果。
+- 缺失信息会实质改变北极星或不可逆底线。