开发指南 on AGW

开发环境与运行

Fri, 25 Sep 2026 00:00:00 +0000

前提：.NET 10 SDK、Node.js 24、pnpm 12.5.1（版本由 src/clients/package.json 的 packageManager 指定）和 Git。只有构建容器镜像时才需要 Docker Buildx。以下应用命令在 AGW 仓库执行，文档站本身不依赖这些工具链。

架构与模块边界

Fri, 25 Sep 2026 00:00:00 +0000

本页帮助开发者判断一项改动应放在哪个模块、哪一层。AGW 按业务拆分代码，例如 Agents、Projects 和 Jobs；它们可以共享一个部署进程和数据库，但各自负责自己的数据和操作。

API 与执行协议

Fri, 25 Sep 2026 00:00:00 +0000

AGW 的管理操作和任务执行使用不同接口。创建或查询配置使用普通 HTTP JSON API；持续接收 Agent 回复和状态使用 SignalR 执行连接；对接其他 Agent 系统时可以使用 A2A。

接入前，先准备可访问的开发 Server 和有效的认证身份，例如 API Key 或浏览器登录会话。具体参数以运行实例的 OpenAPI 及所属模块 Contracts 中的类型定义为准，避免照抄与运行版本不一致的请求。

扩展 Tools 与 Integrations

Fri, 25 Sep 2026 00:00:00 +0000

扩展前先确定要增加什么：一个具体操作可以写成 Tool，一组任务说明和专属工具可以通过 Skill 提供，需要用户连接外部账号的能力则适合 Integration。

先阅读模块边界，确认能力由哪个模块负责。本页说明放置代码、注册能力和验证调用的顺序；具体声明写法可参考文末的工具示例。

工具扩展路径

手写的 IAgwTool、IContextualTool 和 IToolBlock 实现放在 Agw.Tools，全局目录只扫描这个程序集中的手写工具。业务工具放在所属模块的 Application/Tools，以 Attribute 容器声明或通过 Skill 提供，DTO 放 Contracts/Tools。
引用 Agw.Tools.Abstractions，需要 Attribute 声明时将 Agw.Tools.Generators 作为 Analyzer 引用。
显式声明权限、参数说明和返回类型。独立工具及使用 Attribute 声明的工具容器不能保存会话状态；状态放在 Provider、会话对象或所属存储中。
在所属模块注册所需服务与生成声明。选择通过 Skill 提供，或显式加入全局目录。
验证工具发现、参数、权限、项目绑定和错误映射。

生成器输出元数据、JSON Schema 和直接调用委托。不要加入运行时反射扫描兜底。Skill 工具有两个来源：IAgentSkillRegistration.Tools 提供手写的 IProjectScopedAgwTool 实例，ToolTypes 提供 Attribute 容器类型（由 IAgwToolSet<T> 生成）。它们在执行时绑定 Project，不因注册生成模块就自动进入全局目录。

测试与贡献约定

Fri, 25 Sep 2026 00:00:00 +0000

前提：依赖已安装。修改前阅读根目录 AGENTS.md 和 docs/human/ 中的相关规则，保留无关的本地改动。

后端检查

从仓库根运行：

dotnet build Agw.slnx
dotnet test Agw.slnx
dotnet csharpier check .

测试项目使用 xUnit v3，并通过根目录 global.json 使用 Microsoft.Testing.Platform 运行。定位问题时先运行相关测试，例如 dotnet test tests/Agw.Files.Tests。单元和组合测试使用真实实现和纯选项辅助方法，不使用 mock 或 fake 实现。构造 CodexAIAgent 或 ClaudeCodeAIAgent 时会探测 CLI，这类测试作为真实 CLI 测试运行，需要显式启用并确认可执行文件可用，不放进默认测试套件。