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

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

重要变化:

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

Base URL:

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

作用:确认 API 是否就绪。

示例响应:

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

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

返回中常见字段:

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

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

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

• name
• data_id

可选字段通常包括:

• anchor
• behavior

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

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

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

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

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

这和 GET /mascots 不同:

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

返回中常见字段:

• id
• name
• version
• description
• author

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

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

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

作用:获取模板预览图。

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 是个例外:如果当前本来就没有运行时,它不会为了"停止"而反过来再启动一个运行时。

这是最容易混淆的一点。

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

label 的特点:

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

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

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

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

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

以下参数不再支持:

• --host
• --port

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

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

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

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

在 Windows 上,建议直接调用:

NeurolingsCE-cli.exe

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

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

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

• 快速开始
• 导入桌宠模板
• 架构概览