新增能力包手册

本手册详细说明如何在 Tether 代码库中新建一组符合规范的能力程序集。遵循本规范建立的包可无缝接入 Tether 的 YAML 加载器、依赖注入图与生命周期管理系统。

目录与项目规划

假设我们要新增一项名为 Database 的能力，标准的项目结构如下：

src/
├── Tether.Database/          # Seam：纯接口与数据模型（零依赖）
│   └── Tether.Database.csproj
├── Tether.Database.Local/    # Provider：本地/默认实现（依赖 Cordis + Tether.Database）
│   └── Tether.Database.Local.csproj
└── Tether.Database.Tools/    # Tools：大模型工具暴露（依赖 Contracts + Cordis + Tether.Database）
    └── Tether.Database.Tools.csproj
tests/
└── Tether.Database.Tests/    # 单元测试（镜像对应）
    └── Tether.Database.Tests.csproj

1. 创建 Seam 程序集

编辑 src/Tether.Database/Tether.Database.csproj：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

2. 创建 Provider 程序集

编辑 src/Tether.Database.Local/Tether.Database.Local.csproj：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\src\Cordis\Cordis.csproj" />
    <ProjectReference Include="..\Tether.Database\Tether.Database.csproj" />
    <ProjectReference Include="..\Tether.Invariants\Tether.Invariants.csproj" />
  </ItemGroup>
</Project>

编写插件挂载类：

using Cordis;

namespace Tether.Database.Local;

public sealed class DatabaseLocalPlugin : Plugin
{
    protected override void Apply(Context context)
    {
        IDatabaseService service = new LocalDatabaseService();
        context.Provide(service);
    }
}

3. 创建 Tools 程序集

编辑 src/Tether.Database.Tools/Tether.Database.Tools.csproj：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\..\src\Cordis\Cordis.csproj" />
    <ProjectReference Include="..\Tether.Core.Contracts\Tether.Core.Contracts.csproj" />
    <ProjectReference Include="..\Tether.Database\Tether.Database.csproj" />
    <ProjectReference Include="..\Tether.Invariants\Tether.Invariants.csproj" />
  </ItemGroup>
</Project>

编写 Tool 注册插件（使用 [Inject] 声明依赖）：

using Cordis;
using Microsoft.Extensions.AI;
using Tether.Core;

namespace Tether.Database.Tools;

[Inject(typeof(IDatabaseService))]
[Inject(typeof(IToolRegistry))]
public sealed class DatabaseToolsPlugin : Plugin
{
    protected override void Apply(Context context)
    {
        var db = context.Require<IDatabaseService>();
        var tools = context.Require<IToolRegistry>();

        var queryTool = AIFunctionFactory.Create(
            (string sql) => db.ExecuteQueryAsync(sql),
            name: "db_query",
            description: "执行只读 SQL 查询并返回结果表");

        context.Effect(tools.Register(queryTool).Dispose);
    }
}

4. 添加到解决方案并运行测试

在根目录下将新建的项目加入解决方案：

dotnet sln Tether.slnx add src/Tether.Database/Tether.Database.csproj
dotnet sln Tether.slnx add src/Tether.Database.Local/Tether.Database.Local.csproj
dotnet sln Tether.slnx add src/Tether.Database.Tools/Tether.Database.Tools.csproj
dotnet sln Tether.slnx add tests/Tether.Database.Tests/Tether.Database.Tests.csproj

# 运行构建与全量测试
dotnet test Tether.slnx

质量与工程检查清单

• Seam 程序集保持零项目依赖。
• 异步接口一律返回 ValueTask 或 ValueTask<T>。
• 每一个公开的 API 都包含清晰的 XML 注释。
• 通过 tools.Register 拿到的 IDisposable 都以 context.Effect(registration.Dispose) 挂上作用域（context.Provide 返回的服务注册本身已绑定作用域，不需要再挂）。
• 测试项目镜像对应并在 dotnet test 中全部通过。

下一步