Architecture Charter zh

架构宪章

指导每一个设计决策的原则。实现细节属于各模块的文档。

定位

dsh-edge 是适配层，不是 fork。 它将上游已发布的包运行在 Cloudflare Workers 上。上游拥有所有业务逻辑。Edge 只拥有让这些包在 serverless 环境中工作的传输和存储。

应用逻辑完全不变，只有管道变了。

原则

最大化利用上游能力

上游提供了插件，安装它。上游提供了扩展点，使用它。上游提供了抽象类，实现它。永远不重新实现上游已发布的能力。如果你在 Edge 代码里写业务逻辑，那你大概率做错了。

桥接，不重建

上游按单进程设计——服务之间在内存里互相调用，客户端直接读取状态。Edge 唯一的职责是在上游假设本地性的地方补上网络传输。每个 Edge 拥有的组件必须恰好归入三类之一：

• 直接复用 — 上游插件原封安装，零 Edge 代码。
• 最小替换件 — 上游接缝（抽象类或能力接口）的平台相关实现。
• 传输桥 — 将进程内信号转发到网络上，不包含任何业务逻辑。

两条总线，一根网线

上游在一个进程里运行两个 cordis Context——服务端和客户端——通过进程内插件连接。Edge 把它们分到两个物理运行时，通过 WebSocket 和 HTTP 连接。架构不变，只是通信介质不同。

补丁纪律

补丁是最后手段。每个保留的补丁需要版本绑定的文件名、缺少补丁时的失败测试、理由说明和记录在案的移除条件。组合和扩展点永远优先。

决策优先级

1. 安装上游插件。 检查它的 inject 要求——如果所有依赖都能满足，直接安装。这是默认选择，不需要理由。
2. 实现上游接缝。 当上游提供了抽象类或能力接缝，需要平台相关的后端时，写最小的符合实现。
3. 加传输桥。 当上游假设进程内通信时，通过上游的扩展点捕获信号，转发到网络上。桥里不应有任何业务逻辑。
4. 打补丁。 当以上都因为硬性的平台不兼容而无法工作时。记录移除条件——每个补丁都应该在上游演进后可以删除。

所有权边界

Edge 拥有：平台入口。Durable Object 生命周期。服务端与浏览器之间的网络传输。存储后端。文件系统委托。Owner 认证。HTTP 路由分发。

上游拥有：Agent 行为。工具定义。系统提示词。模型编排。Session 事件格式。目标追踪逻辑。压缩策略。所有面向用户的交互设计。所有客户端 UI 插件。

当一个新的上游能力到来时，第一个问题不是"我们怎么实现这个"，而是 "什么阻止了它直接工作？" 答案几乎总是：缺少存储后端、缺少网络传输、或某个 Node.js API 在 Workers 里不可用。修复那个特定的缺口——仅此而已。