AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

综合项目：交付一个可复用的 Agent 工作台包 ​

这个小专题以一个你能丢进任何仓库的包收尾。十一课的接触面压缩进一个你能 cp -r、然后第二天早上就有一个可靠工作的 agent 的目录。综合项目就是这门课程赖以立足的产物。

类型： Build 语言： Python（标准库） 前置要求： 阶段 14 · 31 到 14 · 41 预计时间： ~75 分钟

学习目标 ​

  • 把七个工作台接触面打包进一个即插即用目录。
  • 钉住 schema、脚本和模板，让新仓库拿到一个已知良好的基线。
  • 加一个幂等地铺下这个包的单一安装脚本。
  • 决定什么留在包里、什么留在外面，为每个取舍辩护。

问题背景 ​

一个住在 Google Doc、一段聊天历史和三个半记得的脚本里的工作台，是个每个季度都要重建的工作台。解药是一个带版本的包：一个带接触面、schema、脚本和单命令安装器的仓库或目录。

你将以磁盘上交付的 outputs/agent-workbench-pack/ 和一个把它丢进任意目标仓库的 bin/install.sh 来结束这一课。

核心概念 ​

mermaid
flowchart TD
  Pack[agent-workbench-pack/] --> Docs[AGENTS.md + docs/]
  Pack --> Schemas[schemas/]
  Pack --> Scripts[scripts/]
  Pack --> Bin[bin/install.sh]
  Bin --> Repo[目标仓库]
  Repo --> Surfaces[七个工作台接触面全部接好]

包布局 ​

outputs/agent-workbench-pack/
├── AGENTS.md
├── docs/
│   ├── agent-rules.md
│   ├── reliability-policy.md
│   ├── handoff-protocol.md
│   └── reviewer-rubric.md
├── schemas/
│   ├── agent_state.schema.json
│   ├── task_board.schema.json
│   └── scope_contract.schema.json
├── scripts/
│   ├── init_agent.py
│   ├── run_with_feedback.py
│   ├── verify_agent.py
│   └── generate_handoff.py
├── bin/
│   └── install.sh
└── README.md

什么留在里面、什么留在外面 ​

里面：

  • 接触面 schema。它们是契约。
  • 上面四个脚本。它们是运行时。
  • 四份文档。它们是规则和评分标准。

外面：

  • 项目专属任务。任务属于目标仓库的看板，不属于包。
  • 厂商 SDK 调用。包是框架无关的。
  • 入职散文。包住在团队现有入职文档旁边，不在它里面。

安装器 ​

一个简短的 bin/install.sh（或 bin/install.py）：

  1. 没有 --force 时拒绝覆盖一个现有包。
  2. 把包复制进目标仓库。
  3. 如果存在 .github/workflows/ 就接好 CI。
  4. 打印下一步：填看板、设验收命令、跑 init 脚本。

版本管理 ​

包带一个 VERSION 文件。需要迁移的 schema 升级和脚本变更升主版本号。仅文档的变更升补丁号。目标仓库的 agent_state.json 记录它是对着哪个包版本初始化的。

figure
wb-pack-install

动手构建 ​

code/main.py 把包组装进课旁边的 outputs/agent-workbench-pack/，用这个小专题之前各课的 schema 和脚本以及你已经写好的文档播种。

运行它：

python3 code/main.py

脚本复制并钉住接触面、写 README、打印包目录树，以零退出。重跑是幂等的。

野外的生产模式 ​

一个包只有挺过 fork、更新和一个不友好的上游才有价值。四个模式让这行得通。

VERSION 是契约，不是营销。 主版本升级需要一次状态迁移。次版本升级需要一次检查器重跑。补丁升级只动文档。安装器在每次安装时把 .workbench-version 写进目标仓库；lint_pack.py 在目标的锁与包的 VERSION 不一致时拒绝交付。这就是 npm、Cargo 和 pyproject.toml 挺过十年动荡的办法；关于 agent 的一切都没改变规则。

跨工具分发的单一源。 Nx 提供一个 nx ai-setup，从单一配置铺下 AGENTS.md、CLAUDE.md、.cursor/rules/、.github/copilot-instructions.md 和一个 MCP 服务器。包应该做同样的事；安装器产出符号链接（ln -s AGENTS.md CLAUDE.md），让单一真相源扇出到每个编码 agent。为了支持某个工具而非另一个去 fork 包是个失败模式。

在非平凡状态上拒绝的 uninstall.sh。 卸载包绝不能删掉用户的 agent_state.json、task_board.json 或 outputs/。卸载器移除 schema、脚本、文档和 AGENTS.md（带 --keep-agents-md 退出选项），并在状态文件有任何未提交变更时拒绝继续。状态属于用户；包不拥有它。

skill 可发布。SkillKit 式分发。 包作为一个 SkillKit skill 交付：skillkit install agent-workbench-pack 从单一源把它铺到 32 个 AI agent 上。包仓库是真相源；SkillKit 是分发渠道。厂商锁定坍缩；七个接触面保持不变。

实际使用 ​

包交付的三个地方：

  • 作为一个你丢进仓库的目录。 cp -r outputs/agent-workbench-pack /path/to/repo。
  • 作为一个公开模板仓库。 fork 后定制，用 VERSION 控制漂移。
  • 作为一个 SkillKit skill。 接进你的 agent 产品，让单个命令把它铺下。

包是食谱。每次安装是一份上桌的菜。

拿去用 ​

outputs/skill-workbench-pack.md 生成一个项目调过的包：规则按团队历史锐化、范围 glob 匹配仓库、评分标准维度扩展一个领域专属条目。

练习 ​

  1. 决定哪个可选的第五份文档值得被提升进规范的包。为这个取舍辩护。
  2. 把安装器重写成带 --dry-run 标志的 Python。对比它与 bash 的人体工学。
  3. 加一个 bin/uninstall.sh，安全移除包，并在状态文件有非平凡历史时拒绝。什么算非平凡？
  4. 加一个 lint_pack.py，当包偏离 VERSION 时失败。把它接进包自己仓库的 CI。
  5. 撰写从一个手搓工作台迁移到这个包的操作手册。最小化停机的操作顺序是什么？

关键术语 ​

术语大家怎么说它实际是什么
Workbench pack「starter kit」一个承载所有七个接触面的带版本目录
Installer「setup 脚本」幂等铺下包的 bin/install.sh
Pack version「VERSION」schema/脚本变更升主版本，仅文档升补丁
Drop-in pack「cp -r 就走」包第一天就无需每仓库定制就能工作
Forkable template「GitHub 模板」GitHub 的「Use this template」能从中克隆的公开仓库

延伸阅读 ​