HTTP API 参考

面向用户的 Agent API。更多细粒度命令建议优先使用 CLI（town ...）。

基础接口

`GET /health`

{ "status": "ok", "timestamp": "2026-03-08T12:00:00.000Z" }

`GET /api/status`

{ "name": "downcity", "status": "running", "timestamp": "..." }

`POST /api/execute`

请求体：

{
  "instructions": "帮我总结今天的改动",
  "chatId": "default"
}

托管 plugin API

`GET /api/plugins/list`

列出托管 plugin 运行状态。

`POST /api/plugins/control`

{ "pluginName": "chat", "action": "restart" }

action 支持：start | stop | restart | status。

`POST /api/plugins/command`

{
  "pluginName": "task",
  "command": "list",
  "payload": { "status": "enabled" }
}

Plugin API

`GET /api/plugins/catalog`

列出已注册的 plugin。

`POST /api/plugins/availability`

{ "pluginName": "asr" }

`POST /api/plugins/action`

{
  "pluginName": "asr",
  "actionName": "status",
  "payload": {}
}

Console UI API（摘要）

`GET /api/ui/plugins`

返回 plugin 摘要与可用性信息（适用于 Console UI 面板）。

返回字段示例：

{
  "success": true,
  "plugins": [
    {
      "name": "asr",
      "actions": ["status", "on", "off"],
      "pipelines": ["chat.augmentInbound"],
      "guards": [],
      "effects": [],
      "resolves": [],
      "hasSystem": true,
      "hasAvailability": true,
      "availability": {
        "enabled": true,
        "available": true,
        "reasons": []
      },
      "config": {
        "actions": [
          {
            "name": "status",
            "supportsCommand": true,
            "supportsApi": true,
            "apiMethod": "",
            "apiPath": ""
          }
        ]
      }
    }
  ]
}

`POST /api/dashboard/sessions/:sessionId/execute`

在指定会话执行一轮（例如你在 UI 里选中的 chatKey）。

带附件请求示例：

{
  "instructions": "请阅读附件 markdown，并给出可执行摘要。",
  "attachments": [
    {
      "type": "document",
      "fileName": "page.md",
      "contentType": "text/markdown; charset=utf-8",
      "content": "# Captured Web Page\n\n..."
    }
  ]
}

说明：

sessionId 应传 runtime 返回的目标会话 ID。聊天场景下该 ID 由 chat plugin 维护映射（不再要求可由平台字段直接拼接）。
附件会先被 runtime 落盘，再以 <file ...> 标签自动注入到用户消息前部。
当 sessionId 映射到 chat 会话时，会复用 chat plugin 的同一条执行队列（与平台入站消息一致），并在执行前写入 chat history。
chat 上下文调用会立即返回排队结果（queued=true、queueItemId、queuePosition）。

Action 路由

plugin action 使用这些入口：

/api/plugins/action
/api/plugins/control
/api/plugins/command

调试建议

先确认 runtime 已启动：

town agent start
curl http://localhost:5314/health

HTTP API 参考

目录