endorphin-tessera-gui/docs/architecture/07-decisions.md

07 · 本轮整理的设计决策

职责目录，不冒充已经解耦的层

采用 shell / runtime / model / render / bridge 是为了让入口、对象、执行和绘制更容易定位。当前仍是一个 Rust binary crate：model 需要 bridge 派生类型与 render 几何，bridge 需要 model 和 render，runtime/API 也会通知 shell 的 AppEvent。组件图因此画的是主要行为流，不是严格单向依赖约束。

main.rs 的 pub(crate) use 是内部路径兼容门面，使现有 crate::block 等调用继续指向新目录。它不增加公共库 API、不产生第二份对象，也不隐藏多份实现。代价是调用路径暂时不能单独反映目录所属；需要打开 main.rs 或源码导航确定归属。后续若要拆 crate，应先定义跨边界协议并梳理实际循环依赖，而不是机械删掉别名。

拆分的是职责，不是复制代码

• API 的 worker 负责活跃 VM、候选请求、增量执行、发布与关闭；HTTP 路由和活动记录仍在 api.rs。
• 在线 agent 指南独立到 api/guide.rs，仍由当前 NamespaceState 生成；嵌入例子的相对路径已随目录调整。
• bridge 的 tree.rs 只放无托管句柄的派生画面数据；signatures.rs 负责规范签名；calls.rs 实现 NativeCallable；bootstrap.rs 安装类型表及 globals。
• bridge 主模块保留 Session、窗口 Presentation 和挂起布局等协调。这里仍接近 2000 行；本轮没有声称已把全部大模块拆完。
• 原有 tests.rs 随所属模块移动，保持原测试含义，只修正编译时样例文件路径。没有删减现有测试来让检查通过。

这些子模块共享父模块的内部类型；use super::* 表达它们是同一实现单元的拆分，而不是独立公共服务。worker 只向 API 父作用域暴露必要协调接口和现有测试所需状态；其他请求处理细节继续私有。

本轮保持的边界

• 不更改 Endor 示例、API 路由、语法、运行时预算、窗口视觉参数和交互效果。
• 不更新 Aster 子模块，不改变 vendor 历史。
• 不移动构建产物、已有示例与媒体目录，不修改用户未提交的示例工作。
• 不引入新的产品依赖或在线 UML 渲染服务。文档图片由仓库外的临时 Node 工具生成，应用构建不依赖它。

文档的可信度

本套 UML 以实际 Rust 类型、线程名、队列、方法和引用语义为依据。.puml 是图的唯一可编辑来源，PNG/SVG 由 scripts/render-uml.mjs 生成；文档直接引用生成图像。概念状态机、主要调用流及省略字段都在图旁标明；它们不是自动从源码生成的完整模型。进展矩阵区分代码已有、此前人工验证、本轮验证及未完成项。

更改执行/生命周期语义后应同步更新 02/03/04 与对应 .puml；更改 shell 交互后更新 05；发布阶段结果更新 06 和本轮验收记录。逐文件清单是本次迁移快照，不要求以后每次新增模块都伪装成同一轮迁移。