@actiondock/builder 2.10.0 → 2.12.0

package/dist/skill/templates.d.ts

@@ -1,5 +1,6 @@
 import type { ActionSpec, ProjectConfig } from "@actiondock/core";
 import type { PlaybookDefinition } from "@actiondock/core/project";
+import type { CompositeCustomSection } from "./custom-parser.js";
 export type SkillActionItem = ActionSpec | {
     id: string;
     description?: string;
@@ -7,8 +8,33 @@ export type SkillActionItem = ActionSpec | {
     outputSchema?: any;
     annotations?: any;
 };
-export declare function generateSourceSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: PlaybookDefinition[]): string;
-export declare function generateStandaloneSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: PlaybookDefinition[], binaryRelPath?: string): string;
+export type SkillPlaybookItem = PlaybookDefinition | {
+    id: string;
+    filePath: string;
+    name?: string;
+    description?: string;
+    actions?: string[];
+};
+/**
+ * 渲染完整「运行时环境参考」正文：写入导出目录 references/actiondock-runtime.md，
+ * 由主说明按需链接调阅，不在每个技能正文重复展开整套安装与框架管理教程。
+ */
+export declare function renderRuntimeReferenceContent(options: {
+    /** 依赖安装步骤标题：source 为安装技能源码依赖，composite 为安装复合技能聚合依赖 */
+    dependencyStepLabel: string;
+    /** 重新链接步骤标题 */
+    relinkStepLabel: string;
+    /** 是否在重新链接步骤末尾附加复合链接语义说明 */
+    compositeLinkNote?: boolean;
+    /** 调用方式说明：源码型与 Node 目录型分化（如是否需要全局 ad） */
+    invocationStyle: "global-ad" | "node-entry";
+    /** Node 目录型的入口相对路径（invocationStyle 为 node-entry 时使用） */
+    entryRelPath?: string;
+}): string;
+/** 运行时参考文件的导出目录内相对路径（单一事实源） */
+export declare const RUNTIME_REFERENCE_REL_PATH = "references/actiondock-runtime.md";
+export declare function generateSourceSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: SkillPlaybookItem[]): string;
+export declare function generateStandaloneSkillMd(config: ProjectConfig, actions: SkillActionItem[], playbooks: SkillPlaybookItem[], binaryRelPath?: string): string;
 export interface CompositeSkillPackageInfo {
     config: ProjectConfig;
     actions: Array<{
@@ -23,33 +49,6 @@ export interface CompositeSkillPackageInfo {
     }>;
     packageDir: string;
 }
-/**
- * 复合技能自定义说明书（SKILL.custom.md）的槽位，
- * 决定自定义段落插入到官方模板生成结果中的位置。
- */
-export type CompositeCustomSlot = "intro" | "after-init" | "after-describe" | "after-actions" | "after-playbooks" | "after-invoke" | "append";
-export declare const COMPOSITE_CUSTOM_SLOTS: readonly CompositeCustomSlot[];
-/** 工作区内约定俗成的复合技能自定义说明书文件名。 */
-export declare const COMPOSITE_CUSTOM_DECLARATION_FILE = "SKILL.custom.md";
-export interface CompositeCustomSection {
-    slot: CompositeCustomSlot;
-    content: string;
-}
-export interface CompositeCustomDeclaration {
-    /** 自定义说明书 frontmatter 中声明的 description 覆盖值 */
-    description?: string;
-    sections: CompositeCustomSection[];
-}
-/**
- * 解析自定义说明书正文：以 `<!-- actiondock:slot <name> -->` 标记行分段。
- * 首个标记之前的内容归入 `append` 槽位；未知槽位名直接抛错，避免拼写错误被静默吞掉。
- */
-export declare function parseCustomSections(source: string): CompositeCustomSection[];
-/**
- * 解析复合技能自定义说明书文件：支持 YAML frontmatter 中的 `description` 覆盖，
- * 正文按槽位标记解析为自定义段落。
- */
-export declare function parseCustomSkillDeclaration(source: string): CompositeCustomDeclaration;
 /**
  * 生成多包聚合的复合模式 SKILL.md 文档。
  */

package/dist/skill/templates.js

@@ -4,6 +4,10 @@ function getCleanSkillMetadata(config) {
     const desc = config.description || `AI Agent skill for ${config.name} (${config.id})`;
     return { cleanName, desc };
 }
+/**
+ * 动作摘要列表渲染：只承载能力路由信息（标识、原始业务描述、只读或破坏性标注），
+ * 不展开完整输入输出 Schema；完整契约由 describe 命令按需调阅。
+ */
 function renderActionListMarkdown(actions, options = {}) {
     return actions
         .map((a) => {
@@ -12,7 +16,7 @@ function renderActionListMarkdown(actions, options = {}) {
             ? `\`${options.packageId}/${a.id}\` (或 \`${a.id}\`)`
             : `\`${a.id}\``;
         const lines = [`- ${idLabel}${aDesc}`];
-        // 标注元数据解析
+        // 标注元数据解析（安全标注不得从主说明移走）
         if (a.annotations && typeof a.annotations === "object") {
             const annoList = [];
             if (a.annotations.readOnly === true) {
@@ -25,49 +29,6 @@ function renderActionListMarkdown(actions, options = {}) {
                 lines.push(`  - 属性标注: ${annoList.join(", ")}`);
             }
         }
-        // 输入参数模式解析
-        if (a.inputSchema &&
-            typeof a.inputSchema === "object" &&
-            a.inputSchema.properties) {
-            const props = a.inputSchema.properties;
-            const req = (a.inputSchema.required || []);
-            const propKeys = Object.keys(props);
-            if (propKeys.length > 0) {
-                lines.push("  - 输入参数:");
-                for (const k of propKeys) {
-                    const p = props[k] || {};
-                    const typeStr = p.type ? `\`${p.type}\`` : "`any`";
-                    const reqStr = req.includes(k) ? ", 必填" : "";
-                    const descStr = p.description ? `: ${p.description}` : "";
-                    const defStr = p.default !== undefined
-                        ? ` (默认值: \`${JSON.stringify(p.default)}\`)`
-                        : "";
-                    lines.push(`    - \`${k}\` (${typeStr}${reqStr})${descStr}${defStr}`);
-                }
-            }
-            else {
-                lines.push("  - 输入参数: 无");
-            }
-        }
-        else {
-            lines.push("  - 输入参数: 无");
-        }
-        // 输出字段模式解析
-        if (a.outputSchema &&
-            typeof a.outputSchema === "object" &&
-            a.outputSchema.properties) {
-            const outProps = a.outputSchema.properties;
-            const outKeys = Object.keys(outProps);
-            if (outKeys.length > 0) {
-                lines.push("  - 输出字段:");
-                for (const k of outKeys) {
-                    const p = outProps[k] || {};
-                    const typeStr = p.type ? `\`${p.type}\`` : "`any`";
-                    const descStr = p.description ? `: ${p.description}` : "";
-                    lines.push(`    - \`${k}\` (${typeStr})${descStr}`);
-                }
-            }
-        }
         return lines.join("\n");
     })
         .join("\n\n");
@@ -93,6 +54,31 @@ Playbook SOPs 为复杂业务任务提供逐步指导规程。详细规程请查
 ${list}
 `;
 }
+/**
+ * 渲染「执行 Action」调用指引正文：三处生成器共用同一决策原则，
+ * 承载输入模式选择（扁平赋值与 --input-file）与输出模式选择（默认原始输出与按需 --json）。
+ */
+function renderInvocationGuidance(describeCmd, runCmd) {
+    return `推荐在执行前调用 describe 命令调阅确切参数契约：
+
+\`\`\`bash
+# 调阅参数契约与建议赋值样例
+${describeCmd}
+
+# 调用语法格式（其中 ASSIGNMENT 根据 describe 查阅的参数契约提供）
+${runCmd} -- ASSIGNMENT...
+\`\`\`
+
+输入模式选择（三种输入模式严格互斥，仅选其一）：
+
+- 扁平赋值为默认首选：参数项少且结构简单时，直接以 \`-- key="value" count:=10\` 形式内联传递。
+- 文件输入用于复杂参数：当参数含深层嵌套结构、大段文本或内容易被终端引号转义破坏时，将完整 JSON 写入文件并通过 \`--input-file input.json\` 传递。
+
+输出模式选择（避免浪费上下文 token）：
+
+- 默认不加 \`--json\`：stdout 直接输出业务返回正文，保留原生格式与真实换行，绝大多数调用直接阅读正文即可推进后续步骤。
+- 仅在需要结构化提取时才追加 \`--json\`：如需按 \`error.code\` 判定自愈策略、以 \`runId\` 关联追踪或程序化消费完整字段时，才使用 JSON 信封输出（格式见下节）。`;
+}
 /**
  * 渲染「结构化响应解析」小节：三处生成器共用同一 JSON 信封代码块，
  * 仅首行名词与 stdout/stderr 描述行随变体分化。
@@ -106,9 +92,9 @@ function renderJsonEnvelopeSection(wording, options) {
     const descriptionBlock = options?.withDescriptions === false
         ? ""
         : `\n\n${stdoutLine}\n- \`stderr\`：执行日志与诊断${stderrTail}信息。`;
-    return `### 结构化响应解析
+    return `### 结构化响应解析（--json 模式）
 
-所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON ${noun}：
+仅当调用时显式追加 \`--json\` 选项，\`stdout\` 才输出标准 JSON ${noun}；默认不加该选项时直接输出业务正文：
 
 \`\`\`json
 // 执行成功响应 (ok 为 true)
@@ -130,39 +116,63 @@ function renderJsonEnvelopeSection(wording, options) {
 \`\`\`${descriptionBlock}`;
 }
 /**
- * 渲染「故障排查与环境安装指引」整节：source 与 composite 共用完整安装指引，
- * 差异点（依赖安装步骤标题、重新链接步骤标题、复合链接语义说明）通过参数分化。
+ * 渲染完整「运行时环境参考」正文：写入导出目录 references/actiondock-runtime.md，
+ * 由主说明按需链接调阅，不在每个技能正文重复展开整套安装与框架管理教程。
  */
-function renderTroubleshootingSection(options) {
+export function renderRuntimeReferenceContent(options) {
     const relinkNote = options.compositeLinkNote
-        ? `\n  \`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。`
+        ? `\`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。`
         : "";
-    return `---
+    const invocationSection = options.invocationStyle === "node-entry"
+        ? `本技能为 Node 目录型交付，可直接使用自身入口执行，不要求全局安装 \`ad\` 命令行工具：
 
-## 故障排查与环境安装指引（按需查阅）
-
-> [!NOTE]
-> **按需排查原则**：默认宿主环境中已预置 \`ad\` 命令行工具与 Node.js 运行环境。正常执行流程直接调用上述 Action 即可，**严禁在任务启动前盲目进行前置环境检查或体检**；仅在终端明确报错提示命令不存在（如 \`ad: command not found\`）或提示依赖缺失时，方可按本节指引安装初始化。
-
-### 命令行工具与环境依赖未就绪时的安装指引
-
-若宿主环境未安装 \`ad\` 命令行工具或依赖缺失，请依次按如下步骤完成安装：
+\`\`\`bash
+${options.entryRelPath || "node ./entry.mjs"} list
+${options.entryRelPath || "node ./entry.mjs"} describe <action-id>
+${options.entryRelPath || "node ./entry.mjs"} run <action-id> -- ASSIGNMENT...
+\`\`\`
 
-- **环境要求**：Node.js 版本大于等于 24.12.0（执行 \`node -v\` 确认）。
+若宿主环境已全局安装 \`ad\`，亦可将其链接后统一调度。`
+        : `本技能为源码型交付，通过全局安装的 \`ad\` 命令行工具执行。`;
+    const isNodeEntry = options.invocationStyle === "node-entry";
+    const probePrinciple = isNodeEntry
+        ? `默认宿主环境中已预置 Node.js 运行环境。本目录型交付直接使用自身入口执行，不依赖全局 \`ad\`；正常执行流程直接调用上述 Action 即可，严禁在任务启动前盲目进行前置环境检查或体检；仅在入口报错提示模块缺失（如 \`Cannot find package\`）或 Node.js 版本不满足时，方可按本文指引修复。`
+        : `默认宿主环境中已预置 \`ad\` 命令行工具与 Node.js 运行环境。正常执行流程直接调用上述 Action 即可，严禁在任务启动前盲目进行前置环境检查或体检；仅在终端明确报错提示命令不存在（如 \`ad: command not found\`）或提示依赖缺失时，方可按本文指引安装初始化。`;
+    const cliInstallSection = isNodeEntry
+        ? `- **Node.js 环境要求**：Node.js 版本大于等于 24.12.0（执行 \`node -v\` 确认）。目录型交付不需要全局安装 \`ad\`；若需要接入全局调度，可另行安装：
+  \`\`\`bash
+  npm install -g @actiondock/cli
+  \`\`\``
+        : `- **环境要求**：Node.js 版本大于等于 24.12.0（执行 \`node -v\` 确认）。
 - **全局安装 ActionDock 命令行工具**：
   \`\`\`bash
   npm install -g @actiondock/cli
-  \`\`\`
+  \`\`\``;
+    return `# ActionDock 运行时环境参考
+
+> 本文件为技能主说明的按需参考，仅在环境未就绪或报错时查阅；正常执行流程无需阅读本文。
+
+## 调用方式
+
+${invocationSection}
+
+## 按需排查原则
+
+${probePrinciple}
+
+## 环境依赖未就绪时的安装指引
+
+若宿主环境依赖缺失，请依次按如下步骤完成安装：
+
+${cliInstallSection}
 - **${options.dependencyStepLabel}**：
   若在技能目录内调用时提示模块缺失，在 \`<skill_root>\` 目录下安装生产依赖：
   \`\`\`bash
   cd "<skill_root>" && npm install --omit=dev
   \`\`\`
-- **验证工具就绪**：
-  \`\`\`bash
-  ad --version
-  \`\`\`
-- **环境诊断与体检**：
+- **验证就绪**：
+  ${isNodeEntry ? `${options.entryRelPath || "node ./entry.mjs"} list` : "ad --version"}
+- **环境诊断与体检**（仅全局接入 \`ad\` 后适用）：
   安装完成后若仍遇到异常，执行体检命令排查：
   \`\`\`bash
   ad doctor
@@ -170,8 +180,24 @@ function renderTroubleshootingSection(options) {
 - **${options.relinkStepLabel}**：
   \`\`\`bash
   ad link "<skill_root>"
-  \`\`\`${relinkNote}`;
+  \`\`\`
+${relinkNote ? `  ${relinkNote}\n` : ""}`;
 }
+/**
+ * 渲染主说明中的「故障排查」精简入口：仅保留按需排查原则与参考文件链接。
+ */
+function renderTroubleshootingSection(referenceRelPath) {
+    return `---
+
+## 故障排查与环境安装指引（按需查阅）
+
+> [!NOTE]
+> **按需排查原则**：默认宿主环境中已预置运行环境与依赖，正常执行流程直接调用上述 Action 即可，严禁在任务启动前盲目进行前置环境检查或体检。
+
+仅在报错提示命令不存在或依赖缺失时，按需查阅完整安装与自愈指引：[${referenceRelPath}](${referenceRelPath})`;
+}
+/** 运行时参考文件的导出目录内相对路径（单一事实源） */
+export const RUNTIME_REFERENCE_REL_PATH = "references/actiondock-runtime.md";
 export function generateSourceSkillMd(config, actions, playbooks) {
     const { cleanName, desc } = getCleanSkillMetadata(config);
     const pkgId = config.id;
@@ -191,9 +217,9 @@ ${desc}
 
 本技能为 **ActionDock 源码型技能包**。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
 
-### 注册与链接
+### 注册与链接（全局调用）
 
-在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册：
+本技能面向全局挂载使用：在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册链接，之后可在任意工作目录通过完全限定 ID 全局调用：
 
 \`\`\`bash
 ad link "<skill_root>"
@@ -213,28 +239,7 @@ ad describe ${pkgId}/${firstAction}
 
 为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
 
-推荐在执行前调用 describe 命令调阅确切参数契约：
-
-\`\`\`bash
-# 调阅参数契约与建议赋值样例
-ad describe ${pkgId}/${firstAction}
-
-# 调用语法格式（其中 ASSIGNMENT 根据 ad describe 查阅的参数契约提供）
-ad run ${pkgId}/${firstAction} --json -- ASSIGNMENT...
-\`\`\`
-
-将参数写入 JSON 文件并通过 --input-file 传递：
-
-\`\`\`bash
-ad run ${pkgId}/${firstAction} --json --input-file input.json
-\`\`\`
-
-> 免注册本地执行：
-> 若工作目录已位于本技能根目录，亦可直接免 link 执行：
-> \`\`\`bash
-> cd <skill_root>
-> ad run ${firstAction} --json
-> \`\`\`
+${renderInvocationGuidance(`ad describe ${pkgId}/${firstAction}`, `ad run ${pkgId}/${firstAction}`)}
 
 ${renderJsonEnvelopeSection("envelope")}
 ${playbookSection}
@@ -260,10 +265,7 @@ ad state list --package ${pkgId}
 ad state get KEY --package ${pkgId}
 \`\`\`
 
-${renderTroubleshootingSection({
-        dependencyStepLabel: "安装技能源码依赖",
-        relinkStepLabel: "完成安装后重新链接本技能",
-    })}
+${renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH)}
 `;
 }
 export function generateStandaloneSkillMd(config, actions, playbooks, binaryRelPath = "./bin/action-bin") {
@@ -291,21 +293,7 @@ ${binaryRelPath} describe ${firstAction}
 
 ### 执行 Action
 
-推荐在执行前调用 describe 命令调阅确切参数契约：
-
-\`\`\`bash
-# 调阅参数契约与建议赋值样例
-${binaryRelPath} describe ${firstAction}
-
-# 调用语法格式（其中 ASSIGNMENT 根据 describe 查阅的参数契约提供）
-${binaryRelPath} run ${firstAction} --json -- ASSIGNMENT...
-\`\`\`
-
-将参数写入 JSON 文件并通过 --input-file 传递：
-
-\`\`\`bash
-${binaryRelPath} run ${firstAction} --json --input-file input.json
-\`\`\`
+${renderInvocationGuidance(`${binaryRelPath} describe ${firstAction}`, `${binaryRelPath} run ${firstAction}`)}
 
 ${renderJsonEnvelopeSection("result")}
 ${playbookSection}
@@ -335,73 +323,16 @@ ${binaryRelPath} state get KEY
 
 ## 故障排查与依赖自愈指引（按需查阅）
 
-若在宿主环境中执行时提示模块缺失，在技能根目录下安装生产依赖：
+本目录为 Node 目录型交付，直接使用自身入口执行，不要求全局安装 \`ad\` 命令行工具。
+若提示模块缺失，在技能根目录下安装生产依赖：
 
 \`\`\`bash
 npm install --omit=dev
 \`\`\`
+
+完整环境安装与自愈指引按需查阅：[${RUNTIME_REFERENCE_REL_PATH}](${RUNTIME_REFERENCE_REL_PATH})
 `;
 }
-export const COMPOSITE_CUSTOM_SLOTS = [
-    "intro",
-    "after-init",
-    "after-describe",
-    "after-actions",
-    "after-playbooks",
-    "after-invoke",
-    "append",
-];
-/** 工作区内约定俗成的复合技能自定义说明书文件名。 */
-export const COMPOSITE_CUSTOM_DECLARATION_FILE = "SKILL.custom.md";
-const CUSTOM_SLOT_MARKER_PATTERN = /^\s*<!--\s*actiondock:slot\s+([a-zA-Z][a-zA-Z0-9-]*)\s*-->\s*$/;
-/**
- * 解析自定义说明书正文：以 `<!-- actiondock:slot <name> -->` 标记行分段。
- * 首个标记之前的内容归入 `append` 槽位；未知槽位名直接抛错，避免拼写错误被静默吞掉。
- */
-export function parseCustomSections(source) {
-    const sections = [];
-    let currentSlot = "append";
-    let buffer = [];
-    const flush = () => {
-        const content = buffer.join("\n").trim();
-        buffer = [];
-        if (content) {
-            sections.push({ slot: currentSlot, content });
-        }
-    };
-    for (const line of source.split(/\r?\n/)) {
-        const match = line.match(CUSTOM_SLOT_MARKER_PATTERN);
-        if (match) {
-            flush();
-            const slot = match[1];
-            if (!COMPOSITE_CUSTOM_SLOTS.includes(slot)) {
-                throw new Error(`Unknown ActionDock custom slot '${match[1]}'. Valid slots: ${COMPOSITE_CUSTOM_SLOTS.join(", ")}`);
-            }
-            currentSlot = slot;
-            continue;
-        }
-        buffer.push(line);
-    }
-    flush();
-    return sections;
-}
-/**
- * 解析复合技能自定义说明书文件：支持 YAML frontmatter 中的 `description` 覆盖，
- * 正文按槽位标记解析为自定义段落。
- */
-export function parseCustomSkillDeclaration(source) {
-    let body = source;
-    let description;
-    const frontmatter = source.match(/^\uFEFF?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/);
-    if (frontmatter) {
-        body = source.slice(frontmatter[0].length);
-        const descLine = frontmatter[1].match(/^description:[ \t]*(.+?)[ \t]*$/m);
-        if (descLine) {
-            description = descLine[1].replace(/^["']|["']$/g, "");
-        }
-    }
-    return { description, sections: parseCustomSections(body) };
-}
 /**
  * 生成多包聚合的复合模式 SKILL.md 文档。
  */
@@ -463,28 +394,10 @@ ${playbookEntries.join("\n")}
         : "";
     const sInvoke = `## 标准调用命令
  
-推荐在执行前调用 describe 命令调阅确切参数契约：
-
-\`\`\`bash
-# 调阅参数契约与建议赋值样例
-ad describe ${sampleActionId}
-
-# 调用语法格式（其中 ASSIGNMENT 根据 ad describe 查阅的参数契约提供）
-ad run ${sampleActionId} --json -- ASSIGNMENT...
-\`\`\`
- 
-将参数写入 JSON 文件并通过 --input-file 传递：
- 
-\`\`\`bash
-ad run ${sampleActionId} --json --input-file input.json
-\`\`\`
+${renderInvocationGuidance(`ad describe ${sampleActionId}`, `ad run ${sampleActionId}`)}
 
 ${renderJsonEnvelopeSection("envelope", { withDescriptions: false })}`;
-    const sTroubleshooting = renderTroubleshootingSection({
-        dependencyStepLabel: "安装复合技能聚合依赖",
-        relinkStepLabel: "完成安装后重新链接复合技能",
-        compositeLinkNote: true,
-    });
+    const sTroubleshooting = renderTroubleshootingSection(RUNTIME_REFERENCE_REL_PATH);
     const parts = [
         { slot: "intro", text: sIntro },
         { slot: "after-describe", text: sDescribe },

package/dist/skill-md.d.ts

@@ -1,5 +1,5 @@
-import { type PlaybookDefinition, type ProjectConfig } from "@actiondock/core/project";
-import { type CompositeCustomDeclaration, type SkillActionItem } from "./skill/index.js";
+import { type ProjectConfig } from "@actiondock/core/project";
+import { type CompositeCustomDeclaration } from "./skill/index.js";
 import type { CompositeSkillExportOptions, SelectionPlan } from "./types.js";
 /**
  * SKILL.md 发现、复用与模板视图适配层。
@@ -7,16 +7,6 @@ import type { CompositeSkillExportOptions, SelectionPlan } from "./types.js";
  * 职责单一聚焦：定位项目中已有的 SKILL.md（单包与复合套件两种检索策略）、
  * 解析自定义说明书声明，并将规划产物适配为模板生成所需视图。
  */
-/** 供模板生成使用的 SkillActionItem 兼容视图 */
-type PlanActionView = SkillActionItem;
-/**
- * 将规划产物中的 Action 列表适配为模板所需的 SkillActionItem 视图。
- */
-export declare function toSkillActionItems(actions: SelectionPlan["actions"]): PlanActionView[];
-/**
- * 将规划产物中的 Playbook 列表适配为模板所需的 PlaybookDefinition 视图。
- */
-export declare function toPlaybookDefinitions(playbooks: SelectionPlan["playbooks"]): PlaybookDefinition[];
 /**
  * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
  */
@@ -36,7 +26,7 @@ export declare function resolveCustomSkillDeclaration(options: CompositeSkillExp
  * 复制或生成 SKILL.md 到目标目录。
  * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
  */
-export declare function writeSkillMd(root: string, destDir: string, plan: SelectionPlan, options: {
+export declare function writeSkillMd(root: string, destDir: string, options: {
     skipSkillMd?: boolean;
     skillMdPath?: string;
     pkgSlug: string;
@@ -45,4 +35,3 @@ export declare function writeSkillMd(root: string, destDir: string, plan: Select
  * 构造模板生成所需的 ProjectConfig 视图。
  */
 export declare function buildConfigForTemplates(plan: SelectionPlan, actionsDir: string, playbooksDir: string): ProjectConfig;
-export {};

package/dist/skill-md.js

@@ -4,17 +4,11 @@ import { getPackageSlug, } from "@actiondock/core/project";
 import { COMPOSITE_CUSTOM_DECLARATION_FILE, parseCustomSkillDeclaration, } from "./skill/index.js";
 import { BuilderError } from "./errors.js";
 /**
- * 将规划产物中的 Action 列表适配为模板所需的 SkillActionItem 视图。
+ * SKILL.md 发现、复用与模板视图适配层。
+ *
+ * 职责单一聚焦：定位项目中已有的 SKILL.md（单包与复合套件两种检索策略）、
+ * 解析自定义说明书声明，并将规划产物适配为模板生成所需视图。
  */
-export function toSkillActionItems(actions) {
-    return actions;
-}
-/**
- * 将规划产物中的 Playbook 列表适配为模板所需的 PlaybookDefinition 视图。
- */
-export function toPlaybookDefinitions(playbooks) {
-    return playbooks;
-}
 /**
  * 检索单个 Action 项目目录中已存在的 SKILL.md 文件。
  */
@@ -134,7 +128,7 @@ export function resolveCustomSkillDeclaration(options) {
  * 复制或生成 SKILL.md 到目标目录。
  * 返回实际复用的已有 SKILL.md 路径（若发生复用）。
  */
-export function writeSkillMd(root, destDir, plan, options, generate) {
+export function writeSkillMd(root, destDir, options, generate) {
     const existingSkill = options.skipSkillMd
         ? undefined
         : findExistingSingleSkillMd(root, options.skillMdPath, options.pkgSlug);

package/dist/types.d.ts

@@ -206,6 +206,25 @@ export interface BuildOptions {
     /** 是否跳过本地相对依赖完整性校验（默认 false） */
     skipDependencyValidation?: boolean;
 }
+/**
+ * 基于已规划依赖图的目录型交付产物生成选项。
+ */
+export interface BuildProjectWithPlanOptions {
+    /** 目标项目根目录绝对路径（可选，缺省时使用规划内 projectRoot） */
+    projectRoot?: string;
+    /** 产物输出目录路径（默认输出至 dist 目录） */
+    outDir?: string;
+    /** 输出路径别名 */
+    outfile?: string;
+    /** 是否生成标准 zip 压缩归档交付产物 */
+    archive?: boolean;
+    /** 是否在干净暂存目录中物化锁定的生产依赖 */
+    vendorDeps?: boolean;
+    /** 是否允许执行依赖安装生命周期脚本（默认 false） */
+    allowInstallScripts?: boolean;
+    /** 是否强制要求构建可复现（默认 false） */
+    requireReproducible?: boolean;
+}
 /**
  * 目录型构建产物结果描述。
  */
@@ -357,26 +376,6 @@ export interface SkillExportResult {
  * 导出 Skill 结果契约（对齐标准接口命名）。
  */
 export type ExportSkillResult = SkillExportResult;
-/**
- * 批量 Skill 导出选项。
- */
-export interface BatchSkillExportOptions extends Omit<SkillExporterOptions, "projectRoot"> {
-    /** 待导出的项目根目录绝对路径列表 */
-    projectRoots: string[];
-}
-/**
- * 批量 Skill 导出结果。
- */
-export interface BatchSkillExportResult {
-    /** 各包独立导出结果列表 */
-    results: SkillExportResult[];
-    /** 批量导出根目录 */
-    outDir: string;
-    /** 导出的总 Action 数量 */
-    totalActions: number;
-    /** 导出的总 Playbook 数量 */
-    totalPlaybooks: number;
-}
 /**
  * 复合 Skill 套件导出选项。
  */

package/dist/vendor.d.ts

@@ -0,0 +1,5 @@
+import type { SelectionPlan } from "./types.js";
+/**
+ * 物化锁定生产依赖到产物 node_modules 目录（vendorDeps 开启时）。
+ */
+export declare function vendorDependencies(root: string, stagingDir: string, plan: SelectionPlan): void;