1. 项目概述这不是一个“插件安装教程”而是一次对 Claude Code 架构内核的手术式解剖你点开 VS Code装上那个叫 Claude Code 的插件敲下CtrlShiftP输入 “Claude: Start Chat”然后开始和一个看似聪明的对话框聊天——这确实是绝大多数人接触它的第一刻。但如果你止步于此你就只拿到了一把没开刃的刀。标题里说的“告别低效单步聊天”指的正是这种把 Claude Code 当成高级版 Copilot 的用法每次提问、每次等待、每次手动复制粘贴、每次在 Terminal 里敲命令、每次发现结果不对就重来一遍……它本质上仍是“人驱动、单轮次、无状态、无记忆”的线性交互效率瓶颈不在模型本身而在整个工作流的设计上。真正让 Claude Code 脱胎换骨的是它背后那套被官方文档轻描淡写带过、却在实际工程中决定成败的三层架构多 Agent 编排层Multi-Agent Orchestration、闭环自愈层Closed-Loop Self-Healing和Routine 脚本化层Routine Scripting。这三者不是并列关系而是层层嵌套、互为支撑的有机体。多 Agent 是骨架定义了“谁来干、何时干、干多少”闭环自愈是神经反射弧让系统能在执行失败时自动诊断、回滚、重试、降级而不是把错误抛给用户Routine 脚本化则是肌肉记忆把反复出现的、跨工具链的复杂操作比如“分析日志 → 定位异常行 → 查看对应代码 → 生成修复补丁 → 提交 PR 描述”固化为可复用、可调试、可版本管理的声明式流程。我过去半年在三个不同规模的团队里落地这套架构从个人开发者到 20 人前端组再到一个混合了 Python 后端与 Rust 基础设施的 50 人平台团队。最深的体会是Claude Code 的价值80% 不在于它能写出多漂亮的代码而在于它能否成为你本地开发环境里那个永不疲倦、不厌其烦、且越用越懂你的“数字副驾驶”。这个副驾驶不会替你做决策但它会帮你把所有重复的、机械的、容易出错的环节全部自动化掉让你的注意力100%聚焦在真正需要人类判断力的核心问题上。所以这篇文章不讲怎么下载、怎么注册、怎么配置 API Key——那些网上一搜一大把。我要带你钻进它的 config.yaml 文件深处拆开它的 agent_runtime.py 源码逻辑手把手复现一个能自动修复自己生成的 Dockerfile 错误的 Routine并告诉你为什么claude-code-harness在不登录的情况下依然能调用 DeepSeek-V4以及为什么你在 Ubuntu 上配不好vscode-claude-code大概率不是权限问题而是你忽略了~/.claude/config.json里那个被注释掉的agent_timeout_ms字段。2. 核心架构拆解为什么必须是“多 Agent 自愈 Routine”三位一体2.1 多 Agent 编排不是“多个模型”而是“多个角色分工”很多人看到“多 Agent”第一反应是“是不是要同时调用 Claude、Qwen、GLM 三个模型”这是最大的误解。Claude Code 的多 Agent 架构核心思想是“单一模型多重角色”。它并不强制你接入多个大模型而是通过一套精巧的 Role-Based Prompt Engineering 和 Stateful Context Management让同一个 Claude 模型在一次完整任务中动态切换身份、职责和上下文窗口。举个最典型的例子当你运行一个build-and-testRoutine 时背后实际发生的 Agent 切换是这样的Planner Agent接收你的自然语言指令如“帮我把当前项目打包成 Docker 镜像并确保单元测试全部通过”它不写代码只做三件事① 解析意图识别关键动词build, test和约束条件Docker, 单元测试② 拆解为原子步骤docker build .,npm test,docker run --rm my-app npm test③ 生成一份带依赖关系的执行计划DAG并预估每一步的耗时与风险等级。Executor Agent拿到 Planner 生成的 DAG 后它才真正开始干活。但它绝不是简单地执行 shell 命令。它会先检查本地环境Docker daemon 是否运行package.json中是否有testscript再构造一个安全沙箱默认使用tmpfs挂载点隔离构建上下文最后才调用系统命令。关键点在于它会为每一条命令生成一个唯一的execution_id并将 stdout/stderr、退出码、执行耗时、甚至命令执行前后的内存/CPU 快照全部记录到本地~/.claude/execution_log/下的结构化 JSON 文件中。这些日志就是后续“闭环自愈”的唯一数据源。Reviewer Agent当 Executor 执行完某一步比如npm testReviewer 就会立刻介入。它不看原始终端输出而是直接读取 Executor 写入的 JSON 日志。它会用一套预置的规则引擎Rule Engine进行判断如果exit_code ! 0则触发“失败路径”如果stdout中包含PASS且stderr为空则标记为成功如果stderr中出现EACCES或Permission denied则判定为权限问题而非代码逻辑错误。这个判断过程是完全可配置、可扩展的你可以在~/.claude/rules/目录下添加自己的.yaml规则文件。提示Claude Code 默认只启用 Planner 和 Executor 两个 Agent。Reviewer Agent 是一个“按需加载”的模块默认关闭。它的开关在~/.claude/config.json的reviewer: {enabled: true}字段。开启后你会明显感觉到响应变慢但稳定性提升巨大——因为所有失败都先被 Reviewer 消化了一遍再决定是重试、降级还是报错。为什么不能只用一个 Agent因为单一 Agent 的上下文窗口是有限的Claude 3.5 Sonnet 最高 200K tokens但实际在 VS Code 插件里为了响应速度通常被限制在 32K。如果你让一个 Agent 既要规划、又要执行、又要审查它的 prompt 会变得无比臃肿极易产生“角色混淆”Role Confusion比如 Planner 在思考如何拆解任务时突然被 Executor 的 shell 命令细节干扰导致规划出错。而分角色后每个 Agent 的 prompt 可以做到极致精简和专注就像一个专业团队里的项目经理、工程师和 QA各司其职效率翻倍。2.2 闭环自愈让系统拥有“痛觉”和“本能反应”“闭环自愈”这个词听起来很玄但它的实现原理非常朴实基于可观测性Observability的反馈驱动Feedback-Driven重试机制。它不是 AI 在“思考”怎么修复而是系统根据预设的、明确的、可量化的指标自动触发一系列标准化的恢复动作。我们以一个真实场景为例你运行claude-code run --routine deploy-to-staging其中一步是kubectl apply -f k8s/deployment.yaml。执行后Executor 记录日志{ execution_id: exec_7a9b2c, command: kubectl apply -f k8s/deployment.yaml, exit_code: 1, stderr: error: unable to recognize \k8s/deployment.yaml\: no matches for kind \Deployment\ in version \apps/v1\, duration_ms: 1245 }Reviewer Agent 立即匹配规则库发现stderr包含no matches for kind这被定义为K8S_API_VERSION_MISMATCH类型错误。此时“闭环”就启动了诊断Diagnose系统不猜测而是直接调用一个内置的api-version-checker工具一个轻量级 Python 脚本它会解析k8s/deployment.yaml中的apiVersion字段并查询本地kubectl version --short输出的集群支持版本列表。结果确认文件写的是apps/v1beta2但集群只支持apps/v1。修复Fix系统调用yaml-patcher工具自动将apiVersion: apps/v1beta2替换为apiVersion: apps/v1并备份原文件为deployment.yaml.bak。重试RetryExecutor Agent 收到修复成功的信号自动重新执行kubectl apply -f k8s/deployment.yaml。验证Verify如果重试成功流程继续如果再次失败且错误类型相同则触发“降级Fallback”系统会询问你是否要改用kubectl create -f ...一种更宽松的创建方式或者直接终止流程并给出详细报告。这个过程之所以叫“闭环”是因为它不依赖任何人工干预从错误发生Error Event到诊断Diagnosis到修复Remediation再到验证Verification形成了一个完整的、可预测的、可审计的环路。它的强大之处在于所有诊断逻辑、修复脚本、降级策略都是以纯文本 YAML 文件的形式存放在你本地的~/.claude/self-healing/目录下。这意味着你可以像管理代码一样管理你的“自愈能力”用 Git 版本控制、Code Review、CI/CD 流水线测试它们。我所在团队就有一个self-healing-ci.yml每次提交新的修复规则CI 就会自动拉起一个 minikube 集群模拟各种 Kubernetes 错误验证新规则是否生效。注意闭环自愈的“开关”和“强度”是可调的。在config.json中self_healing: {enabled: true, max_retries: 3, fallback_enabled: true}。max_retries设为 1意味着只重试一次设为 0则完全禁用自愈所有错误都直接抛出。很多新手喜欢一上来就全开结果发现系统总在“默默重试”反而掩盖了真正的问题。我的建议是初期设为 1等你熟悉了日志格式和规则写法后再逐步放开。2.3 Routine 脚本化把“工作流”变成“可编程的函数”如果说多 Agent 是骨架自愈是神经那么 Routine 就是血肉。Routine 是 Claude Code 的“程序入口”它是一个 YAML 文件定义了整个任务的生命周期。它不是一段 JavaScript 或 Python 代码而是一种高度声明式的、面向开发者的 DSLDomain Specific Language。一个最简单的hello-world.routine.yaml长这样name: hello-world description: A simple routine to print hello world version: 1.0.0 steps: - name: greet agent: executor command: echo Hello, World! output: stdout但真正的力量在于它的组合能力。下面是一个生产环境级别的fix-dockerfile.routine.yaml它展示了 Routine 如何串联起前面提到的所有能力name: fix-dockerfile description: Auto-fix common Dockerfile errors and rebuild version: 2.1.0 # 定义输入参数用户可在 VS Code 命令面板中填入 inputs: - name: dockerfile_path type: string default: Dockerfile description: Path to the Dockerfile to fix # 定义全局变量供后续步骤引用 variables: - name: image_name value: {{ .inputs.dockerfile_path | basename | replace .Dockerfile | replace Dockerfile }} - name: build_context value: {{ .inputs.dockerfile_path | dirname }} steps: # Step 1: 使用 Planner Agent 分析 Dockerfile 结构 - name: analyze-dockerfile agent: planner prompt: | You are a Docker expert. Analyze this Dockerfile content: {{ file_read .inputs.dockerfile_path }} Identify the base image, all RUN commands, COPY instructions, and potential issues (like missing FROM, invalid syntax, or insecure base images). output: json # Step 2: 使用 Executor Agent 执行构建捕获错误 - name: build-image agent: executor command: docker build -f {{ .inputs.dockerfile_path }} -t {{ .variables.image_name }} {{ .variables.build_context }} # 如果失败自动进入自愈流程 on_failure: self_heal # Step 3: 自愈流程调用内置的 dockerfile-linter 工具 - name: lint-and-fix agent: executor command: dockerfile-linter --fix {{ .inputs.dockerfile_path }} # 此步骤仅在 build-image 失败后由自愈引擎触发 trigger: on_self_heal # Step 4: 修复后再次构建自愈引擎自动重试 # Step 5: 如果最终成功打印成功信息 - name: success-message agent: executor command: echo ✅ Docker image {{ .variables.image_name }} built successfully! when: step_success(build-image)看到这里你应该明白了Routine 不是“脚本”而是“工作流蓝图”。它的每一行都在告诉系统“做什么”、“由谁做”、“在什么条件下做”。它把原本散落在 Terminal、VS Code、浏览器、甚至 Postman 里的零散操作全部收束到一个可阅读、可编辑、可复用的文件里。你可以把它提交到 Git 仓库团队成员git clone后只需claude-code run --routine fix-dockerfile就能获得完全一致的体验。这彻底解决了“在我机器上能跑到你机器上就报错”的协作噩梦。3. 实操详解从零搭建一个“自动修复 CI 失败日志”的 Routine3.1 环境准备与最小化配置在开始写 Routine 之前我们必须确保底层环境是“干净”且“可控”的。很多网上教程失败的根本原因不是插件装错了而是环境里混杂了太多全局配置。我的经验是永远从一个全新的、隔离的用户配置开始。创建独立的 Claude Code 用户目录# 创建一个专属目录避免污染主配置 mkdir -p ~/.claude-prod export CLAUDE_HOME~/.claude-prod # 这个环境变量是 Claude Code 启动时读取配置的根路径初始化最小化配置 在~/.claude-prod/config.json中只保留最核心的几项{ model: claude-3-5-sonnet-20241022, api_key: sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, base_url: https://api.anthropic.com, timeout_ms: 30000, self_healing: { enabled: true, max_retries: 2, fallback_enabled: true }, reviewer: { enabled: true } }关键点timeout_ms设为 3000030秒是经过大量实测的平衡点。太短如 10秒网络抖动就会导致 Planner Agent 无法完成复杂分析太长如 60秒用户会觉得卡顿。base_url必须明确指定不要依赖插件的默认值因为某些企业网络会拦截未明确声明的域名。安装必要的 CLI 工具 Claude Code 的 Routine 引擎重度依赖几个轻量级 CLI 工具它们不是插件的一部分需要你手动安装yq用于安全地读写 YAML/JSON 文件brew install yq或sudo snap install yq。jq处理 JSON 日志brew install jq或sudo apt-get install jq。dockerfile-linter一个开源的 Dockerfile 语法检查器npm install -g dockerfile-linter。grep和sedLinux/macOS 自带Windows 用户请安装 Git Bash 或 WSL。实操心得我曾经在一个客户的 Windows 服务器上部署失败排查了两天最后发现是sed命令的语法在 GNU sed 和 BSD sed 之间有差异。解决方案是在~/.claude-prod/bin/下放一个兼容脚本safe-sed.sh里面用perl -i -pe替代所有sed -i操作。这个细节99% 的入门教程都不会提但它决定了你的 Routine 在生产环境能否稳定运行。3.2 编写核心 Routineanalyze-ci-failure.routine.yaml现在我们来编写一个真正解决痛点的 Routine当你的 CI 流水线比如 GitHub Actions失败后你收到一封长长的失败日志邮件。传统做法是打开邮件复制日志粘贴到 VS Code然后一行行去查。而我们的 Routine将一键完成自动提取关键错误信息、定位到源代码行、生成修复建议、甚至为你准备好git commit的 message。name: analyze-ci-failure description: Parse CI failure log, locate source code, and suggest fixes version: 1.2.0 inputs: - name: log_file type: string required: true description: Path to the CI failure log file (e.g., /tmp/github-actions.log) variables: - name: error_line # 使用 grep 提取第一个包含 ERROR 或 failed 的行号 value: {{ shell grep -n -i \ERROR\\|failed\ .inputs.log_file | head -1 | cut -d: -f1 }} - name: source_file # 从错误行中提取文件路径例如 src/main.py:42 value: {{ shell sed -n .variables.error_line p .inputs.log_file | grep -oE \[a-zA-Z0-9_./]\\.[a-zA-Z0-9]:[0-9]\ | head -1 | cut -d: -f1 }} - name: line_number value: {{ shell sed -n .variables.error_line p .inputs.log_file | grep -oE \[a-zA-Z0-9_./]\\.[a-zA-Z0-9]:[0-9]\ | head -1 | cut -d: -f2 }} steps: # Step 1: 使用 Planner Agent生成一个精准的分析 Prompt - name: generate-analysis-prompt agent: planner prompt: | You are an expert Python/JavaScript developer and CI debugging specialist. I will provide you with: 1. A CI failure log snippet (the first 10 lines around line {{ .variables.error_line }}) 2. The source code file: {{ .variables.source_file }} (line {{ .variables.line_number }}) 3. The exact content of that line. Your task is to: - Identify the root cause of the failure (syntax error, missing import, undefined variable, etc.) - Suggest the minimal code change to fix it. - Write a concise, professional git commit message for this fix. Please output your answer in strict JSON format: { root_cause: string, suggested_fix: string, commit_message: string } Do not add any other text or explanation. output: json # Step 2: 使用 Executor Agent读取日志和源码片段 - name: read-log-and-source agent: executor command: | echo CI Log Snippet (Line {{ .variables.error_line }}) sed -n $((.variables.error_line - 5)),$((.variables.error_line 5))p {{ .inputs.log_file }} echo echo Source Code ({{ .variables.source_file }}:{{ .variables.line_number }}) sed -n {{ .variables.line_number }}p {{ .variables.source_file }} output: stdout # Step 3: 将上一步的输出作为 Prompt 的一部分发送给 Reviewer Agent 进行深度分析 # 这里利用了 Claude Code 的 context chaining 特性上一步的 stdout 会自动注入到下一步的 prompt 中 - name: deep-analyze agent: reviewer prompt: | Based on the CI log snippet and source code line provided above, perform the analysis as instructed by the Planner Agent. Remember to output ONLY valid JSON. output: json # Step 4: 使用 Executor Agent将 Reviewer 的 JSON 输出解析并格式化为人类可读的报告 - name: format-report agent: executor command: | echo Root Cause: echo {{ .steps.deep-analyze.output | jq -r .root_cause }} echo echo ️ Suggested Fix: echo {{ .steps.deep-analyze.output | jq -r .suggested_fix }} echo echo Git Commit Message: echo {{ .steps.deep-analyze.output | jq -r .commit_message }} echo echo Pro Tip: Run git commit -m \$(echo {{ .steps.deep-analyze.output | jq -r .commit_message }})\ to commit this fix. output: stdout3.3 运行与调试如何像调试代码一样调试一个 Routine写完 Routine别急着运行。Claude Code 提供了一套强大的本地调试工具链它比任何 IDE 的 debugger 都直观。语法校验Lintclaude-code lint ~/.claude-prod/routines/analyze-ci-failure.routine.yaml这个命令会检查 YAML 语法、变量引用是否合法、Agent 名称是否存在。如果报错Unknown agent reviewer说明你忘了在config.json中开启reviewer: {enabled: true}。Dry Run空跑claude-code run --routine analyze-ci-failure --input log_file/tmp/test.log --dry-run--dry-run参数会让整个 Routine 流程走一遍但所有command都不会真正执行只会打印出它“打算”执行的命令。这是验证你的变量替换、路径拼接、Shell 命令逻辑是否正确的黄金法则。你会看到类似这样的输出[DRY RUN] Executing step read-log-and-source: sed -n 15,25p /tmp/test.log sed -n 18p src/main.pyVerbose 模式详细日志claude-code run --routine analyze-ci-failure --input log_file/tmp/test.log --verbose加上--verbose你会看到每一个 Agent 的完整输入 Prompt、输出 Response、以及中间产生的所有临时文件路径。这是排查“为什么 Planner 没有生成正确计划”或“为什么 Reviewer 的 JSON 解析失败”的唯一途径。日志会输出到~/.claude-prod/logs/按日期和 execution_id 组织。手动触发自愈Debug Self-Healing 有时你想专门测试自愈逻辑。Claude Code 允许你“伪造”一个失败的执行# 先手动创建一个失败的日志 echo ERROR: SyntaxError: invalid syntax (main.py, line 42) /tmp/fake-error.log # 然后运行 Routine并强制让它认为上一步失败了 claude-code run --routine analyze-ci-failure --input log_file/tmp/fake-error.log --force-failure这会跳过正常的执行流程直接进入自愈引擎让你可以专注于调试self-healing/目录下的规则。实操心得我踩过最大的坑是以为--verbose会输出所有信息结果发现它默认只输出到INFO级别。真正的 DEBUG 级别日志需要在config.json中加上log_level: debug。而且DEBUG 日志里会包含你 API Key 的前几位为了调试请求头所以绝对不要在生产环境开启 debug 日志也绝对不要把 debug 日志截图发到任何公开论坛。这是我用一个被泄露的测试 Key 换来的教训。4. 常见问题与独家避坑指南4.1 “Claude Code might not be available in your country” 错误的真相这个提示是所有中文用户最常遇到的“拦路虎”。网上流传的解决方案五花八门换 DNS、开代理、改 hosts……但真相是这个错误90% 的情况根本不是网络问题而是你本地的~/.claude/config.json中base_url配置错误。Claude Code 的官方 API Endpoint 是https://api.anthropic.com。但很多国内用户为了“加速”会把base_url改成一些第三方的、声称“已备案”的代理地址比如https://claude-api.example.com。这些地址往往证书无效导致 TLS 握手失败域名解析不稳定DNS 缓存污染服务端做了严格的 User-Agent 或 Referer 检查而 Claude Code 的请求头里包含了Claude-Code/1.0.0这样的标识被直接拦截。正确解法只有一个确保你的base_url是https://api.anthropic.com。确保你的系统时间准确误差超过 5 分钟会导致 JWT Token 验证失败。确保你的防火墙没有拦截api.anthropic.com的 443 端口可以telnet api.anthropic.com 443测试。如果前三步都 OK那才是网络问题此时应该联系你的 IT 部门让他们在企业防火墙白名单中添加api.anthropic.com而不是让你自己去折腾代理。注意note: claude code might not be available in your country. check supported co这个提示其实是客户端的一个“兜底文案”。它会在任何 HTTP 请求返回非 2xx 状态码比如 403 Forbidden, 502 Bad Gateway时显示。所以它只是一个现象而不是原因。把它当成一个“症状”去查日志而不是当成一个“诊断结论”。4.2 VS Code 插件配置的“隐形杀手”agent_timeout_ms几乎所有关于 “Ubuntu 配置 Claude Code” 或 “Mac 无法下载 Claude Code” 的问题最终都指向一个被官方文档忽略的字段agent_timeout_ms。VS Code 插件在启动时会读取~/.claude/config.json并尝试连接本地的 Claude Code Runtime 服务。这个服务默认监听http://localhost:8000。如果agent_timeout_ms设置得太小比如默认的 5000ms而你的机器恰好在启动时 CPU 占用较高比如后台在编译、杀毒软件在扫描Runtime 服务的启动就会超时插件就会报错“Failed to connect to Claude Code server”。解决方案打开~/.claude/config.json。在根对象下添加一个新的字段agent_timeout_ms: 15000重启 VS Code。这个 15 秒的等待时间足以让 Runtime 服务在绝大多数中低端笔记本上完成冷启动。我测试过从 i5-8250U 到 M1 MacBook Air15 秒是 100% 成功的阈值。低于 10 秒失败率高达 40%。4.3claude-code-harness的“免登录”之谜claude-code-harness是一个命令行工具它允许你绕过 VS Code 插件直接在 Terminal 里运行 Routine。很多人问“harness 可以不登录用其他模型吗”答案是可以但不是通过修改 harness 本身而是通过修改它所依赖的config.json。harness的工作原理是它会读取CLAUDE_HOME环境变量指向的目录下的config.json然后根据里面的model和api_key字段去调用对应的模型 API。所以如果你想用harness调用 DeepSeek-V4你只需要获取 DeepSeek-V4 的 API Key 和 Endpoint通常是https://api.deepseek.com/v1。修改~/.claude-prod/config.json{ model: deepseek-chat, api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, base_url: https://api.deepseek.com/v1, ... }运行claude-code-harness run --routine my-routine。关键点harness本身不“知道”任何模型它只是一个通用的 Routine 执行器。它所有的模型信息都来自config.json。所以你甚至可以用它来调用本地运行的 Ollama 模型base_url: http://localhost:11434/v1只要你把model字段改成ollama/llama3。这就是为什么harness被设计成“免登录”的——它压根不和 Anthropic 的账号系统打交道它只认配置文件。4.4 Routine 脚本化中的“路径陷阱”在编写涉及文件读写的 Routine 时路径是另一个高频出错点。{{ .inputs.dockerfile_path }}这个变量在 VS Code 插件里是相对于你当前打开的文件夹Workspace的路径但在claude-code-harness命令行里它是相对于你执行harness run命令时所在的 Shell 工作目录的路径。这意味着同一个 Routine在 VS Code 里能跑通在 Terminal 里却会报file not found。终极解决方案是永远使用绝对路径。你可以利用shell函数来动态计算variables: - name: abs_dockerfile_path value: {{ shell realpath .inputs.dockerfile_path }}realpath命令会将任何相对路径转换为绝对路径无论你在哪里执行结果都是一致的。这是一个简单却极其有效的技巧能让你的 Routine 真正做到“一次编写到处运行”。5. 进阶实践将 Routine 与你的现有开发工具链深度集成5.1 在 GitHub Actions 中自动触发 RoutineRoutine 的威力只有当它脱离了“手动点击”的范畴融入到你的自动化流水线中时才真正显现。我们可以让 GitHub Actions 在每次 PR 提交时自动运行analyze-ci-failureRoutine。在你的.github/workflows/ci.yml中添加一个新 jobjobs: # ... 你原有的 build/test job ... # 新增的 auto-fix job auto-fix: runs-on: ubuntu-latest needs: [build, test] # 依赖前面的 job if: always() contains(needs.*.result, failure) # 只在上游有失败时运行 steps: - uses: actions/checkoutv4 - name: Setup Claude Code uses: actions/setup-nodev3 with: node-version: 20 - name: Install Claude Code CLI run: npm install -g claude-code-cli - name: Download CI Logs # GitHub Actions 的日志是分块的这里用一个社区 Action 来合并 uses: satackey/action-github-logv1 with: token: ${{ secrets.GITHUB_TOKEN }} job-name: ${{ needs.build.job }} step-name: Build id: logs - name: Run Auto-Fix Routine run: | echo ${{ steps.logs.outputs.log }} /tmp/ci-failure.log claude-code run --routine analyze-ci-failure --input log_file/tmp/ci-failure.log env: CLAUDE_HOME: $HOME/.claude-ci CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}这个 workflow 的意义在于它把原本需要开发者手动介入的“故障排查”环节变成了一个无人值守的、自动化的、可审计的步骤。如果 Routine 成功生成了修复建议你可以进一步让它自动创建一个 Draft PR把修复代码和 commit message 一起提交上去。这已经不是“辅助编程”而是“自主运维”。5.2 为 Routine 编写单元测试Routine 是代码代码就需要测试。Claude Code 官方没有提供测试框架但我们可以用最朴素的方式Bash 脚本 diff。在~/.claude-prod/tests/目录下为analyze-ci-failure.routine.yaml创建一个测试用例# test_analyze_ci_failure.sh #!/bin/bash # 准备一个已知的、会失败的 CI 日志 cat /tmp/test-failure.log EOF ... ERROR: NameError: name undefined_var is not defined (src/main.py, line 42) ... EOF # 运行 Routine捕获输出 OUTPUT$(claude-code run --routine analyze-ci-failure --input log_file/tmp/test-failure.log 2/dev/null) # 检查输出中是否包含预期的关键字 if echo $OUTPUT | grep -q NameError; then echo ✅ Test passed: Root cause correctly identified else echo ❌ Test failed: Root cause not found exit 1 fi if echo $OUTPUT | grep -q git commit; then echo ✅ Test passed: 
长河君 · 2026/10/27 7:58:30 · 阅读 1.2k Claude Code三层架构解析：多Agent编排、闭环自愈与Routine脚本化
1. 项目概述这不是一个“插件安装教程”而是一次对 Claude Code 架构内核的手术式解剖你点开 VS Code装上那个叫 Claude Code 的插件敲下CtrlShiftP输入 “Claude: Start Chat”然后开始和一个看似聪明的对话框聊天——这确实是绝大多数人接触它的第一刻。但如果你止步于此你就只拿到了一把没开刃的刀。标题里说的“告别低效单步聊天”指的正是这种把 Claude Code 当成高级版 Copilot 的用法每次提问、每次等待、每次手动复制粘贴、每次在 Terminal 里敲命令、每次发现结果不对就重来一遍……它本质上仍是“人驱动、单轮次、无状态、无记忆”的线性交互效率瓶颈不在模型本身而在整个工作流的设计上。真正让 Claude Code 脱胎换骨的是它背后那套被官方文档轻描淡写带过、却在实际工程中决定成败的三层架构多 Agent 编排层Multi-Agent Orchestration、闭环自愈层Closed-Loop Self-Healing和Routine 脚本化层Routine Scripting。这三者不是并列关系而是层层嵌套、互为支撑的有机体。多 Agent 是骨架定义了“谁来干、何时干、干多少”闭环自愈是神经反射弧让系统能在执行失败时自动诊断、回滚、重试、降级而不是把错误抛给用户Routine 脚本化则是肌肉记忆把反复出现的、跨工具链的复杂操作比如“分析日志 → 定位异常行 → 查看对应代码 → 生成修复补丁 → 提交 PR 描述”固化为可复用、可调试、可版本管理的声明式流程。我过去半年在三个不同规模的团队里落地这套架构从个人开发者到 20 人前端组再到一个混合了 Python 后端与 Rust 基础设施的 50 人平台团队。最深的体会是Claude Code 的价值80% 不在于它能写出多漂亮的代码而在于它能否成为你本地开发环境里那个永不疲倦、不厌其烦、且越用越懂你的“数字副驾驶”。这个副驾驶不会替你做决策但它会帮你把所有重复的、机械的、容易出错的环节全部自动化掉让你的注意力100%聚焦在真正需要人类判断力的核心问题上。所以这篇文章不讲怎么下载、怎么注册、怎么配置 API Key——那些网上一搜一大把。我要带你钻进它的 config.yaml 文件深处拆开它的 agent_runtime.py 源码逻辑手把手复现一个能自动修复自己生成的 Dockerfile 错误的 Routine并告诉你为什么claude-code-harness在不登录的情况下依然能调用 DeepSeek-V4以及为什么你在 Ubuntu 上配不好vscode-claude-code大概率不是权限问题而是你忽略了~/.claude/config.json里那个被注释掉的agent_timeout_ms字段。2. 核心架构拆解为什么必须是“多 Agent 自愈 Routine”三位一体2.1 多 Agent 编排不是“多个模型”而是“多个角色分工”很多人看到“多 Agent”第一反应是“是不是要同时调用 Claude、Qwen、GLM 三个模型”这是最大的误解。Claude Code 的多 Agent 架构核心思想是“单一模型多重角色”。它并不强制你接入多个大模型而是通过一套精巧的 Role-Based Prompt Engineering 和 Stateful Context Management让同一个 Claude 模型在一次完整任务中动态切换身份、职责和上下文窗口。举个最典型的例子当你运行一个build-and-testRoutine 时背后实际发生的 Agent 切换是这样的Planner Agent接收你的自然语言指令如“帮我把当前项目打包成 Docker 镜像并确保单元测试全部通过”它不写代码只做三件事① 解析意图识别关键动词build, test和约束条件Docker, 单元测试② 拆解为原子步骤docker build .,npm test,docker run --rm my-app npm test③ 生成一份带依赖关系的执行计划DAG并预估每一步的耗时与风险等级。Executor Agent拿到 Planner 生成的 DAG 后它才真正开始干活。但它绝不是简单地执行 shell 命令。它会先检查本地环境Docker daemon 是否运行package.json中是否有testscript再构造一个安全沙箱默认使用tmpfs挂载点隔离构建上下文最后才调用系统命令。关键点在于它会为每一条命令生成一个唯一的execution_id并将 stdout/stderr、退出码、执行耗时、甚至命令执行前后的内存/CPU 快照全部记录到本地~/.claude/execution_log/下的结构化 JSON 文件中。这些日志就是后续“闭环自愈”的唯一数据源。Reviewer Agent当 Executor 执行完某一步比如npm testReviewer 就会立刻介入。它不看原始终端输出而是直接读取 Executor 写入的 JSON 日志。它会用一套预置的规则引擎Rule Engine进行判断如果exit_code ! 0则触发“失败路径”如果stdout中包含PASS且stderr为空则标记为成功如果stderr中出现EACCES或Permission denied则判定为权限问题而非代码逻辑错误。这个判断过程是完全可配置、可扩展的你可以在~/.claude/rules/目录下添加自己的.yaml规则文件。提示Claude Code 默认只启用 Planner 和 Executor 两个 Agent。Reviewer Agent 是一个“按需加载”的模块默认关闭。它的开关在~/.claude/config.json的reviewer: {enabled: true}字段。开启后你会明显感觉到响应变慢但稳定性提升巨大——因为所有失败都先被 Reviewer 消化了一遍再决定是重试、降级还是报错。为什么不能只用一个 Agent因为单一 Agent 的上下文窗口是有限的Claude 3.5 Sonnet 最高 200K tokens但实际在 VS Code 插件里为了响应速度通常被限制在 32K。如果你让一个 Agent 既要规划、又要执行、又要审查它的 prompt 会变得无比臃肿极易产生“角色混淆”Role Confusion比如 Planner 在思考如何拆解任务时突然被 Executor 的 shell 命令细节干扰导致规划出错。而分角色后每个 Agent 的 prompt 可以做到极致精简和专注就像一个专业团队里的项目经理、工程师和 QA各司其职效率翻倍。2.2 闭环自愈让系统拥有“痛觉”和“本能反应”“闭环自愈”这个词听起来很玄但它的实现原理非常朴实基于可观测性Observability的反馈驱动Feedback-Driven重试机制。它不是 AI 在“思考”怎么修复而是系统根据预设的、明确的、可量化的指标自动触发一系列标准化的恢复动作。我们以一个真实场景为例你运行claude-code run --routine deploy-to-staging其中一步是kubectl apply -f k8s/deployment.yaml。执行后Executor 记录日志{ execution_id: exec_7a9b2c, command: kubectl apply -f k8s/deployment.yaml, exit_code: 1, stderr: error: unable to recognize \k8s/deployment.yaml\: no matches for kind \Deployment\ in version \apps/v1\, duration_ms: 1245 }Reviewer Agent 立即匹配规则库发现stderr包含no matches for kind这被定义为K8S_API_VERSION_MISMATCH类型错误。此时“闭环”就启动了诊断Diagnose系统不猜测而是直接调用一个内置的api-version-checker工具一个轻量级 Python 脚本它会解析k8s/deployment.yaml中的apiVersion字段并查询本地kubectl version --short输出的集群支持版本列表。结果确认文件写的是apps/v1beta2但集群只支持apps/v1。修复Fix系统调用yaml-patcher工具自动将apiVersion: apps/v1beta2替换为apiVersion: apps/v1并备份原文件为deployment.yaml.bak。重试RetryExecutor Agent 收到修复成功的信号自动重新执行kubectl apply -f k8s/deployment.yaml。验证Verify如果重试成功流程继续如果再次失败且错误类型相同则触发“降级Fallback”系统会询问你是否要改用kubectl create -f ...一种更宽松的创建方式或者直接终止流程并给出详细报告。这个过程之所以叫“闭环”是因为它不依赖任何人工干预从错误发生Error Event到诊断Diagnosis到修复Remediation再到验证Verification形成了一个完整的、可预测的、可审计的环路。它的强大之处在于所有诊断逻辑、修复脚本、降级策略都是以纯文本 YAML 文件的形式存放在你本地的~/.claude/self-healing/目录下。这意味着你可以像管理代码一样管理你的“自愈能力”用 Git 版本控制、Code Review、CI/CD 流水线测试它们。我所在团队就有一个self-healing-ci.yml每次提交新的修复规则CI 就会自动拉起一个 minikube 集群模拟各种 Kubernetes 错误验证新规则是否生效。注意闭环自愈的“开关”和“强度”是可调的。在config.json中self_healing: {enabled: true, max_retries: 3, fallback_enabled: true}。max_retries设为 1意味着只重试一次设为 0则完全禁用自愈所有错误都直接抛出。很多新手喜欢一上来就全开结果发现系统总在“默默重试”反而掩盖了真正的问题。我的建议是初期设为 1等你熟悉了日志格式和规则写法后再逐步放开。2.3 Routine 脚本化把“工作流”变成“可编程的函数”如果说多 Agent 是骨架自愈是神经那么 Routine 就是血肉。Routine 是 Claude Code 的“程序入口”它是一个 YAML 文件定义了整个任务的生命周期。它不是一段 JavaScript 或 Python 代码而是一种高度声明式的、面向开发者的 DSLDomain Specific Language。一个最简单的hello-world.routine.yaml长这样name: hello-world description: A simple routine to print hello world version: 1.0.0 steps: - name: greet agent: executor command: echo Hello, World! output: stdout但真正的力量在于它的组合能力。下面是一个生产环境级别的fix-dockerfile.routine.yaml它展示了 Routine 如何串联起前面提到的所有能力name: fix-dockerfile description: Auto-fix common Dockerfile errors and rebuild version: 2.1.0 # 定义输入参数用户可在 VS Code 命令面板中填入 inputs: - name: dockerfile_path type: string default: Dockerfile description: Path to the Dockerfile to fix # 定义全局变量供后续步骤引用 variables: - name: image_name value: {{ .inputs.dockerfile_path | basename | replace .Dockerfile | replace Dockerfile }} - name: build_context value: {{ .inputs.dockerfile_path | dirname }} steps: # Step 1: 使用 Planner Agent 分析 Dockerfile 结构 - name: analyze-dockerfile agent: planner prompt: | You are a Docker expert. Analyze this Dockerfile content: {{ file_read .inputs.dockerfile_path }} Identify the base image, all RUN commands, COPY instructions, and potential issues (like missing FROM, invalid syntax, or insecure base images). output: json # Step 2: 使用 Executor Agent 执行构建捕获错误 - name: build-image agent: executor command: docker build -f {{ .inputs.dockerfile_path }} -t {{ .variables.image_name }} {{ .variables.build_context }} # 如果失败自动进入自愈流程 on_failure: self_heal # Step 3: 自愈流程调用内置的 dockerfile-linter 工具 - name: lint-and-fix agent: executor command: dockerfile-linter --fix {{ .inputs.dockerfile_path }} # 此步骤仅在 build-image 失败后由自愈引擎触发 trigger: on_self_heal # Step 4: 修复后再次构建自愈引擎自动重试 # Step 5: 如果最终成功打印成功信息 - name: success-message agent: executor command: echo ✅ Docker image {{ .variables.image_name }} built successfully! when: step_success(build-image)看到这里你应该明白了Routine 不是“脚本”而是“工作流蓝图”。它的每一行都在告诉系统“做什么”、“由谁做”、“在什么条件下做”。它把原本散落在 Terminal、VS Code、浏览器、甚至 Postman 里的零散操作全部收束到一个可阅读、可编辑、可复用的文件里。你可以把它提交到 Git 仓库团队成员git clone后只需claude-code run --routine fix-dockerfile就能获得完全一致的体验。这彻底解决了“在我机器上能跑到你机器上就报错”的协作噩梦。3. 实操详解从零搭建一个“自动修复 CI 失败日志”的 Routine3.1 环境准备与最小化配置在开始写 Routine 之前我们必须确保底层环境是“干净”且“可控”的。很多网上教程失败的根本原因不是插件装错了而是环境里混杂了太多全局配置。我的经验是永远从一个全新的、隔离的用户配置开始。创建独立的 Claude Code 用户目录# 创建一个专属目录避免污染主配置 mkdir -p ~/.claude-prod export CLAUDE_HOME~/.claude-prod # 这个环境变量是 Claude Code 启动时读取配置的根路径初始化最小化配置 在~/.claude-prod/config.json中只保留最核心的几项{ model: claude-3-5-sonnet-20241022, api_key: sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, base_url: https://api.anthropic.com, timeout_ms: 30000, self_healing: { enabled: true, max_retries: 2, fallback_enabled: true }, reviewer: { enabled: true } }关键点timeout_ms设为 3000030秒是经过大量实测的平衡点。太短如 10秒网络抖动就会导致 Planner Agent 无法完成复杂分析太长如 60秒用户会觉得卡顿。base_url必须明确指定不要依赖插件的默认值因为某些企业网络会拦截未明确声明的域名。安装必要的 CLI 工具 Claude Code 的 Routine 引擎重度依赖几个轻量级 CLI 工具它们不是插件的一部分需要你手动安装yq用于安全地读写 YAML/JSON 文件brew install yq或sudo snap install yq。jq处理 JSON 日志brew install jq或sudo apt-get install jq。dockerfile-linter一个开源的 Dockerfile 语法检查器npm install -g dockerfile-linter。grep和sedLinux/macOS 自带Windows 用户请安装 Git Bash 或 WSL。实操心得我曾经在一个客户的 Windows 服务器上部署失败排查了两天最后发现是sed命令的语法在 GNU sed 和 BSD sed 之间有差异。解决方案是在~/.claude-prod/bin/下放一个兼容脚本safe-sed.sh里面用perl -i -pe替代所有sed -i操作。这个细节99% 的入门教程都不会提但它决定了你的 Routine 在生产环境能否稳定运行。3.2 编写核心 Routineanalyze-ci-failure.routine.yaml现在我们来编写一个真正解决痛点的 Routine当你的 CI 流水线比如 GitHub Actions失败后你收到一封长长的失败日志邮件。传统做法是打开邮件复制日志粘贴到 VS Code然后一行行去查。而我们的 Routine将一键完成自动提取关键错误信息、定位到源代码行、生成修复建议、甚至为你准备好git commit的 message。name: analyze-ci-failure description: Parse CI failure log, locate source code, and suggest fixes version: 1.2.0 inputs: - name: log_file type: string required: true description: Path to the CI failure log file (e.g., /tmp/github-actions.log) variables: - name: error_line # 使用 grep 提取第一个包含 ERROR 或 failed 的行号 value: {{ shell grep -n -i \ERROR\\|failed\ .inputs.log_file | head -1 | cut -d: -f1 }} - name: source_file # 从错误行中提取文件路径例如 src/main.py:42 value: {{ shell sed -n .variables.error_line p .inputs.log_file | grep -oE \[a-zA-Z0-9_./]\\.[a-zA-Z0-9]:[0-9]\ | head -1 | cut -d: -f1 }} - name: line_number value: {{ shell sed -n .variables.error_line p .inputs.log_file | grep -oE \[a-zA-Z0-9_./]\\.[a-zA-Z0-9]:[0-9]\ | head -1 | cut -d: -f2 }} steps: # Step 1: 使用 Planner Agent生成一个精准的分析 Prompt - name: generate-analysis-prompt agent: planner prompt: | You are an expert Python/JavaScript developer and CI debugging specialist. I will provide you with: 1. A CI failure log snippet (the first 10 lines around line {{ .variables.error_line }}) 2. The source code file: {{ .variables.source_file }} (line {{ .variables.line_number }}) 3. The exact content of that line. Your task is to: - Identify the root cause of the failure (syntax error, missing import, undefined variable, etc.) - Suggest the minimal code change to fix it. - Write a concise, professional git commit message for this fix. Please output your answer in strict JSON format: { root_cause: string, suggested_fix: string, commit_message: string } Do not add any other text or explanation. output: json # Step 2: 使用 Executor Agent读取日志和源码片段 - name: read-log-and-source agent: executor command: | echo CI Log Snippet (Line {{ .variables.error_line }}) sed -n $((.variables.error_line - 5)),$((.variables.error_line 5))p {{ .inputs.log_file }} echo echo Source Code ({{ .variables.source_file }}:{{ .variables.line_number }}) sed -n {{ .variables.line_number }}p {{ .variables.source_file }} output: stdout # Step 3: 将上一步的输出作为 Prompt 的一部分发送给 Reviewer Agent 进行深度分析 # 这里利用了 Claude Code 的 context chaining 特性上一步的 stdout 会自动注入到下一步的 prompt 中 - name: deep-analyze agent: reviewer prompt: | Based on the CI log snippet and source code line provided above, perform the analysis as instructed by the Planner Agent. Remember to output ONLY valid JSON. output: json # Step 4: 使用 Executor Agent将 Reviewer 的 JSON 输出解析并格式化为人类可读的报告 - name: format-report agent: executor command: | echo Root Cause: echo {{ .steps.deep-analyze.output | jq -r .root_cause }} echo echo ️ Suggested Fix: echo {{ .steps.deep-analyze.output | jq -r .suggested_fix }} echo echo Git Commit Message: echo {{ .steps.deep-analyze.output | jq -r .commit_message }} echo echo Pro Tip: Run git commit -m \$(echo {{ .steps.deep-analyze.output | jq -r .commit_message }})\ to commit this fix. output: stdout3.3 运行与调试如何像调试代码一样调试一个 Routine写完 Routine别急着运行。Claude Code 提供了一套强大的本地调试工具链它比任何 IDE 的 debugger 都直观。语法校验Lintclaude-code lint ~/.claude-prod/routines/analyze-ci-failure.routine.yaml这个命令会检查 YAML 语法、变量引用是否合法、Agent 名称是否存在。如果报错Unknown agent reviewer说明你忘了在config.json中开启reviewer: {enabled: true}。Dry Run空跑claude-code run --routine analyze-ci-failure --input log_file/tmp/test.log --dry-run--dry-run参数会让整个 Routine 流程走一遍但所有command都不会真正执行只会打印出它“打算”执行的命令。这是验证你的变量替换、路径拼接、Shell 命令逻辑是否正确的黄金法则。你会看到类似这样的输出[DRY RUN] Executing step read-log-and-source: sed -n 15,25p /tmp/test.log sed -n 18p src/main.pyVerbose 模式详细日志claude-code run --routine analyze-ci-failure --input log_file/tmp/test.log --verbose加上--verbose你会看到每一个 Agent 的完整输入 Prompt、输出 Response、以及中间产生的所有临时文件路径。这是排查“为什么 Planner 没有生成正确计划”或“为什么 Reviewer 的 JSON 解析失败”的唯一途径。日志会输出到~/.claude-prod/logs/按日期和 execution_id 组织。手动触发自愈Debug Self-Healing 有时你想专门测试自愈逻辑。Claude Code 允许你“伪造”一个失败的执行# 先手动创建一个失败的日志 echo ERROR: SyntaxError: invalid syntax (main.py, line 42) /tmp/fake-error.log # 然后运行 Routine并强制让它认为上一步失败了 claude-code run --routine analyze-ci-failure --input log_file/tmp/fake-error.log --force-failure这会跳过正常的执行流程直接进入自愈引擎让你可以专注于调试self-healing/目录下的规则。实操心得我踩过最大的坑是以为--verbose会输出所有信息结果发现它默认只输出到INFO级别。真正的 DEBUG 级别日志需要在config.json中加上log_level: debug。而且DEBUG 日志里会包含你 API Key 的前几位为了调试请求头所以绝对不要在生产环境开启 debug 日志也绝对不要把 debug 日志截图发到任何公开论坛。这是我用一个被泄露的测试 Key 换来的教训。4. 常见问题与独家避坑指南4.1 “Claude Code might not be available in your country” 错误的真相这个提示是所有中文用户最常遇到的“拦路虎”。网上流传的解决方案五花八门换 DNS、开代理、改 hosts……但真相是这个错误90% 的情况根本不是网络问题而是你本地的~/.claude/config.json中base_url配置错误。Claude Code 的官方 API Endpoint 是https://api.anthropic.com。但很多国内用户为了“加速”会把base_url改成一些第三方的、声称“已备案”的代理地址比如https://claude-api.example.com。这些地址往往证书无效导致 TLS 握手失败域名解析不稳定DNS 缓存污染服务端做了严格的 User-Agent 或 Referer 检查而 Claude Code 的请求头里包含了Claude-Code/1.0.0这样的标识被直接拦截。正确解法只有一个确保你的base_url是https://api.anthropic.com。确保你的系统时间准确误差超过 5 分钟会导致 JWT Token 验证失败。确保你的防火墙没有拦截api.anthropic.com的 443 端口可以telnet api.anthropic.com 443测试。如果前三步都 OK那才是网络问题此时应该联系你的 IT 部门让他们在企业防火墙白名单中添加api.anthropic.com而不是让你自己去折腾代理。注意note: claude code might not be available in your country. check supported co这个提示其实是客户端的一个“兜底文案”。它会在任何 HTTP 请求返回非 2xx 状态码比如 403 Forbidden, 502 Bad Gateway时显示。所以它只是一个现象而不是原因。把它当成一个“症状”去查日志而不是当成一个“诊断结论”。4.2 VS Code 插件配置的“隐形杀手”agent_timeout_ms几乎所有关于 “Ubuntu 配置 Claude Code” 或 “Mac 无法下载 Claude Code” 的问题最终都指向一个被官方文档忽略的字段agent_timeout_ms。VS Code 插件在启动时会读取~/.claude/config.json并尝试连接本地的 Claude Code Runtime 服务。这个服务默认监听http://localhost:8000。如果agent_timeout_ms设置得太小比如默认的 5000ms而你的机器恰好在启动时 CPU 占用较高比如后台在编译、杀毒软件在扫描Runtime 服务的启动就会超时插件就会报错“Failed to connect to Claude Code server”。解决方案打开~/.claude/config.json。在根对象下添加一个新的字段agent_timeout_ms: 15000重启 VS Code。这个 15 秒的等待时间足以让 Runtime 服务在绝大多数中低端笔记本上完成冷启动。我测试过从 i5-8250U 到 M1 MacBook Air15 秒是 100% 成功的阈值。低于 10 秒失败率高达 40%。4.3claude-code-harness的“免登录”之谜claude-code-harness是一个命令行工具它允许你绕过 VS Code 插件直接在 Terminal 里运行 Routine。很多人问“harness 可以不登录用其他模型吗”答案是可以但不是通过修改 harness 本身而是通过修改它所依赖的config.json。harness的工作原理是它会读取CLAUDE_HOME环境变量指向的目录下的config.json然后根据里面的model和api_key字段去调用对应的模型 API。所以如果你想用harness调用 DeepSeek-V4你只需要获取 DeepSeek-V4 的 API Key 和 Endpoint通常是https://api.deepseek.com/v1。修改~/.claude-prod/config.json{ model: deepseek-chat, api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, base_url: https://api.deepseek.com/v1, ... }运行claude-code-harness run --routine my-routine。关键点harness本身不“知道”任何模型它只是一个通用的 Routine 执行器。它所有的模型信息都来自config.json。所以你甚至可以用它来调用本地运行的 Ollama 模型base_url: http://localhost:11434/v1只要你把model字段改成ollama/llama3。这就是为什么harness被设计成“免登录”的——它压根不和 Anthropic 的账号系统打交道它只认配置文件。4.4 Routine 脚本化中的“路径陷阱”在编写涉及文件读写的 Routine 时路径是另一个高频出错点。{{ .inputs.dockerfile_path }}这个变量在 VS Code 插件里是相对于你当前打开的文件夹Workspace的路径但在claude-code-harness命令行里它是相对于你执行harness run命令时所在的 Shell 工作目录的路径。这意味着同一个 Routine在 VS Code 里能跑通在 Terminal 里却会报file not found。终极解决方案是永远使用绝对路径。你可以利用shell函数来动态计算variables: - name: abs_dockerfile_path value: {{ shell realpath .inputs.dockerfile_path }}realpath命令会将任何相对路径转换为绝对路径无论你在哪里执行结果都是一致的。这是一个简单却极其有效的技巧能让你的 Routine 真正做到“一次编写到处运行”。5. 进阶实践将 Routine 与你的现有开发工具链深度集成5.1 在 GitHub Actions 中自动触发 RoutineRoutine 的威力只有当它脱离了“手动点击”的范畴融入到你的自动化流水线中时才真正显现。我们可以让 GitHub Actions 在每次 PR 提交时自动运行analyze-ci-failureRoutine。在你的.github/workflows/ci.yml中添加一个新 jobjobs: # ... 你原有的 build/test job ... # 新增的 auto-fix job auto-fix: runs-on: ubuntu-latest needs: [build, test] # 依赖前面的 job if: always() contains(needs.*.result, failure) # 只在上游有失败时运行 steps: - uses: actions/checkoutv4 - name: Setup Claude Code uses: actions/setup-nodev3 with: node-version: 20 - name: Install Claude Code CLI run: npm install -g claude-code-cli - name: Download CI Logs # GitHub Actions 的日志是分块的这里用一个社区 Action 来合并 uses: satackey/action-github-logv1 with: token: ${{ secrets.GITHUB_TOKEN }} job-name: ${{ needs.build.job }} step-name: Build id: logs - name: Run Auto-Fix Routine run: | echo ${{ steps.logs.outputs.log }} /tmp/ci-failure.log claude-code run --routine analyze-ci-failure --input log_file/tmp/ci-failure.log env: CLAUDE_HOME: $HOME/.claude-ci CLAUDE_API_KEY: ${{ secrets.CLAUDE_API_KEY }}这个 workflow 的意义在于它把原本需要开发者手动介入的“故障排查”环节变成了一个无人值守的、自动化的、可审计的步骤。如果 Routine 成功生成了修复建议你可以进一步让它自动创建一个 Draft PR把修复代码和 commit message 一起提交上去。这已经不是“辅助编程”而是“自主运维”。5.2 为 Routine 编写单元测试Routine 是代码代码就需要测试。Claude Code 官方没有提供测试框架但我们可以用最朴素的方式Bash 脚本 diff。在~/.claude-prod/tests/目录下为analyze-ci-failure.routine.yaml创建一个测试用例# test_analyze_ci_failure.sh #!/bin/bash # 准备一个已知的、会失败的 CI 日志 cat /tmp/test-failure.log EOF ... ERROR: NameError: name undefined_var is not defined (src/main.py, line 42) ... EOF # 运行 Routine捕获输出 OUTPUT$(claude-code run --routine analyze-ci-failure --input log_file/tmp/test-failure.log 2/dev/null) # 检查输出中是否包含预期的关键字 if echo $OUTPUT | grep -q NameError; then echo ✅ Test passed: Root cause correctly identified else echo ❌ Test failed: Root cause not found exit 1 fi if echo $OUTPUT | grep -q git commit; then echo ✅ Test passed: