@code2rich/jpage 1.5.0 → 1.5.2

package/.github/workflows/ci.yml

@@ -28,7 +28,9 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+          # 不启用 cache: 'npm'：setup-node 恢复缓存时 _cacache/tmp 残留与
+          # npm ci 冲突（EEXIST errno -17），Node 20 矩阵稳定复现。
+          # npm ci 本身够快（~10s），缓存收益不值得这个 bug。
 
       - name: Install dependencies
         run: npm ci

package/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+# npm 自动发版：打 v* tag 触发，跑测试 + 校验版本号一致 + npm publish。
+#
+# 用法（本地）：
+#   1. 改 package.json 的 version（如 1.5.1）
+#   2. commit + push 到 main
+#   3. git tag v1.5.1 && git push origin v1.5.1
+#   4. 本 workflow 自动跑：test → 校验 tag==version → npm publish
+#
+# 前置（仓库设置，一次性）：
+#   GitHub 仓库 Settings → Secrets and variables → Actions → New repository secret
+#   Name: NPM_TOKEN
+#   Value: 在 npm 生成的 granular access token（@code2rich scope, Read and write）
+#   生成地址：https://www.npmjs.com/settings/code2richnpm/tokens/granular-access-tokens/new
+#
+# 版本一致性：tag 名（去 v 前缀）必须等于 package.json 的 version，否则失败。
+# 这样能防止「tag 标 v1.6.0 但 package.json 还写着 1.5.0」这类手滑。
+
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+# 同一 tag 不要并发跑（理论上 git push tag 是原子的，但保险起见）
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    # 同时跑测试矩阵确认绿（轻量：只 Node 20，CI workflow 已覆盖 20+22）
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          # 不启用 cache: 'npm'：见 ci.yml 同款注释（EEXIST bug）
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Run tests (unit + integration)
+        run: npm test
+
+      - name: Build frontend bundle
+        run: npm run build
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(node -p "require('./package.json').version")
+          echo "tag (去 v 前缀): $TAG"
+          echo "package.json version: $PKG"
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::tag ($TAG) 与 package.json version ($PKG) 不一致"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          # setup-node 配置的 registry 会读这个环境变量做鉴权
+          # publishConfig.access=public 已设，scoped 包公开发布无需 --access
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Release ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          if [ "${{ job.status }}" = "success" ]; then
+            echo "✅ 已发布 \`$(node -p "require('./package.json').name")@$(node -p "require('./package.json').version")\`" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "安装：\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+            echo "npm install -g $(node -p "require('./package.json').name")" >> $GITHUB_STEP_SUMMARY
+            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "❌ 发布失败，查看上面日志" >> $GITHUB_STEP_SUMMARY
+          fi

package/CLAUDE.md

@@ -133,7 +133,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - `GET /api/skills` — 列出已安装的 skill 包（需登录）
 - `GET /api/skills/:name` — skill 详情（含 SKILL.md 内容、文件列表、INSTALL.md 渲染）
 - `GET /api/skills/:name/download` — ZIP 下载整个 skill 目录
-- `GET /api/mcp/config` — 返回 MCP 连接配置（URL、Token 列表、JSON 配置片段）
+- `GET /api/mcp/config` — 返回 MCP 连接配置（URL、Token 列表、多客户端 mcpServers JSON 片段；仅 MCP 客户端）
+- `GET /api/cli/guide` — 返回 `jpage` CLI 用法指南（baseUrl、渲染后的 guideHtml、纯文本 guideText）；CLI 与 MCP 是并列的两个客户端入口，各自独立端点
 
 **Skills registry** — `skills-registry.js` 自动发现 `skills/*/SKILL.md`，解析 YAML frontmatter（`name`, `description`, `version`, `author`）。Web UI 首页展示 Skills 区块，管理员可查看详情（弹窗）和下载 ZIP。ZIP 包与磁盘目录结构一致，可直接解压到 `~/.claude/skills/`。
 
@@ -168,6 +169,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **大 body 端点专用解析** — 全局 `express.json` 限 1MB；`upload-json` / `upload-zip-base64` / `overwrite-json` 用 `largeJson`（50MB）。新增大 body 端点时挂 `largeJson`。
 - **静态资源长缓存** — `express.static` 统一带 `STATIC_OPTS`（30d + immutable）。前端 CSS/JS 引用带 `?v=x.y.z`，改资源后务必 bump 版本号以失效缓存。
 - **MCP 进程内分发** — MCP tool 不再走 `fetch('http://127.0.0.1:port/...')` 自调用，改用 `lib/dispatch.js` 的 `createDispatcher(app, {token})` 直接调 `app.handle()`。新增 MCP tool 时用传入的 `api` 对象（`api.get/post/put/del`），接口与 fetch 版一致；鉴权靠 `Authorization: Bearer <token>` 头走 `requireAuth`，行为与 HTTP 完全相同（权限、限流、审计都生效）。
+- **CLI 与 MCP 双客户端入口必须同步** — `bin/commands/*.js`（CLI 命令）与 `mcp/tools-*.js`（MCP tool）是两个对等的客户端入口，都构建在同一套 REST API（`routes/`）之上。**新增或修改任一端的功能时，另一端必须同步实现对应能力**：CLI 加命令就同时给 MCP 加 tool，反之亦然，避免两边能力漂移。功能域与文件对应：文件管理 → `commands/{upload,ls,cat,url,mv,rm,star,tags}.js` ↔ `mcp/tools-files.js`；标签 → `commands/tags.js` ↔ `mcp/tools-tags.js`；版本 → `mcp/tools-versions.js`（CLI 待补）；分类 → `mcp/tools-categories.js`（CLI 待补）。
 - **模板预编译** — `loadTemplates()` 把每个模板经 `compileTemplate()` 编为函数存入 `templateCache`（静态 vendor URL 占位符在加载时一次替换，运行时仅 title/content/hljs_theme 三个 `split/join`）。`templateCache[name]` 是**函数**而非字符串，`applyTemplate(tplFn, ...)` 直接调用。
 - **marked.parse 同步** — 所有 `marked.parse(...)` 显式带 `async: false`（v12 默认同步，显式声明防止未来升级开启 async 返回 Promise 被当字符串拼接）。
 - **搜索 UNION 合并** — `/api/files/search` 用 `UNION` 合并 FTS 全文命中（带 `snippet`）与文件名 LIKE 命中（snippet 为 NULL），一次往返替代旧的两查询+内存去重，分页准确。注意 FTS5 的 `MATCH` 不能与普通列在 `LEFT JOIN + OR` 中混用（SQLite 报 "unable to use function MATCH"）。

package/README.md

@@ -6,8 +6,6 @@
 
 [English](README_EN.md) | 中文
 
-**[>>> 查看即页产品介绍 <<<](https://jpage.cn/)**
-
 **即页**是一个零配置的 HTML / Markdown 即时预览与分享工具。把写好的文档拖进来，立刻获得一个干净的在线页面——无需部署流程，无需服务器知识。特别适合 AI 生成内容的一键分享。
 
 ---
@@ -105,6 +103,32 @@ node test/mcp-harness.js 8858    # MCP 端点
 node test/perf-bench.js 8858     # 渲染/列表/缓存延迟基准
 ```
 
+### CLI 工具（npm 包已发布）
+
+即页随包提供 `jpage` 命令行工具，可通过 REST API 上传 / 列出 / 管理文件，对大文件和 ZIP 走 multipart 二进制流式上传（比 MCP 的 base64 进 token 流更快更省）：
+
+```bash
+npm install -g @code2rich/jpage
+jpage upload ./report.html --public --token <你的 token>
+jpage ls --kw 季度
+jpage cat 8
+jpage --help
+```
+
+`jpage` 与 MCP 是对称的两个客户端入口，都架在同一套 REST API 之上。详见 `jpage --help`。
+
+更新到最新版（不需 token）：
+
+```bash
+jpage update                  # 自更新到最新版
+jpage update --check          # 只查有没有新版本
+jpage update --registry https://registry.npmmirror.com   # 国内源
+```
+
+### 发版
+
+维护者发版指南（含 GitHub Actions 自动发版配置、token 轮换、故障排查）见 [`docs/RELEASING.md`](docs/RELEASING.md)。
+
 ## 鉴权与安全
 
 即页支持多用户体系。admin 可管理全部用户和文件，普通用户只能操作自己的文件和公开文件。

package/bin/commands/ls.js

@@ -1,9 +1,9 @@
 // ls 命令：列出文件。
 // 后端：GET /api/files（支持 page/limit/sort/order/keyword/category/tag）。
 
-const { formatSize, formatTime, out } = require('./_shared');
+const { formatSize, formatTime, shareUrl, out } = require('./_shared');
 
-async function run(client, args) {
+async function run(client, args, { base }) {
   const o = args.opts;
   const params = new URLSearchParams();
   if (o.page) params.set('page', o.page);
@@ -24,14 +24,17 @@ async function run(client, args) {
     return;
   }
 
-  // 对齐表格：id / 类型 / 公开 / 大小 / 更新时间 / 文件名 / 标签
+  // 对齐表格：id / 类型 / 公开 / 大小 / 更新时间 / 文件名 / 短链 / 标签
   for (const f of files) {
     const pub = f.is_public ? 'pub' : 'pri';
     const tags = (f.tags || []).map((t) => t.name).join(',');
     const bundle = f.is_bundle ? ' 📦' : '';
+    const url = shareUrl(base, f);
+    const short = url ? `  ${url}` : '';
     out(
       `#${f.id}  [${f.file_type || '?'} ${pub}]  ${formatSize(f.size).padEnd(7)}  ` +
         `${formatTime(f.updated_at)}  ${f.original_name}${bundle}` +
+        short +
         (tags ? `  {${tags}}` : '') +
         '\n'
     );

package/bin/commands/update.js

@@ -0,0 +1,74 @@
+// update 命令：把 jpage 自更新到最新版（npm 全局包）。
+//
+// 纯客户端操作：不调后端 API，不需 token（自更新与 jpage 服务端无关）。
+// 流程：npm view 查最新版本 → 与本地对比 → 有新版则 npm install -g 重装。
+//
+// 可注入 npmExec（形如 (args) => string）：测试时注入假执行器，避免真的跑 npm。
+// 默认走 child_process.execFileSync，与 build.js 既有风格一致。
+
+const { execFileSync } = require('child_process');
+const { out, err } = require('./_shared');
+
+const PKG_NAME = '@code2rich/jpage';
+const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+// 默认 npm 执行器：同步拿 stdout（trim 尾部换行）。
+function defaultNpmExec(args) {
+  return execFileSync(npmBin, args, {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim();
+}
+
+async function run(_client, args, ctx) {
+  const o = args.opts;
+  const exit = ctx.exit || ((c) => { process.exitCode = c; });
+  const npmExec = ctx.npmExec || defaultNpmExec;
+
+  // --registry 后面没给值时，args.js 会把它解析成 true。
+  if (o.registry === true) {
+    const e = new Error('用法：jpage update [--registry <url>] [--check]');
+    e.name = 'UsageError';
+    throw e;
+  }
+  const registryArgs = o.registry ? ['--registry', o.registry] : [];
+
+  const current = require('../../package.json').version;
+
+  // 查最新版本。
+  let latest;
+  try {
+    latest = (npmExec(['view', PKG_NAME, 'version', ...registryArgs]) || '').trim();
+  } catch (e) {
+    err(`✗ 查询最新版本失败：${e.message || e}\n`);
+    err('  检查网络连接，或用 --registry 指定可达的 npm 源。\n');
+    exit(1);
+    return;
+  }
+
+  if (latest === current) {
+    out(`已是最新版 ${current}\n`);
+    return;
+  }
+
+  out(`发现新版本 ${latest}（当前 ${current}），正在更新…\n`);
+
+  if (o.check) {
+    return; // 只查不更新
+  }
+
+  try {
+    npmExec(['install', '-g', `${PKG_NAME}@latest`, ...registryArgs]);
+  } catch (e) {
+    const detail = (e.stderr || e.message || e).toString().split('\n').slice(0, 3).join('\n');
+    err(`✗ 更新失败：\n${detail}\n`);
+    err('  常见原因：权限不足（试 sudo）、网络中断、registry 不可达。\n');
+    err('  也可手动执行：npm install -g ' + PKG_NAME + '@latest\n');
+    exit(1);
+    return;
+  }
+
+  out(`✓ 已更新到 ${latest}，重新运行 jpage 生效\n`);
+}
+
+module.exports = { run };

package/bin/jpage.js

@@ -31,8 +31,12 @@ const COMMANDS = {
   tags: () => require('./commands/tags'),
   skills: () => require('./commands/skills'),
   whoami: () => require('./commands/whoami'),
+  update: () => require('./commands/update'),
 };
 
+// 这些命令纯本地执行（不调后端 API），不强制要求 token。
+const NO_TOKEN = new Set(['update']);
+
 const HELP = `jpage —— 即页命令行
 
 用法：
@@ -51,6 +55,7 @@ const HELP = `jpage —— 即页命令行
   skills ls | get <名> | download <名> [--out 文件]
                                               列出 / 查看 / 下载 Skill
   whoami                                      校验 token 是否有效
+  update [--registry <url>] [--check]         自更新到最新版（不需 token）
 
 通用选项：
   --token <TOKEN>        鉴权 token（jp_ 用户 token 或 MCP_TOKEN）
@@ -108,7 +113,7 @@ async function run(argv, inject = {}) {
   }
 
   const { token, base } = resolveConfig(opts, inject.env, inject.cwd);
-  if (!token) {
+  if (!token && !NO_TOKEN.has(cmd)) {
     stderr.write(
       '未提供 token。用 --token <TOKEN>、JPAGE_TOKEN 环境变量、或 .env 的 MCP_TOKEN 设置。\n'
     );
@@ -117,7 +122,7 @@ async function run(argv, inject = {}) {
   }
 
   const client = createClient({ base, token, fetchImpl: inject.fetchImpl });
-  const ctx = { base, token, exit };
+  const ctx = { base, token, exit, npmExec: inject.npmExec };
   const mod = COMMANDS[cmd]();
 
   try {

package/docs/RELEASING.md

@@ -0,0 +1,209 @@
+# 发版指南
+
+> 维护者文档。记录如何把 `@code2rich/jpage` 发布到 npm，以及 GitHub Actions 自动发版的配置与一次性设置。
+
+## TL;DR
+
+```bash
+npm version patch          # 1.5.0 → 1.5.1（自动改 package.json + commit + 打 tag）
+git push origin main       # 推 commit
+git push origin v1.5.1     # 推 tag → 触发 GitHub Actions 自动发布
+```
+
+打完 tag 等 Actions 跑完（2-3 分钟），`npm view @code2rich/jpage version` 确认。
+
+---
+
+## 前置（一次性配置）
+
+### 1. 生成 npm granular access token
+
+专为 CI 用的 token，不要复用你本地的或之前的。
+
+1. 访问 `https://www.npmjs.com/settings/code2richnpm/tokens/granular-access-tokens/new`
+2. 按以下填：
+   - **Name**: `jpage-ci-publish`（或任意易识别的名字）
+   - **Expiration**: 建议 90 天（到期前轮换）
+   - **Packages and scopes**: `Only select packages and scopes` → 勾 `@code2rich`
+     - 包已存在时可选精确到 `@code2rich/jpage`，权限更小更安全
+   - **Permissions**: `Read and write`
+3. 生成后复制 `npm_xxxx...`（**只显示一次**）
+
+> granular token 在生成时已勾选 bypass 2FA，CI 发布无需 OTP。
+
+### 2. 把 token 存进 GitHub Secrets
+
+1. 访问 `https://github.com/code2rich/jpage/settings/secrets/actions`
+2. **New repository secret**
+   - Name: `NPM_TOKEN`
+   - Value: 上一步复制的 token
+3. Add secret
+
+token 从此只存在 GitHub Secrets，不出现在本地终端、代码、`.npmrc`。
+
+### 3.（强烈建议）给 npm 账号开 2FA
+
+访问 `https://www.npmjs.com/settings/code2richnpm/account/security` → 选 `auth-and-writes`。
+
+- 2FA 保护**账号登录态**（防账号被盗后乱改设置）
+- granular token 的 bypass 2FA 只针对**发布动作**，两者互补不冲突
+
+---
+
+## 发版流程
+
+### 常规发版（推荐：自动 CI）
+
+```bash
+# 1. 确认在 main 分支且工作区干净
+git checkout main
+git status
+
+# 2. 升版本号（npm version 会自动改 package.json + commit + 打 tag）
+npm version patch    # 1.5.0 → 1.5.1  修 bug
+# npm version minor  # 1.5.0 → 1.6.0  新功能
+# npm version major  # 1.5.0 → 2.0.0  破坏性变更
+
+# 3. 推送 commit 和 tag
+git push origin main
+git push origin v1.5.1
+
+# 4. 等 GitHub Actions 跑完
+#    进度：https://github.com/code2rich/jpage/actions
+#    成功后验证：
+npm view @code2rich/jpage version
+```
+
+**CI 会做什么**（见 `.github/workflows/release.yml`）：
+
+1. checkout 代码
+2. `npm ci`（用 lockfile 锁定的依赖）
+3. lint + test（全绿才继续）
+4. build 前端产物
+5. **校验 tag 名 == package.json version**（防手滑：tag 标 v1.6.0 但 package.json 还写 1.5.0 会失败）
+6. `npm publish`（用 `NPM_TOKEN` 鉴权）
+7. 在 Actions Summary 写发布结果
+
+### 手动发版（应急，CI 挂了时用）
+
+```bash
+# 1. 确认版本号已改、commit 已推
+npm version patch
+git push origin main
+git push origin v1.5.1
+
+# 2. 本地登录（首次需要）
+npm login
+
+# 3. 发布（账号开了 2FA 时需要 --otp）
+npm publish --otp=<authenticator 当前的 6 位>
+
+# 4. 验证
+npm view @code2rich/jpage version
+```
+
+> 手动发版后建议补打 tag（如果 `npm version` 已打就不用），保持「每个 npm 版本对应一个 git tag」。
+
+---
+
+## 版本号约定（语义化版本）
+
+| 改动类型 | 命令 | 例子 | 含义 |
+|---|---|---|---|
+| 修 bug、小优化 | `npm version patch` | 1.5.0 → 1.5.1 | 向后兼容的修复 |
+| 新功能 | `npm version minor` | 1.5.0 → 1.6.0 | 向后兼容的新能力 |
+| 破坏性变更 | `npm version major` | 1.5.0 → 2.0.0 | 不兼容旧版的改动 |
+
+> 重大变更应同步更新 `CHANGELOG`（如果有）或在 GitHub Release 写说明。
+
+---
+
+## 预发版（可选，beta/rc）
+
+npm 支持预发布版本号，如 `1.6.0-beta.1`：
+
+```bash
+npm version prerelease --preid=beta   # 1.5.0 → 1.6.0-beta.0
+git push origin main
+git push origin v1.6.0-beta.0
+
+# 用户安装 beta：npm install -g @code2rich/jpage@beta
+# 正式版：npm install -g @code2rich/jpage@latest（默认）
+```
+
+预发版默认不进 `latest` tag，用户不主动指定 `@beta` 不会装到。
+
+---
+
+## 回滚 / 撤回
+
+**npm 版本一旦发布，版本号永久占用，无法删除**（只能 deprecate）。
+
+### 标记弃用（deprecate）
+
+```bash
+# 弃用某个版本（用户安装时会看到警告）
+npm deprecate @code2rich/jpage@1.5.1 "有严重 bug，请用 1.5.2"
+```
+
+### 发布修复版本
+
+发一个新版本（如 `1.5.2`）修正问题，然后 deprecate 坏版本。**不要试图覆盖已发布的版本号**——npm 不允许重复发布同一版本。
+
+### 完全撤下包（72 小时内）
+
+```bash
+# 包发布 72 小时内可 unpublish 整个包（慎用，会破坏所有依赖者）
+# npm unpublish @code2rich/jpage --force
+```
+
+> 超过 72 小时无法 unpublish。一般用 deprecate + 发新版本代替。
+
+---
+
+## 故障排查
+
+### CI 发版失败
+
+| 错误 | 原因 | 处理 |
+|---|---|---|
+| `403 Forbidden - Two-factor authentication required` | `NPM_TOKEN` 是 session token 不是 granular token | 重新生成 granular token（bypass 2FA），更新 GitHub Secret |
+| `403 Forbidden - You do not have permission` | token 权限不含 `@code2rich` scope | 重新生成 token，Packages 勾 `@code2rich` |
+| `EPUBLISHCONFLICT - You cannot publish over` | 该版本号已发布过 | 升版本号再发，npm 不允许覆盖 |
+| `tag (x) 与 package.json version (y) 不一致` | tag 名和 package.json 对不上 | 确保 `npm version` 自动打 tag，或手动对齐 |
+| lint/test/build 失败 | 代码有问题 | 看 Actions 日志修，修完不用重打 tag（直接 push commit 到 main，tag 已存在不会重跑——需删 tag 重打） |
+
+**删 tag 重跑**（修完代码后）：
+
+```bash
+git tag -d v1.5.1                  # 删本地
+git push origin :refs/tags/v1.5.1  # 删远程
+# 重新打 tag（指向最新 commit）
+git tag v1.5.1
+git push origin v1.5.1
+```
+
+### `NPM_TOKEN` 过期 / 轮换
+
+1. npm 网站生成新 granular token
+2. 更新 GitHub Secret：`https://github.com/code2rich/jpage/settings/secrets/actions` → `NPM_TOKEN` → Update
+3. 下次发版自动用新 token
+
+---
+
+## 安全清单（每次发版前后自查）
+
+- [ ] 没有把 npm token / `.npmrc` 含明文 token 的文件 commit 到仓库
+- [ ] `.gitignore` 含 `.npmrc`（防误提交）
+- [ ] CI 的 `NPM_TOKEN` 是 granular token（最小权限），不是账号 session token
+- [ ] npm 账号开了 2FA（`auth-and-writes`）
+- [ ] 过期的 token 已在 npm 网站撤销
+
+---
+
+## 相关文件
+
+- `.github/workflows/release.yml` — 自动发版 workflow（tag 触发）
+- `.github/workflows/ci.yml` — CI 测试 workflow（push/PR 触发）
+- `package.json` 的 `publishConfig.access: "public"` — scoped 包公开发布（必须）
+- `package.json` 的 `bin`、`engines`、`version` — 发布元信息