Distributed system

Distributed system 在这里指“系统行为依赖多节点协同、复制状态或集群控制面”的工程模式，而不是“仓库里有几个服务”这么宽。真正命中这个 Topic 的项目，通常存在 cluster-wide desired state、节点成员关系、复制日志、leader/follower 语义、局部 runtime reconcile 和网络分区后的恢复问题；维护者必须同时考虑单节点局部行为与跨节点一致性（projects/xp.md）。

它和 Rust web service、Ops tool、Embedded admin UI 常常相邻，但边界不同。Rust web service 解释单个服务进程怎么实现，Ops tool 解释运维动作怎样安全落地，Distributed system 解释的是“为什么某个 API、配置或状态变更不能只看单机成功，而要看它怎样在集群里复制、提交、应用和恢复”。

当仓库明确维护多主机控制面、共识状态、集群成员管理、节点间复制或“期望状态 -> 每节点本地执行”的架构时使用。只要改动会影响 leader 选举、日志/状态迁移、节点注册、配置下发、局部执行器与全局状态的接缝、集群 API 的提交语义，或者 split-brain / partial failure / replay 行为，就应该命中本 Topic。

若项目只是由多个服务拼起来、但没有复制状态和一致性约束，就不该强行归到这里。普通微服务、单机后台配一个前端、或某个 repo 只是引用了 raft/grpc 依赖，都不足以命中 Distributed system。这里要回答的是“系统如何在多节点条件下保持同一份运维真相”，不是“项目规模看起来很大”。

• 先明确“哪一层是真正被复制的状态”，再讨论本地 agent/worker 如何应用它。像 projects/xp.md 这种模式里，Raft 保存的是 cluster-wide desired state，本地 xray runtime 只是被 reconcile 的结果；如果把两层混成一个概念，后续 API、回滚和排障都会出错。
• 默认把节点局部副作用做成可重复执行的 reconcile，而不是把 Web/API 请求直接等同于成功生效。分布式控制面里，accepted、committed、applied 是不同阶段；Topic 回答里应明确改动属于哪一层完成。
• 状态模型、日志结构和 migration 必须作为一等维护面写出来。只要持久化格式、协议字段或 cluster state 语义发生变化，就不能只跑普通单元测试，还要考虑旧节点升级、新旧版本混跑和历史日志回放。
• 运维控制台和 API 需要暴露分布式健康信息，例如 leader、membership、lag、last applied、reconcile failure 或节点离线状态；否则系统虽然“能工作”，维护者却无法判断问题出在共识层还是本地执行层。
• 验证时至少区分三类路径：单节点 happy path、多节点一致性路径、以及节点异常/网络分区后的恢复路径。没有这三层划分，Distributed system 很容易被退化成“本地起两个进程看看能不能跑”。

• projects/xp.md：核心样本。它把 OpenRaft cluster state、本地 Xray reconcile、gRPC 边界和嵌入式 admin UI 放进同一控制面里，足够说明这里的“分布式”不是抽象概念，而是每天都会影响 API 设计、运维可见性和升级策略的主约束。
• skills/style-distributed-system/SKILL.md：分发层的 group Skill 会把后续 Agent 引回 cluster state、reconcile 和多节点验证面，而不是只让它回答“这个仓库是不是分布式”。这证明 Topic 的复用点是维护动作与判断路径，不是词汇标签本身。

• 把任何多服务项目都叫 Distributed system，会让 Topic 完全失去边界。没有复制状态、成员关系和局部 reconcile 的系统，不该借这个词抬规格。
• 直接修改节点本地 runtime，却不更新 cluster-wide desired state 或 migration 规则，会造成“单机看起来修好了，集群下一轮 reconcile 又把它改回去”的假修复。
• 把一次 API 返回成功等同于全局生效，忽略 commit/applied 差异，会在 rollout、回滚和故障分析里持续误判。
• 只验证 happy path，不验证节点离线、旧版本回放或重新加入集群的路径，系统会在最关键的时候暴露出恢复语义缺失的问题。

• projects/xp.md
• skills/style-distributed-system/SKILL.md
• skills/style-playbook/references/data/topics/distributed-system.json