Ensemble 是依据 Bill Cox 的可执行教学书《The Art of Building AI Coding Agents》构建的编码智能体。当前版本为第 3 版：应用采用 C# 14 / .NET 10，并在 Ensemble 内部借助 Cadence 开发。代码与规范同步构建。开发过程本身赢得规范。目标不是先写一份详尽计划再交给 AI，也不是凭感觉写出一套系统、事后再补文档。目标是借助与 AI 结对编程成长为专家，再把这份专业知识以另一个智能体可以执行的形式保存下来。

最终产物是一份可执行规范：一本代码手册，传递构建该系统所需的判断力，而不只是一份期望功能清单。Ensemble V2 执行本书构建出 V3；随后 Bill 与 Cadence 在 V3 内部继续工作，同时改进智能体与教学内容。各章节保留其已记录的验证边界。

人的专业能力在开发过程中增长，而不是依赖最后检查自己不熟悉的生成代码。代码只是产出；可复用的资产是能够再次构建它的知识。不要只记录要构建什么，要教会如何以及为何这样构建。这些不可能一开始就全部学会。请阅读本书、章节指南或汇编手稿。当前应用源码与人类伴侣。保留的章节解答。晋升与验证，实现证据。冻结历史：第 1 版与第 2 版，各自包含其书、源码与评分器。

构建与运行 使用已有的 .NET 10 SDK（仅有运行时无法构建应用）。此处不会安装 SDK、不会为构建读取凭据、不会自动启动服务器，也不会替换已安装的应用。首先检查你的 shell 能否找到 SDK： dotnet --list-sdks # 应包含 10.x SDK 如果找不到 dotnet，或 make 报告 dotnet: No such file or directory，说明构建尚未进入编译阶段：SDK 可执行文件不在你 shell 的 PATH 中。如果你已安装 SDK，要么把其目录加入当前 shell 的 PATH（将示例路径替换为你的实际 SDK 目录）： export PATH="/absolute/path/to/dotnet-sdk:$PATH" dotnet --list-sdks 要么保持 PATH 不变，把可执行文件的完整路径交给 Make： make DOTNET=/absolute/path/to/dotnet make cli DOTNET=/absolute/path/to/dotnet

对其他目标使用同样的覆盖方式，例如 make test。

例如，如果你把 SDK 安装在 $HOME/.local/share/ensemble-dotnet10，则使用 make DOTNET="$HOME/.local/share/ensemble-dotnet10/dotnet"。这只是示例位置，并非必需布局。如果未安装 .NET 10 SDK，请从 Microsoft 的 .NET 10 下载页安装，然后打开新终端再次检查。 make # 构建 C# GUI 并写出 ./ensemble 启动器 make cli # 构建 C# 终端客户端 ./ensemble --help # 显式启动；使用前先查看选项

make cli 之后的终端客户端：

dotnet agent/Cli/bin/Debug/net10.0/ch04.dll --help 如果你改用显式 SDK 覆盖，启动终端客户端时也要用该完整可执行路径代替 dotnet。

真实启动时，请自行选择数据目录、工作区、资金配置和未使用端口。不要为了刷新源码而替换正在运行的主机。GUI 在构建时内嵌其资源。应用行为与合格测试证据见 crossover 章节和源码 README。

make test 运行 C# 回归可执行程序与根目录 Go 工具测试；make test-go 只测试后者。Go 保留在根目录用于可复用评分器、本地假 provider 和发布工具——不再是活动运行时。

使用各章节已记录的可执行命令与范围。C# 不得送给 Go 源码消费者评分器。例如，第 5 章记录了显式的 grade-edition3 -ch 5 -executable-only 路线及其 65 个限定分值。 make grade CH=5 DIR=/path/to/CLI-wrapper GRADEFLAGS='-executable-only ...' 需要显式目标，并转发到该 Edition 3 命令。可执行评分器编号与保留的 chNN 快照保持其原始含义；章节映射解释了后续手稿重新编号。历史 Edition 2 评分可从 edition-2/ 运行；Edition 1 保留在 edition-1/。两个归档都不会为当前布局而重写。

make book 汇编当前手稿；make ebook 构建其 EPUB；make print 构建其印刷版与阅读版 PDF。这些使用现有本地发布工具，绝不安装它们。前置条件与隔离输出见书籍构建说明。生成的出版物与源码编辑不同；仅做源码晋升并不会发布新书或上传。

Puffin 书是 Gateway、Connections、Agenda、Puffin 及相关 Watchtower/安全工作的当前工作家园。其笔记遵循 Development-Driven Specs；大纲是暂定的，不是已完成的功能。编码智能体书仍位于 book/ 下。