目录
引子
Inkwell 是什么
为什么要做这个
后端怎么落 MAF
现在到哪一步了
想看看的话
引子
Microsoft Agent Framework 是微软官方开源的 Agent 框架：AIAgent把模型调用、工具、记忆、多轮对话统一成一套抽象；Workflows 能编排确定性的多智能体协作；DurableTask 让长跑任务的状态可持久化，进程重启也能接着跑；再加上结构化输出、MCP 工具集成、Agent Skills 等等等等一系列能力，官方文档和示例把这些能力一个个讲得很清楚。
但"每个能力单独看清楚"和"拼成一个能落地的真实产品"之间还有一段距离——要给团队部署、给个人自托管，要扛住多用户多会话、还能自己持续迭代，中间会遇到什么问题，光看官方示例看不出来，得自己拿真实项目走一遍才知道。
Inkwell 就是我拿来做这件事的项目：一边把 Agent 平台从头搭到能用，一边在真实约束下探索 MAF 的最佳实践。
Inkwell 是什么
Inkwell 是一个建在 Microsoft Agent Framework 之上的智能体工作空间：自助创建、配置、发布、版本化 LLM Agent，统一接入不同模型，用桌面客户端和 Agent 对话。团队可以把它部署给内部成员协作，个人或 OPC（一人公司）也能自己部署自己用。
项目地址：https://github.com/shuaihuadu/inkwell
现在只是实现了能跑起来，目前已经能跑起来的部分如下：
Agent 创建、完整配置、草稿保存与试运行
Agent 发布、版本历史、团队共享与复制
LiteLLM 模型发现、模型管理与基础对话
Agent Skills 管理与只读工具目录
用户账号管理与密码修改
Aspire 本地编排，支持 PostgreSQL / SQL Server 双数据库
还在做的：Agent 版本回滚的桌面操作与更完整的协作治理、知识库、长期记忆、多模态、调试与评测、对外协议兼容与生产部署。
为什么要做这个
做 Inkwell 有两个目的：一是想要一个自己真能落地用的 Agent 平台，不是一次性 demo；二是想认真探索一遍 MAF 的最佳实践——光看文档和官方示例不够，只有拿真实项目里"多用户、多数据库 Provider、多模型网关"这些真实约束去逼一遍，才知道 MAF 的抽象在哪些地方好用，在哪些地方需要自己补一层。
Inkwell 从需求到架构到详细设计再到编码，每一步我都要求自己先写清楚文档、经过评审才能往下走，不允许直接跳到写代码。这套流程慢一些，但换来的是每个技术决策都能追溯到具体的需求和取舍理由，而不是"当时就是这么写的"。
后端怎么落 MAF
Inkwell 后端是 .NET 10 + ASP.NET Core 10，Agent 引擎直接用 MAF 的Microsoft.Agents.AI/.AGUI/.Workflows/.DurableTask几个包。几个和"纯示例写法"不一样的地方：
Agent 装配走 MAF 原生入口：不自己包一层
IAgentRuntimefacade，直接用IAgentFactory.BuildAgentAsync(...)。业务层只负责校验ModelId是否属于 Chat 类别，再通过IChatLLMProvider拿到统一的IChatClient去构建AIAgent，真正的调用交给 MAF。模型不是配置文件里写死的列表：模型网关用 LiteLLM Proxy，LiteLLM Portal 是模型与路由唯一的事实源。Inkwell 通过
ILLMProvider实时发现 Portal 里配置好的模型，自己不持有任何模型厂商的凭据，只持有 LiteLLM 内部地址和网关 Key。README 里"启动后先登录 LiteLLM Portal 添加模型"这一步就是这么来的。协议走 REST + AG-UI：客户端和后端之间没有自建 WebSocket / SignalR，流式交互直接用
@ag-ui/client对接 AG-UI Protocol 的 SSE 端点。持久化和基础设施全走 Provider 抽象：
IPersistenceProvider（EF Core，SQL Server / PostgreSQL 双实现）、ICacheProvider（Redis）、IFileStorageProvider（Local / MinIO / AzureBlob）、IQueueProvider（Channels 本地 / Redis Stream 生产）。业务代码只认接口，换 Provider 不改业务层一行代码——这条约束在架构评审阶段就锁死了：后端按 Ports & Adapters 分了 19 个 csproj，业务命名空间被 CI 的 Roslyn analyzer 挡着，不能直接using任何具体 SDK。
这些选择大多不是为了炫技，而是被"要真的能部署、能换基础设施"这个目标逼出来的——回到前面那句：光看文档看不出这些约束，做一遍才知道。
现在到哪一步了
Inkwell 走的是需求 → 架构 → 详细设计 → 测试设计 → 编码 → 发布这样的阶段划分，每个阶段都要有文档产出、经过评审才能进入下一阶段。目前架构阶段已经评审通过，正准备进详细设计——也就是说"要用什么、不用什么"已经拍板，接下来是把每个模块的接口、数据结构和调用链写清楚，再进编码。
想看看的话
本地跑起来需要 .NET 10 SDK 和 Docker Desktop：
git clone https://github.com/shuaihuadu/inkwell.git cd inkwell dotnet user-secrets --project src/core/Inkwell.AppHost set "Parameters:litellm-master-key" "<local-litellm-key>" dotnet run --project src/core/Inkwell.AppHost跑起来后先去 LiteLLM Portal（http://localhost:6804/ui）登录、添加模型和供应商凭据，Inkwell 才能发现可用模型；默认管理员账号密码都是admin，首次登录要改密码。Aspire Dashboard（https://localhost:15888）能看到本地所有服务的状态。
Inkwell 项目地址：https://github.com/shuaihuadu/inkwell
Microsoft Agent Framework 官方项目地址：https://github.com/microsoft/agent-framework
引入地址
