工具链搭建：编辑器助手、终端 Agent 与本地模型的组合
装工具的常见结局是：编辑器里一个助手、终端里一个 Agent、再加一个本地模型，各说各话，谁都不能替你跑一次测试。这一章讲的是组合：先把仓库改造成「可被验证」的样子，再按职责把三层工具配上，最后留一条随时能自检的流程。判断标准只有一条——它能不能自己跑通验收命令，并把结果贴给你看。
第一步：先把仓库改造成「可验证」
工具再强，也强不过仓库里的自动化程度。搭工具链之前，先让一条命令覆盖「静态检查 + 测试」：
# Makefile：Agent 只需要记住这一条命令
.PHONY: check test lint
check: lint test
test:
go test ./... -count=1
lint:
golangci-lint run ./...
Next.js 项目的等价写法放在 package.json：
{
"scripts": {
"check": "next lint && tsc --noEmit && vitest run"
}
}
配套三条约定：命令幂等（重复执行不改动工作区，别拿会自动修复文件的 lint 当验收命令）、命令失败要红（退出码非 0，否则 Agent 会读成「通过」）、命令够快（单次三分钟内，否则改一行没人愿意跑）。
第二步：三层工具的职责划分
| 层 | 典型形态 | 配置落点 | 职责 | 不要用它做 |
|---|---|---|---|---|
| 编辑器助手 | 行内补全 + 侧边栏问答 | 编辑器设置或插件配置 | 局部改写、解释代码、生成样板 | 跨模块重构 |
| 终端 Agent | 命令行 Agent | 项目根配置 + 用户级权限配置 | 检索、改多文件、跑命令、读报错 | 没有验收标准的探索性大改 |
| 本地模型 | 本机推理服务 | 本机端口 + 工具里的模型名 | 敏感代码、离线场景、批量重复任务 | 需要最强推理的复杂设计 |
三层可以共存，但同一时刻只让一层动代码，否则会出现「两个工具互相覆盖对方改动」的场面。
编辑器助手：把上下文范围配清楚
助手类工具的配置大同小异：一份模型清单、一份上下文范围、一个规则文件入口。以常见的 JSON 配置风格为例（字段名按你所用工具调整）：
{
"models": [
{ "title": "云端主力", "provider": "openai", "model": "gpt-class-model" },
{ "title": "本地备用", "provider": "ollama", "model": "qwen2.5-coder:14b" }
],
"context": {
"include": ["**/*.go", "**/*.ts", "**/*.tsx", "AGENTS.md", "docs/**/*.md"],
"excludeGlobs": ["**/node_modules/**", "**/dist/**", "**/vendor/**", "**/*.min.js", "**/.env*", "**/*.lock"]
},
"rulesFile": "AGENTS.md"
}
两个细节值得花时间：排除生成物与锁文件（体积大、信息密度低，会把真正相关的代码挤出上下文），以及把规则文件纳入 include（让助手每次都读到项目约定，写法见第 3 章）。
终端 Agent：先配权限，再放它跑
终端 Agent 的能力来自「能执行命令」，所以配置重点是权限边界，而不是模型选择。
# 权限配置示意：字段名按你所用工具调整
[permissions]
read = ["**"] # 读：允许看整个仓库
write = ["src/**", "internal/**", "tests/**"]
deny_write = [".github/**", "deploy/**", "**/*.sql", "go.mod", "package.json"]
confirm = ["git push", "git reset --hard", "rm -rf", "kubectl apply", "terraform apply"]
timeout_seconds = 300
log_dir = ".ai/logs" # 每次执行的命令与输出留档
两条落地建议：
- 依赖清单与部署脚本设为只读：升级依赖、改 SQL、动流水线属于高风险操作，让 AI 出方案、人来执行。
- 留执行日志，危险命令必须人工确认：日志能回溯「它到底跑了什么」；
git push、reset --hard、批量删除永远不要放进自动允许列表。
本地模型：什么时候值得上
| 维度 | 本机推理服务（如 Ollama 类） | 带图形界面的本地工具 | 带 GPU 的推理服务（如 vLLM 类） |
|---|---|---|---|
| 上手成本 | 低，一条命令拉模型 | 最低，装完即用 | 高，要 GPU 与运维 |
| 适用规模 | 单人、单机 | 单人、试模型 | 团队共享、需要并发 |
| 强项与弱项 | 脚本调用方便，但大模型吃内存 | 探索与对比模型方便，但不易自动化 | 吞吐稳定可长期服务，但成本与维护门槛高 |
判断顺序：代码不能出内网 → 本地或私有部署；能出内网且任务复杂 → 云端主力；需要批量重复处理（比如给 500 个文件补注释） → 本地模型配脚本更省钱。
第三步：一条随时可跑的自检流程
工具链是否真的通了，用一个小任务验证，别靠「装上就算」。
git status --short # 1) 工作区必须干净，避免把已有改动混进验证
make check # 2) 验收命令本身要先是绿的
# 3) 给 Agent 一个可验证的小任务：给 internal/order/service.go 的
# CalculateTotal 补 2 个边界测试（空订单、金额为 0），
# 只改测试文件，改完运行 make check 并贴出完整结果
git diff --stat # 4) 验收：它只动了测试文件，且 make check 为绿
第 4 步是重点：如果它顺手改了业务代码，说明权限或提示词还不够紧，回到前两步收紧。
按场景推荐组合
| 场景 | 组合 | 关键配置 |
|---|---|---|
| 日常写业务代码 | 编辑器助手（补全 + 问答） | 排除生成物、规则文件生效 |
| 跨文件重构、排查报错 | 终端 Agent | 验收命令 + 写权限白名单 |
| 内部敏感项目 | 本地模型 + 编辑器助手 | 关闭云端模型，只留本机模型 |
| 批量重复任务（注释、迁移） | 本地模型 + 脚本 | 固定提示词模板，产出走 diff 审查 |
常见坑
| 坑 | 后果 | 规避 |
|---|---|---|
| 没有一条统一的验收命令 | Agent 无法自证，只能说「已完成」 | 先加 make check |
| 验收命令会修改工作区 | diff 被污染，看不清真实改动 | 验收命令保持只读 |
| 给 Agent 全仓库写权限 | 误改配置、依赖、流水线 | 写权限白名单 + 危险命令确认 |
| 助手读不到规则文件 | 每次都按它自己的偏好写代码 | 把规则文件加入 include 并实测 |
| 让本地小模型干复杂设计 | 产出质量低，还不如不用 | 本地模型只做批量与敏感任务 |
| 多个工具同时改同一模块 | 改动相互覆盖 | 同一时刻只放一个工具动代码 |
小结：工具链的价值不在于装了多少个工具，而在于仓库能被一条命令验证、每个工具职责单一、危险操作有边界；先把 make check 建起来，再按「读全仓、写白名单、危险命令确认」配权限，最后用一个可验证的小任务跑通自检流程——能自己跑测试并把结果贴出来的工具，才算真正接进了工程流程。