【AI面试临阵磨枪-92】Skill 开发规范：命名、文档、测试、日志、监控、告警？

一、面试题目

请讲解 AI Agent Skill 开发规范 ，包含：命名规范、文档规范、测试规范、日志规范、监控规范、告警规范、安全规范。

二、知识储备

1. 命名规范（清晰、统一、可维护）

• Skill 命名 ：业务_场景_动作，小写下划线，见名知意

• • 例：aftersale_refund_order、hotel_change_date

• Skill ID：唯一、固定、不重复
• 入参/出参：小写下划线，禁止拼音、缩写

• • 例：user_id、order_id、tenant_id

• 版本 ：语义化 v1.0.0，大改升主版本，小改升次版本

2. 文档规范（开箱即用、可协作）

• 必须包含：

1. 1. 功能说明：做什么业务
   2. 入参列表：字段、类型、是否必填、示例
   3. 出参格式：成功/失败结构
   4. 依赖工具：依赖哪些 Tool
   5. 业务规则：可执行条件、禁忌、风险点
   6. 异常说明：常见错误码与文案

• 支持 Markdown + 可视化流程图

3. 测试规范（上线前必过）

• 单元测试：参数正常/异常/空值/边界
• 集成测试：Skill 调用、上下文透传、依赖校验
• 异常测试：超时、重试、熔断、格式错误、幻觉
• 幂等测试：重复调用不重复执行
• 权限测试：越权访问必须拦截
• 回归测试：版本更新不影响旧流程

4. 日志规范（可追溯、可排查）

• 必须打印：

• • skill_id、request_id、user_id、tenant_id
  • 入参、出参、执行状态
  • 工具调用、异常信息、耗时

• 日志级别：INFO 正常、ERROR 异常
• 禁止打印：敏感信息（密码、手机号、密钥）

5. 监控规范（全链路可观测）

• 核心监控指标：

1. 1. 调用量 QPS
   2. 成功率 / 异常率
   3. 执行耗时 P95/P99
   4. 超时次数、重试次数
   5. 熔断次数
   6. 幻觉拦截次数

• 按 skill_id + tenant_id 维度监控

6. 告警规范（快速响应）

• 触发告警：

• • 异常率 > 5%
  • P95 延迟 > 3s
  • 连续超时、熔断开启
  • 幻觉拦截突增

• 告警方式：企业微信、电话、短信
• 分级：一般、严重、紧急

7. 安全规范（企业级强制）

• 必做：

• • 参数校验
  • 租户+用户权限校验
  • 幂等防重
  • 超时控制
  • 熔断降级

• 禁止：

• • 越权操作
  • 敏感信息日志打印
  • 无限制重试
  • 高危操作无审核

三、代码示例（规范模板）

# 命名规范
def aftersale_refund_order(context):
    # 日志规范
    logger.info(
        skill_id="aftersale_refund_order",
        request_id=context.request_id,
        params=context.params
    )
    # 参数校验
    if not context.params.get("order_id"):
        raise MissingParamError("order_id is required")
    # 权限校验
    auth.check(context.user_id, context.tenant_id)
    # 执行业务
    result = tools.refund(context.params["order_id"])
    # 监控埋点
    monitor.incr("skill_success", tags={"skill_id": "aftersale_refund_order"})
    return result

四、破局之道（面试升华）

Skill 开发规范的核心目标是：可维护、可观测、可追溯、安全稳定 。

通过统一命名、完善文档、全量测试、标准日志、全方位监控、分级告警、强制安全，让 Skill 从"能用"变成"企业级可上线"，是 Agent 规模化落地的基础保障。

30 秒口述精简版

Skill 开发规范包括：见名知意的命名、完整的文档、全场景测试、全链路日志、多维度监控、分级告警、安全强制校验，目标是让技能稳定、安全、可维护、可观测。