Coding Agent 研发工程师训练营

主题

Capstone Demo 与作品集 ​

本课交付结果 ​

你将交付 buildPortfolioEvidence(run, evalResult)：完整 README、5 分钟定时 Demo 脚本和量化简历叙述。架构、Trace、Eval 链接与成功率缺一不可，证据不全时门禁失败。

岗位问题 ​

作品集不是功能截图合集。面试官需要回答：解决了什么问题、架构为何这样分层、安全边界在哪里、一次运行如何审计、质量如何量化、你具体做了什么。每个陈述都应能点击到证据。

前置检查 ​

前置知识快照 ​

先通过端到端与回归门禁：

bash
pnpm --filter @learn-traeai/coding-agent-bootcamp verify:lesson -- 38
pnpm --filter @learn-traeai/coding-agent-bootcamp verify:lesson -- 39

准备 architectureLink、traceLink、eval reportLink、successRate 和至少两个 demoSteps。

第 38 课给一次真实 Bug Fix 行为证据，第 39 课给版本回归结论；Capstone 不再发明新能力，而是把八周产物组织成审查者可沿链接验证的叙事。功能、架构图、Trace、Eval、Demo 和简历句必须指向同一 commit/版本，不能各自挑最好截图。

作品集有三类读者：招聘者在几十秒判断问题与影响，工程师沿架构/代码/测试判断深度，面试官通过五分钟 Demo 和追问判断你是否真正做过。README 给入口，artifact 给证据，脚本控制叙事节奏，简历句只压缩已经被证据支持的结论。

证据门禁先验证 title、architectureLink、traceLink、reportLink、successRate 和 demoSteps。任何空链接、越界比例或少于两个步骤都在生成文案前失败。先写“成功率达到九十”以后再补报告，会让营销事实先于工程事实，本课明确禁止。

原理拆解 ​

mermaid
flowchart TD
  A[同一 release commit] --> B[架构与威胁模型]
  A --> C[端到端 Trace/Diff/Test]
  A --> D[Eval 与回归报告]
  B --> E[README 六节]
  C --> E
  D --> E
  E --> F[五分钟 Demo 脚本]
  E --> G[量化简历叙述]
  F --> H[可复核面试故事]
  G --> H
  H --> I{任一主张无证据?}
  I -->|是| J[拒绝发布作品集]
  I -->|否| K[生成 evidence manifest]

README 固定六节：问题、架构、安全边界、Trace 证据、Eval 结果、运行方式。Demo 将步骤均匀放入 00:00–05:00。简历句包含项目名、可审计机制与量化成功率，且能由链接报告复核。

代码实验 ​

打开本课 Lab

bash
pnpm --dir bootcamps/coding-agent/labs/40-capstone-demo/starter test
pnpm --dir bootcamps/coding-agent/labs/40-capstone-demo/solution test

Starter 应声明 实现作品集证据完整性门禁；Solution 应通过 5 项测试。

失败实现 ​

ts
function buildUnsafe(title: string) {
  return {
    readme: `# ${title}\n\n一个强大的 AI Agent。`,
    resume: "显著提升开发效率，负责核心架构。",
  };
}

失败实现只有形容词，没有问题、边界、命令、Trace、评测和数字来源；任何人都能写，无法通过追问。截图可以伪造或过期，“显著”没有基线，“负责”没有具体决策。作品集看似完整，证据密度为零。

先验证输入，再生成所有派生文案：

ts
for (const key of ["title", "architectureLink", "traceLink"] as const) {
  if (!run[key].trim()) throw new Error(`作品集缺少 ${key}`);
}
if (!evalResult.reportLink.trim()) throw new Error("作品集缺少 reportLink");
if (!Number.isFinite(evalResult.successRate)
    || evalResult.successRate < 0 || evalResult.successRate > 1) {
  throw new Error("successRate 必须位于 0 到 1");
}
if (run.demoSteps.length < 2 || run.demoSteps.some((step) => !step.trim())) {
  throw new Error("demoSteps 至少需要两个有效步骤");
}

关键实现讲解 ​

成功率 0.85 展示为 85%，但原始 Eval JSON 保留精度。README 链接使用传入相对路径，便于静态仓库浏览。任何空 traceLink 或超出 0–1 的 successRate 在生成文案前失败，防止“先写宣传、以后补证据”。

title 是具体项目名而非“AI项目”；一句副标题说明为谁解决什么问题，例如“在受限工作区中可审计地搜索、编辑并验证代码”。首屏放安装/运行最短路径、当前状态和证据索引，不堆技术 badge。读者先理解问题，再决定是否深入架构。

README“问题”节描述真实失败模式：模型会猜路径、跳过测试、自报完成、泄漏secret和无限花费；不是泛泛说“提升效率”。列出设计目标与非目标，例如支持确定Bug Fix与本地工具，不承诺自主发布或完全理解大型仓库。范围诚实让后续决策有依据。

“架构”节用一张最小图串起 CLI→Provider→Agent Loop→Tool Registry→Sandbox/Editor→Trace/Eval，并解释依赖方向。链接到完整 architecture.md/ADR，说明为什么 Core只认Action/Tool contract，为什么动态扩展隔离。图与当前代码目录一致，过期节点由链接检查/评审发现。

架构文档不只列模块，还列关键不变量：Workspace realpath边界、shell false参数、权限allow/ask/deny、预算停止、编辑事务、JSONL连续序号、测试+Diff完成门禁、Fixture原态。每个不变量链接对应测试文件或课次，展示设计到证据的映射。

“安全边界”节用威胁/控制/残余风险表。路径穿越→realpath/relative；命令注入→executable+args/shell false；秘密日志→写前脱敏；插件扩权→manifest子集+沙箱；子Agent泄密→context allowlist；仍有模型误判、第三方依赖和平台差异等限制。

审批与授权必须可演示：写工具没有批准时阻断，批准绑定动作后执行，网络/发布不在Demo授权范围。不要在作品集配置里全局 auto-approve 所有权限只求顺滑；可对临时fixture的单一write显式批准，并在Trace指出这条边界。

“Trace证据”链接原始脱敏JSONL、可选Viewer和一份注释说明。原始机器文件可搜索sequence/runId，Viewer便于人读；只放截图无法验证连续性或秘密扫描。公开artifact使用无敏感fixture，扫描seed key与绝对个人路径，保留schema和内容hash。

选择一条成功Trace和一条失败Trace。成功展示search/read/edit/test/diff/finish，失败展示错误乘法或权限拒绝如何被门禁阻止。只有happy path会让人怀疑系统只是演示脚本；失败证据更能说明安全控制实际生效。

“Eval结果”给任务数、类别分布、成功率、成本、步骤、基线/next、阈值和回归status，不只突出最高百分比。链接原始JSON与comparison报告，说明模型/fixture/grader版本。小样本注明限制，不把八十五百分比包装成行业通用准确率。

successRate展示可四舍五入为整数，原始链接保留计数与精度。简历句写“在固定N个任务的课程基准达到85%”，比“准确率85%”更可回答。若样本数尚未进入输入contract，应扩展PortfolioEval，而不是从rate猜N。

“运行方式”提供从clone/pnpm install到fake E2E、eval、Viewer的准确命令、Node版本和预计时间；默认无需真实API key。真实Provider作为可选步骤，用环境变量占位和费用/数据提示。命令在干净clone/CI验证，不能只在作者机器工作。

构建/测试 badge链接具体workflow与commit，不能用静态绿色图片。站点教程、源码和release artifact版本对应；README顶部标当前release/tag。若仓库尚有已知失败，在Known Limitations写清，不隐藏在issue列表。

README六节是最小门禁，可再加Architecture Decisions、Threat Model、Benchmarks、Known Limitations、Roadmap和Contributing。扩展内容围绕证据，不把篇幅当质量。首页保持扫描友好，深文档用链接渐进披露，正如Skill目录设计。

Demo固定五分钟是工程约束。步骤N个时将索引均匀映射零到三百秒，首项00:00、末项05:00；课程函数展示确定算法。实际脚本可按叙事非均匀分配，但总时长、每段目标和fallback命令固定。每步包含“展示什么、说什么、证据在哪里”。

ts
const format = (seconds: number) =>
  `${String(Math.floor(seconds / 60)).padStart(2, "0")}:` +
  `${String(seconds % 60).padStart(2, "0")}`;
const demoScript = steps.map((step, index) =>
  `${format(Math.round(index * 300 / (steps.length - 1)))} ${step}`,
).join("\n");

00:00先展示失败测试与任务边界，让观众知道成功条件；约01:00运行Agent并指出权限/预算，而不是沉默等终端；约03:00打开Diff/Trace解释完成门禁；04:00展示Eval/回归；05:00总结限制与可复现链接。不要从安装依赖开始浪费Demo。

Demo使用预热依赖和确定Fake Provider，真实Provider另录可选片段。现场网络、模型随机或Registry不应决定核心演示成败；仍可说明适配真实Provider并展示契约测试。确定性不是作弊，而是让架构证据可重复。

每段准备fallback：命令意外慢时打开已生成artifact但说明它对应哪个commit/hash；Viewer不可用时用jq/文本逐行解释；不要拿无关截图蒙混。fallback事先演练并仍可机器复核。Demo失败也可展示系统如何安全失败，前提是叙事不失控。

录制时终端字号、窗口、命令历史、用户名和通知都处理隐私。使用专门demo用户/目录和假credential，关闭桌面通知；Trace/路径不含个人HOME。视频字幕与章节帮助访问，不用颜色作为唯一信息，关键命令在README可复制。

简历叙述采用“构建了什么 + 关键工程机制 + 量化证据 + 范围”结构。例如“构建Mini Code Agent，以受限工具、事务编辑、可审计Trace和确定评测闭环，在固定Bug Fix基准达到85%”。每个名词都能被追问并打开artifact。

避免“负责”“参与”“大幅提升”等空词。写你做的决策：设计Action/Tool contract、实现路径与权限边界、用Trace/Eval证明；若是团队项目说明个人负责模块和协作。数字必须给基线/样本/成本，不能把课程fixture成功率等同真实生产效果。

面试故事用问题—约束—选择—证据—反思。问题是false completion与工具风险；约束是本地workspace、预算、无网络测试；选择是contract分层与门禁；证据是E2E/Trace/Eval；反思是样本小、真实Provider随机、插件隔离仍需加强。反思不会削弱作品，反而证明判断。

准备三层讲解：三十秒说明价值，五分钟走Demo，三十分钟深入一个设计。不要试图在五分钟覆盖四十课；选择最能代表系统思考的路径，其他通过索引链接。面试官追问timeout、权限或Eval时再展开对应ADR/测试。

证据manifest把artifact name、相对path、sha256、content type、generatedFrom commit和sensitivity列成JSON。buildPortfolioEvidence不仅检查非空字符串，生产门禁还确认文件存在、链接不逃逸、hash匹配和无secret。静态站点构建后运行链接检查，防相对路径断裂。

外部链接会失效，核心证据尽量仓库内相对链接；规范/第三方资料可用版本化URL和访问日期。大视频放release/受控平台，README保留脚本与字幕，即使视频失效仍可复现。截图只作为预览，不是唯一证据。

artifact生成绑定同一commit。E2E后写Trace，Evaluation引用run evidence hash，comparison引用eval hash，portfolio manifest引用三者；工作树脏或commit不一致时release gate失败。不能用旧版高分Eval搭配新版代码Demo。

ts
it("rejects evidence gaps before writing claims", () => {
  expect(() => buildPortfolioEvidence({ ...run, traceLink: "" }, evalResult))
    .toThrow("traceLink");
  expect(() => buildPortfolioEvidence(run, { ...evalResult, successRate: 1.2 }))
    .toThrow("successRate");
});

测试README六个heading、三类链接、Demo首尾时间、每个step出现、resume包含数字与Trace/Eval；负面测试空链接、无效rate、空title、一个step和空step。项目 progression test还检查三段Demo恰为00:00/02:30/05:00，证据文案可审计。

生成器输出纯字符串但调用方写文件要原子、格式化并跑链接/Markdown检查。不要自动覆盖作者手写README全部内容；可以生成 PORTFOLIO.md 或受标记section，人工叙事与机器证据分层。任何手写数字可由门禁搜索与eval对照，防漂移。

作品集也需安全审查。运行secret scanner、个人路径/邮箱检查、许可证与第三方代码归属；公开Trace不包含用户数据，fixture明确合成。Git history可能仍有误提交secret，删除当前文件不够，需要轮换credential与历史处理。

可访问性包括架构图alt文本、表格heading、视频字幕、键盘可用Viewer、颜色对比和中文/英文关键术语。面试官可能在移动端或无视频环境，README仍可理解。Mermaid旁用短文本解释依赖，图渲染失败不丢核心信息。

反馈循环邀请不了解项目的人按README在干净环境运行，再问他能否回答问题、边界、证据和限制。记录卡住位置，改文档/脚本而不是口头补充。Demo录制后按五分钟计时复盘，删掉无证据铺垫，给关键Trace更多解释。

作品集成功指标不是star，而是可复现率、链接健康、Demo时长、面试追问可回答和证据完整性。CI每次release重跑artifact/links/secret/commands，定期检查外链。README是产品入口，也受回归门禁，不是写完即结束。

完整验收输入Mini Code Agent、架构/Trace/Eval相对链接、四个Demo步骤和成功率零点八五，生成六节README、00:00到05:00脚本和含85%的resume；清空任一证据或rate超界立即失败。再在真实仓库确认链接存在、命令通过和manifest hash一致。

Capstone目录可以固定为 docs/architecture.md、docs/threat-model.md、artifacts/trace.jsonl、artifacts/eval.json、artifacts/comparison.json、docs/capstone-demo.md 和 evidence manifest。固定布局让链接、站点、DOCX与发布脚本复用，也让审查者无需猜文件在哪。

架构决策记录选择少而关键的主题：为何用Action协议隔离Provider、为何shell false、为何搜索替换要求唯一匹配、为何完成需要test+diff、为何Skill渐进加载与Subagent预算收缩。每篇包含context、decision、alternatives、consequences和evidence，不把ADR写成事后胜利宣言。

威胁模型列资产、信任边界、攻击者、威胁、控制和残余风险。资产包括代码、凭证、预算、Trace和发布权；边界包括Provider、Plugin/MCP、workspace和Subagent。映射课程测试后，面试官可从任意安全问题追到实现，而不是只听“做了沙箱”。

Known Limitations至少写：真实模型规划仍有随机性，课程fixture规模有限，主进程Plugin隔离需强化，跨平台路径/进程差异，Eval样本与统计置信，真实凭证/数据政策由部署者管理。每项给未来验证方案，不用roadmap掩盖当前边界。

Demo前做rehearsal checklist：干净git status、依赖/构建完成、fixture重置、假key确认、终端/Viewer字号、链接可开、artifact hash匹配、计时器、断网fallback和通知关闭。演示结束也检查source原态和无残留进程，证明Demo没有破坏环境。

问答准备基于证据而非背台词。常见追问包括为何不用shell、realpath仍有哪些TOCTOU、timeout能否防计费、Eval为何选阈值、Subagent如何不泄密、Plugin清单是否真正沙箱。每题先承认边界，再指实现/测试/后续强化，避免夸大。

如果作品集部署成网站，构建后用Pagefind/链接检查确认教程和artifact可发现，静态服务器验证MIME与相对base；敏感JSON不应公开则提供脱敏样例和hash。站点Analytics不收Trace内容，下载链接有清晰数据说明。

DOCX版课程作为另一交付物，要保留标题层级、代码、表格、Mermaid替代图/说明、页眉页码和可点击链接；从同一Markdown/manifest生成，视觉渲染抽查。作品集README链接DOCX与在线教程，但两者版本hash一致，避免内容漂移。

发布说明列40课、Labs、项目测试、checkpoint、博客门禁、构建、DOCX和线上URL的最终证据；不是只说“课程上线”。每项命令、通过数和artifact path可复核。失败项不通过时保持draft/未上线状态，不用部分绿色宣称完成。

简历上只放一至两条最强叙述，面试文档保留更完整STAR/FAQ。数字随最新正式Eval更新由生成器校验，不能每次手改。若新版本成功率下降但仍在阈值内，resume是否继续旧数字要绑定release tag，不混用当前main。

项目公开后处理issue/反馈也能成为证据：复现bug、加fixture、运行回归、更新ADR与release。不要追求star或功能堆积，展示如何用已有Trace/Eval闭环改进。一次诚实失败复盘通常比十个未验证feature更有工程含量。

作品集的最终标准不是“看起来像产品”，而是陌生人能从主张到artifact、从artifact到命令、从命令到相同结果，再理解哪些结论仍有限。这个可追溯链正是Coding Agent作为工程系统而非魔法Demo的最好证明。

最终验收邀请一位陌生工程师只按README完成三件事：跑Fake E2E、打开一条失败Trace、解释comparison为何regress；邀请非工程读者在五分钟Demo后复述问题、控制和量化结果。两类人都能成功，说明入口既清晰又有深度。

若读者复现失败，优先把问题转成文档/脚本/fixture回归测试，不靠私聊口头补丁。作品集本身也进入与产品相同的观测—证据—修复闭环；每次反馈都能加强下一位读者的确定体验。

发布之后保留对应tag、artifact和DOCX，不让main持续变化破坏简历链接。新版本生成新manifest并更新“latest”，历史数字仍指向原tag。这样面试时任何陈述都有稳定时间点，而不是依赖当天仓库状态。

到这里，四十课共同交付的不只是一个会改代码的Demo，而是一套可以被限制、取消、恢复、观察、评测、扩展和发布的工程方法。Capstone的任务是让这套方法在五分钟内可见、在半小时内可深挖、在命令行中可复现。

每一个对外主张都必须回到同一版本的代码、测试、Trace、Eval与发布证据；无法回链的句子不进入作品集。

可验证性就是作品集最重要的表达方式。

可信。

运行与验证 ​

bash
pnpm --filter @learn-traeai/coding-agent-bootcamp verify:lesson -- 40
pnpm --filter @coding-agent/evaluator test

5 分钟 Demo 脚本：

  1. 00:00 展示失败测试与任务边界。
  2. 01:40 运行 Agent，指出权限、预算和工具观察。
  3. 03:20 打开 Diff 与 Trace，解释为何允许完成。
  4. 05:00 展示 Eval 与回归结论。

真实运行输出 ​

text
✓ tests/lab.test.ts (5 tests)
Test Files  1 passed (1)
Tests       5 passed (5)

项目 evaluator progression test还会生成README、三段五分钟脚本和resume evidence；最终发布门禁再验证artifact存在、链接、hash、secret扫描和端到端命令，而不只断言字符串。

常见失败与排查 ​

故障案例 1 ​

症状：README有大量功能和badge，读者仍说不清解决的问题、安全边界与为何这样分层。

根因：按代码目录罗列能力，没有问题—约束—选择—证据主线，架构图与当前实现漂移。

定位：让陌生读者在两分钟回答五个核心问题，逐个主张查链接/测试。

修复：六节最小结构，架构不变量映射代码与测试，已知限制与ADR显式链接。

故障案例 2 ​

症状：Trace/Eval只有截图或空链接，百分比来自旧运行，当前commit无法复现。

根因：文案先写、artifact后补，证据没有hash/commit链，发布门禁只检查字符串非空。

定位：从README链接下载原始文件，核对manifest hash、generatedFrom与命令；扫描断链。

修复：先生成同commit E2E/Eval，再构建文案；文件存在/hash/link/secret全量门禁，截图只作预览。

故障案例 3 ​

症状：Demo超时、现场安装或网络失败，简历写“显著提升”却答不出样本与基线。

根因：无定时脚本/fallback，依赖真实随机Provider，量化叙述脱离报告范围。

定位：连续录制三次计时，断网演练；对resume每个数字追问base、N、artifact。

修复：确定Fake Demo、00:00–05:00节奏与证据fallback；简历句含机制、范围和可点击rate。

课后作业 ​

录制一次严格 5 分钟 Demo，根据观众问题修改脚本；为 README 加架构图、威胁模型和一条失败 Trace，证明你不仅展示 happy path。

验收 Rubric ​

维度通过标准常见扣分
README六节完整且可运行营销描述替代证据
链接架构/Trace/Eval 均可访问截图或空链接
Demo00:00–05:00 有节奏无脚本现场漂移
叙述量化且可追问回答空泛“负责开发”

作品集证据清单：架构文档、真实 Trace、Eval JSON、回归比较、端到端命令、已知限制、5 分钟脚本、简历 bullet。

可回答的面试叙述：我把 Coding Agent 拆成契约、Provider、工具、Sandbox、编辑、状态、Trace、Eval 和扩展层；安全依靠路径 realpath、权限三态、无 shell 命令和预算；完成状态必须经过测试与 Diff；质量由固定夹具和分类回归门禁证明，而不是凭演示感觉。

总项目增量 ​

总项目包：@coding-agent/evaluator

总项目路径：packages/evaluator/src/portfolio-evidence.ts、docs/capstone-demo.md

总项目验证命令：pnpm --filter @coding-agent/evaluator test

40 课教学内容至此闭环；接下来运行全 40 Lab、全课链接、总项目与站点的最终审计。

延伸阅读 ​

  • Evidence-based portfolio。
  • Architecture Decision Record。
  • Technical interview storytelling：问题—约束—选择—证据—反思。

方案对比与工程取舍 ​

手写作品集最有个人表达，却容易数字/链接漂移；全自动模板一致但可能空洞。生成器负责证据字段、固定章节、数字和Demo时间，作者负责问题、决策与反思；CI验证两者连接。机器守事实，人写判断。

实时真实模型Demo显得“智能”，却不稳定、昂贵且难复现；Fake Provider稳定展示系统工程，可能不直接证明规划能力。核心五分钟用Fake证据，另提供受控真实Provider录制与Eval，明确两者测量对象，避免把随机性当真实感。

一个高成功率数字容易传播，却掩盖类别、成本和样本；完整报告可信但读者负担大。README给一句有范围摘要，链接详细Eval/回归/失败Trace。渐进披露让招聘者快速理解、工程师继续审查，不牺牲准确。

下一课衔接 ​

四十课内容在此闭环，但交付尚未结束：需要运行全40博客质量门禁、全Lab、总项目、八周checkpoint、教程/Portal构建，生成并视觉校验DOCX，更新训练营上线元数据，合并主分支、正式部署并在线验证。只有这些证据全部成立，课程才真正发布。

从零实现 Mini Code Agent Runtime

© 2026 learn.traeai.com