上下文为什么应该是一个文件系统

分析 Agent 答错，通常不是因为模型不够强，而是因为它不知道「我们的销售额」到底怎么算。

传统做法有两条路：一是再建一层语义模型，把指标和维度锁在建模工具里；二是把文档切碎、向量化，指望检索能召回正确的那一段。两条路都能跑，但成本都会随时间上升。前者需要专人来维护模型层，后者在文档和索引之间不断积累偏差。

第三条路：写成文件复制锚点链接

Cappy 的上下文就是一个 Markdown 仓库：

context/
├── RULES.md          # 必须始终遵循的规则
├── metrics/          # 指标、定义、领域事实
├── skills/           # 某类分析该怎么做
├── tools/            # 脚本与 MCP 工具连接
└── metricflow.json   # 可选：沿用已有语义层

一个指标就是一个文件：

---
type: metric
description: 电商渠道已支付订单的实付金额，扣除退款
resource: dws_trade_gmv_d
last_verified: 2026-03-01
---

## 定义
已支付订单的实付金额之和，扣除退款。

## 计算
按 paid_at 归属月份，使用 paid_amount。

## 注意
不要用 orders.amount，那是应付金额。

Agent 用 ls、grep、cat 就能读到它需要的那一段，不需要索引，也不需要构建。

为什么这样更省复制锚点链接

• 对人：打开就能读、能改，改完在 PR 里 review，不满意就回滚。
• 对 Agent：文件系统是它最熟悉的接口，按需读取，不必把全部上下文塞进窗口。
• 对团队：口径变更就是一个 diff，谁改的、为什么改，都在提交记录里。
• 对工具链：纯文本，换模型、换数据库都不用重写；已有 dbt 语义层也能作为可选文件接进来。

它不是最大的知识库复制锚点链接

上下文工程的目标不是把所有知识都存进去，而是让 Agent 在具体任务上可靠。先定义一个场景，再为它写最小可用的上下文；随着问题暴露，一次改一个文件。

这比维护一整套建模流程轻得多，也是我们把上下文做成文件系统的原因。