企业官网建设流程全解析

1. 智能体知识库为什么越堆越乱：从一本百科全书到一张地图

你大概遇到过这种场景：为了让智能体（Agent）在项目里少犯错，你把架构说明、编码规范、接口文档、部署流程、历史决策全部塞进一个AGENTS.md，洋洋洒洒几千行。结果它执行任务时，反而开始"遗忘"开头写死的核心原则，只盯着最近几段内容做决策。这不是模型变笨了，而是信息过载下的注意力稀释。

智能体知识库的渐进式披露，说的就是这件事：不要给智能体一本百科全书，而是给它一张地图。地图只告诉你"知识库怎么组织、去哪找"，真正的细节按需加载。这个思路来自用户体验设计里的 Progressive Disclosure——只展示当前需要的信息，把更多细节留到需要时再呈现。放到智能体场景，就是入口文档负责导航，模块化文档负责深度，维护机制负责对抗知识腐烂。

它适合谁？适合正在用 Claude Code、Cline、Codex 这类编码智能体做真实项目的人；适合文档已经膨胀到几百上千行、智能体开始"选择性失明"的团队；也适合想把知识库当代码来管理的独立开发者。核心检索词就三个：智能体、知识库、渐进式披露，而落地载体是AGENTS.md。

我试过把一份 2000 行的AGENTS.md直接喂给智能体，它在处理一个简单的接口改动时，居然引用了三段互不相关的部署说明，最后给出的方案里混进了过时的配置项。问题根源很清楚：当所有信息平铺在一起，智能体每次都要自己判断"哪些相关、哪些忽略"，而这个筛选责任本不该由它承担。

正确的做法是把知识库拆成三层：入口层（地图）、模块层（按主题拆分的详细文档）、维护层（文档园丁）。入口层控制在几百词，只讲结构和核心原则；模块层每个文档聚焦一个主题，长度几百到一两千词；维护层用智能体定期扫描文档与代码的一致性。下面我会给出可复制的AGENTS.md目录骨架、渐进式披露配置，以及在 TaoToken 统一 Key/API 通道下验证按需检索的具体动作。

2. TaoToken 前置准备：统一 Key 与 API 通道怎么配

在演示渐进式披露之前，得先把智能体的模型通道打通。这里用 TaoToken 作为统一入口，原因是它把多家模型的 Key 和 Base URL 收敛成一套，切换模型时不用改一堆环境变量。官网入口是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api （这个不加 UTM）。

你需要准备三件套：Base URL、API Key、Model ID。这三者在后面所有配置里都会反复出现，缺一不可。

先拿 Key。登录后进入控制台，在 API Keys 页面创建一个新 Key。建议按项目命名，比如agent-docs-demo，方便后面排查是哪个项目在调用。创建后立刻复制保存，页面刷新后就看不全了。

模型对话入口可以用来快速验证 Key 是否可用： https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 。在这里选一个模型发一条消息，能正常返回就说明 Key 和通道没问题。

如果你打算长期跑编码智能体或 Agent 任务，Coding Plan 会更划算，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它按订阅方式提供额度，适合每天都要调用模型的场景。

接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有各客户端的详细配置。API Keys 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

这里要强调一点：TaoToken 是统一的模型调用通道，不是编辑器替代品。它负责把请求转发到对应模型，你的智能体客户端（Claude Code、Cline、Codex 等）仍然是执行主体。配置时把 Base URL 指向https://taotoken.net/api，Key 填刚创建的，Model ID 按文档里列出的填。

环境变量方式最通用，先导出：

export TAOTOKEN_BASE_URL="https://taotoken.net/api" export TAOTOKEN_API_KEY="sk-你的key" export TAOTOKEN_MODEL="claude-sonnet-4-5"

如果你用的是 Claude Code，它读取的是 Anthropic 兼容配置，需要把 Base URL 指向 TaoToken 的 Anthropic 兼容端点。具体路径参考接入文档里的 ClaudeCodeAnthropic 章节： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。配置完先别急着跑复杂任务，用一条简单请求验证通道，确认返回正常再进入知识库部分。

3. 可复制配置：AGENTS.md 目录骨架与渐进式披露

这一节是核心。先给目录骨架，再给AGENTS.md入口文档模板，最后给客户端的 settings 配置片段。

目录结构建议这样组织，放在项目根目录：

project/ ├── AGENTS.md # 入口地图，几百词 ├── docs/ │ ├── architecture/ │ │ ├── overview.md # 架构概览 │ │ ├── frontend.md │ │ ├── backend.md │ │ └──># Agent 指南 本文档是你理解此仓库的入口。详细知识在 `/docs` 目录，按需查阅。 ## 知识库结构 - `/docs/architecture` - 系统架构设计 - `/docs/standards` - 编码和工程规范 - `/docs/guides` - 开发流程指南 - `/docs/api` - API 接口文档 - `/docs/decisions` - 架构决策记录 ## 核心原则（不超过 5 条） 1. 分层依赖：Types → Config → Repo → Service → Runtime → UI 2. 可观测性：所有服务输出结构化日志，含 requestId 3. 测试覆盖：新功能必须含单元测试和 E2E 测试 ## 开始任务 1. 先读 `/docs/guides/workflow.md` 了解流程 2. 架构疑问查 `/docs/architecture/overview.md` 3. 实现时遵循 `/docs/standards/coding-conventions.md` ## 重要提示 - 文档可能更新，发现不一致请重新读取相关部分 - 不确定时优先查 `/docs/architecture/overview.md`

这份入口文档只有几百词，但它给了智能体完整的导航信息。智能体接到任务后，先读地图，再决定去哪个模块取细节，而不是一次性加载全部内容。

接下来是客户端配置。以 Cline 的 MCP 配置为例，settings.json里要写全三件套：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "BASE_URL": "https://taotoken.net/api", "API_KEY": "sk-你的key", "MODEL_ID": "claude-sonnet-4-5" } } } }

如果你用 Codex，它读取auth.json，配置如下：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的key", "model": "claude-sonnet-4-5" }

Claude Code 的配置走环境变量或settings.json，关键是 Base URL 指向 TaoToken 的兼容端点，Key 和 Model ID 填对。CC Switch 这类切换工具也是同样的三件套逻辑：Base URL、Key、Model ID，一个都不能少。

配置完成后，智能体在启动时会加载AGENTS.md作为系统提示的一部分，但不会自动加载docs/下的所有文件。它需要主动去读——这就是渐进式披露的关键：把"读什么"的决定权交给智能体，而不是一次性灌给它。

4. 验证请求：确认智能体按需检索、上下文不膨胀

配置好之后，怎么确认渐进式披露真的生效了？不能只看它"能跑"，要看它"读了什么"。

第一步，发一个需要查文档的任务。比如："帮我给用户接口加一个分页参数，遵循项目规范。"观察智能体的行为链：它应该先读AGENTS.md，然后根据任务去读/docs/api/users.md和/docs/standards/coding-conventions.md，而不是把整个docs/目录都加载进来。

第二步，用模型对话入口做一次对照验证。在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 里，把AGENTS.md的内容作为系统提示，然后问一个具体问题，比如"日志格式规范是什么"。如果入口文档写得对，模型应该回答"请查阅/docs/standards/logging.md"，而不是直接编造内容。这说明地图在起作用。

第三步，检查上下文长度。在客户端的日志里看每次请求的 token 数。渐进式披露生效时，单次请求的上下文应该明显小于"把整个知识库塞进去"的方案。你可以做个对比：先跑一次全量加载，记录 token 数；再跑一次按需检索，记录 token 数。正常情况下后者会低不少。

第四步，验证文档园丁。在.agent/gardener.md里写一段提示词：

你是文档园丁。每天扫描 /docs 目录，检查文档描述与代码实现是否一致。 发现不一致时，生成修复建议并标记 TODO。 重点检查：API 字段名、配置项、代码示例。

然后让智能体执行一次扫描任务，看它能否发现你故意埋下的不一致。比如在docs/api/users.md里写返回{ "id": number, "name": string }，但代码里实际返回{ "userId": number, "fullName": string }。如果园丁能识别并报告，说明维护层也跑通了。

实测下来，这套组合的效果是：智能体不再"迷失"，因为它每次只面对当前任务相关的文档；上下文不再膨胀，因为地图和细节分离；文档不再腐烂，因为有园丁定期扫描。三个问题一起解决，而不是只解决一个。

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

配置过程中最容易踩的坑集中在认证和通道上。下面按真实报错逐个排查。

401 Unauthorized：最常见。先检查 API Key 是否复制完整，有没有多余空格。然后确认 Base URL 是不是https://taotoken.net/api，注意不要带 UTM 参数到 API 地址上。如果 Key 是在控制台刚创建的，确认没有误删。还有一种情况是 Key 权限不足，去 API Keys 页面检查该 Key 的可用模型范围。

local proxy failed：这个报错通常出现在客户端尝试走本地代理时。检查你的环境变量里有没有残留的HTTP_PROXY或HTTPS_PROXY指向了不可用的地址。如果有，清掉再试。另外确认客户端配置里的 Base URL 是直连 TaoToken 的地址，没有经过额外的转发层。

reading choices 相关报错：这类错误一般是响应格式不符合客户端预期。检查 Model ID 是否填对，不同模型返回结构可能不同。如果客户端期望 OpenAI 格式但模型返回 Anthropic 格式，就会在解析choices字段时报错。去接入文档确认该模型对应的端点路径，ClaudeCodeAnthropic 章节有说明： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=claudecode&utm_campaign=rewrite 。

OAuth 相关报错：如果你用的是需要 OAuth 的客户端，确认回调地址配置正确。有些客户端在 OAuth 流程中会校验 redirect URI，填错就会失败。这种情况建议先用 API Key 方式跑通，再切 OAuth。

排查顺序建议：先验证 Key 和 Base URL（用模型对话入口发一条消息），再验证客户端配置（三件套是否齐全），最后验证知识库加载（入口文档是否被正确读取）。每一步单独验证，不要混在一起调，否则很难定位是哪一层的问题。

6. 长期编码与 Agent 场景：把知识库当代码来管

渐进式披露不是一次性配置，而是持续维护的工程实践。当你把知识库拆成模块化文档后，下一步是把它当代码来管：文档变更走 PR 评审，文档和代码一起版本控制，定期检查链接和示例是否有效。

对于长期跑编码智能体的场景，Coding Plan 比按量调用更稳定，入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它适合每天都要调用模型做代码生成、文档维护、园丁扫描的任务。

文档园丁的提示词可以迭代。初期只做一致性检查，后期可以加入"检测过时配置项""验证内部链接""统一术语命名"等规则。每次园丁发现问题，生成修复 PR，人类只需确认或微调，而不是从零修复。

一个实用技巧：在AGENTS.md里加一条"文档新鲜度"提示，比如"如果发现文档与代码不一致，优先信任代码，并标记该文档待更新"。这样智能体在遇到冲突时有个明确的决策依据，不会在两个版本之间反复横跳。

最后，知识库的目录结构不是一成不变的。项目早期可能只有architecture和standards，随着规模增长再拆出api、decisions、guides。关键是保持入口文档始终精简，细节始终按需加载。地图可以更新，但不要让它变成第二本百科全书。