适用场景
这套流程适合已经在用 Amp 写代码、想把它扩展到非编码任务的团队与个人：竞品调研、技术选型、日志巡检、文档整理、数据汇总等。核心解决的问题是：非编码任务没有编译器和测试做裁判，智能体容易"看起来干完了"，所以需要用工作目录约定、工具授权和人工验收三条线把它框住。下面以一次「运维巡检 + 一份调研报告」为例走完整流程。
环境与前置条件
- 操作系统：macOS、Linux，或 Windows 下的 WSL2。原生 Windows 的终端兼容性较差，建议走 WSL2。
- 运行时：Node.js LTS 版本，具体最低版本以官方文档当前版本为准。
- 终端与 git：git 不只是版本控制，也是验收阶段判断"智能体到底改了什么"的主要工具。
- 内存与磁盘：8GB 内存起步；工作目录留出几 GB，用于存放原始材料、产出文件和会话日志。
- 网络：能访问所用模型服务；公司网络需确认代理与域名放行。
- 凭证：一个可用的账号或 API Key，具体获取方式以官方页面的当前说明为准。
- 权限：能自己创建工作目录并写入，不需要 sudo。
关键前置动作是先建一个专用工作目录，不要让智能体直接在你的主仓库或家目录根下跑。
分步骤部署
步骤 1：创建工作目录骨架
```bash
mkdir -p ~/agent-workspace/{inbox,output,tasks,scripts,logs}
cd ~/agent-workspace
git init
printf 'inbox/\noutput/\nlogs/\n.env\n*.key\n' > .gitignore
```
各目录职责固定下来，后面所有任务都围绕它转：
inbox/：原始材料，只读，智能体不允许改tasks/：任务说明书，一个任务一个文件scripts/：可复用的提示词模板、巡检清单output/：产出物，写操作只允许落在这里logs/：每次任务的执行记录
成功标志：ls 能看到五个目录，git status 显示这是一个干净的仓库。
步骤 2：安装 Amp CLI
通过 npm 全局安装（包名与安装方式以官方文档当前版本为准）：
```bash
node -v
npm install -g @sourcegraph/amp
amp --help
```
如果 amp --help 打印出了帮助信息，说明命令已经进入 PATH。若提示 command not found，见报错章节第一条。
步骤 3：接入凭证
交互式登录：
```bash
amp login
```
或者在 shell 配置里使用环境变量：
```bash
export AMP_API_KEY="你的密钥"
```
几点约束：
1. 密钥只放本机，写进 ~/.zshrc 这类文件，不要提交进仓库。
2. .env 已经在步骤 1 加进了 .gitignore。
3. 团队共用机器时，每人用自己的凭证，便于审计。
成功标志：执行一次极简任务能返回结果，且没有认证错误。
步骤 4：先跑一次只读任务，确认边界
```bash
cd ~/agent-workspace
amp "统计 inbox/ 下有多少个文件，列出文件名和大小，不要创建或修改任何文件"
```
跑完立刻检查：
```bash
git status
```
预期是 nothing to commit, working tree clean。这一步的目的是确认"只读任务确实不落盘"，如果这里就有文件被创建，说明授权策略还没生效，不要往下走。
步骤 5：配置工具授权
这是整套流程里最重要的一步。Amp 默认对只读操作（列目录、读文件、搜索）比较宽松，对写文件、执行 shell 命令、访问网络通常会要求人工确认。授权大致分三层：
1. 逐次确认：每次有副作用操作都弹出来问你。调研类任务建议保持这一层。
2. 工作区白名单：在项目里放一个配置文件，声明哪些工具、哪些模式允许、拒绝或询问。
3. 全量放行：跳过所有确认。只建议在容器、临时目录、可随时删掉的仓库里使用，不要在你的正式工作目录里开。
白名单的配置文件形状大致如下（字段名、匹配语法以官方文档当前版本为准，这里只示范思路）：
```json
{
"permissions": [
{ "tool": "Bash", "matches": "rm -rf*", "action": "reject" },
{ "tool": "Bash", "matches": "git push*", "action": "reject" },
{ "tool": "Bash", "matches": "curl*", "action": "reject" },
{ "tool": "Bash", "matches": "rg *", "action": "allow" },
{ "tool": "Write", "matches": "output/**", "action": "allow" },
{ "tool": "Write", "matches": "**", "action": "ask" }
]
}
```
编写原则是：拒绝表比允许表更重要。先想清楚"绝对不能发生什么"，再考虑放行什么。常见的拒绝清单：
- 任何
rm、mv、chmod批量操作 git push、git reset --hard、切分支- 任何指向生产环境的命令、API 调用、数据库连接
- 往外部地址上传文件的网络请求
- 修改
inbox/和tasks/
步骤 6：写任务说明书，而不是靠聊天记录
在 tasks/ 下建文件，把要求写死。模板如下：
```markdown
任务：XXX 方案调研
背景
为什么做这件事，谁要看这份产出。
目标产出
- 文件路径：output/调研-xxx.md
- 必须包含：现状、可选方案对比表、推荐方案、风险与未知项
- 篇幅：1500 字以上
约束
- 只使用 inbox/ 下的材料，以及任务中明确允许访问的官方页面
- 每个结论后面标注来源文件名与章节
- 无法核实的写「未验证」，不要推测
禁止
- 不修改 inbox/、tasks/ 下任何文件
- 不执行任何删除、推送、部署类命令
- 不把 inbox/ 内容发送到外部地址
执行方式
先输出执行计划，等我确认后再动手。
```
"先输出计划"这一条是省时间的关键：计划不对，改计划比改产出便宜得多。
步骤 7：下发任务（两段式）
第一段，只要计划：
```bash
cd ~/agent-workspace
amp "阅读 tasks/调研-xxx.md 和 inbox/ 下的材料，输出执行计划：要读哪些文件、要执行哪些命令、产出什么文件。不要创建或修改任何文件。"
```
人工看一遍计划：命令里有没有越界操作？材料够不够？不够就先去补 inbox/。
第二段，确认后执行：
```bash
amp "按你刚才的计划执行。每完成一步，把进展追加到 logs/调研-xxx.log。需要写文件或执行命令时，说明原因。"
```
运维巡检类任务同理，先让它列命令清单：
```bash
amp "读取 scripts/巡检.md，输出你打算执行的只读命令清单，不要执行。"
```
确认清单里没有写操作后，再让它跑，并把结果写到 output/巡检-$(date +%F).md。
步骤 8：人工验收
验收分三查一抽：
查产出位置：
```bash
ls -l output/
git status
git diff --stat
```
查内容是否满足任务书：打开产出文件，对着 tasks/ 里的要求逐条打勾。缺章节、缺对比表、结论没有来源的，直接退回重做，不要自己补。
查副作用：git status 必须是干净的，除非产出文件本身在版本控制里。如果出现了你没预期的改动，先 git checkout 回滚，再回头收紧授权规则。
抽样复核来源：让它给一张映射表——每条结论对应哪个来源文件、哪个章节。抽 2 到 3 条去 inbox/ 里核对。这一步能抓出大部分"看起来很合理但没依据"的内容。
再补一个动作，让它自己交底：
```bash
amp "列出这次任务里你没有把握、或者信息不足的地方，写进 output/调研-xxx-待确认.md"
```
这份"待确认"清单，通常比正文更有价值。
验证部署是否成功
按顺序跑一遍，全部通过说明链路可用：
1. amp --help 有输出，amp --version 能打印版本。
2. 只读任务：amp "统计 inbox/ 下文件数量"，返回的数字和 ls inbox/ | wc -l 一致。
3. 跑完 git status 干净。
4. 写入任务：amp "在 output/ 下创建 hello.md，写一行说明"，文件存在、内容正确，且这个写操作经过了你的确认。
5. 拒绝规则生效：在临时目录里试 amp "执行 rm -rf output"，应当被拒绝或要求二次确认；确认没有真的删除文件。
6. ls logs/ 里能看到本次任务的记录。
第 5 条建议在容器或临时目录里做，别拿正式工作目录试。
常见报错与解决
报错：command not found: amp
原因：npm 的全局 bin 目录不在 PATH 里。
解决：
```bash
npm prefix -g # 拿到全局前缀，bin 目录通常是 <prefix>/bin
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```
不想改 PATH 时，可以临时用 npx @sourcegraph/amp。
报错：认证失败 / 401 / API key invalid
原因：凭证没配置、已过期，或环境变量没有在当前 shell 生效。
解决：
```bash
amp login
或
export AMP_API_KEY="新的密钥"
source ~/.zshrc
```
注意新开的终端窗口不会继承旧窗口里 export 的变量，密钥建议写进 shell 配置文件。
报错：EACCES: permission denied（npm 全局安装或写文件时）
原因：全局目录属主是 root，或工作目录归属不对。
解决：不要用 sudo npm install -g，改用 nvm 管理 Node；目录权限问题：
```bash
ls -ld ~/agent-workspace
chown -R "$USER" ~/agent-workspace
```
报错：请求超时 / ETIMEDOUT / 证书错误
原因：公司网络需要代理，或代理证书没被信任。
解决：
```bash
export HTTPS_PROXY="http://代理地址:端口"
export HTTP_PROXY="$HTTPS_PROXY"
```
同时确认出口规则允许访问模型服务域名，具体域名以官方文档为准。
现象：任务卡住，反复要求确认同一件事
原因：任务边界太宽，或者需要频繁写入但白名单没配。
解决：把任务拆小，一次只做一件事；对确定的低风险操作（比如只往 output/ 写）补一条 allow 规则，而不是整体放行。
现象：上下文超限，读大文件时中断
原因：一次性塞进去的材料太多。
解决：先让它生成文件清单和每个文件的摘要，再按需逐个读取；超大日志先切片：
```bash
split -l 2000 big.log logs/part-
```
后续维护
备份：把工作目录当代码仓库管理。tasks/、scripts/、output/ 都纳入 git，.env 排除在外。定期打快照：
```bash
cd ~/agent-workspace && git add -A && git commit -m "快照 $(date +%F)"
tar czf ~/backup-agent-workspace-$(date +%F).tar.gz ~/agent-workspace
```
升级：升级前先跑一遍上面的验证清单，确认授权规则仍然生效。
```bash
npm outdated -g
npm update -g @sourcegraph/amp
```
具体升级方式与支持的版本以官方文档当前版本为准。
日志与审计：logs/ 里的记录按任务名加日期命名，保留提示词原文和产出路径。涉及系统变更的命令，和 shell history 交叉核对一遍。有副作用的任务，建议保留原始 prompt 至少三个月。
权限复查：每季度过一遍白名单，删掉不再需要的 allow 规则。规则只增不减，是这类工具最常见的安全债。
密钥轮换：AMP_API_KEY 定期更换，换完记得同步到所有用到的机器。
成本与额度：计费方式、免费额度、用量上限均以官方页面的当前说明为准，长任务建议先小范围试跑再放量。
产出质量回看：把退回重做的任务记下来，补进 tasks/ 模板的约束里。跑上十几次之后，模板本身就成了这套流程最值钱的部分。