Agent 工作流搭建总结

 Posted on June 3, 2026  |  6 minutes  |  1111 words  |  Wang

AI Coding Agent 工作流搭建总结

受控执行型系统 · Intel Mac 2018 · 双系统路线

一、硬件底座与系统分支

设备： MacBook Pro 15-inch (2018, Intel i7, 16GB RAM)

根据系统版本，路线完全不同——先确认你的 macOS 版本：

系统版本工具选择原因
macOS 12 MontereyVS Code 1.123 + ClineVS Code 原生兼容，Cline 插件完整支持
macOS 10.15 CatalinaOpenCode CLIVS Code 从 v1.86 起断供 Catalina，Cline 无法正常运行

以下第二至十章为 macOS 12 Monterey + Cline 路线。 Catalina 用户请直接跳至 附录：macOS 10.15 Catalina — OpenCode CLI 路线。

三条共同硬限制（两个路线均适用）：

  • 本地推理不可行：Ollama / Qwen 等本地模型在 16GB 机器上会触发风扇满载
  • 固定订阅不划算：$20/月网页端 Pro 存在阵发性闲置，且有 Token 限流
  • 唯一出路：轻量工具 + 云端 API 按量计费，推理在云端，本地负载极低

二、工具范式对比

维度Cline (VS Code 插件)OpenCode (Terminal)Claude Code (CLI)
定位IDE 内结对程序员任务编排系统全自动驾驶系统
核心机制Human-in-the-loopMulti-agent 编排Context Compaction
交互界面Sidebar 可视化 DiffTerminal / Session 隔离纯文本 CLI
适合场景非连续开发、多 Debug自动化流水线大型旧库长周期重构
老 Mac 负载极低低极低

现阶段选择：Cline，原因是 Human-in-the-loop 可视化 Diff 适合建立初期纪律，后续可无缝迁移至 OpenCode / Claude Code。

三、大模型能力的去幻想化定位

  • Free Tier API（OpenRouter Free 等）≠ Production Agent 高延迟、限流排队、Tool Calling 极不稳定，严禁作为 Agent 主力。

  • Gemini 1.5 Pro = 海量上下文阅读器 擅长通读整个 Repo 和分析大日志，但多文件修改一致性和指令遵循度（Instruction Adherence）明显弱于 Claude，适合白嫖训练阶段。

  • Claude 3.5 Sonnet = 工业级代码执行上限 $5 充值的执行力远超任何免费混合路由。是复杂攻坚的切换目标。

结论：放弃多模型动态路由。白嫖训练锁定 Gemini 1.5 Pro，复杂攻坚一键切换 Claude Sonnet。

四、Cline 安装与基础配置

Step 1 — 安装

VS Code 扩展市场搜索 Cline（saoudrizwan.claude-dev），侧边栏出现机器人图标即完成。

安装前确认 Node.js ≥ 18：

node -v
# 低于 18 则执行：brew install node

Step 2 — 配置 Gemini 1.5 Pro

Cline 设置 → Provider 选 Google Gemini → 填入 API Key（从 aistudio.google.com 免费获取）→ Model 选：

gemini-1.5-pro-latest

保存后点击 Test 确认连通。

Step 3 — Tool Permission 设置（核心，优先级高于任何 Prompt）

Agent 的安全性由权限层决定，不由 Prompt 决定。

在 Cline Auto-approve 设置里：

  • ✅ Read files
  • ✅ Write files（保留 Diff 预览）
  • ❌ Execute commands — 关闭
  • ❌ Browser actions — 关闭
  • ❌ MCP tools — 关闭（初期）

五、System Prompt（精简 5 规版）

设计原则：ChatGPT 审查指出原版 7 条过重，会削弱 Gemini 的任务理解能力。保留最关键的行为约束，删除可由权限层替代的条目。

进入 Cline 设置，粘贴以下内容：

You are a coding assistant.

Rules:
1. Before ANY code change, output a numbered plan. Wait for user approval.
2. Modify at most 3 files per response. Stop and ask if more are needed.
3. Never run shell commands without explicit instruction.
4. Never delete files. List them and wait for approval.
5. After each task: list files changed and what to test.

切换 Claude Sonnet 时：仅修改 Provider 和 Model，System Prompt 保持不变。

六、项目级 .clinerules（Context 预算控制）

定位说明：.clinerules 是 token 节流阀，不是安全沙盒。其价值在于防止 Gemini 把整个 Repo 塞入上下文，不是作为权限控制层使用。

在 Python / Cloudflare Workers 项目根目录创建 .clinerules：

# CLINE PROJECT RULES

## Scope
- Ignore: .git, __pycache__, .wrangler, node_modules
- Never read .env or wrangler.toml credentials section directly; ask the user

## Log handling
- If any log or script output exceeds 20 lines, read only the last 15 lines

## File structure (按项目填写)
- src/main.py         — entry point
- src/utils/          — shared helpers
- workers/index.ts    — CF Worker entry

## Conventions
- Python: black formatter, type hints required
- CF Workers: Web APIs only, no npm packages

对话开场白模板（每次新任务开始时用，替代喂整个项目）：

Task scope: [具体文件路径]
Context: [1-3 句话描述现状]
Do NOT read any files outside this scope unless I say so.

七、“五轮一抽离"机制

Gemini 百万 Token 窗口容易引发挥霍错觉。Context drift 是 Agent 崩坏的首要原因。

规则：对话达到 5-6 轮，立即点击 New Task 清空历史。

新对话接力 Prompt：

当前项目一阶段修改已完成。[文件名] 的现状是 [简述核心变动]。
接下来进行第二步：[新任务描述]。不要读历史，基于当前代码开始。

如需在重置前保留进度，让 Cline 输出快照：

Summarize everything decided and changed in this session.
Format: files modified / key decisions (max 5) / remaining tasks.
Keep under 200 words.

八、防御性工程安全设计

物理文件保护

ChatGPT 审查认为 chmod 444 是"心理意义大于实际”，但这个判断忽略了人类深夜疲惫时的误操作场景。将"需要自律"的事变成"系统强制"是 Defensive Engineering 的标准做法，保留此设计。

chmod 444 .env
chmod 444 wrangler.toml

即使深夜疲惫误点 Approve，macOS 底层的 Permission Denied 是最后一道物理闸门。

Git 防误推

git config branch.main.pushRemote no_push

此后 git push 在 main 分支上报错，防止 Cline 误触。

每次开工前 30 秒检查

git status
git stash   # 有未提交变更先存起来
git branch  # 确认在正确分支

死循环识别与终止

识别信号：同一文件反复修改超过 3 次 / 相同类型报错超过 2 次 / 出现 “I apologize, let me try again”。

终止操作：点停止按钮，然后输入：

Stop. Tell me: what is the EXACT error, and what have you tried so far?
Do not write any more code until I respond.

误删恢复路径

  • 第一层：git checkout -- [文件]
  • 第二层：git reflog 找 hash，git checkout [hash] -- [文件]
  • 第三层：macOS Time Machine（建议开启，指向外置硬盘）

九、三种工业级 Prompt 模板

Bug Fix

[GOAL]
Fix ONLY the reported bug in: {文件名}
Do not refactor surrounding code. Keep diff minimal.

[CONTEXT]
Error: {粘贴 traceback 最后 5 行 或 wrangler tail 异常}
Relevant code: {相关代码片段}

[CONSTRAINTS]
- Fix ONLY the root cause
- Do not add new dependencies
- If unsure, ask before editing
- Output: diff + one-line root cause

Feature

[GOAL]
Add: {一句话描述新功能}
Location: {文件路径 / 模块名}

[ACCEPTANCE CRITERIA]
1. {可测试条件 1}
2. {可测试条件 2}
3. {可测试条件 3，最多 3 条}

[OUT OF SCOPE]
- {明确排除项}

[CONSTRAINTS]
- CF Workers: Web APIs only, do not modify wrangler.toml
- Python: type hints required, no new packages
- Proceed only after outputting a numbered plan

Refactor

[GOAL]
Refactor: {文件/函数名}
Reason: {一句话说明为什么重构}

[HARD CONSTRAINTS]
- ZERO behavior change. Input/output must be identical
- Do not rename public functions or change signatures
- Do not add new features
- Do not change error handling behavior

[ALLOWED CHANGES]
- {明确允许的改动}

[VERIFICATION]
After refactoring, confirm: "All existing tests still pass with no modifications."
If no tests exist, list cases I should manually verify.

Output: diff only.

重构前必做：git add . && git stash，确保有退路。

十、演进路线

阶段一：白嫖训练              阶段二：轻量攻坚              阶段三：进阶生产
Cline + Gemini 免费 Key  →  Cline + $5 Claude API  →  OpenCode / Claude Code
熟悉 Diff 与 5 轮重置机制     阵发性高频任务，月均几美分      全自动多 Agent 编排

十一、核心认知

权限控制 + Context 裁剪 + Workflow 纪律 > 模型本身的选择

Agent 稳定性不等于 Prompt 长度。Agent 安全性不等于文件权限数量。选择正确的控制点，而不是堆砌控制点。

在 macOS 12 Monterey 上，这套配置以最低硬件负载和最高执行纪律，将一台 2018 款 Intel Mac 嵌入了 2026 年的 Agent 编程工作流。

附录：macOS 10.15 Catalina — OpenCode CLI 路线

为什么 Catalina 上 VS Code + Cline 走不通

两座不可逾越的墙：

  • VS Code 官方断供：从 v1.86 起彻底放弃 macOS 10.15 支持，新版本双击直接报错。
  • Cline 插件生态脱节：退回到 v1.85 之前的旧版 VS Code 虽然能打开，但 Cline 最新插件要求高版本底座，旧版 VS Code 只能安装极早期的 Cline，既不认识 Gemini 新接口，也没有红绿 Diff 视图。

结果：系统太老 → 软件太老 → 插件断供，无尽内耗。

为什么 OpenCode 是 Catalina 的正确选择

OpenCode 是用 Go 语言编写的单文件二进制 CLI。Go 编译产物不依赖 macOS UI 渲染层，直接调用底层 Posix 接口，对系统版本无感知。macOS 10.15、12、最新版，行为完全一致。

内存优势同样显著：VS Code（Electron 架构）开机数个插件就能吃掉大量内存，OpenCode 作为终端工具内存占用可忽略不计。

安装 OpenCode（官方二进制，非 pip 包）

Step 1 — 一行安装

curl -fsSL https://opencode.ai/install | bash

脚本自动检测 Intel 芯片（amd64），下载至 ~/.opencode/bin/。

Step 2 — 配置环境变量

echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc
echo 'export GEMINI_API_KEY="你的AIzaSy...密钥"' >> ~/.zshrc
source ~/.zshrc

验证：opencode --version 输出版本号即成功。

在终端使用 OpenCode 的两个关键习惯

习惯 1 — 用 AGENTS.md 做任务计划书

进入项目目录后：

opencode run "任务描述"

OpenCode 不会立刻改代码，而是先生成 AGENTS.md 并打印计划。用 cat AGENTS.md 或直接双击查看，确认步骤合理后输入 y 批准执行。

习惯 2 — 每次改动前先 Git 存档

没有图形界面的撤销机制，Git 是唯一后悔药：

git init   # 项目首次使用时执行一次
git add . && git commit -m "AI改动前的干净版本"

如果 OpenCode 把代码改崩，一行恢复：

git restore .

Catalina 路线的安全铁律

与 Monterey + Cline 路线相同的核心约束，在 OpenCode 里通过 AGENTS.md 约束模型行为：

# AGENTS.md 约束头部（每次任务开始前写入）

Rules:
1. Output a numbered plan before any code change. Wait for approval.
2. Modify at most 3 files per task. Stop and ask if more are needed.
3. Never delete files. List them and wait for approval.
4. Do not modify .env or any credentials file.
5. After task: list files changed and what to test.

Catalina 演进路线

阶段一：白嫖训练                    阶段二：轻量攻坚
OpenCode + Gemini 免费 Key  →  OpenCode + $5 Claude API
熟悉 CLI 工作流与 Git 恢复机制       阵发性高频任务，月均几美分

Catalina 用户跳过 OpenCode 直接用 Claude Code 也是可行路线，两者都是 CLI 架构，安装方式类似，行为约束逻辑完全相同。

📚 所有文章