Skip to content

HTTP API

Jump to bottom
qingchenyouforcc edited this page Apr 24, 2026 · 3 revisions

HTTP API 与 CLI

本页统一说明 NeurolingsCE 的外部控制方式，避免把 HTTP API、CLI 和本地控制接口混为一谈。

先看分工

  • HTTP API：给外部程序使用的 REST 接口。
  • NeurolingsCE-cli：给终端、脚本、agent 用的命令行前端。
  • 本地控制接口：CLI 与运行时在本机通信的主通道。

重要变化：

  • 现在 CLI 的主通道是本地控制接口，不是 HTTP。
  • HTTP API 仍然存在，但它不是 CLI 必经层。

HTTP API

Base URL：

http://127.0.0.1:32456/shijima/api/v1

GET /ping

作用：确认 API 是否就绪。

示例响应：

{
  "ok": true,
  "app": "NeurolingsCE",
  "api_version": "v1"
}

GET /mascots

作用：列出当前屏幕上的桌宠实例。

返回中常见字段：

  • id
  • name
  • data_id
  • active_behavior
  • anchor
  • label，如果该实例被 CLI 标记过

POST /mascots

作用：生成一个新桌宠实例。

请求里至少提供以下之一：

  • name
  • data_id

可选字段通常包括：

  • anchor
  • behavior

DELETE /mascots

作用：关闭全部桌宠实例。

GET /mascots/:id

作用：查询单个桌宠实例状态。

如果目标不存在，会返回 mascot_not_found 这一类错误对象。

PUT /mascots/:id

作用：修改现有桌宠实例状态，例如位置或行为。

GET /loadedMascots

作用：列出当前已加载、可被召唤的模板。

这和 GET /mascots 不同：

  • loadedMascots 是模板列表
  • mascots 是已在屏幕上的实例列表

返回中常见字段：

  • id
  • name
  • version
  • description
  • author

其中 name 来自 .mascot 包根目录的 info.json.name。

GET /loadedMascots/:id

作用：查看某个已加载模板的信息。

该接口同样会返回 version、description、author 等模板元数据。

GET /loadedMascots/:id/preview.png

作用：获取模板预览图。

CLI：NeurolingsCE-cli

CLI 是当前最适合自动化的入口。

全局选项

  • --quiet
  • --json
  • --connect-timeout-ms <ms>
  • --read-timeout-ms <ms>

常用命令

  • --help / -h
  • --summon / -s
  • --close
  • --close-all
  • --stop
  • --mascot / -m
  • --list / -l
  • --version / -v

常见命令形式

NeurolingsCE-cli --summon mascot --name NAME [label]
NeurolingsCE-cli --summon mascot --data-id ID [label]
NeurolingsCE-cli --summon random [label]
NeurolingsCE-cli --close LABEL
NeurolingsCE-cli --close-all
NeurolingsCE-cli --stop
NeurolingsCE-cli --mascot list
NeurolingsCE-cli --mascot add PACKAGE_OR_ZIP
NeurolingsCE-cli --mascot remove MASCOT
NeurolingsCE-cli --list
NeurolingsCE-cli --version

模板管理和运行时控制的区别

  • --mascot list / add / remove：直接管理本机模板包，不要求主程序已运行。
  • --mascot add 可以接受新的 .mascot 单文件包，也可以接受兼容的传统 ZIP 资源包；传统 ZIP 会在导入时转换为 .mascot。
  • --summon / --close / --close-all / --stop / --list：面向运行时控制。

自动启动运行时

当你执行运行时控制命令，而当前本机还没有可用运行时时：

  • CLI 会尝试自动拉起 NeurolingsCE 运行时。
  • 拉起成功后，再通过本地控制接口发命令。

--stop 是个例外：如果当前本来就没有运行时，它不会为了“停止”而反过来再启动一个运行时。

label 和 runtime id 的区别

这是最容易混淆的一点。

  • runtime id：运行时内部实例 ID。
  • label：CLI 层给用户和脚本使用的标签。

label 的特点：

  • 只在当前运行时进程存活期间有效。
  • 应用重启后会清空。
  • GET /mascots 返回中可能包含 label 字段。

如果你在写自动化脚本，希望更稳定地关闭“刚刚自己召唤出来的那一只”，通常应该主动给它一个 label。

兼容旧命令

目前仍兼容的旧命令包括：

  • list
  • list-loaded
  • spawn
  • alter
  • dismiss
  • dismiss-all

如果你在维护旧脚本，可以先继续用；新脚本建议直接改用文档化的新参数形式。

不再支持的参数

以下参数不再支持：

  • --host
  • --port

原因是 CLI 已经不再走 HTTP 作为主通信层。

--json 什么时候该用

你在这些场景里应优先加 --json：

  • 写自动化脚本
  • 写 agent skill
  • 需要稳定解析成功/失败结果

--json 会让输出更适合机器解析，包括错误对象。

Windows 使用建议

在 Windows 上，建议直接调用：

NeurolingsCE-cli.exe

这样 shell 和 agent 更容易获得正确的退出码。

真源文档

如果你在维护接口文档或做代码同步，请以主仓库中的 src/docs/HTTP-API.md 为接口真源。

wiki 这一页的目标是提升可读性，不替代源码树内的接口文档。

下一步阅读

NeurolingsCE Wiki

用户入口

资源包与模板

开发者入口

Clone this wiki locally