很多开发者的知识采集流程还是手工的：早上打开浏览器，把 Hacker News 首页、GitHub Trending、几份邮件列表和 arXiv 新论文扫一遍，看到有用的复制到笔记软件，顺手打几个标签。每天花二十分钟到半小时，重复、容易漏，也很难坚持。更麻烦的是过两周回头找某条信息，发现当时只存了一行链接，上下文全丢了。
ai-knowledge-base 试图把这条链路交给机器：GitHub Actions 定时唤醒，OpenCode 作为执行主体，配合 Sub-Agent、Skill、Pipeline 和 MCP 完成抓取、筛选与整理，最终把结构化条目写回仓库。它目前只有约 2 个星标，不是能直接投产的成熟产品；但也正因为它小，反而适合当作一份可读的流水线样本——拆开看每个环节怎么接、哪里容易断、哪些设计值得搬进自己的仓库。
先弄清楚它不是什么
在拆解之前，需要先确定预期。2 个星标意味着这个仓库没有经过大规模使用验证，issue、文档和边界情况大概率不完整。它更适合被当作“架构草图”而不是“部署模板”。如果你需要的是一个开箱即用的知识库产品，应该去看有维护者、有 release 节奏、有用户反馈的项目；如果你想理解“定时任务 + 终端智能体 + MCP 数据源”这套组合怎么落地，它才有阅读价值。
另一个前提是 OpenCode 本身。OpenCode 是一个运行在终端里的开源 AI 编码智能体，支持多种模型提供商，可以通过 opencode.json 配置 MCP 服务器，也支持 TypeScript 插件扩展。它不是专门为知识采集设计的工具，但它的能力边界——读文件、执行命令、调用外部工具、按指令分步骤完成任务——恰好覆盖了采集流水线需要的大部分动作。理解这一点，才能看懂 ai-knowledge-base 为什么选它当执行引擎。
五个角色，各管一段
把仓库里的组件按职责拆开，大致是下面这条链：
GitHub Actions：定时器与运行容器
整条流水线的起点是 workflow 文件里的 schedule 触发器。cron 表达式决定多久跑一次，workflow_dispatch 则留一个手动触发的入口，方便调试。Actions 在这里不只是“定时器”，它还提供了运行环境、密钥注入和日志留存——采集过程中的输出、报错和耗时都能在 run 记录里查到，这对排查问题很关键。
需要注意的是权限配置。如果流水线要把结果写回仓库，workflow 里的 permissions 必须显式声明 contents: write；默认的只读 token 会在提交步骤直接失败。这类问题在本地跑脚本时不会暴露，只有放到 Actions 里才会出现。
OpenCode：把自然语言指令变成可执行步骤
OpenCode 在流水线里承担的是“决策与执行”层。它读取仓库里的指令文件（类似 AGENTS.md 的角色），理解本次任务要采集什么、按什么格式整理、写到哪个目录，然后调用工具完成。相比把采集逻辑全部写成硬编码脚本，用智能体驱动的好处是规则调整更灵活——改一段自然语言描述，比改十几个正则和选择器要快。
代价是确定性下降。模型的输出存在波动，同样的输入两次运行可能得到不同粒度的结果。所以这类项目通常需要在提示词里把输出格式约束得很死，或者在智能体之后再加一层校验脚本。
Sub-Agent 与 Skill：把大任务拆小
一个采集任务往往包含多个动作：抓取源页面、提取正文、判断相关性、生成摘要、打标签、写入文件。把这些全部塞给一个智能体，上下文会迅速膨胀，出错后也难以定位。Sub-Agent 的思路是把每个动作拆成独立的小任务，各自有明确的输入输出；Skill 则是可复用的能力单元，比如“抓取网页并转 Markdown”或“对文本做主题分类”，在不同流水线里重复调用。
这种拆分带来的实际收益是排错更容易：某一步输出为空，你可以单独重跑那个 Sub-Agent，而不用把整条链路重新走一遍。对于只有两三个贡献者的项目来说，这种可调试性比性能更重要。
MCP：接上外部数据源
MCP（Model Context Protocol）是 OpenCode 连接外部工具和数据的标准方式。在 opencode.json 里配置 MCP server 后，智能体就能调用搜索、网页抓取、GitHub issue 读取等能力，而不需要为每个数据源单独写适配代码。对知识采集来说，这意味着采集源的扩展成本降低了——换一个搜索后端或加一个文档源，通常只需要改配置，而不是改流水线主体。
不过 MCP 也有代价。每个 server 都会往上下文里注入工具描述，工具越多，token 消耗越大，模型选择工具时的干扰也越多。GitHub 官方 MCP 的文档里就提醒过这一点，并建议用工具白名单限制暴露范围。在自己的项目里，最好一开始就只挂当前任务真正需要的 server。
Pipeline：串联与状态传递
Pipeline 负责把上面的环节按顺序串起来，并处理“上一步的输出怎么交给下一步”。简单做法是落盘成文件，每一步读写约定好的路径；复杂一点可以用结构化格式（JSON/YAML）传递元数据，比如来源 URL、抓取时间、内容哈希。落盘的好处是中间状态可查，失败后能从断点继续，而不是从头再来。
跑起来之前，先盘清密钥和权限
这类项目在本地和 CI 里的行为差异，大多来自密钥。按依赖关系梳理，通常涉及三类：
| 类别 | 用途 | 常见配置位置 |
|---|---|---|
| 模型提供商 API Key | 驱动 OpenCode 完成推理与工具调用 | Actions Secrets，运行时注入环境变量 |
| GitHub Token | 读写仓库内容、调用 GitHub MCP | GITHUB_TOKEN 或自定义 PAT |
| 外部数据源凭据 | 搜索 API、文档源、第三方 MCP server | Actions Secrets，按需注入 |
有两个容易出错的地方。第一，GITHUB_TOKEN 的权限是 workflow 级别的，如果写回操作在 job 内被拆到不同 step，要确认权限声明覆盖到实际执行写入的那一步。第二，PAT 的过期时间要留意——用长期 token 图省事，半年后流水线会突然静默失败，而 Actions 的报错信息未必直接指向 token 过期。
另外，如果采集过程需要访问私有仓库或受保护的分支，权限模型会更复杂，建议先用一个公开的测试仓库把整条链路跑通，再迁移到真实目标。
质量控制的三个闸门
自动化采集最容易出的问题不是“跑不起来”，而是“跑起来了但产出垃圾”。仓库里的控制手段通常集中在三个位置。
来源控制。 采集源最好用白名单而不是黑名单。白名单意味着新增来源需要显式修改配置，虽然麻烦，但能避免某次搜索把低质量页面带进来。如果使用搜索类 MCP，可以在提示词里限定站点范围或时间窗口，减少噪声。
去重。 常见做法是对正文做规范化后计算哈希，写入前比对历史记录；标题层面则可以用相似度阈值兜底。去重逻辑要注意保留“为什么判定为重复”的记录，否则后期很难判断是算法太激进还是源本身在重复推送。
失败重试。 Actions 本身支持 step 级别的重试，但更可控的方式是在代码层区分错误类型：网络超时值得重试，解析失败重试通常没意义，模型返回格式错误则应该让整个任务失败并留下上下文。幂等设计在这里很重要——重跑一次不应该产生重复条目，也不应该覆盖已经人工修正过的内容。
把思路搬到自己仓库的路径
看完架构，真正有价值的问题是：哪些部分值得迁移，哪些不值得。
值得迁移的是分层思路。把“触发—执行—数据接入—状态传递—质量校验”拆成独立环节，每个环节有明确的输入输出契约。这样即使你换掉 OpenCode 改用别的执行器，或者把 GitHub Actions 换成 cron + 容器，整体结构不用重写。Sub-Agent 和 Skill 的拆分方式也值得借鉴，它本质上是在用工程手段控制智能体的不确定性。
需要谨慎的是直接复用具体实现。2 个星标的项目，代码路径未必覆盖了边界情况，配置项也可能只对作者自己的环境有效。更稳妥的做法是把它当参考，用自己的采集源和输出格式重写一遍——通常只需要几百行代码，但你对每一行的行为都有把握。
如果决定动手，建议按这个顺序推进：先用 Actions 的 workflow_dispatch 手动触发跑通单个源的采集；加上落盘和日志，确认输出可读；再接入去重和失败处理；最后才开 schedule 定时。跳过前面几步直接上定时任务，出问题时很难判断是逻辑错误还是环境差异。
什么情况下这套方案不划算
最后说限制。如果你的采集频率很低——比如每周一次、源只有两三个——手写一个 Python 脚本加 cron 可能更简单，引入智能体和 MCP 反而增加了调试面。如果你的采集目标对格式准确性要求极高（比如法律条文、财务数据），让模型参与提取和改写会带来不可接受的风险，这时候规则解析更可靠。
ai-knowledge-base 展示的是一种组合方式：用定时任务做调度，用终端智能体做决策，用 MCP 做数据接入，用分层拆解控制复杂度。这个组合在“源多、格式杂、需要语义筛选”的场景下才有明显收益。判断是否采用，不妨先问自己一个问题：我的采集流程里，有多少步骤是“看一眼就能决定”的？如果比例很高，自动化才值得投入；如果大部分步骤需要人工判断，那这套流水线省下的时间可能还不够填它带来的维护成本。
评论列表 (4条)：
加载更多评论 Loading...