Qoder自动化脚本生成教程：新手入门到实战指南

在 Qoder 的 Agent 模式下通过脚本驱动自动化任务，关键在于理解并遵循其定义的输入/输出契约。这套契约明确了脚本如何接收数据、处理逻辑并返回结构化结果，确保整个流程清晰可控。

本质上，契约规定了脚本与 Agent 的交互协议：从标准输入读取 JSON 格式的上下文，处理后将 JSON 结果输出到标准输出。下面，我们具体解析三种脚本类型的实现方法。

一、编写兼容 Agent 模式的 Python 脚本

Python 脚本在 Agent 模式下提供了强大的灵活性，能够直接访问 Agent 注入的完整上下文对象，例如 project_path、input 和 workspace 等变量。这使其成为处理复杂业务逻辑或多步骤任务的理想选择。

脚本必须严格遵守“从标准输入读 JSON，向标准输出写 JSON”的约定。具体实现步骤如下：

首先，在项目根目录的 .qoder/scripts/ 目录下创建脚本文件，例如 generate-api-spec.py。

文件头部需包含解释器声明 #!/usr/bin/env python3，并导入 sys 和 json 模块。

核心操作是使用 data = json.load(sys.stdin) 加载 Agent 传递的整个上下文。随后，你可以像操作字典一样提取所需字段，例如 data.get("input", {}).get("api_name") 或直接引用 data["project_path"]。

完成业务逻辑处理后，构建一个结果字典。建议字典的键名与下游 Skill 的预期保持一致，例如 {"output": {"openapi_yaml": "paths: [...]"}}。

最后，通过 print(json.dumps(result)) 将结果输出到标准输出。请注意，输出必须是纯净的 JSON 字符串，避免附加任何额外文本或空行，以防解析失败。

二、编写轻量级 Shell 脚本对接 Agent 工具链

对于需要快速调用系统命令、检查环境状态或触发现有 CLI 工具的任务，Shell 脚本是更轻量、启动更快的方案。虽然 Shell 本身不擅长解析复杂 JSON，但可以借助 jq 工具高效处理。

同样，在 .qoder/scripts/ 目录下创建脚本文件，如 validate-env.sh。首行指定 #!/bin/bash，并确保文件使用 LF 换行符。

脚本中，首先通过 INPUT=$(cat) 读取标准输入，然后使用 jq 提取参数：API_NAME=$(echo "$INPUT" | jq -r '.input.api_name')。

获取参数后，可执行条件检查。例如，验证必要参数是否存在：if [ -z "$API_NAME" ]; then echo '{"error":"missing api_name"}' >&2; exit 1; fi。将错误信息输出到标准错误（stderr）并返回非零退出码，符合 Unix 最佳实践。

随后，调用外部工具链执行任务，例如使用 OpenAPI Generator 生成客户端代码：openapi-generator generate -i ./specs/$API_NAME.yaml -g python -o ./gen/$API_NAME-client。

任务成功完成后，同样以 JSON 格式向标准输出报告结果：echo '{"status":"success","client_dir":"./gen/'$API_NAME'-client"}'。

三、配置 Hook 脚本在 Agent 执行节点注入自定义逻辑

Hook 脚本扮演着特殊角色，它不参与主任务流，而是在特定事件点（如工具执行前 PreToolUse 或执行后 PostToolUse）被触发。这使其非常适合用于危险操作拦截、代码自动格式化或审计日志记录。

Hook 脚本的输入同样是事件上下文的 JSON 数据，但它主要通过退出码和输出到 stderr 的信息与 Agent 交互。

配置过程如下：首先，在用户主目录下创建钩子脚本专用目录：mkdir -p ~/.qoderworkcn/hooks。

接着，新建一个钩子脚本，例如 enforce-ja va-version.sh。脚本逻辑可以是：读取输入，提取即将执行的命令；若命令涉及 ja vac，则检查当前 Ja va 版本；若版本低于 17，则向 stderr 输出错误信息并退出。

记得为脚本添加可执行权限：chmod +x ~/.qoderworkcn/hooks/enforce-ja va-version.sh。

最后，在全局设置文件 ~/.qoderworkcn/settings.json 中注册此钩子。添加一个配置段，指定监听的事件（如 PreToolUse）、工具类型（如 Bash），并提供脚本的绝对路径和超时设置。

完成配置后，每当 Agent 准备执行 Bash 工具前，都会先运行你的检查脚本，确保环境符合预设要求，从而实现有效的安全卡点控制。