wiki-research-loop

Wiki Research Loop

将 wiki 转化为自动扩展知识库的驱动程序。在 wiki-builder 和 wiki-query 之上构建。

循环语义

seed-queue (pending) → next-seed
  → fetch sources via plugins (web | arxiv | github)
  → extract claims
  → dedupe vs index (FTS5; later vector via 3.3.2)
  → compile new page or amend existing
  → upsert page (auto-FTS-index)
  → enqueue follow-up seeds (max-depth gate)
  → mark seed done
  → if budget OR convergence OR kill-switch → halt

停止条件（满足任意一项即停止）

• 超出 budget_usd（循环会跟踪每个抓取器的成本估算）
• 达到 max_pages_per_run
• 所有活动分支均达到 max_depth
• 连续 3 个页面新增的声明少于 5 %（收敛）
• 文件 ~/.pro-workflow/STOP 存在（操作员紧急停止开关）
• wiki.config.md 中的 auto_research.enabled: false
• Wiki 设置为 private: true，且选择了任意非本地抓取器

命令

在插件会话中，使用 providers MCP 服务的 run_provider_task 工具，设置 task: "research" 并传入下方的运行器参数，例如 args: ["run", "agent-memory", "--fetchers", "github"]。可选的 GitHub 令牌来自插件配置对话框。直接使用 CLI 时，只有显式提供 PRO_WORKFLOW_GITHUB_TOKEN 才会使用它。切勿从现有机器凭据中读取令牌。

node $SKILL_ROOT/scripts/research-loop.js run <slug> [--max-pages N] [--max-depth N] [--budget-usd 0.50] [--fetchers web,arxiv,github]
node $SKILL_ROOT/scripts/research-loop.js seed <slug> "<query>" [--depth 0] [--parent-id N]
node $SKILL_ROOT/scripts/research-loop.js seeds <slug> [--status pending|active|done|failed]
node $SKILL_ROOT/scripts/research-loop.js cancel <slug>
node $SKILL_ROOT/scripts/research-loop.js status

CLI 标志仅对单次运行覆盖 wiki.config.md 中的设置。

来源抓取器

可插拔。每个抓取器位于 scripts/source-fetchers/<name>.js。接口：

module.exports = {
  name: 'web',
  match: (q) => true,                       // is this fetcher useful?
  estimateCost: (q) => ({ usd: 0, tokens: 0 }),
  fetch: async (q, opts) => [               // returns RawDoc[]
    { url, title, content, fetched_at }
  ]
};

内置抓取器：

• web.js — 通过标准输入/输出桥接程序，使用用户可用的 WebFetch 工具进行抓取。将结果视为纯文本/Markdown。
• arxiv.js — https://export.arxiv.org/api/query（免费、公开、无需密钥）。返回摘要和元数据。
• github.js — https://api.github.com/search/repositories，并抓取 README（使用显式配置的 GitHub 令牌；否则受未认证请求速率限制）。

独立 CLI 运行会从 ~/.pro-workflow/fetchers/<name>.js 加载自定义抓取器。插件 MCP 服务仅使用内置抓取器，因此不会将已配置的令牌交给用户提供的模块。

预算执行

迭代前：汇总所选抓取器的 estimateCost。如果预计累计成本会超出 budget_usd，则停止。

迭代后：跟踪大模型编译步骤（Anthropic/OpenAI 透传）使用的令牌数。超出预算时立即终止。

可通过环境变量设置每个抓取器的覆盖值：WIKI_LOOP_BUDGET_USD、WIKI_LOOP_MAX_PAGES、WIKI_LOOP_MAX_DEPTH。

种子队列

由 SQLite 的 wiki_seeds 表提供支持：

字段	含义
query	自然语言种子
status	pending → active → done|failed
parent_id	生成此种子的种子
depth	从根节点开始的 BFS 深度

循环按 (depth ASC, created_at ASC) 弹出种子，因此会按广度优先顺序探索。

收敛检测

每编译完一个页面，就计算其声明文本令牌与之前 3 个页面的 Jaccard 重合度。如果连续 3 个页面的新内容均 < 5 %，则停止并报告 converged。

紧急停止开关

touch ~/.pro-workflow/STOP

循环会在每次迭代时检查，并平稳停止。删除文件即可在下次运行时恢复。

隐私保护

如果 wiki.config.md 中设置了 private: true，循环将拒绝任何非本地抓取器并发出警告。仅允许通过手动种子将内容导入 raw/。

响应式触发（Phase 3.3.4）

scripts/file-watcher.js 会监视 wiki/<slug>/wiki/**/*.md。当用户编辑声明时，它会在深度 0 的位置加入验证种子（verify: <claim>）。此功能通过 pro-workflow 的 file-watcher.js 钩子接入。

定时任务触发（Phase 3.3.4）

scripts/research-tick.js 可由任意 cron 风格的运行器启动。它会选取最早加入选择列表且存在待处理种子的 wiki，并运行单次迭代。钩子事件：pro-workflow:research-tick。

输出

每次运行都会写入：

<wiki-root>/logs/research-<UTC-timestamp>.md   # human-readable run log
<wiki-root>/derived/run-<UTC-timestamp>.json   # structured stats

运行日志行：

[2026-05-08T10:42Z] seed-3 (depth=1) "memory consolidation in agents"
  fetcher=arxiv hits=3
  fetcher=web hits=2
  compiled wiki/concepts/memory-consolidation.md (claims=7, novel=4)
  enqueued 2 follow-up seeds
  cost so far: $0.04 / $0.50

与 wiki-query 集成

每个编译后的页面都会通过 wiki-cli.js page 处理，以保持 FTS5 一致。去重步骤会调用 searchWiki，使用候选声明文本查找近似重复项。

状态（Phase 3.3.1）

已提供：循环驱动程序、种子队列、web/arxiv/github 抓取器、预算上限、收敛检测器、紧急停止开关、手动 run 命令。

暂不提供：

• 向量去重（Phase 3.3.2，通过 sqlite-vec 实现）
• 由大模型判断声明的新颖性（当前使用 Jaccard 令牌重合度）
• 定时任务与响应式触发（Phase 3.3.4）