把 AgentForge 的库模块以正式版 1.0.0 发布到 Maven Central，让使用者可以直接通过 Maven 依赖引入。

在做开源项目时，我们常常会遇到这样一个具体问题：项目在 GitHub 上跑通了，别人想用却不知道该怎么引入。要么 git clone 后自己 mvn install，要么把 jar 传来传去，体验非常差。最优雅的方式，是把它发布到 Maven Central 官方仓库，使用者只需要在 pom.xml 里写一段依赖坐标即可。

AgentForge 的模型层与 Agent Runtime 已经具备发布条件，于是我们决定把它正式推送到 Maven Central。整个过程中，第一个拦路虎就是 groupId 命名空间该怎么定。本文就把这段完整实践记录下来。

一、背景与问题​

1.1 为什么要发布到 Maven Central​

• 使用零门槛：使用者只需声明依赖坐标，无需 clone / 编译；
• 生态认可：能被 IDE、依赖平台（如 mvnrepository）索引，属于开源项目的"正式身份"；
• 多项目复用：配合 BOM 统一版本管理，便于后续模块化演进。

1.2 我们遇到的问题​

给 AgentForge 发布时，坐标命名（groupId）是绕不过去的第一关：

• 早期项目里用的是 com.changlu.agentforge；
• 但 Maven Central 要求 groupId 必须是你能够证明"拥有 / 控制"的命名空间，com.changlu 反推域名是 changlu.com，我们并不拥有它，校验会被驳回。

那么问题来了：个人开源项目的 groupId，到底该怎么取？ 这就是本文要先讲清楚的核心概念。

二、核心概念​

2.1 发布 Maven Central 的硬性要求​

在动手之前，必须先知道 Central 对上传构件做了哪些校验。它不是"上传就完事"，而是要求同时满足：

1. sources jar + javadoc jar（非 pom 打包模块必须提供）；
2. GPG/PGP 签名：每个文件要有一个 .asc 签名文件；
3. 校验和：.md5 / .sha1 必需（.sha256 / .sha512 可选），由发布插件自动生成；
4. POM 必需元数据：name、description、url、licenses、developers、scm；
5. 版本号不能以 -SNAPSHOT 结尾。

重点：以上任何一条不满足，发布都会在 Portal 校验阶段失败。本文后续所有配置，都是围绕这 5 条来做的。

2.2 groupId 命名空间的两种来源（方案对比）​

对于个人 / 小团队项目，groupId 命名空间常见有两条路：

方案一：基于 GitHub 账号 —— io.github.<username>​

• 规则：io.github.myusername，例如 io.github.changluya；
• 校验方式：无需域名，Sonatype 要求你在对应的 GitHub 账号下，创建一个 Portal 指定名字的公开仓库来证明账号归属，验证通过后删掉即可。

方案二：基于自有域名 —— 反向域名​

• 规则：拥有 example.com 就用 com.example；拥有 changlu.cloud 就用 cloud.changlu，还能继续加项目子空间 cloud.changlu.agentforge；
• 校验方式：在该域名 DNS 添加一条 Portal 给出的 TXT 记录。

两种方案对比​

弊端说明：方案一虽然零成本，但命名会带上 GitHub 账号名（如 changluya），既不好看也无法改；一旦账号改名，历史坐标就"名不副实"。方案二需要你真正持有并会操作域名 DNS，但长期收益更大。

2.3 本方案的选择​

本方案采用方案二：命名空间 cloud.changlu，项目子空间 cloud.changlu.agentforge。

因此下文的全部前置准备（命名空间校验用 DNS TXT、Token、GPG、settings）都按「自有域名」路径编写。

注意：如果你想改用方案一，只需把命名空间换成 io.github.changluya，并把"DNS TXT 校验"替换成"建 GitHub 公开仓库"，其余步骤（GPG / Token / settings.xml / 工程改造 / 发布流程）完全一致。

三、整体方案设计​

3.1 发布哪些模块​

AgentForge 是一个多模块工程，并不是所有模块都需要对外发布。我们把库模块发布，示例模块排除：

3.2 发布链路​

本地构建
  → 各模块生成 sources / javadoc jar
  → 各模块 GPG 签名（.asc）
  → central-publishing-maven-plugin 打包成 bundle
  → 上传到 Sonatype Central Portal 校验
  → Portal 发布 → 同步到 Maven Central

重点：Sonatype 的 central-publishing-maven-plugin 会把整个 reactor 的构件打成一个 bundle 上传，因此我们只需在 parent 里配置一次，而示例模块用 excludeArtifacts 排除即可。

3.3 是否需要脚本？​

建议配置脚本。 把"版本号校验 → 本地签名打包预演 → 正式 deploy"封装成一个 release.sh，可以避免每次手敲长命令、漏参数。脚本内容见第七节。

日常开发仍然用 mvn install / test，只有发布时才走脚本。

四、前置准备（账号 / 域名 / 密钥）​

本节按「自有域名」路径说明。若用 GitHub 方式，见 2.2 的说明。

4.1 注册 Sonatype Central Portal​

打开 https://central.sonatype.com/，用邮箱 / GitHub 注册登录，记住这个账号——后面命名空间、Token、发布都在这里管理。

默认进入的时候选择的namespace由于是github登陆的则是如下默认的namespace空间：

4.2 添加并校验命名空间 cloud.changlu（自有域名路径）​

如何完成命名空间校验呢？ 步骤如下：

1. 登录 Portal → 右上角 Account → Namespaces（或首页 Add Namespace）；
2. 输入 cloud.changlu，提交；
   • 注意：校验针对的是域名本身 changlu.cloud，cloud.changlu 只是它的反向命名空间；

3. Portal 给出一个 Verification Key，到 changlu.cloud 的 DNS 服务商添加一条 TXT 记录：

   • 主机记录：@（根域名 changlu.cloud）
   • 记录类型：TXT
   • 记录值：Portal 给出的验证值（完整粘贴）

   

4. 如何验证 TXT 是否生效呢？ 本地执行：

   dig -t txt changlu.cloud
   # 或
   host -t txt changlu.cloud
   

   能看到你添加的 TXT 值即可。

5. 回到 Portal 点击 Verify，状态变为 Verified。

注意：DNS 有缓存，刚添加可能需要等几分钟到几十分钟；国内 DNS 商可能更久。

重点：命名空间一旦通过，其子命名空间（cloud.changlu.agentforge）无需再次校验，可直接发布。

4.3 安装 GPG、生成密钥并上传公钥（含常见失败排查）​

本节按“安装 → 配置 → 生成 → 签名自检 → 上传反查 → 备份”编排。除密钥向导中的姓名、公开邮箱和 Passphrase 需要人工输入外，命令块都可按顺序直接复制执行。示例不包含任何真实密钥、口令或 Token。

第 0 步：先确认本机是否已有 GPG：

gpg --version

• 有输出且 >= 2.2 → 直接跳到 4.3.2；
• 提示 command not found → 按下文安装。

4.3.1 按操作系统选择安装方式​

macOS​

先看 macOS 版本，再选安装路径：

sw_vers -productVersion
uname -m

Homebrew 只会为当前支持的 macOS 版本持续生成预编译 bottle。较旧的 macOS 可能被划为 Tier 3，此时 brew install gnupg 会转为从源码编译 OpenSSL 等大型依赖，耗时且容易中断。以 2026-10 的官方支持矩阵为例，Apple Silicon 上 macOS 15–27 可用 bottle，macOS 11–14 属 Tier 3。请以 Homebrew Support Tiers 的实时说明为准。

路径 A：Homebrew（当前受支持的 macOS）​

brew --version
brew install gnupg pinentry-mac
command -v gpg
gpg --version

Homebrew 在有匹配 bottle 时会自动下载预编译包，无需手动加 --force-bottle。如果提示 has no bottle 或长时间出现 build.rb / 编译 openssl@3，说明当前系统没有匹配的二进制包；不要反复启动 brew install，直接改用路径 B 或 C。

Apple Silicon 上 Homebrew 默认在 /opt/homebrew；若 command -v gpg 无输出，执行 eval "$(/opt/homebrew/bin/brew shellenv)"，并将该行写入 ~/.zprofile。Intel Mac 默认前缀为 /usr/local。

路径 B：MacPorts（旧版 macOS 推荐，可用二进制包）​

1. 从 MacPorts 官方安装页 下载与 macOS 大版本一致的 .pkg（例如 Sonoma 14）并安装；
2. 打开新终端，执行：

cd /tmp
sudo /opt/local/bin/port selfupdate
# 使用默认 +pinentry（终端口令输入器），不需要完整 Xcode
sudo /opt/local/bin/port install gnupg2

export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
command -v gpg && gpg --version

MacPorts 默认安装到 /opt/local。若 PATH 未自动生效：

echo 'export PATH="/opt/local/bin:/opt/local/sbin:$PATH"' >> ~/.zprofile
source ~/.zprofile

不要在只安装了 Command Line Tools 的机器上加 +pinentry_mac。MacPorts 的 pinentry-mac 端口要求完整 Xcode，否则会报 requires a full Xcode installation。Maven Central 签名使用默认终端版 pinentry 即可。如果已用错误 variant 启动过构建，需先清理该 port 的临时构建目录，再安装默认 variant：

cd /tmp
sudo /opt/local/bin/port clean gnupg2
sudo /opt/local/bin/port install gnupg2

port clean gnupg2 只会清理该 port 的临时构建产物，不会删除项目文件，也不会卸载已安装的其他依赖。

路径 C：GPG Suite（图形化快速方案）​

从 GPG Suite 官网 下载与当前 macOS 兼容的安装包。它自带 MacGPG、GPG Keychain 和 pinentry，不需要用 Homebrew 编译 OpenSSL。GPG Mail 是可选邮件插件，发布 Maven Central 并不需要它。

/usr/local/MacGPG2/bin/gpg --version
echo 'export PATH="/usr/local/MacGPG2/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile

Linux / WSL​

GnuPG 通常已在 Linux 发行版中提供。WSL 按其 Linux 发行版执行相同命令：

# Debian / Ubuntu / WSL Ubuntu
sudo apt update
sudo apt install -y gnupg2 pinentry-curses

# Fedora / RHEL
sudo dnf install -y gnupg2 pinentry

gpg --version

SSH、CI 或纯终端环境建议使用 pinentry-curses，并在当前 shell 设置：

export GPG_TTY="$(tty)"

Windows 10/11​

从 Gpg4win 官网 下载安装包。发布 Maven Central 只需 GnuPG 和 pinentry，Kleopatra 可用于图形化管理密钥。安装后重开 PowerShell 验证：

gpg --version
where.exe gpg

gpg 若未进入 PATH，将 Gpg4win 的 bin 目录加入用户 PATH，再重开 PowerShell。

什么时候才需要 Command Line Tools​

Homebrew 安装 gnupg 时若报下面这个错：

Error: No developer tools installed.
Install the Command Line Tools:
  xcode-select --install

说明系统缺少 Command Line Tools——即使 /usr/bin/clang 存在，只要没有"active developer directory"就会报。先执行：

xcode-select --install

会弹出安装窗口，点 安装 / Install，等待下载安装完成（几分钟）。完成后确认：

xcode-select -p
# 期望输出：/Library/Developer/CommandLineTools

注意：安装 bottle 时 Apple Silicon 通常不需要 CLT；从源码编译时才必须安装。若已装完整 Xcode，也可用 sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer。

4.3.2 验证 PATH 并配置 pinentry​

先确认 Maven 后续能通过 PATH 找到同一个 gpg：

command -v gpg
gpg --version
command -v pinentry || true

command -v gpg 必须输出一个真实路径，然后再执行下面的对应环境命令。

macOS/Linux 建议把 GPG_TTY 写入 shell 配置，避免口令提示绑定到错误终端：

# zsh（macOS 默认）
grep -qxF 'export GPG_TTY="$(tty)"' ~/.zshrc 2>/dev/null || \
  echo 'export GPG_TTY="$(tty)"' >> ~/.zshrc
export GPG_TTY="$(tty)"

bash 用户执行：

grep -qxF 'export GPG_TTY="$(tty)"' ~/.bashrc 2>/dev/null || \
  echo 'export GPG_TTY="$(tty)"' >> ~/.bashrc
export GPG_TTY="$(tty)"

macOS 上 gpg --full-generate-key 最常见的报错就是 No pinentry 或 Inappropriate ioctl for device，原因是找不到口令输入程序：

Homebrew 用户直接复制：

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
PINENTRY="$(brew --prefix)/bin/pinentry-mac"
touch ~/.gnupg/gpg-agent.conf
sed -i.bak '/^pinentry-program /d' ~/.gnupg/gpg-agent.conf
echo "pinentry-program $PINENTRY" >> ~/.gnupg/gpg-agent.conf
chmod 600 ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

MacPorts 用户直接复制：

export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
touch ~/.gnupg/gpg-agent.conf
sed -i.bak '/^pinentry-program /d' ~/.gnupg/gpg-agent.conf
echo 'pinentry-program /opt/local/bin/pinentry' >> ~/.gnupg/gpg-agent.conf
chmod 600 ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

Linux 纯终端用户若需要显式配置 pinentry-curses：

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
touch ~/.gnupg/gpg-agent.conf
sed -i.bak '/^pinentry-program /d' ~/.gnupg/gpg-agent.conf
echo "pinentry-program $(command -v pinentry-curses)" >> ~/.gnupg/gpg-agent.conf
chmod 600 ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

GPG Suite 和 Gpg4win 已自带并配置 pinentry，通常无需手动写 gpg-agent.conf。MacPorts 默认的 /opt/local/bin/pinentry 是终端版，可直接用于 Maven 签名。

4.3.3 生成密钥对​

个人本机推荐交互式，让 pinentry 安全读取 Passphrase，避免把口令写入 shell 历史或配置文件：

export GPG_TTY="$(tty)" 2>/dev/null || true
gpg --full-generate-key
# RSA and RSA → 4096 → 有效期（例如 2y）→ 姓名/邮箱 → 设置强 Passphrase

建议值：

• 类型：RSA and RSA；
• 长度：4096；
• 有效期：建议 2y，到期前可续期，比永久密钥更易管理风险；
• 姓名/邮箱：使用长期维护 Maven Central 构件的发布者身份；
• Passphrase：使用强口令，不要写入仓库、脚本或 shell 历史。

CI 场景可用 --batch 生成专用密钥，但不建议把 %no-protection 作为个人发布密钥的默认选项。如果必须使用无口令 CI 密钥，应限定用途、设置有效期，并将私钥仅保存在 CI Secret 中。

4.3.4 查看并记录 KEY_ID​

gpg --list-secret-keys --keyid-format=long
# sec   rsa4096/ABCDEF1234567890 2026-10-04 ...
#              ^^^^^^^^^^^^^^^^ 即 KEY_ID

同时记录完整的 40 位指纹，对外核对密钥时应优先使用指纹，不要只比较短 KEY_ID：

# 自动取当前密钥环中的第一把私钥
KEY_ID="$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')"
FULL_FINGERPRINT="$(gpg --batch --with-colons --fingerprint "$KEY_ID" | awk -F: '$1 == "fpr" { print $10; exit }')"

test -n "$KEY_ID" && test -n "$FULL_FINGERPRINT" || {
  echo 'ERROR: 未找到私钥或指纹'
  exit 1
}
echo "KEY_ID=$KEY_ID"
echo "FULL_FINGERPRINT=$FULL_FINGERPRINT"
gpg --fingerprint "$KEY_ID"

如果密钥环中已有多把私钥，先通过 gpg --list-secret-keys --keyid-format=long 找到本次创建的密钥，再手动执行 KEY_ID="16位长KEY_ID"。后续命令默认在同一个终端中执行并复用这两个变量。

4.3.5 本地签名与验签（发布前必做）​

这一步会同时验证私钥、pinentry、Passphrase 和 GPG agent，比直接跑 Maven 更容易定位问题：

# 即使换了新终端，也能自动恢复变量
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"

echo 'AgentForge Maven Central GPG signing test' > /tmp/agentforge-gpg-test.txt

gpg --local-user "$KEY_ID" \
  --armor \
  --detach-sign /tmp/agentforge-gpg-test.txt

gpg --verify \
  /tmp/agentforge-gpg-test.txt.asc \
  /tmp/agentforge-gpg-test.txt

看到 Good signature / 完好的签名 即表示本地签名链路正常。测试文件位于 /tmp，不要将其提交到项目。

4.3.6 上传公钥并从服务器反查​

# 自动恢复 KEY_ID 与完整指纹
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"
FULL_FINGERPRINT="${FULL_FINGERPRINT:-$(gpg --batch --with-colons --fingerprint "$KEY_ID" | awk -F: '$1 == "fpr" { print $10; exit }')}"

# 主用：Ubuntu 服务器（较稳定）
gpg --keyserver hkps://keyserver.ubuntu.com --send-keys "$KEY_ID"

# 备用：主用超时时改用它
gpg --keyserver hkps://keys.openpgp.org --send-keys "$KEY_ID"

# 上传后请使用完整指纹反查，不要只用短 KEY_ID
curl -fsSL \
  "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x${FULL_FINGERPRINT}" \
  | grep 'BEGIN PGP PUBLIC KEY BLOCK'

输出 BEGIN PGP PUBLIC KEY BLOCK 说明 keyserver 已经可以返回该公钥。刚上传后索引可能有短暂延迟，等待几十秒后再查即可。

注意：keys.openpgp.org 会剥离用户身份，且需要收邮件点确认链接后才算上传成功；Maven Central 更常从 keyserver.ubuntu.com 拉取，因此优先用 ubuntu。

4.3.7 备份私钥和 ownertrust​

公钥可以公开，私钥必须加密保存。备份时先限制当前 shell 的文件权限：

umask 077
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"
GPG_BACKUP_DIR="$HOME/agentforge-gpg-backup"
mkdir -p "$GPG_BACKUP_DIR"
chmod 700 "$GPG_BACKUP_DIR"

gpg --armor --export-secret-keys "$KEY_ID" \
  > "$GPG_BACKUP_DIR/agentforge-private-key.asc"
gpg --export-ownertrust \
  > "$GPG_BACKUP_DIR/agentforge-ownertrust.txt"
chmod 600 "$GPG_BACKUP_DIR"/*

$HOME/agentforge-gpg-backup 只是临时导出位置。加密磁盘、离线介质或支持安全附件的密码管理器才是合适的长期备份位置。转移完成后删除该临时目录；不要提交 Git，不要上传网盘明文，不要把私钥或 Passphrase 发给他人。

4.3.8 完整验收清单​

command -v gpg
gpg --version
gpg --list-secret-keys --keyid-format=long
KEY_ID="${KEY_ID:-$(gpg --batch --with-colons --list-secret-keys | awk -F: '$1 == "sec" { print $5; exit }')}"
gpg --fingerprint "$KEY_ID"
gpg --verify /tmp/agentforge-gpg-test.txt.asc /tmp/agentforge-gpg-test.txt

全部满足以下条件后，4.3 才算完成：

• gpg 可通过 PATH 找到；
• 能看到私钥、长 KEY_ID 和完整指纹；
• detached signature 本地验签成功；
• Ubuntu keyserver 能按完整指纹返回公钥；
• 私钥和 ownertrust 已在仓库外安全备份；
• KEY_ID 已记录，供 Maven GPG 插件使用。

4.3.9 常见失败与排查​

注意：私钥与 Passphrase 只在本机 / CI 使用，不要提交到仓库。公开的只有公钥、KEY_ID 和指纹。

4.4 生成 Portal User Token​

1. 登录 https://central.sonatype.com/；

2. 右上角打开用户菜单，点击 View User Tokens（或访问 https://central.sonatype.com/account）；

   

   

3. 在 User Tokens 页面生成 Token，得到一对 username / password（这是 Token，不是登录密码），只显示一次，立即保存。

4.5 配置 Maven settings.xml​

可以使用 Maven 默认位置 ~/.m2/settings.xml，也可放在仓库外的独立目录，发布时通过 mvn -s /absolute/path/settings.xml 指定。下面配置不把 GPG Passphrase 明文写入 XML：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <!-- Central Portal 的 User Token -->
        <server>
            <id>central</id>
            <username>YOUR_CENTRAL_TOKEN_USERNAME</username>
            <password>YOUR_CENTRAL_TOKEN_PASSWORD</password>
        </server>

    </servers>
</settings>

限制文件权限：

chmod 600 /absolute/path/settings.xml

发布前在当前终端安全读取 GPG Passphrase，输入时不回显，也不进入 shell 历史：

printf 'GPG Passphrase: '
IFS= read -r -s MAVEN_GPG_PASSPHRASE
printf '\n'
export MAVEN_GPG_PASSPHRASE

使用自定义配置文件时，Maven 命令必须带 -s：

mvn -s /absolute/path/settings.xml help:effective-settings

重点：<server id="central"> 对应发布插件的 publishingServerId，不要写成 ${server}。Maven GPG Plugin 3.2.x 默认从 MAVEN_GPG_PASSPHRASE 读取口令，不再需要在 settings.xml 增加 gpg server。

settings.xml 包含 Central Token，不得提交到 Git。文章中只使用占位符，不展示真实 Token 或 Passphrase。

五、工程构建改造（POM）​

为什么核心发布配置只改两个文件？ 因为本仓库模块的 parent 是 agentforge-ai-parent，根 agentforge-aggregator 并不是模块的 parent，所以：

• 所有模块要用的插件（source/javadoc/gpg/central）→ 放 agentforge-ai-parent；
• 根聚合器自己不发布 → 根 POM 加 maven.deploy.skip=true。

Central 还要求每个发布 POM 具有完整描述；如果某个子聚合模块原来缺少 <description>，还需在该模块的 POM 中补上。本项目对应为 agentforge-model/pom.xml 和 agentforge-framework/pom.xml。

改造全部放进 release profile，日常 mvn install / test 不触发，行为不变。

5.1 根 pom.xml​

在 <properties> 增加（只影响根聚合器自身）：

<properties>
    <revision>1.0.0-SNAPSHOT</revision>
    <!-- 根聚合器不发布到 Central -->
    <maven.deploy.skip>true</maven.deploy.skip>
    ...
</properties>

5.2 agentforge-ai-parent/pom.xml 补齐元数据​

在 <licenses>...</licenses> 之后增加：

<developers>
    <developer>
        <id>changlu</id>
        <name>changlu</name>
        <email>YOUR_PUBLIC_EMAIL_OR_NOREPLY_EMAIL</email>
        <url>https://changlu.cloud</url>
        <organization>AgentForge</organization>
        <organizationUrl>https://github.com/changluya/AgentForge</organizationUrl>
    </developer>
</developers>

<scm>
    <connection>scm:git:https://github.com/changluya/AgentForge.git</connection>
    <developerConnection>scm:git:ssh://git@github.com/changluya/AgentForge.git</developerConnection>
    <tag>HEAD</tag>
    <url>https://github.com/changluya/AgentForge</url>
</scm>

licenses / developers / scm 会被子模块继承，Central 校验时可读取；name / description 现有模块已具备，如校验提示缺 url，在 parent 补 <url> 或逐模块补齐。

5.3 agentforge-ai-parent/pom.xml 增加 release profile​

先在现有 <properties> 中统一声明插件版本：

<gpg.executable>gpg</gpg.executable>
<!-- 公开指纹：固定发布密钥，避免多私钥环境误签 -->
<gpg.keyname>YOUR_FULL_GPG_FINGERPRINT</gpg.keyname>
<maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
<maven.javadoc.plugin.version>3.11.2</maven.javadoc.plugin.version>
<maven.source.plugin.version>3.3.1</maven.source.plugin.version>
<central.publishing.maven.plugin.version>0.11.0</central.publishing.maven.plugin.version>

再在 </project> 之前加入：

<profiles>
    <profile>
        <id>release</id>
        <build>
            <plugins>
                <!-- 1) 为每个待发布 JAR 附加 Central 必需的 sources JAR -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-source-plugin</artifactId>
                    <version>${maven.source.plugin.version}</version>
                    <executions>
                        <execution>
                            <id>attach-sources</id>
                            <goals><goal>jar-no-fork</goal></goals>
                        </execution>
                    </executions>
                </plugin>

                <!-- 2) 附加 Central 必需的 Javadoc JAR；放宽 doclint，避免文档告警阻断发布 -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-javadoc-plugin</artifactId>
                    <version>${maven.javadoc.plugin.version}</version>
                    <configuration>
                        <doclint>none</doclint>
                        <quiet>true</quiet>
                    </configuration>
                    <executions>
                        <execution>
                            <id>attach-javadocs</id>
                            <goals><goal>jar</goal></goals>
                        </execution>
                    </executions>
                </plugin>

                <!-- 3) verify 阶段签名 POM 及全部附件；口令来自 gpg-agent 或 MAVEN_GPG_PASSPHRASE -->
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-gpg-plugin</artifactId>
                    <version>${maven.gpg.plugin.version}</version>
                    <configuration>
                        <!-- 脚本会用 -Dgpg.executable 覆盖为 MacPorts / Homebrew 绝对路径 -->
                        <executable>${gpg.executable}</executable>
                        <keyname>${gpg.keyname}</keyname>
                        <bestPractices>true</bestPractices>
                    </configuration>
                    <executions>
                        <execution>
                            <id>sign-artifacts</id>
                            <goals><goal>sign</goal></goals>
                            <phase>verify</phase>
                        </execution>
                    </executions>
                </plugin>

                <!-- 4) 将 reactor 构件汇总为一个 Central Portal deployment；首发保留手动 Publish -->
                <plugin>
                    <groupId>org.sonatype.central</groupId>
                    <artifactId>central-publishing-maven-plugin</artifactId>
                    <version>${central.publishing.maven.plugin.version}</version>
                    <extensions>true</extensions>
                    <configuration>
                        <publishingServerId>central</publishingServerId>
                        <!-- 首次建议 false：上传后到 Portal 手工检查再发布 -->
                        <autoPublish>false</autoPublish>
                        <!-- 排除示例模块，避免被打进上传 bundle -->
                        <excludeArtifacts>
                            <excludeArtifact>agentforge-examples</excludeArtifact>
                            <excludeArtifact>agentforge-service</excludeArtifact>
                            <excludeArtifact>agentforge-service-ui</excludeArtifact>
                            <excludeArtifact>agentforge-service-web</excludeArtifact>
                        </excludeArtifacts>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

重点：

• extensions=true 让插件接管 deploy，并把整个 reactor 打成一个 bundle 上传；
• excludeArtifacts 按 artifactId 排除，确保 service 应用不进入 bundle；
• bestPractices=true 禁止在 POM / XML 中传入明文 GPG 口令，发布前使用 MAVEN_GPG_PASSPHRASE；
• autoPublish=false（首次）上传后需到 Portal 手动点 Publish，稳定后可改 true 并加 <waitUntil>published</waitUntil>。

5.4 版本号策略​

• 工程用 ${revision} 管理版本，flatten-maven-plugin 已配置 resolveCiFriendliesOnly，部署前会把 ${revision} 解析为实际版本；

• 发布时不改文件，命令行覆盖即可：

  -Drevision=1.0.0
  

弊端说明：正式版本不能是 1.0.0-SNAPSHOT；且 Central 版本一经发布不可覆盖，每次发布请递增版本号。

5.5 本地验证第五步（不签名、不上传）​

在仓库根目录执行。这里只选中实际要发布的 11 个模块，避免 service 应用工程下载大量无关依赖：

SETTINGS_FILE="/absolute/path/settings.xml"
RELEASE_MODULES='agentforge-ai-parent,agentforge-ai-bom,agentforge-model,agentforge-model/agentforge-model-api,agentforge-model/agentforge-model-core,agentforge-model/agentforge-model-openai,agentforge-model/agentforge-model-anthropic,agentforge-model/agentforge-model-registry,agentforge-framework,agentforge-framework/agentforge-agent-core,agentforge-framework/agentforge-harness-agent'

mvn -s "$SETTINGS_FILE" \
  -P release \
  -Drevision=1.0.0 \
  -DskipTests \
  -Dgpg.skip=true \
  -pl "$RELEASE_MODULES" \
  verify

预期结果：日志中出现 Inspecting build with total of 10 modules、Installing Central Publishing features 和最终的 BUILD SUCCESS。每个 JAR 模块的 target/ 中应同时存在：

<artifactId>-1.0.0.jar
<artifactId>-1.0.0-sources.jar
<artifactId>-1.0.0-javadoc.jar

-Dgpg.skip=true 只用于第五步的 POM / 构件结构验证；第六步预演和正式发布必须移除它，确保 Central 收到 .asc 签名。

六、实战发布与一键部署​

本节是 AgentForge 1.0.0 真实跑通后整理的线性 Runbook。后续发布人员不需要手工拼 Maven 参数，从 6.1 开始按顺序执行，任何一步失败都不要继续下一步。

一键脚本位于 bin/local/release.sh，说明位于 bin/local/README.md。脚本会自动限定 11 个公开库模块、排除 examples / service、探测 GPG 绝对路径并在 Maven 前做独立签名预检。

6.1 步骤 0：创建一键发布脚本​

在仓库根目录创建 bin/local/release.sh，完整内容如下：

#!/usr/bin/env bash
set -euo pipefail

readonly RELEASE_MODULES='agentforge-ai-parent,agentforge-ai-bom,agentforge-model,agentforge-model/agentforge-model-api,agentforge-model/agentforge-model-core,agentforge-model/agentforge-model-openai,agentforge-model/agentforge-model-anthropic,agentforge-model/agentforge-model-registry,agentforge-framework,agentforge-framework/agentforge-agent-core,agentforge-framework/agentforge-harness-agent'

usage() {
    cat <<'EOF'
Usage: bin/local/release.sh <version> [options]

Options:
  --settings <file>  Maven settings.xml (default: $MAVEN_SETTINGS or ~/.m2/settings.xml)
  --dry-run          Build and sign the release artifacts without uploading
  --auto-publish     Upload and publish automatically instead of waiting in Portal
  --skip-tests       Skip tests (not recommended for a formal release)
  -h, --help         Show this help
EOF
}

[[ $# -gt 0 ]] || { usage; exit 1; }
if [[ "$1" == '-h' || "$1" == '--help' ]]; then
    usage
    exit 0
fi

VERSION="$1"
shift
SETTINGS_FILE="${MAVEN_SETTINGS:-${HOME}/.m2/settings.xml}"
DRY_RUN=0
AUTO_PUBLISH=0
SKIP_TESTS=0

while [[ $# -gt 0 ]]; do
    case "$1" in
        --settings)
            [[ $# -ge 2 ]] || { echo 'Error: --settings requires a file path.' >&2; exit 1; }
            SETTINGS_FILE="$2"
            shift 2
            ;;
        --dry-run) DRY_RUN=1; shift ;;
        --auto-publish) AUTO_PUBLISH=1; shift ;;
        --skip-tests) SKIP_TESTS=1; shift ;;
        -h|--help) usage; exit 0 ;;
        *) echo "Error: unknown option: $1" >&2; usage; exit 1 ;;
    esac
done

[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][A-Za-z0-9]+)*$ ]] || {
    echo "Error: invalid release version: $VERSION" >&2
    exit 1
}
[[ "$VERSION" != *-SNAPSHOT ]] || { echo 'Error: a Central release cannot use -SNAPSHOT.' >&2; exit 1; }
[[ -f "$SETTINGS_FILE" ]] || { echo "Error: settings.xml not found: $SETTINGS_FILE" >&2; exit 1; }
command -v mvn >/dev/null || { echo 'Error: mvn was not found in PATH.' >&2; exit 1; }

# GUI Terminal 的 PATH 可能没有 MacPorts / Homebrew，因此显式探测 GPG。
GPG_EXECUTABLE="${GPG_EXECUTABLE:-}"
if [[ -z "$GPG_EXECUTABLE" ]]; then
    for candidate in "$(command -v gpg 2>/dev/null || true)" /opt/local/bin/gpg /opt/homebrew/bin/gpg /usr/local/bin/gpg; do
        if [[ -n "$candidate" && -x "$candidate" ]]; then
            GPG_EXECUTABLE="$candidate"
            break
        fi
    done
fi
[[ -n "$GPG_EXECUTABLE" ]] || { echo 'Error: gpg was not found.' >&2; exit 1; }
export GPG_TTY="${GPG_TTY:-$(tty)}"

# 口令隐藏输入，不放入命令行、POM 或 settings.xml。
if [[ -z "${MAVEN_GPG_PASSPHRASE:-}" ]]; then
    printf 'GPG Passphrase (input hidden): '
    IFS= read -r -s MAVEN_GPG_PASSPHRASE
    printf '\n'
    [[ -n "$MAVEN_GPG_PASSPHRASE" ]] || { echo 'Error: GPG Passphrase cannot be empty.' >&2; exit 1; }
    export MAVEN_GPG_PASSPHRASE
fi

# Maven 前先对临时文件签名和验签，尽早发现错误口令或 GPG 配置。
SIGN_CHECK_FILE="$(mktemp /tmp/agentforge-gpg-check.XXXXXX)"
cleanup_sign_check() {
    rm -f "$SIGN_CHECK_FILE" "${SIGN_CHECK_FILE}.asc"
}
trap cleanup_sign_check EXIT
printf 'AgentForge Maven Central signing check\n' > "$SIGN_CHECK_FILE"
if ! printf '%s\n' "$MAVEN_GPG_PASSPHRASE" | "$GPG_EXECUTABLE" \
    --batch --yes --no-tty --pinentry-mode loopback --passphrase-fd 0 \
    --armor --detach-sign "$SIGN_CHECK_FILE"; then
    echo 'Error: GPG preflight signing failed. Enter the private-key Passphrase created with this GPG key.' >&2
    echo '       Do not enter the Central Token, KEY_ID, fingerprint, or macOS login password.' >&2
    exit 1
fi
"$GPG_EXECUTABLE" --batch --verify "${SIGN_CHECK_FILE}.asc" "$SIGN_CHECK_FILE"
cleanup_sign_check
trap - EXIT

MVN_ARGS=(
    -s "$SETTINGS_FILE"
    -P release
    "-Drevision=${VERSION}"
    "-Dgpg.executable=${GPG_EXECUTABLE}"
    -pl "$RELEASE_MODULES"
)
[[ "$SKIP_TESTS" -eq 1 ]] && MVN_ARGS+=(-DskipTests)

echo ">> version=$VERSION dryRun=$DRY_RUN autoPublish=$AUTO_PUBLISH"
echo ">> settings=$SETTINGS_FILE"
echo ">> gpg=$GPG_EXECUTABLE"

if [[ "$DRY_RUN" -eq 1 ]]; then
    mvn "${MVN_ARGS[@]}" clean verify
    echo '>> Dry run succeeded: artifacts were built and signed; nothing was uploaded.'
    exit 0
fi

if [[ "$AUTO_PUBLISH" -eq 1 ]]; then
    MVN_ARGS+=(-Dcentral.publishing.autoPublish=true -Dcentral.publishing.waitUntil=published)
fi

mvn "${MVN_ARGS[@]}" clean deploy

if [[ "$AUTO_PUBLISH" -eq 1 ]]; then
    echo '>> Central deployment was uploaded and automatic publishing was requested.'
else
    echo '>> Central deployment was uploaded. Review and publish it in the Portal:'
    echo '   https://central.sonatype.com/publishing/deployments'
fi

脚本中不要填写任何 Token、Passphrase 或私钥内容。

6.2 步骤 1：进入仓库并设置本次发布参数​

cd "/absolute/path/AgentForge"

VERSION="1.0.0"
SETTINGS_FILE="/absolute/path/settings.xml"

VERSION 必须是从未在 Central 发布过的非 SNAPSHOT 版本。SETTINGS_FILE 必须位于 Git 仓库外。

6.3 步骤 2：发布前自检​

先依次执行：

chmod +x bin/local/release.sh
chmod 600 "$SETTINGS_FILE"

# 脚本语法与用法
bash -n bin/local/release.sh
bin/local/release.sh --help

# settings.xml 必须存在；macOS 可额外用 xmllint 检查 XML
test -f "$SETTINGS_FILE"
xmllint --noout "$SETTINGS_FILE"

# 必须能看到至少一把 sec 私钥
GPG_BIN="$(command -v gpg || true)"
[[ -x /opt/local/bin/gpg ]] && GPG_BIN="/opt/local/bin/gpg"
[[ -x /opt/homebrew/bin/gpg ]] && GPG_BIN="/opt/homebrew/bin/gpg"
"$GPG_BIN" --list-secret-keys --keyid-format LONG

# 检查工作树；正式发布建议使用可追溯的 commit/tag
git status --short

# 404 表示该版本尚未出现在 Central；200 时必须换新版本
curl -sS -o /dev/null -w '%{http_code}\n' \
  "https://repo1.maven.org/maven2/cloud/changlu/agentforge/agentforge-ai-parent/${VERSION}/agentforge-ai-parent-${VERSION}.pom"

同时在 Central Portal 确认命名空间为 Verified、settings.xml 中存在 <server id="central">、GPG 公钥已上传 keyserver。

6.4 步骤 3：一键预演（不上传）​

bin/local/release.sh "$VERSION" \
  --settings "$SETTINGS_FILE" \
  --dry-run

执行时脚本会提示：

GPG Passphrase (input hidden):

输入创建当前 GPG 私钥时设置的 Passphrase。输入不回显，也不会进入 shell 历史。成功时应出现：

[INFO] BUILD SUCCESS
>> Dry run succeeded: artifacts were built and signed; nothing was uploaded.

本次实战结果：10 个模块全部 SUCCESS，真实生成的 28 个 .asc 全部本地验签成功。

经验：不要用 -Dgpg.skip=true 做最终预演，那只能验证 POM 和构件结构，无法证明真实签名链路可用。

6.5 步骤 4：一键上传（首次推荐）​

bin/local/release.sh "$VERSION" \
  --settings "$SETTINGS_FILE"

该模式执行 clean deploy，但 POM 中 autoPublish=false，因此只上传至 Central Portal，不会立即公开。成功标志：

[INFO] BUILD SUCCESS
>> Central deployment was uploaded. Review and publish it in the Portal:
   https://central.sonatype.com/publishing/deployments

本次真实上传前的 Bundle 检查结果：

• Bundle 大小约 1.8 MB；
• 共 168 个条目；
• 正好包含 10 个公开 artifact；
• 不包含 examples / studio；
• POM、主 JAR、sources JAR、Javadoc JAR 及对应 .asc 齐全。

示范案例：

# 打开AgentForge
cd "/Users/edy/changlu_workspace/mymd/我的开源项目/AgentForge"

# 执行一键推送
bin/local/release.sh 1.0.0 \
    --settings "/Users/edy/changlu_workspace/mymd/我的开源项目/maven/settings.xml" \
    --dry-run

输入的Passphrase为安装 GPG自己设置的密钥～

6.6 步骤 5：Portal 核对与 Publish​

打开 https://central.sonatype.com/publishing/deployments：

1. 确认 deployment 的版本和构件数量正确；

2. 等待状态变为 VALIDATED；

3. 首次发布建议人工检查后点击 Publish；

   

   此时会进入到publishing过程中：

   

4. 等待状态变为 PUBLISHED。

Publish 是不可逆操作。Central 上已发布的 GAV 版本不能覆盖，所以不建议首次直接使用自动 Publish。

Publish 后的等待时间：

• 点击 Publish 后，VALIDATED 通常会立即进入 PUBLISHING；
• PUBLISHING → PUBLISHED 一般需要几分钟，常见约 1～10 分钟；
• PUBLISHED 后同步到 repo1.maven.org 通常还需要几分钟；
• Central Search 索引通常在发布后几分钟内更新，但可能比公共仓库更晚。

建议每隔 1～2 分钟刷新一次 Deployments 页面，不要重复上传。状态变为 PUBLISHED 后，可直接检查公共仓库：

curl -sS -L -o /dev/null -w '%{http_code}\n' \
  'https://repo1.maven.org/maven2/cloud/changlu/agentforge/agentforge-agent-core/1.0.0/agentforge-agent-core-1.0.0.pom'

返回 200 表示已公开可用；返回 404 则继续等待同步。如果超过 30 分钟仍停留在 PUBLISHING，先查看 https://status.maven.org/；超过 1 小时仍未完成，记录 deployment ID 并联系 central-support@sonatype.com。

6.7 步骤 6（后续版本可选）：一键自动 Publish​

VERSION="1.0.1"
bin/local/release.sh "$VERSION" \
  --settings "$SETTINGS_FILE" \
  --auto-publish

--auto-publish 会动态覆盖 POM 的 autoPublish=false，并使用 waitUntil=published 等待 Central 完成发布。只应在首次人工发布验证成功后使用。

6.8 步骤 7：发布后验证​

• Portal Deployments 状态为 PUBLISHED；

• 在 https://central.sonatype.com/ 搜索完整 groupId cloud.changlu.agentforge 或 artifactId agentforge-agent-core；

• 直接检查 repo1.maven.org/maven2/<groupId 路径>/<artifactId>/<version>/；

• 在空白 Maven 项目中真实引用：

  <dependency>
      <groupId>cloud.changlu.agentforge</groupId>
      <artifactId>agentforge-agent-core</artifactId>
      <version>1.0.0</version>
  </dependency>
  

可先用 HTTP 状态做无缓存的核心验证：

curl -sS -L -o /dev/null -w '%{http_code}\n' \
  'https://repo1.maven.org/maven2/cloud/changlu/agentforge/agentforge-agent-core/1.0.0/agentforge-agent-core-1.0.0.pom'

• 200：构件已进入 Maven Central 公共仓库；
• 404 且 Portal 是 VALIDATED：只完成上传，还需在 Deployments 页点击 Publish；
• Portal 是 PUBLISHING：继续等待，不要重复上传；
• Portal 是 PUBLISHED 但仍为 404：公共仓库正在同步，稍后重试；
• repo1.maven.org 已返回 200 但 Central Search 搜不到：只是搜索索引延迟。

Portal 显示 PUBLISHED 后，同步到 Central Search 和镜像仓库仍可能需要几十分钟，以 Portal 状态和 repo1.maven.org 为准。脚本不包含任何凭据：Central Token 仅从 settings.xml 读取，GPG Passphrase 仅存在于当前发布进程。

七、常见问题与注意事项​

八、总结​

发布到 Maven Central 的完整路径可以归纳为：

1. 选命名空间：无域名用 io.github.<username>，有域名用反向域名（本方案选 cloud.changlu）；
2. 过校验：域名方式加 DNS TXT，GitHub 方式建公开仓库；
3. 备密钥与口令：GPG 密钥对 + Portal User Token + settings.xml；
4. 改构建：parent 里补元数据与 release profile（sources / javadoc / gpg / central）；
5. 跑发布：--dry-run 预演 → 正式 deploy → Portal Publish → 验证依赖；
6. 可持续：用 release.sh 固化流程，版本号递增，永不覆盖。

至此，AgentForge 的库模块即可被全世界的 Java 开发者通过一段依赖坐标直接引入。

参考资料​

[1]. Sonatype Central Portal 官方文档

[2]. Choosing your Coordinates（groupId 命名空间）

[3]. Requirements（sources/javadoc、GPG、POM 元数据）

[4]. Publishing By Using the Maven Plugin

[5]. Generating a Portal Token for Publishing

[6]. How do I set the TXT record needed to prove ownership of my Web Domain?

[7]. GPG Requirements

[8]. central-publishing-maven-plugin（Maven Central Artifact）

整理者：长路　创建时间：2026.10.4　更新时间：2026.10.5

本文按「背景/问题引入 → 核心概念 → 主流框架调研 → 实现思路 → 实战代码 → 验证测试 → 总结」递进展开，共七个部分。

一句话结论：三方中只有 LangChain4j 自研协议栈，Spring AI 与 AgentScope Java 都基于官方 MCP Java SDK；而 AgentForge 选择"核心自研协议栈 + 官方 SDK 可选桥接"。下面把这一结论的来龙去脉讲清楚。

一、背景与问题引入​

1.1、场景驱动：一个真实的接入难题​

在为 AgentForge 规划 MCP 生态接入时，我们就遇到了这样一个具体问题：

团队希望 AgentForge 的 ReActAgent 能直接吃下 MCP 生态里现成的工具（filesystem、git、fetch、数据库……）。但 AgentForge 有一条硬约束——Java 8 兼容、核心零第三方依赖。而放眼 Java 生态，Spring AI 与 AgentScope 都选了官方 MCP Java SDK，那个 SDK 却要求 JDK 17+，还会带进 Jackson、Reactor、SLF4J。
于是问题来了：我们到底该不该跟官方 SDK？

这不是 AgentForge 一家的困惑。任何"低 JDK / 零依赖"取向的框架，在接入 MCP 时都会撞上同一堵墙。

1.2、问题引导：我们要回答什么？​

1. 三个主流 Java 框架，stdio 与 HTTP 支不支持？支持到什么程度？
   
2. 它们的协议是"自己手写"还是"基于官方 MCP Java SDK"？
   
3. AgentForge 应该怎么选？自研还是官方？支持到什么程度？
   
4. 落地后，如何与 AgentForge 既有的 http / local 工具模式统一？

1.3、调研范围与对照基线​

调研对象：LangChain4j、Spring AI、AgentScope Java。对照基线是官方 MCP Java SDK。

二、核心概念​

2.1、两条技术路线：官方 SDK vs 自研​

2.1.1、路线一：基于官方 Java SDK​

协议细节（JSON-RPC、版本协商、传输分帧）由官方维护，框架只做薄封装 + 生态整合。

• 优点：省心、易过一致性测试、能力齐全、规范跟进快。
• 弊端说明：JDK 17+、引入 Jackson / Reactor / SLF4J，难以嵌入低 JDK / 零依赖项目。

2.1.2、路线二：自研协议栈​

框架自己实现 McpTransport / McpClient / JSON-RPC 路由。

• 优点：完全掌控依赖与 API，可兼容更低 JDK、零额外依赖。
• 弊端说明：需自行跟进规范修订、做双时代兼容与一致性验证。

重点：这两条路线没有绝对优劣，只取决于框架自身的约束取向——这正是三方分野、也是 AgentForge 决策的根因。

2.2、官方 SDK 的三层架构（对照）​

Client/Server 层   协议操作（listTools / callTool / initialize）
        ↓
Session 层         通信模式与连接状态
        ↓
Transport 层        JSON-RPC 收发与序列化（STDIO / HTTP / SSE）

2.3、三方速览​

三、主流框架调研​

3.1、LangChain4j：自研协议栈​

3.1.1、它到底用没用官方 SDK？​

MCP 能力在 dev.langchain4j:langchain4j-mcp 模块。查其 pom.xml 依赖：langchain4j、langchain4j-core、jackson-databind、langchain4j-http-client(-jdk)、langchain4j-open-ai。没有 io.modelcontextprotocol.sdk——即协议是自己实现的。

重点：它是三方中唯一自研的（自有 McpTransport / DefaultMcpClient / McpOperationHandler）。

3.1.2、stdio 支持​

• StdioMcpTransport：ProcessBuilder 起子进程，按行读写 JSON-RPC。
• 独立模块 langchain4j-mcp-docker 提供 DockerMcpTransport（容器形态的 stdio server）。
• Server 侧（构建 stdio server）放在 LangChain4j Community。

3.1.3、HTTP 支持​

• StreamableHttpMcpTransport：基于 JDK HttpClient，POST 单一 endpoint；可选 subsidiaryChannel(true) 打开 GET SSE 支流（legacy）。
• HttpMcpTransport：旧 HTTP+SSE，已 @Deprecated(forRemoval)。
• WebSocketMcpTransport：非标准额外传输，兼容 Quarkus MCP Server 扩展。

3.1.4、协议版本与工具治理​

• 同时支持 legacy（2025-11-25）与 modern（2026-07-28），默认自动探测（server/discover → 失败回退 initialize）。
• 工具能力：McpToolProvider 支持按名过滤、toolNameMapper、toolSpecificationMapper、多 client 聚合；DefaultMcpClient 自带工具列表缓存；支持 x-mcp-header、_meta 注入、资源订阅。
• 另有 MCP Registry 只读客户端。

3.2、Spring AI：基于官方 Java SDK​

3.2.1、它到底用没用官方 SDK？​

Spring AI MCP 明确采用官方 MCP Java SDK，其文档直接给出 SDK 的三层架构。自 Spring AI 2.0 起要求官方 SDK 1.0.0+。

注意（迁移点）：mcp-spring-webflux / mcp-spring-webmvc 从 io.modelcontextprotocol.sdk 迁到了 org.springframework.ai；相关传输类包名也从 io.modelcontextprotocol.* 变为 org.springframework.ai.mcp.*。

3.2.2、stdio 支持​

• Client：spring-ai-starter-mcp-client 提供 STDIO。
• Server：spring-ai-starter-mcp-server（spring.ai.mcp.server.stdio=true）。

3.2.3、HTTP 支持​

• Client：spring-ai-starter-mcp-client（Servlet 版 Streamable-HTTP / Stateless / SSE）、spring-ai-starter-mcp-client-webflux（WebFlux 版）。
• Server：spring-ai-starter-mcp-server-webmvc / -webflux，用 spring.ai.mcp.server.protocol = SSE | STREAMABLE | STATELESS 切换。

3.2.4、注解与治理​

• Server 注解：@McpTool、@McpResource、@McpPrompt、@McpComplete。
• Client 注解：@McpLogging、@McpSampling、@McpElicitation、@McpProgress。
• 工具适配：SyncMcpToolCallback / AsyncMcpToolCallback、SyncMcpToolCallbackProvider、McpToolUtils。

重点：Spring AI 自己不实现协议，而是薄封装官方 SDK + 补齐 Spring Boot 体验（Starter / 注解 / WebMVC·WebFlux 传输）。

3.3、AgentScope Java：基于官方 Java SDK​

3.3.1、它到底用没用官方 SDK？​

AgentScope Java 的 McpClientBuilder 内部复用官方 io.modelcontextprotocol SDK 的传输与客户端类，最终包装成 McpAsyncClient / McpSyncClient，并注入 AgentScope 的版本与 User-Agent。

3.3.2、stdio 支持​

McpClientWrapper client = McpClientBuilder.create("filesystem-mcp")
        .stdioTransport("npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp")
        .buildAsync().block();

3.3.3、HTTP 支持​

• sseTransport(url)：SSE（有状态流式）。
• streamableHttpTransport(url)：Streamable HTTP（无状态流式）。
• 支持 .header(...) / .queryParam(...)、.timeout(...)、.initializationTimeout(...)、.protocolVersions(...)、elicitation 回调。

3.3.4、工具治理​

• Toolkit.registerMcpClient(...) 统一注册；enableTools / disableTools 白黑名单；group(...) 工具分组；removeMcpClient(...) 动态摘除。
• 命名空间惯例：mcp__{server}__{tool}。
• 另有 Higress AI 网关扩展（语义化工具检索）。

注意：默认只声明 2024-11-05，连较新 Server 需显式 protocolVersions(...)，否则报 "Unsupported protocol version"。

3.4、横向对比​

3.4.1、stdio / HTTP 支持矩阵​

3.4.2、实现方式与约束​

3.5、对比分析与选型建议​

3.5.1、三种选型场景​

• 方案一：已是 Spring Boot 应用 → Spring AI。官方 SDK + Starter 最省事，但被 Spring 生态绑定。
• 方案二：多 Agent 编排 / 要工具治理与网关 → AgentScope Java。工具分组、命名空间、Higress 网关检索最完整。
• 方案三：已用 LangChain4j 或要脱离官方 SDK 约束 → LangChain4j。自研协议栈、依赖可控。

弊端说明：三者都直接或间接要求 JDK 17+ 并引入第三方库。凡是"低 JDK / 零依赖"的项目，三条都不满足——只能自研。

3.5.2、小结​

• 传输层面：三者 stdio 与 HTTP（Streamable HTTP）都支持。
• 实现层面：LangChain4j 自研，Spring AI 与 AgentScope 基于官方 SDK。
• 推论：官方 SDK 是事实标准，但它把 JDK 门槛抬到 17——这正是 AgentForge 需要单独决策的地方。

四、AgentForge 实现思路​

4.1、AgentForge 现状与约束​

4.1.1、硬约束​

重点：官方 MCP Java SDK 要求 JDK 17+ 并引入 Jackson + Reactor + SLF4J，与 AgentForge 核心约束直接冲突。

4.1.2、可复用的工具抽象​

重点：MCP 与 AgentForge 工具抽象天然同构，接入落点就是 ToolExecutor 的实现。

4.1.3、既有模式规范​

agent-core 已有两种工具模式，遵循同一套「工厂 + 执行器 + 子包」：

tool/local/   LocalToolFactory + LocalToolExecutor + support/
tool/http/    HttpToolFactory  + HttpToolExecutor  + domain/ enums/ support/ parser/
tool/mcp/     （本文新增，对齐上述规范）

4.2、实现思路：官方 SDK vs 自研​

4.2.1、方案对比​

方案一：基于官方 MCP Java SDK

• 优点：协议官方维护、易过一致性测试、能力齐全。
• 弊端说明：JDK 17+、引入 Jackson / Reactor / SLF4J，破坏核心零依赖；需额外桥接层适配 ToolExecutor。

方案二：自研协议栈

• 优点：JDK 8 兼容、零额外依赖、与 ToolExecutor 无缝、复用内置 Json 与 HttpTransport。
• 弊端说明：需自行跟进规范修订、做双时代兼容与一致性验证。

方案三：混合（核心自研 + 官方桥接）

• 核心（agentforge-agent-core）自研协议栈，保持零依赖（已落地）；
• 另设可选模块 agentforge-mcp-sdk-bridge（JDK 17），把官方 SDK 的 McpClient 包装成 AgentForge 的 ToolExecutor（P3 规划，尚未实现）。

结论：目标形态采用 方案三——主路径自研先行落地，官方 SDK 作为可选桥接后续补齐，既守住核心约束，又不把用户锁死在自研协议栈上。

4.2.2、决策依据​

4.2.3、桥接如何解决 JDK 17 冲突​

疑问：官方 SDK 要求 JDK 17，那设一个"官方桥接"模块，岂不是把 JDK 17 又带回来了？JDK 8 到底还能不能用 MCP？

先厘清：MCP 是 JSON-RPC 协议，与 JDK 无关；JDK 17 是"官方 Java SDK 这个实现"的门槛，不是 MCP 的门槛。JDK 8 完全能实现 MCP——ProcessBuilder（stdio）+ HttpURLConnection（HTTP）+ 内置 Json 即可，无需 Jackson / Reactor。

关键原则：依赖单向、字节码向上兼容。 JDK 17 编译的模块可以依赖 Java 8 编译的模块，反之不行。所以让 bridge 依赖 core，而不是 core 依赖 bridge：

agentforge-agent-core（release 8 / 零依赖）
   ▲  定义 ToolExecutor / McpClient / ToolSpecification
   │  ← 只被依赖，不含任何 MCP 实现
agentforge-mcp-sdk-bridge（release 17）
   依赖 core + 官方 SDK + Jackson / Reactor / SLF4J
   把官方 McpClient 包装成 core 的 ToolExecutor

于是 JDK 17 类型、Jackson、Reactor、SLF4J 全被关在 bridge 内部，永远不会出现在 core 的编译或运行路径上。

JDK 版本 × 实现路径

重点：自研栈不是 JDK 8 专用，它在 JDK 17 / 21 上同样运行；官方桥接是"opt-in"，不是按 JDK 版本自动切换。两条路是部署期二选一，由用户决定。

隔离手段

• 构建隔离：多模块工程，core 用 maven.compiler.release=8，bridge 用 17；core 的 POM 绝不声明 bridge，故 Jackson / Reactor / SLF4J 进不了 core 的依赖树。
• 运行隔离：bridge 是独立 artifact，JDK 8 用户不引入即永不加载，规避 UnsupportedClassVersionError。
• 接口隔离：core 只暴露 Java 8 的 ToolExecutor / McpClient，bridge 内部兼容官方类型，向上只实现 core 接口。
• 可选懒加载：用 Java 8 自带的 java.util.ServiceLoader 定义 McpClientFactory SPI——有 bridge 则发现，无则回落到自研 DefaultMcpClient，core 始终零依赖。

结论：桥接并非"在 Java 8 上跑 JDK 17 SDK"，而是给"愿意升 JDK 17 且想要官方能力"的用户开的一扇可选、受隔离的门；不升 JDK 17 的用户完全走自研栈，两条路各自干净。

当前进度：自研协议栈已实现；agentforge-mcp-sdk-bridge 与 McpClientFactory SPI 均为 P3 规划，尚未落地。

4.3、总体架构与分包​

4.3.1、目录结构​

agentforge-agent-core/src/main/java/cloud/changlu/agentforge/agent/tool/
├── mcp/
│   ├── McpToolFactory.java         # 构建入口：listTools → Map<ToolSpecification, ToolExecutor>
│   ├── McpToolExecutor.java        # implements ToolExecutor：tools/call
│   ├── McpClient.java              # 客户端接口：serverAlias / listTools / callTool / close
│   ├── DefaultMcpClient.java       # JSON-RPC 生命周期（initialize 握手、惰性初始化）
│   ├── McpProtocolException.java   # JSON-RPC error → 异常
│   ├── McpTransportException.java  # 传输失败异常
│   ├── domain/
│   │   ├── McpTool.java
│   │   ├── McpCallToolResult.java
│   │   ├── McpContent.java
│   │   ├── McpServerInfo.java
│   │   └── McpCapabilities.java
│   ├── transport/
│   │   ├── McpTransport.java       # send / request / close 的 SPI
│   │   ├── StdioMcpTransport.java
│   │   └── StreamableHttpMcpTransport.java
│   └── support/
│       ├── JsonRpcCodec.java
│       ├── McpJson.java
│       ├── McpToolSpecificationMapper.java
│       └── McpResultConverter.java

4.3.2、分层职责​

┌──────────────────────────────────────────────┐
│ McpToolFactory / McpToolExecutor              │  对接 Agent 工具表
├──────────────────────────────────────────────┤
│ DefaultMcpClient（id 递增、握手、惰性初始化）  │  协议层
├──────────────────────────────────────────────┤
│ McpTransport（stdio / Streamable HTTP）        │  传输层
└──────────────────────────────────────────────┘

4.4、核心设计与映射​

4.4.1、McpToolExecutor implements ToolExecutor​

public class McpToolExecutor implements ToolExecutor {

    private final McpClient client;        // 构造期绑定：这个工具属于哪个 MCP Server
    private final String remoteToolName;   // 构造期绑定：Server 上的原始工具名（不带 alias 前缀）

    public McpToolExecutor(McpClient client, String remoteToolName) {
        this.client = client;
        this.remoteToolName = remoteToolName;
    }

    /** 简化接口：只回文本。 */
    @Override
    public String execute(ToolExecutionRequest request, Object memoryId) {
        // 步骤①：模型给的 arguments 是 JSON 字符串 → 还原为 Map
        Map<String, Object> args = McpJson.argumentsAsMap(request.arguments());
        // 步骤②：用绑定的原始远程名发 tools/call，并把 content 拍成文本
        return McpResultConverter.toText(client.callTool(remoteToolName, args));
    }

    /** 结构化接口：额外携带 structuredContent 与 isError。 */
    @Override
    public ToolExecutionResult executeWithResult(ToolExecutionRequest request, Object memoryId) {
        try {
            // 步骤①：JSON 字符串 → Map（嵌套对象/数组保持原样）
            Map<String, Object> args = McpJson.argumentsAsMap(request.arguments());
            // 步骤②：定位"发往哪个 Server、调哪个工具"——由构造期绑定的两个字段决定
            McpCallToolResult result = client.callTool(remoteToolName, args);
            // 步骤③：无损映射回 AgentForge 结果
            return ToolExecutionResult.builder()
                    .isError(result.isError())                    // isError 原样透传
                    .result(result.structuredContent())           // structuredContent → result
                    .text(McpResultConverter.toText(result))      // content 文本 → text（回灌模型）
                    .build();
        } catch (McpProtocolException e) {                        // JSON-RPC error（如 -32601）
            return ToolExecutionResult.failure("MCP protocol error: " + e.getMessage(), e);
        } catch (McpTransportException e) {                       // 传输失败 / 超时
            return ToolExecutionResult.failure("MCP transport error: " + e.getMessage(), e);
        }
    }
}

4.4.2、McpToolFactory：List → Spec + Executor​

核心步骤：① 解析 alias（显式优先，否则 client.serverAlias()）→ ② 拉取原生工具（tools/list）→ ③ 白/黑名单过滤 → ④ 拼 alias 生成模型可见名 → ⑤ 绑定 McpToolExecutor(client, 原始名) → ⑥ 交 ToolService 按 spec.name() 建表。

public final class McpToolFactory {

    private McpToolFactory() {}

    /** 用 client 自身的 serverAlias 作为前缀。 */
    public static Map<ToolSpecification, ToolExecutor> buildTools(McpClient client) {
        return buildTools(client, null, null, null);
    }

    /** 显式 alias 优先，空白时回落到 client.serverAlias()。 */
    public static Map<ToolSpecification, ToolExecutor> buildTools(
            McpClient client, String serverAlias) {
        return buildTools(client, serverAlias, null, null);
    }

    /** enabledTools 非空时只暴露其中的远程工具名；disabledTools 命中的被隐藏。 */
    public static Map<ToolSpecification, ToolExecutor> buildTools(
            McpClient client, String serverAlias,
            Set<String> enabledTools, Set<String> disabledTools) {
        // 步骤①：确定前缀——显式 alias 优先，否则读 client.serverAlias()
        String alias = (serverAlias != null && !serverAlias.trim().isEmpty())
                ? serverAlias : client.serverAlias();

        Map<ToolSpecification, ToolExecutor> result = new LinkedHashMap<>();

        // 步骤②：拉取 Server 原生工具（首次会触发 initialize → initialized → tools/list）
        for (McpTool tool : client.listTools()) {

            // 步骤③：白/黑名单过滤（按"原始工具名"判定）
            if (enabledTools != null && !enabledTools.isEmpty()
                    && !enabledTools.contains(tool.name())) {
                continue;
            }
            if (disabledTools != null && disabledTools.contains(tool.name())) {
                continue;
            }

            // 步骤④：拼 alias 生成模型可见名；inputSchema 原样透传；写入归属元数据
            ToolSpecification spec = ToolSpecification.builder()
                    .name(qualify(alias, tool.name()))          // fs__read_file
                    .description(tool.description())
                    .parameters(McpToolSpecificationMapper.toToolParameters(tool.inputSchema()))
                    .addMetadata("mcp.server", alias == null ? "" : alias)
                    .addMetadata("mcp.tool", tool.name())
                    .build();

            // 步骤⑤：绑定 (client + 原始远程名)——运行期据此路由回对应 Server
            result.put(spec, new McpToolExecutor(client, tool.name()));
        }
        // 步骤⑥：返回 spec→executor 映射，交给 ToolService.tools(...) 按 spec.name() 建表
        return result;
    }

    private static String qualify(String alias, String toolName) {
        return (alias == null || alias.trim().isEmpty()) ? toolName : alias + "__" + toolName;
    }
}

4.4.3、Schema 映射（零损耗）​

public static ToolParameters toToolParameters(Map<String, Object> inputSchema) {
    if (inputSchema == null || inputSchema.isEmpty()) {
        return ToolParameters.empty();      // {"type":"object","properties":{}}
    }
    return ToolParameters.from(inputSchema); // 原样透传 JSON Schema
}

4.4.4、错误映射​

五、AgentForge 实战代码​

5.1、最小接入：两种传输​

5.1.1、接入本地 stdio Server​

// 1) 启动 stdio MCP Server（本地子进程，换行分帧的 JSON-RPC）
McpClient fs = DefaultMcpClient.builder()
        .serverAlias("fs")
        .transport(StdioMcpTransport.builder()
                .command("npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp")
                .build())
        .build();

// 2) 拉取工具并注册进 ToolService（读取 client 的 serverAlias，自动加前缀：fs__read_file）
ToolService toolService = new ToolService();
toolService.tools(McpToolFactory.buildTools(fs));

// 3) 与本地 @Tool 共存（同一张工具表）
toolService.tools(new WeatherTools());

// 4) 装配 ReActAgent
ReActAgent agent = ReActAgent.builder()
        .chatModel(chatModel)
        .toolService(toolService)
        .build();

重点：DefaultMcpClient 是惰性的——首次 listTools() / callTool() 时才发 initialize 握手与 notifications/initialized，随后才发 tools/list。StdioMcpTransport.of("npx", "-y", ...) 是等价的简写。

5.1.2、接入远程 Streamable HTTP Server​

McpClient remote = DefaultMcpClient.builder()
        .serverAlias("github")
        .transport(StreamableHttpMcpTransport.builder()
                .endpoint("https://mcp.example.com/mcp")
                .header("Authorization", "Bearer " + token) // 自定义头随请求透传
                .build())
        .build();

toolService.tools(McpToolFactory.buildTools(remote)); // 读取 client 的 serverAlias，工具名形如 github__search_repos

与 stdio 的差异只在传输层：serverAlias="github" → 模型可见名 github__search_repos；buildTools / ToolService / ToolExecutor 的定位与参数转换完全一致。HTTP 侧每次 tools/call 就是一次 POST：

• 请求体 = 上述 JSON-RPC（{"jsonrpc","id","method":"tools/call","params":{...}}）；
• 握手后自动带 MCP-Protocol-Version，自定义头（Authorization）原样透传；
• 响应按 id 取出（application/json 或 SSE data:），再走同一套 content / isError 映射。

5.1.3、按需过滤与关闭​

// 只暴露 read_file，屏蔽其余工具（白名单为空/null 表示全部）
Map<ToolSpecification, ToolExecutor> tools =
        McpToolFactory.buildTools(
                client, "fs",
                Collections.singleton("read_file"), // 白名单
                null);                              // 黑名单

client.close(); // stdio：关闭并回收子进程；HTTP：释放传输

5.1.4、底层核心原理：一句提问如何被闭环（真实 function call 串）​

场景：MCP fs（filesystem）与 MCP weather 同时注册，用户问「把 /tmp/a.txt 内容读出来，并查一下杭州天气」。下面按真实发生顺序展开。

① MCP Server 先返回原生 tools/list（无前缀）

AgentForge 先对每个 Server 调 tools/list，拿到的是工具本名（此时还没有 fs__ 前缀）：

// ← fs server 的 tools/list 响应
{"jsonrpc":"2.0","id":1,"result":{"tools":[
  {"name":"read_file","description":"Read a file","inputSchema":
    {"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}}
]}}

// ← weather server 的 tools/list 响应
{"jsonrpc":"2.0","id":2,"result":{"tools":[
  {"name":"get_weather","description":"Query weather","inputSchema":
    {"type":"object","properties":{"location":{"type":"string"}},"required":["location"]}}
]}}

② 中间层拼装 alias（McpToolFactory）

buildTools(client) 对上述原始工具做转换：alias__原始名，同时绑定 executor 并写入 ToolService：

fs      + read_file    → spec.name = "fs__read_file"        + McpToolExecutor(fsClient,      "read_file")
weather + get_weather  → spec.name = "weather__get_weather" + McpToolExecutor(weatherClient, "get_weather")

注意：原始名始终保留在 executor 里（read_file / get_weather），前缀只加在模型可见名上——这是后续"剥前缀、发原始名"的依据。

③ 大模型看到的 tools[]（alias 形态）

[
  {"type": "function", "function": {"name": "fs__read_file",
    "parameters": {"type": "object", "properties": {"path": {"type": "string"}}, "required": ["path"]}}},
  {"type": "function", "function": {"name": "weather__get_weather",
    "parameters": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}}
]

④ 模型返回的组合 function call（OpenAI 形态，一次两条）

{
  "role": "assistant",
  "tool_calls": [
    {
      "id": "call_a1b2",
      "type": "function",
      "function": {
        "name": "fs__read_file",
        "arguments": "{\"path\":\"/tmp/a.txt\"}"
      }
    },
    {
      "id": "call_c3d4",
      "type": "function",
      "function": {
        "name": "weather__get_weather",
        "arguments": "{\"location\":\"杭州\"}"
      }
    }
  ]
}