ContextFS

ContextFS 是一个面向 OpenCode 的轻量上下文工程插件，目标是让 Agent 在长会话中保持“稳定、可检索、可追溯”。

当前版本：v5.0.0

---

1. 为什么需要 ContextFS

在长链路任务里，常见问题是：

• 会话越长，token 越容易失控
• 模型容易“忘前文”，导致任务漂移
• 需要回溯历史时，只能翻聊天记录，效率低

ContextFS 的核心思路是把上下文管理工程化：

• 用固定结构注入上下文（而不是拼接整段历史）
• 用渐进式检索按需展开细节
• 用热/归档分层存储，控制成本同时保留可追溯性

---

2. 核心能力

2.1 稳定上下文注入

每轮构建固定 Context Pack：

• PINS：关键约束（上限 20）
• SUMMARY：压缩摘要（上限 3200 chars）
• MANIFEST：工作区清单（上限 20 行）
• RETRIEVAL_INDEX：最近检索索引
• WORKSET_RECENT_TURNS：最近若干轮导航视图

2.2 渐进式检索（L0/L1/L2）

• L0：低成本索引行（search / timeline）
• L1：导航层（PINS/SUMMARY/MANIFEST/WORKSET）
• L2：按需展开完整明细（get）

推荐流程：search -> timeline -> get

2.3 分层存储与索引

• history.ndjson：热数据
• history.archive.ndjson：归档数据
• index.sqlite：派生检索索引（FTS5 + sqlite-vec）

2.4 检索模式

• legacy：grep 兜底
• lexical：SQLite FTS5 词法检索
• vector：sqlite-vec 向量检索
• hybrid：词法+向量融合（RRF）
• fallback：默认自动回退模式

2.5 MCP 接入

提供本地 MCP stdio server，工具契约与 CLI JSON 输出一致：

• search
• timeline
• get
• save_memory
• __IMPORTANT

---

3. 安装

mkdir -p .opencode/plugins
cp <path-to-contextfs>/.opencode/plugins/contextfs.plugin.mjs .opencode/plugins/
cp -r <path-to-contextfs>/.opencode/plugins/contextfs .opencode/plugins/

重启 OpenCode 会话。

---

4. 快速开始

在 OpenCode 对话框中：

/ctx ls
/ctx stats

常用命令：

/ctx search "关键词" --k 5 --mode hybrid --session current
/ctx timeline H-xxxx --before 3 --after 3 --session current
/ctx get H-xxxx --head 1200 --session current
/ctx save "长期记忆" --title "可选标题" --session current
/ctx doctor --json
/ctx reindex --full --vectors

---

5. CLI 与 JSON 契约

• ctx search --json / ctx timeline --json
  • 返回 layer: "L0"
• ctx get --json
  • 返回 layer: "L2"
• ctx save --json
  • 返回 layer: "WRITE"

这套契约用于保证 Agent 工具链可组合、可自动化。

---

6. MCP Server

入口：.opencode/plugins/contextfs/mcp-server.mjs

启动：

node .opencode/plugins/contextfs/mcp-server.mjs --workspace <workspace-path>

工具：

• search(query, k?, scope?, session?|session_id?)
• timeline(anchor_id, before?, after?, session?|session_id?)
• get(id, head?, session?|session_id?)
• save_memory(text, title?, role?, type?, session?|session_id?)
• __IMPORTANT()

---

7. 配置

默认配置在：.opencode/plugins/contextfs/src/config.mjs

常用环境变量：

CONTEXTFS_EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
CONTEXTFS_EMBEDDING_API_KEY=<your_api_key>
CONTEXTFS_EMBEDDING_MODEL=Pro/BAAI/bge-m3
CONTEXTFS_COMPACT_MODEL=Pro/Qwen/Qwen2.5-7B-Instruct

说明：

• 未安装可选 SQLite 依赖时，会自动降级到 legacy。
• 若调整了 text_preview 生成策略，建议执行一次：

/ctx reindex --full

---

8. 评估体系与实验结果

ContextFS 现在包含三层评估：

• 性能评估：bench:full 内含 ContextFS vs Naive
• 检索评估：bench:retrieval（Recall@k / MRR@k / nDCG@k）
• 任务评估：bench:task（规则优先，灰区可接 LLM Judge）

8.1 评估命令

npm run bench:retrieval
npm run bench:task
npm run bench:full

8.2 最近一次全量评估（2026-02-23）

执行命令：

npm run bench:full -- --turns 300 --threshold 1000000 --outDir bench/results_full

注：该次 run 使用高阈值避免触发在线 compact API，主要用于性能/检索/任务一致性验证。

性能（ContextFS vs Naive）

指标	ContextFS	Naive	变化
pack_tokens max	556	21,947	-97.47%
pack_tokens p95	556	20,721	-97.32%
turn_time p95 (ms)	136.413	99.145	+37.59%
total_elapsed_ms	27,240	21,918	+24.28%

解读：ContextFS 以可接受时延开销换取稳定 token 上界。

检索（300 样本）

模式	Recall@k	MRR@k	nDCG@k
legacy	0.903	0.902	0.902
lexical	1.000	1.000	1.000
vector	0.903	0.902	0.902
hybrid	1.000	1.000	1.000
fallback	1.000	1.000	1.000

解读：在该数据集上 hybrid/lexical/fallback 达到满分，legacy 略弱。

任务（150 样本）

• task_success_rate = 1.0
• task_partial_rate = 0
• critical_fact_miss_rate = 0
• judge.total_calls = 0（本次样本由规则层直接通过）

解读：在当前数据与参数下，检索证据覆盖足够，规则判分可直接通过。

8.3 LLM Judge 说明

当任务处于灰区（例如 k=1 导致证据不全）时，会触发 Judge。

默认使用：

• Base URL：https://api.siliconflow.cn/v1
• 模型：由 bench/lib/judge_client.mjs 的默认值或 --judge-model 决定
• API key：复用 .env 中 CONTEXTFS_EMBEDDING_API_KEY

---

9. 开发与测试

安装：

npm install
npm install --prefix .opencode/plugins/contextfs

测试：

npm run test:contextfs:unit
npm run test:contextfs:regression
node --test --test-isolation=none bench/bench.test.mjs bench/eval.test.mjs

---

10. 常见问题

Q1. 压缩后还能检索历史吗？

可以。归档历史仍可通过 search/timeline/get 检索，get 支持 archive fallback。

Q2. 未安装 SQLite 依赖怎么办？

会自动回退到 legacy，不阻塞基础功能。

Q3. 为什么某次 bench 触发 compact 报 key 缺失？

该 run 触发了在线 compact 调用，但进程没有有效 CONTEXTFS_EMBEDDING_API_KEY。可设置 key 或提高 threshold 避免触发。

---

11. License

MIT