keel

Keel

Keel 用于发现、评判和治理承重性架构安排。它会确定证据最充分的方向，并确保声明的架构随着系统演进，仍然可执行、经济、可迁移且可删除。

在模块、边界和系统层面使用 keel，处理各部分之间的职责、权力或所有权、接口或契约、依赖方向、状态或恢复所有权，以及隔离未来变更的接缝。使用仓库原生术语，并将适用的说明、记录、契约和入口路径视为证据，而非装饰。

状态与所有权

只检查足以根据当前请求、约束来源以及有代表性的调用点或契约来选择当前状态的内容。仅在证据改变架构任务时才转换状态：

• Decision — 建立、更改或比较承重性架构安排。这包括从零开始的工作，以及对现有目标进行经授权的改进。
• Judgment — 评估所提供的架构、设计、RFC、变更集或现有系统是否充分、符合要求或可行。保持目标不变。如果目标不可行，应基于证据和所需的决策权限以 Open 状态结束；仅当授权范围包含选择或改进时才进入 Decision。
• Governance — 决定是否恢复、保留、迁移、退役或移除已声明或有证据支持的架构安排或控制，或评判其长期健康状况。证据必须表明存在承重性义务、反复绕过或架构漂移，而非普通维护。仅当经授权的补救措施需要新的承重性架构安排时才进入 Decision。
• Exit — 请求和约束来源已确定一项可行且重要的架构，剩余任务仅是在该架构范围内实施、诊断、调优、测试或验证。仅当证据表明出现了实质不同的承重性 Decision、Judgment 或 Governance 问题时才重新进入。

私有、本地、可逆且只有一个消费者的选择仍可能需要 Decision 或 Judgment；应根据影响、可逆性和不确定性来调整证据规模和流程形式。

专注型工作流负责其领域证据、标准、方法、词汇、产物、专业判断和完成条件。Keel 仅在声明的决策权限范围内整合承重性架构结果；执行工作流负责变更、工作保全、测试机制和验证。

自动或强制加载既不代表适用，也不授予行动权限。在 Exit 状态下，如果宿主提供技能目录，则检查该目录；若存在合适的归属工作流，则选择并完整阅读，否则继续使用通用工作流。停止使用 Keel 专属的路径、参考资料和输出格式。

以建设性方式求解

决策、判断和治理共享一个有界的证据循环，但各自承担不同工作。决策比较不同方向。判断依据相同的标准检验给定目标，并在提出改进建议前转入决策。治理比较适用的恢复、保留、迁移、退役、移除和不采取行动等应对措施。

1. 界定并检查 — 说明当前状态要回答的问题、期望结果、权限、硬性约束和标准。绿地证据包括用户目标、明确的外部约束、带有来源信息的聚焦或领域发现，以及运行环境。将架构形态视为候选方案，标注假设，并将缺少的代码库先例视为不可用，而不是凭空编造继承而来的架构。只查找可能改变问题界定、候选方案集合或结果的证据。
2. 形成、检验或比较 — 对于决策，推导出一组最精简、具有实质差异且可行的方向，以揭示真正的权衡。对于判断，依据同一组已声明的标准检验给定目标，不生成替代方向。对于治理，只比较适用的干预措施。可信时，纳入更简单的方案或不作更改的结果；如果约束只允许一条路径，就不要编造替代方案。当有界模型、特征描述、一致性检查或可逆实验是获取能够改变决策的证据的最低成本方式时，就采用它。
3. 整合并给出结果 — 保留聚焦工作流的发现，依据相同标准评估证据和任何真正的候选方案，并给出证据支持最充分的方向、结论或治理措施，同时说明其重大权衡和置信度。如果证据支持用户未提及的更好选项，就指出该选项，但不要暗中改变目标。
4. 仅深化有证据支持的结果 — 只有当答案仍可能改变结果、采用方式、恢复方案或退役计划时，才解决编号列出的问题。

当进一步搜索、增加选项或补充细节不太可能改变结果或消除重大风险时，就停止。如果新证据使某个可行方向重新成为选项，就对它进行比较，而不是为现有方案辩护。

决策、判断和治理最终会进入以下两种状态之一；退出则直接交接，不采用此界定方式：

• 已关闭 — 证据支持最充分的结果、适用权限、问责安排和重大风险均已明确；已知未知因素不再可能改变结果。
• 未关闭 — 给出目前可得的最有力且有界的结果、建议或实验，说明可能改变决策的未知因素，以及其负责人或责任归属缺口，并指出下一项证据或决策触发条件。只有确实存在的替代方案才纳入。

对于影响范围较小的内部选择，简洁的比较和建议就可能足够完整。不要编造无法改变选择的兼容性、迁移、恢复、保护措施、治理或产物。

对于治理，建设性结果可以是删减、恢复执行、更经济的受治理路径、分阶段迁移、退役或有依据的不采取行动——而不是默认新增一层。

1. 保持主干精简

仅映射适用的关键节点，并使用仓库原生术语。入口界面、变更准入、已接受状态、外部可见效果、完成和恢复都是示例，并非必需清单。若省略了仓库声明的节点或基于风险合理推断出的节点，请说明其缺失或不适用的原因，而不要凭空增加阶段。更改或新增适用节点属于边界决策。

关键决策链并非指某个控制器、写入方、进程、传输方式或部署拓扑。只要多种执行机制保留了所有适用且已声明的边界契约，它们就可以共存。新增或更改关键节点属于重新设计：说明该节点要解决的结果、影响因素或阻碍；在相关时说明其协调规则；以及它会更改或退役的路径。

跨领域机制可以有专属负责人，而不必成为并行的权威根或绕过路径。只有在职责范围明确、现有负责人无法妥善承担且不会造成概念扭曲，并且它减少的歧义多于新增的歧义时，才添加顶层概念。

2. 评定每个界面

根据每个具体界面所承载的兼容性承诺进行评定；有仓库分类时使用这些分类。若没有分类，请采用适度的备用方案，不要给整个领域或机制评级：其私有实现与跨边界契约可能不同。

每个导出项、字段、标志、选项以及消费者依赖的可观察行为，都可能构成承诺。选择满足需求的最窄承诺。公共、持久化和跨边界界面需要明确的兼容性或切换策略；绝不可静默地破坏它们。

只有在目标和切换决策权限、消费者与数据范围、旧入口退役方式以及恢复方式都明确时，才可以直接切换到目标方案。否则应进行版本升级或迁移。

3. 声明权威、写入方和投影

对于每个重要事实和职责范围，使用受支持的最简模型。仅声明实际存在的维度，并使其彼此独立：

• 事实权威 — 决定哪些内容会被接受为事实的来源或规则。
• 决策权威 — 获准批准或更改关键决策的参与方。
• 责任负责人 — 对语义、策略、生命周期和升级处理负责；第 4 节涵盖共同责任。
• 写入方和准入 — 可以提出变更的参与方及其途径。写入权限既不授予所有权，也不构成事实权威。
• 数据分区 — 职责范围、边界和传输规则。
• 副本 — 角色、来源、时效性和读取语义。
• 提交 — 接受、顺序或版本、可见性和法定人数。
• 冲突 — 预防或检测方式，以及收敛规则。
• 恢复 — 触发条件、决策权威、负责人、操作、终态不变量，以及第 5 节要求的证据。

这些维度可以共存；分区、复制、法定人数和多写入方准入不能取代权威模型。

某个制品可以投影一个事实，同时权威地记录另一个事实；请分别声明每种关系。通过其来源和重新生成路径更改投影。应解决重叠的事实权威问题，而不是声称写入方可以互换。

4. 明确责任边界与目标范围

为每项重要事实、契约、边界决策和生命周期设定责任模型。所有者不同于编写者、维护者、操作者和使用者；由一位所有者负责很常见，但并非普遍适用。联合或联邦责任制应明确管辖范围、决策权、平局裁决或升级机制，以及生命周期。

说明每位关键所有者负责什么。对于容易与相邻职责混淆的部分，也要说明其不负责什么。

遵循已声明的依赖方向，并通过公共接口或组装接缝跨越边界。只有当语义是中立的且责任归属在共享领域时，才将语义移入共享领域；两个使用者需要相同能力，并不足以构成理由。

目标范围 — 区分所请求的本地成果、任何拟议的可复用接缝或产品系列，以及首个实现阶段。依据请求或权威范围来源确定范围；样本数量、代码形态、“试点”一词以及后续成果都只是可行性证据，并非范围依据。如果已授权更广的产品系列范围，应针对具有代表性且存在实质差异的成员测试该接缝，但不要迁移它们。如果范围尚未明确且可能影响决策，就不要声称更广泛的复用范围，并提出成本最低的澄清问题或可逆实验。

优先采用范围有限且已声明、可由工具枚举的入口表面，以便仍可退役。

5. 设计负向路径与时间维度

为重要的负向结果定义行为或明确标记为未知。只检查设计中合理可能发生的情形，包括故障、部分完成或过时的工作、取消、超时、重复、并发、提交状态不确定、重试、重启和重放。不要为可逆的私有选择凭空设计状态机。

为每种适用的恢复方式明确以下内容：

• 检测方式或触发条件；
• 决策权限与恢复责任人；
• 回滚、向前修复或协调操作；
• 终态不变量与完成证据；以及
• 无法收敛时的升级方式。

将效果分类为可逆、可补偿或不可逆，并据此调整控制措施。应确认问题已解决，而不只是指出恢复路径。

6. 用可证伪的检查守护边界

为每条重要架构规则保留可追溯的理由。只有在违反规则会造成重大风险，且检查结果能够改变行动时，才添加可证伪的守护措施或明确的审查。守护措施需要有证据表明它能检测到已知或安全植入的违规；执行工作流负责确定如何生成此类证据。

默认例外基线只减不增。扩大基线属于边界决策，应记录决策权限、理由、有限范围、责任人、审查触发条件和移除条件。将代码移出守护措施的适用范围，同样是边界变更。

只有在更简单的义务仍能保持其不变量，或有证据表明其失效机制已不再影响决策时，才更改或退役 Keel 规则。仅凭未观察到问题，无法证明其中任何一点。

7. 让受治理路径成本最低

在不削弱具有约束力的产品、安全、安保、隐私或合规政策的前提下，减少可避免的阻力。反复出现的绕行信号表明的是路径成本，而非不当行为。负责的工作流可以立即控制当前风险；在修复持久解决路径的同时，应记录遏制范围、决策权限、成本和退出条件。

8. 代谢，否则腐朽

腐朽就是熵：无法阻止，只能以快于其累积的速度将其代谢。让漂移、迁移和删除成为常规操作。新增名词、层或抽象，必须消除比引入更多的歧义。在现有系统中，说明它将取代什么；否则记录净增长、责任归属、原因和审查触发条件。在全新项目中，应与一个更简单、未采用的替代方案进行比较，而不是凭空创建退役台账。

退役意味着关闭当前的入口界面，列出并迁移或退役依赖项，并在实现之外保留所需的行为证据。历史代码可用于了解行为和风险，但不能决定目标拓扑。

参考资料

选择 Decision、Judgment 或 Governance 后，仅加载所选状态和当前相关事项所需的匹配分支参考资料；Exit 不加载任何资料：

• references/rule-rationale.md — 变更、审计、替换或退役 Keel 规则时使用。
• references/task-routes-and-lenses.md — 重大全新设计、架构审查、边界变更或结构性重构需要正式路线时，或重写需要判断采用切片还是完整目标时使用。
• references/surface-cutover.md — 仓库等级尚未明确、某个界面可能已成为事实上的契约，或需要切换证据时使用。
• references/recovery-guards.md — 选择恢复控制、设计或退役防护措施，或变更例外基线时使用。
• references/rot-audit.md — 对架构衰退、漂移、反复绕过、例外增长或长期健康状况进行 Governance 时使用。
• references/architecture-records.md — 记录承载或传递关键架构事实时使用。