# AGENTS.md 治理体系版本迭代谱系与全史

本项目中的工作区治理文件 [`AGENTS.md`](../../AGENTS.md) 经历了从“简单的自然语言技能映射”到“工业级自主多 Agent 协同与拓扑编排体系”的完整演化历程。

本目录完整封存了该治理文件自诞生以来的**全部 9 个历史里程碑版本**，方便人类随时查阅治理协议的演进脉络与设计决策。

---

## 1. 版本迭代总览表 (Evolution Matrix)

| 版本代号 | Git Commit | 提交日期 | 规模 | 核心演进主题 | 历史文件链接 |
| :---: | :---: | :---: | :---: | :--- | :--- |
| **V1** | `ca891c7` | 2026-10-11 | 43 行 | **启蒙期**：初始建立技能自然语言意图映射表 | [`v1-ca891c7-初始自然语言意图映射表.md`](./v1-ca891c7-初始自然语言意图映射表.md) |
| **V2** | `7b4dc4c` | 2026-10-11 | 36 行 | **协议化**：升级为“泛化意图识别”与 Skill-First 模式，精炼核心路由 | [`v2-7b4dc4c-升级为语义泛化与Skill-First.md`](./v2-7b4dc4c-升级为语义泛化与Skill-First.md) |
| **V3** | `426a6ec` | 2026-10-11 | 47 行 | **留痕立法**：确立“实体资产留痕优先原则”，杜绝空谈，强制落盘研报/Spec/ADR | [`v3-426a6ec-实体资产留痕优先原则.md`](./v3-426a6ec-实体资产留痕优先原则.md) |
| **V4** | `086b3f8` | 2026-10-11 | 81 行 | **自治闭环**：确立“自主执行闭环协议 (Autonomous Loop)”，免打扰自驱动自审 | [`v4-086b3f8-配置自主执行闭环协议Loop.md`](./v4-086b3f8-配置自主执行闭环协议Loop.md) |
| **V5** | `51a7df5` | 2026-10-11 | 85 行 | **事实求真**：确立“实证探路优先原则 (Ground-Truth-First)”，严禁凭空臆想 | [`v5-51a7df5-Research实证调研入法.md`](./v5-51a7df5-Research实证调研入法.md) |
| **V6** | `eb920aa` | 2026-10-11 | 116 行 | **精装修**：固化“方案先决 (Plan-First)”，梳理核心资产显式拓扑结构 | [`v6-eb920aa-精装修规范体系与核心资产拓扑.md`](./v6-eb920aa-精装修规范体系与核心资产拓扑.md) |
| **V7** | `97d49a4` | 2026-10-11 | 116 行 | **资产出土**：彻底废除以点（`.`）开头的隐藏目录，工单全面迁移至 `docs/issues/` | [`v7-97d49a4-废除隐藏目录工单出土显式化.md`](./v7-97d49a4-废除隐藏目录工单出土显式化.md) |
| **V8** | `6f37dc6` | 2026-10-11 | 132 行 | **编排引擎**：引入 Orca 调度引擎（Coordinator、Task DAG、串并行判定、Worktree 放置矩阵） | [`v8-6f37dc6-Orca多Agent调度与Worktree放置矩阵.md`](./v8-6f37dc6-Orca多Agent调度与Worktree放置矩阵.md) |
| **V9** | `e0594fe` | 2026-10-11 | 136 行 | **通用升华 (最新)**：注入任务轻重分级准则 (Tier 1/2)、人类最高中断权与 Worktree 修剪契约 | [`v9-e0594fe-任务分级人类最高中断权与Worktree修剪.md`](./v9-e0594fe-任务分级人类最高中断权与Worktree修剪.md) |

---

## 2. 演化四大阶段深度复盘

```mermaid
flowchart LR
    Stage1["第 1 阶段：意图识别 (V1-V2)<br>听懂人话，调动对应技能"] --> Stage2["第 2 阶段：资产实体化 (V3-V5)<br>严禁聊天空谈，实证+留痕"]
    Stage2 --> Stage3["第 3 阶段：自驱动闭环 (V6-V7)<br>方案先决，闭环自审，废除隐藏路径"]
    Stage3 --> Stage4["第 4 阶段：多Agent编排 (V8-V9)<br>Orca调度、串并行DAG、Worktree隔离与人类最高中断权"]
```

### 阶段一：意图感知与技能调动 (V1 ~ V2)
- **解决痛点**：早期的 Agent 容易陷入“泛泛而谈”的代码生成，无法精准使用生态中已有的 42 个专业技能；
- **核心飞跃**：建立意图路由映射网络，并升级为基于研发阶段的泛化语义识别， Agent 进场第一反应变为“检索最匹配的 Skill”。

### 阶段二：实体资产留痕与实证探路 (V3 ~ V5)
- **解决痛点**：对话结束或会话窗口被截断后，设计决策、背景调研完全丢失；Agent 容易凭大模型幻觉编造考纲或技术参数；
- **核心飞跃**：
  1. 确立 `Paper-Trail-First` 铁律：对话必须落地为 `RESEARCH`、`ADR`、`SPEC`、`TICKETS`、`RETRO` 等实体文件；
  2. 确立 `Ground-Truth-First` 铁律：外部事实必须先用 `research` 深入一手信源查证，写成研报后再出方案。

### 阶段三：自治执行闭环与资产全景可视 (V6 ~ V7)
- **解决痛点**：每写一个文件都停下询问人类，交互极其繁琐；且部分工单落盘在隐藏目录（如 `.scratch/`）中，用户在操作系统 Finder 文件树中肉眼看不到；
- **核心飞跃**：
  1. 确立 `Autonomous Loop`：用户审阅方案发出“同意/执行”后，进入自闭环流水线，测试与审查全部绿灯后才退出；
  2. 彻底废除任何点号（`.`）开头的隐藏目录，所有研发生命周期资产 100% 直观可见。

### 阶段四：Orca 调度引擎与高度泛化协同 (V8 ~ V9)
- **解决痛点**：单线程串行处理在多模块、多学科交付时耗时长；缺乏工作树物理隔离机制；缺乏执行途中突发插话的中断控制；
- **核心飞跃**：
  1. 引入 Orca 编排引擎：主 Agent 升维为 Coordinator，编排 Task DAG（串行阻塞依赖与并行波次）；
  2. 确立 Worktree 放置策略矩阵与完工修剪契约；
  3. 确立任务轻重分级准则（Tier 1 微调极速闭环，Tier 2 启动编排）；
  4. 赋予人类最高中断权（User Interruption Override），实现绝对的人机安全协同。

---

## 3. 当前主文件位置

最新的生效工作区宪法文件位于项目根目录：
- [`AGENTS.md`](../../AGENTS.md)（与全局规则 `~/.gemini/config/GEMINI.md` 同步保持一致）