网关脚本设计Skill gateway-script-design

---

名称: 网关脚本设计 描述: 设计网关脚本作为智能体编码的入口点。用于创建代理的CLI入口点、设计基于子进程的代理调用或构建智能体工作流的脚本接口。 允许工具: Read, Grep, Glob

网关脚本设计技能

指导创建网关脚本 - 智能体编码的入口点。

何时使用

• 创建新的代理CLI入口点
• 构建程序化代理调用
• 设计组合工作流
• 设置自动化脚本

核心概念

“这个脚本是进入智能体编码的网关。它与任何其他类型的代码都不同 - 它是在调用一个代理。”

网关脚本将你从对话移动到自动化。

三种网关模式

模式1: 直接提示

执行临时提示：

# adw_prompt.py
@click.command()
@click.argument("prompt")
@click.option("--model", default="opus")
def main(prompt: str, model: str):
    request = AgentPromptRequest(
        prompt=prompt,
        model=model,
        agent_name="oneoff"
    )
    response = prompt_claude_code(request)

使用案例: 快速一次性任务、测试、探索

模式2: 斜杠命令包装器

程序化执行斜杠命令：

# adw_slash_command.py
@click.command()
@click.argument("command")
@click.argument("args", nargs=-1)
def main(command: str, args: tuple):
    request = AgentTemplateRequest(
        slash_command=f"/{command}",
        args=list(args)
    )
    response = execute_template(request)

使用案例: 计划命令、触发器、外部集成

模式3: 组合工作流

链式多个代理：

# adw_chore_implement.py
def main(description: str):
    # 阶段1: 计划
    plan_response = execute_template("/chore", description)
    plan_path = extract_plan_path(plan_response)

    # 阶段2: 实施
    impl_response = execute_template("/implement", plan_path)
    return impl_response

使用案例: 多步骤自动化、完整工作流

设计清单

1. CLI接口

import click

@click.command()
@click.argument("input", required=True)
@click.option("--model", default="opus", help="使用的模型")
@click.option("--verbose", is_flag=True, help="详细输出")
def main(input: str, model: str, verbose: bool):
    ...

2. 唯一标识

def generate_short_id() -> str:
    return uuid.uuid4().hex[:8]

adw_id = generate_short_id()  # 例如: "a1b2c3d4"

3. 输出组织

output_dir = f"agents/{adw_id}/{agent_name}"
os.makedirs(output_dir, exist_ok=True)

output_file = f"{output_dir}/cc_raw_output.jsonl"

4. 安全环境

def get_safe_env() -> dict:
    return {
        "ANTHROPIC_API_KEY": os.getenv("ANTHROPIC_API_KEY"),
        "PATH": os.getenv("PATH"),
        # 仅必需变量
    }

5. 错误处理

try:
    response = prompt_claude_code(request)
except TimeoutError:
    log_error("代理超时")
    sys.exit(1)
except ExecutionError as e:
    log_error(f"执行失败: {e}")
    sys.exit(1)

6. 丰富输出

from rich.console import Console
from rich.panel import Panel

console = Console()

console.print(Panel(
    response.output,
    title=f"[bold green]{agent_name}[/]",
    border_style="green"
))

请求/响应模型

class AgentPromptRequest(BaseModel):
    prompt: str
    adw_id: str
    model: str = "opus"
    agent_name: str = "oneoff"
    output_file: Optional[str] = None

class AgentPromptResponse(BaseModel):
    output: str
    success: bool
    error: Optional[str] = None
    output_file: str

输出文件结构

每个网关产生：

agents/{adw_id}/{agent_name}/
├── cc_raw_output.jsonl     # 流式消息
├── cc_raw_output.json      # 解析后的数组
├── cc_final_object.json    # 最后消息
└── custom_summary.json     # 元数据

关键记忆参考

• @gateway-script-patterns.md - 模式示例
• @agentic-layer-structure.md - 脚本所在位置
• @programmable-claude-patterns.md - CLI调用

输出格式

## 网关脚本设计

**脚本名称:** adw_{purpose}.py
**模式:** [直接 | 包装器 | 组合]

### CLI接口
- 参数: {required args}
- 选项: --model, --verbose

### 代理配置
- 名称: {agent_name}
- 模型: opus (默认)
- 输出: agents/{adw_id}/{agent_name}/

### 执行流程
1. 解析参数
2. 生成ADW ID
3. 创建输出目录
4. 构建请求
5. 执行代理
6. 处理响应
7. 显示结果

### 错误处理
- 超时: 记录并退出1
- 执行错误: 记录原因并退出1
- 成功: 显示结果面板

### 生成文件
- cc_raw_output.jsonl
- cc_raw_output.json
- cc_final_object.json
- custom_summary.json

反模式

• 将完整环境传递给子进程
• 不生成唯一ID（碰撞风险）
• 无错误处理（静默失败）
• 内联输出而非文件（不可审计）
• 无CLI接口（难以使用）

版本历史

• v1.0.0 (2025-12-26): 初始发布

---

最后更新

日期: 2025-12-26 模型: claude-opus-4-5-20251101