需严格遵循qoder脚本输入/输出契约：python脚本读json上下文、输出结构化结果；shell脚本用jq解析参数并调用cli；hook脚本在pre/post事件点触发，通过stderr返回错误。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望在 Qoder Agent 模式下通过脚本驱动自动化任务，但不确定如何组织结构、调用上下文或返回结果，则需严格遵循 Qoder 对脚本输入/输出契约的定义。以下是实现该目标的具体操作路径：
一、编写兼容 Agent 模式的 Python 脚本
Python 脚本是 Qoder Agent 模式中最灵活的脚本类型，可直接访问注入的 project_path、input、workspace 等上下文变量，并支持复杂逻辑判断与多步骤处理。脚本必须从标准输入读取 JSON 上下文，并向标准输出写入结构化响应。
1、在项目根目录下的 .qoder/scripts/ 目录中新建文件，例如 generate-api-spec.py。
2、首行添加解释器声明：#!/usr/bin/env python3，第二行导入 sys 和 json 模块。
3、使用 data = json.load(sys.stdin) 读取 Agent 注入的完整上下文对象。
4、提取关键字段，例如 data.get("input", {}).get("api_name") 或 data["project_path"]，用于后续逻辑分支。
5、构造结果字典，如 {"output": {"openapi_yaml": "paths: [...]"}}，确保键名符合下游 Skill 的预期。
6、以 print(json.dumps(result)) 输出最终结果，不可附加任何额外文本或空行。
二、编写轻量级 Shell 脚本对接 Agent 工具链
Shell 脚本适用于快速调用系统命令、校验环境就绪状态或触发已有 CLI 工具，其执行不经过 Python 解释器层，启动更快，但无法直接解析复杂 JSON 上下文，需借助 jq 工具提取字段。
1、在 .qoder/scripts/ 下创建 validate-env.sh 文件。
2、首行指定解释器：#!/bin/bash，并确认换行符为 LF（Unix 格式）。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
3、读取标准输入并用 jq 提取参数：INPUT=$(cat); API_NAME=$(echo "$INPUT" | jq -r '.input.api_name')。
4、执行条件检查，例如 if [ -z "$API_NAME" ]; then echo '{"error":"missing api_name"}' >&2; exit 1; fi。
5、调用外部工具生成中间产物：openapi-generator generate -i ./specs/$API_NAME.yaml -g python -o ./gen/$API_NAME-client。
6、输出结构化结果：echo '{"status":"success","client_dir":"./gen/'$API_NAME'-client"}'。
三、配置 Hook 脚本在 Agent 执行节点注入自定义逻辑
Hook 脚本不直接参与 Agent 的主任务流，而是在 PreToolUse、PostToolUse 等确定性事件点被触发，用于拦截危险操作、自动格式化或审计日志，其输入为事件上下文 JSON，输出为退出码与 stderr 错误信息。
1、在用户主目录下创建钩子脚本路径：mkdir -p ~/.qoderworkcn/hooks。
2、新建 enforce-java-version.sh，内容包含：#!/bin/bash; INPUT=$(cat); CMD=$(echo "$INPUT" | jq -r '.tool_input.command'); if echo "$CMD" | grep -q 'javac'; then JAVA_VER=$(java -version 2>&1 | head -n1 | cut -d' ' -f3 | tr -d '"'); [ "$(printf '%s\n' '17' '$JAVA_VER' | sort -V | head -n1)" != '17' ] && echo "Java 17 required, got $JAVA_VER" >&2 && exit 2; fi。
3、赋予可执行权限：chmod +x ~/.qoderworkcn/hooks/enforce-java-version.sh。
4、在 ~/.qoderworkcn/settings.json 中添加 Hook 配置段，匹配 PreToolUse 事件与 Bash 工具类型。
5、配置中指定 "command": "~/.qoderworkcn/hooks/enforce-java-version.sh"，并设置 "timeout": 30。
