企业官网建设流程全解析

1. 为什么编码 Agent 需要一份 AGENTS.md 行为规范

Harness Engineering 这个词最近在编码 Agent 圈子里被反复提起，说白了就是给 Agent 套上一副“缰绳”——不是限制它的能力，而是让它每次动手之前都知道边界在哪、目标是什么、什么算做完。我试过让 Agent 在一个中型 RAG 项目里自由发挥，结果它把apps/api和apps/web的依赖方向搞反了，前端直接 import 了后端 service 层的模块，跑起来才发现循环依赖。那次之后我才认真对待 AGENTS.md 这件事。

AGENTS.md 本质上是一份放在仓库根目录的“Agent 行为契约”。它和 README 不一样，README 是给人看的，AGENTS.md 是给编码 Agent 看的。它要回答三个问题：这个项目要构建什么、Agent 该怎么工作、任务真正完成的标准是什么。配合 ARCHITECTURE.md 定义系统骨架、CLAUDE.md 定义 Claude Code 的启动指令，三者构成一套可执行的规范体系。

适合谁读这篇？如果你正在用 Cline、Claude Code、Codex 这类编码 Agent 做真实项目，并且发现 Agent 经常跑偏、改错文件、忽略测试、或者每次都要手动提醒它读文档，那这套方法就是为你准备的。本文会给出可直接复制的 AGENTS.md 模板、目录结构、约束条目示例，并演示在 Cline MCP 中把 Base URL 改到 TaoToken 后跑通一次规范校验，验证 Agent 是否真的按规范执行。

核心检索词先明确：Harness Engineering 是一套让编码 Agent 在可控边界内工作的工程实践，AGENTS.md 是这套实践的落地载体，ARCHITECTURE.md 和 CLAUDE.md 是配套的骨架与启动指令。三者缺一不可，只有 AGENTS.md 而没有 ARCHITECTURE.md，Agent 知道规则但不知道系统怎么拼；只有 ARCHITECTURE.md 而没有 AGENTS.md，Agent 知道骨架但不知道工作流程。

我踩过的坑是：一开始只写了一份很长的 AGENTS.md，把所有规则堆在一起，结果 Agent 每次只读前几行就开始动手。后来拆成 AGENTS.md 管规则、ARCHITECTURE.md 管结构、docs/ 下各专项文档管细节，Agent 的命中率明显提升。关键原则是：AGENTS.md 要短而硬，ARCHITECTURE.md 要全而准，专项文档要深而专。

2. TaoToken 前置准备：Base URL、API Key 与 Model ID 三件套

在演示 Cline MCP 跑通规范校验之前，需要先把接入层准备好。TaoToken 提供的是兼容 OpenAI 接口规范的 API 网关，编码 Agent 通过它来调用模型。你需要准备三样东西：Base URL、API Key、Model ID。这三件套在任何编码 Agent 的配置里都是必须的，缺一个都跑不起来。

Base URL 统一使用https://taotoken.net/api，注意这里不加任何 UTM 参数，保持干净。API Key 需要到控制台创建，路径是 console 页面下的 api-keys 管理。Model ID 根据你用的模型来填，比如claude-sonnet-4-20250514或者gpt-4o这类，具体以模型对话页面列出的可用模型为准。

如果你用的是 Claude Code，接入方式略有不同，需要参考 ClaudeCodeAnthropic 的文档配置。Cline MCP 的配置则是在 Cline 的设置里找到 API Provider，选择 OpenAI Compatible，然后填入 Base URL 和 API Key。这里有个细节：Cline 的 Base URL 字段有时候会自动补/v1，而 TaoToken 的路径是/api，所以填的时候要确认最终请求地址是https://taotoken.net/api/v1/chat/completions这种形式，不要多也不要少。

我实测下来，Cline 里配置 TaoToken 最稳的方式是：API Provider 选 OpenAI Compatible，Base URL 填https://taotoken.net/api，API Key 填控制台生成的 key，Model ID 填你需要的模型。保存后 Cline 会发一个测试请求，如果返回正常就说明接入成功。如果报 401，先检查 key 有没有复制完整；如果报 model not found，检查 Model ID 拼写。

对于长期做编码和 Agent 任务的场景，可以考虑 Coding Plan，它在额度上更适合高频调用。如果只是验证模型效果，用模型对话页面就够了。接入文档在 doc 页面有详细说明，遇到配置问题可以先翻文档。

需要强调的是，TaoToken 在这里的角色是模型调用网关，不是替代你的编辑器或 IDE。Cline 仍然是你的编码 Agent 宿主，TaoToken 只是它背后调用的模型服务。这个边界要清楚，不然配置的时候容易搞混。

3. 可复制配置：AGENTS.md 模板与 Cline MCP settings 片段

这一节给出可直接复制的配置。先看 AGENTS.md 模板，这是整个 Harness Engineering 的核心文件。模板设计原则是：短、硬、可执行。每一条规则都必须是 Agent 能判断“做了还是没做”的，不能是“尽量”“建议”这种模糊表述。

# AGENTS.md This repository is designed for agent-assisted development: humans define intent, constraints, and review standards; agents implement, test, document, and improve the system. ## Product Build an internal AI system for company use: - Organization-network access only for end users. - LLM runtime with Ollama. - Model routing across DeepSeek R1 distilled models, Mistral, and Llama 3.1 class models. - RAG over approved OEM whitepapers, datasheets, and internal documents. - JWT, RBAC, document-level permissions, audit logs, and prompt-injection controls. - React web app backed by a Python API backend that also owns LLM orchestration. - Observability across latency, token usage, cache hit rate, retrieval quality, and hallucination feedback. ## Start Here - Architecture map: `ARCHITECTURE.md` - Copilot/Codex instructions: `.github/copilot-instructions.md` - Product behavior: `docs/product-specs/index.md` - Engineering plans: `docs/exec-plans/active/` - Security rules: `docs/SECURITY.md` - Reliability rules: `docs/RELIABILITY.md` - Quality scorecard: `docs/QUALITY_SCORE.md` - Frontend rules: `docs/FRONTEND.md` - Design principles: `docs/DESIGN.md` - External/library references for LLMs: `docs/references/` ## Agent Operating Rules 1. Before changing code, read the relevant product spec, design doc, architecture section, and active execution plan. 2. Prefer small, reviewable PR-sized changes. 3. If a requirement is ambiguous, write the assumption into the active execution plan before implementing. 4. Update docs when behavior, interfaces, data shapes, security rules, or operational assumptions change. 5. For frontend work, use Tailwind CSS and shadcn/ui components unless an existing design system overrides this. 6. Internet access is allowed for approved runtime integrations, but company data, prompts, traces, and documents must only flow to approved services. 7. Validate data at every trust boundary: upload, auth, retrieval, tool call, model response, and API response. 8. Treat security, observability, and evaluation tooling as product code. 9. When you discover repeated review feedback, convert it into docs, tests, lints, or checklists. ## Expected Agent Loop 1. Read task and relevant docs. 2. Create or update an execution plan in `docs/exec-plans/active/`. 3. Implement the smallest coherent slice. 4. Run tests, linters, type checks, and relevant evaluation scripts. 5. Validate manually through API/UI where applicable. 6. Update generated docs such as schema maps. 7. Record decisions and remaining risks in the execution plan. 8. Move completed plans to `docs/exec-plans/completed/`. ## Definition of Done - Product behavior matches the relevant spec. - Access control and document permissions are enforced. - Retrieval results are source-attributed. - Model outputs include uncertainty or refusal behavior where required. - Tests cover the main path and at least one failure path. - Observability emits useful traces, metrics, and audit events. - Documentation reflects the implemented behavior.

这份模板的关键在于 Definition of Done 部分。很多 Agent 跑偏是因为“完成”的定义不清晰，它以为代码写完就算完，但实际需要测试覆盖、文档更新、可观测性埋点。把 DoD 写死，Agent 就没有模糊空间。

接下来是 Cline MCP 的 settings 片段。Cline 的配置存在 VS Code 的 settings.json 里，MCP 服务器的配置格式如下：

{ "cline.mcpServers": { "taotoken-gateway": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"], "env": { "OPENAI_BASE_URL": "https://taotoken.net/api", "OPENAI_API_KEY": "sk-your-key-here", "OPENAI_MODEL": "claude-sonnet-4-20250514" } } } }

注意这里的OPENAI_BASE_URL填的是https://taotoken.net/api，不要加/v1，因为 MCP server 内部会自己拼接路径。OPENAI_API_KEY换成你在 console 创建的 key。OPENAI_MODEL换成你实际要用的 Model ID。

如果你用的是 Claude Code，配置在~/.claude/settings.json或者项目级的.claude/settings.json：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-your-key-here", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

Codex 的配置在~/.codex/auth.json：

{ "openai_api_key": "sk-your-key-here", "base_url": "https://taotoken.net/api", "model": "gpt-4o" }

三件套的对应关系要记牢：Base URL 统一是https://taotoken.net/api，API Key 从 console 的 api-keys 页面创建，Model ID 从模型对话页面查。任何一处填错都会导致请求失败。

4. 验证请求：在 Cline MCP 中跑通一次规范校验

配置写好后，需要验证 Agent 是否真的按 AGENTS.md 执行。验证方法是设计一个“规范校验任务”，让 Agent 去检查代码是否符合 AGENTS.md 里的约束条目，然后看它的输出是否引用了正确的文档、是否按 Expected Agent Loop 的步骤走。

具体操作：在 Cline 里打开你的项目，确保根目录有 AGENTS.md 和 ARCHITECTURE.md。然后在 Cline 对话框里输入这样的任务：

请检查 apps/api/app/services/orchestrator.py 是否符合 AGENTS.md 中的 Agent Operating Rules。 具体要求： 1. 先读 AGENTS.md 和 ARCHITECTURE.md 2. 说明你读了哪些文件 3. 逐条对照 Operating Rules 检查 4. 如果发现违规，指出具体条目和代码位置 5. 不要直接修改代码，只输出检查报告

发送后观察 Cline 的行为。如果配置正确且 AGENTS.md 生效，Agent 应该先输出它读取了哪些文件，然后逐条对照规则给出检查结果。如果 Agent 直接开始改代码，说明它没有遵守“不要直接修改代码”的指令，这时候需要检查 AGENTS.md 是否被正确加载。

我实测下来，Cline 在读取 AGENTS.md 后，会在回复开头列出“Read AGENTS.md, ARCHITECTURE.md, docs/SECURITY.md”这样的文件清单，然后才开始分析。这个行为本身就是规范生效的信号。如果它没有列文件清单就直接分析，说明 AGENTS.md 没有被优先读取，需要检查 Cline 的 instruction files 配置。

验证成功的标志有三个：第一，Agent 在动手前先读了 AGENTS.md 和 ARCHITECTURE.md；第二，Agent 的输出引用了具体的规则条目编号；第三，Agent 遵守了“只输出报告不修改代码”的约束。三个都满足，说明 Harness Engineering 的规范层已经生效。

如果要做更严格的验证，可以故意在代码里埋一个违规点，比如在apps/web里 import 了apps/api的模块，然后让 Agent 去检查。看它是否能发现这个跨层依赖违规，并引用 ARCHITECTURE.md 里的依赖方向规则。这个测试能验证 Agent 是否真的理解了规范，而不是只做了表面检查。

验证通过后，你可以把这次检查报告作为模板，后续每次 Agent 完成任务后都跑一遍类似的规范校验。这样就把 Harness Engineering 从“一次性配置”变成了“持续执行的流程”。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

配置和验证过程中最容易遇到四类报错，逐个说清楚原因和排查方法。

第一类：401 Unauthorized。这个最常见，原因是 API Key 无效或没传对。排查步骤：先确认 key 是从 console 的 api-keys 页面创建的，没有多余空格；再确认配置里 key 的字段名正确，Cline 里是OPENAI_API_KEY，Claude Code 里是ANTHROPIC_API_KEY，Codex 里是openai_api_key；最后确认 Base URL 没有拼错，https://taotoken.net/api不要写成https://taotoken.net/api/v1或https://taotoken.net/v1。如果 key 确认没问题还是 401，到模型对话页面发一条测试消息，看是否能正常返回，以此判断是 key 问题还是配置问题。

第二类：local proxy failed。这个报错通常出现在 Cline 或 Claude Code 启动时，原因是本地代理配置冲突。排查步骤：检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这些，如果有且指向了一个不可用的地址，就会报 local proxy failed。解决方法是清掉这些环境变量，或者确保它们指向可用的地址。另外检查 VS Code 的http.proxy设置，如果设了一个失效的代理也会导致这个问题。

第三类：reading choices 相关报错。这个通常出现在请求返回后解析响应时，报错信息类似Cannot read properties of undefined (reading 'choices')。原因是返回的 JSON 结构不符合预期，可能是 Base URL 路径不对导致返回了 HTML 错误页，也可能是 Model ID 不存在导致返回了错误对象。排查步骤：先用 curl 直接请求一次，看返回的 JSON 结构：

curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-your-key-here" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"hi"}]}'

如果返回里有choices字段，说明接口正常，问题在 Agent 配置；如果没有，看返回的错误信息是什么。常见的是 model not found，这时候去模型对话页面确认 Model ID 拼写。

第四类：OAuth 相关报错。这个出现在 Claude Code 或 Codex 的认证流程里，报错信息类似OAuth token expired或invalid_grant。原因是这些工具默认走 OAuth 认证，但配置了 Base URL 后应该走 API Key 认证。排查步骤：确认配置里用的是 API Key 而不是 OAuth token；如果之前登录过 OAuth，先退出登录再重新配置；检查~/.claude/settings.json或~/.codex/auth.json里是否有残留的 OAuth 字段，有的话删掉。

这四类报错覆盖了 90% 的接入问题。排查顺序建议是：先 curl 验证接口通不通，再检查 Agent 配置的字段名和路径，最后检查环境变量和残留配置。按这个顺序走，基本都能定位到问题。

6. 把规范校验接入日常编码流程

规范校验跑通一次之后，下一步是把它变成日常流程的一部分。我的做法是在 AGENTS.md 的 Expected Agent Loop 里加一条：每次任务完成后，Agent 必须自己跑一次规范校验，把结果写进 execution plan。这样就不需要人工每次提醒。

具体实现是在 AGENTS.md 里追加一条规则：

10. Before marking a task complete, run a self-check against the Agent Operating Rules and record the result in the active execution plan.

然后在docs/exec-plans/active/下的每个 plan 文件里加一个## Self-Check段落，Agent 完成任务后要在这里填写检查结果。格式可以是：

## Self-Check - [x] Read AGENTS.md and ARCHITECTURE.md before editing - [x] Changes are PR-sized and reviewable - [x] Docs updated for behavior changes - [x] Tests cover main path and one failure path - [ ] Observability traces added (pending)

这个自检清单让 Agent 的每一步都可追溯。如果某一项没打勾，review 的时候一眼就能看到哪里没做完。

对于长期做编码 Agent 任务的场景，可以考虑用 Coding Plan 来支撑高频的模型调用。规范校验本身会消耗不少 token，因为 Agent 要读多个文档、逐条对照、输出报告。如果只是偶尔验证，用模型对话页面手动测就行。

接入文档在 doc 页面有完整的配置说明，包括 Cline、Claude Code、Codex 各自的配置示例。API Key 在 console 的 api-keys 页面管理，可以创建多个 key 分别给不同工具用，方便排查问题时隔离。

最后说一个实用技巧：把 AGENTS.md 里的规则条目编号固定下来，不要随意增删。因为 Agent 在输出检查报告时会引用编号，如果编号变了，之前的报告就对不上了。新增规则就往后追加编号，废弃规则就标记为 deprecated 而不是删除。这样整个规范体系就是可追溯的，和 Harness Engineering 的核心理念一致——每一步决策都留记录，Agent 不容易跑偏。