nacos-cli 使用手册 — 完整版

nacos-cli 是一个命令行工具，管理 Nacos 配置中心 + AI Skills 同步。

一、安装

# 一键安装（推荐）
curl -fsSL https://nacos.io/nacos-installer.sh | bash -s -- --cli

# 安装后添加 PATH
export PATH="$HOME/.nacos/bin:$PATH"

# 验证
nacos-cli --help

安装后完成的操作：

• ~/.nacos/bin/nacos-cli 二进制文件
• ~/.nacos/ 配置目录
• PATH 已写入 ~/.zshrc

二、Profile 管理

Profile = 环境配置（服务器地址、账号）。可以建多个：dev / prod / home。

创建 Profile

# 交互式（会打开编辑器让你填）
nacos-cli profile edit home

# 一行命令设置所有字段
nacos-cli profile set home \
  host=192.168.1.108 \
  port=8848 \
  username=nacos \
  password=nacos

安全说明： username、password、accessKey、secretKey、securityToken 这五个字段用 AES-256-GCM 加密后存到文件。加密密钥在 ~/.nacos-cli/key（权限 600）。

查看 Profile

nacos-cli profile list          # 列出所有 profiles
nacos-cli profile show home     # 查看某个 profile 的值
                                # 密码显示为 ******
nacos-cli profile get home host # 只看单个字段

切换默认 Profile

nacos-cli profile switch home
# 之后运行 nacos-cli 命令时不加 --profile，默认使用 home

删除 Profile

nacos-cli profile delete dev

三、配置管理（Config）

Nacos 最核心的功能：增删改查配置。

# 读取配置
nacos-cli config-get <dataId> <group>
nacos-cli --profile home config-get sa-contract.yaml GAME

# 写入配置
nacos-cli config-set <dataId> <group>              # 从 stdin 读取
nacos-cli config-set <dataId> <group> --file ./f.yaml  # 从文件读取
echo 'content' | nacos-cli config-set <dataId> <group>

# 列出配置
nacos-cli config-list
nacos-cli config-list --data-id sa-*    # 支持通配符过滤
nacos-cli config-list --page 2 --size 10

配置优先级

命令行参数 > --profile > profile switch > 环境变量 > 默认值

四、Skill 管理

Skill 三阶段生命周期

每个 Skill 经历三个阶段才能上线：

# 📤 阶段一：上传草稿（editing）
nacos-cli skill-upload ./my-skill                # 单个
nacos-cli skill-upload --all ./skills/           # 批量

# 📋 阶段二：提交审核（reviewing → reviewed）
nacos-cli skill-review my-skill
# 审核是异步的，状态从 reviewing 变为 reviewed
# 可以查看状态：
nacos-cli skill-describe my-skill

# 🚀 阶段三：发布上线（online）
nacos-cli skill-release my-skill --version 0.0.2

查看和下载

nacos-cli skill-list                              # 列表
nacos-cli skill-list --output json                # JSON 输出（脚本用）
nacos-cli skill-list --name my-skill --page 1 --size 20  # 过滤+分页

nacos-cli skill-describe my-skill                 # 详情+版本历史
nacos-cli skill-describe my-skill --output json

nacos-cli skill-get my-skill                      # 下载到 ~/.skills/
nacos-cli skill-get my-skill -o /custom/path      # 指定路径

可见性和标签

nacos-cli skill-scope my-skill --scope PUBLIC    # 公开
nacos-cli skill-scope my-skill --scope PRIVATE   # 私有（仅自己可见）
nacos-cli skill-tags my-skill --tags retail,finance  # 标签分类

五、Skill Sync（跨 Agent 同步）

Skill Sync 是最常用的功能：让多个 Agent 共用同一套 Skills。

原理

中心仓库（~/.nacos-cli/skill-sync/profiles/<profile>/skill-repo/）
    │
    ├── symlink → ~/.claude/skills/skill-a
    ├── symlink → ~/.cursor/skills/skill-a
    ├── symlink → ~/.codex/skills/skill-a
    └── symlink → ~/.hermes/skills/skill-a

磁盘上 Skill 文件只存一份在中心仓库，其他 Agent 目录都是 symlink。

本地模式（Local Mode）

不需要 Nacos 服务器，本地文件做中心。

# 添加 skill 到 sync
nacos-cli skill-sync add my-skill
nacos-cli skill-sync add --all                    # 全部

# 注册自定义 Agent 目录（nacos-cli 不认识的需要手动加）
nacos-cli skill-sync agent add hermes ~/.hermes/skills
nacos-cli skill-sync agent add workbuddy ~/.workbuddy/skills
nacos-cli skill-sync agent list

# 查看状态
nacos-cli skill-sync status

# 加完所有 skill 后启动守护进程（持续同步）
nacos-cli skill-sync start

Nacos 模式

有 Nacos 服务器时，以服务器为中央源。

nacos-cli --profile home skill-sync add --all
nacos-cli --profile home skill-sync start
# 启动后自动每 60 秒检查同步状态
# 本地有修改自动上传为 draft
# 远程有更新自动拉取到本地

解决冲突

# 查看冲突
nacos-cli skill-sync status
# 显示 Conflict 状态的 skill

# 以 Nacos 版本为准
nacos-cli skill-sync resolve my-skill --use-nacos

# 以本地某个 Agent 的版本为准
nacos-cli skill-sync resolve my-skill --use-agent codex

同步状态说明

六、你本机已完成的配置

Nacos 服务器: 192.168.1.108:8848
Profile 名称: home
已同步 Skills: 191 个
已注册 Agent: 10 个
  - codex / claude / cursor
  - openclaw / agents / hermes
  - workbuddy / qclaw / cc-switch / open-design

日常使用

# 查看同步状态
nacos-cli --profile home skill-sync status

# 加新 skill
nacos-cli --profile home skill-sync add <skill-name>

# 查看 Nacos 上的 Skills
nacos-cli --profile home skill-list

# 读/写接口契约
nacos-cli --profile home config-get sa-contract.yaml GAME
nacos-cli --profile home config-set sa-contract.yaml GAME --file ./contract.yaml

七、交互终端模式

不想每次都敲 --profile home 前缀？用交互模式：

nacos-cli -s 192.168.1.108:8848 -u nacos -p nacos

进入后支持命令：

nacos> help           # 显示所有命令
nacos> server         # 服务器信息
nacos> ns             # 当前命名空间
nacos> ns production  # 切换命名空间
nacos> skill-list     # 列出 skills
nacos> config-list    # 列出配置
nacos> clear          # 清屏
nacos> quit           # 退出

八、完整命令速查