dsh-plus-nacos
v0.1.0
Published
Nacos 3.3 AI Registry 的 Agent 注册器(Java 实现 + 完整中文 SDK 文档):发布 Agent 定义、注册运行时端点、心跳保活、优雅注销,支持 A2A AgentCard。
Maintainers
Readme
dsh-plus-nacos
把 A2A Agent 注册到 Nacos 3.3 AI Registry 的注册器,Java 实现,附带一份完整的 Nacos 3.3.0 Java SDK 中文参考手册。
为什么是 Java 项目却发在 npm 上? 因为 Nacos 3.3 的 Agent 能力(
publishAgent/registerAgentEndpoints/subscribeAgent/ AgentCard 转换)目前只有 Java SDK 提供完整实现,Python 只覆盖旧接口,Node 和 Go 还没有。这个包把「可直接运行的 jar + 可二次开发的 Maven 工程 + 中文 API 手册」三件套放进一个 npm 包里,方便通过npm i分发到内网机器。
它做什么
Nacos 3.3 里「把 Agent 注册上去」是两件独立的事,本工具都做了:
| 步骤 | 调用的 API | 何时执行 |
|---|---|---|
| 发布 Agent 定义(含 A2A AgentCard、协议、版本) | AgentService.publishAgent | 首次部署执行一次 |
| 注册运行时端点(本实例的 IP:Port) | AgentService.registerAgentEndpoints | 每次启动 |
| 心跳保活 / 断线重连 | SDK 内部 gRPC 长连接 | 常驻自动 |
| 优雅注销 | AgentService.deregisterAgentEndpoints | JVM 退出(shutdown hook) |
注册完成后,其他 agent 可以通过 subscribeAgent(RAD)发现你,或把结果转成标准 A2A AgentCard。
安装
npm install -g dsh-plus-nacos(不需要全局也可以用 npx dsh-plus-nacos)
快速开始
# 1. 检查 Java 环境
dsh-plus-nacos doctor
# 2. 生成配置模板
dsh-plus-nacos init ./my-agent
# 编辑 ./my-agent/registrar.properties:
# nacos.server-addr=你的nacos:8848
# agent.name=my-agent
# agent.endpoint-uri=http://你的地址:9000/a2a
# 账号密码走环境变量 NACOS_USERNAME / NACOS_PASSWORD
# 3. 启动注册器
dsh-plus-nacos run ./my-agent/registrar.properties启动成功的日志长这样(日志落在 ./logs/YYYY-MM-DD/agent-registrar.N.log,单文件 5MB 滚动,保留 7 天):
启动自检 | nacos=10.0.0.1:8848 | namespace=public | agent=my-agent:1.0.0 | ...
agent definition published: my-agent:1.0.0
agent endpoint registered: my-agent -> http://10.0.0.2:9000/a2a (1.0.0 [1.0.0])
ready: my-agent -> http://10.0.0.2:9000/a2a命令
| 命令 | 作用 |
|---|---|
| dsh-plus-nacos doctor | 检查 jar、Node、Java 版本 |
| dsh-plus-nacos path | 打印内置 jar 的绝对路径(自己写脚本时用) |
| dsh-plus-nacos init [目录] | 生成 registrar.properties 配置模板 |
| dsh-plus-nacos extract [目录] | 导出 Maven 工程源码 + 文档,用于二次开发 |
| dsh-plus-nacos run [配置] | 启动注册器 |
包内容
dsh-plus-nacos/
├── dist/nacos-agent-registrar.jar fat jar,java -jar 直接跑(约 35MB)
├── java/ 完整 Maven 工程
│ ├── pom.xml nacos-client 3.3.0 + shade 打 fat jar
│ ├── src/main/java/... 3 个类,约 370 行
│ ├── registrar.properties.example 配置模板
│ └── docs/ SDK 中文手册,7 篇约 1700 行
└── bin/cli.js CLI 入口前置要求
- JDK 8+(fat jar 编译目标是 Java 8,JDK 17/21 也能跑)
- Nacos 服务端 3.3.0 或更高 —— 3.2.x 及以下调用
aiService.agent()会抛UnsupportedOperationException - 9848 端口可达 —— gRPC 通道,只开 8848 连不上;内网只放行了 8848 的话把
nacos.ai-transport-mode改成http - 账号权限 —— 3.3 默认开启鉴权,光能登录不够,需要 Grant Agent 读权限 + 端点写权限
文档
java/docs/ 下是 Nacos 3.3.0 的 Java SDK 参考手册,内容逐条对照 api 模块(477 个类)源码核实,标注了 [实测] / [源码核对] 两种可信度:
| 文件 | 内容 |
|---|---|
| docs/README.md | 入口:包地图、能力矩阵 |
| docs/01-setup.md | 依赖、初始化、鉴权、传输模式、错误码 |
| docs/02-agent-registry.md | 发布定义、注册端点、发现、订阅、AgentCard 转换 |
| docs/03-a2a-compat.md | A2A 旧接口(releaseAgentCard 那一套) |
| docs/04-mcp-prompt-skill-lock.md | MCP / Prompt / Skill / AgentSpec / 分布式锁 |
| docs/05-naming-config.md | NamingService / ConfigService |
| docs/06-pitfalls.md | 踩坑清单、排错路径、上线自检 |
退出码
| 码 | 含义 | |---|---| | 0 | 正常退出 | | 1 | Nacos 交互失败(连不上、鉴权失败、版本不支持) | | 2 | 配置错误 / 环境缺失 |
方便直接配 supervisor / systemd 做失败重启。
License
MIT
