技能介绍

它解决什么问题

把一个写好的 Python skill 脚本暴露成 HTTP 接口，常见做法是丢给 agent runtime，用一段自由文本 message 让 LLM 去理解、再取数执行。这条路的代价很具体：冷启动动辄 30 秒以上，每次执行结果都有 LLM 漂移，还得先部署一个 Gateway。想做「脚本里 curl 一下就能拿到结构化数据」这种事，就显得又重又脆。

它怎么工作

核心思路是绕开 LLM 和 agent 链路，直接编译成微服务。flash.py create 时扫描 skill 入口（推荐在 frontmatter 写 flash.entry，否则按 scripts/main.py、main.py 等 7 个候选路径兜底），用启发式规则从 argparse 参数推入参 JSON Schema；这一步可选调用 LLM 辅助提取，没配就退化成空 schema + additionalProperties: true，生成后手动改 params.json 即可。

运行期完全是 subprocess.run() 直调 Python 入口：

入参映射：{"foo_bar": 10} → --foo-bar 10，true 变 flag style，数组展开成重复 flag，嵌套对象序列化成 JSON 字符串。字段名走 [a-z][a-z0-9_]* 白名单，argv 用 list 不拼 shell。
响应 envelope：stdout 是合法 JSON 就走 data 结构化字段，否则走 output 原文，脚本零改动。
同步 / 异步：/run 默认 60s 超时、512KB 截断；/run/async 立即返回 job_id，完整 stdout 不截断，内存（1h TTL）+ JSONL 持久化，并发上限 20。
错误分层：HTTP 状态码只表达框架问题（400 校验失败、408 超时、429 限流），脚本业务失败用 envelope.success=false + stderr 表达，仍返回 200。

生成的 server.py 完全自包含，可 scp 到任意机器裸跑，不依赖任何 agent runtime。异步任务、TLS、API Key 鉴权、CORS、K8s 持久化目录都有对应配置项。

适用边界

入口必须是 Python 文件，v2.0 已移除 shell 支持——想包 .sh 得自己加一层 Python launcher。另外它不解决「需要 LLM 理解自然语言后取数」的场景，也不处理交互式 TUI 输出、长连接 / SSE / WebSocket。v2.0 与 v1.x 不兼容，老项目要先 flash.py remove 再重建。