light-system-design

系统设计生命周期

负责系统边界、运行时接口、运营数据存储、系统迁移和架构决策。不要把图表、SQL 文件或 OpenAPI 文档等同于可运行、安全或可扩展的系统。

对于任何现有系统任务，请先阅读 references/system-design-resource-map.md。 该文档定义了生命周期、制品契约、决策停止点、证据状态、访问层级和跨技能所有权。仅针对所选系统适用的数据库/API/可靠性分支，阅读 references.md。

不可妥协的边界

1. 将仓库、配置、架构、API、依赖项和部署信息的接收视为只读访问。此操作不代表获得重写它们的授权。
2. 将缺失的事实保留为 UNKNOWN。不要根据“系统设计”这一说法推断流量、SLO、一致性、预算、合规要求、迁移窗口或团队能力。
3. 至少提供一项建议、一个可行替代方案，以及明确的拒绝/退出条件。在用户作出选择前，不要替用户决定数据库、拓扑、兼容策略或迁移策略。
4. 后续任何变更都必须以用户选定的选项和精确授权的操作 ID 为依据。保留变更前后的定位信息、SHA-256、验证结果和回滚方案。
5. 切勿修改生产数据库或配置。仅在明确纳入范围的一次性环境中应用变更；否则提供经过审核的计划和脚本。
6. 将 schema_lint.py 描述为词法启发式工具。它不是 SQL 解析器、查询规划器、锁模拟器、架构差异引擎，也不能证明零停机。
7. 仅对实际运行过的检查使用 VERIFIED，并保留其命令、返回码、定位信息和哈希。其他情况使用 PLANNED、UNKNOWN 或 UNAVAILABLE。
8. 不要将此技能纳入研究 DAG。不得输出 light.findings.v1；不得添加 STAGE_GATES、ROUTES、阶段编号或反向边；不得附加 _shared。

选择模式

情况	模式
没有实现的新系统	绿地需求和方案设计
现有仓库/系统	只读接收，然后盘点当前状态
逐步变更的现有单体或服务	现代化，兼顾兼容性和回滚
仅 API 变更	契约和使用方兼容性分支
仅架构变更	特定方言/版本/上下文的迁移分支
用户提供已完成的方案包	审核和证据验证

阶段 1 — 接收与保护

记录以下信息，或在缺失时保留为 UNKNOWN：

• 用户、业务目标、关键用例、数据分类；
• 负载范围、延迟、可用性、持久性和一致性目标；
• 团队/运维能力、预算、部署环境、合规要求和迁移窗口；
• 拓扑：绿地、单体、模块化单体或服务；
• 组件、负责人、接口、存储、依赖项、写入路径、信任边界、故障模式、版本、源定位信息和新鲜度；
• 现有客户端、架构历史、部署/运行时约束和兼容性承诺。

对于现有系统，请从 templates/system-intake.template.json 创建接收清单，并运行：

python scripts/architecture_lifecycle.py intake <root> \
  --manifest <system-intake.json> --out <evidence-dir>

确保 --out 位于源根目录之外。读取所有生成的制品，并验证 source_unchanged=true。

阶段 2 — 需求与当前状态

生成：

• 上下文场景和质量属性场景，包含可衡量的刺激、环境、响应和目标，或 UNKNOWN；
• 请求速率、存储增长、扇出、延迟预算及任何主要资源的容量估算；如果未知，请填写 UNKNOWN 并提供测量计划，而不是编造数字；
• 当前状态 → 目标状态映射，并明确列出差距。对于绿地项目，当前状态可以是 none，但差距列表仍须记录缺失的证据；
• 架构适应度函数：可观测信号、阈值、验证命令/探测方式以及证据状态。没有适应度函数的质量属性仍然只是文字描述；
• 组件/接口/存储清单，注明负责人和事实来源；
• 同步/异步数据流、事务边界、交付语义、幂等性/去重、背压、超时/重试和故障处理；
• 风险、假设、未知项和过时事实登记表。

不要悄然将代码搜索结果转化为架构事实。将每项事实标记为已声明、已观察、已推断或未知。

阶段 3 — 方案与决策暂停点

至少提出：

1. 一个推荐方案及其理由；
2. 一个可行的替代方案；
3. 各方案不应采用的条件；
4. 成本/复杂度、迁移风险、兼容窗口、回滚、运维和退出标准；
5. 可能推翻推荐方案的未决事实。

然后暂停。请用户选择一个方案并授权确切的操作 ID。不要预先写入用户的选择，也不要在尚未获得批准时生成所选方案的架构方案/ API /迁移/ADR。

在呈现决策前，请验证是否已提供需求、容量估算、当前/目标状态、适应度函数、至少两个实质不同的方案、硬约束和适应度证据、权衡、不采纳条件、反转成本以及迁移/弃用立场：

python scripts/design_readiness.py --input templates/design-readiness.example.json \
  --as-of 2026-07-05

在 proposal 中，PASS 仅表示 ready_for_user_decision=true；绝不写入用户的选择，且报告会为每个方案生成规范化的 option_packet_sha256。在 authorized 中，用户的选择必须与 light.system-design.v2.authorization 配对，且方案摘要仍须匹配、获批操作 ID 必须是该方案的子集、目标必须明确为可丢弃、回滚不得被豁免，并且日期不得晚于 --as-of。行走骨架 （entry/core_path/state_boundary/observable_result/failure_probe/verification/action_ids）在 ready_for_implementation=true 之前，只能包含获批的操作。

对于每个方案，说明迁移/弃用是否适用。如果适用，该方案必须优先替换。使用方清单须列出稳定的使用方/接口 ID、负责人、使用状态、证据状态、证据位置/日期，或明确的测量计划。遥测须采用结构化的指标/来源/证据记录。发布须由多个阶段组成，并为每个阶段注明进入、退出和回滚条件；回滚须包含触发条件、操作和验证方式。弃用兼容窗口须注明开始时间、结束时间和移除条件。纯文本字符串不满足这些字段要求。如果迁移不适用，请记录原因；不要留空。

在用户回复后，使用 templates/decision-authorization.template.json。 复制 design_readiness.py 输出的所选摘要；需求、状态模型、适应度函数或所选方案发生变化，都会改变该摘要，并需要重新授权。

阶段 4 — 构建架构包

获得授权后，仅产出选定范围内的内容：

• 上下文和质量属性；
• 组件/边界视图和数据流视图；
• API/事件契约和消费者兼容性策略；
• 架构方案（schema）及从当前状态到目标状态的变更计划；
• 发布、回填、回滚和弃用计划；
• 包含备选方案和影响的 ADR；
• 安全/隐私设计控制措施及待专家审查事项；
• 验证计划和交付证据。

使用 templates/architecture-package.template.md。 将随附的 SQL/OpenAPI 文件视为标注了方言/版本的示例，绝不要视为生产环境默认方案。

阶段 5 — 契约、架构方案和迁移检查

API 契约

定义版本控制、身份验证/授权边界、错误模型、分页、幂等性、 兼容窗口和弃用策略。使用以下工具验证 OpenAPI：

python scripts/contract_validate.py --spec openapi.yaml \
  --examples examples.json --json

VALIDATED 要求使用 openapi-spec-validator，并成功通过示例架构检查。 STRUCTURE_ONLY 或 UNAVAILABLE 不属于契约验证。

架构方案和迁移

将以下四项任务分开处理：

1. 设计阶段的架构方案审查；
2. 当前状态与目标状态的差异/漂移；
3. 迁移 SQL 风险检查；
4. 发布/回填/回滚执行测试。

仅在明确指定方言并提供相关上下文时，才运行启发式检查器：

python scripts/schema_lint.py --ddl migration.sql \
  --dialect postgresql --server-version 18 \
  --context migration-context.json --json

对于权威的差异/漂移检查，请使用为项目选定的真实引擎/工具 （例如 Atlas、Skeema、Alembic、Flyway、Liquibase 或 Prisma），并保留 其命令/输出。不要声称此技能实现了这些引擎。

根据架构方案规范生成 ER 视图：

python scripts/er_diagram.py --in schema.yaml --strict --out schema.mmd

如果 Mermaid 渲染不可用，只报告语法/结构验证结果。

阶段 6 — 验证、演练并交付

根据适用情况进行验证：

• 契约和示例请求/响应；
• 在选定的数据库/版本上创建架构方案并执行迁移；
• 数据保留、兼容窗口、回滚和重新应用；
• 负载假设，而不是编造负载测试结果；
• 超时/重试/熔断器及故障演练；
• 日志、指标、追踪、SLO、部署和回滚的可观测性；
• 租户隔离和 PII 控制，专家审查仍须待完成。

在包清单中记录授权绑定、源材料接收绑定、已实施的操作 ID、 产物哈希和验证条目，然后运行：

python scripts/architecture_lifecycle.py verify-package \
  --package package-manifest.json --json

仅当软件包明确区分 VERIFIED、PLANNED、UNKNOWN 和 UNAVAILABLE，每个 VERIFIED 条目都有证据支持，清单 绑定了复制的授权文件、选项摘要、已批准的操作 ID 和已实施的操作 ID， 且现有系统的软件包绑定了只读的 intake-integrity.json 哈希时，才可交付。 清单中的产物和验证定位符均相对于清单所在目录解析，且必须位于 该软件包目录内；../、指向外部证据的绝对路径或依赖当前工作目录的定位符， 都不属于可移植的交付软件包。

跨技能职责

• system-design：系统边界、运行时接口、运维架构方案、 系统迁移、可靠性选择、ADR。
• project-structure：可见文件树和获授权的文件移动。借鉴其 保护规范；绝不要将架构方案迁移交给它。
• data-engineering：研究数据质量、沿袭、转换、拆分 和数据发布。服务数据库不等于研究数据集管道。
• frontend-design：交互和界面实现。此技能负责后端/API 边界， 不负责 UI。
• research-ethics：最终伦理/隐私判断。此技能仅提出设计控制措施 和待审查事项。
• orchestrator：可使用已交付状态；不得为其虚构门槛。

验证

运行每个脚本的自测：

python scripts/architecture_lifecycle.py --selftest
python scripts/schema_lint.py --selftest
python scripts/er_diagram.py --selftest
python scripts/contract_validate.py --selftest
python scripts/design_readiness.py --selftest

交付前，请确认：

• 对现有系统的盘点为只读。
• 明确标示了未知需求和过时事实。
• 明确列出了容量、负载和存储估算；未知项有测量计划，而非凭空编造数字。
• 已记录当前状态 → 目标状态之间的差距，包括绿地项目（current_state=none）也是如此。
• 每项质量属性都有适用性函数；每个选项都有适用性结果，并附有证据或如实标注 UNKNOWN/UNAVAILABLE 警告。
• 存在选项、权衡、否决条件和真实的用户决策。
• 授权摘要仍与所选选项方案包匹配；已批准的操作 ID 在范围内，目标明确为可丢弃，且仍要求回滚。
• 软件包清单绑定了授权文件哈希、选项摘要、已实施的操作 ID，以及只读盘点的完整性，或明确说明属于绿地项目／不适用。
• 至少比较了两个接口／选项；没有悄然接受第一个想法。
• 已授权设计采用最精简的端到端步行骨架，并包含故障探测。
• 明确说明了迁移／弃用方案；适用的迁移以替换为先，并包含使用方清单、遥测、推出、回滚和兼容窗口。
• 变更与已授权的操作 ID 以及可丢弃目标相符。
• API／架构／迁移相关声明注明了方言、版本、上下文和限制。
• 每项 VERIFIED 均包含命令、返回码、定位信息和 SHA-256。
• 每条验证记录都带有操作 ID，且这些 ID 属于已实施并获批准的范围。
• 软件包产物／证据的定位信息均以清单为基准，且不会越出软件包目录。
• 已执行回滚和兼容性验证，或仍有明确的计划。
• 跨技能和 DAG 外边界保持不变。