架构总览

Tether 是 deepseek-harness（dsh）的 C# 重实现， 建立在 Cordis 插件框架之上——一切皆插件。本页说明包为什么这么划分，以及划分背后的三条规则。

两层

分层是硬约束，不是风格偏好。

• Cordis.* —— 与 agent 无关的通用插件框架层。它不知道什么是 LLM、什么是工具调用。
• Tether.* —— agent harness 产品层。能力按 Service Definition、Provider、Consumer 三种角色组合，进程入口只负责装配插件树。

Tether 以 dsh 的调用方可观察语义为复刻目标，但允许采用符合 .NET 生态的包划分、类型和内部实现。 复刻基线与对齐制度见 dsh 基线与对齐。

三条结构性规则

一、Cordis 与 Tether 分层。 Cordis 是通用插件框架，保持独立；Tether 建立在它之上。框架核心禁止引用任何 Tether.* 包。

二、能力 seam 决定是否拆程序集。 Service Definition 单独一个程序集，里面只有接口与数据类型；Provider 与 Consumer 都引用它。这样组合预设时只换实现、不换引用。

三、Composition Root 收敛到 Boot。 进程入口只管日志与宿主，插件树由加载器从 YAML 挂载，保持一切可 patch。

实际的依赖图

下表来自各 csproj 的 ProjectReference，不是设计意图的描述。

零引用的定义程序集

这些程序集一个 ProjectReference 都没有——连 Cordis 都不引用。

第一条规则因此是被机械保证的，不依赖人的自觉；第二条规则也在这里落地：换实现永远不动引用。

能力包的三角色模式

每块能力都按同一个形状展开，引用关系是可预测的公式：

按这个模式展开的能力：

同一个形状重复了十余次，这不是巧合——它是第二条规则被机械执行的结果。看到一个新的 Tether.X 目录，不用读代码就能推断出它是零引用的接口包，Tether.X.Local 是它的本地实现，Tether.X.Tools 把它暴露给模型。

会话持久化在三角色之外再显式拆出 .Coordinator：它消费唯一的 ISessionEventStore Provider，并向其它 consumers 提供 ISessionPersistence；composition 替换 .Jsonl / .Sqlite 时不替换 Coordinator。

能力清单与文档覆盖

仓库当前有约六十个程序集，本站不为每一个都写专页。下表按能力族给出全图，并如实标注哪些还没有专页。

其余程序集

三点值得单独指出：

• 产品层实现包彼此不可见，仅通过服务接口相遇。唯一的例外是 Tether.Core.AgentLoop 依赖 Tether.Core.Agent。
• 只有拥有两个可独立观察、可能分叉的运行期事实的实现包才引用 Tether.Invariants 并注册 package-owned 检查；没有这种关系的包不创建空 companion。详见运行期不变量。
• Tether.Shell.Local 与 Tether.Fs.Search 都额外引用 Tether.Subprocess——前者用它起 bash / pwsh，后者用它跑打包的 ripgrep。进程执行只有一份实现。

目录约定

src/Cordis/          框架核心，与 agent 无关，禁止引用任何 Tether.* 包
src/Cordis.*/        框架周边（Loader / Hmr / Scripting）
src/Tether.*/        产品层能力包
apps/                进程入口（CLI / Web 宿主）
tests/               与 src 镜像：src/Foo/Foo.csproj ↔ tests/Foo.Tests/Foo.Tests.csproj
formal/lean/         Lean 4 形式化对照模型（独立 Lake 工程，不进解决方案）

既定技术选型

这些是已经拍定的决策，新包按此选型，不需要重新讨论。

工程规范要点

• C# 最新语言版本，net10.0；Nullable 与 ImplicitUsings 保持开启。
• 包版本统一由根目录 Directory.Packages.props（CPM）管理，csproj 的 PackageReference 不写 Version。
• 异步 API 一律 ValueTask 优先；禁止 sync-over-async（.Result / .Wait()）。
• 公开 API 必须有 XML doc 注释，说明语义而不复述签名。
• 每个核心语义必须有单元测试，提交前 dotnet test 全绿。
• 新能力包按 Service Definition / Provider / Consumer 三角色评估是否拆程序集。

已知风险

热重载卸载成功率。 ALC 卸载要求没有任何活引用指向旧程序集——事件处理器、静态缓存、timer 回调都算。注册即回收纪律是唯一保障。

沙箱跨平台。 全项目唯一无法纯托管解决的部分，首版容器优先压成本。

点访问 ergonomics。 ctx.tools 式体验需要源生成器聚合 partial interface，是计划内投入，但不要提前做。

范围与进度的事实来源

README 与本站都不维护实现进度或完成清单。以 GitHub 为唯一事实来源：

• dsh 能力对齐矩阵：固定基线、能力 owner、差异与验收义务
• Milestones：版本规划
• Issues：具体工作与依赖

下一步