毕业项目:交付一个可复用的 Agent 工作台包

毕业项目:交付一个可复用的 Agent 工作台包

本节摘要:工作台小专题(第 31~41 节)以一个你能丢进任何仓库的包(pack)收尾。十一节关于「面」的课,压缩进一个你能 cp -r、第二天早上就让 Agent 可靠干活的目录。这个毕业项目,是本教程拿来立足的工件。诊断很直接:一个活在 Google Doc、聊天历史、三个半记得的脚本里的工作台,是每季度都要重建的工作台。解药是一个版本化的包:一个带面、模式、脚本、一条命令安装器的仓库或目录。本节结束时,你会在盘上交付 outputs/agent-workbench-pack/ 和一个能把它丢进任何目标仓库的 bin/install.sh。包的布局是七面的物化:AGENTS.md 路由 + docs/(agent-rules/reliability-policy/handoff-protocol/reviewer-rubric)+ schemas/(agent_state/task_board/scope_contract 三模式)+ scripts/(init_agent/run_with_feedback/verify_agent/generate_handoff 四脚本)+ bin/install.sh。本节明确什么进包什么不进:进——面模式(契约)、四脚本(运行时)、四文档(规则与量表);不进——项目特定任务(属目标仓的板)、厂商 SDK 调用(包框架无关)、入职散文(活在团队已有入职旁非其内)。安装器幂等(拒覆盖无 --force、复制包、接 CI、打印下一步),版本化(VERSION 文件:模式/脚本变更升 major、纯文档升 patch,目标仓 agent_state.json 记初始化时的包版本)。本节还给出四条让包挺过 fork、更新、不友好上游的生产模式:VERSION 是契约非营销(同 npm/Cargo/pyproject 挺过十年 churn)、跨工具分发的单一源(Nx nx ai-setup + 符号链接扇出)、uninstall.sh 在非平凡状态上拒绝(状态属用户,包不拥有)、Skill-as-publishable(SkillKit 式分发,32 个 AI Agent 单源安装)。读完本节,你拥有一个能跨仓库、跨工具、跨团队复用的工程级 Agent 工作台包——第 15 章 42 节的全部积累,落成一个可交付产物。

对应原课程:Phase 14 · Lesson 42 · agent-workbench-capstone(原英文 phases/14-agent-engineering/42-agent-workbench-capstone/docs/en.md)。前置:第 31~41 节。本节为第 15 章毕业项目。

学习目标

阅读完本节,你应当能够:

1. 把七个工作台面打包进一个即插即用目录。
2. 钉死模式、脚本、模板,让新仓拿到已知良好基线。
3. 加一个幂等地铺设包的单一安装器。
4. 决定什么进包、什么留外,并为每个取舍辩护。
5. 说出四条让包挺过 fork、更新、不友好上游的生产模式。

一、问题与直觉

一个活在 Google Doc、聊天历史、三个半记得的脚本里的工作台,是每季度都要重建的工作台。解药是一个版本化的包:一个带面、模式、脚本、一条命令安装器的仓库或目录。

你将在本节结束时,在盘上交付 outputs/agent-workbench-pack/ 和一个能把它丢进任何目标仓库的 bin/install.sh。

包的布局

outputs/agent-workbench-pack/
├── AGENTS.md
├── docs/
│   ├── agent-rules.md          # 五类规则(第 33 节)
│   ├── reliability-policy.md   # 可靠性策略
│   ├── handoff-protocol.md     # 交接协议(第 40 节)
│   └── reviewer-rubric.md      # 审查者量表(第 39 节)
├── schemas/
│   ├── agent_state.schema.json   # 状态契约(第 34 节)
│   ├── task_board.schema.json    # 任务板契约(第 32 节)
│   └── scope_contract.schema.json # 范围契约(第 36 节)
├── scripts/
│   ├── init_agent.py           # 初始化(第 35 节)
│   ├── run_with_feedback.py    # 反馈运行器(第 37 节)
│   ├── verify_agent.py         # 验证门(第 38 节)
│   └── generate_handoff.py     # 交接生成器(第 40 节)
├── bin/
│   └── install.sh
└── README.md
​

什么进,什么不进

进:

• 面模式——它们是契约。
• 上面四个脚本——它们是运行时。
• 四个文档——它们是规则与量表。

不进:

• 项目特定任务——任务属目标仓的板,不属包。
• 厂商 SDK 调用——包框架无关。
• 入职散文——包活在团队已有入职旁,不活在其内。

安装器

一个短的 bin/install.sh(或 bin/install.py):

1. 无 --force 拒绝覆盖已有包。
2. 把包复制进目标仓。
3. 若 .github/workflows/ 存在则接 CI。
4. 打印下一步:填板、设验收命令、跑初始化脚本。

版本化

包带一个 VERSION 文件。模式升级与需迁移的脚本变更升 major。纯文档变更升 patch。目标仓的 agent_state.json 记录它初始化时所对的包版本。

二、从零实现

原课程 code/main.py 把包组装进课程旁的 outputs/agent-workbench-pack/,用本小专题前几节的模式与脚本播种,加上你已写的文档。

Step 1:组装包(钉死面)

def assemble_pack(out_dir):
    copy("AGENTS.md", f"{out_dir}/AGENTS.md")
    for d in ["agent-rules.md", "reliability-policy.md",
              "handoff-protocol.md", "reviewer-rubric.md"]:
        copy(f"docs/{d}", f"{out_dir}/docs/{d}")
    for s in ["agent_state.schema.json", "task_board.schema.json",
              "scope_contract.schema.json"]:
        copy(f"schemas/{s}", f"{out_dir}/schemas/{s}")
    for sc in ["init_agent.py", "run_with_feedback.py",
               "verify_agent.py", "generate_handoff.py"]:
        copy(f"scripts/{sc}", f"{out_dir}/scripts/{sc}")
    write(f"{out_dir}/VERSION", "1.0.0")
    write(f"{out_dir}/README.md", pack_readme())
​

Step 2:安装器(幂等)

#!/usr/bin/env bash
# bin/install.sh
set -euo pipefail
TARGET="${1:-.}"
if [ -f "$TARGET/.workbench-version" ] && [ "${FORCE:-0}" != "1" ]; then
  echo "已存在包,用 FORCE=1 覆盖"; exit 1
fi
cp -r outputs/agent-workbench-pack/* "$TARGET/"
echo "$(cat outputs/agent-workbench-pack/VERSION)" > "$TARGET/.workbench-version"
[ -d "$TARGET/.github/workflows" ] && wire_ci "$TARGET"
echo "下一步: 填 task_board.json、设验收命令、跑 scripts/init_agent.py"
​

运行 python3 code/main.py 会复制并钉死面、写 README、打印包树、退出零。重跑幂等。

生产模式(让包挺过 fork、更新、不友好上游)

一个包只有在挺过 fork、更新、不友好上游时才有价值。四条模式让它工作。

VERSION 是契约,非营销。 major 升级要状态迁移。minor 升级要检查器重跑。patch 升级纯文档。安装器每次安装往目标仓写 .workbench-version;lint_pack.py 在目标锁与包 VERSION 不一致时拒绝交付。这是 npm、Cargo、pyproject.toml 挺过十年 churn 的方式;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/。卸载器移除模式、脚本、文档、AGENTS.md(带 --keep-agents-md opt-out),并在状态文件有任何未提交改动时拒绝继续。状态属用户;包不拥有它。

Skill-as-publishable(SkillKit 式分发)。 包作为 SkillKit skill 发:skillkit install agent-workbench-pack 从单一源跨 32 个 AI Agent 铺设。包仓库是真相源;SkillKit 是分发渠道。厂商锁定塌缩;七个面不变。

💡 设计要点:毕业项目的本质是把知识从「懂」变成「可分发」。前 41 节你学了七面是什么、为什么、怎么造;本节把它们压成一个 cp -r 就能用的包,让别的仓库、别的团队、别的 Agent 产品都能受益。版本化让包能演化而不破坏已安装的实例;符号链接让单一真相源扇出到所有工具;卸载器保护用户状态。这与第 31 节「工作台独立于模型」的洞见合流——包是面,面是可复用的,模型换不换都成立。

三、框架对比

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

四、可复用产物

原课程 outputs/skill-workbench-pack.md:生成一个调到项目的包——规则按团队历史磨锐、范围 glob 匹配仓库、量表维度扩展一个领域特定项。

五、练习

1. (Medium) 决定哪个可选第五文档值得晋升进规范包。论证取舍。
2. (Medium) 把安装器重写成 Python,带 --dry-run 标志。对比 bash 的人体工学。
3. (Hard) 加一个 bin/uninstall.sh,安全移除包,状态文件有非平凡历史即拒。什么算非平凡?
4. (Hard) 加一个 lint_pack.py,包偏离 VERSION 即失败。接进包自己仓的 CI。
5. (Hard) 写从手搓工作台迁到本包的迁移 runbook。最小化停机的操作顺序是什么?

本节要点回顾

1. 毕业项目 = 可复用包:十一节面压进一个 cp -r 即用的目录,第二天早上 Agent 可靠干活。
2. 解药是版本化包:活在 Doc/聊天/半记得脚本里的工作台每季度重建;包带面/模式/脚本/一条命令安装器。
3. 包布局:AGENTS.md 路由 + docs(规则/策略/交接/量表)+ schemas(状态/板/范围)+ scripts(init/反馈/验证/交接)+ bin/install.sh。
4. 进包:面模式(契约)、四脚本(运行时)、四文档(规则量表);不进:项目任务、厂商 SDK、入职散文。
5. 安装器幂等:无 --force 拒覆盖、复制、接 CI、打印下一步。
6. 版本化:模式/脚本变更升 major、纯文档升 patch;目标仓记初始化包版本。
7. VERSION 是契约非营销:同 npm/Cargo/pyproject 挺过十年 churn;.workbench-version + lint_pack.py 防漂移。
8. 跨工具单一源:Nx ai-setup + 符号链接扇出;fork 包支持单工具是失败模式。
9. uninstall 保护状态:删模式/脚本/文档但不删 agent_state/task_board/outputs;非平凡状态拒绝继续。
10. SkillKit 分发:32 个 AI Agent 单源安装;厂商锁定塌缩,七面不变。

全章收尾

至此,第 15 章「Agent 工程」全部 42 节汉化完成。让我们回望这条从「观察-思考-行动」到「可交付工程级工作台」的完整路径:

P0 核心路径(第 01~06 节) 奠定了 Agent 的工程地基——Agent 循环、ReWOO 与计划执行解耦、Reflexion 言语强化学习、思维树与 LATS 审慎搜索、Self-Refine 与 CRITIC 迭代精炼、工具使用与函数调用。这条闭环回答了「一个 Agent 如何观察、思考、行动、调工具、自我修正」。

记忆与学习(第 07~11 节) 把短期上下文扩展成持久能力——MemGPT 虚拟上下文与分页、记忆块与睡眠时计算、Mem0 混合记忆、Voyager 技能库与终身学习、HTN 与进化规划。Agent 不再是「每次从零开始」,而是会积累。

框架与编排(第 12~18 节) 给出把 Agent 组装成系统的工具箱——Anthropic 工作流模式、LangGraph 状态图、AutoGen Actor 模型、CrewAI 角色团队、OpenAI/Claude Agent SDK、Agno/Mastra 运行时。你学会了按「先工作流后 Agent、先 Flow 后 Crew、先单 Agent 后拓扑」做取舍。

评估与基准(第 19~22 节) 把「感觉它挺好」变成客观度量——SWE-bench/GAIA/AgentBench、WebArena/OSWorld、Computer Use、语音 Agent。你学会了查状态不查形状、看分布不看均值、报 Verified/+ 审计分。

可观测性与安全(第 23~27 节) 是生产的入场券——OTel GenAI 约定、Langfuse/Phoenix/Opik 平台、多智能体辩论、失败模式分类、提示注入与 PVE 防御。你学会了内容捕获默认关、把检索内容当不可信、纵深防御而非单一银弹。

生产与方法论(第 28~30 节) 把一切整合成可运维的系统——编排模式、六种运行时形态、评估驱动开发。你学会了复杂度是税不是美德、可观测性承重、评估是外层循环。

工作台工程(第 31~42 节) 是本章的压轴——为什么有能力的模型仍失败、最小三文件工作台、指令即约束、仓库记忆、初始化脚本、范围契约、运行时反馈、验证门、审查者、多会话交接、真实仓库实战、可复用包。你学会了工作台独立于模型、循环闭合在状态文件非聊天、七面是分布式系统八原语的 UX 层、把「应该」变「必须」、把知识从「懂」变「可分发」。

贯穿全章的一条主线是:Agent 不是更聪明的 LLM,而是给 LLM 装上记忆、工具、循环、约束、验证与交接的工程系统。承重的工程在模型周围,不在模型内部;词汇会变(外壳/harness/工作台/护栏),但工程原语——函数、工人、触发器、运行时、队列、持久化、授权策略——不变。今天如此,明天依然。

第 15 章完。下一章(第 16 章·自主系统)将在本章的 Agent 工程地基上,探讨更高级的自主性——长期运行的自主 Agent、具身智能、机器人,以及自主系统特有的安全与对齐挑战。