refactor: documents - regroup into principles/guides/case-studies

2026-08-20 14:28:05 +00:00 · 2026-02-28 06:50:35 +08:00
parent 5c341e0f71
commit e35529d8db
52 changed files with 0 additions and 0 deletions
@@ -0,0 +1,29 @@
+# AI蜂群协作
+
+> 基于 tmux 的多 AI Agent 协作系统
+
+## 核心理念
+
+传统模式：人 ←→ AI₁, 人 ←→ AI₂, 人 ←→ AI₃ (人是瓶颈)
+
+蜂群模式：**人 → AI₁ ←→ AI₂ ←→ AI₃** (AI 自主协作)
+
+## 能力矩阵
+
+| 能力 | 实现方式 | 效果 |
+|:---|:---|:---|
+| 🔍 感知 | `capture-pane` | 读取任意终端内容 |
+| 🎮 控制 | `send-keys` | 向任意终端发送按键 |
+| 🤝 协调 | 共享状态文件 | 任务同步与分工 |
+
+## 核心突破
+
+AI 不再是孤立的，而是可以互相感知、通讯、控制的集群。
+
+## 详细文档
+
+👉 [深入了解AI蜂群协作](../02-方法论/AI蜂群协作-tmux多Agent协作系统.md)
+
+## 相关资源
+
+- [tmux快捷键大全](../02-方法论/tmux快捷键大全.md)
@@ -0,0 +1,541 @@
+# Vibe Coding 哲学方法论提效工具箱（Python）
+
+> 目标：把"vibe（探索）"系统化为"可验证、可迭代、可收敛"的工程产出。
+> 每个方法给出：用途 / 落地动作 / Python工具 / 可复制提示词。
+
+## 目录
+
+- [总体作业流](#总体作业流)
+- [推荐底座](#推荐底座python)
+- [方法论](#方法论)
+  - [1. 现象学还原](#1-现象学还原悬置假设)
+  - [2. 正反合](#2-正反合三段迭代)
+  - [3. 可证伪主义](#3-可证伪主义波普尔)
+  - [4. 形式化方法](#4-形式化方法轻量形式化)
+  - [5. 奥卡姆剃刀](#5-奥卡姆剃刀最小复杂度)
+  - [6. 实用主义](#6-实用主义以指标为准)
+  - [7. 系统论/整体论](#7-系统论整体论边界与反馈回路)
+  - [8. 诠释学](#8-诠释学语境澄清)
+  - [9. 钢人化原则](#9-钢人化原则最强版本理解)
+  - [10. 决策论/机会成本](#10-决策论机会成本可逆优先)
+  - [11. 反事实推理](#11-反事实推理counterfactuals)
+  - [12. 溯因推理](#12-溯因推理abduction最佳解释)
+  - [13. 贝叶斯式信念更新](#13-贝叶斯式信念更新与溯因配合)
+  - [14. 反思平衡](#14-反思平衡reflective-equilibrium)
+  - [15. 概念分析/概念工程](#15-概念分析--概念工程)
+  - [16. 方法论怀疑](#16-方法论怀疑笛卡尔式)
+  - [17. 视角三角测量](#17-视角三角测量triangulation)
+  - [18. 机制解释](#18-机制解释mechanistic-explanation)
+  - [19. 错误认识论](#19-错误认识论error-epistemology)
+  - [20. 实验哲学](#20-实验哲学x-phi)
+  - [21. 计算哲学](#21-计算哲学computational-philosophy)
+  - [22. 自然化认识论](#22-自然化认识论naturalized-epistemology)
+  - [23. 贝叶斯认识论](#23-贝叶斯认识论bayesian-epistemology)
+- [附录](#附录)
+- [使用指南](#使用指南)
+
+---
+
+## 总体作业流
+
+建议默认流程：
+
+1. **现象卡片**（现象/意图/情境/边界）→ 清零脑补
+2. **规格化**（类型+schema+错误语义+不变式）→ 可机器检查
+3. **检查器**（单测+性质测试+lint+类型检查+关键断言）→ 可证伪
+4. **最小实现**（main path）→ 快速跑通
+5. **反例驱动**（Hypothesis/边界/差分/基准）→ 找到失败模式
+6. **收敛重构**（删复杂度、固化概念、稳定接口、补文档）→ 可维护
+
+---
+
+## 推荐底座（Python）
+
+```text
+ruff + black + pyright(或 mypy) + pytest + hypothesis + pydantic(msgspec可替代)
+```
+
+---
+
+## 方法论
+
+### 1. 现象学还原（悬置假设）
+
+**用途**：需求含糊、模型脑补、Bug难复现时，先把"解释/偏好"清零，回到可观察事实与可复现结构。
+
+**落地动作**：
+
+- 先写四件套：现象(实际) / 意图(期望) / 情境(环境约束) / 边界(明确不做)
+- 输出最小可复现体 MRE：最小输入 + 最小脚本 + 复现步骤 + 预期vs实际
+- 把抽象词降维：快/稳/好用 → 指标&验收用例
+
+**Python工具**：`pytest`（MRE脚本）、日志、最小数据样例
+
+**提示词**：
+
+```text
+先做现象学还原：不要推测原因。输出：现象/意图/情境/边界/未确定项/MRE；然后再给最小修复与测试。
+```
+
+---
+
+### 2. 正反合（三段迭代）
+
+**用途**：把一次性"写到完美"替换为可控三轮：快速可用 → 反例打脸 → 收敛为工程版本。
+
+**落地动作**：
+
+- **正**：只做 main path，让它跑通
+- **反**：列失败模式（边界/空值/并发/权限/超时/性能），用测试与基准逼出反例
+- **合**：重构接口/收敛依赖/补文档与回归，形成下一轮稳定起点
+
+**Python工具**：`pytest` + `hypothesis` + `ruff/black` + profiling/benchmark
+
+**提示词**：
+
+```text
+按正反合输出：1)最小可运行实现 2)反例与失败模式+测试 3)综合后的重构方案与最终代码。
+```
+
+---
+
+### 3. 可证伪主义（波普尔）
+
+**用途**：把"看起来对"变成"暂时无法证伪"；显著降低隐藏 bug。
+
+**落地动作**：
+
+- 每个关键断言都要配一个能让它失败的测试（边界/随机/反例）
+- 优先性质测试而非只写示例测试
+
+**Python工具**：`hypothesis`（性质/模糊）、`pytest`
+
+**提示词**：
+
+```text
+为该实现列出 5 个可证伪点，并为每个点写一个最小测试（优先 Hypothesis 性质测试）。
+```
+
+---
+
+### 4. 形式化方法（轻量形式化）
+
+**用途**：减少非法状态、约束模型输出、让行为可检查可累积。
+
+**落地动作**：
+
+- **先规格**：类型 + schema + 不变式 + 错误集合（异常或 error object）+ 复杂度约束（可选）
+- **再检查器**：类型检查 + 运行时校验 + 断言/契约 + 性质测试
+- **最后实现**：逐条映射规格（谁保证哪条约束）
+
+**Python工具**：
+
+- `typing`（Literal/NewType/Protocol/TypedDict/Annotated）
+- `pyright/mypy`
+- `pydantic/msgspec`（输入输出校验）
+- `assert` / `icontract` / `deal`
+- `pytest` + `hypothesis`
+
+**提示词**：
+
+```text
+先输出形式化规格（类型/schema/不变式/错误语义），再给至少 3 条 Hypothesis 性质测试，最后写实现并逐条说明满足关系。
+```
+
+---
+
+### 5. 奥卡姆剃刀（最小复杂度）
+
+**用途**：避免模型引入不必要框架/抽象；提升可维护性与迭代速度。
+
+**落地动作**：
+
+- 要求两套方案：常规版 vs 简化版；以测试为准删复杂度
+- 优先标准库、减少依赖、减少可变状态、减少层级
+
+**Python工具**：`ruff`（复杂度/风格）、依赖审计（requirements最小化）
+
+**提示词**：
+
+```text
+在满足全部测试与验收的前提下，把实现复杂度删掉 30%：减少依赖、状态和抽象层，并解释删减理由。
+```
+
+---
+
+### 6. 实用主义（以指标为准）
+
+**用途**：避免"优化方向漂移"；每轮明确一个可量化目标。
+
+**落地动作**：
+
+- 先定义成功指标（P95延迟/错误率/成本/内存/可维护性）
+- 每轮只优化一个指标；其余保持不退化（用基准/回归锁住）
+
+**Python工具**：`pytest-benchmark` 或简单计时；日志与指标；回归测试
+
+**提示词**：
+
+```text
+把需求转成指标与验收阈值，并给出测量方法；本轮只优化 X 指标，保证其它指标不退化。
+```
+
+---
+
+### 7. 系统论/整体论（边界与反馈回路）
+
+**用途**：复杂系统容易在耦合点失控；缩短反馈回路提效最大。
+
+**落地动作**：
+
+- 先画数据流/依赖边界：I/O 放边缘，核心逻辑保持纯函数
+- 优先解耦高耦合点；把慢依赖换成桩/模拟以加速测试
+
+**Python工具**：依赖注入（轻量）、`pytest fixtures`、纯函数设计
+
+**提示词**：
+
+```text
+画出数据流与依赖边界，指出最高耦合点与最短反馈回路改造方案；给出可测试的纯函数核心与 I/O 适配层。
+```
+
+---
+
+### 8. 诠释学（语境澄清）
+
+**用途**：需求文本有歧义，模型与人对同一词理解不同。
+
+**落地动作**：
+
+- 先复述需求 + 歧义清单 + 默认选择（必须显式）
+- 默认选择写入 docstring/README/类型定义
+
+**Python工具**：docstring、类型与 schema 固化默认
+
+**提示词**：
+
+```text
+先复述需求并列出所有歧义点；对每个歧义给默认策略与理由；确认后再写实现与测试。
+```
+
+---
+
+### 9. "钢人化"原则（最强版本理解）
+
+**用途**：减少无效争论/误解；让重构建议更贴近原意图。
+
+**落地动作**：
+
+- 先把现有方案表达成最强版本（目标、约束、权衡）
+- 再提出改进（保留其优势，指出代价）
+
+**Python工具**：PR描述结构化（优点/风险/替代方案）
+
+**提示词**：
+
+```text
+先钢人化现有实现：列出它的最佳解释与优点；再给改进方案并明确代价与风险。
+```
+
+---
+
+### 10. 决策论/机会成本（可逆优先）
+
+**用途**：避免过早做不可逆技术决策（换框架/改数据模型）。
+
+**落地动作**：
+
+- 标注决策：可逆 vs 不可逆；优先做可逆高价值项
+- 先写接口+测试桩+适配层，延后绑定外部系统
+
+**Python工具**：抽象边界、adapter、in-memory 实现
+
+**提示词**：
+
+```text
+把方案拆成可逆/不可逆决策；先给可逆路径的 MVP，实现通过测试；不可逆部分只给接口与占位实现。
+```
+
+---
+
+### 11. 反事实推理（Counterfactuals）
+
+**用途**：系统性覆盖异常路径，降低线上事故。
+
+**落地动作**：
+
+- 问"如果 X 不成立会怎样"：超时、乱序、重复、空值、弱网、权限缺失、时钟漂移
+- 把反事实转成测试矩阵与降级策略
+
+**Python工具**：`pytest` 参数化、`hypothesis` 生成器、超时与重试控制
+
+**提示词**：
+
+```text
+列出 15 个反事实场景并按风险排序；为 Top5 写测试与降级/错误语义。
+```
+
+---
+
+### 12. 溯因推理（Abduction，最佳解释）
+
+**用途**：debug/性能退化时，比穷举更快定位"最可能原因"。
+
+**落地动作**：
+
+- 列候选原因 → 为每个原因写最便宜的区分性实验（日志点/开关/最小基准）
+- 用证据淘汰而不是凭感觉改代码
+
+**Python工具**：结构化日志、trace、最小 benchmark、feature flag
+
+**提示词**：
+
+```text
+给出候选原因列表，并为每个原因提供一个最低成本、最高区分度的验证实验与预期观察。
+```
+
+---
+
+### 13. 贝叶斯式信念更新（与溯因配合）
+
+**用途**：在不确定下理性分配排查时间。
+
+**落地动作**：
+
+- 给假设先验（高/中/低）→ 实验后更新后验排序
+- 只对后验最高的 1-2 个假设投入修改成本
+
+**Python工具**：同 12；加一张"假设-证据"表
+
+**提示词**：
+
+```text
+按先验排序原因；给最信息增益实验；根据可能结果更新排序并给下一步。
+```
+
+---
+
+### 14. 反思平衡（Reflective equilibrium）
+
+**用途**：当用例、原则、约束冲突时收敛规范（尤其 API 语义、错误处理、兼容性）。
+
+**落地动作**：
+
+- 三层对齐：具体用例 ↔ 一般原则 ↔ 系统约束
+- 用测试固化：回归用例（具体判断）+ 性质测试（原则）
+
+**Python工具**：`pytest` + `hypothesis`；规范文档（错误模型/幂等语义）
+
+**提示词**：
+
+```text
+列出用例/原则/约束三集，指出冲突点；给两轮调整方案，每轮说明要改哪些用例、原则或实现以达成一致。
+```
+
+---
+
+### 15. 概念分析 / 概念工程
+
+**用途**：防止术语漂移导致返工；把领域概念固化进代码。
+
+**落地动作**：
+
+- 概念表：术语/定义/边界/不变量/转换关系
+- 概念工程：用 Enum/Literal/NewType/dataclass(frozen) 与 schema 固化边界；禁止混用
+
+**Python工具**：`Enum`、`Literal`、`NewType`、`pydantic` 校验
+
+**提示词**：
+
+```text
+先产出概念表；再映射成 Python 类型与 schema；给 5 个应被拒绝的反例输入，并写对应测试。
+```
+
+---
+
+### 16. 方法论怀疑（笛卡尔式）
+
+**用途**：把不可靠前提当事实是 vibe coding 常见事故源。
+
+**落地动作**：
+
+- 对关键前提标注：是否可验证
+- 不可验证 → 必须加运行时校验/超时/重试/降级；并写会失败的测试
+
+**Python工具**：`assert`/校验器、超时、重试、容错分支测试
+
+**提示词**：
+
+```text
+列出该方案依赖的所有前提，并标注可验证性；对不可验证前提添加防线（校验/超时/降级）与对应测试。
+```
+
+---
+
+### 17. 视角三角测量（Triangulation）
+
+**用途**：减少单一证据的误判；提升结论可靠性。
+
+**落地动作**：
+
+- 同一结论至少两种证据：单测/性质测试 + 日志/指标；或差分测试 + fuzz
+
+**Python工具**：`pytest`/`hypothesis` + metrics/logging；差分对照
+
+**提示词**：
+
+```text
+对关键行为给出至少两种独立验证方式，并说明各自盲区与如何互补。
+```
+
+---
+
+### 18. 机制解释（Mechanistic explanation）
+
+**用途**：把"能跑"变成"可解释可维护"；降低未来修改风险。
+
+**落地动作**：
+
+- 要求输出数据流：输入 → 中间状态 → 输出
+- 对中间状态写不变式/断言；把解释与代码结构对齐
+
+**Python工具**：`assert`、类型收窄、分层函数、docstring
+
+**提示词**：
+
+```text
+给出机制解释：数据在系统中如何流动；列出每个中间状态的不变式，并在代码中用断言或类型保证。
+```
+
+---
+
+### 19. 错误认识论（Error epistemology）
+
+**用途**：系统化"我们会如何错"，比事后补洞更省。
+
+**落地动作**：
+
+- 先做失败模式清单（空值/乱序/重复/并发/权限/超时/编码/浮点等）
+- 每类至少一个测试；明确错误语义（raise / error object / log+metric）
+
+**Python工具**：`pytest` 参数化 + `hypothesis`；统一 error 模型
+
+**提示词**：
+
+```text
+生成失败模式清单并按风险排序；为 Top N 写测试；统一错误模型并给出示例响应/异常层级。
+```
+
+---
+
+### 20. 实验哲学（x-phi）
+
+**用途**：交互与默认策略别靠直觉，用数据决定。
+
+**落地动作**：
+
+- 把争议点改成可测实验（A/B 默认值、错误文案、重试策略）
+- 指标：误用率、重试率、成功率、工单率、完成时间
+
+**Python工具**：埋点/日志、简单 A/B 分组、配置开关
+
+**提示词**：
+
+```text
+把该设计争议转成实验：分组、指标、样本、持续时间、判定阈值；给出埋点字段与分析方法。
+```
+
+---
+
+### 21. 计算哲学（Computational philosophy）
+
+**用途**：复杂状态与规则用"可运行模型/仿真/搜索"代替纯讨论。
+
+**落地动作**：
+
+- reference 实现（慢但清晰）作为 oracle
+- optimized 实现（快/工程化）用差分测试锁死行为
+- 用仿真/生成器自动探索边界
+
+**Python工具**：`hypothesis`、差分测试、状态机测试（Hypothesis stateful）
+
+**提示词**：
+
+```text
+先写 reference（清晰）+ optimized（高效）；写差分测试与状态机/性质测试自动找反例并修复。
+```
+
+---
+
+### 22. 自然化认识论（Naturalized epistemology）
+
+**用途**：承认人类/模型都有系统性偏误，用流程与工具把偏误外包给检查器。
+
+**落地动作**：
+
+- 默认自动化：lint+format+类型检查+测试
+- 高风险路径：必须性质测试/模糊测试/运行时校验
+- 结论至少双证据（测试+指标）
+
+**Python工具**：`ruff`/`black`/`pyright`/`pytest`/`hypothesis`/`pydantic`
+
+**提示词**：
+
+```text
+列出该任务最常见的误判点，并为每个误判点给一个自动化防线（检查器/测试/断言/埋点）。
+```
+
+---
+
+### 23. 贝叶斯认识论（Bayesian epistemology）
+
+**用途**：在多个方案/原因间理性分配注意力与试错预算。
+
+**落地动作**：
+
+- 先验 → 实验 → 后验 → 下一步；把排查变成序列决策问题
+
+**Python工具**：同 12/13；记录表
+
+**提示词**：
+
+```text
+用贝叶斯式流程组织排查：先验排序、信息增益最高的实验、更新后的行动计划。
+```
+
+---
+
+## 附录
+
+### 通用"性质测试"提示（可复用）
+
+| 性质 | 说明 |
+|:---|:---|
+| 非负性/有界性 | 结果不越界 |
+| 幂等性 | `f(f(x)) == f(x)` |
+| 单调性 | 输入增大输出不违反预期 |
+| 守恒性 | 长度/集合元素/总和按规则变化 |
+| 互逆性 | `decode(encode(x)) == x`（或近似） |
+| 稳定性 | 排序/去重等操作满足稳定条件 |
+| 交换/结合 | 满足代数性质的操作应通过 |
+
+### 建议的项目骨架（最小）
+
+```text
+src/           # 纯逻辑与 I/O 分离
+tests/         # 示例+性质+差分
+pyproject.toml # ruff/pytest/pyright
+README.md      # 概念表/错误语义/验收指标
+```
+
+---
+
+## 使用指南
+
+| 场景 | 推荐方法组合 |
+|:---|:---|
+| 需求不清 | 1（现象学）+ 8（诠释学）+ 15（概念工程） |
+| 质量不稳 | 3（可证伪）+ 4（形式化）+ 19（错误认识论） |
+| 排错提效 | 12（溯因）+ 13/23（贝叶斯更新）+ 17（三角测量） |
+| 复杂系统 | 7（系统论）+ 21（计算哲学）+ 14（反思平衡） |
+| 交互默认争议 | 20（x-phi）+ 6（实用主义指标） |
@@ -0,0 +1,107 @@
+### 现象学还原（悬置假设）用于 vibe coding
+
+**核心目的**
+把“我以为需求是这样”从对话里剥离出去，只留下可观察、可复现、可检验的事实与体验结构，从而让模型在更少臆测的前提下产出可用代码。
+
+---
+
+## 1) 方法要点（在工程语境下怎么理解）
+
+* **悬置（epoché）**：暂时不采纳任何“原因解释/业务推断/最佳实践偏好”。
+  只记录：发生了什么、期望是什么、约束是什么。
+
+* **还原（reduction）**：把问题还原到“给定输入→经过过程→得到输出”的最小结构。
+  先不谈架构、模式、技术栈优雅与否。
+
+* **意向性（intentionality）**：明确“这个功能是为谁、在什么情境下、要达成什么体验”。
+  不是“做个登录”，而是“用户在弱网下也能在 2 秒内完成登录并得到明确反馈”。
+
+---
+
+## 2) 适用场景
+
+* 需求描述充满抽象词：快、稳定、像某某一样、智能、顺滑。
+* 模型开始“自带设定”：自己补产品逻辑、乱选框架、擅自加复杂度。
+* Bug 复现困难：偶发、环境相关、输入边界不清。
+
+---
+
+## 3) 操作流程（可直接照做）
+
+### A. 先“清空解释”，只保留现象
+
+用四件套描述：
+
+1. **现象**：实际发生的结果（含报错/截图/日志片段）。
+2. **意图**：我想要的结果（可观察标准）。
+3. **情境**：环境与前置条件（版本、平台、网络、权限、数据规模）。
+4. **边界**：哪些不需要做/不要假设（不改接口、不引入新依赖、不改数据库结构等）。
+
+### B. 产出“最小可复现体”（MRE）
+
+* 最小输入样例（最短 JSON/最小表/最小请求）
+* 最小代码片段（去掉无关模块）
+* 明确复现步骤（1、2、3）
+* 预期 vs 实际（对照表）
+
+### C. 把“抽象词”降维成可测指标
+
+* “快”→ P95 延迟 < X、冷启动 < Y、吞吐 >= Z
+* “稳定”→ 错误率 < 0.1%、重试策略、熔断条件
+* “好用”→ 交互反馈、错误文案、可撤销/可恢复
+
+---
+
+## 4) 给模型的提示词模板（可直接复制）
+
+**模板 1：还原问题（禁止脑补）**
+
+```
+请先做“现象学还原”：不要推测原因、不要引入额外功能。
+只根据我给的信息，输出：
+1) 现象（可观察事实）
+2) 意图（我想要的可观察结果）
+3) 情境（环境/约束）
+4) 未确定项（必须问清或需要我补的最小信息）
+5) 最小可复现步骤（MRE）
+然后再给出最小修复方案与对应测试。
+```
+
+**模板 2：抽象需求变可测规格**
+
+```
+把下面需求做“悬置假设”处理：删掉所有抽象词，转成可验证规格：
+- 明确输入/输出
+- 明确成功/失败判定
+- 明确性能/资源指标（如需要）
+- 明确不做什么
+最后给出验收用例列表。
+需求：<粘贴>
+```
+
+---
+
+## 5) 在 vibe coding 的具体落地方式（习惯化）
+
+* **每次开工先写“现象卡片”**（2 分钟）：现象/意图/情境/边界。
+* **先让模型复述**：要求它只复述事实与缺口，不许给方案。
+* **再进入生成**：方案必须绑定到“可观察验收”与“可证伪测试”。
+
+---
+
+## 6) 常见陷阱与对策
+
+* **陷阱：把解释当事实**（“可能是缓存导致”）
+  对策：把“可能”移到“假设列表”，每条假设配验证步骤。
+
+* **陷阱：需求用形容词堆叠**
+  对策：强制转成指标与用例；不满足“可测”不让写代码。
+
+* **陷阱：模型自选技术栈**
+  对策：边界里写死：语言/框架/依赖/接口不可变。
+
+---
+
+## 7) 一句话口诀（便于放进工具箱卡片）
+
+**先悬置解释，再固定现象；先写验收标准，再让模型写实现。**
@@ -0,0 +1,28 @@
+# 辩证法在 Vibe Coding 里的用法：正反合
+
+把辩证法的“正反合”用到 Vibe Coding：我把每次写代码都当一轮“三段论”。
+
+## 正：当前状态（先跑通）
+
+- 让模型按直觉快速给出“最顺的实现”
+- 目标只有一个：尽快跑通主路径
+
+## 反：审计与调优（再打脸）
+
+- 立刻站在“挑刺者”视角反驳它
+- 列出失败模式、边界条件、性能与安全隐患
+- 用测试、类型、lint、基准把反驳落地
+
+## 合：根据审核修正（再收敛）
+
+- 把速度与约束合起来
+- 重构接口、收敛依赖、补齐测试与文档
+- 形成下一轮更稳定的起点
+
+## 实践口诀
+
+先顺写 → 再打脸 → 再收敛
+
+## 一句话总结
+
+Vibe 负责生成可能性，正反合负责把可能性变成工程确定性。