@actiondock/builder 2.20.0 → 2.21.0

package/dist/dependency-resolver.js

@@ -15,10 +15,40 @@ export const TEST_FILE_SUFFIXES = [
     ".spec.jsx",
     ".d.ts",
 ];
+/**
+ * ActionDock 配置加密主密钥与身份标记的规范文件名（位于密钥目录 keys 内）。
+ *
+ * 命名事实源为 core/security/config-key.ts 的 resolveKeyPaths：
+ * 密钥文件 config.key、身份标记 config.key.id。
+ */
+const CONFIG_KEY_FILE_NAMES = ["config.key", "config.key.id"];
+/**
+ * 判断文件名是否为 ActionDock 配置加密密钥资产。
+ *
+ * 密钥发布采用原子硬链接，临时文件名为 .{原名}.tmp.{pid}.{uuid}
+ * （core/security/config-key.ts 的 publishAtomically）；失败清理为尽力而为，
+ * 残留临时名同样可能出现在密钥目录内，须一并识别。
+ */
+function isConfigKeyArtifactName(fileName) {
+    for (const name of CONFIG_KEY_FILE_NAMES) {
+        if (fileName === name || fileName.startsWith(`.${name}.tmp.`)) {
+            return true;
+        }
+    }
+    return false;
+}
 /** 运行环境配置不得进入分发产物；普通业务 bindings.json 不受影响。 */
 export function isRuntimeConfigFile(relPath) {
     const segments = relPath.replace(/\\/g, "/").split("/");
-    return segments.includes(".actiondock") || segments.at(-1) === "profiles.json";
+    const fileName = segments.at(-1) ?? "";
+    if (segments.includes(".actiondock") || fileName === "profiles.json") {
+        return true;
+    }
+    // 配置加密主密钥仅落在密钥目录 keys 内：dataDir 定位为 <dataDir>/keys，
+    // 主目录定位为 .actiondock/keys（后者已被上方 .actiondock 分支覆盖）。
+    // 仅在 keys 目录上下文下精确排除，普通业务 keys 目录内的其他文件
+    // （如 keys/data.json、keys/api.key）与密钥目录外的同名业务资产不受影响。
+    return segments.at(-2) === "keys" && isConfigKeyArtifactName(fileName);
 }
 /**
  * 忽略的文件模式判断（排除测试文件、类型声明文件以及构建/版本控制等私有目录）。

package/dist/npm-pack.d.ts

@@ -1,6 +1,7 @@
+import { type RunPackageManagerOptions } from "@actiondock/core/project";
 /**
  * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
- * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
- * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
+ * 使用 --json=false 确保标准输出仅输出单行压缩包文件名（显式覆盖 npm_config_json 等环境配置）。
+ * 复用统一包管理器启动解析与驱动底座，以 shell: false 执行，完整保留路径参数与特殊字符边界。
  */
-export declare function runNpmPack(stagingPkgDir: string, packDestination: string, fallbackName: string): Promise<string>;
+export declare function runNpmPack(stagingPkgDir: string, packDestination: string, _fallbackName?: string, options?: RunPackageManagerOptions): Promise<string>;

package/dist/npm-pack.js

@@ -1,69 +1,47 @@
-import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
+import { runPackageManager } from "@actiondock/core/project";
 import { BuilderError } from "./errors.js";
 /**
  * 在暂存目录调用带有 --ignore-scripts 的 npm pack 生成标准 npm 压缩包（.tgz）。
- * 优先解析 --json 结构化输出，失败时回退到尾部行文件名解析。
- * Windows 兼容：npm 是 .cmd 脚本，无 shell 直接 spawn 会 ENOENT/EINVAL。
+ * 使用 --json=false 确保标准输出仅输出单行压缩包文件名（显式覆盖 npm_config_json 等环境配置）。
+ * 复用统一包管理器启动解析与驱动底座，以 shell: false 执行，完整保留路径参数与特殊字符边界。
  */
-export async function runNpmPack(stagingPkgDir, packDestination, fallbackName) {
-    const { stdout } = await new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn("npm", ["pack", "--ignore-scripts", "--json", "--pack-destination", packDestination], {
+export async function runNpmPack(stagingPkgDir, packDestination, _fallbackName, options) {
+    const args = [
+        "pack",
+        "--ignore-scripts",
+        "--json=false",
+        "--pack-destination",
+        packDestination,
+    ];
+    let procResult;
+    try {
+        procResult = await runPackageManager("npm", args, {
+            ...options,
             cwd: stagingPkgDir,
-            shell: process.platform === "win32",
         });
-        let stdoutBuf = "";
-        let stderrBuf = "";
-        child.stdout.on("data", (chunk) => (stdoutBuf += chunk));
-        child.stderr.on("data", (chunk) => (stderrBuf += chunk));
-        child.on("error", rejectPromise);
-        child.on("close", (code) => {
-            if (code === 0) {
-                resolvePromise({ stdout: stdoutBuf, stderr: stderrBuf });
-            }
-            else {
-                rejectPromise(new BuilderError(`npm pack exited with code ${code}. Output:\n${stdoutBuf}\n${stderrBuf}`));
-            }
-        });
-    });
-    // 优先解析 --json 结构化输出中的压缩包文件名
-    let generatedName;
-    const trimmed = stdout.trim();
-    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
-        try {
-            const parsed = JSON.parse(trimmed);
-            let items;
-            if (Array.isArray(parsed)) {
-                items = parsed;
-            }
-            else if (typeof parsed === "object" && parsed !== null) {
-                // npm >= 11 的 pack --json 输出为按包名索引的对象，取全部包含 filename 的条目
-                items = Object.values(parsed).filter((entry) => typeof entry === "object" && entry !== null && "filename" in entry);
-            }
-            else {
-                items = [];
-            }
-            // 多包输出时取最后一个 filename（npm 按依赖顺序逐包输出，末尾为当前项目产物）
-            const filenames = items
-                .map((item) => item.filename)
-                .filter((name) => typeof name === "string" && name.length > 0);
-            const filename = filenames[filenames.length - 1];
-            if (filename !== undefined) {
-                generatedName = filename;
-            }
-        }
-        catch {
-            // 回退到尾部行解析
-        }
     }
-    if (!generatedName) {
-        const packLines = trimmed
-            .split("\n")
-            .map((line) => line.trim())
-            .filter((line) => line.length > 0);
-        const tgzLine = packLines.slice().reverse().find((line) => line.endsWith(".tgz"));
-        generatedName = tgzLine || packLines.pop() || fallbackName;
+    catch (err) {
+        throw new BuilderError(`npm pack failed to execute: ${err?.message || String(err)}`);
+    }
+    if (procResult.status !== 0) {
+        throw new BuilderError(`npm pack exited with code ${procResult.status}. Output:\n${procResult.stdout}\n${procResult.stderr}`);
+    }
+    const stdout = procResult.stdout;
+    const lines = stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0) {
+        throw new BuilderError(`npm pack produced empty stdout; expected tarball filename. Output:\n${stdout}\nStderr:\n${procResult.stderr}`);
+    }
+    if (lines.length > 1) {
+        throw new BuilderError(`npm pack produced unexpected multi-line output; expected single tarball filename. Output:\n${stdout}`);
+    }
+    const generatedName = lines[0];
+    if (!generatedName.endsWith(".tgz")) {
+        throw new BuilderError(`npm pack produced unexpected output line '${generatedName}'; expected .tgz filename. Output:\n${stdout}`);
     }
     const generatedTarball = join(packDestination, generatedName);
     if (!existsSync(generatedTarball)) {

package/dist/skill/templates.js

@@ -220,19 +220,24 @@ ${desc}`;
 
 本技能为 ActionDock 源码型技能包。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
 
-### 安装依赖与注册链接
+### 注册链接至全局路由表
 
-本技能面向全局挂载使用。在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\`。标准流程为先安装生产依赖，再执行注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
+本技能面向全局挂载使用。在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\`。标准流程为执行注册链接，将其登记至全局路由表：
 
 \`\`\`bash
-# 安装生产依赖
-cd "<skill_root>" && npm install --omit=dev
-
 # 注册并链接到 ActionDock
 ad link "<skill_root>"
 \`\`\`
 
-> \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。若后续依赖发生变更，可重新执行上述安装依赖与链接命令更新环境。`;
+> 登记后，在任意工作目录通过完全限定 ID 本地调用 \`ad run\` 时，主动作与宿主快照中已有的本地子动作均会在实际调用前按需准备依赖。\`ad link\` 天然具备幂等性，可安全重复调用。
+
+### 显式手动预装依赖（可选）
+
+使用者明确要求预先准备环境或修复已有依赖时，按项目实际使用的包管理器手动安装生产依赖。若本次调用指定了 \`--no-install\` 或 \`ACTIONDOCK_AUTO_INSTALL=false\`，整条调用链均保持禁装策略并报告依赖未就绪，智能体不能擅自执行安装命令绕过策略。以下为 npm 项目的预装示例：
+
+\`\`\`bash
+cd "<skill_root>" && npm install --omit=dev
+\`\`\``;
     const sDescribe = `### 动作参数契约按需调阅
 
 在调用未知参数的 Action 前，可在终端执行命令查阅该 Action 的输入输出模式与详细说明：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/builder",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "ActionDock Build Planner, distribution packaging, and Skill exporter",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.20.0",
-    "@actiondock/sdk": "^2.20.0"
+    "@actiondock/core": "^2.21.0",
+    "@actiondock/sdk": "^2.21.0"
   },
   "keywords": [
     "actiondock",