MarkZ

从 Code Context 到 Business Context：多代码库中的 Agent 路由

15分钟阅读

文章定位

本文总结张立理《从 Code Context 到 Business Context：让 Agent 在数百个代码库中高效定位代码》中的 Flower Business Wiki 实践。文章解决的是一个特定问题：当 Agent 面对几十到数百个代码库时，如何先找到真正相关的仓库，再进入源码分析。

原文的核心判断是：

让知识负责缩小搜索空间，让 Agent 负责探索，让源码始终保持 Single Source of Truth。

Business Wiki 不是源码知识副本，也不替代 Coding Agent 的代码检索与理解能力。它是一层面向业务的仓库导航，用稳定、低成本的信息回答“应该去哪里 grep”。

名词与文件的对应关系

Business Context、Business Wiki 和 wiki/INDEX.md 不是三个同义词，它们分别指信息视角、实现方案和具体文件：

名称它是什么在路由中的职责
Business Context系统职责、业务术语、能力边界等业务视角的上下文让 Agent 从需求语言推断应该关注哪些系统
Business WikiFlower 对 Business Context 的工程化实现组织全局索引、词汇表和仓库卡片，并规定渐进式读取顺序
wiki/INDEX.mdBusiness Wiki 的第一层入口文件汇总所有仓库的一句话职责，让 Agent 一次观察整个 Workspace
wiki/VOCABULARY.mdWorkspace 级业务词汇表用少量业务词快速检索候选仓库
Repository Card每个仓库各自的第二层详细描述说明仓库负责什么、不负责什么、入口在哪里以及依赖谁

因此，wiki/INDEX.md 可以看作最小版 Business Context 的入口，但不能代表完整的 Business Wiki。内容仍然按仓库生成：每个仓库有自己的一句话描述、词汇和 Repository Card；消费方式则按 Workspace 汇总，Agent 不需要在第一步分别打开 200 份文档。

Business Wiki 的逻辑目录

原文明确给出了 wiki/INDEX.md 与 wiki/VOCABULARY.md，但没有规定 Repository Card 的实际文件名和落盘目录。为了说明对象关系，可以把它理解为下面的逻辑结构示意，而不是 Flower 的原样目录：

wiki/
├── INDEX.md                    # 全局索引：每个仓库一行职责，不超过约 100 字
├── VOCABULARY.md               # 全局词汇表：业务词 → 可能相关的仓库
└── repositories/               # 逻辑分组；原文未声明实际目录名
    ├── feed-ad-card.md         # Repository Card：负责广告入口
    ├── landing-page-card.md    # Repository Card：负责落地页与半屏容器
    └── coupon-sdk-card.md      # Repository Card：负责领取核销，不负责容器

任务开始时不是把整棵目录树全部塞给模型，而是按需读取。完整链路从业务需求开始：Business Wiki 找到候选仓库，Repository Card 确认职责和代码入口，Agent 随后打开当前源码，并用 rg、LSP、测试和日志完成真实分析。

从业务需求到源码分析的完整流程 图 1：Business Wiki 只负责把 Agent 引向正确仓库；进入源码后，当前实现和验证证据才是事实依据。

例如需求包含“优惠券半屏调起”，第一层可能同时命中广告入口、落地页和优惠券三个仓库。第二层再通过 Card 中的负向边界排除“只负责领取核销、不负责页面容器”的仓库，避免仅凭名称相似深入错误代码库。

Code Wiki 在多库路由中的错位

Code Wiki 类工具通常通过 AST、依赖图、RAG、模块树或 Agent 探索，为单个仓库生成层次化文档。它适合帮助 Agent 深入理解一个已经确定相关的仓库，却不适合作为数百个仓库之间的第一层路由。

这里的 Code Wiki 不等同于 Graphify 这类代码图工具。Code Wiki 的主要产物是 overview.md、模块说明和依赖文档等自然语言知识；Graphify 的主要产物是从 AST 抽取的类、方法、导入和直接调用关系图。两者属于不同实现，但都更擅长回答“目标仓库确定后，仓库内部有什么”，不能单独回答“当前业务需求应该先进入哪几个仓库”。本节讨论的是原文对 Code Wiki 的实践结论，Graphify 的索引范围、缺失源码和运行时调用边界见关联笔记。

原文在实践中观察到两个主要问题。

生成与维护成本过高

在约 80 万行代码的仓库上使用小型高速模型生成 Code Wiki，运行超过 2 小时、花费超过 100 元后仍未完成。即使首次生成完成，代码的高频变化也会持续产生更新成本。

路由阶段只需要判断仓库是否值得继续探索。如果为此先生成完整模块树和仓库文档，投入的信息处理成本与决策目标并不匹配。

横向比较仍然超出上下文

假设 Workspace 包含 200 个仓库，分别生成 Code Wiki 后，第一层输入仍是 200 × repository overview。把仓库合并后统一生成，规模只是变成 200 × module overview，没有消除 Agent 在大量对象之间横向比较的成本。

因此，Code Wiki 的纵向分层没有解决多库路由所需要的横向压缩。纵向分层回答“一个库内部有什么”，而路由阶段首先要回答“哪些库值得看”。

下图把两种信息组织方式放在同一尺度比较。Code Wiki 把每个仓库都展开后再做横向判断；Business Wiki 先用薄索引缩小范围，只对少量候选逐步增加信息密度。

Code Wiki 与 Business Wiki 的多库路由差异

图 2：完整仓库文档适合单库理解；多库路由需要先压缩横向搜索空间。

Business Context 的三项设计原则

Business Wiki 从需求天然携带的业务线索出发，把系统职责、业务术语和能力边界作为更稳定的导航信息。

初始上下文必须平面化

第一层信息需要刻意牺牲单个仓库的完整度，让 Agent 用较小的上下文同时观察整个 Workspace。这里的“渐进式”不是沿代码目录逐层展开，而是：

候选范围越大，每个对象使用的信息越少；候选范围越小，才为每个对象提供更高密度的信息。

派生知识只负责导航

模型生成的 Wiki、摘要和索引可能滞后或不完整，只能用于决定下一步探索方向。仓库是否相关、功能如何实现以及修改是否正确，最终都要回到源码与验证结果。

缓存变化较慢的业务信息

具体实现会频繁变化，但仓库职责、业务能力和领域词汇通常变化较慢。这些信息压缩率高，更适合按周期生成和缓存，也更契合仓库初筛的目标。

Business Wiki 的三层路由

Business Wiki 把发现过程划分为“筛选—精挑—理解”三层，每一层只提供当前决策需要的信息。

层级Agent 消费的信息目标
全局初筛所有仓库的一句话描述和领域词汇从整个 Workspace 中找出一批候选仓库
相关性确认候选仓库的 Repository Card判断哪些仓库真正与任务相关
源码理解源码、引用关系、测试和运行结果完成分析、修改与验证

三层不是三套相互竞争的知识库，而是一条上下文逐步加深的漏斗。每层的输出限定下一层要读取的对象。

Business Wiki 的三层渐进式路由

图 3：候选范围逐层缩小，单个仓库获得的信息密度逐层增加，最终以源码和验证结果定案。

第一层：一句话索引与全局词汇表

wiki/INDEX.md 为每个仓库提供不超过 100 字的一句话描述，一行一个仓库。wiki/VOCABULARY.md 汇总各仓库的专有名词，供 Agent 使用 grep 快速检索。

这一层强调召回：先排除明显无关的仓库，允许保留少量误选，避免过早漏掉真正相关的仓库。

第二层：Repository Card

Agent 只读取候选仓库的卡片。每张卡片聚焦六类信息：

  • 适合处理的需求；
  • 明确不负责的任务；
  • 核心业务名词；
  • 适合开始代码分析的入口文件；
  • 业务入口和关键节点；
  • 与周边仓库的依赖关系。

“不负责什么”与“负责什么”同样重要，它可以降低名称相似造成的误路由。

第三层：回到源码

候选范围确定后，Business Wiki 退出主导位置。Agent 使用 grep、文件阅读、符号关系、测试和真实运行结果理解实现。源码继续承担事实源角色，Wiki 只保留导航价值。

Flower 实践数据与证据边界

原文披露的当前实践规模和评测结果如下：

  • 覆盖 20 多个 Workspace、约 400～500 个代码库；
  • 约 60 万行代码的仓库，使用 DeepSeek V4 Flash 完整生成一次 Business Wiki，成本约 5～6 元；
  • 业务属性变化慢于实现细节，因此按周更新；
  • 在数十个经典任务中回看实际涉及的仓库；对于 10 多到 200 多个仓库的场景，报告的“有效准确率”为 90% 以上；
  • Flower 已将 Business Wiki 作为 Workspace 能力全量启用，并提供复用和缓存机制。

这些数据来自原文团队的内部实践陈述。文章没有展开评测集规模、准确率计算公式、召回率与误选率的独立分项，也没有提供外部复现结果。因此可以把它们视为方案在内部场景可行的证据，不能直接外推为所有语言、仓库结构和业务类型下的通用效果。

对 Agent Workspace 建设的启发

这套方案补充了 Agent Workspace 中的 Repo 路由层：Workspace 不能只把多个仓库放到同一目录，还需要让 Agent 在任务开始时获得一张足够轻量的业务地图。

落地时可以先建设最小版本，而不必立即生成完整 Code Wiki：

  1. 为所有仓库维护一句话职责和领域词汇；
  2. 为候选仓库补充包含正向职责、负向边界和代码入口的 Repository Card；
  3. 让真实任务依次经过全局初筛、卡片确认和源码验证；
  4. 分别记录相关仓库召回率、无效仓库数量、路由耗时与上下文消耗；
  5. 只有业务职责或核心词汇变化时才刷新导航知识，具体实现始终从源码读取。

这也划清了 Business Wiki 的适用边界：它优化的是多代码库中的路由问题。单库内部的架构理解、复杂调用链分析和代码问答，仍可以交给 Code Wiki、LSP、静态分析或 Coding Agent 自主探索。

相关笔记

评论

关系图谱

反向链接