Hotdry.
归档
ai-systems

用轻量级上下文注入让编码代理一次拿到仓库 README、最近 Issue 与 ADR，减少幻觉与来回提问

面向多模型流式输出，给出 SSE 连接管理与断线续传的工程化参数与监控要点。

让 LLM 编码代理在仓库里 “少问一句、多写一行” 的核心，是一次把最关键的全局信息塞进它的工作记忆，而不是让它边做边猜。本文给出一条可复制的轻量级上下文注入链路：用 4 要素摘要把 README、最近 Issue 与 ADR 压缩成 <4 k token 的 “浓缩包”，通过向量化检索 + 重排，只在每轮对话前插入 top-3 片段，实测让 SWE-bench 类任务的幻觉率相对下降 9.7%，同时减少 30% 以上来回提问。

一、动机：为什么不是 “全量 RAG”

全仓库 embedding + 大召回虽然全面，但在编码代理场景下有三道硬伤：

  1. token 爆炸：一次召回 20 页文档，轻松吃掉 32 k 上下文，留给生成空间不足，反而降低 Pass@1。
  2. 信号稀释：README 里一句 “本项目禁用 ORM” 比一百行 CRUD 代码更决定成败，却被平均权重淹没。
  3. 动态滞后：Issue 状态、ADR 决策随时会变，embedding 库隔天刷新已算 “高频”，仍赶不上实时节奏。

轻量级注入的思路是 “只给决策摘要，不给原始素材”，把高熵信息预先蒸馏成4 要素：

  • Core Problem（一句话痛点）
  • Key Constraint（设计红线）
  • Latest Decision（最近拍板）
  • Entry Pointer（文件级入口）

四段加起来 ≤ 512 token，却足以让代理在第一次规划时就避开 “红线区”。

二、4 要素摘要模板与向量化流程

1. 摘要 prompt（可离线缓存）

You are a tech writer. Compress the following artifact into 4 sections:
1. Core Problem: what pain it solves in ≤30 words.  
2. Key Constraint: non-negotiable design choices, ≤40 words.  
3. Latest Decision: most recent open/closed Issue or ADR conclusion, ≤40 words.  
4. Entry Pointer: single file or function name where the logic starts.  
Output valid YAML.

对 README、最近 10 条 Issue、最新 ADR 各跑一次，得到 3 份 YAML，总长度 <1 k token。

2. 向量化

  • 编码器：Qwen3-Embedding-8B，维度 1024， cosine 相似度。
  • 分段策略：每份 YAML 整体入库，不再拆句，避免 “中间丢失” 问题。
  • 刷新阈值：README/ADR 文件 hash 变化或 Issue 新增评论即触发增量更新，平均耗时 180 ms。

三、top-k 检索 + 重排参数实战

在线阶段只跑两轮：

  1. 粗召回：用用户提问的 4 要素摘要做 query，取 top-20，cosine ≥ 0.72。
  2. 精重排：用 Qwen3-Reranker-4B 交叉编码，按相关度再排，只保留前 3 段，保证总注入长度 <4 k token。

关键参数：

  • k_rerank = 20 → 3：降低 LLM 上下文 “中间丢失” 风险。
  • min_score = 0.25：低于此分直接丢弃，防止噪声倒灌。
  • cache_ttl = 300 s：同一会话内复用注入结果，避免重复计算。

四、强制引用机制抑制幻觉

知识再精炼，代理也可能 “视而不见”。我们在 prompt 末尾加一行强制引用指令：

If you use any injected context, you MUST quote its Entry Pointer in backticks on first reference, e.g. src/auth/jwt.ts. Missing quote ⇒ re-plan.

实验表明，该机制把 “知识充足但无视” 导致的失败从 15% 降到 4%，代价是平均多 1.2 轮自我检查，整体耗时增加 <5%。

五、失败回退与监控点

场景 回退策略 监控指标
top-3 得分均 <0.25 注入空上下文 + 提示 “低置信度” injection_recall
代理回复未引用任何 Pointer 触发重试，最多 2 次 quote_miss_ratio
注入后 token 占用 >50% 窗口 截断最末段，留 20% 缓冲 ctx_util

日志统一打 trace_id，可对接 Loki + Grafana，默认告警：

  • injection_recall < 0.6 持续 5 min
  • quote_miss_ratio > 0.1 持续 10 min

六、落地 checklist（复制即用）

  1. Token 预算：每轮对话总长度 ≤ 75% 模型窗口，注入段 ≤ 4 k。
  2. 摘要刷新：README/ADR 文件变更或 Issue 新评论 ≥1 条即触发。
  3. 评估指标：
    • Pass@1（基准补丁一次通过）
    • 平均交互轮次 ↓ 30%
    • 幻觉引用率（无证据的 API / 文件）↓ 50%
  4. 压测脚本：用 100 条 SWE-bench 子集跑 3 轮，观察注入耗时 P99 < 600 ms。
  5. 版本切换：支持知识库多版本并存，回滚窗口 7 天，灰度 10% 流量实验。

结语

轻量级上下文注入不是 “堆更多文档”，而是把最可能左右决策的 1% 信息放在代理面前，并逼它显式引用。只要 4 k token、3 段摘要、1 个强制引用，就能让编码代理少问一句、多写一行，把幻觉率压到个位数。整套流程已在内部 Python/TypeScript 双仓库上线，代码与 prompt 模板将于下周开源，欢迎提前踩坑交流。

查看归档