npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

dsh-plus-nacos

v0.1.0

Published

Nacos 3.3 AI Registry 的 Agent 注册器(Java 实现 + 完整中文 SDK 文档):发布 Agent 定义、注册运行时端点、心跳保活、优雅注销,支持 A2A AgentCard。

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