本地服务 API

API 接口清单

对外 HTTP 接口，面向外部程序接入、调试和联调。

GET /health

只做一件事：确认服务活着。

curl.exe http://127.0.0.1:18081/health

成功时会返回 status=ok 和 service=fengshenbot-local。

GET /actions

先查动作摘要列表，再决定走哪个入口。

curl.exe http://127.0.0.1:18081/actions

重点看 description、risk_level、tags：先判断是不是目标动作。
重点看 allow_actions_run 和 allow_action_flows：判断当前能走哪个执行入口。
重点看 recommended_entry：判断当前更推荐走哪个入口。
支持 keyword、category、sub_category、tag、risk_level、recommended_entry、limit 查询参数。

GET /action-flows

先看当前动作流目录里有哪些现成动作流。

curl.exe http://127.0.0.1:18081/action-flows

当前动作流目录直接复用宠物服务 / 托盘服务菜单里“设置动作流目录...”保存的目录。
返回里重点看 script_path、description、input_parameters。

GET /actions/info

执行前先看单个动作的完整契约。

GET /actions/info?action_name=read_env_var

action_name 必填。
返回里会包含参数、服务层参数、返回结构、示例等完整信息。

GET /action-flows/info

执行前先看单个动作流的说明、头信息和正文预览。

GET /action-flows/info?script_path=示例/读取环境变量.txt

script_path 必填，传动作流目录下的相对路径。
返回里的 header 和 content_preview 适合给 AI 先做判断。

POST /actions/run

适合单个动作指令调用。

{
  "action": "read_env_var",
  "args": {
    "name": "PATH"
  },
  "input_context": {
    "调用方": "demo"
  }
}

action 必填。
args 可选，必须是对象。
input_context 可选，必须是对象。
不允许直接调用控制语句，如 if、loop、while、for_each、break、continue。

POST /action-flows/run

适合程序直接提交结构化动作流。

{
  "script_name": "demo_steps",
  "steps": [
    {
      "action": "read_env_var",
      "args": {
        "name": "PATH"
      },
      "save_as": "环境值"
    }
  ]
}

如果要一次执行多步，就继续往 steps 数组里追加多个步骤对象，按顺序执行：

{
  "script_name": "demo_multi_steps",
  "steps": [
    {
      "action": "log",
      "args": {
        "content": "开始执行"
      }
    },
    {
      "action": "wait_seconds",
      "args": {
        "seconds": 1
      }
    },
    {
      "action": "log",
      "args": {
        "content": "执行完成"
      }
    }
  ]
}

这种入口直接传 JSON 动作流，不需要先落成文件。已有动作流或 Python 脚本文件时，使用同一个入口的 script_path 模式：

{
  "script_path": "sub/a.jy",
  "input_args": {}
}

steps 和 script_path 二选一，不能同时提供。
script_path 必须是动作流根目录或当前脚本目录下的相对路径。
不支持用 /actions/run 执行文件，也不支持把 module_path 作为 Python 脚本参数。
复杂剪映流程优先一次请求完整提交，不要拆成很多个 /actions/run。