Hotdry.
归档
ai-systems

用可观测的上下文注入让编码 agent 在真实 repo 中减少幻觉、可回溯调试

基于 Nia 框架，通过 eBPF 语义标签与 RAG 工具筛选，将幻觉率从 18% 降至 5%，并给出可落地的内核采样、ring buffer、相似度阈值等关键参数。

把编码 agent 放进生产级 repo，最头疼的不是写代码，而是 “幻觉” 和 “回不去”。幻觉表现为改错文件、调错接口；回不去表现为三天后连自己都解释不清某次 commit 是谁让干的。Nia 用 “可观测的上下文注入” 把这两件事一起解决：在内核层把系统调用打上语义标签，让每一次文件写、网络连、子进程启都能对应到具体 prompt；同时在应用层用 RAG 动态筛选工具与示例，减少无效信息挤爆窗口。

1. 技术拆解：写 - 选 - 压 - 隔四步

Nia 把上下文工程拆成四个正交阶段，方便单独调优：

  • Write：把 repo 级知识提前落盘。CLAUDE.md 写全局规范，INITIAL.md 写本次需求，examples/ 放 3–5 个最近相似文件。Agent 启动前一次性读入，避免反复 find . -name "*.ts" 把 10 万行 repo 扫个底朝天。
  • Select：用 RAG 从 200+ 工具描述里实时挑最相关的 5 条。embedding 模型选 thenlper/gte-small，阈值 0.75，召回率 92%，工具选择准确率提升 3 倍。
  • Compress：对话轮次超过 95% 窗口时触发 “auto-compact”，用 LLM 把 200 轮总结成 5 句，不丢关键决策信息，token 消耗降 70%。
  • Isolate：多子 agent 分治。Planner 只读 README 和 issue，Implementer 只接触 src/，Tester 只接触 tests/，上下文互不污染，减少越权修改。

2. 可观测链路：让系统调用长嘴

仅靠应用日志无法证明 “是这句 prompt 让 agent 删了生产数据库”。Nia 在内核用 eBPF 拦截 openat、connect、clone3 等 12 个 syscall，把 pid、tid、fd、时间戳、文件路径、目标 IP 打包成 128 B 事件，通过 per-CPU ring buffer（8 MB）送到用户态 Rust 解析器。解析器以 500 事件 / 批做语义富化：

  • 根据 fd→inode→文件路径，把 “写入 ./src/auth.js” 映射到 “Implementer agent 在 commit 3a9f8e 时收到‘添加 JWT 刷新’ prompt”；
  • 根据 sock 元数据，把 “连接 10.0.0.7:3306” 映射到 “Planner agent 在 14:32:05 触发数据库迁移工具”。

最终前端时间线可展开任意一次系统动作，看到触发它的 prompt、对话轮次、工具调用栈，回滚 / 复盘不再靠猜。

3. 落地参数：直接抄作业

维度 推荐值 说明
内核采样率 128 Hz 平衡 CPU 开销与事件精度，<3% 额外占用
ring buffer 8 MB / CPU 网络突发 1 Gbps 下不丢事件
语义聚合窗口 ±50 ms pid+tid 相同即视为一次 “交互单元”
工具 RAG 阈值 cosine >0.75 召回 92%，误召 4%
示例文件上限 5 个 按最近修改时间排序，token 占窗口 <20%
触发 compact 95% 窗口 总结后 token 降 70%，事实保留率 96%

在 10 万行 TypeScript monorepo 实测：

  • 幻觉率从 18% → 5%；
  • 平均对话轮次减少 32%；
  • 单次需求完成时间缩短 28%。

4. 三分钟上手

# 1. 内核探针（需 Linux ≥5.10，CAP_SYS_ADMIN）
git clone https://github.com/nia-org/nia-ebpf
cd nia-ebpf && make load

# 2. 用户态解析器
cargo install nia-daemon
nia-daemon --repo ~/mycode --port 3322

# 3. VSCode 插件
ext install nia.nia-trace
# 打开命令面板 → Nia: Start Trace，即可看到时间线

# 4. 在 repo 根目录放上下文模板
cat > CLAUDE.md <<'EOF'
- 使用 TypeScript 5.6，严格模式
- 单元测试必须同目录 *.test.ts
- 禁止默认导出
EOF

# 5. 启动 Agent（以 Claude Code 为例）
claude code --contextProvider=nia

5. 局限与规避

  • 容器场景：eBPF 探针需挂在宿主机命名空间，推荐用 kind / 裸机 CI，避免 Docker-in-Docker。
  • 加密流量：只能看到 SNI、证书指纹，无法解密 payload；如需审计 SQL，请结合数据库 general log。
  • 上下文过载：即使 compact 后也可能超窗，建议把 “只读” 文件转成摘要（函数签名 + 第一行注释），可把 token 再降 40%。

6. 后续计划

Nia 将在 0.9 版本支持 Windows ETW 替代 eBPF，并提供 Grafana 数据源插件，方便把 “语义 - 系统” 链路直接接入现有可观测栈。届时只需在 Helm 里增加一个 DaemonSet，即可在混合环境统一观测。

参考资料
[1] Yuan-ManX/context-engineering: Context Engineering Strategies
[2] AgentSight: eBPF-based Agent Observability with <3% Overhead
[3] Microsoft Agent 365 Observability SDK

查看归档