本地服务 API

API 接入示例

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

最小闭环

启动服务。
调 GET /health。
调 GET /actions。
调一个普通 /actions/run。
再调一个多步 /action-flows/run。

curl 示例

最小单动作指令联调：

curl -X POST "http://127.0.0.1:18081/actions/run" ^
  -H "Content-Type: application/json; charset=utf-8" ^
  --data "{\"action\":\"read_env_var\",\"args\":{\"name\":\"PATH\"}}"

最小 JSON 动作流联调：

curl -X POST "http://127.0.0.1:18081/action-flows/run" ^
  -H "Content-Type: application/json; charset=utf-8" ^
  --data "{\"script_name\":\"demo_multi_steps\",\"steps\":[{\"action\":\"log\",\"args\":{\"content\":\"开始执行\"}},{\"action\":\"wait_seconds\",\"args\":{\"seconds\":1}},{\"action\":\"log\",\"args\":{\"content\":\"执行完成\"}}]}"

Python 示例

import requests

base = "http://127.0.0.1:18081"
resp = requests.post(
    f"{base}/actions/run",
    json={
        "action": "read_env_var",
        "args": {"name": "PATH"},
    },
    timeout=30,
)
print(resp.json())

如果是多步 JSON 动作流，直接提交 steps 数组：

import requests

base = "http://127.0.0.1:18081"
resp = requests.post(
    f"{base}/action-flows/run",
    json={
        "script_name": "demo_multi_steps",
        "steps": [
            {"action": "log", "args": {"content": "开始执行"}},
            {"action": "wait_seconds", "args": {"seconds": 1}},
            {"action": "log", "args": {"content": "执行完成"}},
        ],
    },
    timeout=30,
)
print(resp.json())

动作流目录示例

推荐顺序：先查动作流列表，再查动作流详情，最后通过 /action-flows/run 的 script_path 模式执行目录动作流。

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

curl.exe "http://127.0.0.1:18081/action-flows/info?script_path=%E7%A4%BA%E4%BE%8B/%E8%AF%BB%E5%8F%96%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F.txt"

curl.exe -X POST "http://127.0.0.1:18081/action-flows/run" ^
  -H "Content-Type: application/json; charset=utf-8" ^
  --data "{\"script_path\":\"示例/读取环境变量.txt\",\"input_args\":{\"目标变量\":\"PATH\"}}"

动作流文件头推荐写法：

# 动作流说明: 读取环境变量并保存结果
# 适用场景: AI 先查现有动作流后直接复用
# 输入参数: 目标变量
# 简言简语 v1
读取环境变量 变量名="{目标变量}" 默认值="fallback" 保存为=环境值

剪映流程示例

剪映复杂流程建议一次请求走 /action-flows/run。

curl -X POST "http://127.0.0.1:18081/action-flows/run" ^
  -H "Content-Type: application/json; charset=utf-8" ^
  --data @examples/local_service_jianying_完整修改流程_run_steps.json

这类流程第一步通常要显式读取草稿。
最后一步通常要显式保存草稿。
同一请求里要显式给出草稿定位信息，不要指望服务记住上一次的当前草稿。

batch-run 多步示例

普通多步请求可以直接这样写：

curl -X POST "http://127.0.0.1:18081/action-flows/run" ^
  -H "Content-Type: application/json; charset=utf-8" ^
  --data "{\"script_name\":\"demo_multi_steps\",\"steps\":[{\"action\":\"log\",\"args\":{\"content\":\"开始执行\"}},{\"action\":\"wait_seconds\",\"args\":{\"seconds\":1}},{\"action\":\"log\",\"args\":{\"content\":\"执行完成\"}}]}"

如果你是程序接入，通常直接构造一个 steps 数组再整体提交就行。