Agent Skill 的 Script 架构设计指南：平衡认知与执行

Shadow：这个指南可以直接作为创建skill时的prompt给curosr或者claude code使用。合理安排哪些适合放到script，哪些适合交给Agent。

Agent Skill Script

架构设计指南

本指南面向 Skill 架构师与 Agent 开发者，聚焦"何时用 Script"与"如何设计 Tool-Like 模块"

1. 核心理念：认知层与执行层的解耦

在 Agent Skill 架构中，Prompt 负责认知（理解意图、规划路径、生成创意），Script 负责执行（确定性计算、安全交互、环境操作）。

1.1 核心判断标准：何时需要 Script？

2. Script 架构设计原则（Tool-Like 思维）

优秀的 Skill Script 应像一个标准的 API 工具，遵循以下六大原则：

2.1 黑盒封装

• 隐藏实现细节：内部逻辑、密钥、第三方依赖对 Agent 透明
• 暴露清晰接口：仅定义输入参数（类型、范围、必填项）与输出结构
• 最小权限暴露：只返回 Agent 后续流程所需的最小数据集合

2.2 无状态性

• 每次调用独立执行，不依赖全局变量或历史调用状态
• 如需状态管理（如计数、缓存），通过外部存储（数据库/Redis）显式传递
• 便于并发执行、重试机制与水平扩展

2.3 强校验

• 入口校验：对 Agent 传入的参数进行类型、范围、业务规则校验
• 失败快返：校验不通过时立即返回标准错误，避免进入核心逻辑
• 防御式编程：假设 Agent 可能传递异常参数，提前拦截

2.4 结构化输出

• 始终返回标准 JSON 或对象结构，包含： status、 data、 error 等字段
• 避免返回纯文本，便于 Agent 解析与后续决策
• 输出字段命名清晰、语义明确，减少 LLM 二次理解成本

2.5 异常隔离

• Script 内部捕获所有异常，不向 Agent 抛出原始错误栈
• 将技术异常转换为业务友好的错误码与提示语
• 记录详细日志供开发者排查，但对外仅暴露必要信息

2.6 可观测性

• 关键执行节点埋点：输入、输出、耗时、错误类型
• 支持日志分级（DEBUG/INFO/ERROR），便于生产环境调试
• 与 Agent 的追踪体系打通，实现端到端问题定位

3. 角色场景实战

3.1 品牌设计师场景： BrandColorExtractor（品牌色提取器）

业务需求：用户上传 Logo 图片，Agent 需提取主色调并生成配色建议。

分工逻辑：

• Script 职责：

1. 接收图片文件二进制流，校验文件大小与格式
2. 使用图像算法（如 K-Means 聚类）计算出现频率最高的 N 个颜色
3. 将 RGB 值转换为 HEX 格式，便于前端与 CSS 使用
4. 返回标准结构：主色、配色列表、处理状态

• Prompt 职责：

1. 接收 Script 返回的 HEX 颜色代码
2. 结合品牌知识库，分析色彩心理学含义
3. 生成符合品牌调性的文案建议与使用场景

数据流：

用户上传图片 
→ Agent 调用 Script 
→ Script 返回颜色数据 
→ Agent 将颜色+
Prompt 送入 LLM 
→LLM 生成品牌建议 
→ 返回用户

关键设计点：

• 图片处理逻辑封装在 Script，避免 LLM"看图猜色"产生幻觉
• 颜色转换在 Script 层完成，确保 HEX 格式 100% 准确
• Script 仅返回颜色数据，不生成文案，保持职责单一

3.2 管理咨询师场景： SecureMeetingScheduler（安全会议调度器）

业务需求：协助客户安排会议，需访问企业内部日历系统，且不能泄露认证信息。

分工逻辑：

• Script 职责：

1. 从安全配置中心加载 API 凭证（不经过 Agent 或 LLM）
2. 调用日历 API 查询指定时间段的空闲状态
3. 执行预订操作，处理冲突检测与重试逻辑
4. 返回脱敏后的会议信息（时间、链接、状态），隐藏内部 ID 与 Token

• Prompt 职责：

1. 与客户沟通时间偏好、参会人、议程等柔性信息
2. 根据 Script 返回的空闲时段，生成确认话术
3. 处理用户变更需求，协调多方时间

数据流：

用户表达 scheduling 需求 
→ Agent 提取时间参数 
→ 调用 Script 查询/预订
→ Script 返回可用时段 
→ Agent 生成确认话术
→ 用户确认后再次调用 Script 执行预订

关键设计点：

• API Key 仅在 Script 内部环境变量中读取，Prompt 层完全不可见
• Script 返回的会议链接为脱敏后的展示链接，非原始 API 响应
• 冲突处理逻辑在 Script 层实现，避免 LLM 反复尝试无效时间

3.3 数据分析师场景： FinancialRatioCalculator（财务比率计算器）

业务需求：上传财报 CSV，计算关键财务指标，并生成趋势分析。

分工逻辑：

• Script 职责：

1. 解析 CSV 文件，校验表头与数据完整性
2. 执行精确的数学公式计算（如流动比率、ROI、毛利率）
3. 处理边界情况：除零错误、缺失值填充、异常值过滤
4. 返回结构化指标数据与可选的图表数据源

• Prompt 职责：

1. 接收 Script 返回的指标数值
2. 结合行业基准与历史数据，解读指标含义
3. 生成风险提示、投资建议等创造性内容

数据流：

用户上传 CSV 
→ Agent 调用 Script 计算指标 
→ Script 返回{
"current_ratio": 1.5, "roi": 0.23} 
→ Agent 将数值+行业知识库送入
 LLM 
→ LLM 生成分析报告

关键设计点：

• 所有数学计算在 Script 层完成，避免 LLM 进行多位数运算产生误差
• Script 返回的指标名称与业务术语一致，减少 LLM 理解歧义
• 边界情况（如除零）在 Script 层处理，返回"N/A"而非报错中断流程

3.4 在线教师场景： AutoQuizGrader（自动作业批改器）

业务需求：批改客观题作业，统计分数，并生成个性化学习建议。

分工逻辑：

• Script 职责：

1. 接收学生答案与标准答案键值对
2. 执行字符串比对（忽略大小写、空格等干扰）
3. 计算得分、标识错题 ID、判断是否通过阈值
4. 返回结构化结果：分数、错题列表、通过状态

• Prompt 职责：

1. 接收 Script 返回的批改结果
2. 针对错题 ID，从知识库检索对应知识点讲解
3. 生成鼓励性评语与个性化学习路径建议

数据流：

学生提交答案 
→ Agent 调用 Script 批改 
→ Script 返回 { score:
 80, wrong_ids: [3,5], pass: true} 
→ Agent 
根据错题 ID 检索知识点 
→ LLM 生成讲解+鼓励话术

关键设计点：

• 批改逻辑（比对规则、计分方式）封装在 Script，确保公平一致
• Script 仅返回"哪些题错了"，不生成讲解内容，保持职责边界
• 通过状态（pass/fail）作为布尔值返回，便于 Agent 快速决策后续流程

4. 通用 Script 执行流程模板

为确保架构一致性，建议所有 Skill Script 遵循以下执行流程：

4.1 初始化阶段

• 加载安全配置（API Key、数据库连接等）
• 初始化日志系统与监控埋点
• 校验运行环境依赖（如第三方库版本）

4.2 输入校验阶段

• 检查必填参数是否存在
• 校验参数类型、取值范围、业务规则
• 校验失败时立即返回标准错误响应，终止执行

4.3 前置处理阶段

• 数据脱敏：移除或掩码敏感信息（如手机号、邮箱）
• 缓存检查：查询 Redis/DB，命中则直接返回缓存结果
• 数据预处理：格式转换、编码统一、噪声过滤

4.4 核心逻辑阶段

• 执行业务主流程（计算、查询、调用外部服务等）
• 所有外部调用设置超时与重试策略
• 捕获并记录异常，但不中断整体流程（除非致命错误）

4.5 后置处理阶段

• 结果格式化：转换为 Agent 易解析的结构
• 敏感信息二次过滤：确保输出不包含内部标识
• 指标上报：记录耗时、成功率等运维指标

4.6 标准响应阶段

• 返回包含 status、 data、 error 的标准 JSON 结构
• status 字段明确标识 success/warning/error
• data 字段仅包含业务必要信息，避免冗余

5. 安全与运维关键事项

5.1 密钥与凭证管理

• 禁止：将 API Key、数据库密码等写入 Prompt 或传给 LLM
• 必须：通过环境变量在 Script 启动时加载
• 建议：为不同环境（dev/staging/prod）配置独立凭证，避免交叉污染

5.2 超时与熔断机制

• 为每个外部调用设置合理超时（如 10-30 秒）
• 实现熔断逻辑：连续失败 N 次后暂停调用，避免雪崩
• 超时或熔断时返回友好提示，引导 Agent 降级处理

5.3 日志与审计

• 记录关键执行节点：输入摘要、输出摘要、耗时、错误码
• 日志中自动抹除用户隐私数据（PII），符合 GDPR 等合规要求
• 支持按 Skill ID、用户 ID、时间范围进行日志检索

5.4 版本兼容与灰度

• Script 接口变更时，保持旧版本字段兼容至少 1 个大版本
• 支持通过配置开关灰度发布新逻辑，便于回滚
• Agent 配置层适配 Script 版本，避免硬编码依赖

5.5 测试与验收

• 单元测试：覆盖正常路径、边界条件、异常输入
• 集成测试：模拟 Agent 调用，验证端到端数据流
• 安全测试：校验密钥隔离、注入防护、权限控制

6. 常见反模式与避坑指南

7. 总结：构建"可靠执行层"的三大方法

1. 职责边界清晰 Script 不做创意生成，Prompt 不做精确计算。让每一层专注自己最擅长的事情。
2. 接口契约稳定 Script 的输入输出是 Agent 与执行层的"合同"。变更需谨慎，兼容要优先。
3. 失败可预期 任何外部依赖都可能失败。Script 的设计目标不是"永不出错"，而是"出错时可被 Agent 理解与处理"。

最终目标：通过 Tool-Like 的 Script 架构，让 Agent 从"会聊天的 AI"进化为"能可靠执行任务的数字化员工"。