@nggaigc/cli 0.1.44 → 0.1.47

package/README.md

@@ -1,6 +1,6 @@
 # @nggaigc/cli
 
-NGGAIGC Codex Skill 的一命令安装器。
+NGGAIGC Skill 的受信安装器。Codex 与 WorkBuddy 使用同一条安装命令，自动识别当前宿主。
 
 ```powershell
 npx --yes @nggaigc/cli@latest install
@@ -11,3 +11,31 @@ npx --yes @nggaigc/cli@latest install
 CLI 保留 macOS npm symlink 入口与 packed-TGZ launcher 检查，并验证随包的已签名 Plugin；实际版本以包内签名清单为准。支持 Windows x64/arm64 与 Apple 芯片 Mac arm64，使用本机 Node.js 22.x（22.13 起）或 24.x，不下载或内嵌 Node.js。Windows PowerShell 5.1 默认 `Restricted` 时，安装器仅为受信凭据辅助脚本的子进程指定 `RemoteSigned`；不修改系统或用户执行策略。安装成功但连接失败会明确分开报告，无需重装；由于系统 URL 处理器退出码不能证明浏览器窗口已显示，安装器会同时给出短期一次性手动授权链接。
 
 macOS arm64 辅助程序沿用已签名 Plugin 中通过完整性校验的字节；Intel Mac 不在支持范围内。实际公开版本和 `@latest` 状态以 npm registry 为准，Apple Silicon 真机验收需单独进行。
+
+## 统一安装入口（0.1.46 起）
+
+不带目录参数时，`install`、`start-skill`、`client` 使用同一套宿主识别：Codex 的当前会话标记，或 WorkBuddy 的会话标记／实际工作会话与专属应用标记组合。配置目录、已安装应用和通用终端变量本身不代表当前宿主；环境标记只是便利提示，不用于认证或授权。
+
+无法识别或同时命中两个宿主时，有交互终端可选择 Codex 或 WorkBuddy；非交互调用立即返回 `status: selection-required`、两项 `choices` 和退出码 3，不安装、不打开授权网页。当前 Agent 应让用户选择一次，再把 `--agent codex` 或 `--agent workbuddy` 加到原命令继续；`client` 的目标选项放在 `--` 分隔符之前，业务参数保持原样。安装结果始终返回真实 `skillsDirectory` 和 `skillPath`，连接失败也保留该位置，后续继续使用同一位置。
+
+本次仅 Codex 与 WorkBuddy 为自动识别支持范围；旧 `universal` 与自定义目录参数仍兼容，但不代表其他 Agent 已获验收。
+
+## 显式目标（0.1.45 起）
+
+下列目标参数与 `client` 桥要求 CLI 0.1.45 或更高版本。旧版本不支持新参数；`@latest` 的实际可用版本以 npm registry 与对应签名制品为准。
+
+```text
+npx --yes @nggaigc/cli@latest install --agent workbuddy
+npx --yes @nggaigc/cli@latest install --agent universal --no-login
+npx --yes @nggaigc/cli@latest install --skills-dir "/absolute/project/.codebuddy/skills" --no-login
+npx --yes @nggaigc/cli@latest start-skill skill.<id> [version] --skills-dir "/absolute/project/.codebuddy/skills"
+npx --yes @nggaigc/cli@latest client --skills-dir "/absolute/project/.codebuddy/skills" -- <原command> <原args>
+```
+
+`install`、`start-skill` 和 `client` 支持互斥的 `--agent codex|workbuddy|universal` 或 `--skills-dir <绝对目录>`。识别或选择 Codex 后使用 `CODEX_HOME/skills`，未设置时为 `~/.codex/skills`。WorkBuddy 优先使用实际进程提供的 `WORKBUDDY_CONFIG_DIR/skills`（其次 `CODEBUDDY_CONFIG_DIR/skills`），否则使用 `~/.workbuddy/skills`；在宿主外升级时，若现代目录没有根 Skill 而旧 `~/.codebuddy/skills` 已安装，则继续使用旧位置。不会删除或迁移旧安装。`--skills-dir` 始终精确指定项目级或其他现有安装。universal 使用 `~/.agents/skills`，不保证所有 Agent 自动识别。`--no-login` 仅跳过安装后的登录，不绕过签名、哈希、路径检查或后续鉴权。
+
+根 Skill 按实际读取的 `SKILL.md` 定位父目录及其上一级 `skillsDirectory`；后续升级与 `start-skill` 显式使用同一目录。准备回执增加 `skillsDirectory`、`rootLauncherPath`，保留 `preparedSkills`；宿主应显式读取返回的真实路径。独立包的原客户端调用使用回执的受信根启动器；`client` 是同目录根包验签桥，保留原命令／参数，不增加 API 专用业务分支。安装新包不证明当前宿主热加载，必要时开启新会话。
+
+本地技能包导入可能复制文件，需核导入后的实际路径和独立包同级关系。交互使用宿主可用的提问工具或当前聊天，交付使用宿主可用的媒体／附件能力；不依赖 Codex 专用工具。切换宿主继续复用当前系统用户的系统凭证库和任务历史，不迁移凭据、不要求重新粘贴密钥。资金、权限与未知结果同幂等键恢复规则不变。
+
+此功能不增加 Linux、Intel Mac 支持，也不代表已接入或认证 WorkBuddy 官方连接器市场；现有系统、Node.js 与正式发布门禁保持适用。

package/dist/agent-selection.js

@@ -0,0 +1,91 @@
+import { createInterface } from "node:readline/promises";
+import { resolveSkillLocation, } from "./skill-location.js";
+export const agentChoices = [
+    { agent: "codex", label: "Codex" },
+    { agent: "workbuddy", label: "WorkBuddy" },
+];
+export class AgentSelectionRequired extends Error {
+    reason;
+    code = "AGENT_SELECTION_REQUIRED";
+    constructor(reason) {
+        super("AGENT_SELECTION_REQUIRED");
+        this.reason = reason;
+    }
+}
+/** Configuration paths and installed applications are not caller identity. */
+export function detectCallingAgent(environment) {
+    const present = (value) => typeof value === "string" && value.trim().length > 0;
+    const codex = present(environment.CODEX_THREAD_ID);
+    // WorkBuddy's prewarmed runtime omits WORKBUDDY_CONVERSATION_ID. Its shell
+    // still has a CodeBuddy session AND WorkBuddy-specific application markers.
+    // A standalone CodeBuddy session is deliberately not treated as WorkBuddy.
+    const workbuddy = present(environment.WORKBUDDY_CONVERSATION_ID) ||
+        (present(environment.CODEBUDDY_SESSION_ID) &&
+            present(environment.WORKBUDDY_APP_VERSION) &&
+            present(environment.WORKBUDDY_APP_PATH));
+    if (codex && workbuddy)
+        return { reason: "conflicting" };
+    if (codex)
+        return { agent: "codex" };
+    if (workbuddy)
+        return { agent: "workbuddy" };
+    return { reason: "unknown" };
+}
+async function chooseInTerminal() {
+    const terminal = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    const controller = new AbortController();
+    const cancel = () => controller.abort();
+    terminal.once("SIGINT", cancel);
+    terminal.once("close", cancel);
+    try {
+        const answer = (await terminal.question("请选择使用 NGGAIGC 的 AI 助手：1. Codex  2. WorkBuddy\n输入 1 或 2：", { signal: controller.signal }))
+            .trim()
+            .toLowerCase();
+        if (answer === "1" || answer === "codex")
+            return "codex";
+        if (answer === "2" || answer === "workbuddy")
+            return "workbuddy";
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        terminal.off("SIGINT", cancel);
+        terminal.off("close", cancel);
+        terminal.close();
+    }
+}
+/** Resolve before any installation, browser authorization or client request. */
+export async function selectCommandLocation(options, runtime = {}) {
+    const environment = runtime.environment ?? process.env;
+    if (options.agent !== undefined ||
+        options.skillsDirectory !== undefined ||
+        options.codexHome !== undefined) {
+        resolveSkillLocation(options, environment);
+        return options;
+    }
+    const detected = detectCallingAgent(environment);
+    if ("agent" in detected)
+        return { ...options, agent: detected.agent };
+    const choose = runtime.choose ??
+        (process.stdin.isTTY && process.stderr.isTTY
+            ? chooseInTerminal
+            : undefined);
+    const agent = await choose?.();
+    if (agent === "codex" || agent === "workbuddy")
+        return { ...options, agent };
+    throw new AgentSelectionRequired(detected.reason);
+}
+export function selectionRequiredResult(error) {
+    return {
+        status: "selection-required",
+        error: { code: error.code, reason: error.reason },
+        message: "请选择当前使用的 AI 助手，然后在原命令中添加 --agent codex 或 --agent workbuddy 继续；client 命令的选项须放在 -- 分隔符之前。",
+        choices: agentChoices,
+        nextAction: "select-agent-and-retry",
+    };
+}

package/dist/bundle.js

@@ -47,7 +47,7 @@ export async function verifyBundle(input) {
             !exactKeys(manifestValue, manifestKeys) ||
             manifestValue.schemaVersion !== "nggaigc-plugin-package/v1" ||
             manifestValue.artifactId !== "plugin.nggaigc" ||
-            manifestValue.version !== "1.1.43" ||
+            manifestValue.version !== "1.1.45" ||
             manifestValue.artifactPath !==
                 `packages/plugins/nggaigc-plugin-${manifestValue.version}.zip` ||
             typeof manifestValue.sourceCommit !== "string" ||

package/dist/errors.js

@@ -1,9 +1,57 @@
+const localCauseCodes = new Set([
+    "EPERM",
+    "EACCES",
+    "ENOENT",
+    "EAGAIN",
+    "EMFILE",
+    "ENFILE",
+    "ENOMEM",
+    "EINVAL",
+    "ERR_ACCESS_DENIED",
+    "ERR_MODULE_NOT_FOUND",
+    "SETUP_REQUIRED",
+    "CREDENTIAL_FRAME_INVALID",
+    "CREDENTIAL_STORE_FAILED",
+    "INVALID_INPUT",
+    "CREDENTIAL_CHANGED",
+    "ALREADY_CONFIGURED",
+    "CREDENTIAL_STORE_UNAVAILABLE",
+    "CREDENTIAL_HELPER_START_FAILED",
+    "CREDENTIAL_HELPER_FAILED",
+    "DISTRIBUTION_INVALID",
+    "LOCAL_SESSION_FAILED",
+    "LOCAL_SESSION_TIMEOUT",
+    "POWERSHELL_EXECUTION_POLICY_BLOCKED",
+    "RUNTIME_UNSUPPORTED",
+    "UNKNOWN",
+]);
+export function safeConnectionDiagnostics(value) {
+    if (value === null || typeof value !== "object" || !("stage" in value))
+        return undefined;
+    const stage = value.stage;
+    if (stage !== "helper_start" && stage !== "credential_verification")
+        return undefined;
+    const cause = "causeCode" in value ? value.causeCode : undefined;
+    return {
+        stage,
+        causeCode: typeof cause === "string" && localCauseCodes.has(cause)
+            ? cause
+            : "UNKNOWN",
+    };
+}
 export class CliError extends Error {
     code;
-    constructor(code) {
+    stage;
+    causeCode;
+    constructor(code, diagnostics) {
         super(code);
         this.code = code;
         this.name = "CliError";
+        const safe = safeConnectionDiagnostics(diagnostics);
+        if (safe) {
+            this.stage = safe.stage;
+            this.causeCode = safe.causeCode;
+        }
     }
 }
 export function fixedErrorCode(error) {

package/dist/independent-skill.js

@@ -1,6 +1,7 @@
 import { createHash, createPublicKey, randomUUID, verify } from "node:crypto";
-import { open, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { open, lstat, mkdir, readFile, readdir, realpath, rename, rm, writeFile, } from "node:fs/promises";
 import path from "node:path";
+import { resolveSkillLocation, stateDirectoryForSkills, } from "./skill-location.js";
 const ID = /^skill\.[a-z0-9][a-z0-9.-]{0,79}$/;
 const VERSION = /^\d+\.\d+\.\d+$/;
 const DIGEST = /^[a-f0-9]{64}$/;
@@ -17,6 +18,33 @@ export class IndependentSkillError extends Error {
 function fail(code) {
     throw new IndependentSkillError(code);
 }
+async function independentLocation(options, create = false) {
+    // Missing programmatic arguments must not select the user's real home.
+    if (options.codexHome === undefined &&
+        options.skillsDirectory === undefined &&
+        options.agent === undefined)
+        fail("INSTALL_PATH_UNSAFE");
+    try {
+        const selected = resolveSkillLocation(options).skillsDirectory;
+        if (await hasLinkedPathComponent(selected, create))
+            fail("INSTALL_PATH_UNSAFE");
+        if (create)
+            await mkdir(selected, { recursive: true });
+        // One physical target must use one journal, including case aliases on
+        // case-insensitive disks. Check links before resolving the actual casing.
+        const skillsDirectory = await realpath(selected);
+        const legacyDirectory = await realpath(path.join(path.dirname(skillsDirectory), "skills")).catch(() => null);
+        return {
+            skillsDirectory,
+            stateDirectory: legacyDirectory === skillsDirectory
+                ? path.join(path.dirname(skillsDirectory), ".nggaigc-managed")
+                : stateDirectoryForSkills(skillsDirectory),
+        };
+    }
+    catch {
+        return fail("INSTALL_PATH_UNSAFE");
+    }
+}
 async function hasLinkedPathComponent(value, allowMissing = false) {
     const absolute = path.resolve(value);
     const root = path.parse(absolute).root;
@@ -795,10 +823,7 @@ async function acquireInstallLock(lock) {
 }
 export async function prepareIndependentSkill(options) {
     const ordered = resolve(options.index, options.skillId, options.skillVersion, options.rootSkillVersion, options.platformVersion);
-    if (!path.isAbsolute(options.codexHome))
-        fail("INSTALL_PATH_UNSAFE");
-    const skillsRoot = path.join(options.codexHome, "skills");
-    const stateRoot = path.join(options.codexHome, ".nggaigc-managed");
+    const { skillsDirectory: skillsRoot, stateDirectory: stateRoot } = await independentLocation(options, true);
     if (await hasLinkedPathComponent(skillsRoot, true).catch(() => true))
         fail("INSTALL_PATH_UNSAFE");
     if (await hasLinkedPathComponent(stateRoot, true).catch(() => true))
@@ -943,10 +968,7 @@ export async function rollbackIndependentSkill(options) {
         entry.version === options.installedVersion);
     if (!current)
         fail("ROLLBACK_UNAVAILABLE");
-    if (!path.isAbsolute(options.codexHome))
-        fail("INSTALL_PATH_UNSAFE");
-    const skillsRoot = path.join(options.codexHome, "skills");
-    const stateRoot = path.join(options.codexHome, ".nggaigc-managed");
+    const { skillsDirectory: skillsRoot, stateDirectory: stateRoot } = await independentLocation(options);
     if (await hasLinkedPathComponent(skillsRoot).catch(() => true))
         fail("INSTALL_PATH_UNSAFE");
     if (await hasLinkedPathComponent(stateRoot).catch(() => true))

package/dist/install.js

@@ -4,11 +4,12 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { extractBundle, verifyBundle, verifyExtractedBundle, verifyInstalledSkill, } from "./bundle.js";
-import { CliError, fixedErrorCode } from "./errors.js";
+import { CliError, fixedErrorCode, safeConnectionDiagnostics, } from "./errors.js";
+import { resolveSkillLocation, } from "./skill-location.js";
 function defaultBundle() {
     const vendor = fileURLToPath(new URL("../vendor/", import.meta.url));
     return {
-        archive: path.join(vendor, "nggaigc-plugin-1.1.43.zip"),
+        archive: path.join(vendor, "nggaigc-plugin-1.1.45.zip"),
         manifest: path.join(vendor, "manifest.json"),
         trust: path.join(vendor, "trusted-keys.json"),
     };
@@ -36,6 +37,47 @@ function installationError(error) {
         return new CliError("SKILL_PAIR_RECOVERY_REQUIRED");
     return new CliError("INSTALLATION_FAILED");
 }
+function connectionError(error, fallback) {
+    const code = fixedErrorCode(error);
+    const localCodes = [
+        "CREDENTIAL_HELPER_START_FAILED",
+        "CREDENTIAL_VERIFICATION_FAILED",
+        "CREDENTIAL_STORE_FAILED",
+        "CREDENTIAL_STORE_UNAVAILABLE",
+        "CREDENTIAL_FRAME_INVALID",
+        "CREDENTIAL_HELPER_FAILED",
+        "DISTRIBUTION_INVALID",
+        "LOCAL_SESSION_FAILED",
+        "LOCAL_SESSION_TIMEOUT",
+        "POWERSHELL_EXECUTION_POLICY_BLOCKED",
+        "RUNTIME_UNSUPPORTED",
+        "UNSUPPORTED_PLATFORM",
+        "BROWSER_OPEN_FAILED",
+    ];
+    if (localCodes.includes(code))
+        return new CliError(code, error);
+    // Older signed launchers can throw a synchronous OS spawn error before
+    // they can return a protected error envelope. Keep only this closed cause.
+    if (error !== null &&
+        typeof error === "object" &&
+        "syscall" in error &&
+        typeof error.syscall === "string" &&
+        /^spawn(?: |$)/.test(error.syscall)) {
+        return new CliError("CREDENTIAL_HELPER_START_FAILED", {
+            stage: "helper_start",
+            causeCode: code,
+        });
+    }
+    if (fallback === "BROWSER_AUTHORIZATION_FAILED" &&
+        [
+            "AUTHORIZATION_REJECTED",
+            "AUTHORIZATION_CANCELLED",
+            "ACTIVATION_REJECTED",
+            "ACTIVATION_INPUT_INVALID",
+        ].includes(code ?? ""))
+        return new CliError(fallback);
+    return new CliError("CONNECTION_VERIFICATION_FAILED");
+}
 async function installedVersion(target) {
     try {
         const marker = JSON.parse(await readFile(path.join(target, ".nggaigc-install.json"), "utf8"));
@@ -59,11 +101,11 @@ async function installedVersion(target) {
         return undefined;
     }
 }
-async function installSkill(installer, source, profile, codexHome, expectedVersion, bundleFiles) {
-    const target = path.join(codexHome, "skills", "nggaigc");
+async function installSkill(installer, source, profile, skillsDirectory, expectedVersion, bundleFiles) {
+    const target = path.join(skillsDirectory, "nggaigc");
     try {
         const result = await installer.main(["install", "--profile", profile], {
-            codexHome,
+            skillsDirectory,
             source,
         });
         if (result.status !== "installed" || result.version !== expectedVersion)
@@ -84,7 +126,7 @@ async function installSkill(installer, source, profile, codexHome, expectedVersi
     }
     try {
         const result = await installer.main(["update", "--profile", profile], {
-            codexHome,
+            skillsDirectory,
             source,
         });
         if (result.status !== "updated" || result.version !== expectedVersion)
@@ -115,10 +157,8 @@ async function connect(launcher, options, report, probe) {
     catch (error) {
         if (!probe && fixedErrorCode(error) === "SETUP_REQUIRED")
             configured = false;
-        else if (fixedErrorCode(error) === "POWERSHELL_EXECUTION_POLICY_BLOCKED")
-            throw new CliError("POWERSHELL_EXECUTION_POLICY_BLOCKED");
         else
-            throw new CliError("CONNECTION_VERIFICATION_FAILED");
+            throw connectionError(error, "CONNECTION_VERIFICATION_FAILED");
     }
     if (!configured) {
         report("launching");
@@ -156,11 +196,7 @@ async function connect(launcher, options, report, probe) {
                 throw new Error();
         }
         catch (error) {
-            if (fixedErrorCode(error) === "BROWSER_OPEN_FAILED")
-                throw new CliError("BROWSER_OPEN_FAILED");
-            if (fixedErrorCode(error) === "POWERSHELL_EXECUTION_POLICY_BLOCKED")
-                throw new CliError("POWERSHELL_EXECUTION_POLICY_BLOCKED");
-            throw new CliError("BROWSER_AUTHORIZATION_FAILED");
+            throw connectionError(error, "BROWSER_AUTHORIZATION_FAILED");
         }
         finally {
             process.off("SIGINT", interrupt);
@@ -180,9 +216,7 @@ function assertDisposableRoot(value, expectedParent) {
 export async function runInstall(options = {}) {
     validateRuntime(options.platform ?? process.platform, options.architecture ?? process.arch);
     const profile = safeProfile(options.profile ?? os.homedir());
-    const codexHome = safeProfile(options.codexHome ??
-        (options.profile ? undefined : process.env.CODEX_HOME) ??
-        path.join(profile, ".codex"));
+    const { skillsDirectory } = resolveSkillLocation(options);
     const report = options.reporter ?? (() => undefined);
     report("verifying");
     const bundle = await verifyBundle(options.bundle ?? defaultBundle());
@@ -200,8 +234,10 @@ export async function runInstall(options = {}) {
         const installer = require(path.join(extracted, "installer", "install.cjs"));
         if (!installer || typeof installer.main !== "function")
             throw new CliError("INSTALLATION_FAILED");
-        const installation = await installSkill(installer, path.join(extracted, "skills", "nggaigc"), profile, codexHome, bundle.version, bundle.files);
-        const installedScripts = path.join(codexHome, "skills", "nggaigc", "scripts");
+        const installation = await installSkill(installer, path.join(extracted, "skills", "nggaigc"), profile, skillsDirectory, bundle.version, bundle.files);
+        const installedScripts = path.join(skillsDirectory, "nggaigc", "scripts");
+        if (options.connect === false)
+            return { status: "installed", installation, version: bundle.version };
         const launcher = require(path.join(installedScripts, "launch-ngg-client.cjs"));
         if (!launcher ||
             typeof launcher.main !== "function" ||
@@ -214,11 +250,13 @@ export async function runInstall(options = {}) {
         catch (error) {
             if (!(error instanceof CliError))
                 throw error;
+            const diagnostics = safeConnectionDiagnostics(error);
             return {
                 status: "installed-unconnected",
                 installation,
                 version: bundle.version,
                 connectionError: error.code,
+                ...(diagnostics ? { connectionDiagnostics: diagnostics } : {}),
             };
         }
     }

package/dist/main.js

@@ -1,6 +1,9 @@
-import { CliError, fixedErrorCode } from "./errors.js";
+import path from "node:path";
+import { CliError, fixedErrorCode, safeConnectionDiagnostics, } from "./errors.js";
 import { runInstall } from "./install.js";
-import { runSkillStartCommand, } from "./skill-command.js";
+import { runSkillStartCommand, runClientCommand, } from "./skill-command.js";
+import { parseSkillLocation, resolveSkillLocation } from "./skill-location.js";
+import { AgentSelectionRequired, selectCommandLocation, selectionRequiredResult, } from "./agent-selection.js";
 const messages = {
     authorizing: "浏览器已成功启动，请在 NGGAIGC 页面确认连接…",
     connected: "NGGAIGC Skill 已安装，设备连接验证成功。",
@@ -11,14 +14,23 @@ const messages = {
 };
 const errorMessages = {
     ARCHIVE_EXTRACTION_FAILED: "安装包无法安全解压，请稍后重试。",
-    BROWSER_AUTHORIZATION_FAILED: "网页授权未完成；请在新 Codex 任务中调用 NGGAIGC 继续连接，无需重装。",
-    BROWSER_OPEN_FAILED: "系统未能打开默认浏览器，也无法提供手动授权入口；请在新 Codex 任务中调用 NGGAIGC 重试连接，无需重装。",
-    CONNECTION_VERIFICATION_FAILED: "设备连接验证未完成；请在新 Codex 任务中检查连接状态，无需重装。",
+    BROWSER_AUTHORIZATION_FAILED: "网页授权未完成；请在当前 Agent 中调用 NGGAIGC 继续连接，无需重装。",
+    BROWSER_OPEN_FAILED: "系统未能打开默认浏览器，也无法提供手动授权入口；请在当前 Agent 中调用 NGGAIGC 重试连接，无需重装。",
+    CONNECTION_VERIFICATION_FAILED: "设备连接验证未完成；请在当前 Agent 中检查连接状态，无需重装。",
+    CREDENTIAL_HELPER_START_FAILED: "本地凭据助手未能启动；请先处理当前运行错误，不要重复网页授权或重装。安装器没有更改系统保护。",
+    CREDENTIAL_VERIFICATION_FAILED: "凭据写入后的本地验证未完成，已尝试安全清理本次凭据；请先处理原本地错误，不要重复网页授权或重装。",
+    CREDENTIAL_STORE_FAILED: "本地凭据保存未完成；请先检查本地存储错误，不要重复网页授权。",
+    CREDENTIAL_STORE_UNAVAILABLE: "本地凭据存储暂不可用；请先检查本地运行条件，不要重复网页授权。",
+    CREDENTIAL_FRAME_INVALID: "本地凭据数据未能通过校验；请先处理当前本地错误，不要重复网页授权。",
+    CREDENTIAL_HELPER_FAILED: "本地凭据助手未能完成操作；请先处理当前本地错误，不要重复网页授权。",
+    DISTRIBUTION_INVALID: "本地受信客户端文件无法通过校验；请先检查当前安装，不要重复网页授权或手工修改签名文件。",
+    LOCAL_SESSION_FAILED: "本地凭据会话未能完成；请先处理本地错误，不要重复网页授权。",
+    LOCAL_SESSION_TIMEOUT: "本地凭据会话超时；请先检查当前本地进程，不要重复网页授权。",
     POWERSHELL_EXECUTION_POLICY_BLOCKED: "Windows 脚本执行受到系统或组织策略限制，设备连接未完成。安装器没有更改执行策略。",
     INSTALLATION_FAILED: "本地安装未完成，请检查现有文件状态后重试。",
     SKILL_PAIR_UPGRADE_REQUIRED: "检测到无法安全配套迁移的本地 Seedream Skill，已停止升级。请保留旧 Skill 和任务文件并联系支持。",
     SKILL_PAIR_RECOVERY_REQUIRED: "检测到本地组合安装中断或目录变化，已停止自动操作。请保留相关目录和任务文件并联系支持。",
-    INVALID_INPUT: "命令格式无效。请使用 install，或 start-skill skill.<id> [version]。",
+    INVALID_INPUT: "命令格式无效。使用 --help 查看 install、start-skill 和 client 的目录选项。",
     PACKAGE_VERIFICATION_FAILED: "安装包签名或完整性验证失败，已停止安装。",
     RUNTIME_UNSUPPORTED: "请使用 Node.js 22.x（22.13 起）或 24.x 版本。",
     UNSUPPORTED_PLATFORM: "当前系统或架构尚未获得此签名安装包支持，请使用已支持的平台。",
@@ -26,24 +38,91 @@ const errorMessages = {
 export async function main(args, runtime = {}) {
     const output = runtime.output ?? ((line) => process.stdout.write(line));
     const errorOutput = runtime.error ?? ((line) => process.stderr.write(line));
-    if (args[0] === "start-skill" && (args.length === 2 || args.length === 3)) {
+    if (args.length === 1 && ["--help", "-h", "help"].includes(args[0])) {
+        output([
+            "NGGAIGC CLI",
+            "install [--agent codex|workbuddy|universal | --skills-dir <absolute-directory>] [--no-login]",
+            "start-skill skill.<id> [version] [--agent codex|workbuddy|universal | --skills-dir <absolute-directory>]",
+            "client [--agent codex|workbuddy|universal | --skills-dir <absolute-directory>] -- <command> [arguments]",
+            "Default: automatically detect Codex or WorkBuddy. If unknown or conflicting, select one; non-interactive calls return selection-required (exit 3).",
+            "Codex: existing CODEX_HOME is preserved, otherwise ~/.codex/skills. WorkBuddy: its runtime config directory/skills, otherwise ~/.workbuddy/skills; existing legacy ~/.codebuddy installs are reused. Explicit legacy universal/custom targets remain supported.",
+            "Use the same target for install and subsequent commands. --no-login installs verified files without opening a browser.",
+            "client examples: -- status, -- login, -- account-status, -- workflows, -- history, -- disconnect",
+            "",
+        ].join("\n"));
+        return 0;
+    }
+    if (args[0] === "client") {
+        const controller = new AbortController();
+        const interrupt = () => controller.abort();
+        try {
+            const separator = args.indexOf("--");
+            if (separator < 1 || separator === args.length - 1)
+                throw new CliError("INVALID_INPUT");
+            const { location, positional } = parseSkillLocation(args.slice(1, separator));
+            if (positional.length)
+                throw new CliError("INVALID_INPUT");
+            process.once("SIGINT", interrupt);
+            const selectedLocation = await selectCommandLocation(location, runtime.agentSelection);
+            const result = await (runtime.client ?? runClientCommand)(args.slice(separator + 1), selectedLocation, {
+                signal: controller.signal,
+                browserManualLink: (url) => errorOutput(`如果没有看到授权网页，请在本机浏览器打开此一次性链接；不要转发或保存：\n${url}\n`),
+                browserFallback: (url) => errorOutput(`浏览器未能自动打开，请在本机手动打开此一次性链接；不要转发或保存：\n${url}\n`),
+            });
+            output(`${JSON.stringify(result)}\n`);
+            return 0;
+        }
+        catch (error) {
+            if (error instanceof AgentSelectionRequired) {
+                output(`${JSON.stringify(selectionRequiredResult(error))}\n`);
+                return 3;
+            }
+            errorOutput(`${JSON.stringify({ error: { code: fixedErrorCode(error) ?? "CLIENT_UNAVAILABLE", ...safeConnectionDiagnostics(error) } })}\n`);
+            return 1;
+        }
+        finally {
+            process.off("SIGINT", interrupt);
+        }
+    }
+    let parsed;
+    try {
+        parsed = parseSkillLocation(args.slice(1));
+    }
+    catch {
+        errorOutput(`${errorMessages.INVALID_INPUT}\n`);
+        return 1;
+    }
+    const parameters = parsed.positional;
+    if (args[0] === "start-skill" &&
+        (parameters.length === 1 || parameters.length === 2)) {
         try {
-            const result = await (runtime.startSkill ?? runSkillStartCommand)(args[1], args[2], runtime.skillOptions);
+            const location = await selectCommandLocation({ ...runtime.skillOptions, ...parsed.location }, runtime.agentSelection);
+            const result = await (runtime.startSkill ?? runSkillStartCommand)(parameters[0], parameters[1], location);
             output(`${JSON.stringify({ status: "ready", ...result })}\n`);
             return 0;
         }
         catch (error) {
+            if (error instanceof AgentSelectionRequired) {
+                output(`${JSON.stringify(selectionRequiredResult(error))}\n`);
+                return 3;
+            }
             const code = fixedErrorCode(error) ?? "SKILL_START_UNAVAILABLE";
             errorOutput(`${JSON.stringify({ error: { code } })}\n`);
             return 1;
         }
     }
-    if (args.length !== 1 || args[0] !== "install") {
+    if (args[0] !== "install" ||
+        !(parameters.length === 0 ||
+            (parameters.length === 1 && parameters[0] === "--no-login"))) {
         errorOutput(`${errorMessages.INVALID_INPUT}\n`);
         return 1;
     }
     try {
+        const location = await selectCommandLocation(parsed.location, runtime.agentSelection);
+        const { skillsDirectory } = resolveSkillLocation(location);
         const result = await (runtime.install ?? runInstall)({
+            ...location,
+            ...(parameters[0] === "--no-login" ? { connect: false } : {}),
             reporter: (event) => output(`${messages[event]}\n`),
             launcherOptionsFactory: () => ({
                 browserManualLink: (url) => {
@@ -56,13 +135,24 @@ export async function main(args, runtime = {}) {
                 },
             }),
         });
+        output(`${JSON.stringify({
+            ...result,
+            ...(location.agent ? { agent: location.agent } : {}),
+            skillsDirectory,
+            skillPath: path.join(skillsDirectory, "nggaigc", "SKILL.md"),
+            guidance: "在当前 AI 助手中调用 NGGAIGC；若未发现新 Skill，请新开一个对话。后续安装、更新和工作流加载沿用此 skillsDirectory。",
+        })}\n`);
         if (result.status === "installed-unconnected") {
-            errorOutput(`NGGAIGC Skill ${result.version} 文件已${result.installation === "unchanged" ? "存在" : "安装"}，但设备尚未连接。${errorMessages[result.connectionError] ?? "请在新 Codex 任务中检查连接状态。"}\n`);
+            errorOutput(`NGGAIGC Skill ${result.version} 文件已${result.installation === "unchanged" ? "存在" : "安装"}，但设备尚未连接。${errorMessages[result.connectionError] ?? "请在当前 Agent 中检查连接状态。"}\n`);
             return 2;
         }
         return 0;
     }
     catch (error) {
+        if (error instanceof AgentSelectionRequired) {
+            output(`${JSON.stringify(selectionRequiredResult(error))}\n`);
+            return 3;
+        }
         const code = error instanceof CliError ? error.code : "INSTALLATION_FAILED";
         errorOutput(`${errorMessages[code] ?? errorMessages.INSTALLATION_FAILED}\n`);
         return 1;

package/dist/skill-command.js

@@ -1,9 +1,9 @@
 import { createHash, createPublicKey } from "node:crypto";
 import { readFile, realpath } from "node:fs/promises";
 import { createRequire } from "node:module";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveSkillLocation, } from "./skill-location.js";
 import { trustedKeyId, trustedKeySpkiSha256, verifyBundle, verifyInstalledSkill, } from "./bundle.js";
 import { IndependentSkillError, projectActiveSkillCatalog, startIndependentSkill, } from "./independent-skill.js";
 function fail(code) {
@@ -12,14 +12,14 @@ function fail(code) {
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-async function productionDependencies(codexHome) {
+export async function productionDependencies(skillsDirectory) {
     const vendor = fileURLToPath(new URL("../vendor/", import.meta.url));
     const bundle = await verifyBundle({
-        archive: path.join(vendor, "nggaigc-plugin-1.1.43.zip"),
+        archive: path.join(vendor, "nggaigc-plugin-1.1.45.zip"),
         manifest: path.join(vendor, "manifest.json"),
         trust: path.join(vendor, "trusted-keys.json"),
     });
-    const root = path.join(codexHome, "skills", "nggaigc");
+    const root = path.join(skillsDirectory, "nggaigc");
     await verifyInstalledSkill(root, bundle.files);
     const source = JSON.parse(await readFile(path.join(root, "references", "source.json"), "utf8"));
     if (!record(source) ||
@@ -58,24 +58,28 @@ async function productionDependencies(codexHome) {
         rootSkillVersion: source.version,
     };
 }
+/** Generic bridge only: the verified launcher owns command and API contracts. */
+export async function runClientCommand(args, options = {}, launcherOptions = {}) {
+    if (args.length === 0)
+        fail("INVALID_INPUT");
+    const { skillsDirectory } = resolveSkillLocation(options);
+    const { launcher } = await productionDependencies(skillsDirectory);
+    return launcher.main(args, launcherOptions);
+}
 /** Candidate npm entry: active catalog → server admission → verified local Skill path. */
 export async function runSkillStartCommand(skillId, skillVersion, options = {}) {
     if (!/^skill\.[a-z0-9][a-z0-9.-]{0,79}$/.test(skillId) ||
         (skillVersion !== undefined && !/^\d+\.\d+\.\d+$/.test(skillVersion)))
         fail("INVALID_INPUT");
-    const configuredCodexHome = path.resolve(options.codexHome ??
-        process.env.CODEX_HOME ??
-        path.join(os.homedir(), ".codex"));
-    if (!path.isAbsolute(configuredCodexHome))
-        fail("INSTALL_PATH_UNSAFE");
-    const codexHome = process.platform === "win32"
-        ? await realpath(configuredCodexHome).catch((error) => record(error) && error.code === "ENOENT"
-            ? configuredCodexHome
+    const configuredDirectory = resolveSkillLocation(options).skillsDirectory;
+    const skillsDirectory = process.platform === "win32"
+        ? await realpath(configuredDirectory).catch((error) => record(error) && error.code === "ENOENT"
+            ? configuredDirectory
             : fail("INSTALL_PATH_UNSAFE"))
-        : configuredCodexHome;
+        : configuredDirectory;
     const production = options.launcher && options.trust && options.rootSkillVersion
         ? null
-        : await productionDependencies(codexHome);
+        : await productionDependencies(skillsDirectory);
     const launcher = options.launcher ?? production.launcher;
     const trust = options.trust ?? production.trust;
     const rootSkillVersion = options.rootSkillVersion ?? production.rootSkillVersion;
@@ -96,13 +100,13 @@ export async function runSkillStartCommand(skillId, skillVersion, options = {})
     if (matches.length !== 1)
         fail("SKILL_UNAVAILABLE");
     const selected = matches[0];
-    return startIndependentSkill({
+    const result = await startIndependentSkill({
         index,
         skillId: selected.id,
         skillVersion: selected.version,
         rootSkillVersion,
         platformVersion,
-        codexHome,
+        skillsDirectory,
         trust,
         fetcher: options.fetcher,
         admit: async (identity) => {
@@ -117,4 +121,9 @@ export async function runSkillStartCommand(skillId, skillVersion, options = {})
             return answer;
         },
     });
+    return {
+        ...result,
+        skillsDirectory,
+        rootLauncherPath: path.join(skillsDirectory, "nggaigc", "scripts", "launch-ngg-client.cjs"),
+    };
 }

package/dist/skill-location.js

@@ -0,0 +1,96 @@
+import os from "node:os";
+import path from "node:path";
+import { lstatSync } from "node:fs";
+import { CliError } from "./errors.js";
+export function absoluteDirectory(value) {
+    if (!path.isAbsolute(value) || /[\0\r\n]/u.test(value))
+        throw new CliError("INVALID_INPUT");
+    const resolved = path.resolve(value);
+    if (resolved === path.parse(resolved).root)
+        throw new CliError("INVALID_INPUT");
+    return resolved;
+}
+export function stateDirectoryForSkills(skillsDirectory) {
+    // Preserve existing */skills journals. Other targets use a different leaf:
+    // /x and /x/skills must never share backups or installation locks.
+    return path.basename(skillsDirectory) === "skills"
+        ? path.join(path.dirname(skillsDirectory), ".nggaigc-managed")
+        : path.join(skillsDirectory, ".nggaigc-managed", "custom-target");
+}
+function hasInstalledRoot(home) {
+    try {
+        lstatSync(path.join(home, "skills", "nggaigc"));
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw new CliError("INSTALLATION_FAILED");
+    }
+}
+function workbuddyHome(profile, environment) {
+    const configured = environment.WORKBUDDY_CONFIG_DIR ?? environment.CODEBUDDY_CONFIG_DIR;
+    if (configured !== undefined)
+        return absoluteDirectory(configured);
+    const current = path.join(profile, ".workbuddy");
+    const legacy = path.join(profile, ".codebuddy");
+    // Upgrade an existing legacy global installation in place when outside the
+    // host. Inside WorkBuddy, its actual runtime configuration takes precedence.
+    // The installer still verifies ownership/signatures before changing files.
+    return !hasInstalledRoot(current) && hasInstalledRoot(legacy)
+        ? legacy
+        : current;
+}
+/** One explicit location for root installation and every dependent Skill. */
+export function resolveSkillLocation(options = {}, environment = process.env) {
+    if ([options.agent, options.skillsDirectory, options.codexHome].filter((value) => value !== undefined).length > 1)
+        throw new CliError("INVALID_INPUT");
+    if (options.skillsDirectory !== undefined) {
+        const skillsDirectory = absoluteDirectory(options.skillsDirectory);
+        return {
+            skillsDirectory,
+            stateDirectory: stateDirectoryForSkills(skillsDirectory),
+        };
+    }
+    const profile = absoluteDirectory(options.profile ?? os.homedir());
+    const agent = options.agent ?? "codex";
+    if (!["codex", "workbuddy", "universal"].includes(agent))
+        throw new CliError("INVALID_INPUT");
+    const home = absoluteDirectory(options.codexHome ??
+        (agent === "codex"
+            ? ((options.profile === undefined
+                ? environment.CODEX_HOME
+                : undefined) ?? path.join(profile, ".codex"))
+            : agent === "workbuddy"
+                ? workbuddyHome(profile, options.profile === undefined ? environment : {})
+                : path.join(profile, ".agents")));
+    return {
+        skillsDirectory: path.join(home, "skills"),
+        // Explicit and named-host calls for the same directory share one journal.
+        stateDirectory: stateDirectoryForSkills(path.join(home, "skills")),
+    };
+}
+export function parseSkillLocation(args) {
+    const location = {};
+    const positional = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (value !== "--agent" && value !== "--skills-dir") {
+            positional.push(value);
+            continue;
+        }
+        if (location.agent !== undefined || location.skillsDirectory !== undefined)
+            throw new CliError("INVALID_INPUT");
+        const argument = args[++index];
+        if (!argument || argument.startsWith("--"))
+            throw new CliError("INVALID_INPUT");
+        if (value === "--agent") {
+            if (!["codex", "workbuddy", "universal"].includes(argument))
+                throw new CliError("INVALID_INPUT");
+            location.agent = argument;
+        }
+        else
+            location.skillsDirectory = absoluteDirectory(argument);
+    }
+    return { location, positional };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nggaigc/cli",
-  "version": "0.1.44",
-  "description": "Secure one-command NGGAIGC Skill installer for Codex.",
+  "version": "0.1.47",
+  "description": "Secure NGGAIGC Skill installer for Codex, WorkBuddy and compatible agents.",
   "type": "module",
   "bin": {
     "nggaigc": "dist/bin.js"

package/vendor/manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": "nggaigc-plugin-package/v1",
   "artifactId": "plugin.nggaigc",
-  "version": "1.1.43",
-  "sourceCommit": "8ad838c5d286a3d321e0d12e8583d1a833575a20",
-  "artifactPath": "packages/plugins/nggaigc-plugin-1.1.43.zip",
-  "sha256": "46ed3cfd4701c51d3d916a307c6975448f326af12d3c58f17d0d9f88658d94ff",
-  "sizeBytes": 493785,
+  "version": "1.1.45",
+  "sourceCommit": "241601b7d034ce36442e7738438cbc6c6b3b867d",
+  "artifactPath": "packages/plugins/nggaigc-plugin-1.1.45.zip",
+  "sha256": "e23b7781579124a1b90ece1558d58d418dfef6a6557152f1581cbb81145281da",
+  "sizeBytes": 502168,
   "fileCount": 24,
   "platforms": [
     "win32-x64",
@@ -13,8 +13,8 @@
     "darwin-arm64"
   ],
   "files": {
-    ".codex-plugin/plugin.json": "df32ed1e3fa7732fe712b9021336f629f8f0dfaf0df9813b2b31089828ec61b6",
-    "installer/install.cjs": "a0c94ed71edf4cd7eb4a66609a4dcf73049abbd14aa273ee65b9b3029be2da2b",
+    ".codex-plugin/plugin.json": "89478e096e5cbd46ad156cb06abee9a59973f530e08be815283bf6d4ddc3903f",
+    "installer/install.cjs": "76f4ed73233fd39900fb0bedbc434dea39e52e6b6b4622f3fd388a5ca09c6f62",
     "installer/legacy-root-digests.json": "922552646a5aa6cff8616c372912a37b1d5f263351206b85785ed9b2eae31641",
     "installer/signed-pair-1.1.16.json": "ccb22a90302cc5c9c585067ebc211a27b0c9d8a177c2740a5678a58a3d70bfe9",
     "installer/signed-pair-1.1.17.json": "a3697506c929aaa085a6d994fc3a1b9a87e522ec6e1e32f3f760e6a534effa2b",
@@ -24,24 +24,24 @@
     "migration/seedream-1.1.3/scripts/seedream.mjs": "dcc6af4d945790d9dfd7fac21c60934759d7ac2576a14507d0299f4833942a96",
     "migration/seedream-1.1.3/SKILL.md": "5c5cf3c2d99376f246425e873c5566436ed528256372ac3208abb60364c4517c",
     "skills/nggaigc/agents/openai.yaml": "8936d97b9821e687e224e9349cc42be2ee5fc20988562efffbcb70080aedf87c",
-    "skills/nggaigc/references/catalog-and-updates.md": "c609a560ad8245d825511a4c47b6eb0a663d01a9beb57cecc7451928226a277f",
-    "skills/nggaigc/references/source.json": "ca9231612752cb06e43596f13fa9976236b3ead304c7683546f5dc0af6107bec",
+    "skills/nggaigc/references/catalog-and-updates.md": "a43bee94a480aa2bf0b1e7038cee6f27fb86d2bd8fa88a28a63678963d7c1530",
+    "skills/nggaigc/references/source.json": "26838dd1c3df2347abb97ac47da61148c7099ce9f12c935b788c6fe2e9e26f0c",
     "skills/nggaigc/scripts/api_client.mjs": "e16bf750a297ef7e88e4843d2fba9c33b412a66516bfe76822d7deec6c153069",
     "skills/nggaigc/scripts/api_package.mjs": "6beee22aed770cbf501abe6d1d9d252f7a53893eeb9b6399bd26c4ef68470d5a",
-    "skills/nggaigc/scripts/bootstrap-public.json": "a203a838fbb8c1b200e1cd30044a11ee851d2a6b1161d634e2f87f52dbcbf6f2",
-    "skills/nggaigc/scripts/launch-ngg-client.cjs": "ada77f2d7505e908248cd7d2840b068559a21ad518f0e92560973faa8c633d0d",
+    "skills/nggaigc/scripts/bootstrap-public.json": "4b1aba50683bc50d3ac9c2ec10479366fa10e7452874b67f2cd6b93e3e23952d",
+    "skills/nggaigc/scripts/launch-ngg-client.cjs": "5953b9211b31e72b9f7d22a92f954e9b526387f6d86ac4387e0c810f3e01c0da",
     "skills/nggaigc/scripts/macos-keychain": "b0bdf29d14219d38ca18c7e5c599deb0daa8c8ac70b0babbc7d4fb23673079ec",
     "skills/nggaigc/scripts/macos-keychain.swift": "1b57e74fde66c824fe970547dd8ca0883a3334c34c065e85a8a2a90d4556a7f5",
-    "skills/nggaigc/scripts/ngg_client.mjs": "4d572106c3bb2c84b13ecb3b68c9293768b821fe7b78a11281ccccee7916ba3c",
-    "skills/nggaigc/scripts/ngg-session.mjs": "f42d6f0db94c9f66a6a7a5bc7754ba238e32ea12052ac706cb1e97ffe148ec55",
+    "skills/nggaigc/scripts/ngg_client.mjs": "2b4903ad8afe76b0dc970b5519a50d04dcc0e12dfa8f4267fb85d878187c3789",
+    "skills/nggaigc/scripts/ngg-session.mjs": "21df7cd76e729a2109e2f8ec53d5a5998e801ab9259ce8d20b9c62f9926b1135",
     "skills/nggaigc/scripts/supported-platforms.json": "ec8b0754c489e04534a1d9880dd6664ba9c5bcd07789e06d138e0923f23575ff",
     "skills/nggaigc/scripts/windows-credential.ps1": "80d470fb0c9473d26bd599cafa9f1c2ad69056d4a835888ddcbb5c1548f9d059",
-    "skills/nggaigc/SKILL.md": "b871cbd03eb551c58282effd4c1e7d07df560fd4f95b460ddc0d9e570b912db1"
+    "skills/nggaigc/SKILL.md": "8cb3eb8a03cf144ce15fa01d7d342495c2b11ba0f6a0cf61a493e1e43c83a11f"
   },
   "signature": {
     "algorithm": "ed25519",
     "keyId": "ngg-signing-skill-release-1",
     "scope": "artifact-bytes",
-    "value": "dDgL9aFqIt/xqrZI8R3fCCINYrs329MFzJt+GKdwXjEOGA4y87OXEle6UM6dRMPTZCHxZWSu6HLPOtdd8HfABA=="
+    "value": "OlUz+AuTVQN/u8Kp+d91twCKkU6VtRPUrzez8iGYLRmLck5lXvG6KUbVabPMIkEirKD/fOCcwJ47SKSsS8x+BQ=="
   }
 }