S24-A06 · 编码助手的工作流集成：IDE、CI 与上下文

编辑器里问它一句"这个接口怎么改"，答得挺准；把同样的模型接进 CI，让它顺手修 lint 和失败用例，十个 PR 里有八个被改出别的问题。不是模型退化，是落点变了：IDE 里你看得见 diff、随手就能否掉；CI 里没人看，信息也更全，但错误直接进主干。

三个落点各有自己的信息完整度和延迟容忍度。判据按"落点 → 上下文 → 契约 → 阶段"排。

1. 三个落点：信息完整度换延迟

落点	上下文来源	信息完整度	延迟容忍	失败代价	适合任务
IDE 内联	打开的文件 + 光标附近	低到中	秒级	低（人当场看 diff）	局部改写、补用例
PR 评审	diff + 仓库索引	中	分钟级	中（评审关拦截）	一致性、漏边界、命名
CI 流水线	全量检出 + 失败日志	高	十分钟级	高（直接进主干）	修确定性失败、格式化

判据：信息越完整、延迟容忍越高，越适合自动化；信息越局部、越依赖人判断，越该留给人。 反过来做——在 CI 里让它做需要产品判断的重构——是绝大多数"助手在 CI 里变废"的真实原因。

2. 上下文的三条路与各自成本

路径	获取方式	成本	主要风险
打开的文件	编辑器自动带	近零	只见局部，看不见调用方
仓库索引	向量/符号索引、检索	建索引 + 维护 + 每次检索延迟	索引过期→引用不存在的代码
显式提供	人指定路径、贴日志与用例	人工时间	漏关键文件，全凭经验

索引不是免费的：一次全量重建按仓库规模可能从分钟到小时，增量更新要额外维护 hooks；检索本身还占上下文预算。所以先问"这次任务缺的是哪个文件"，再决定要不要索引——多数单文件改写用不着。

# 显式上下文：把"没打开但相关"的东西列进任务描述，比整仓索引便宜得多
git log --oneline -5 -- src/order/            # 最近的决策痕迹
git grep -n "OrderStatus\." -- '*.java' | head -20   # 调用点，代替"让模型猜"

3. 仓库索引的收益边界

场景	索引有用吗	说明
改签名找全部调用点	是	补上"没打开的那些文件"
命名与风格一致性	是	靠同族样例比靠描述准
历史决策（为什么这么写）	部分	需 ADR 或提交摘要，索引本身无语义
强类型重构	否	编译器与 IDE 重构更可靠
无测试的遗留代码	否	索引帮你找，不帮你验证

4. "助手没看到的东西"是错误主因

盲区	典型错误形态	补法
未打开的调用方	改签名漏改调用	索引或让编译报错暴露
团队约定	用了禁用库、日志格式不对	规范作为约束传入（§5）
运行期配置	把环境相关值硬编码	明确告知配置读取位置
数据边界	空值、分页、权限未处理	用例先行，让测试说话
已有工具类	重复造轮子	目录级说明里点名

这张表比任何提示技巧都值钱：把盲区补上，输出质量的变化通常比换模型明显。

5. 提示工程的工程化

三件事：模板版本化、按任务类型分模板、把团队规范作为约束传入。

# prompts/<task>/<version>.yaml，与代码同仓，改动走 PR
task: fix-failing-test
version: 3
inputs: [stacktrace, test_file, impl_file]
constraints:
  - "禁止改测试断言，除非断言本身与需求不符"
  - "禁止引入新依赖"
  - "日志用 slf4j 占位符，不用字符串拼接"
output:
  format: unified_diff        # 只要 diff，不要整文件
  max_files: 2

层次	内容	谁维护	变更频率
平台模板	通用角色、输出格式	平台/工具负责人	季度
任务模板	修测试、写用例、评审、迁移	团队	月度
项目约束	技术栈、禁用项、目录职责	项目负责人	随架构

模板版本化之后，"上周还好用"才有对照物：先比模板 sha，再怀疑模型。反之，模板散在个人聊天记录里，效果波动永远归因不到原因。

6. 生成代码的验收责任划分

产物形态	谁签名	必须做的验证
IDE 建议直接落盘	编写者	编译 + 本地单测
助手在 PR 里提交	发起人	CI 全绿 + 自审 diff 的删除部分
CI 自动修复后提交	合并者或值班	白名单范围 + 回归
完全自动合并	不该存在	除非变更范围可枚举（见 §7）

签名者负责，是唯一能落地的规则。写"AI 生成，仅供参考"的注释没有任何约束力；把产物挂在具体人身上，评审才会真的看。

fix: 补齐 OrderService 空态分支

Assisted-by: coding-assistant/model-x
Prompt-Template: fix-failing-test@v3
Human-Reviewed-By: zhangsan

7. CI 里做自动修复，还是只做提示

模式	适用	风险
只提示（评论/报告）	不可判定问题、风格建议	没人看，变成噪音
自动修复 + 提交到 PR 分支	确定性失败：格式化、import、依赖版本、快照更新	顺手改坏逻辑
自动修复 + 人工合并	中等风险，需解释的改动	流程变慢但可控
只允许改测试/配置	边界清晰的子集	覆盖面小，但最安全

# 只允许助手动"可枚举"的路径，其它一律退回评论
on: [pull_request]
jobs:
  autofix:
    if: github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - run: assistant fix --task lint --paths "src/**" --paths "!src/core/**"
      - run: git diff --name-only | grep -vE '^(src/|pom.xml$)' && exit 1 || true

白名单比提示词管用：改坏逻辑最常见的路径是"它顺手重构了不该动的文件"，而不是"它算错了"。

8. 内网/离线部署的效果折损

约束	折损点	量化方式
模型规模受限	多文件推理与长上下文能力下降	同一任务集按类型出通过率
无外网检索	依赖最新文档/API 的任务失败	分任务类型统计，不看总分
数据脱敏	上下文被裁剪，缺字段	统计"因信息缺失返工"的次数
硬件共享	排队延迟拉长	排队时长 P95 与放弃率

量化方式只有一种可信：同一批任务、同一批人、两种环境各跑一遍，按任务类型出通过率。整体分数会把"修 lint 依然很好"和"跨模块重构崩了"平均成一个没用的数字。

9. 成本控制

杠杆	做法	代价
上下文长度	只给相关文件，长文件给摘要	漏信息导致返工
缓存	前缀缓存、索引缓存	失效管理变复杂
调用频率	收紧触发条件、同类请求去重	覆盖率下降
模型分层	简单任务走小模型	路由规则要维护

budget:
  per_task_tokens: 60000        # 超了先裁上下文，不加预算
  per_dev_daily_calls: 200
  cache: { prefix: true, ttl: 1h }
  escalate_to_large_model: [cross_module_refactor, migration]

10. 三阶段落地与各阶段该量什么

阶段	做法	度量	退出条件
个人辅助	自选工具、自测收益	个人采纳率、返工率	有稳定收益的人过半
团队约定	统一模板、规范、评审口径	评审意见量、同类问题复发率	不再反复提同一类问题
流程集成	CI/PR 自动化、白名单	自动修复合并率、被回滚率	回滚率低于阈值并稳定

# 最小可用度量，先记这四个，别一开始就上大看板
采纳率 = 被接受并保留到合并的产物 / 全部产物
返工率 = 合并后 30 天内被 revert 或大改的比例
评审意见量 = 每 PR 的有效评论条数（按类别分）
知识沉淀 = 新增/更新的模板、约束、目录说明条数

第三阶段最容易失控：自动修复的合并率好看，被回滚率却在涨。两个指标必须一起看，否则是在用返工换吞吐。

11. 排错

现象	原因	处置
IDE 里好用，CI 里乱改	任务类型超出了"确定性修复"	收窄到白名单任务
输出引用了不存在的类	索引过期或幻觉	重建索引 + 要求引用前先检索
改完测试还是红	它改了断言而不是实现	模板里禁止改断言，CI 校验
同一问题反复出现	团队规范没进约束	规范条目化，进项目约束层
内网效果明显差	上下文被裁剪，无外部文档	按任务类型分配，别一刀切

12. 边界

情形	助手价值	说明
探索性研究、方案未定	低	没有"对"的标准，无法验收
遗留代码且无测试	低	改对改错都无法验证
团队规范本身缺失	负	会放大混乱，先补规范
一次性脚本	中	可验证成本低，但沉淀为零
强合规/强审计路径	低	需要可解释的确定性变更

13. 自测

同一个模型在 IDE 里好用、在 CI 里变差，差别在哪两个变量上？
什么情况下仓索引的收益抵不过它的维护成本？
"改完测试还是红"最常见的实现原因是什么，怎么用流程堵住？
内网部署的效果折损为什么必须按任务类型量化？
三阶段落地里，第二阶段该量的指标和第一阶段有什么不同？
自动修复的合并率上涨，为什么不是好消息的唯一信号？