跳到主要内容

handler 型 · HTTP

什么时候读：技能只是把模型填的参数转发给一个 HTTP 接口，不需要本地逻辑。

形态​

exec.config 指向一个 TOML 文件，平台按其描述发请求。

<skill_name>/
├── SKILL.md
├── schema.json      # 模型看到的入参
└── request.toml     # 请求描述

frontmatter 里 exec.config: request.toml。

约束​

  • 输入 = 请求体；没有 runtime_context，拿不到 actor、org、db。
  • 所有需要「谁在调」的判断不能用这种形态。
  • 凭证走 requires.env，在 TOML 里用 $VAR 引用，见 references/config-secrets.md。
  • 返回是接口原样响应，平台再按 references/output-envelope.md 处理（远程 URL 物化、产物登记同样生效）。
  • 响应若不含 success/ok，平台不判失败；要让模型能区分失败，接口本身需要返回 ok: false + error，或者改用进程内 Python 包一层。

什么时候不该用​

需要重试、需要参数校验、需要把响应整形再给模型、需要鉴权分支——任何一条命中都改进程内 Python。 HTTP 型省的是几十行代码，代价是失败时模型拿不到可自纠的 error。