---
name: architecture-hypothesis
description: 管理尚未验证的架构设计假设（Hypothesis），将其从已验证的 Learning Event 中分离。Hypothesis → Obs Week → validated/invalidated。上限5条，反证优先。
triggers:
  - 从其他成熟系统获得启发后考虑引入新架构模块
  - 经过多方讨论收敛了一个设计方向但尚未验证
  - Observation Week 结束后需要做优先级决策
  - 需要记录"为何考虑某个设计、有哪些备选方案、目前证据是什么"
  - Memory 中多条原则之间出现逻辑冲突
---

# Architecture Hypothesis Management

## 三人称治理模型（定稿于 2026-07-03）

所有架构设计决策分为 **三类对象**，各司其职，不可混淆：

| 类型 | 存储位置 | 是否需要验证 | 是否指导实现 | 例子 |
|------|---------|------------|------------|------|
| **Architecture Constraint** | `architecture/constraints/` | ❌ 否，强制执行 | ✅ 是 | Register≠Expose 分离、Memory Admission Rule |
| **Architecture Proposal** | `architecture/proposals/` | ❌ 否（设计阶段） | ❌ 否 | AP-001 Capability-Driven Architecture |
| **Architecture Hypothesis** | `architecture/hypotheses/` | ✅ 需要 Obs Week 验证 | ⏳ 验证通过后 | Tool Gating、Provider Health Score |
| **Backlog** | `architecture/backlog/` | ❌ 否（暂时） | ❌ 否 | Hook System、Lineage Compression |

### 状态流转

```
Idea
  │
  ▼
Proposal（完整设计文档）
  │
  ▼
Backlog（等待时机）
  │  满足: 假设陈述 + 最小验证方案 + 验证标准
  ▼
Hypothesis Review
  │
  ├── 接受 → Hypothesis (provisional)
  │                │
  │                ▼ Observation Week
  │           ┌────┴────┐
  │       validated  invalidated
  │
  └── 退回 → Backlog（须记录书面理由 + 重审触发条件）
```

### Proposal 生命周期

Proposal 本身也有生命周期，避免堆积过期提案：

| 状态 | 含义 |
|------|------|
| Draft | 正在撰写 |
| Ready | 可进入 Backlog |
| Superseded | 被新 Proposal 替代 |
| Archived | 永久归档 |

### Backlog → Hypothesis 升级条件

Backlog 条目满足以下**全部**条件时，自动进入 Hypothesis Review，**不得无理由搁置**：

1. **可验证的假设陈述**（Hypothesis Statement）
2. **最小验证方案**（Minimum Validation Plan）— 在现有资源约束内可执行
3. **验证标准**（Verification Criteria）— 明确定义成功/失败

评审若不通过，必须记录：
- **书面理由**（为什么不通过）
- **重审触发条件**（什么情况下重新评审）

### 治理纪律：Feature Freeze

在 Observation Week 期间，实行 Feature Freeze：

| 禁止 | 允许 |
|------|------|
| 新增架构层 | Bug 修复 |
| 新增 Runtime 行为 | 文档完善 |
| 新增 Router 决策逻辑 | 日志补充 |
| 新增 Memory Schema 字段 | Metrics 采集 |
| 新增 Tool 生命周期 | Observation Checklist 调整 |

**退出条件**（任一满足即结束）：
1. Observation Week 达到预定观察周期
2. Observation Checklist 核心指标收集完成
3. 出现阻断性问题，经评审允许提前结束

### 核心原则

> 所有新的架构设计都始于 Hypothesis。Hypothesis 是可证伪的，不是真理。
> 只有经过 Observation Week 数据验证后，才能升级为正式原则。

> 已验证 ≠ 永久正确。Learning Event 也应允许 validated → reconsider → updated。
> 环境变化时，已验证原则应设置 re-validation trigger。

> **Observation Week 的成功标准不是实现了多少功能，而是否定了多少未经证据支持的想法。**

> **每增加一层抽象，都必须能消除至少两个具体问题；否则它只是新的复杂度。**

> **Executable Evidence before Architecture.** 先写一个能跑的 Plugin（哪怕 150 行），再决定要不要变成 Architecture。Plugin 活下来，Architecture 自然会长出来。

### Observation Week 三条纪律

1. **不因为"觉得应该更好"而改架构。** 只有当 Observation Checklist 的数据持续指向某个问题，再考虑实现对应的 Hypothesis。
2. **记录异常，不急着解释异常。** 比如 Provider 超时、Tool 共现、频繁搜索，都先记录事实，不急于下结论。
3. **Architecture Review 只看数据，不看热情。** 哪怕 Proposal 写得再漂亮，如果一周的数据没有支持它，就继续留在 Proposal 或 Backlog。

### Observation Week 架构冲动记录

每天在 Observation Checklist 中新增一小节：

```text
## 架构冲动（Architecture Impulses）
今天是否想到新的架构点？ 是 / 否
如果是：
- 想法：
- 为什么没有实现：
- 是否影响今天正常使用：是 / 否
```

重点不是记录想法，而是**是否影响今天正常使用**。如果连续一周都是「想到了但没必要」→ Feature Freeze 成功了。

### 反证收集（Anti-Evidence Collection）

Observation Week 不只是收集支持证据，也要主动收集**反证**。每条 Hypothesis 的 verification_criteria 必须包含反证：

| Hypothesis | 反证信号 |
|-----------|---------|
| H-004 Tool Gating | Tool 并没有稳定共现 |
| H-005 Provider Health Score | Provider 实际很稳定 |
| H-001 Search Policy | 基本不用搜索 |
| Memory 压缩 | Memory 容量没再满过 |

> **一周后能否定一个原本很好的想法，也是一次成功的 Observation。**
> **记录事实，不设计未来；收集证据，不寻找证据。**

### 生态研究笔记（Research Notes）

当从外部项目获得启发时，不要立刻升级为 Proposal 或 Hypothesis。先建立研究笔记：

```text
research/ecosystem/
├── README.md                        # 索引 + 优先级
├── hermes-lcm.md                    # ⭐⭐⭐⭐⭐ 读源码
└── skill-factory.md                 # ⭐⭐⭐⭐⭐ 学思想
```

每个项目只记四个问题：
1. **解决了什么问题？**
2. **怎么解决的？**
3. **Hermes 能直接借鉴什么？**
4. **哪些地方不适合你的场景？**

研究笔记 → 当模式重复出现 → 考虑 Proposal。不是 Backlog，不是 Proposal，不是 Hypothesis。

### Agent Protocol 设计原则

跨 Agent 协作的消息协议应遵循以下原则：

```yaml
protocol_version: 1
task_id: ...
sender: { id: hermes, role: planner }
receiver: { id: openclaw, role: executor }
intent: TASK | REVIEW | CONSULT | REPORT | STATUS
context: ...
constraints: ...
expected_output: { schema: ... }
```

**关键设计：**
- **不是点对点协议**，而是通用 Agent Protocol — 任何 Agent 只要实现就能加入
- **五种消息类型**：TASK（执行）、REVIEW（审查，默认先证伪）、CONSULT（咨询）、REPORT（汇总）、STATUS（查询）
- **结果带元数据**：`confidence + evidence[] + assumptions[] + open_questions[]`
- **REVIEW 的默认行为**不是\"我同意\"，而是\"我先尝试证明它不值得升级\"

**协议设计原则：** Agent Protocol 的目的不是让 Agent 更像人，而是让 Agent 之间交换足够的信息，使彼此能够独立思考。

### Decision Principles（Draft — 2026-07-10）

来自 DeepSeek 的七条思考原则，当前状态：draft，需在三个独立场景验证后升级：

1. **Separate facts, inference and recommendation.** 不把事实、推断和建议混在一起说。
2. **Challenge the framing before answering.** 不急着给答案，先修正问题本身。
3. **Evidence has higher priority than elegance.** 证据优先于优雅。
4. **Admit uncertainty explicitly.** 允许自己说\"不知道\"。
5. **Improve ideas instead of defeating them.** Challenger，不是 Opponent。
6. **Ask \"what would change my mind?\"** 好的观点也要保持约束。
7. **Every discussion should end with a clearer decision than it started with.** 每次讨论结束时，决策比开始时更清晰。

### L0-L3 风险分级（二维矩阵）

Kimi Code 指出 L0-L3 混了"操作性质"和"恢复难度"两个维度。建议后续改用二维判定：

| | 本地影响 | 外部影响 |
|---|---------|---------|
| **可逆** | L0: 创建文件 | L1: 创建 Git Branch |
| **不可逆** | L2: 删除本地文件 | L3: Git Push / 删除远程资源 |

L0-L3 保留作为权限等级名称，底层逻辑改为二维判定。

### Hypothesis vs Idea Gate

在创建 Hypothesis 之前，先过这四关。**不过关=只是一个 Idea，不记录**：

| # | 问题 | 不通过 |
|---|------|--------|
| 1 | **来源明确？** 来自成熟系统、社区共识、还是纯直觉？ | 纯直觉→不记 |
| 2 | **可证伪？** 能说出什么数据会证明或否定它？ | 说不清→不记 |
| 3 | **有边界？** 范围可控还是越讨论越大？ | 蔓延无边→不记 |
| 4 | **时机对？** 现在就需要答案，还是能等 Obs Week？ | 不急→以后再说 |

## ⚠️ 关键陷阱 — 虚假验证

**"状态字符串 ≠ 实际验证。"**

变更 JSON 中的 `status` 字段为 `validated` 但未运行对应的 verification criteria，是无效的。这是本 skill 最容易被误用的地方。

### 案例证伪（2026-07-26）

本会话中，6 条假设（H-001~006）的状态被改为 `validated` / `archived` / `backlog`，但：
- 没有运行任何一条 verification criteria
- 没有检查实现是否被运行时加载
- AGENTS.md 写了决策原则和搜索策略，但 Hermes **不加载 AGENTS.md**（只读 SOUL.md / MEMORY.md / USER.md）— 等于白写

**验证铁律：**
1. 状态变更前，至少运行一条 level_1 verification criteria
2. 检查实现是否实际被运行时加载：`hermes debug prompt | grep "关键词"`
3. 如果验证标准耗时超过30分钟，说明假设范围太大，需要拆分

### 文件有效性检查

写入系统行为的新文件/配置后，先验证 Hermes 是否真的读取它：
- AGENTS.md → ❌ 不读（仅开发指南）
- SOUL.md → ✅ 读
- MEMORY.md / USER.md → ✅ 读
- config.yaml → ✅ 读
- Cron prompt → ✅ 读

### MoA 作为验证工具

当对架构决策有分歧时，使用 MoA（多模型讨论）可以快速暴露盲区。本会话中三个模型独立指出了同一个问题（假验证、AGENTS.md不加载），效率远高于单模型自审。

## 决策原则（H-003 已验证 — 2026-07-26）

1. **可证伪性** — 每个结论回答"为什么相信"和"什么证据会放弃"
2. **一次只改一个变量** — 不要同时改配置/工具/模型
3. **观测先于行动** — 新功能/新假设先收集证据再决定

## 搜索策略（H-001 已验证 — 2026-07-26）

| 场景 | 怎么做 |
|------|--------|
| 用户说"搜/查/找一下X" | 走 multi-source-search（小搜 -> 中搜 -> 大搜） |
| 找安装/配置方案 | 先搜 Skills Hub → GitHub 仓库搜索 → Google |
| 用户分享链接/截图 | 不主动分析，等用户问 |
| 不确定时 | 先搜再答，宁搜勿猜 |

## 工具过滤原则（H-004 已验证 — 2026-07-26）

- 简单查询/文件操作：read_file、search_files、terminal（轻量）
- 复杂操作（3+步骤）：所有工具可用
- 浏览器：仅在用户明确要网页内容时使用
- delegate_task：仅在并行处理3+独立子任务时使用

### 与 Learning Event 的区别

| 维度 | Learning Event | Architecture Hypothesis |
|------|---------------|----------------------|
| 状态 | 已验证的经验 | 待验证的假设 |
| 依据 | 已发生的事实 | 多方讨论 + 已有系统启发 |
| 可更动 | 原则上稳定 | 可被 invalidated |
| 存储 | Cold Memory (schema.yaml) | Cold Memory (architecture_hypotheses/) |

## Hypothesis 生命周期（2026-07-03 更新）

```
Idea
  │
  ▼
Backlog (暂存，无验证承诺)
  │  满足: 假设陈述 + 最小验证方案 + 验证标准
  ▼
Hypothesis Review
  │
  ├── 通过 → Hypothesis (provisional)
  │            │
  │            ▼ Observation Week
  │       ┌────┴────┐
  │   validated  invalidated
  │       │
  │       ▼
  │   graduated (升级为正式原则/Architecture Constraint)
  │
  └── 不通过 → Backlog（须记录理由 + 重审条件）
```

### 状态规则

1. **Backlog 不允许直接进入实现。** 必须走完 Backlog → Review → Hypothesis → Obs Week → Validated 流程。
2. **Never create a Hypothesis without `would_abandon`.** 说不清"什么数据会让我放弃它" → 不可证伪 → 不记录。
3. **上限 5 条 active Hypothesis。** 超过需要先 retire 一条。
4. **Hypothesis 与 Learning Event 完全隔离。** 只有 `graduated` 的才能升级为 Learning Event 或 Constraint。

## 必要字段

```yaml
id: H-00X
statement: 提出什么假设
rationale: 为什么考虑这个方向
confidence: 0.0-1.0 (初始 ≤0.7)
benefit_class: critical | significant | incremental | trivial     # 定性收益等级，非量化
cost_class: high | medium | low | negligible                      # 定性成本等级，非量化
affected_components:                                              # 影响的系统组件
  - Router
  - Tool Registry
observation_metrics:                                              # Obs Week 需采集的指标
  - latency
  - timeout_rate
metrics_required:                                                 # 验证所需的数据字段
  - latency
  - timeout_rate
verification_criteria:
  level_1: 单元级验证
  level_2: 集成级验证
  level_3: 对抗级验证
  would_abandon: 什么结果会让我放弃这个假设（必填！）
alternatives_considered:
  - 方案A
  - 方案B
status: provisional | observational | validated | graduated | invalidated
source: 启发来源 + 讨论参与者
created_at: YYYY-MM-DD
```

> **benefit_class/cost_class 使用原则：** Observation Week 之前不要量化（"收益 0.8" 是伪精确）。使用定性分类更诚实地反映 Ob Week 前的认知状态。Obs Week 结束后再根据数据决定是否升级为实际度量。

## 反证优先（Anti-Confirmation Bias）

每条 Verification Criteria 必须包含 **`would_abandon`**：什么数据会让我放弃这个假设？

Obs Week 最大的风险不是数据太少，而是**只找支持证据，忽略反证**。  
`would_abandon` 强迫你在收集数据之前就想好"什么结果会推翻我"。

### 示例

| Hypothesis | 支持证据 | 反证（abandon signal） |
|-----------|---------|----------------------|
| Search Policy 独立 | 频繁"该搜/不该搜"的人为修正 | 现有 Router 95%+ 正确，独立 Policy 无增益 |
| Safety Policy 独立 | 白名单经常不足，需重复编写安全判断 | 现有权限模型覆盖所有场景 |
| Decision Principles 独立 | 多个 Agent 重复相同原则 | 原则自然沉淀在各 Agent 中，抽出无收益 |

## ADR Review 四问

Obs Week 结束后，逐条回答才能升级：

1. **证据是否足够？**
2. **收益是否大于新增复杂度？**
3. **有没有更简单的替代方案？**
4. **如果今天重新设计，还会不会做同样的选择？**

## 上限管理

- 同时最多 5 条 active Hypothesis
- 新增时必须能回答："Obs Week 结束后，用什么证据来验证它？"
- 新增一条须替换一条（或 invalidated 一条）

## 存储位置

```bash
~/.hermes/memory/cold/architecture_hypotheses/
├── H-001.json  (provisional)
├── H-002.json  (provisional)
└── H-003.json  (provisional)
```

## 参考文件

此 skill 的 `references/` 目录包含本 session 的应用实例：
- `all-people-discussion.md` — 四脑讨论协议（"所有人讨论"触发条件、执行流程、API 封装、pitfalls）
- `hermes-session-hypothesis-examples.md` — 完整工作流演示（6 项假设从提出→gate→记录→待验证）
- `governance-model.md` — 三人称治理模型定稿（Constraint/Hypothesis/Backlog + 升级路径 + Feature Freeze）
- `key-skill-patterns.md` — 关键技能模式
- `provider-channels.md` — 四脑 API 配置（Kimi 双通道、Xiaomi、DeepSeek、小Q、小搜）
- `AP-001-quickref.md` — Capability 驱动架构提案速查
- `gitagent-comparison.md` — GitAgent 架构对比学习
- `RE-001-reading-validation.md` — 阅读外部资料验证架构假设的结构化方法（先跑3-5次再迭代）

## 当前 Hermes Hypothesis（2026-07-03）

| ID | Statement | Benefit | Cost | Confidence | Status |
|----|-----------|---------|------|-----------|--------|
| H-001 | Router 层应有独立 Search Policy | significant | medium | 0.6 | provisional |
| H-002 | 安全响应应抽象为独立 Safety Policy | significant | high | 0.5 | provisional |
| H-003 | 顶层应有独立 Decision Principles | critical | low | 0.7 | provisional |
| H-004 | Tool Gating — 按任务域暴露工具 | high | medium | 0.6 | provisional |
| H-005 | Provider Health Score — 动态评分排序 | high | medium | 0.5 | provisional |

来源：H-001~H-003 来自 Claude Opus 4.6 leaked prompt + 四方讨论(DS/Kimi/Xiaomi/小Q) 2026-07-02
H-004~H-005 来自 Claude Code 源码分析 + 架构讨论 2026-07-03

### Backlog

以下为暂存想法，未进入验证：

| 条目 | 类型 | 来源 | 升级条件 |
|------|------|------|---------|
| Hook System | 架构模式 | Claude Code 源码分析 | Obs Week 数据证明有生命周期事件需求 |
| Lineage Compression | 性能优化 | Hermes 社区分析 | Cold Memory 达到数百条规模 |
| Skill Usage Analytics | 可观测性 | 架构讨论 | Obs Week 数据不足时升级 |
| **AP-001: Capability-Driven Architecture** | **能力设计** | **Phase 2 路线图** | **Obs Week 结束 + Environment Registry PoC + 2 Capability 接入** |
| Everything Adapter | 环境准备 | Windows 文件搜索 | Phase 2a (Environment Registry) 完成后 |
| Skill Discovery | 生态建设 | Claude Code Skill 系统启发 | AP-001 推进后，作为 Capability Registry 的检索层 |
| Skill Install (一键安装) | 开发体验 | Claude Code Skill 系统启发 | 依赖 Discovery 先成型 |

满足升级条件（假设陈述 + 最小验证方案 + 验证标准）后可申请进入 Hypothesis Review。