Kloudy CLI

默认使用 https://shape.kloudy.cn/api-x、授权页面 https://shape.kloudy.cn 和 OAuth Resource https://shape.kloudy.cn/mcp，连接线上服务，无需启动本地开发服务器。

本地 CLI 与 Kloudy MCP 复用 packages/shared/src/capabilities 的能力定义、参数校验、权限策略、调用及结构化结果，并共用 OAuth 状态。CLI 直接调用共享能力层，不启动 MCP Client/Server，不接受浏览器 Session 或客户端选择的 Character；设备由共享客户端维护。

需要 Node.js 20 或以上。安装与使用：

npm install -g kloudy-cli
kloudy --version
kloudy status
kloudy tools
kloudy rules
kloudy call characters_search '{"name":"示例"}'

当前工作区支持可选登录（尚未发布）：未登录时 tools 仅列出公开只读能力，call 可直接读取公开 Wiki、Archive 等内容。个人资产、草稿、写操作和语义检索仍需先执行 kloudy login；退出使用 kloudy logout。已有 Token 被拒绝或刷新失败时保留错误，不匿名重试。

tools 输出能力名、说明和策略；call 接收 JSON 参数，按共享 Zod Schema 校验，输出与 MCP structuredContent 相同的 JSON 对象。能力返回错误时，CLI 以非零状态退出。当前源码已提供命令和构建入口。2026-09-27 使用本地构建连接线上服务，完成真实浏览器授权、status、62 项 tools 列举、characters_search 只读调用、logout 与退出后状态检查。独立 tarball 安装已验证命令入口、版本、状态和能力列表。Token 自动刷新、撤销后旧 Token 重放及全部能力仍未验收；npm 发布版本以 registry 为准。

characters_search 和 characters_get 输出保留基础 name / intro 与完整 nameI18n / introI18n 映射；characters_search 的 name 参数由 API-X 同时用于基础名称和译名搜索。CLI 不替调用方选择语言，且仍裁剪邮箱、Character SN 和内部资料配置。

开发者可在仓库根目录运行 npm run build:cli 独立构建 CLI，或 npm run pack:cli 检查 npm 文件清单。发布前必须提交发布相关源码，再重新构建和打包；包内包含所需 shared 代码，不依赖 MCP 包。

可使用 node scripts/smoke-cli-package.mjs <tarball路径> 验证独立安装；该检查不启动 Mock，也不调用线上业务接口。

本地设备保存

当前源码在首次匿名或 OAuth 业务调用时注册 API-X 设备，将 deviceId 保存到 KLOUDY_MCP_STATE_DIR 指定状态目录的 anonymous-devices/<API-X 地址摘要>.json。本地 MCP 与 CLI 使用相同状态目录和 API-X 地址时共用设备，跨命令、重启后均从文件读取；不同 API-X 地址分别保存。OAuth 登录/退出不删除此独立文件，匿名调用不读取浏览器设备。首次并发注册使用文件锁，保存使用原子替换；缓存损坏、写入失败或锁超时会明确报错，不静默重复注册。异常退出留下锁时，确认没有注册进程后再删除对应 .lock 目录。远程 HTTP MCP 改用固定设备 kloudy-mcp-server；请求级 serve-request 保持进程内缓存。此改动尚未正式发布。

OAuth 与匿名业务调用复用相同设备来源，登录退出不会改变设备 ID。OAuth Token 失效仍直接失败，不降级匿名；设备文件沿用 anonymous-devices/ 目录名称。需与要求 OAuth+Device 的新版 API-X 配套上线，当前尚未发布。

公共资料角色投稿（本地源码，尚未发布）

新增 9 个 character_contribution_* 能力，与 MCP 使用同一参数校验和 API-X 调用。需先 kloudy login，且后端和已安装 CLI 均已更新支持此功能。仅能投稿人物、团体、虚拟角色和虚拟团体；不能修改用户、Agent、管理员等身份角色。完整参数和状态说明见 角色投稿工具说明。

kloudy call character_contribution_create_draft '{"characterId":"example_character","operation":"create","metadata":{"name":"示例角色","nameI18n":{"ja":"サンプル役","en":"Example Character"},"characterType":"virtual","intro":"角色简介","introI18n":{"ja":"キャラクター紹介"},"color":""}}'
kloudy call character_contribution_status '{"characterId":"example_character"}'
kloudy call character_contribution_submit '{"characterId":"example_character"}'
kloudy call character_contribution_list '{"status":"submitted"}'

修改已有角色时用 operation: "update" 创建草稿；修改已经保存的草稿用 character_contribution_update_draft。nameI18n / introI18n 省略时保留当前值，显式 {} 清空；其他可选资料仍使用完整快照语义，省略会清空，应先读取当前资料。其他操作为 withdraw、reopen、delete_draft、history_get，均使用上述工具前缀。提交仅进入审核，不会发布；CLI 不提供管理员审核或删除正式角色的能力。

2026-10-01 本地 CLI/MCP 与 npm 包隔离 smoke 通过：公开查询/详情多语言映射、投稿多语言参数、工具发现、非法类型拦截及匿名拒绝均已覆盖；未写入线上数据，尚未发布 npm 包。

新增图鉴类型投稿

共享 archive_search、archive_get 和 archive_contribution_* 已支持产品、图书、美术、地点的新建与编辑投稿。提交进入审核，不直接发布。参数和示例见图鉴投稿说明。

歌曲/音频查询、播放来源属性和创作者关系投稿：见共享能力说明。新增能力位于当前源码，正式安装版本以 npm 发布为准。 关系草稿可引用当前 Agent Character 自己的角色新建草稿；角色先送审后才能送审关系，管理员按角色先于关系的顺序审核。

CLI 同步提供 archive_documents_list、archive_document_get 与 9 个 archive_document_contribution_* 能力，用于图鉴详情和公开 Character 主页的介绍文档、子文档投稿。参数和审核边界见图鉴与角色介绍文档投稿。

统一贡献规则

当前工作树新增 kloudy rules，等价于 kloudy call contribution_get_rules '{}'，读取 API-X /contributions/rules 的通用规范、模块目录和版本，输出 JSON；无需登录即可通过访客设备读取。规则缺失、格式错误或响应过大时非零退出，不使用本地副本。创建、编辑和投稿前阅读规范，所有贡献能力的 tools 描述均给出该入口。本次模块读取扩展尚待上线，协议见贡献规范读取。

按需读取模块规范（2026-10-15 本地实现）

GET /contributions/rules、contribution_get_rules({})、kloudy rules 返回通用规范及 modules 目录（module、entryId、title），只读取目录元数据，不读取各模块正文。

使用 GET /contributions/rules?module=wiki、contribution_get_rules({"module":"wiki"}) 或 kloudy rules wiki 读取通用规范和所选模块全文。Character 使用 character；Archive 按实际资源类型选择，如 song、movie、game、activity、collection，以目录返回值为准。没有模块细则时仍应读取通用规范，不虚构规则。旧 wiki_get_writing_rules 专用入口自动选择 wiki。

目录来自通用规范的公开直属子词条关系，后端维护唯一根 ID，客户端不复制正文。所选模块缺失、隐藏或正文为空时失败，不静默回退；版本为实际返回正文的 SHA-256。通用正文及所选正文原文保留，模块正文前附标题。模块目录变化不改变正文哈希。未发布部署，当前连接行为不据此推断。