本文档定义所有改进计划文档的统一组织方式、共同约束、治理规则和执行标准，是 docs/ 目录下所有专项改进计划的基础框架。
docs/
├── general.md ← 本文档：统一治理规范、共同约束
├── README.md ← 总索引与全景执行计划
├── integration.md ← 集成测试：端到端验证框架
├── [模块改进计划文档]
│ ├── contract.md ← Contract 边界归并
│ ├── config.md ← Config 模块拆分与 SecretRef
│ ├── vault.md ← Vault 安全加固与凭据迁移
│ ├── mail.md ← Mail 模块（已废止；见 website-mail.md）
│ ├── notification.md ← Notification 多渠道系统
│ ├── website-auth.md ← Website Better Auth 会话接入
│ ├── website-mail.md ← 产品邮件投递（website）
│ ├── orbit.md ← Orbit 依赖重构（项目引用 → API 依赖）
│ ├── trunk-push.md ← Trunk 直推形态与 Monorepo 写入序列化
│ └── libra.md ← Libra 协作、Agent 变更证据与主干把关
└── [文档范围外]
└── protocol.md
补充登记（2026-09-06）：libra.md 为 Agent 变更证据与 Libra 协作专项需求，
阶段 0–5 分别为契约、可信接收、任务与修订、主干把关、团队历史／运维、可选接入。
它复用 trunk-push.md 的根写入路径，验收场景在 integration.md 登记；执行依赖与优先级见 README 的 5b 条目。
当前为用户明确要求的文档编写与 review，不执行本文「执行时的共同需求」中的代码实现／版本发布步骤。
| 文档 | 角色 | 职责 |
|---|---|---|
| general.md | 基础框架 | 定义所有文档的共同规则、约束、治理标准 |
| README.md | 总体协调 | 整体执行计划、依赖关系、优先级、里程碑 |
| integration.md | 验证框架 | 端到端测试场景、Docker 环境、验收标准 |
| contract.md | 边界归并 | API/Git/Vault/Policy 模块路径和边界约束 |
| config.md / vault.md / mail.md / notification.md | 专项规划 | 各模块的现状分析、阶段规划、实施细节 |
| orbit.md | 依赖治理 | 把对 orbit 实现 crate 的 path 引用重构为只依赖 orbit-api 契约 |
| trunk-push.md | 写入路径与部署形态 | Monorepo 根树写入的序列化；push_policy 形态开关（review / trunk）；产品规则以 ../monorepo.md 为准 |
| libra.md | Agent 变更证据 | Libra 摄取、任务／CL 修订、证据授权、精确版本验证与 landing；共用 trunk-push 写入边界 |
每个改进计划文档都应遵循以下统一结构，确保信息完整性和查询可索引性：
# 模块名 实现方案分析
本文档记录 `mega2` 中 [模块] 的 [主题描述]。
> **关键依赖**：与其他文档的强绑定说明和集成测试指引要求：
- 一句话总结文档主题
- 明确列出与其他文档的依赖关系
- 指明相关的集成测试场景
## 事实校准（日期）
> 本文档中的代码引用已对照当前 `src/` 重新核对...
> 需特别注意以下与早期版本不一致的事实：
1. **事实点 1**：[具体描述]
2. **事实点 2**：[具体描述]
3. **事实点 3**：[具体描述]要求：
- 更新日期必须是当前日期（格式：YYYY-MM-DD）
- 核实所有代码引用（文件路径、行号、函数名）
- 列出与文档原始版本的不符之处
- 标注修正后的正确信息
## 当前实现状态速览表
| 能力 / 组件 | 实现状态 | 关键事实与风险 |
|-----------|--------|-------------|
| 组件 A | 已实现 / 已激活 / 部分完成 / 仅草案 / 未实现 | [具体说明] |要求：
- 覆盖所有主要功能组件
- 实现状态必须从固定列表中选择（已实现、已激活、部分完成、仅草案、未实现）
- 关键事实字段必须包含代码位置或工程现状
## 硬约束与不可违反的原则
本文档中以下约束是硬边界，任何实现偏离都必须重新评审：
1. **约束 1**：[具体约束内容和理由]
2. **约束 2**：[具体约束内容和理由]要求：
- 每个约束必须明确说明"为什么不能违反"
- 约束应来自系统架构、安全需求或循环依赖
- 任何规划偏离都必须在评审时显式讨论
## 现状与目标对比
| 维度 | 当前状态 | 目标状态 | 实现难度 |
|-----|--------|--------|--------|
| 组件化 | 单文件 `common/config.rs` | 一级模块 `src/config/` | 中等 |要求：
- 清晰对比"现在是什么"和"要变成什么"
- 难度等级：简单 / 中等 / 复杂
- 帮助团队理解改进范围
## 迁移步骤（分阶段）
**阶段 0 — 名称与描述**
1. 具体步骤 1
2. 具体步骤 2
3. 具体步骤 3
> **验收标准**：
> - ✅ 条件 1
> - ✅ 条件 2要求：
- 每个阶段必须有清晰的步骤列表
- 验收标准必须是可测试的、具体的、量化的
- 不包含时间估计（天数、周数）
- 不包含人员分配或团队划分
## 前置依赖矩阵
本文档与其他文档的依赖关系如下：
| 本文档的工作 | 对其他文档的依赖 | 类型 | 关键同步点 |
|-----------|-------------|-----|---------|要求：
- 清晰列出本文档的各项工作依赖谁
- 依赖类型：前置 / 协同 / 后置 / 可选
- 必须标出"关键同步点"（可能相互阻塞的地方）
## 风险与约束
- **风险 1**：[风险描述]
- 影响：[影响范围]
- 缓解措施：[如何降低风险]
- **约束 1**：[约束说明]
- 理由：[为什么存在这个约束]
- 影响：[违反时的后果]要求：
- 风险和约束必须清晰分开
- 每个风险都必须列出"影响"和"缓解措施"
- 约束必须说明违反的后果
## 改进方案多维评估小结
| 维度 | 评估结论 |
|-----|--------|
| **合理性** | **高（9/10）**。[原因阐述] |
| **可行性** | **中高（7.5/10）**。[原因阐述] |
| **完整性** | **中（7/10）**。[原因阐述] |要求：
- 维度建议：合理性、可行性、完整性、安全性、功能正确性、可靠性、兼容性、可扩展性、合规性
- 每个维度的评分必须是数字（x/10）加文字说明
- 说明必须包含"当前不足"和"改进方向"
## 小结
简明概括本改进计划的核心内容和价值。
## 预期收益
- [收益点 1]
- [收益点 2]
- [收益点 3]要求：
- 小结用 3-5 句话总结全文核心
- 预期收益必须是可观测的、可验证的
文档中严格禁止以下内容：
-
❌ 时间估计
- 禁止：
工作量：M（约 3-5 天）、完成期：1 周 - 允许：
依赖 X 先完成、与 Y 协同
- 禁止：
-
❌ 人员分配或团队划分
- 禁止：
由 A 团队负责、需 5 人投入 - 允许：
config + vault 团队协同
- 禁止：
-
❌ 具体的发布日期或里程碑日期
- 禁止：
计划 Q3 2026 完成 - 允许：
在阶段 5 完成前完成
- 禁止：
-
❌ 假设或未验证的代码引用
- 禁止：
大概在 config.rs:300或可能的文件位置 - 允许：
config.rs:385（已核对）或当前代码版本未包含此功能
- 禁止：
-
❌ 个人观点或非共识观点
- 禁止：
我认为应该...、为了看起来更专业 - 允许：
基于分析，建议...、架构考量...
- 禁止：
-
❌ 孤立决策
- 禁止：无视其他文档的决策而自行定义架构
- 允许：
与 config.md 保持一致、遵循 vault.md 的约束
所有相互依赖的文档必须在两个文档中都明确声明这种关系：
示例：
- config.md 中应声明：
vault B 的 bootstrap 拆分必须在 config 3 前或同期完成 - vault.md 中应声明：
config 3 直接依赖本阶段的改造结果
检查清单：
- ✅ 文档 A 提及依赖文档 B
- ✅ 文档 B 也明确提及文档 A 的依赖
- ✅ 两个文档的表述语义一致（不能相互矛盾）
- ✅ 依赖箭头清晰（A → B 还是 B → A）
不允许的循环依赖：
- A 需要 B 完成，B 需要 A 完成 ❌
允许的模式：
- A 的某个阶段需要 B，B 的某个阶段需要 A ✅
- A 和 B 同期协同完成（LoadMode 框架） ✅
- A 是 B 的前置，B 是 C 的前置（串行） ✅
检查方法： 在 README.md 的依赖图中，确保没有闭环。如果发现循环，立即调整各文档的阶段划分。
日志脱敏工具、CLI LoadMode 框架 等共同前置，必须在所有依赖它们的文档中都明确声明：
本阶段依赖：
1. **脱敏工具**（来自 config.md 阶段 0b）— [用途说明]
2. **CLI LoadMode**（config + vault 协同）— [用途说明]如果多个文档涉及同一个架构层面的约束（如"Config → Storage(DB) → Vault"的循环），所有文档必须用完全相同的表述描述这个约束。
示例：
- config.md 说：
Config(synchronous) → Storage(DB + object storage) → VaultCore - vault.md 应该用同一个表述，而不是改成其他说法
启动任何阶段的代码实现之前，文档必须满足：
- ✅ 事实校准已完成（代码引用已核对）
- ✅ 前置依赖已明确列出
- ✅ 与其他文档的协同点已沟通
- ✅ 硬约束已识别并得到认可
- ✅ 集成测试场景已定义（如适用）
每个阶段完成后必须满足以下验收标准：
- ✅
cargo +nightly fmt --all --check— 无格式差异（使用 nightly 工具链） - ✅
cargo clippy --all-targets --all-features -- -D warnings— 无警告 - ✅
source .env.test && cargo test 指定测试用例— 所有指定的测试用例全部通过
说明：
- 不能使用稳定版 fmt，必须使用
+nightly来确保统一的格式标准 - Clippy 必须以"错误"级别处理警告，不允许存在任何警告
- 测试必须运行特定相关的测试用例而不是全量测试，可使用
cargo test 模块名::指定范围 - 任何阶段的工作不能破坏现有的构建或测试
- 如果新增的测试在该阶段不完整，应使用
#[ignore]标记
PRmerge 前的终极检查：
- ✅ 本地
cargo build --all通过 - ✅ 本地上述三项验收标准通过
- ✅ CI/CD 管道验收标准通过
必须在同一个 PR 中完成：
- 代码变更
- 对应文档的同步更新（包括行号更新）
- 对应的单元测试或加载测试
- 版本号递增：更新
Cargo.toml中的version字段，patch 版本号加 1- 例：当前
version = "0.17.500"，改为version = "0.17.501" - 版本号更新应在该阶段的代码变更中进行
- 每个 PR 合并时对应一次版本号递增
- 例：当前
禁止：
- 只更新代码不更新文档
- 只更新文档不更新代码
- 延迟更新相关文档
- PR 合并时不递增版本号
- 在一个 PR 中跳过版本号更新
所有阶段的 PR 评审都必须检查：
- ✅ 本 PR 是否改变了任何硬约束或前置依赖
- ✅ 如果改变了，是否同步更新了所有相关文档
- ✅ 代码引用（如有）是否正确
- ✅ 是否引入了新的循环依赖
- ✅ 相关的集成测试是否也被更新
每次代码重大变更后（如大量行号变化、模块重组、API 改变）：
- 相关文档必须在 2 周内完成事实校准
- 事实校准必须包含日期和核对范围
- 任何行号偏移超过 10 行的部分都应被标出
所有改进计划都可能面临的风险：
| 风险 | 可能性 | 影响 | 缓解措施 |
|---|---|---|---|
| 代码与文档脱节 | 高 | 执行混乱、改进失效 | 同步更新、评审检查清单 |
| 跨模块协同不力 | 中 | 集成时发现冲突 | 前置依赖矩阵、集成测试 |
| 前置条件遗漏 | 中 | 工作无法启动 | 必须先完成清单、沟通机制 |
| 文档过期或错误 | 高 | 决策基于假信息 | 事实校准制度、评审制度 |
| 范围蠕动 | 高 | 无限期延期 | 硬约束、阶段边界清晰 |
| 安全假设不成立 | 中 | 生产环境风险 | fail-closed、集成测试 |
面对改进计划的关键决策时（如更改某个阶段的范围、推迟某个前置、调整优先级）：
必须同时满足：
- 与会者包含受影响模块的 owner
- 决策内容同步更新到 README.md 和相关文档
- 更新后的文档在评审前向团队预公示
- 预公示期不少于 2 个工作日，供团队反馈
每个改进计划文档的版本通过以下方式标识：
## 事实校准（2026-06-14）
> 本文档中的代码引用已对照当前 `src/` 重新核对...- 日期代表该次校准或重大更新的日期
- 日期遵循 ISO 8601 格式（YYYY-MM-DD）
- ✅ 添加或修改代码引用时
- ✅ 改变现状描述（如模块状态从"未实现"变为"已激活"）
- ✅ 改变硬约束或前置依赖时
- ✅ 修复事实错误时
- ❌ 只做格式调整或文案改进时（无需更新日期）
- 更新文档顶部的校准日期
- 在事实校准部分补充或更新内容
- 更新所有代码行号引用
- 如果改变了与其他文档的关系，同步更新相关文档
改进方案讨论
↓
文档初稿或更新
↓
内部评审（检查清单）
↓
团队预公示（2 工作日）
↓
合并到 main
当一个决策同时影响 config、vault、mail、notification 时：
- 问题提出：在任何一个文档中提出
- 跨文档讨论：在 README.md 或专项会议中讨论
- 对齐表述：确保所有受影响文档用一致的语言描述决策
- 同步合并：同一个 PR 中更新所有相关文档
对于非紧急的文档更新（如错别字修复、重新表述），采用异步评审：
- PR 开启后，设置 3 个工作日的反馈期
- 无反馈则自动合并
- 有异议可在反馈期内提出，延长讨论
所有文档的 PR 必须满足：
格式与结构：
- ✅ 包含所有必需部分（事实校准、现状表、硬约束、前置依赖矩阵等）
- ✅ 代码引用格式统一：
文件:行号 - ✅ 不包含禁止内容（时间估计、人员分配等）
- ✅ 标题和部分编号清晰
内容质量：
- ✅ 事实校准有日期且内容完整
- ✅ 硬约束明确说明"为什么不能违反"
- ✅ 前置依赖矩阵与实际工作流一致
- ✅ 阶段步骤具体、验收标准可测试
跨文档一致性：
- ✅ 与其他文档的依赖关系表述一致
- ✅ 共同约束的表述相同
- ✅ 如有改变前置依赖或硬约束，相关文档已同步更新
- ✅ README.md 中的优先级顺序与各文档一致
与集成测试的对应：
- ✅ 关键功能都有对应的集成测试场景
- ✅ 集成测试场景在 integration.md 中有明确定义
每个代码 PR 的评审都必须包括：
- ✅ 代码改动是否与对应的文档阶段一致
- ✅ 文档中的行号引用是否需要更新
- ✅ 是否需要更新事实校准日期
- ✅ 是否引入了对文档的前提假设的改变
如果后续需要为新模块添加改进计划文档（如 storage.md、auth.md），必须：
- 参照本文档的结构和规范创建新文档
- 在 general.md 中添加该模块的引用
- 在 README.md 的文档总览中添加该模块
- 明确该模块与现有文档的依赖关系
- 更新 README.md 的优先级和执行顺序
如果某个改进计划不再适用（如模块被重构或删除）：
- 在文档顶部添加标记：
[ARCHIVED 日期] 原因说明 - 保留文档以供历史查证
- 从 README.md 的活跃文档中移除
- 更新相关文档中的交叉引用
- 硬约束：因为架构或安全原因而不可以违反的限制
- 前置依赖：某项工作必须在另一项工作完成后才能开始
- 协同：两项工作应该在同一时间段内共同进行
- 可迁移凭据：可以从配置文件中转移到 Vault 的敏感数据
- 可诊断错误：包含足够信息让用户自行修复的错误消息
- fail-closed：在错误或缺少条件时停止运行，而不是继续执行
- 事实校准：核对文档中的代码引用和现状描述是否与实际代码一致
- 集成测试：验证多个模块或系统的相互作用是否正常工作
- config.md：0a, 0b, 1, 2, 3, 4, 5, 6, 7, 8（共 10 个阶段，其中 0a 和 0b 合并为"阶段 0"）
- vault.md：A, B, C, D, E, F, G, H, I, J（共 10 个阶段）
- mail.md：0, 1, 2, 3, 4, 5（共 6 个阶段，其中 0 和 1 已完成）
- notification.md：0, 1, 2, 3, 4, 5（共 6 个阶段）
- orbit.md：0, 1, 2, 3（共 4 个阶段，其中阶段 3 为决策门）
- trunk-push.md：1, 2, 3, 4, 5, 6（共 6 个阶段，其中阶段 1-3 为独立可验收的缺陷修复——生产部署以阶段 2 为前置；阶段 6 为可选优化）
- libra.md：0, 1, 2, 3, 4, 5（契约、可信接收、任务与修订、主干把关、团队历史与运维、可选接入；阶段 3 依赖 trunk-push 1–3）
- P0：必须先做，阻塞其他工作，独立或与少数文档协同
- P1：高优先级，在 P0 后紧随进行
- P2：中优先级，第一批功能完整时必须包含
- P3：后续优化，可与其他高优先级并行
- P4：长期或可选，不阻塞关键路径
- 日期：2026-09-06（历史：2026-06-14 首版；2026-06-19 增补 orbit.md 登记）
- 本次更新：登记 libra.md 的分层结构、文档角色、阶段编号及专项执行索引；用户要求的本次交付仅为文档与 review。
- 内容：首版发布，定义所有改进文档的共同治理规范；2026-06-19 新增 orbit.md（orbit 依赖重构）；2026-09-04 新增 trunk-push.md（Trunk 直推形态与 Monorepo 写入序列化），均已登记到分层结构、角色定义与阶段编号约定
- 适用文档：README.md、config.md、vault.md、mail.md、notification.md、integration.md、orbit.md、trunk-push.md、libra.md
本文档是所有改进计划的基础框架。在执行改进时，遇到任何"这个应该怎么做"的问题，应首先查阅本文档。如果本文档未覆盖，应提出到团队讨论，再补充到本文档中，确保后续改进遵循相同的规则。