后端 API 参考Backend API reference

无请求参数。

{
  "plugins": [
    {
      "id": "builtin-history",
      "name": "历史",
      "icon": "history",
      "slot": "panel",
      "slotDef": { "type": "panel", "area": "panel" },
      "entry": "index.html",
      "configSchema": [],
      "config": {},
      "builtin": true,
      "backend": { "kind": "npm" },
      "root": "builtin",
      "origin": "builtin",
      "rootOk": true,
      "dependency": [{ "type": "skill", "id": "xxx" }]
    }
  ],
  "rail": { "stage": 0, "hidden": {}, "opacity": 1 },
  "panelContainer": {},
  "active": { "panel": "builtin-history" }
}

每条插件附：configSchema（插件自声明）与 config（webminConfig 中已存值，有效配置 = schema 默认值 ∪ config 覆盖）、builtin（是否位于内置根）、backend（是否自带后端，有 server/server.js 则为 { "kind": "npm" }，否则 null）；root（声明的期望位置）、origin（后端回填的实际所在根）、rootOk（两者是否一致）；dependency 归一化为 [{ "type", "id" }]（类型限定白名单：skill / plugin / mcp / agentloop / sensor / graph）；slot 归一化为字符串 id，完整语义见 slotDef。

顶层另返回 rail（最左图标栏状态：stage、hidden、opacity）、panelContainer（宿主中栏容器配置）、active（单例槽当前选中的插件 id）。

curl 'http://127.0.0.1:8000/api/webmin/manifest'

{ "status": "ok", "result": {} }

plugin_id 缺失或含非法字符返回 400；插件不存在返回 404 与 { "detail": "插件 <plugin_id> 不存在" }；插件进程执行异常（PluginProcessError）返回 502，detail 为异常信息。

curl -X POST 'http://127.0.0.1:8000/api/webmin/plugin-rpc/my-plugin/echo' \
  -H 'Content-Type: application/json' \
  -d '{"payload": {"msg": "hi"}, "timeout": 30}'

无请求参数。

{ "plugins": { "my-plugin": { "key": "value" } } }

返回 webminConfig 中的插件配置分节；缺失时返回 { "plugins": {} }。

curl 'http://127.0.0.1:8000/api/webmin/config'

{ "status": "ok" }

请求体非 JSON 对象时返回 400 与 { "detail": "请求体必须是 JSON 对象" }。

curl -X PUT 'http://127.0.0.1:8000/api/webmin/config' \
  -H 'Content-Type: application/json' \
  -d '{"rail": {"stage": 1, "opacity": 0.9, "hidden": {}}, "active": {"panel": "builtin-history"}}'

{ "status": "ok", "deleted": "my-plugin" }

plugin_id 缺失或含非法字符返回 400；位于内置根的插件返回 403 与 { "detail": "内置插件不可删除" }；用户/沙盒根下均不存在该插件返回 404 与 { "detail": "插件 <plugin_id> 不存在" }。

curl -X POST 'http://127.0.0.1:8000/api/webmin/plugin/my-plugin/delete'

{
  "status": "ok",
  "filename": "wallpaper_a1b2c3d4e5f6.png",
  "url": "/api/webmin/wallpaper/wallpaper_a1b2c3d4e5f6.png"
}

文件不存在返回 404 与 { "detail": "壁纸文件不存在" }；扩展名不在允许集合（png/jpg/jpeg/gif/webp/bmp/mp4/webm/mov）返回 400 与 { "detail": "不支持的壁纸格式: <ext>" }。

curl -X POST 'http://127.0.0.1:8000/api/webmin/wallpaper' \
  -H 'Content-Type: application/json' \
  -d '{"path": "C:/Users/me/Pictures/wall.png"}'

直接返回文件流（FileResponse）。文件名非法返回 400 与 { "detail": "非法的文件名" }；文件不存在返回 404 与 { "detail": "壁纸不存在" }。

curl -OJ 'http://127.0.0.1:8000/api/webmin/wallpaper/wallpaper_a1b2c3d4e5f6.png'

直接返回文件流（FileResponse），MIME 由文件扩展名推断。

未命中任何文件（含回退 entry 失败）返回 404 与 { "detail": "插件 <plugin_id> 资源不存在" }。路径穿越（越出插件目录）一律视为未命中。

curl 'http://127.0.0.1:8000/api/webmin/plugin/builtin-history/index.html'

{
  "path": "data",
  "entries": [
    { "name": "a.json", "isDir": false },
    { "name": "sub", "isDir": true }
  ]
}

以 . 开头的条目被跳过。目录不存在（越界或未定位到）返回 404 与 { "detail": "插件 <plugin_id> 目录不存在" }；列目录异常返回 500 与 { "detail": "读取目录失败: <err>" }。

curl 'http://127.0.0.1:8000/api/webmin/plugin-dir/my-plugin/data'

[
  {
    "id": "session_xxx",
    "alias": "New Session",
    "messages_count": 12,
    "updated_at": "2026-10-14T10:00:00"
  }
]

curl 'http://127.0.0.1:8000/api/sessions'

{ "id": "session_xxx", "alias": "New Session" }

curl -X POST 'http://127.0.0.1:8000/api/sessions/new' -H 'Content-Type: application/json' -d '{"alias":"我的会话"}'

返回消息对象数组（role / content 等字段）。当 branch_id 为 main 且为 Agent 当前活跃会话时，取内存最新历史；否则按 branch_id 从磁盘加载对应隔离子分支历史。

curl 'http://127.0.0.1:8000/api/sessions/session_xxx?branch_id=main'

{ "main": { "status": "active" } }

分支 id 为键、元数据（含 status）为值；会话不存在或读取异常时回退为 {"main": {"status": "active"}}。

curl 'http://127.0.0.1:8000/api/sessions/session_xxx/branches'

{
  "is_thinking": true,
  "state": "running",
  "compressing": false,
  "live_reasoning": "",
  "phase": "thinking"
}

phase 取值：thinking（模型推理中）/ processing（工具执行中）/ aborting（打断等待收尾）/ idle（空闲）。当查询的会话不是 Agent 当前挂载会话时，is_thinking 为 false、state 为 idle。

curl 'http://127.0.0.1:8000/api/sessions/session_xxx/status'

{ "status": "ok" }

失败时返回 500 与 { "detail": "<reason>" }。

curl -X PUT 'http://127.0.0.1:8000/api/sessions/session_xxx/rename' -H 'Content-Type: application/json' -d '{"alias":"新名字"}'

{ "status": "ok" }

curl -X POST 'http://127.0.0.1:8000/api/sessions/session_xxx/checkout'

{ "id": "session_xxx", "alias": "Branch Session" }

curl -X POST 'http://127.0.0.1:8000/api/sessions/session_xxx/branch' -H 'Content-Type: application/json' -d '{"alias":"试验分支"}'

{ "paradigm": "" }

curl 'http://127.0.0.1:8000/api/sessions/session_xxx/paradigm'

{ "ok": true, "paradigm": null, "paradigm_path": "..." }

paradigm 为切换后的目标名（为空时返回 null），paradigm_path 为对应 YAML 的落盘路径。

curl -X POST 'http://127.0.0.1:8000/api/sessions/session_xxx/paradigm' -H 'Content-Type: application/json' -d '{"paradigm":"MY_LOOP"}'

{ "status": "ok" }

curl -X DELETE 'http://127.0.0.1:8000/api/sessions/session_xxx'

{ "status": "ok" }

分支不存在或禁止删除时返回 400。

curl -X DELETE 'http://127.0.0.1:8000/api/sessions/session_xxx/branches/session_yyy'

{ "status": "processing", "message": "Message pushed to agent" }

curl -X POST 'http://127.0.0.1:8000/api/chat' -H 'Content-Type: application/json' -d '{"session_id":"session_xxx","message":"你好"}'

{
  "status": "processing",
  "processed_events": [
    { "type": "user", "content": "你好" }
  ]
}

processed_events 为做过超长输入缓冲替换（与 force_push_batch 保持一致）后的事件副本。

curl -X POST 'http://127.0.0.1:8000/api/chat/batch' -H 'Content-Type: application/json' -d '{"session_id":"session_xxx","events":[{"type":"user","content":"你好"}]}'

{ "status": "ok", "interrupted": true }

status 为 ok（成功打断）或 no_agent（无 Agent 实例）；interrupted 为布尔结果。异常时返回 500。

curl -X POST 'http://127.0.0.1:8000/api/chat/interrupt'

{ "status": "processing" }

异常时返回 500。

curl -X POST 'http://127.0.0.1:8000/api/chat/compress-memory'

{
  "window_token": 12345,
  "max_token": 500000,
  "consumed_main": 0,
  "consumed_sub": 0,
  "consumed_total": 0
}

window_token 为上下文窗口长度，max_token 为当前模型上限；consumed_* 为本会话累计消耗（含子代理）：活跃会话主干取内存实时值，子代理取落盘聚合值，非活跃会话整体取落盘聚合值。异常时回退为 window_token: 0、max_token: 1000000、其余为 0。

curl 'http://127.0.0.1:8000/api/agent/token?session_id=session_xxx'

无参数。

{
  "main": {
    "openai:deepseek-flash": {
      "api_keys": [""],
      "base_url": "https://api.deepseek.com",
      "max_token": 500000
    }
  },
  "task": {},
  "vision": {}
}

curl 'http://127.0.0.1:8000/api/config/model'

{ "status": "ok", "message": "Model config updated and reloaded successfully" }

保存失败返回 500：{ "detail": "Failed to save model config" }

curl -X PUT 'http://127.0.0.1:8000/api/config/model' \
  -H 'Content-Type: application/json' \
  -d '{"main":{"openai:deepseek-v4-flash":{"base_url":"https://api.deepseek.com","max_token":500000}}}'

无参数。

{
  "my_sensor": { "enabled": true }
}

curl 'http://127.0.0.1:8000/api/config/sensor'

{ "status": "ok", "message": "Sensor config updated successfully" }

保存失败返回 500：{ "detail": "Failed to save sensor config" }

curl -X PUT 'http://127.0.0.1:8000/api/config/sensor' \
  -H 'Content-Type: application/json' \
  -d '{"my_sensor":{"enabled":true}}'

无参数。

{ "status": "ok", "message": "Sensors reloaded successfully" }

失败返回 500：{ "detail": "热重启失败: <原因>" }

curl -X POST 'http://127.0.0.1:8000/api/config/sensor/reload'

无参数。

{
  "default_permission": "readonly",
  "permissions": {
    "blocked": [".git", "src", "node_modules", "miniconda3", ".env"],
    "readonly": [],
    "writable": []
  }
}

curl 'http://127.0.0.1:8000/api/config/file'

{ "status": "ok", "message": "File config updated successfully" }

保存失败返回 500：{ "detail": "Failed to save file config" }

curl -X PUT 'http://127.0.0.1:8000/api/config/file' \
  -H 'Content-Type: application/json' \
  -d '{"default_permission":"readonly","permissions":{"blocked":[".git"],"readonly":[],"writable":[]}}'

无参数。

{ "mcpServers": {} }

curl 'http://127.0.0.1:8000/api/config/mcp'

{ "status": "ok", "message": "MCP config updated successfully" }

保存失败返回 500：{ "detail": "Failed to save MCP config" }

curl -X PUT 'http://127.0.0.1:8000/api/config/mcp' \
  -H 'Content-Type: application/json' \
  -d '{"mcpServers":{}}'

无参数。

{ "status": "ok", "message": "MCP 已重载到内存：检索树已热更新，共 12 个工具" }

失败返回 500：{ "detail": "MCP 重载失败: <原因>" }

curl -X POST 'http://127.0.0.1:8000/api/config/mcp/reload'

无参数。

{ "GitHub": "https://github.com" }

curl 'http://127.0.0.1:8000/api/config/app'

{ "status": "ok", "message": "App config updated successfully" }

保存失败返回 500：{ "detail": "Failed to save app config" }

curl -X PUT 'http://127.0.0.1:8000/api/config/app' \
  -H 'Content-Type: application/json' \
  -d '{"GitHub":"https://github.com"}'

无参数。

{
  "relay_path": "C:\\Users\\<user>\\.purrcat\\bin\\acp_relay.py",
  "relay_deployed": true,
  "relay_source_found": true,
  "relay_matches_source": true,
  "port": 8000,
  "actual_port": 8001,
  "port_mismatch": true,
  "uv_found": true
}

curl 'http://127.0.0.1:8000/api/config/acp'

{ "status": "ok", "message": "ACP settings updated" }

保存失败返回 500：{ "detail": "保存 acp_port 失败" }

curl -X PUT 'http://127.0.0.1:8000/api/config/acp' \
  -H 'Content-Type: application/json' \
  -d '{"port":8000}'

无参数。

返回当前 ACP 状态并附加 status：

{
  "relay_path": "C:\\Users\\<user>\\.purrcat\\bin\\acp_relay.py",
  "relay_deployed": true,
  "relay_source_found": true,
  "relay_matches_source": true,
  "port": 8000,
  "uv_found": true,
  "status": "ok"
}

失败返回 500：{ "detail": "部署失败：内置源缺失或写入错误" }

curl -X POST 'http://127.0.0.1:8000/api/config/acp/redeploy'

无参数。

{ "status": "ok" }

失败返回 500：{ "detail": "token 重置失败: <原因>" }

curl -X POST 'http://127.0.0.1:8000/api/config/acp/reset-token'

无参数。

{
  "items": {
    "uv": { "ready": true, "detail": "uv x.y.z (C:\\...\\uv.exe)" },
    "node": { "ready": false, "detail": "未检测到 node 命令" },
    "sandbox": { "ready": true, "detail": "..." },
    "embedding": { "ready": false, "detail": "嵌入模型未下载（约 120MB）" }
  },
  "tasks": {
    "uv": { "state": "idle", "log": [], "finished_at": null }
  }
}

curl 'http://127.0.0.1:8000/api/config/deploy'

{ "status": "ok", "message": "已开始部署 uv" }

未知项或已在部署中返回 409：{ "detail": "<reason>" }

curl -X POST 'http://127.0.0.1:8000/api/config/deploy/uv'

无参数。

{ "sandbox_registry": "" }

curl 'http://127.0.0.1:8000/api/config/sandbox-registry'

{ "status": "ok" }

保存失败返回 500：{ "detail": "保存 sandbox_registry 失败" }

curl -X PUT 'http://127.0.0.1:8000/api/config/sandbox-registry' \
  -H 'Content-Type: application/json' \
  -d '{"sandbox_registry":"ghcr.m.daocloud.io"}'

{ "content": "## 性格\n\n你是一个内向的程序员……" }

curl 'http://127.0.0.1:8000/api/config/markdown/SOUL'

{ "status": "ok", "message": "SOUL.md saved successfully" }

写入失败返回 500：{ "detail": "Failed to save SOUL.md" }

curl -X PUT 'http://127.0.0.1:8000/api/config/markdown/SOUL' \
  -H 'Content-Type: application/json' \
  -d '{"content":"## 性格\n\n你是一个内向的程序员……"}'

无参数。

{ "skills": [], "workshops": [] }

curl 'http://127.0.0.1:8000/api/config/info'

无参数。

未配置时：

{ "configured": false, "data_root": "" }

已配置时：

{ "configured": true, "data_root": "D:\\purrcat_data" }

curl 'http://127.0.0.1:8000/api/config/setup-status'

{ "status": "ok", "data_root": "D:\\purrcat_data", "message": "数据盘设置成功，重启后生效" }

已配置过返回 409：{ "detail": "数据盘已配置，变更请使用配置中心的数据根目录入口" }

curl -X POST 'http://127.0.0.1:8000/api/config/setup-data-root' \
  -H 'Content-Type: application/json' \
  -d '{"data_root":"D:\\purrcat_data"}'

{
  "status": "ok",
  "data_root": "E:\\purrcat_data",
  "moved": ["embedding"],
  "message": "数据已就绪（agent_vm 已在新位置全新初始化，沙盒容器已销毁，重启后自动重建）"
}

目标位置已存在同名子目录返回 409；搬迁或落盘失败返回 500。

curl -X POST 'http://127.0.0.1:8000/api/config/change-data-root' \
  -H 'Content-Type: application/json' \
  -d '{"data_root":"E:\\purrcat_data"}'

无参数。

{ "jobs": [] }

curl 'http://127.0.0.1:8000/api/config/cron'

{ "status": "ok", "message": "Cron config updated successfully" }

保存失败返回 500：{ "detail": "Failed to save cron config" }

curl -X PUT 'http://127.0.0.1:8000/api/config/cron' \
  -H 'Content-Type: application/json' \
  -d '{"jobs":[]}'

无参数。

{
  "PURRCAT_DIR": "C:\\Users\\<user>\\.purrcat",
  "DATA_ROOT": "D:\\purrcat_data",
  "BASE_DIR": "D:\\cat-in-cup",
  "settings_path": "C:\\Users\\<user>\\.purrcat\\settings.json",
  "cron_path": "C:\\Users\\<user>\\.purrcat\\core\\cron.json"
}

curl 'http://127.0.0.1:8000/api/config/meta'

无参数。

[
  { "name": "示例技能", "description": "技能描述", "dir_name": "example-skill" }
]

curl 'http://127.0.0.1:8000/api/tools/skills'

{ "status": "success", "message": "Skill 'xxx' 下载成功并已热加载入内存！" }

curl -X POST 'http://127.0.0.1:8000/api/tools/skills/install' -H 'Content-Type: application/json' -d '{"url":"https://github.com/owner/repo/tree/main/path/to/skill"}'

{
  "status": "success",
  "installed": ["skill-a", "skill-b"],
  "failed": [{ "path": "path/to/skill", "error": "仓库下载失败: ..." }],
  "message": "批量安装完成：成功 2 个，失败 1 个"
}

status 在有失败项时为 partial，全部成功时为 success。

curl -X POST 'http://127.0.0.1:8000/api/tools/skills/install-batch' -H 'Content-Type: application/json' -d '{"urls":["https://github.com/owner/repo/tree/main/skills/a","https://github.com/owner/repo/tree/main/skills/b"]}'

{ "status": "success", "message": "Skill 'xxx' 已删除" }

未找到该 Skill 时返回 404。

curl -X POST 'http://127.0.0.1:8000/api/tools/skills/uninstall' -H 'Content-Type: application/json' -d '{"name":"example-skill"}'

无参数。

{ "status": "success", "message": "Skill 已刷新，共加载 12 个技能" }

刷新进行中时：

{ "status": "refreshing", "message": "Skill 正在刷新中，请稍候…" }

curl -X POST 'http://127.0.0.1:8000/api/tools/skills/refresh'

无参数。

以服务器名为键、工具数组为值：

{
  "server_name": [
    { "name": "tool_name", "description": "工具描述" }
  ]
}

curl 'http://127.0.0.1:8000/api/tools/mcp'

无参数。

["server-a", "server-b"]

curl 'http://127.0.0.1:8000/api/tools/mcp/list'

{ "status": "success", "message": "MCP 配置已合并并热加载成功！当前系统共载入 30 个工具。" }

JSON 非法或缺少 mcpServers 顶层键时返回 400。

curl -X POST 'http://127.0.0.1:8000/api/tools/mcp/install' -H 'Content-Type: application/json' -d '{"config_json":"{\"mcpServers\":{\"demo\":{\"command\":\"npx\",\"args\":[\"-y\",\"demo-mcp\"]}}}","repo":""}'

{ "status": "success", "message": "MCP Server 'demo' 已删除" }

未配置该 Server 时返回 404。

curl -X POST 'http://127.0.0.1:8000/api/tools/mcp/uninstall' -H 'Content-Type: application/json' -d '{"name":"demo"}'

无参数。

{ "status": "success", "message": "MCP 缓存已刷新，共加载 30 个工具" }

刷新进行中时：

{ "status": "refreshing", "message": "MCP 正在刷新中，请稍候…" }

curl -X POST 'http://127.0.0.1:8000/api/tools/mcp/refresh'

无参数。

返回闹钟列表（结构由 list_crons() 决定），形如：

[
  { "id": "xxxx", "title": "喝水提醒", "trigger_time": "2026-10-14 09:00", "repeat_rule": "none", "task_hook": "Agent" }
]

curl 'http://127.0.0.1:8000/api/tools/cron'

{ "status": "success", "data": { "id": "xxxx" } }

添加失败时返回 400。

curl -X POST 'http://127.0.0.1:8000/api/tools/cron' -H 'Content-Type: application/json' -d '{"title":"喝水提醒","trigger_time":"2026-10-14 09:00","repeat_rule":"none","task_hook":"Agent","task_inputs":{}}'

{ "status": "success", "data": { "id": "xxxx" } }

删除失败时返回 400。

curl -X DELETE 'http://127.0.0.1:8000/api/tools/cron/喝水提醒'

GET 无参数。POST：

GET：

{ "interval": 300, "active": true, "goal": "# 目标\n..." }

POST：

{ "status": "success", "data": { "interval": 300, "active": true } }

active=true 且 goal 为空时返回 400。

curl 'http://127.0.0.1:8000/api/tools/heartbeat'
curl -X POST 'http://127.0.0.1:8000/api/tools/heartbeat' -H 'Content-Type: application/json' -d '{"interval":300,"active":true,"goal":"# 目标\n持续优化项目"}'

无参数。

{ "version": "1.0.0", "repository": "PurrPod/sensors", "sensors": [{ "name": "feishu-bot", "description": "..." }] }

拉取失败时返回 502。

curl 'http://127.0.0.1:8000/api/tools/market/sensors'

无参数。

[
  { "name": "feishu-bot", "enabled": true, "has_code": true }
]

curl 'http://127.0.0.1:8000/api/tools/market/sensors/installed'

成功：

{ "status": "success", "message": "Sensor 'feishu-bot' 配置已合并，代码已下载到 ...。", "code_downloaded": true }

配置写入成功但代码下载失败时返回 partial，code_downloaded 为 false。缺少 name 时返回 400。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/sensors/install' -H 'Content-Type: application/json' -d '{"sensor":{"name":"feishu-bot","description":"..."}}'

{ "status": "success", "message": "Sensor 'feishu-bot' 已删除" }

未配置该 Sensor 时返回 404。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/sensors/uninstall' -H 'Content-Type: application/json' -d '{"name":"feishu-bot"}'

无参数。

{ "version": "1.0.0", "repository": "PurrPod/graphs", "graphs": [{ "name": "demo", "files": ["graph.json"] }] }

拉取失败时返回 502。

curl 'http://127.0.0.1:8000/api/tools/market/graphs'

无参数。

["demo", "writer"]

curl 'http://127.0.0.1:8000/api/tools/market/graphs/installed'

{ "status": "success", "message": "Graph 'demo' 已安装到 ...（3 个文件）。已从市场自动安装 MCP 依赖: xxx" }

注册表缺失该 Graph 时返回 404，拉取/下载失败时返回 502。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/graphs/install' -H 'Content-Type: application/json' -d '{"name":"demo"}'

{ "status": "success", "message": "Graph 'demo' 已删除" }

未安装该 Graph 时返回 404。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/graphs/uninstall' -H 'Content-Type: application/json' -d '{"name":"demo"}'

无参数。

{ "version": "1.0.0", "repository": "PurrPod/ui-plugins", "plugins": [{ "name": "hello", "root": "user" }] }

拉取失败时返回 502。

curl 'http://127.0.0.1:8000/api/tools/market/ui-plugins'

无参数。

["hello", "dashboard"]

curl 'http://127.0.0.1:8000/api/tools/market/ui-plugins/installed'

{ "status": "success", "message": "UI 插件 'hello' 已安装到 ...（4 个文件）。..." }

注册表缺失该插件时返回 404；root 为 builtin（内置插件）时返回 400。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/ui-plugins/install' -H 'Content-Type: application/json' -d '{"name":"hello"}'

{ "status": "success", "message": "UI 插件 'hello' 已删除" }

未安装该插件时返回 404；名称含 /、\ 或 .. 时返回 400。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/ui-plugins/uninstall' -H 'Content-Type: application/json' -d '{"name":"hello"}'

无参数。

{ "version": "1.0.0", "repository": "PurrPod/agentloops", "agentloops": [{ "name": "demo", "files": ["demo.yaml"] }] }

拉取失败时返回 502。

curl 'http://127.0.0.1:8000/api/tools/market/agentloops'

无参数。

["demo", "writer"]

curl 'http://127.0.0.1:8000/api/tools/market/agentloops/installed'

{ "status": "success", "message": "AgentLoop 'demo' 已安装到 ...（1 个文件）" }

注册表缺失该 AgentLoop 时返回 404；下载或 YAML 校验失败时返回 502。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/agentloops/install' -H 'Content-Type: application/json' -d '{"name":"demo"}'

{ "status": "success", "message": "AgentLoop 'demo' 已删除" }

未安装该 AgentLoop 时返回 404；名称为 PARADIGM（大小写不敏感）或含 /、\、.. 时返回 400。

curl -X POST 'http://127.0.0.1:8000/api/tools/market/agentloops/uninstall' -H 'Content-Type: application/json' -d '{"name":"demo"}'

[
  { "name": "src", "isDir": true, "path": "/agent_vm/src" },
  { "name": "main.py", "isDir": false, "path": "/agent_vm/main.py" }
]

按“目录优先、名称不区分大小写”排序。异常时返回 400。

curl 'http://127.0.0.1:8000/api/filesystem/list?path=/agent_vm'

{ "content": "文件文本内容" }

异常时返回 400。

curl 'http://127.0.0.1:8000/api/filesystem/read?path=/agent_vm/README.md'

{ "size": 2048 }

异常时返回 400。

curl 'http://127.0.0.1:8000/api/filesystem/stat?path=/agent_vm/main.py'

{ "status": "success" }

异常时返回 400。

curl -X POST 'http://127.0.0.1:8000/api/filesystem/write' -H 'Content-Type: application/json' -d '{"path":"/agent_vm/notes.txt","content":"hello"}'

[
  {
    "id": "safe_path@backup_id",
    "path": "/sandbox/path",
    "backup_id": "backup_id",
    "time": ""
  }
]

id 为完整文件名（safe_path@backup_id），path 由安全路径还原为 / 前缀的沙盒路径；time 当前为空串，需前端自行转换。目录不存在时返回空数组。

curl 'http://127.0.0.1:8000/api/filesystem/history_list'

{ "status": "success", "valid_ids": ["backup_id_1", "backup_id_2"] }

读取异常时返回 { "status": "error", "valid_ids": [] }。

curl 'http://127.0.0.1:8000/api/filesystem/backups'

{ "status": "success", "message": "<回滚结果描述>" }

message 为回滚操作的文字结果。失败时返回 500。

curl -X POST 'http://127.0.0.1:8000/api/filesystem/undo' -H 'Content-Type: application/json' -d '{"path":"/agent_vm/notes.txt","backup_id":"backup_id_1"}'

{ "status": "success" }

若当前沙盒解析不到任何备份（文件可能已被外部迁移或销毁），会直接清掉该改动记录并返回：

{ "status": "success", "purged_stale": true }

失败时返回 500。

curl -X POST 'http://127.0.0.1:8000/api/filesystem/ack' -H 'Content-Type: application/json' -d '{"path":"/agent_vm/notes.txt","backup_id":"backup_id_1"}'

{ "status": "success", "total": 3, "purged_stale": 0 }

total 为处理的变更总数，purged_stale 为其中被直接清掉记录的陈旧变更数。若存在处理失败项则返回：

{ "status": "partial", "failed": 1, "total": 3 }

失败时返回 500。

curl -X POST 'http://127.0.0.1:8000/api/filesystem/ack_all'

{ "status": "success", "diffs": [] }

异常时返回 { "status": "error", "diffs": [], "message": "<错误详情>" }。

curl 'http://127.0.0.1:8000/api/filesystem/diffs'

{ "real_path": "D:\\cat-in-cup\\agent_vm\\index.html" }

目标不是文件时返回 404；其它异常返回 400。

curl 'http://127.0.0.1:8000/api/filesystem/resolve?path=/agent_vm/index.html'

返回 FileResponse 文件流，Content-Type 由 mimetypes 依据文件名推断（无法推断时为 application/octet-stream）。

curl 'http://127.0.0.1:8000/api/filesystem/preview?path=/agent_vm/index.html' -o preview.html

[
  { "workplace_id": "wp-001", "name": "my-skill", "status": "processing" }
]

返回沙盒数组；无有效本体（未知名称）的沙盒会被跳过。

curl 'http://127.0.0.1:8000/api/evolve/list?type=skill'

{
  "status": "success",
  "workplace_id": "wp-001",
  "message": "初始化完成"
}

分配失败（无 workplace_id）返回 400；内部异常返回 500。

当 trace=true 且 type=skill 且有 session_id 时，会把该会话的累计 Token 快照写入 skill_workplace/<workplace_id>/trace_meta.json，随后盲测报告据此对比展示「该技能让后台盲测任务少花了多少 token」。快照失败不影响建厂。

curl -X POST 'http://127.0.0.1:8000/api/evolve/init' \
  -H 'Content-Type: application/json' \
  -d '{"type": "skill", "name": "my-skill", "is_upgrade": false, "goal": "补全文档", "trace": true, "session_id": "main"}'

{ "content": "", "attachments": ["SKILL.md", "main.py"] }

filename 为空时返回 attachments（排除 __pycache__ / .venv / node_modules / iteration-* / trigger-* 目录及 .pyc / .png / .jpg 文件，已排序）；否则返回 { "content": "<文件文本>" }。工作区或文件不存在返回 404。

curl 'http://127.0.0.1:8000/api/evolve/file?workplace_id=wp-001&name=my-skill'
curl 'http://127.0.0.1:8000/api/evolve/file?workplace_id=wp-001&name=my-skill&filename=SKILL.md'

{ "status": "success", "message": "保存成功" }

写入前会自动创建父目录；异常返回 500。

curl -X PUT 'http://127.0.0.1:8000/api/evolve/file?workplace_id=wp-001&name=my-skill&filename=SKILL.md' \
  -H 'Content-Type: application/json' \
  -d '{"content": "# My Skill"}'

{ "status": "success", "message": "盲测已启动" }

启动异常返回 500。

curl -X POST 'http://127.0.0.1:8000/api/evolve/test/run' \
  -H 'Content-Type: application/json' \
  -d '{"type": "skill", "workplace_id": "wp-001", "name": "my-skill", "session_id": "main"}'

[1, 2, 3]

扫描 iteration-<n> 目录并返回升序轮次编号数组。

curl 'http://127.0.0.1:8000/api/evolve/test/iterations?workplace_id=wp-001&type=skill'

{ "report_html": "<!DOCTYPE html>\n<html lang=\"zh-CN\">...</html>" }

报告统一以自包含的瑞士国际主义风格 HTML 页面输出，各类型同取该轮次目录下的 report.html（skill 为 Trigger + 盲测合并的单一页面）。页面零外部依赖，前端以 iframe 直接承载，故接口不再返回文件清单或 Markdown。无报告时返回 { "report_html": "" }。

curl 'http://127.0.0.1:8000/api/evolve/test/report?workplace_id=wp-001&name=my-skill&type=skill'

{ "benchmark": { "criteria": [], "coverage": {} } }

读取 iteration-<n>/benchmark.json；轮次不存在、文件缺失或解析失败均返回 { "benchmark": null }。

curl 'http://127.0.0.1:8000/api/evolve/test/benchmark?workplace_id=wp-001&type=sensor'

{ "diff_content": "diff --git ..." }

对比正式库与沙盒：skill 对比 SKILL_DIR/{name}，mcp 对比 ./mcps/{name}，sensor 对比 {name}.py，agentloop 对比 PARADIGMS_DIR/{name}.yaml，graph 对比 GRAPHS_DIR/{name}。全新模块返回文字说明，无变化返回提示语。异常返回 500。

curl 'http://127.0.0.1:8000/api/evolve/diff?workplace_id=wp-001&name=my-skill&type=skill'

{ "status": "success", "message": "合并完成" }

拒绝时（is_approved = false）将拒绝意见写入 REJECT_REASON.md 并返回：

{ "status": "rejected", "message": "已将拒绝意见抛回沙盒，Agent可读取并继续调整。" }

异常返回 500。

curl -X POST 'http://127.0.0.1:8000/api/evolve/handle' \
  -H 'Content-Type: application/json' \
  -d '{"type": "skill", "workplace_id": "wp-001", "name": "my-skill", "is_approved": true}'

{ "status": "success", "message": "回滚成功！'my-skill' 已恢复至上一个版本，并生成了 Rollback Commit。" }

回滚失败或无 Git 历史时返回 400；异常返回 500。

curl -X POST 'http://127.0.0.1:8000/api/evolve/rollback' \
  -H 'Content-Type: application/json' \
  -d '{"type": "skill", "name": "my-skill"}'

{ "status": "success", "message": "沙盒已彻底清理" }

递归删除 workplace 目录（只读文件会先改权限）。沙盒不存在返回 404；异常返回 500。

curl -X DELETE 'http://127.0.0.1:8000/api/evolve/workplace/wp-001?type=skill'

无请求参数。

{
  "os": "Windows",
  "installed": { "docker": true },
  "recommend": "docker",
  "recommend_reason": "检测到已安装 Docker。"
}

curl 'http://127.0.0.1:8000/api/system/env/detect'

无请求参数。

{
  "is_ready": true,
  "engine": "docker",
  "engine_version": "Docker version 27.x.x, build xxxxx",
  "error": null
}

未就绪时 is_ready 为 false，error 携带原因（如 daemon 未启动）。

curl 'http://127.0.0.1:8000/api/system/env-status'

无请求参数。

{ "ready": true, "engine": "docker", "has_docker": true }

未检测到 docker 时 ready 为 false、engine 为 null。

curl 'http://127.0.0.1:8000/api/system/env/status'

{ "exists": true, "image_name": "my_agent_env:latest", "error": null }

镜像不存在时 exists 为 false；docker 缺失或连接失败时 error 携带原因。

curl 'http://127.0.0.1:8000/api/system/image-status?image_name=my_agent_env:latest'

{ "status": "started", "message": "已开始后台拉取镜像 my_agent_env:latest，请稍候..." }

docker 缺失或连接失败返回 500。

curl -X POST 'http://127.0.0.1:8000/api/system/image/pull' \
  -H 'Content-Type: application/json' \
  -d '{"image_name": "my_agent_env:latest"}'

{ "status": "started", "message": "开始安装 docker 环境...", "progress": 0 }

已在安装中时返回 {"status": "installing", "message": "正在安装中，请稍候...", "progress": <当前进度>}。

curl -X POST 'http://127.0.0.1:8000/api/system/env/install' \
  -H 'Content-Type: application/json' \
  -d '{"engine": "docker"}'

无请求参数。

{ "status": "completed", "message": "安装进行中...", "progress": 100 }

status 取值 idle / installing / completed / failed；失败时 message 携带错误原因。

curl 'http://127.0.0.1:8000/api/system/env/install/status'

无请求参数。

{
  "engine": "docker",
  "version": "Docker version 27.x.x, build xxxxx",
  "available_engines": { "docker": true },
  "selected_engine": "docker"
}

获取失败返回 500。

curl 'http://127.0.0.1:8000/api/system/container-engine'

{
  "success": true,
  "saved_path": ".purrcat/agent_vm/.buffer/upload/demo.txt",
  "size_bytes": 1024,
  "agent_path": "D:\\...\\.buffer\\upload\\demo.txt"
}

curl -X POST 'http://127.0.0.1:8000/api/system/agent/upload' \
  -F 'file=@./demo.txt' \
  -F 'filename=demo.txt'

无请求参数。

{
  "today": { "calls": 12, "total_tokens": 34567, "cached_tokens": 8901 },
  "heatmap": { "2026-10-14": 12, "2026-10-13": 8 }
}

heatmap 的键为日期（YYYY-MM-DD），值为当日调用次数；无统计文件时各项为 0 / 空对象。

curl 'http://127.0.0.1:8000/api/system/agent/stats'

无请求参数。

[
  {
    "id": "tsk_ab12cd34",
    "name": "示例任务",
    "graph_name": "default",
    "state": "running",
    "step": 3,
    "expert_type": "Task",
    "create_time": "2026-10-14 10:00:00",
    "token_usage": 1234,
    "checkpoint_dir": "data/checkpoints/task/demo_tsk_ab12cd34"
  }
]

curl 'http://127.0.0.1:8000/api/tasks'

{
  "status": "success",
  "task_id": "tsk_ab12cd34",
  "message": "Task started in background."
}

任务初始化失败时返回 400（detail 为初始化错误信息），其它异常返回 500。

curl -X POST 'http://127.0.0.1:8000/api/tasks/run' \
  -H 'Content-Type: application/json' \
  -d '{"task_name": "示例任务", "graph_name": "default", "inputs": {}}'

{
  "task_id": "tsk_ab12cd34",
  "state": "running",
  "graph": "default",
  "node_states": { "node_1": "running" },
  "outputs": {},
  "node_memory": { "node_1": { "messages": [] } }
}

node_states、outputs 与 node_memory 的具体结构由任务运行时数据决定，此处为示意。任务不存在返回 404。

curl 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34/state'

{ "status": "success", "message": "指令已注入，下游链路状态已重置！" }

注入失败（如节点不存在或非 Agent 节点）返回 400。任务原本未运行时，返回后会自动重启后台引擎。

curl -X POST 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34/submit' \
  -H 'Content-Type: application/json' \
  -d '{"node_id": "node_1", "content": "请补充说明"}'

{ "status": "success", "message": "指令已精确注入" }

curl -X POST 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34/push' \
  -H 'Content-Type: application/json' \
  -d '{"node_id": "node_1", "message": "继续下一步"}'

{
  "task_id": "tsk_ab12cd34",
  "grouped_logs": {
    "node_1": [ { "node_id": "node_1", "level": "INFO", "message": "..." } ],
    "system": [ { "node_id": "system", "level": "ERROR", "message": "..." } ]
  }
}

无日志时 grouped_logs 为空对象 {}。日志条目结构由任务日志格式决定，此处为示意。

curl 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34/log'

返回文件字节流（FileResponse），响应头带 Content-Security-Policy: sandbox allow-scripts（HTML 类产物强制沙箱）与 Cache-Control: no-store。

curl 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34/artifact?uri=purrcat://output/result.html&mime=text/html'

{ "status": "ok", "message": "Task destroyed." }

任务不存在或删除失败返回 404。

curl -X DELETE 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34'

{ "status": "success", "message": "节点及其下游已彻底重置！" }

节点不存在等错误返回 400，任务无法激活返回 404。

curl -X POST 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34/nodes/node_1/reset'

{ "status": "success", "message": "Task killed gracefully." }

任务不在活跃状态或不存在返回 404。

curl -X POST 'http://127.0.0.1:8000/api/tasks/tsk_ab12cd34/stop'

无请求参数。

[
  { "id": "evt_a1b2c3", "content": "示例事件内容", "timestamp": "2026-10-14T10:00:00" }
]

事件字段结构由事件引擎决定，此处为示意；无数据时为 []。

curl 'http://127.0.0.1:8000/api/memory/events'

无请求参数。

[
  { "id": "exp_x9y8z7", "title": "示例经验", "content": "……" }
]

经验字段结构由向量引擎决定，此处为示意；无数据时为 []。

curl 'http://127.0.0.1:8000/api/memory/experiences'

无请求参数。

{
  "nodes": [ { "id": "n1", "label": "示例节点" } ],
  "edges": [ { "source": "n1", "target": "n2" } ]
}

节点/边字段结构由图谱引擎决定，此处为示意。

curl 'http://127.0.0.1:8000/api/memory/graph'

{ "result": "命中的记忆文本……" }

搜索失败时 result 为 搜索失败: <原因>。

curl 'http://127.0.0.1:8000/api/memory/search?q=项目配置'

{ "status": "success", "message": "经验已删除" }

经验不存在返回 404，其它异常返回 500。

curl -X DELETE 'http://127.0.0.1:8000/api/memory/experiences/exp_x9y8z7'

{ "status": "success", "message": "事件已删除" }

事件不存在返回 404，其它异常返回 500。

curl -X DELETE 'http://127.0.0.1:8000/api/memory/events/evt_a1b2c3'

{ "status": "success", "message": "关系边已删除" }

未找到该关系边返回 404，其它异常返回 500。

curl -X DELETE 'http://127.0.0.1:8000/api/memory/graph/relation?source_node_id=n1&target_node_id=n2'

GET 无参数；PUT 请求体为 { "content": "<Markdown 文本>" }。

GET 返回文件内容：

{ "content": "# 记忆\n……" }

文件不存在时 content 为空字符串。PUT 返回保存结果：

{ "status": "success", "message": "MEMORY.md 已成功落盘保存" }

读写失败均返回 500（detail 携带具体原因）。

curl 'http://127.0.0.1:8000/api/memory/markdown'

curl -X PUT 'http://127.0.0.1:8000/api/memory/markdown' \
  -H 'Content-Type: application/json' \
  -d '{"content": "# 记忆\n新的内容"}'

[
  {
    "type": "llm",
    "name": "LLM",
    "description": "调用大模型",
    "inputs": {},
    "outputs": {}
  }
]

返回一个数组，元素为节点定义 JSON（来自 src/harness/node/extensions/*/*.json，仅保留含 type 字段的定义）。

curl 'http://127.0.0.1:8000/api/graphs/nodes'

[
  {
    "name": "trading",
    "path": "/abs/path/graphs/trading/graph.json"
  }
]

返回数组，元素为 { name, path }；仅包含目录下存在 graph.json 的 Graph。

curl 'http://127.0.0.1:8000/api/graphs'

{
  "nodes": [],
  "edges": [],
  "global_schema": {}
}

返回 graph.json 解析后的对象。若 Graph 不存在或解析失败，返回 404 与 { "detail": "Graph not found" }。

curl 'http://127.0.0.1:8000/api/graphs/trading'

{
  "graph_name": "trading",
  "global_schema": {
    "symbol": { "required": true, "description": "交易标的" }
  }
}

global_schema 取自 graph.json 的 global_schema 字段（缺失时为空对象 {}）。若 Graph 不存在，返回 404 与 { "detail": "Graph not found" }。