sk-hermes-cli 1.0.0

package/README.md

@@ -0,0 +1,147 @@
+# sk-hermes-cli
+
+`sk-Hermes`（Java AI Agent）的 npm 分发壳。装完即可在任意目录敲 `hermes` 或 `sk-hermes` 进入对话，
+等价于 Claude Code 的 `claude` 命令。
+
+> 本包只是一个 **JS → Java 的桥接 shim**：`bin/hermes.js` 用 `child_process.spawn` 启动 `java -jar hermes.jar`，
+> 并透传参数、stdin/stdout、退出码。npm 在这里只承担「分发 + 注册全局命令」的职责；
+> 181MB 的 jar 不进 npm 包，而是发布到 **GitHub Release**，安装时自动下载（esbuild 同款思路）。
+
+## 用户体验（安装者视角）
+
+```bash
+npm install -g sk-hermes-cli
+# postinstall 自动从 GitHub Release 下载 hermes.jar
+hermes          # 任意目录直接对话，模型以当前目录为项目根
+```
+
+### 安装者前置依赖
+- **JDK 21+**（`java` 在 PATH 中，或设置 `JAVA_HOME`）
+- 首次运行前配置 `~/.skhermes/config.yaml` 的 `model.api_key`
+- 能访问 GitHub（下载 jar）；被墙时可设 `SKHERMES_JAR_URL` 指向镜像，或 `SKHERMES_JAR` 指向本地文件
+
+### 使用
+
+```bash
+hermes              # 在当前目录直接进入对话，模型以当前目录为项目根
+hermes -m fast      # 指定模型别名
+hermes --help       # 查看全部子命令（chat / sessions / resume）
+hermes chat -s      # 显式子命令 + 流式输出
+```
+
+### jar 查找优先级（运行时）
+1. 环境变量 `SKHERMES_JAR`（显式指定，适合多版本共存 / 开发调试）
+2. 包内 `jar/hermes.jar`（postinstall 下载的落地位置，或作者手动捆绑）
+3. `~/.hermes/hermes.jar`（兼容 `tools/install-hermes.ps1` 的本地安装）
+
+---
+
+## 作者发布教程（模式 B：GitHub Release 按需下载）
+
+> 下载地址不再依赖环境变量：**package.json 内置了默认 `hermes.jarUrl`**（本仓库发布版已指向
+> `https://github.com/chen-2024-cn/Hermes-agent-Java-/releases/download/v1.0.0/hermes.jar`），
+> 环境变量 `SKHERMES_JAR_URL` 仅作临时覆盖（优先于内置值）。
+
+### 第 0 步：一次性准备（只做一次）
+
+| 检查项 | 命令 | 要求 |
+|---|---|---|
+| GitHub CLI | `gh auth status` | 已登录且 token 有 repo 权限 |
+| npm 账号 | `npm whoami` | 未登录则 `npm login`（浏览器注册/验证） |
+| 仓库可见性 | GitHub 仓库设置 | 必须 **public**（Release 资产匿名可下载，postinstall 才不用带 token） |
+| 包名可用性 | `npm view sk-hermes-cli` | 返回 404 = 未占用，可直接用 |
+
+### 第 1 步：构建 jar 并发布到 GitHub Release（一键脚本，幂等）
+
+```powershell
+cd <项目根>
+powershell -ExecutionPolicy Bypass -File tools\release.ps1
+# 指定版本号: -Version 1.1.0（默认取 npm-package\package.json 的 version）
+```
+
+脚本内部等价于三步（理解原理用）：
+
+```powershell
+mvn -f sk-hermes\pom.xml clean package -DskipTests        # ① 构建 fat jar
+gh release create v1.0.0 --title "..." --target master    # ② 建 Release（tag 须与 jarUrl 一致）
+Copy-Item sk-hermes\target\sk-hermes-1.0-SNAPSHOT.jar $env:TEMP\hermes.jar   # ③ 先复制成 hermes.jar
+gh release upload v1.0.0 $env:TEMP\hermes.jar --clobber   #    再上传（见下方"坑"）
+```
+
+> ⚠️ **gh 的 `path#name` 重命名语法不可靠**（gh 2.97 实测 `#name` 只是 Web UI 显示标签，
+> 资产真实名始终 = 源文件 basename）。而 postinstall 下载 URL 尾段必须是 `hermes.jar`，
+> 所以**必须先把 jar 复制成物理文件名 `hermes.jar` 再上传**，否则用户安装时 404。
+> release.ps1 已内置这个复制步骤 + 上传后资产核验（大文件上传可能静默失败）。
+
+**验证下载地址可用**（期望 HTTP/2 200）：
+
+```powershell
+curl.exe -sIL "https://github.com/chen-2024-cn/Hermes-agent-Java-/releases/download/v1.0.0/hermes.jar" | Select-Object -First 1
+```
+
+### 第 2 步：核对 package.json 内置地址
+
+```json
+"hermes": { "jarUrl": "https://github.com/<owner>/<repo>/releases/download/v1.0.0/hermes.jar" }
+```
+
+发新版本时 tag 变了，两种策略二选一：
+- **URL 带具体 tag**（当前方案）：每次发版改一行；地址永久有效、支持版本回滚
+- **`/releases/latest/download/hermes.jar`**：永远指向最新 Release，发版不用改；但用户无法锁旧版
+
+### 第 3 步：发布前本地全链路验证（隔离，不污染全局）
+
+```powershell
+cd npm-package
+npm pack --dry-run          # 包内应只有 3~4 个小文件（无 jar），体积 ~3.5KB
+
+$pfx = "$env:TEMP\hermes_test"; New-Item -ItemType Directory -Force -Path $pfx | Out-Null
+npm install -g .\npm-package --prefix $pfx
+#   期望输出: [sk-hermes] 正在从 https://github.com/... 下载 hermes.jar ...
+#             [sk-hermes] jar 已下载到 ...\jar\hermes.jar（181.x MB）
+& "$pfx\hermes.cmd" --version   # 期望 1.0.0，退出码 0
+Remove-Item -Recurse -Force $pfx
+```
+
+> ⚠️ 若 npm 开启了 install-scripts 安全策略（提示 `allow-scripts`），postinstall 会被拦截，
+> 执行 `npm approve-scripts sk-hermes-cli` 放行后重装。
+
+### 第 4 步：发布
+
+```powershell
+cd npm-package
+npm publish --access public
+```
+
+### 第 5 步：日常迭代发版循环
+
+```powershell
+mvn -f sk-hermes\pom.xml clean package -DskipTests          # 1) 构建
+cd npm-package; npm version 1.1.0 --no-git-tag-version; cd ..   # 2) 升版本号（npm 禁止同版本重复发布）
+powershell -ExecutionPolicy Bypass -File tools\release.ps1    # 3) 传新 tag 的 Release
+#        4) 同步修改 package.json 的 hermes.jarUrl → v1.1.0
+npm pack --dry-run; 第 3 步验证; npm publish                   # 5) 验证后发布
+```
+
+## 常见坑（全部实测踩过）
+
+| 坑 | 现象 | 解法 |
+|---|---|---|
+| Release 资产名不对 | postinstall 下载 404 | 资产真名必须叫 `hermes.jar`；gh 的 `#重命名`不生效，须先 `Copy-Item` 成 hermes.jar 再 upload |
+| 大文件上传静默失败 | 资产列表为空/不全 | `gh release view v1.0.0 --json assets` 核验；失败重跑 release.ps1（幂等，含上传后自动核验） |
+| 仓库是 private | 匿名下载 404 | 仓库设 public；或 postinstall 带 token（复杂度高，不推荐） |
+| npm 拦截 postinstall | 装完没 jar，运行时提示找不到 | `npm approve-scripts sk-hermes-cli` 或 `npm rebuild` |
+| 包名被占用 | `npm publish` 403 | `npm view <名字>` 先探测；占用则换名或用 scoped 包 `@你/sk-hermes-cli` |
+| 含中文 .ps1 报语法错 | "字符串缺少终止符"、输出乱码 | 必须存**带 BOM 的 UTF-8**（PS 5.1 无 BOM 按 GBK 解析） |
+| gh stderr 触发 PS 终止 | `$ErrorActionPreference='Stop'` 时探测命令被误杀 | 探测类 gh 调用临时切回 Continue（见 release.ps1 的 Invoke-GhProbe） |
+
+## 项目结构
+
+```
+npm-package/
+├── package.json           # bin 声明（hermes + sk-hermes）+ hermes.jarUrl 内置下载地址
+├── bin/hermes.js          # shim：定位 jar → 定位 java → spawn 透传（stdio inherit + 退出码）
+├── scripts/postinstall.js # 安装钩子：env > jarUrl 两级取值下载；任何失败都 exit 0 不阻断安装
+└── README.md
+```
+

package/bin/hermes.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hermes CLI 入口（npm bin shim）。
+ *
+ * 职责链：定位 hermes.jar（找不到则懒加载下载兜底）→ 定位 java → spawn 子进程
+ *
+ * 关键点：
+ *   - jar 懒下载：不依赖 postinstall（npm 新版本可能拦截安装脚本），首次运行发现无 jar
+ *     时现场下载（复用 scripts/download-jar.js 的重试逻辑），成功后才 spawn Java
+ *   - stdio:'inherit' 让 Java 进程直接接管终端（交互式对话、Ctrl+C 都正常）
+ *   - 透传退出码，保证脚本化调用（if errorlevel 1）语义不被破坏
+ */
+const { spawn, spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const PKG_ROOT = path.join(__dirname, '..');
+
+/**
+ * 按优先级定位 jar：
+ * 1. SKHERMES_JAR 环境变量（显式指定，开发/多版本共存用）
+ * 2. 包内 jar/hermes.jar（捆绑发布 或 postinstall 从 Release 下载的）
+ * 3. ~/.hermes/hermes.jar（兼容 install-hermes.ps1 的老安装位置）
+ */
+function resolveJar() {
+  const candidates = [
+    process.env.SKHERMES_JAR,
+    path.join(PKG_ROOT, 'jar', 'hermes.jar'),
+    path.join(os.homedir(), '.hermes', 'hermes.jar'),
+  ];
+  for (const c of candidates) {
+    // 加体积校验（>1MB）：排除之前下载中断遗留的空文件/半截 jar，避免把坏文件当好文件用
+    if (c && fs.existsSync(c) && fs.statSync(c).size > 1024 * 1024) return c;
+  }
+  return null;
+}
+
+/** 定位 java：JAVA_HOME 优先（版本可控），否则交给 PATH。 */
+function findJava() {
+  if (process.env.JAVA_HOME) {
+    const exe = process.platform === 'win32' ? 'java.exe' : 'java';
+    const cand = path.join(process.env.JAVA_HOME, 'bin', exe);
+    if (fs.existsSync(cand)) return cand;
+  }
+  return 'java';
+}
+
+async function main() {
+  // 找 jar：找不到 → 懒加载下载兜底（不依赖 postinstall，这是可靠性的核心）
+  let jar = resolveJar();
+  if (!jar) {
+    const { ensureJar, resolveJarUrl } = require('../scripts/download-jar');
+    const dest = path.join(PKG_ROOT, 'jar', 'hermes.jar');
+    const ok = await ensureJar({ dest, url: resolveJarUrl(PKG_ROOT), maxAttempts: 5 });
+    if (!ok) {
+      console.error('[sk-hermes] 无法获取 hermes.jar，退出。请按上方提示手动提供 jar 后重试。');
+      process.exit(1);
+    }
+    jar = dest;
+  }
+
+  // Windows 控制台默认代码页是 GBK，Java 侧用 -Dstdout.encoding=UTF-8 写出 UTF-8 字节，
+  // 必须把控制台代码页也切到 UTF-8，两边编码对齐才不乱码（与 hermes.cmd 的 chcp 65001 同理）。
+  // chcp 是 chcp.com 这个真实可执行文件，spawnSync 不带 shell 时必须写全名。
+  if (process.platform === 'win32') {
+    try {
+      spawnSync('chcp.com', ['65001'], { stdio: 'ignore' });
+    } catch (_) {
+      /* best-effort：失败也不阻断启动 */
+    }
+  }
+
+  const child = spawn(
+    findJava(),
+    [
+      '-Dfile.encoding=UTF-8',
+      '-Dstdout.encoding=UTF-8',
+      '-Dstderr.encoding=UTF-8',
+      '-jar', jar,
+      ...process.argv.slice(2),
+    ],
+    { stdio: 'inherit' }
+  );
+
+  // POSIX 下把信号转发给子进程（Windows 控制台 Ctrl+C 由系统直接发给整个进程组，无需转发）
+  const forward = (sig) => { try { child.kill(sig); } catch (_) { /* 已退出 */ } };
+  process.on('SIGINT', forward);
+  process.on('SIGTERM', forward);
+
+  child.on('error', (err) => {
+    console.error(`[sk-hermes] 无法启动 java（${err.message}）。`);
+    console.error('请确认已安装 JDK 21+ 且 java 在 PATH 中，或设置 JAVA_HOME 环境变量。');
+    process.exit(1);
+  });
+
+  // 透传退出码：CLI 的退出码是与调用方的返回值契约，不能丢
+  child.on('close', (code, signal) => {
+    process.exit(signal ? 1 : (code === null ? 1 : code));
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "sk-hermes-cli",
+  "version": "1.0.0",
+  "description": "sk-Hermes：可自我进化的 AI Agent 命令行工具（Java fat-jar 的 npm 分发壳）",
+  "keywords": [
+    "cli",
+    "ai",
+    "agent",
+    "llm",
+    "chatbot",
+    "rag",
+    "java"
+  ],
+  "license": "MIT",
+  "bin": {
+    "hermes": "bin/hermes.js",
+    "sk-hermes": "bin/hermes.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "hermes": {
+    "jarUrl": "https://github.com/chen-2024-cn/Hermes-agent-Java-/releases/download/v1.0.0/hermes.jar"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/download-jar.js

@@ -0,0 +1,133 @@
+'use strict';
+/**
+ * 可复用的 hermes.jar 下载器。
+ *
+ * 被两处调用：
+ *   - scripts/postinstall.js：安装时 best-effort 预下载（可能被 npm allow-scripts 策略拦截）
+ *   - bin/hermes.js：首次运行时懒加载兜底（不依赖任何安装脚本，最可靠）
+ *
+ * 设计要点（针对不稳定网络，尤其国内访问 GitHub Release CDN 易被 Connection reset）：
+ *   - 整包重试 + 递增退避（重试窗口内大概率能撞上一次通畅）
+ *   - 重定向跟随（GitHub download 链接 302 到 CDN），手动解析 Location 不依赖 new URL
+ *   - .part 临时文件 + 原子 rename，避免半截文件被后续启动误判为有效 jar
+ *   - 单请求超时保护，防止连接假死挂起
+ */
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+
+const MAX_REDIRECTS = 5;
+const REQ_TIMEOUT_MS = 60000;
+
+/** 解析下载地址：环境变量 SKHERMES_JAR_URL 优先，其次 package.json 内置 hermes.jarUrl。 */
+function resolveJarUrl(pkgRoot) {
+  let pkgJson = {};
+  try {
+    pkgJson = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+  } catch (_) {
+    /* package.json 读失败则仅依赖环境变量 */
+  }
+  return process.env.SKHERMES_JAR_URL || (pkgJson.hermes && pkgJson.hermes.jarUrl) || '';
+}
+
+/**
+ * 解析重定向 Location：支持绝对 URL 与相对路径，不依赖 new URL（避免环境差异与变量遮蔽）。
+ */
+function resolveRedirect(base, location) {
+  if (/^https?:\/\//i.test(location)) return location;
+  const m = base.match(/^(https?:)\/\/([^/]+)(\/.*)?$/i);
+  if (!m) return location;
+  if (location.startsWith('/')) return `${m[1]}//${m[2]}${location}`;
+  const dir = (m[3] || '/').replace(/[^/]*$/, '');
+  return `${m[1]}//${m[2]}${dir}${location}`;
+}
+
+/** 单次下载尝试（含重定向跟随）。resolve()=成功；reject(err)=可重试错误。 */
+function downloadOnce(url, dest, redirects) {
+  return new Promise((resolve, reject) => {
+    const mod = url.startsWith('https') ? https : http;
+    const req = mod.get(url, { headers: { 'User-Agent': 'sk-hermes-npm' } }, (res) => {
+      const code = res.statusCode || 0;
+      if (code >= 300 && code < 400 && res.headers.location) {
+        res.resume();
+        if (redirects >= MAX_REDIRECTS) return reject(new Error('重定向次数过多'));
+        return downloadOnce(resolveRedirect(url, res.headers.location), dest, redirects + 1)
+          .then(resolve, reject);
+      }
+      if (code !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${code}（${url}）`));
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const tmp = dest + '.part';
+      const file = fs.createWriteStream(tmp);
+      res.pipe(file);
+      file.on('finish', () => {
+        file.close(() => {
+          try {
+            fs.renameSync(tmp, dest); // 原子替换，避免半截文件
+            resolve();
+          } catch (e) {
+            reject(e);
+          }
+        });
+      });
+      res.on('error', reject); // 服务端中途断流也走重试
+    });
+    req.setTimeout(REQ_TIMEOUT_MS, () => req.destroy(new Error(`请求超时（${REQ_TIMEOUT_MS}ms 无响应）`)));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * 确保 dest 处存在 jar：已存在（>1MB）则跳过；否则带重试下载。
+ *
+ * @param {object} opts
+ * @param {string} opts.dest     目标 jar 路径
+ * @param {string} opts.url      下载地址
+ * @param {number} [opts.maxAttempts=5] 最大重试次数
+ * @param {(msg:string)=>void} [opts.log] 日志输出（默认写 stdout）
+ * @returns {Promise<boolean>} 是否最终拿到了 jar（true=可用；false=下载失败，调用方应给出人话提示）
+ */
+async function ensureJar({ dest, url, maxAttempts = 5, log = (m) => process.stdout.write(`[sk-hermes] ${m}\n`) }) {
+  // 已有可用 jar（>1MB，排除空文件/半截文件）→ 直接用
+  if (fs.existsSync(dest)) {
+    try {
+      if (fs.statSync(dest).size > 1024 * 1024) return true;
+    } catch (_) {
+      /* 忽略统计失败，继续走下载 */
+    }
+  }
+  if (!url) {
+    log('未找到 jar 下载地址（package.json 的 hermes.jarUrl 与环境变量 SKHERMES_JAR_URL 均未设置）。');
+    log('请设 SKHERMES_JAR 指向你本地构建的 jar，或将 jar 放到 ' + dest);
+    return false;
+  }
+
+  log(`正在下载 hermes.jar（约 45 MB，最多重试 ${maxAttempts} 次）...`);
+  log(`来源: ${url}`);
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      await downloadOnce(url, dest, 0);
+      const mb = (fs.statSync(dest).size / 1024 / 1024).toFixed(1);
+      log(`下载完成: ${dest}（${mb} MB）`);
+      return true;
+    } catch (err) {
+      log(`第 ${attempt}/${maxAttempts} 次下载失败：${err.message}`);
+      try { fs.unlinkSync(dest + '.part'); } catch (_) { /* 忽略 */ }
+      if (attempt < maxAttempts) {
+        const wait = attempt * 3000; // 3s→6s→9s→12s 递增退避
+        log(`${wait / 1000}s 后重试...`);
+        await new Promise((r) => setTimeout(r, wait));
+      }
+    }
+  }
+  log('自动下载失败（可能是网络无法稳定访问 GitHub CDN）。可手动解决：');
+  log(`  用浏览器/下载工具获取 ${url}`);
+  log(`  放到 ${dest}`);
+  log(`  或设置环境变量 SKHERMES_JAR 指向该 jar 文件。`);
+  return false;
+}
+
+module.exports = { ensureJar, resolveJarUrl, downloadOnce, resolveRedirect };

package/scripts/postinstall.js

@@ -0,0 +1,31 @@
+'use strict';
+/**
+ * postinstall 钩子：安装后 best-effort 预下载 hermes.jar。
+ *
+ * 定位是「加分项」而非「必需项」——下载逻辑同时内置于 bin/hermes.js（首次运行懒加载兜底），
+ * 因此即使本脚本被 npm 的 allow-scripts / ignore-scripts 策略拦截（npm 新版本默认可能拦），
+ * 或下载因网络失败，用户敲 hermes 时依然会自动补下载，不影响可用性。
+ *
+ * 铁律：任何情况下都 exit 0，绝不阻断 npm install。
+ * 真正的下载实现见 ./download-jar.js（bin 与此处共用同一份，避免逻辑漂移）。
+ */
+const path = require('path');
+const { ensureJar, resolveJarUrl } = require('./download-jar');
+
+process.on('uncaughtException', (err) => {
+  process.stdout.write(`[sk-hermes] postinstall 异常（已忽略，不阻断安装）：${err && err.message}\n`);
+  process.exit(0);
+});
+
+const PKG_ROOT = path.join(__dirname, '..');
+
+(async () => {
+  // 安装阶段少试几次（maxAttempts=3）；失败无所谓，首次运行 hermes 时还会带 5 次重试再下
+  await ensureJar({
+    dest: path.join(PKG_ROOT, 'jar', 'hermes.jar'),
+    url: resolveJarUrl(PKG_ROOT),
+    maxAttempts: 3,
+  });
+  process.exit(0);
+})();
+