YYAgentCore.Tools.Shell 2.2.0

YYAgentCore

一个与 UI 无关的 .NET Agent 运行时基础库，产出 YYAgentCore.dll。

目标：把每次做 agent 工具都要重写的部分——agent 循环、API key 注入、流式解析、各阶段提示词注入、tools 框架、MCP 客户端——沉淀成一个可复用 DLL。之后新建 agent 工具时，宿主只需关心三件事：

1. UI（目标宿主：WinForms 与 Unity 2022；库为 netstandard2.0，任何 .NET 宿主可用，WebGL 除外）
2. 具体工具的实现（继承 ToolBase）
3. 装配：把 provider、工具、审批回调、钩子注入 AgentRunner，然后 await foreach 事件流刷新 UI

非目标：不做 UI 组件、不做具体业务工具（通用工具放 Tools.Builtins）、不做定时/剪贴板/截屏等系统能力；不宣称内建检索质量（RAG 以「接口 + 拼装」提供，实现可插拔）。

当前基线（2026-11-13，最近一次实测）：dotnet build YYAgentCore.slnx -c Release 0 警告 0 错误；dotnet test 1,794/1,794（net8 主工程 1,789 + net48 冒烟 5；含本轮 9 条模块装配诊断用例，见 docs/25。历史明细：1,237 基线 + 17 条数据丢失链/降级只读/损坏保护/完整性标记判别用例，见 docs/17 + 6 条 embedding 分批 + 2 条编排任务数上限 + 4 条记忆 OCE 口径 + 1 条 RagStore Dispose + 9 条归一化缓存一致性 + 2 条召回读不等待写锁 + 2 条代际恢复正确性 + 4 条生命周期/可见性 + 2 条兼容/降级边界 + 3 条复审缺口用例 + 5 条代理身份注入 + 25 条协作总线核心 + 16 条协作工具 + 11 条注入钩子 + 4 条端到端协作用例 + 43 条协作总线审查修复用例（消息不丢/输出转义/终态/限频） + 7 条子代理协作接入用例 + 3 条协作策略 + 5 条编排 presence 用例 + 27 条阶段 4 增强用例 + 22 条阶段 2-4 审查修复用例 + 8 条 Unity AI 编辑器样板用例 + 13 条 replace_in_file 判别用例 + 16 条 search_files 范围/匹配用例 + 6 条 search_files 文件模式(glob)用例 + 8 条 read_file 分页用例 + 6 条 read_image + 3 条 get_environment_info + 5 条 list_dir 递归/排除用例 + 9 条子代理审查修复用例（编码保留/非 UTF-8 拒绝、混合换行拒绝、offset=0 分页、UTF-16 二进制判定、include 不跨目录、MaxFiles 截断提示） + 8 条第二轮动态验证修复用例（tmp 误删/整体时间预算/new_string 换行/单文件 glob/代理对截断/全文二进制/截断提示/空白工作目录） + 2 条 P2 清理用例（路径前缀大小写语义/环境信息 roots 归一化）+ 1 条真实端点复测修复用例（无参工具 schema 归一化）+ 16 条第七轮交叉审查修复用例（摘要跳过洞/并行收尾/SSE 断流计时/进程树/charset/CJK 扩展 A 区/增量槽位解析/分页 include_total/读体预算） + 154 条开箱即用架构用例（模块契约/组合根/配置解析/平台档案/预设/四项能力/复审修补，见 docs/21）+ 10 条多模型复审修补用例（白名单路径拒绝/失败回收钩子/泛型内联/预设命名参数）+ 5 条 net48 冒烟（验证 netstandard2.0 资产））。构建/测试已固化为 CI 门禁（构建与测试）。从 1.0.0 升级的宿主请先读 破坏性变更。

M1 增量（2026-11-14）：新增 YYAgentCore.Runtime.AsyncGate / AsyncKeyedLock 两个并发原语与 30 条测试；当前 dotnet build YYAgentCore.slnx -c Release 0 警告 0 错误，dotnet test 1,824/1,824（net8 1,819 + net48 5）。 M2 增量（2026-11-14）：新增 ResidentAgent / ResidentAgentRegistry 与跨轮历史回填，27 条测试；当前 dotnet build YYAgentCore.slnx -c Release 0 警告 0 错误，dotnet test 1,851/1,851（net8 1,846 + net48 5）。 M3 增量（2026-11-14）：新增 IAgentBusObserver / 空闲唤醒 / 可信发送者 / 滑窗限流，16 条测试；当前 dotnet build YYAgentCore.slnx -c Release 0 警告 0 错误，dotnet test 1,867/1,867（net8 1,862 + net48 5）。 M4 增量（2026-11-14）：异步子代理的并发准入接入 AsyncGate（名额在后台任务收尾时归还，拒绝文案逐字不变），7 条测试；当前 dotnet build YYAgentCore.slnx -c Release 0 警告 0 错误，dotnet test 1,874/1,874（net8 1,869 + net48 5）。 M5 增量（2026-11-14，发布检查）：压测与资源守恒 5 条（50 agent × 10 turn 峰值并发 = gate 8、1000 并发投递 1 接受/999 拒绝、100 次取消风暴、10k 事件洪峰丢 7,955 不阻塞 turn、日志不含 prompt）；版本升 2.2.0 并重打 UPM（26 DLL，asmdef/版本/新鲜度三重校验通过）。当前 dotnet build YYAgentCore.slnx -c Release 0 警告 0 错误，dotnet test 1,879/1,879（net8 1,874 + net48 5）。

能力矩阵

快速开始

using System;
using System.Collections.Generic;
using System.Threading;
using YYAgentCore.Contracts;
using YYAgentCore.Engine;
using YYAgentCore.Providers;
using YYAgentCore.Security;
using YYAgentCore.Tools;
using YYAgentCore.Tools.Builtins;

var tools = new ToolRegistry();
tools.Register(new GetCurrentTimeTool());

var provider = new OpenAiCompatibleProvider(new OpenAiCompatibleOptions
{
    BaseUrl = "https://api.deepseek.com",          // 支持 /、/v1、/chat/completions 三形态
    Keys = new EnvironmentKeySource("deepseek", "DEEPSEEK_API_KEY"),
    ServiceName = "deepseek",
    DefaultModel = "deepseek-chat",
});

var deps = new AgentDependencies(Provider: provider, Tools: tools);
var runner = new AgentRunner(deps, new AgentOptions { MaxRounds = 25 });

// history 由宿主持有：每轮成功后按事件回填，引擎内部会克隆，不改你的列表
var history = new List<ChatMessage>
{
    new ChatMessage(ChatRole.User, new List<ContentPart> { new TextPart("现在几点了？") }),
};

await foreach (var evt in runner.RunAsync(history, CancellationToken.None))
{
    switch (evt)
    {
        case AssistantTextDelta d:      Console.Write(d.Text); break;
        case ToolExecutionFinished f:   Console.WriteLine("\n[tool] " + f.ToolName + " → " + f.Outcome.Result.Output); break;
        case ApprovalSkipped s:         Console.WriteLine("\n[audit] 破坏性工具未经审批执行：" + s.ToolName); break;
        case RunFinished:               Console.WriteLine(); break;
        case RunFailed f:               Console.WriteLine("失败：" + f.Error.Message); break;
    }
}

要点：一个会话不必一个 AgentRunner（Runner 无全局状态，可每次 new；并发多会话各自持 history 与 CancellationTokenSource）；provider 与 registry 可整个程序复用；provider 实现 IDisposable，宿主销毁时应释放。完整模板（含 WinForms/Unity 事件映射、审批弹窗、MCP、会话恢复）见 宿主接入指南。

破坏性变更（必须知晓）

2026-10-23：审批语义从「声明即强制」改为「声明 + 宿主决定」（ApprovalMode 默认 Advisory，见 docs/16 §9.13；决策记录见 ADR 2026-10-23 审批模式）：

受影响的典型工具：forget、write_file/move/trash、MCP 中配置为 confirm 的工具、子代理（默认继承父 run 的模式）。未消费 ApprovalSkipped 的宿主，破坏性工具会静默执行——建议审计事件至少落日志。

2.0.0 起（2026-11-04）：ShellModule / RunCommandTool 在构造时拒绝落在可写工作区内的白名单命令路径（ArgumentException）。旧配置若写过 allowedCommands: ["<工作区>/bin/tool.exe"]，升级后装配会直接失败——因为模型可以用文件工具覆盖那个 exe，精确路径白名单反而比裸名更危险。迁移：把该程序装到工作区之外，或改用裸名（PATH 搜索会自动排除可写区）。

其他破坏性变更：Orchestration 公开 API 由整包依赖改为端口注入（IOrchestrationAgentPort，ADR），包间已零 ProjectReference。

当前状态

宿主矩阵

架构与包边界

Contracts/            消息 / provider / tool / engine / knowledge / embedding / vector 抽象
   ↑
Engine/AgentRunner    主循环（唯一「知道一切」的地方）
   ↑
Providers/ Streaming/ Tools/ Mcp/ Sessions/ Security/ Context/ Prompts/ Vector/
   ↑
可选包：Subagents / Orchestration / Rag / Memory / Tools.Builtins（只依赖核心）

扩展包边界规则（ADR 2026-10-21、02 §3.1）：

• R1 核心只定义「引擎要调用」的接口；
• R2 被 ≥2 个包共用的轻契约可进核心（命中 IEmbeddingProvider / IVectorIndex）；
• R3 包间协作一律端口注入，禁止 ProjectReference 包间引用。

代价：跨包组合（如「编排 × 子代理」）需要端口适配。生产适配器已提供：YYAgentCore.Presets.Team 的 SubagentAgentPort（公开类型，见 docs/25）；偏好自己实现的宿主也可以写约 90–120 行适配代码。核心库只依赖 4 个 NuGet 包（见文末），能力包之间依赖为零（Presets.* / Hosting.* 属组合层，按 R5 允许引用能力包）。

项目结构

src/YYAgentCore/                  核心库（netstandard2.0；含 Modules 装配契约）
src/YYAgentCore.Hosting/          组合根（Builder / 配置解析 / 平台档案 / 装配流程）
src/YYAgentCore.Hosting.Windows/  Windows 平台档案（DPAPI 探测、Process）
src/YYAgentCore.Hosting.Unity/    Unity 平台档案（persistentDataPath、主线程调度）
src/YYAgentCore.Tools.Builtins/   通用工具（含 todo_write）
src/YYAgentCore.Tools.Shell/      命令执行（白名单 + 命令解析 + 进程树收尾）
src/YYAgentCore.Tools.Web/        网页搜索（provider 抽象 + Tavily 实现）
src/YYAgentCore.Skills/           技能包（Markdown 目录 + 按需加载）
src/YYAgentCore.Subagents/        子代理（delegate_task）
src/YYAgentCore.Orchestration/    团队编排（orchestrate）
src/YYAgentCore.Rag/              检索扩展包
src/YYAgentCore.Memory/           长期记忆
src/YYAgentCore.Presets.Chat/     预设：纯对话
src/YYAgentCore.Presets.Coding/   预设：编码助手（文件 + 记忆 + RAG）
src/YYAgentCore.Presets.Team/     预设：多代理协作（含 IOrchestrationAgentPort 生产适配器）
src/YYAgentCore.Demo.Console/     控制台宿主（含 --kb-check / --compact-check / --memory-check 测量模式）
src/YYAgentCore.Demo.WinForms/    WinForms 验收宿主
tests/YYAgentCore.Tests/          xUnit 测试（net8.0，1,874 用例）
tests/YYAgentCore.Tests.Net48/    xUnit 冒烟（net48，5 用例；验证 netstandard2.0 资产）
tests/TestAssets/                 MCP 测试 server、真实 DeepSeek SSE 方言样本
samples/UnityEditorAssistant/      Unity AI 编辑器接入样板（Runtime 宿主逻辑 + Unity 2022.3 工程 + 批处理冒烟）
unity-smoke/                      Unity 2022 冒烟工程（独立，不进 sln）
docs/                             设计、规格、审查、实证（见下）
YYAgentCore.slnx                  解决方案（需 .NET SDK 9.0+）

文档导航

必读（新读者从这里开始）

能力规格

实证与测量记录

审查、验收与 ADR

文档是「写作时刻的快照 + as-built 追加」：每篇的状态行只反映其写作时点，当前基线与破坏性变更以本 README 为准。历史文档中与现状冲突的陈述以对应 ADR 为准。

构建与测试

pwsh scripts/ci.ps1              # 构建 + 全量测试 + 覆盖率门槛(与 CI 同一入口)
pwsh scripts/ci.ps1 -SkipCoverage # 只跑测试(本地快速迭代)
# 等价展开：
dotnet build YYAgentCore.slnx -c Release    # TreatWarningsAsErrors 全局开启 → 构建通过即 0 警告
dotnet test  tests/YYAgentCore.Tests/YYAgentCore.Tests.csproj -c Release ^
  --collect "XPlat Code Coverage" --settings tests/YYAgentCore.Tests/coverlet.runsettings ^
  --results-directory artifacts/coverage
pwsh scripts/coverage.ps1        # 解析 Cobertura 报告并校验行覆盖率 ≥ 80%

• SDK 由 global.json 锁定为 9.0.312（rollForward: latestFeature）：避开 .NET 10 SDK 在本类环境的 workload 解析问题，并保证本地与 CI 使用同一编译器（不同 SDK 的警告集合不一致，例如 CS1998 只在 SDK 9 下暴露）。
• CI：.github/workflows/ci.yml 在 Windows runner 上执行同样的构建 + 测试；仓库主站是 Gitee（不执行 GitHub Actions），Gitee Go / Jenkins 只需一个脚本任务跑 pwsh scripts/ci.ps1，失败即非 0 退出码。
• 覆盖率门槛：行覆盖率 ≥ 80%（当前基线 87.48%，2026-10-23 实测）。coverlet.collector 收集，coverlet.runsettings 按文件路径排除 Demo 示例工程与测试工程源码；scripts/coverage.ps1 逐程序集输出并以非 0 退出码拦截低于阈值的构建。反证：阈值临时设 99% 时 coverage.ps1 与 ci.ps1 均以 exit code 1 失败。
• 需要 .NET 8 运行时（测试与 Demo 目标 net8.0/net8.0-windows）。
• 两个测试工程，覆盖两条 TFM 解析路径：
  • tests/YYAgentCore.Tests（net8.0）—— net8.0 对 netstandard2.1 兼容性更优，MSBuild 永远选 2.1 资产；
  • tests/YYAgentCore.Tests.Net48（net48）—— 不支持 2.1，只能拿 lib/netstandard2.0， 用 TargetFrameworkAttribute 断言"确实加载了 2.0 资产"。缺了它，2.0 产物的运行时差异不在回归网内。
• 部分 MCP 测试会启动真实 Node 子进程（tests/TestAssets/*.mjs），本机需安装 Node。
• Unity 侧有两个独立工程：unity-smoke/（历史 DLL 方式，见 unity-smoke-notes）与 upm-smoke/（UPM 包 + IL2CPP 实测，见 docs/22）。均不进 sln。

依赖

发布与许可

• NuGet 已发布：dotnet add package YYAgentCore --version 2.1.0（2026-11-13 发布 15 个包 + 15 个符号包；NuGet 页面）。2.0.0 是首个对外版本（2026-11-13）。Unity 走 UPM 包或拷贝 DLL（见 宿主接入指南 §1.1、docs/22）；15 个库包统一版本，后续按语义化版本同步升级。
• 打包：dotnet pack YYAgentCore.slnx -c Release -o artifacts/nuget 产出 15 个库包 + 15 个符号包（核心 + 5 个能力包 + 3 个 Hosting/平台包 + 3 个预设包 + Skills/Shell/Web）。发布用 scripts/publish-nuget.ps1（先 -WhatIf 演练）。包内含 README、XML 文档、MIT 许可证表达式、projectUrl/repository（含构建时的 commit）；能力包（Builtins/Subagents/Orchestration/Rag/Memory/Skills/Shell/Web）只依赖核心库、彼此零引用；Hosting 依赖核心；Presets.* 按 R5 允许引用多个能力包（这正是它存在的意义），Presets.Team 的依赖闭包最深（Hosting + Coding + Subagents + Orchestration）。
• 许可证：MIT（LICENSE）——允许商用与闭源再分发，仅需保留版权声明。
• 版本政策：ADR 2026-10-23 兼容性政策 + ADR 2026-10-24 首发版本——1.0.0 是内部验收版本（未对外分发，v1.0.0 tag 保留），2.0.0 是首个对外发布版本，SemVer 自 2.0.0 起算：默认值/语义反转按 major，破坏性变更须 ! 提交 + README 迁移路径 + 包版本同步。
• 变更记录：CHANGELOG.md。