ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

DeepSeek Harness 开源 Vibe Coding 流水线:用 AGENTS.md 与质量门禁搭一套可复现的 Coding Agent 骨架

DeepSeek Harness 开源 Vibe Coding 流水线:用 AGENTS.md 与质量门禁搭一套可复现的 Coding Agent 骨架 1. 为什么 Vibe Coding 需要一套“骨架”而不是一句提示词DeepSeek Harness 开源之后很多人第一反应是去看它的 Agent Runtime 怎么实现但我更关注的是它把内部工程 SOP 一起放出来了。这件事的意义在于Vibe Coding 如果只是“让模型自由发挥写代码”那它顶多是个高级补全工具只有当仓库里存在规则、知识、协议、决策记录和质量门禁这五类资产时Coding Agent 才可能承担持续交付。我试过把需求直接丢给 Agent 让它“看看相关代码然后改”结果通常是它打开名字最像的文件改完跑一下局部测试就宣布完成。问题不在模型能力而在于仓库没有告诉它谁拥有这项行为、当前系统怎么装配、哪些动作属于高风险、什么证据才算验证通过。DeepSeek Harness 的做法是把这些约束拆成不同职责的仓库资产每个资产把 Agent 导向下一步而不是指望它记住一整本规范。这篇文章面向想用 Coding Agent 做持续交付的团队给出一套可复现的骨架AGENTS.md 怎么写、质量门禁怎么配、TaoToken 统一 Key/API 通道怎么接入最后附上本地跑通和门禁触发的验证动作。你可以把它当成一个最小可用的起点再按自己团队的事实往里填。2. TaoToken 前置统一 Key 与 API 通道在搭骨架之前先把模型调用通道固定下来。Coding Agent 的流水线里模型请求会散落在多个环节Agent 主循环、代码审查 Skill、文档同步检查、甚至门禁失败后的自动修复。如果每个环节各自配一套 Key 和 Base URL后面排查问题会非常痛苦。TaoToken 在这里的角色是提供一个统一的 API 通道让 Agent 骨架里的所有模型调用走同一个入口。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 这个不加 UTM。你需要先拿到 API Key。进入控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 然后在 API Keys 页面生成密钥https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。生成后建议直接写进环境变量不要硬编码进仓库。export TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具接入文档里有对应的配置方式https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。Claude Code 专用说明在 https://taotoken.net/ClaudeCodeAnthropic?utm_sourcetaotoken_aicg_blog_endutm_contentClaudeCodeAnthropicutm_campaignrewrite 。注意Key 只放在环境变量或本地密钥管理里不要提交到 Git。门禁脚本里如果需要读取用process.env.TAOTOKEN_API_KEY并在 CI 里配置为 secret。通道固定之后Agent 骨架里的模型调用就可以统一走一个封装后面换模型或调参数只改一处。3. 可复制配置AGENTS.md 骨架与质量门禁这一节是全文的核心。我把它拆成三块根 AGENTS.md、目录级 AGENTS.md、以及质量门禁脚本。3.1 根 AGENTS.md任务分发器而不是项目简介根 AGENTS.md 的第一段不应该写“本项目是做什么的”而应该写“你不能违反什么以及下一步去哪里”。下面是一个可以直接改的骨架# AGENTS.md ## 系统定位 本项目基于 你的框架核心原则是 一句话不变量例如一切能力都是插件。 修改 packages/ 前必须阅读 docs/architecture.md。 文档修改遵从 docs/AGENTS.md。 ## 仓库布局 - core/Session、Prompt、Tool、Agent、Loop 的产品主干 - llm/、shell/、fs/、subagent/各自拥有独立能力 - .agents/工作流与决策记录 - scripts/门禁与生成器 - examples/可运行组合不是可复用实现 ## 全局不变量 - 项目处于预发布阶段优先正确的基础结构而不是兼容旧格式的补丁 - 可以重命名和重组但必须同步更新引用 - 旧磁盘格式可以直接拒绝不写 deprecated alias 和双格式解析 ## 命令与密钥边界 - 模型调用统一走 TAOTOKEN_BASE_URLKey 从 TAOTOKEN_API_KEY 读取 - 禁止在源码、测试、文档中硬编码任何密钥 ## 下一步路由 - 生命周期、并发、子进程、teardown 规则先读 docs/defensive-patterns.md - 推送前检查匹配 .agents/skills/dsh-pre-push-checks - 非平凡决策在 .agents/notes/ 新增或更新记录这段骨架的关键在于“路由”而不是“罗列”。每条规则都很短但指向更具体的拥有者。根文件保持在每个会话都值得加载的体积细节下沉到目录规则和 Skill。3.2 目录级 AGENTS.md约束随作用域收缩进入packages/后规则应该变得更具体。下面是一个 Package 级骨架# packages/AGENTS.md ## 本目录所有权 本目录下的每个 Package 拥有自己的行为、测试入口和失败模式。 修改前先确认行为归属不要跨 Package 直接改别人的内部实现。 ## 高风险约束 - 产品可见插件必须有真实组合测试手工 ctx.plugin(...) 的 unit test 不足以证明装配正确 - Service Definition 要服务所有 Consumer不能让单个 UI 或 Tool 的需求污染公共 Service - 一个异步操作由一个生命周期控制器拥有分散的 ready/cancel/dispose 状态必须收拢 - 权限、配置、公开操作的限制必须在真正执行操作的位置实施不能只在 UI 或 Prompt 中隐藏入口 ## 测试入口 - Package 行为owning Vitest 文件或聚焦测试 - 构建配置或发布路径build、hygiene、built-artifact smoke这几条分别阻止了几种典型错误只在局部 mock 中验证、把最近调用方的需求升格为公共抽象、为“看起来完整”新增状态机、把访问控制做成可绕过的展示逻辑。3.3 质量门禁把文字要求变成非零退出Coding Agent 对可执行 Gate 的遵守程度远高于对纯文字要求的遵守程度。所以门禁的核心不是“请遵守规范”而是“违反时命令必须返回非零”。下面是一个scripts/run-gates.ts的简化骨架type Gate { id: string; command: string; dependsOn?: string[]; allowFailure?: boolean; }; const gates: Gate[] [ { id: ci-static, command: pnpm run lint pnpm run typecheck }, { id: ci-coverage, command: pnpm run test -- --coverage, dependsOn: [ci-static] }, { id: ci-snapshot, command: pnpm run test:snapshot, dependsOn: [ci-static] }, { id: ci-artifacts, command: pnpm run build pnpm run smoke, dependsOn: [ci-static] }, { id: doc-sync, command: pnpm run doc-sync, dependsOn: [ci-static] }, ]; async function runGate(gate: Gate): Promiseboolean { const result await exec(gate.command); if (result.code ! 0 !gate.allowFailure) { console.error([gate:${gate.id}] failed); return false; } return true; }配套的lefthook.yml保持克制pre-commit 只做 staged lint、空白检查、归档 Note 校验pre-push 只跑增量 typecheck。完整测试、coverage、snapshot、build 交给 CI避免 Agent 被慢反馈拖垮。pre-commit: commands: lint-staged: run: pnpm exec lint-staged whitespace: run: pnpm run check:whitespace pre-push: commands: typecheck: run: pnpm run typecheck:incremental3.4 决策记忆Agent Note 的最小格式非平凡变更需要在同一个 PR 里新增或更新至少一个 Agent Note。路径编码生命周期和类别.agents/notes/{lifecycle}/{class}/yyyy-mm-dd-topic-title.mdproposed/保存待评审方案implemented/保存已落地决策rejected/保存被否决但仍有提醒价值的方案archived/保存冻结历史。已实现记录的正文结构建议固定为## Problem ## Decision ## Alternatives considered ## Consequences其中Alternatives considered必须存在。它让未来 Agent 知道某个看起来合理的方案曾经被讨论过、因何失败避免下一次会话重新发明旧方案。4. 验证请求本地跑通与门禁触发配置写完之后必须验证两件事模型通道能通门禁能真的失败。4.1 验证 TaoToken 通道先用一个最小请求确认 Key 和 Base URL 正确curl -s https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: 只回复 ok}] }返回里能看到choices[0].message.content就说明通道正常。如果你想先在网页里确认模型行为可以用模型对话入口https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。4.2 验证门禁会失败门禁最容易犯的错是“永远绿”。故意引入一个类型错误然后跑pnpm run typecheck echo exit code: $?如果退出码不是 0说明 Gate 真的在检查。再跑一次完整门禁pnpm exec tsx scripts/run-gates.ts ci-static观察输出里是否打印了[gate:ci-static] failed。这一步确认了“文字要求”已经变成“可执行的非零退出”。4.3 验证 Agent 会读取 AGENTS.md在仓库根目录放一个测试任务让 Agent 修改packages/下的某个文件观察它是否先读了docs/architecture.md。如果它直接改代码说明根 AGENTS.md 的路由写得不够明确需要把“修改 packages/ 前必须阅读”这句话放到更靠前的位置。4.4 验证决策记录被触发提交一个改变行为的变更检查 PR 里是否自动要求新增 Agent Note。可以在 CI 里加一条检查if git diff --name-only origin/main | grep -q ^packages/; then if ! git diff --name-only origin/main | grep -q ^\.agents/notes/; then echo 非平凡变更需要 Agent Note exit 1 fi fi这条检查跑通后决策记忆就不再依赖人的自觉。5. 本篇常见错排查5.1 AGENTS.md 写成了项目简介最常见的错是把根 AGENTS.md 写成“本项目是做什么的”。Agent 读完知道项目背景但不知道下一步去哪。修正方法是把第一段改成路由每条规则指向更具体的拥有者而不是重复细节。5.2 门禁只跑局部测试只跑 owning Vitest 文件不跑真实组合测试会导致 Loader 和实际装配的问题漏掉。产品可见插件必须有真实组合测试手工ctx.plugin(...)的 unit test 不足以证明装配正确。5.3 为了变绿而放宽阈值Agent 很容易用--passWithNoTests、降低 coverage 阈值、或把--coverage.include缩窄到不再覆盖受影响文件。这些行为必须在 Skill 里明确禁止并在 Review 时检查。5.4 决策记录写成工作日志Agent Note 不是施工清单。提案用 Problem / Proposal / Alternatives considered / Acceptance criteria / Risks已实现记录改写为 Problem / Decision / Alternatives considered / Consequences。合并时要把“将要做什么”变成“现在实际是什么”。5.5 模型调用散落各处如果 Agent 主循环、审查 Skill、文档同步各配一套 Key排查问题会非常痛苦。统一走TAOTOKEN_BASE_URL和TAOTOKEN_API_KEY换模型只改一处。5.6 门禁依赖图缺失把质量检查写成一条长 Shell 命令前面失败会截断后面输出Agent 和 Reviewer 分不清哪项证据失败。用依赖图组织 Gate每项检查保留自己的 id、输出和失败原因。6. 长期编码与 Agent 场景的下一步如果你只是偶尔用 Agent 改几个文件上面的骨架可能显得重。但只要团队开始让 Coding Agent 承担持续交付规则、知识、协议、决策记录、质量门禁这五类资产就会变成刚需。它们不能互相替代规则缩小搜索空间文档提供当前事实Skill 约束高风险动作Agent Note 保存长期决策Gate 独立验证结果。对于长期跑编码任务和 Agent 流水线的团队建议把模型调用通道也固定下来。Coding Plan 适合需要持续、稳定调用额度的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入细节和参数说明在文档里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。落地顺序建议从最小开始先建根 AGENTS.md、docs/architecture.md和 Issue 验收条件模板再为最重要的领域补docs/subsystems/然后为关键用户旅程建最小的测试或 E2E Gate当团队反复遇到同一种高风险任务时再沉淀为 Skill当某项设计会被未来重新讨论时再创建 Agent Note。这样每一步都有可验证的产出而不是一次性搭一个没人维护的大架子。
返回列表