@cloudglab/confluence-cli 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -2,17 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
-## 0.0.2 - 2026-06-16
+## 0.0.3 - 2026-06-16
 
 ### Fixed
 
-- `createSkillAddArgs` 默认向 `npx -y skills add <source> --yes` 追加 `--global`，让 `npx -y @cloudglab/confluence-cli@latest install` 把 skill 装到 user-level 全局目录（`vercel-labs/skills` 的 `-g, --global` 选项）。修复 `npx ... install` 在 npx 临时目录里跑完被清理、导致 agent 找不到 skill 的问题。
-- `tests/install.test.ts` 同步更新 3 处 `npx -y skills add` 期望参数为 `--global --yes`，覆盖默认安装、`--skill-source=npm` 与 `--skill-local-path` 三条路径。
+- 撤掉 0.0.2 在 `npx -y skills add` 命令里默认追加的 `--global`。`vercel-labs/skills` 在 agent 内运行时本身就走项目级（`cwd` 下对应 agent 的 skills 目录），与 npx 临时目录是否被回收无关；强制传 `--global` 会让不支持全局安装的 agent（如 `PromptScript`，见 `vercel-labs/skills` `src/installer.ts`）直接报 `does not support global skill installation`。
+- 新增 `--skill-global` opt-in 标记，用户明确需要 user-level 全局时通过 `confluence install --skill-global true` / `confluence update --skill-global true` 显式开启。`InstallOptions` 新增 `skillGlobal: boolean`（默认 `false`），CLI 工具层 schema 与 help 文本同步更新。
+- `runUninstallCommand` 链路行为不变（仍同时清理项目级与全局级残留），0.0.2 升级到 0.0.3 不会丢清理路径。
 
-### Notes
+### Tests
+
+- `tests/install.test.ts` 回退 3 处 `npx -y skills add` 期望参数为 `--yes`（默认项目级），新增 `--skill-global true` 用例验证 opt-in 路径会追加 `--global`。
+- `tests/cli.test.ts` / `tests/update-probe.test.ts` 硬编码版本号同步 0.0.2 → 0.0.3。
+
+## 0.0.2 - 2026-06-16（已撤回）
+
+> 0.0.2 在 `createSkillAddArgs` 里默认传 `--global`，对不支持全局的 agent 不可用，发布后已被 0.0.3 撤回。已通过 `npm deprecate` 标记，请直接升级到 0.0.3。
+
+### Reverted by 0.0.3
 
-- `runUninstallCommand` 链路已经通过 `createSkillRemoveArgs(true)` 覆盖全局 skill 清理，升级到 0.0.2 后 `confluence uninstall --confirm true` 会同时清理项目级与全局级残留，幂等。
-- 0.0.1 → 0.0.2 升级仅影响 `npx ... install` / `npx ... update` 触发的 skill 安装路径，已经在 0.0.1 装到项目级的用户可以重新执行 `npx -y @cloudglab/confluence-cli@latest install` 让 skill 迁回全局。
+- 撤掉 `createSkillAddArgs` 默认追加的 `--global`；改回 `--yes`（项目级）。
+- `runUninstallCommand` 链路保持兼容。
 
 ## 0.0.1 - 2026-06-15
 

package/README.md

@@ -32,7 +32,7 @@ confluence-reader list
 confluence-writer list
 ```
 
-> `install` / `update` 默认把 Confluence skill 装到 user-level 全局目录（`npx -y skills add ... --global --yes`），不会落到当前项目目录。卸载链路会同时清理项目级与全局级残留。
+> `install` / `update` 默认走 `vercel-labs/skills` 推荐的项目级安装（`cwd` 下 agent skills 目录，兼容所有 agent，包括不支持全局的 PromptScript）。需要 user-level 全局时显式传 `--skill-global`（仅当 agent 支持，如 Claude Code / Cursor / OpenCode）。`confluence uninstall --confirm true` 会同时清理项目级与全局级残留。
 
 卸载入口（默认仅打印卸载计划，真实执行需显式确认）：
 

package/dist/core/cli-output.js

@@ -126,15 +126,16 @@ export function getBuiltinCommandHelp(commandName) {
             "confluence install",
             "",
             "用法：",
-            "  confluence install [--skill-source local|git|npm] [--skill-local-path <path>] [--skip-config-check] [--cli-only] [--skill-only]",
+            "  confluence install [--skill-source local|git|npm] [--skill-local-path <path>] [--skill-global] [--skip-config-check] [--cli-only] [--skill-only]",
             "  npx -y @cloudglab/confluence-cli@latest install",
             "",
             "说明：",
-            "  安装或更新 CLI，并按来源安装 Confluence skill。",
+            "  安装或更新 CLI，并按来源安装 Confluence skill。默认走 vercel-labs/skills 推荐的项目级（cwd 下 agent skills 目录），兼容所有 agent；需要 user-level 全局时显式传 --skill-global（需 agent 支持）。",
             "",
             "参数：",
             "  --skill-source <local|git|npm> （可选）：skill 安装来源，默认 local。",
             "  --skill-local-path <string> （可选）：直接从本地目录安装 skill。",
+            "  --skill-global （可选）：将 skill 装到 user-level 全局目录；不支持的 agent（如 PromptScript）会失败。",
             "  --skip-config-check （可选）：安装后跳过 Confluence 配置校验。",
             "  --cli-only （可选）：只安装 CLI，不安装 skill。",
             "  --skill-only （可选）：只安装 skill，不安装 CLI。",
@@ -143,15 +144,16 @@ export function getBuiltinCommandHelp(commandName) {
             "confluence update",
             "",
             "用法：",
-            "  confluence update [--skill-source local|git|npm] [--skill-local-path <path>] [--skip-config-check] [--cli-only] [--skill-only]",
+            "  confluence update [--skill-source local|git|npm] [--skill-local-path <path>] [--skill-global] [--skip-config-check] [--cli-only] [--skill-only]",
             "  npx -y @cloudglab/confluence-cli@latest update",
             "",
             "说明：",
-            "  更新或重新安装 CLI，并按来源更新 Confluence skill。",
+            "  更新或重新安装 CLI，并按来源更新 Confluence skill。默认走项目级，--skill-global 同 install。",
             "",
             "参数：",
             "  --skill-source <local|git|npm> （可选）：skill 更新来源，默认 local。",
             "  --skill-local-path <string> （可选）：直接从本地目录更新 skill。",
+            "  --skill-global （可选）：将 skill 装到 user-level 全局目录；不支持的 agent 会失败。",
             "  --skip-config-check （可选）：更新后跳过 Confluence 配置校验。",
             "  --cli-only （可选）：只更新 CLI，不更新 skill。",
             "  --skill-only （可选）：只更新 skill，不更新 CLI。",

package/dist/install.js

@@ -55,6 +55,7 @@ function printSuccessGuide(action, status) {
 常用配置：
   confluence update                       更新 CLI 和 Skill
   confluence install --skip-config-check  仅安装，跳过配置校验
+  confluence install --skill-global       把 skill 装到 user-level 全局目录
   CONFLUENCE_DISABLE_WRITE=true           禁用真实写操作
 
 写操作提示：真实写入仍需显式传 confirm=true。
@@ -63,6 +64,7 @@ function printSuccessGuide(action, status) {
 function parseInstallOptions(args) {
     let skillSource = "local";
     let skillLocalPath;
+    let skillGlobal = false;
     let skipConfigCheck = false;
     let cliOnly = false;
     let skillOnly = false;
@@ -84,6 +86,12 @@ function parseInstallOptions(args) {
                 index += 1;
             continue;
         }
+        if (arg === "--skill-global" || arg.startsWith("--skill-global=")) {
+            const parsed = readBooleanFlag(args, index, "--skill-global");
+            skillGlobal = parsed.value;
+            index += parsed.consumedArgs;
+            continue;
+        }
         if (arg === "--skip-config-check" || arg.startsWith("--skip-config-check=")) {
             const parsed = readBooleanFlag(args, index, "--skip-config-check");
             skipConfigCheck = parsed.value;
@@ -107,7 +115,7 @@ function parseInstallOptions(args) {
     if (cliOnly && skillOnly) {
         throw new Error("--cli-only 和 --skill-only 不能同时使用");
     }
-    return { skillSource, skillLocalPath, skipConfigCheck, cliOnly, skillOnly };
+    return { skillSource, skillLocalPath, skillGlobal, skipConfigCheck, cliOnly, skillOnly };
 }
 function parseUninstallOptions(args) {
     let confirm = false;
@@ -158,11 +166,11 @@ function printUninstallPreview(options) {
 function shouldRemoveConfig(options) {
     return !options.keepConfig && !options.cliOnly && !options.skillOnly;
 }
-function createSkillAddArgs(source) {
-    // 默认装到全局（user-level）skill 目录，避免 `npx ... install` 在临时目录里
-    // 跑完被回收、导致 agent 找不到 skill。`--global` 与 `--yes` 配合 vercel-labs/skills
-    // 的 add 选项；卸载时通过 createSkillRemoveArgs(true) 同样走全局路径。
-    return ["-y", "skills", "add", source, "--global", "--yes"];
+function createSkillAddArgs(source, global = false) {
+    // 默认走 vercel-labs/skills 推荐的项目级（cwd 下 agent skills 目录），
+    // 兼容所有 agent（包括不支持 --global 的，如 PromptScript）。
+    // 用户明确需要 user-level 全局时再通过 --skill-global 显式开启。
+    return ["-y", "skills", "add", source, ...(global ? ["--global"] : []), "--yes"];
 }
 function createSkillRemoveArgs(global = false) {
     return ["-y", "skills", "remove", "confluence-cli", "--yes", ...(global ? ["--global"] : [])];
@@ -253,20 +261,20 @@ async function runNpxStepWithRetry(title, args) {
 }
 async function installSkill(action, options) {
     if (options.skillLocalPath) {
-        await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(path.resolve(options.skillLocalPath)));
+        await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(path.resolve(options.skillLocalPath), options.skillGlobal));
         return;
     }
     if (options.skillSource === "local") {
-        await installSkillFromInstalledPackage(action);
+        await installSkillFromInstalledPackage(action, options.skillGlobal);
         return;
     }
     if (options.skillSource === "git") {
-        await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(GIT_SKILL_SOURCE));
+        await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(GIT_SKILL_SOURCE, options.skillGlobal));
         return;
     }
-    await installSkillFromNpmPackage(action);
+    await installSkillFromNpmPackage(action, options.skillGlobal);
 }
-async function installSkillFromInstalledPackage(action) {
+async function installSkillFromInstalledPackage(action, skillGlobal) {
     const skillPath = await getInstalledPackageSkillPath();
     try {
         await access(skillPath);
@@ -274,7 +282,7 @@ async function installSkillFromInstalledPackage(action) {
     catch {
         throw new Error(`未找到已安装包内的 Confluence skill：${skillPath}。可重试 --skill-source npm 或 --skill-source git。`);
     }
-    await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(skillPath));
+    await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(skillPath, skillGlobal));
 }
 async function getInstalledPackageSkillPath() {
     const globalNodeModules = (await runCommandOutput("npm", ["root", "-g"])).trim();
@@ -282,7 +290,7 @@ async function getInstalledPackageSkillPath() {
         throw new Error("npm root -g 没有返回全局 node_modules 路径");
     return path.join(globalNodeModules, PACKAGE_NAME, "skills", "confluence-cli");
 }
-async function installSkillFromNpmPackage(action) {
+async function installSkillFromNpmPackage(action, skillGlobal) {
     const tempDir = await mkdtemp(path.join(os.tmpdir(), "confluence-cli-skill-"));
     try {
         const stdout = await runCommandOutput("npm", ["pack", `${PACKAGE_NAME}@latest`, "--pack-destination", tempDir, "--silent"]);
@@ -290,7 +298,7 @@ async function installSkillFromNpmPackage(action) {
         if (!tarballName)
             throw new Error("npm pack 没有返回包文件名");
         await runStep("解压 Confluence npm 包", "tar", ["-xzf", path.join(tempDir, tarballName), "-C", tempDir]);
-        await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(path.join(tempDir, "package")));
+        await runNpxStepWithRetry(`${action} Confluence skill`, createSkillAddArgs(path.join(tempDir, "package"), skillGlobal));
     }
     finally {
         await rm(tempDir, { recursive: true, force: true });

package/dist/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.2",
+  "version": "0.0.3",
   "commands": [
     "addComment",
     "addLabels",

package/dist/tools/install.js

@@ -4,6 +4,7 @@ import { jsonResult } from "../utils/result.js";
 const installSchema = z.object({
     "skill-source": z.enum(["local", "git", "npm"]).optional().default("local").describe("技能来源"),
     "skill-local-path": z.string().optional().describe("本地 skill 目录"),
+    "skill-global": z.boolean().optional().default(false).describe("将 skill 装到 user-level 全局目录（需 agent 支持）"),
     "skip-config-check": z.boolean().optional().default(false).describe("跳过配置校验"),
     "cli-only": z.boolean().optional().default(false).describe("只安装 CLI"),
     "skill-only": z.boolean().optional().default(false).describe("只安装 skill"),

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.2";
+export declare const VERSION = "0.0.3";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "0.0.2";
+export const VERSION = "0.0.3";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudglab/confluence-cli",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Confluence REST CLI for agents and local automation",
   "repository": {
     "type": "git",