企业官网建设流程全解析

如果你最近在折腾 AI Agent，大概率会看到一组高频词：Skill、Wiki、Codex Skill、Claude Code Skill、Agent.md。刚接触时，很容易把它们理解成“一种提示词模板”或“一套插件机制”，好像只要把任务说明写清楚，模型就能稳定干活。但真正用过几次之后，你会发现一个更麻烦的问题：模型确实会做某一个具体任务了，可下次碰到一个稍微变化过的同类任务，它又像失忆一样从头开始，同样的问题再踩一遍。

这就是 WikiSkill 相关讨论最吸引我的地方。它给出的核心思路其实非常朴素：与其把经验放在模型参数里，不如在模型外面增加一个 Wiki 层，把跑通过的过程、失败过的原因、调整过的参数沉淀下来，再反过来提升 Skill 的执行效果。换句话说，Skill 负责“会做”，Wiki 负责“越做越懂”。这篇博客，我想把这个思路拆开，讲讲它到底解决了什么问题，怎么落到自己的 Agent 工作流里，以及哪些地方最容易踩坑。

1. WikiSkill 到底想解决什么问题

1.1 Agent 的“失忆”不是模型笨，而是缺少持久层

如果你让同一个模型连续执行三次完全相同的任务，但每次都开一个新会话，三次结果可能都不一样。这是当前很多 Agent 的真实状态：模型的能力摆在那里，但它缺少一个“上一回我是怎么做的”这样的持久化信息。

我们可以把一次 Agent 任务理解成一次临时合作：模型接到请求，结合系统提示、工具列表和当前上下文，生成动作序列，完成任务。这个过程里最像“记忆”的东西，其实是上下文里的历史消息。可一旦任务结束、上下文被清空，刚才的经验就不存在了。下一次继续执行类似任务，模型又得重新推理，重新试探参数，重新踩坑。

这解释了为什么很多人觉得 Agent 不够“聪明”。问题不一定出在模型推理能力，而是它没有一个稳定的经验参考层。人做熟悉的事情会越做越顺，是因为脑子会把过程固化成一种可调用的经验。Agent 目前默认状态下，恰恰缺少这个固化环节。

1.2 Skill 解决的是“怎么做”，但解决不了“这世界会变化”

为了改善这个问题，社区开始强调 Skill。你可以把 Skill 理解成一份写给模型的“操作手册”或“脚本”，里面写明任务目标、流程、工具用法、注意事项。Codex Skill、Claude Code Skill 这类实践，本质上都是把某一个任务领域的执行方法预置给模型。

Skill 的好处很明显，它能减少模型从零开始探索的成本。比如你给它一个“批量解析 PDF”的 Skill，它会知道第一步调用解析工具，第二步处理表格，第三步输出 Markdown。这比靠提示词临场发挥稳定得多。

但 Skill 也有一个硬伤：它是静态的。你把它写成什么样，模型就用什么样。如果依赖库升级了，如果输入数据的格式变了，如果某个参数在当前项目里必须调整，Skill 不会自动更新。你会发现，维护 Skill 本身变成了一种新负担：每换一个场景，就要手动改一份 Skill 文件；每出现一种新情况，就要重新设计流程。

我并不是说 Skill 没有价值。它解决了一个很重要的问题，就是把无结构的任务变成有结构的执行路径。但它没有解决另一个问题：经验如何随任务持续积累。一个静态手册，没办法自动记住“昨天那次失败是因为表格里有多余表头”。

1.3 WikiSkill 的切入点：把经验当作一等公民

WikiSkill 的做法，可以理解成在 Skill 之外再增加一个 Wiki 层。Skill 负责写清“任务应该怎么做”，Wiki 负责记录“这个任务在我们这里实际是怎么跑通的”。

这两个东西的差别很关键。Skill 更像产品说明书，描述的是通用设计；Wiki 更像工作日志，记录的是发生在这个环境里的真实案例。真实案例里有环境变量，有失败原因，有最终选用的参数，有验证方式。这些信息恰好是模型容易缺失的。

把经验当作一等公民之后，整个 Agent 系统的结构就变了。原本是“模型 + 工具 + 静态 Skill”，现在变成“模型 + 工具 + 静态 Skill + 可增长 Wiki”。任务开始时，Agent 可以先检索 Wiki 里有没有相似经验；任务结束后，把新经验写回 Wiki。这样 Skill 不再只是一个固定文件，而会随着 Wiki 条目的积累，逐渐被修正和丰富。

从公开讨论来看，WikiSkill 的价值并不是发明了某种复杂算法，而是给 Agent 增加了一个非常轻量的反馈闭环。它提醒我们：单次执行能力再强，如果经验不能复用，那 Agent 永远只是一个需要手把手教的新人。

2. Wiki层和Skill层是怎么协作的

2.1 我的理解：Skill是“肌肉记忆”，Wiki是“工作日志”

用一个类比来理解两层协作：Skill 像吉他手练熟的和弦手型，弹奏时不需要每次重新思考手指位置；Wiki 像乐手随身带的曲目笔记，上面写着某首歌哪个段落容易卡顿、变调夹放在第几品、现场演出时哪一段要提前和鼓手对齐。

演奏时，肌肉记忆负责稳定输出；遇到新曲子或新调式时，就要靠笔记快速定位关键经验。Skill 和 Wiki 的关系也是这样。Skill 给模型提供了相对稳定的执行动作；Wiki 给模型提供了“在这个具体环境里，哪些做法被验证过”的补充信息。

在实际编排里，我会把两者分得很清楚：

• Skill 文件：包含任务名称、描述、步骤、工具调用顺序、默认参数。它相对稳定，只在流程有明显改进时才更新。
• Wiki 条目：包含具体任务特征、输入样例、遇到的异常、最终解法、验证结果、时间戳。它随时可以追加和修正。

如果只有 Skill，Agent 知道“怎么做”，但不知道“这次做的时候特别要注意什么”。如果只有 Wiki，Agent 有一堆经验笔记，但没有稳定的执行框架，每次读取都可能跑偏。两层合在一起，才像是一个有经验的老手在工作。

2.2 写入链路：什么时候值得写进Wiki

一条重要的原则是：不是所有中间过程都值得写进 Wiki。如果什么内容都往里塞，Wiki 很快就会变成一个无法检索的垃圾桶，到时模型读了三分钟还找不到有用信息。

我一般会让一条经验进入 Wiki 前过三道闸：

1. 可复现：这次结果是稳定复现的，还是偶然成功的？如果只是运气好，先标记为“待验证”。
2. 可更新：这次经验是否修正了已有 Skill 步骤，或者发现了某个参数的新边界？如果只是大段复制粘贴已有文档，不写。
3. 可检索：这条经验能不能被后来的任务快速找到？如果没有明确的任务类型、关键词和环境标记，就先别急着写入。

通过三道闸的内容，可以按一个相对固定的格式记录。一个简化示例：

title: "批量 PDF 转 Markdown 时扫描件识别失败的调优记录" tags: [pdf, markdown, batch, ocr] status: verified 适用场景: 输入: "100份PDF，混合文本版和扫描版，文件名包含batch标记" 失败原因: "扫描版PDF未开启OCR，表格文字全部丢失" 最优参数: batch_size: 8 ocr: true output_dir: "./output/markdown" 验证方法: "随机抽取5份扫描件，确认表格和标题正常" 更新时间: 2025-06-10

这套字段的意义不只是给人看，更是为了让检索时更容易被匹配。模型可以先通过tags和适用场景缩小范围，再读取完整的处理经验。

2.3 检索链路：先缩小范围，再让模型阅读

很多 Agent 项目失败，不是因为没写 Wiki，而是因为让模型“把所有 Wiki 都读一遍”。当 Wiki 逐渐变大，全量读取既浪费 token，又会引入大量不相关信息，干扰模型判断。

我认为 Wiki 检索应该是一套三级路由：

1. 任务类型路由：先判断当前任务属于哪个领域。是 SQL 任务，还是文档解析，还是网络抓取？
2. 标签路由：在该领域内，通过标签和关键词过滤候选条目。比如pdf, ocr, batch。
3. 条目级精读：只让模型阅读一两个相关条目的完整内容，并在上下文里生成一段“经验摘要”，而不是一口气把所有文档都交给模型。

如果项目里已经有 Agent.md 这类总入口，可以把 Wiki 索引放在这里。模型在执行任何任务前，先读取总入口，里面有各领域 Wiki 条目的索引和优先级说明，然后按需加载具体条目。这样可以让检索消费的上下文更可控。

2.4 更新机制：经验不是越多越好，要定期治理

Wiki 层如果没有更新机制，过一段时间会变成“一潭死水”。某个条目可能上个月还是最优方案，这个月因为依赖升级已经失效了；某个步骤可能只在特定目录结构下成立，换一个项目就完全不适用。

我建议给 Wiki 条目设计状态：

• verified：经过至少两次不同任务验证，可以稳定使用。
• draft：只成功过一次，需要后续任务进一步确认。
• stale：超过一段时间没被检索，或者被标记为“疑似过期”。
• archived：已经确认不再适用，但保留原因，避免后人重复踩坑。

每次任务结束后，不一定要立刻写新条目，也可以先检查现有条目是否还成立。如果这次执行发现参数变了，就更新对应条目；如果发现旧方案被推翻，就把状态改成stale并写清原因。

这些机制听起来有点重，但只要在一开始就定好状态和更新规则，后面维护成本反而低。最怕的是“写了一次就再也不动”，那样 Wiki 很快会失去意义。

3. 把WikiSkill落到自己的Agent工作流

3.1 先不要设计宏大系统，先跑通一次最小闭环

很多人看完 WikiSkill 的思路，第一反应是“我要做一个团队知识库，让所有 Agent 都能从 Wiki 中学习”。一旦这样想，项目多半会卡在目录设计、权限控制、标签体系这些前期工程上，迟迟看不到效果。

更务实的做法是先跑通一次最小闭环。比如你手里有一个 Agent 经常要处理 SQL 查询历史数据，那就先做一个任务：让 Agent 查某个月份的订单汇总。手工把一次成功的执行过程记录下来，写成一个 Wiki 条目，再修改一个 Skill 文件，让 Skill 在执行前先读取这条 Wiki 经验，然后用第二个类似查询去验证。

注意：不要一上来就设计完整的目录结构。两个目录、三个字段、一个验证标准，足够开始。

最小闭环的意义在于，你可以快速验证“Wiki 到底有没有用”，而不是验证“我的知识库管理得是否规范”。如果第二条查询确实因为参考了第一条经验而更稳定，再考虑扩大范围才有说服力。

3.2 Wiki条目的组织方式：可以从Agent.md和LLM Wiki中借鉴

现在很多 Agent 工具都在推agent.md标准模板，核心目的就是给模型一个固定入口，让它知道项目里有哪些约定。Wiki 层可以借这个思路，把“经验索引”也放进出入口文件。

一个比较顺眼的目录结构长这样：

project/ AGENTS.md skill/ sql-agent/ SKILL.md wiki/ sql-agent/ 20250610-order-summary-join.md 20250611-partition-filter-best-practice.md

入口文件AGENTS.md里可以写明：

# 项目约定 - 涉及 SQL 分析任务前，先读取 wiki/sql-agent/ 下的相关条目。 - 如果任务特征与已有条目不匹配，执行完毕后新增一条经验。 - 更新 wiki 时，保留旧条目的失败原因，不要覆盖。

这么做的好处是，模型不用每次都猜测“经验放在哪里”。它有一个明确的路径，先看索引，再按需读取。对人类读者来说，这个目录也很直观，不会出现“文档和代码混在一起找不到”的问题。

3.3 Skill文件里如何引用Wiki

Skill 文件本身不需要写得越来越长。相反，Skill 文件应该保持精炼，把容易变化的内容交给 Wiki。我一般会在 Skill 文件头部写明“使用前检索 Wiki”，然后列出最小执行步骤。

一个示例是：

--- name: sql-agent description: 处理 SQL 查询和报表生成 runbook: - 读取 wiki/sql-agent/ 下的经验索引 - 匹配与当前请求最相似的条目 - 按条目标记的参数和注意事项执行 - 结束时更新 wiki 对应条目 defaults: model: "由用户指定" output_dir: "./output"

这里很重要的是：Skill 不绑定某一个具体经验，而是绑定“经验查找方式”。这样 Skill 才能保持稳定，Wiki 才能持续变化。如果每次更新经验都要修改 Skill，两层就分不开了，最终又回到“手动改配置”的老路。

3.4 同步更新Skill和Wiki的操作顺序

我见过一种常见失败：任务跑得不错，但没有记录；等到想写 Wiki 时，细节已经忘了。因此我建议把“任务后复盘”变成流程的一部分，顺序放在执行之后、结束之前。

复盘可以简单走四步：

1. 这次发生了什么？比如“输入文件里出现了扫描版 PDF，导致表格丢失”。
2. 哪里没预料到？比如“之前默认所有 PDF 都是文本版”。
3. 下次怎么做？比如“增加 OCR 步骤，扫描版自动识别”。
4. 哪些内容写进 Wiki？把结果写入对应条目，并更新 Skill 的默认参数或检查项。

实际操作中，第 4 步不一定每次都改 Skill。只有当“执行步骤本身需要变化”时，才更新 Skill；如果只是参数调整，更新 Wiki 就够了。这样职责清晰，也能避免频繁改动 Skill 导致不稳定。

4. 常见的坑和排查路径

4.1 误区一：把Wiki当成资料库，而不是经验库

很多人听到“Wiki”，第一反应是把官方文档、教程、产品资料全放进去。这其实跑偏了。WikiSkill 关注的是“经验”，而不是“知识”。

我理解里的经验库有两个明显特征：

• 包含具体环境信息，比如“这个方案只在 Linux 环境下验证过”。
• 包含失败和修正过程，比如“一开始用read_pdf直接解析，结果扫描件乱码；换成 OCR 后解决”。

如果 Wiki 里全是“什么是 SQL”“什么是 PDF”这类通用知识，模型本来就知道，模型不会因此变强。真正能提升效果的，是那些“不在通用教材里，但在这个项目里反复踩坑”的本地经验。

4.2 误区二：让Agent每次从头到尾读Wiki

有一些实现为了让模型“不遗漏信息”，会把整个 Wiki 目录下所有 Markdown 文件都拼进上下文。当 Wiki 条目还少时，这样做问题不大；一旦超过几十个文件，模型就会在无关信息里迷失，甚至把旧条目的过时参数当成当前推荐值。

更合理的方式永远是先检索、再精读。如果当前任务不涉及 PDF，就不需要读 PDF 条目；如果当前任务使用的是另一个模型或工具，也应先过滤掉不属于该环境下的经验。

提醒：如果发现 Agent 输出结果里出现了与当前任务无关的旧参数，第一反应不应该去调提示词，而应该检查检索环节是不是把不相关条目也喂给了模型。

4.3 排查链路：任务效果没提升时先查哪里

当 Wiki 已经存在但效果不明显，我建议按下面顺序排查：

这个顺序很重要。大多数情况下，问题不在模型能力，而在入口、检索或内容质量。先看日志确认模型到底读没读，再谈优化路径，而不是盲目把 Skill 文件加长。

4.4 如何验证Wiki确实提升了Skill效果

验证是很容易被跳过的环节。有人写完 Wiki 后凭感觉说“好像稳定了”，但实际上可能只是这次任务本身比较简单。

我建议做一个简单的对比测试，用同一批任务跑三组：

每组至少跑 5 次，任务难度要基本一致。观察的关键指标不是“模型看起来更聪明”，而是成功率、耗时的稳定性以及人工介入频率是否下降。如果三条结果差异不大，要么是 Wiki 条目内容质量不够，要么是这个任务领域本身不需要额外经验，不用硬撑。

5. 适用边界与长期工程化

5.1 什么场景值得用，什么场景先别用

WikiSkill 不是所有 Agent 任务的银弹。它更适合那些“任务边界清晰、结果可验证、需要多次重复”的场景。

适合的场景：

• 企业报表生成：同样的查询逻辑，不同月份不同业务线反复跑。
• 数据清洗与格式转换：输入格式有少量变化，但处理路径大体一致。
• 代码库维护：Agent 需要遵循项目的代码规范、目录结构和历史约定。
• 领域型文档处理：不同批次文档存在固定类型的差异，需要积累处理规则。

不适合的场景：

• 一次性闲聊或问答，不需要长期记忆。
• 高度开放、没有明确成功标准的创意任务，经验很难标准化。
• 任务只需要调用一次，且不需要重复的场景，Wiki 反而增加维护成本。

另外要意识到，Wiki 的维护本身也是成本。初期写一条经验可能比直接跑一次任务还慢。所以如果任务量很小，或者任务变化无穷，建议先不要强行引入这套机制。

5.2 从个人实验到团队协作：难点主要在人和规范

一个人用 Wiki 层，可以靠自己的手感维护。但团队协作时，核心难点不是技术，而是规范。如果没有约定，不同成员写出的 Wiki 条目可能风格完全不一样：有人写明参数，有人只写“我已经解决了”，还有人会顺手删掉别人的条目。

我建议团队引入一个非常轻的规则：每条 Wiki 至少包含“场景描述、解决步骤、验证方式、负责人”。更新时不要直接覆盖旧条目，而是追加“新发现”，把旧内容标记为历史记录。这样既能保留线索，也避免互相覆盖。

版本控制是必须的。Wiki 目录应该纳入 Git 管理，提交信息里写明改动原因。一旦 Agent 因为某条旧经验出错，你可以快速回滚到上一个版本，找到是哪个改动引入了问题。

5.3 长期使用必须补的工程能力

如果想把 WikiSkill 变成 Agent 基础设施的一部分，除了写作规范，还需要补几块能力：

1. 自动捕获执行日志：Agent 每次调用了什么工具、传了什么参数、返回了什么错误，这些原始数据是 Wiki 条目的重要来源。
2. 检索质量评估：定期检查“模型读取了哪些 Wiki 条目，最终结果是否成功”。如果某个条目被读了但结果仍然失败，要标记为待优化。
3. 条目去重和过期清理：时间久了，同一个问题可能被记录三次。需要定期合并相似条目，标注状态为stale或archived。
4. 权限控制：如果 Wiki 里有内部指标、敏感查询逻辑或客户信息，不能把所有内容都开放给所有任务。至少要按领域或角色控制读取范围。
5. 写入冲突处理：多个任务同时执行时，可能同时更新同一个 Wiki 条目。需要一个简单的“锁”或“最后写入有效”机制，避免互相覆盖。

这些能力并不需要一次全部实现。个人项目可以先只做日志和更新两个环节，等确实进入重复批量使用阶段，再逐步补全。

5.4 我的判断：Agent的进化不靠模型参数，靠外部经验系统

最后说回 WikiSkill 给我的整体判断。过去我们总认为，让 Agent 变强，无非是换一个更大的模型，或者写一段更长的提示词。但 WikiSkill 提供了一个不同方向：模型的参数不变，外部环境多了一层可增长的经验系统，Agent 也能越来越熟练。

这个思路真正的价值，是把 Agent 从“单次执行工具”变成“可持续积累的经验执行器”。Skill 解决的是“怎么执行”，Wiki 解决的是“怎么记下执行中的知识”，合在一起，就是一个最简化版本的学习闭环。

如果你也想尝试，不要急着复刻什么复杂组件。先选一个你手里最常做的任务，准备一个空目录，跑通一次，写下第一条经验，再跑第二个类似任务，对比看看结果是否更稳定。只要完成这一轮闭环，你就能真切感受到这个结构的价值。后面的事情，一步一步再说。