为 Mika 编写百度贴吧站点知识:从 SITE.md 到 Agent 可消费的网页说明书

原创2026-10-31 14:26:091,857 阅读
文章标签:AI 应用AI AgentGUI 自动化移动开发交互助手大模型

为 Mika 编写百度贴吧站点知识:从 SITE.md 到 Agent 可消费的网页说明书

在 Mika 这类端侧 AI Agent 中,“能不能把网页用对”往往不取决于模型大小,而取决于它是否事先知道这个网站的入口长什么样、哪些路径可用、哪些页面会骗人。core/src/main/resources/knowledge/sites/tieba.baidu.com/SITE.md 就是一份面向百度贴吧的站点知识文件:它用几十行纯文本,把贴吧的搜索地址、吧页面地址、功能边界和几个典型“看起来像结果、其实不是”的现象固定下来。本文以这份文件为主线,逐字段拆解它的写法,并沿着 Mika 的源码链路说明这份文件如何被构建期校验、如何在运行期注入模型上下文、如何与浏览节奏(pace)和桌面版/手机版页面选择相互配合,最终给出一套可复用的站点知识编写与验证方法。

一、这份文件到底写了什么:先看完整内容

贴吧的站点知识全文只有一段 YAML 头部加四个正文小节,属于“短、硬、只写事实”的典型写法:

---
name: tieba.baidu.com
display: 百度贴吧
description: 查老型号和小众话题的使用经验、通病讨论帖
domains: ["tieba.baidu.com"]
aliases: ["贴吧", "百度贴吧"]
apps: []
open: tieba.baidu.com
mode: desktop
---
## 是什么
百度的社区论坛,按「吧」分话题。老型号、长尾话题的长期使用、维修和反复出现的问题讨论多,但老帖不反映当前售价和政策。

## 页面与网址
- 搜索 `https://tieba.baidu.com/f/search/res?qw=<编码后的关键词>`,可能要登录。
- 进具体的吧 `https://tieba.baidu.com/f?kw=<编码后的吧名>`,不登录也能看帖子列表。置顶帖常是吧规和定期汇总(装机吧、显卡吧每月一期装机推荐)。

## 功能
- **搜索**:结果有帖子链接、吧名和日期;没有可用的时间筛选参数。
- **帖子**:原帖和跟帖里有具体使用经历,包括型号、批次、故障、使用时长、修复过程。

## 已知现象
- 不存在的吧也会显示「<名字>吧」的页面,但没有帖子;零帖子就是这个吧不存在。
- 搜索页显示「木有找到相关内容」后,下面的热门吧、签到、「我常逛的吧」是导航,不是搜索结果。
- 同一故障出现在多个回复里,可能是转述或同一个案例。
- 偶尔出现安全验证。

文件路径见 SITE.md。它没有 pace、没有 links、没有 接口 小节,apps 是空数组——这些“没写”的部分同样是有信息量的,后面会逐一说明。

从内容组织上看,这份文件严格遵循了 Mika 的知识格式约定:SITE.md 只回答“这个网站是什么、页面和网址怎么组织、有哪些功能、能看到什么”,不写“该怎么做”“先点哪里”“不许怎样”这类行为规定,行为方法归到技能(SKILL.md)。完整的格式说明见 docs/knowledge-format.md。

二、头部字段逐项解读

Mika 的头部解析器非常克制:只认 key: value、key: <a href="https://link.gitcode.com/i/881485ac8e37363534da3ea095369513" target="_blank">a, b] 和带引号的字符串,值是 String 或 List<String>,不支持嵌套结构,也没有多行值。实现见 [FrontMatter.kt。这意味着头部必须写得扁平、可直接解析。

字段 贴吧文件里的值 作用与约束
name tieba.baidu.com 必须与目录名一致;站点必须是它的主域名(小写),并且必须出现在 domains 里
display 百度贴吧 展示名,注入上下文时作为标题的一部分
description 查老型号和小众话题的使用经验、通病讨论帖 一句话说明,最多 60 个码点(DESCRIPTION_LIMIT)
domains ["tieba.baidu.com"] 主机名匹配用;会统一转小写并去掉开头的 www.
aliases ["贴吧", "百度贴吧"] 用于 knowledge_search 的模糊检索与任务开头的渠道匹配
apps [] 关联的 App 知识名;这里显式声明“没有对应 App 条目”
open tieba.baidu.com 打开这个网站时使用的地址
mode desktop 页面版本,只允许 desktop / mobile

这些约束不是文档层面的“建议”,而是构建期强校验。KnowledgeIndex.parse 在 KnowledgeIndex.kt 中逐条检查:头部缺失、name 与目录名不一致、display 缺失、正文为空、正文超过 2500 字、description 超过 60 字、站点目录名不是主域名小写形式、domains 为空或未包含 name、mode 不在允许集合内、头部出现不认识的键——任何一条都会让构建失败,而不是被静默忽略。头部允许的键集合定义在同文件的 KEYS 中,pace 的合法值集合是 PACES = setOf("careful")。

还有一条容易被忽略的约束:terms 只有技能能写,App 和网站一律用 aliases。贴吧文件里正好没有 terms,符合规则。

apps: [] 说明了什么

apps 表示“同一个服务的另一种运行面”。对比 知乎站点知识 里的 apps: <a href="https://link.gitcode.com/i/d73935c07f43de20767dddc91bc86e78" target="_blank">"zhihu"]:它把网站条目和 knowledge/apps/zhihu/APP.md 关联起来,交叉校验还要求 App 条目的 sites 反向写上该域名,缺一边就报错(见 crossCheck,[KnowledgeIndex.kt)。

贴吧写 apps: [],等于明确声明“Mika 里没有与之配对的 App 知识条目”。因此 KnowledgeEntry.service 在站点条目上会退回到 name 本身,ChannelAdvisor 生成的“可用渠道”一行也就只会出现网页渠道,不会凭空给出一个“App:已安装”的说法。这比留空或随口写一个不存在的 App 名要诚实得多——写错会直接在构建期失败。

mode: desktop:记录页面版本,而不是强制

mode 是站点知识里的一条事实:这个网站的页面按桌面版组织。运行期模型看到的运行时状态会带上这一信息,ContextBuilder.runtimeState 里把它渲染成“(桌面版)/(手机版)”,见 ContextBuilder.kt。

真正切换页面版本要调用 web_site_mode 工具:页面默认以桌面版打开,切到手机版(或切回桌面版)后重新加载,选择按站点记住,早期元素引用会失效。相关提示词在 prompts/tools/web_site_mode.md。记住逻辑落在 App 侧 SiteModes.kt:按主机名记录、去掉 www.、子域名跟随上级域名,写进 App 私有目录的 site_modes.json,读到坏文件时从空表开始。

换句话说,头部 mode 表达的是“这个站点适合哪种页面”的静态事实;实际标签用的是哪一版,由浏览器回报。贴吧写 desktop,与它“按吧分话题、帖子列表信息密度高”的形态是吻合的;如果某次桌面版在手机上难以阅读,模型仍可以按提示词把当前标签切到手机版。

三、正文四小节的功能分工

1. 是什么:给出判断边界

百度的社区论坛,按「吧」分话题。老型号、长尾话题的长期使用、维修和反复出现的问题讨论多,
但老帖不反映当前售价和政策。

这一段承担了两个作用:说明站点性质(按“吧”组织的论坛),以及预先声明证据边界(老帖不可用于当前售价与政策)。这正是 Agent 在“查一件商品值不值得买”时最容易犯错的点——把三年前的讨论当成今天的行情。

按格式约定,SITE.md 的正文上限是 2500 字,所以这类“是什么”必须压缩到一两句,不能写成站点介绍长文;大段资料(站点代码表、网址格式、搜索语法)应当放到 references/ 附件里,正文只写“什么时候去读哪个附件”。贴吧这份文件没有附件,说明它需要记住的内容量本身就很小。

2. 页面与网址:两个可直接拼装的入口

  • 搜索:https://tieba.baidu.com/f/search/res?qw=<编码后的关键词>,可能要登录;
  • 吧页面:https://tieba.baidu.com/f?kw=<编码后的吧名>,不登录也能看帖子列表。

这两条是这个文件里最有工程价值的部分。它们把“怎么进入”从自然语言猜测变成了可拼装的 URL 模板:qw 和 kw 两个查询参数名被原样保留,关键词需要做 URL 编码(格式文档要求“包名、域名、网址、接口地址、字段名这些事实原样保留”)。Agent 拿到的不是一个可以自由发挥的目标,而是一个确定的前缀加参数。

同时它还标注了登录状态差异:搜索可能被登录墙拦截,而吧页面在未登录状态下仍可浏览。这一条直接影响工具选择——如果搜索页被登录墙挡住,web_read_page 的结果会给出 needs_sign_in 之类的判定,此时按“吧名直连”往往比继续在搜索页上折腾更有效。

最后一句是站点特有的“内容分布事实”:置顶帖常是吧规和定期汇总,例如装机吧、显卡吧每月一期的装机推荐。它解释的是“为什么有些帖子看起来不像正文”,而不是“你应当去读置顶帖”。

3. 功能:说清能拿到什么字段

  • 搜索:结果包含帖子链接、吧名和日期;没有可用的时间筛选参数。
  • 帖子:原帖与跟帖含有具体使用经历,包括型号、批次、故障、使用时长、修复过程。

“没有可用的时间筛选参数”是一条否定式事实,价值不低于肯定式事实。它提前堵住了 Agent 反复尝试 &time=、&sort= 之类参数的行为。作为对照,微博站点知识 就明确写出了 timescope=custom:YYYY-MM-DD:YYYY-MM-DD 这样的时间范围参数;贴吧没有等价能力,于是直接写明“没有”,而不是留白让模型自己试。

“帖子”一条实际上是在告诉模型:这里的价值单元是长尾经验,字段是型号、批次、故障、时长、修复过程。这决定了后续结论该怎么写——可以引用具体经历,但不能把这些经历当成统计结论。

4. 已知现象:把“陷阱”写成现象

四条现象全部是可观察的界面行为,而不是指令:

  1. 不存在的吧也会显示「<名字>吧」的页面,但没有帖子;零帖子就是这个吧不存在。
  2. 搜索页显示「木有找到相关内容」后,下面的热门吧、签到、「我常逛的吧」是导航,不是搜索结果。
  3. 同一故障出现在多个回复里,可能是转述或同一个案例。
  4. 偶尔出现安全验证。

第 1、2 条针对的是同一类错误:把导航区当成结果区。Mika 的 web_read_page 会把导航、页脚等链接块折叠成一行 <<collapsed …>>,并给出文本密度与 verdict(如 thin、needs_sign_in、refused)等质量信号,说明见 prompts/tools/web_read_page.md。当一个不存在的吧返回“有页面、零帖子”时,正文很少但页面并非错误页,模型必须依赖站点知识才能判断“零帖子 = 吧不存在”,而不是“需要继续滚动加载”。

第 3 条是证据去重问题:多个回复提到同一故障,可能只是转述。它和通用调研技能里“同一篇通稿会被很多网站转载,看起来来源很多,其实只有一个出处”的判断是同一类,但在这里被下沉为站点事实。

第 4 条“偶尔出现安全验证”解释了偶发的失败:这类结果不是“内容不存在”,而是需要换时机或交给用户。注意它没有写成 pace: careful——因为 careful 的含义是“这个网站限制一个访客浏览的快慢,翻页或点开详情太快太多会被拦”,而这里描述的是偶发验证,不是稳定的频率限制。这种区分很重要:pace 会实际改变浏览节奏与页数上限,写错会带来可测量的代价。作为对照,BOSS直聘站点知识 就明确写了 pace: careful。

四、从文件到模型:这份知识是怎么被用上的

理解了写作规范,还需要知道它进入模型的路径,否则很容易写出“人看着有用、机器读不到”的内容。

1. 构建期:扫目录、校验、生成索引

运行时无法枚举资源目录,所以 Mika 在构建时扫一遍三棵树(knowledge/apps、knowledge/sites、skills),校验头部后生成 knowledge/index.json。Gradle 任务定义在 core/build.gradle.kts:输入是两个资源目录,输出是 generated/knowledge-index/knowledge/index.json,主类是 KnowledgeIndex,校验不过就以非零状态退出,从而让构建失败。

这一步同时做了跨条目检查:名字不能重复、同一个包名不能被多个 App 声明、同一个域名不能被多个站点声明、apps / sites 的互相引用必须双向存在、正文里提到的 references/… 附件必须真实存在、任何文件里不能出现 /Users/ 这样的本机路径。因此贴吧条目里的 apps: [] 不会被误判成“引用了不存在的条目”。

2. 运行期:按域名匹配,最具体的域名优先

进入网站后,KnowledgeStore.byDomain(host) 负责找到对应条目,内部走 SiteMatch.best:主机名等于某个域名或是它的子域名即算命中,多份命中时取匹配到的域名最长的那个(例如 shop.example.com 优先于 example.com),并列时全部保留。实现见 SiteMatch.kt 与 KnowledgeStore.kt。匹配前会去掉 www.,所以 www.tieba.baidu.com 与 tieba.baidu.com 命中同一份知识。

这也解释了为什么 domains 字段必须包含主域名,而 name 必须等于目录名:目录名、主域名、匹配键三者是同一件事。

3. 什么时候注入:四个“到达站点”的动作

注入不是每步都发生。NoticePolicy.knowledgeAfter 定义了规则:当当前位置是站点,且刚执行成功的是 observe、list_elements、navigate、read_page 之一时,就按主机名去找站点知识;主机名会被转成小写并去掉 www.。实现见 NoticePolicy.kt,调用点在 AgentLoop.kt。

同一份站点知识在一个任务里只注入一次:AgentLoop 用 visitedSites 记录已经查过的 host,ContextBuilder 再用 (name, surface) 去重。这带来一个直接的写作后果——站点知识要在第一次进入时就能提供全部关键信息,不能指望“模型看到第二页时再补一段”。

4. 注入成什么:带可信度标签的参考资料

注入后的内容不是以系统提示词的身份出现,而是一段带 kind、source、trust 的上下文块。ContextBuilder.knowledgePiece 把站点头部渲染成“展示名 + 主机名”的标题,正文放在 <context kind="site_knowledge" …> 里,可信度标签是“参考资料:可能过时,以当前读到的内容为准”。实现见 ContextBuilder.kt。

这条设计决定了站点知识的语气:它是参考事实,不是命令。也正因为标了“可能过时”,贴吧文件里那句“老帖不反映当前售价和政策”才显得必要——它把“过时”这个抽象风险落到了具体字段上。

注入还有预算约束:每个任务最多注入 3 份 App/站点参考资料(maxKnowledge),单份正文最多 4000 字,超出会截断并附上“可用 knowledge_read 查看全文”的提示;知识层的总预算是 10000 字,整体 16000 字,裁到不足 300 字就整份不给。参数见 ContextBuilder.kt 与同文件的 ContextBudget。贴吧这份正文只有两百多字,远低于上限,属于“一次注入、长期有效”的理想形态。

5. 主动查阅:knowledge_search / knowledge_read

除了自动注入,模型还可以主动查。knowledge_search 接受 query(1–200 字)与可选 kind(app / site),最多返回 10 条 {name, display, kind, description};knowledge_read 接受 name(可写成 app:<id>、site:<域名>)与可选 file_path,用于读取附件,单次最多返回 12000 字。实现见 LookupTools.kt 与 GuideCatalog.kt。

对贴吧来说,一个典型调用是 knowledge_read(name="site:tieba.baidu.com")。如果名字写错,返回的是明确的 knowledge_not_found 并提示改用 knowledge_search;如果名字其实属于技能,会提示改用 skill_read;如果同名既有 App 又有站点,则要求写成带前缀的形式。这些错误分支在 GuideCatalog.view 中定义,写作时把名字写准,能省掉一轮试错。

读取结果还会带上 files 列表与脚本信息。贴吧条目没有 scripts/,也没有 references/,所以 files 只有主文件本身。

6. 浏览节奏:没有 pace 意味着什么

pace 是站点知识头部里唯一会直接改变运行时行为的字段。默认参数在 PagePacing.kt:一个站点的第一页不停留;从第二页起,停留时长在 4–7 秒内随机;同一时间窗(10 分钟)内看得越多,上下限各加 600–1000 毫秒,最多 12 秒;每个任务里同站点最多 20 页,用户答话后重新计数。

写了 pace: careful 的站点改用 Limits.CAREFUL:首屏停留 10–16 秒,上限 30 秒,页数上限降到 12 页。判定逻辑在 PagePacing.kt:SitePace.of(value) 只在值等于 careful 时返回 CAREFUL,其余情况一律 NORMAL。站点知识的 pace 通过 GuideCatalog.sitePace(host) 读出,认站点的规则与注入时完全一致——同一份 SiteMatch,不会出现“注入的是这份、计节奏的是另一份”的错位,见 GuideCatalog.kt。

贴吧没有写 pace,因此按普通站点处理。此外还有两条与“上限”有关的例外:本任务在该站点做过对外动作(发送、提交一类)之后,页数上限不再生效;waitBefore 只在最近一页来自同一站点时才补足停留时间,去另一个网站从第一页算起。

五、把这份文件与技能接起来

站点知识只写事实,方法归技能。内置技能 info-research 在头部 sites 里点名了 tieba.baidu.com,在第 3 步“补体验和反面”里写明:真实使用感受看社区和视频平台,问题看投诉平台,并专门搜一次反面的词。这就是两者的正确分工:

  • 技能回答“查一件事的通用流程是什么”;
  • 站点知识回答“贴吧的搜索 URL 长什么样、哪些页面会骗人”。

反过来的写法是错的:SITE.md 里不能出现“按 XX 技能”这样的交叉引用——格式约定明确要求“App/网站说明里不出现『按 XX 技能』”,交叉校验也会检查文中提到的 app: / site: / skill: 引用是否存在。技能可以点名站点,站点不点名技能,方向是单向的。

技能与站点的关联在运行期也会体现:当进入某个站点并注入其知识时,GuideCatalog.linkedSkills(name) 会找出所有在 apps / sites 里点名它的技能,把索引行补进上下文的技能索引,已列过的不再重复。因此把 tieba.baidu.com 写进 info-research 的 sites,实际效果是“进了贴吧,模型能顺手看到这条调研技能”。

六、验证:怎么确认改动真的生效

Mika 用构建期校验加单元测试双重兜底。

构建期:./gradlew :core:test :app:testDebugUnitTest 会触发索引任务;只要头部有任何一处不合规,索引任务失败,构建即失败,错误信息会带上相对于资源根目录的位置,例如 knowledge/sites/tieba.baidu.com/SITE.md: description 超过 60 字。

测试期:BundledKnowledgeTest.kt 会把校验再跑一遍,并核对类路径上的索引与按当前文件生成的索引完全一致(防止改了文件忘了重新生成)。它同时断言了当前内置规模:app 18 份、site 12 份、skill 4 份,以及每份条目都有正文且不超过 2500 字。另一个用例 sitePaceFollowsTheSiteKnowledge 直接验证 www.zhipin.com 读出 careful、未知域名读出 null,可以用来确认 pace 链路是否通畅。

对贴吧这类没有 pace 的站点,还可以用 KnowledgeStoreTest 里的域名匹配用例思路自测:www.tieba.baidu.com 与 tieba.baidu.com 应命中同一条;m.tieba.baidu.com 之类的子域名按子域名规则同样命中主条目。这些行为由 SiteMatch 保证,不需要在文件里额外声明。

七、可复用的站点知识编写清单

把上面的分析收成一份可操作的清单,写新站点或修改贴吧条目时逐条对照:

  1. 目录名就是主域名:knowledge/sites/tieba.baidu.com/SITE.md,name 必须完全一致且小写;domains 必须包含它。
  2. description 控制在一句话、60 字以内:它同时是 knowledge_search 的检索依据和列表展示内容。
  3. aliases 写用户可能说出的叫法:贴吧写了“贴吧”“百度贴吧”,这是任务开头匹配的主要依据。
  4. mode 必填,只能是 desktop / mobile;只在确有必要时才写 pace: careful。
  5. apps 只在真有配对条目时写,并且对端 APP.md 的 sites 必须反向写上;没有就写 []。
  6. 网址模板原样保留参数名,关键词用 <编码后的关键词> 这类占位符标明需要 URL 编码,登录要求单独标注。
  7. 否定式事实要写出来:“没有可用的时间筛选参数”能直接省掉无效尝试。
  8. 现象写成现象:写“不存在的吧会显示页面但没有帖子”,不写“不要相信空页面”。
  9. 正文控制在 2500 字内,大段资料放 references/,并在正文里写清何时去读哪个附件。
  10. 不写行为规定、不引用技能、不写运行时不用的元数据(如 risk、status、updated、verified_on,写了会构建失败)。
  11. 改完跑测试:索引任务与 BundledKnowledgeTest 会一起确认文件合规、索引最新、条数符合预期。

八、边界与时效:这份知识不能替你做什么

最后需要强调这份文件自身的限制,这也是它诚实的地方:

  • 它不提供实时性。贴吧的老帖可以说明“某型号用两年后出现什么故障”,但不能说明“今天这款卖多少钱”。文件里已经把这条写进了“是什么”,使用者的结论里也应当保留这个区分。
  • 它不保证可访问。“可能要登录”“偶尔出现安全验证”都是概率性事实,遇到时应视为本次未读到,而不是“没有这回事”。
  • 它不替代交叉核对。“同一故障出现在多个回复里,可能是转述或同一个案例”本身就是对“多来源”这一直觉的反驳:帖子的数量不等于独立案例的数量。
  • 它不覆盖未验证的字段。没有写进文件的网址格式、参数、接口,都不应被当成已知事实使用;格式约定里那句“拿不准的事实宁可不写”,在这份文件里体现为只有两条网址模板、没有 接口 小节。

一份好的站点知识,价值不在于长,而在于每一行都能被构建期校验、被运行期消费、被使用者验证。贴吧这份 26 行的文件,正好把这三件事都做到了:头部字段有校验、正文有明确的注入与预算路径、每条现象都能对应到一次真实的页面观察。

登录后查看全文
Mika