@actiondock/core 2.0.9 → 2.0.11-beta.0

package/src/export/templates.ts

@@ -15,24 +15,78 @@ function renderActionListMarkdown(
   return actions
     .map((a) => {
       const aDesc = a.description ? ` - ${a.description}` : "";
-      let params = "";
+      const idLabel = options.packageId
+        ? `\`${options.packageId}/${a.id}\` (或 \`${a.id}\`)`
+        : `\`${a.id}\``;
+
+      const lines: string[] = [`- ${idLabel}${aDesc}`];
+
+      // 标注元数据解析
+      if (a.annotations && typeof a.annotations === "object") {
+        const annoList: string[] = [];
+        if ((a.annotations as any).readOnly === true) {
+          annoList.push("只读操作");
+        }
+        if ((a.annotations as any).destructive === true) {
+          annoList.push("破坏性操作（执行前须向用户确认）");
+        }
+        if (annoList.length > 0) {
+          lines.push(`  - 属性标注: ${annoList.join(", ")}`);
+        }
+      }
+
+      // 输入参数模式解析
       if (
         a.inputSchema &&
         typeof a.inputSchema === "object" &&
         (a.inputSchema as any).properties
       ) {
-        const props = Object.keys((a.inputSchema as any).properties);
-        const req = (a.inputSchema as any).required || [];
-        params = `\n  - 参数列表: ${props
-          .map((p) => (req.includes(p) ? `\`${p}\` (必填)` : `\`${p}\``))
-          .join(", ")}`;
+        const props = (a.inputSchema as any).properties as Record<string, any>;
+        const req = ((a.inputSchema as any).required || []) as string[];
+        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("  - 输入参数: 无");
       }
-      const idLabel = options.packageId
-        ? `\`${options.packageId}/${a.id}\` (或 \`${a.id}\`)`
-        : `\`${a.id}\``;
-      return `- ${idLabel}${aDesc}${params}`;
+
+      // 输出字段模式解析
+      if (
+        a.outputSchema &&
+        typeof a.outputSchema === "object" &&
+        (a.outputSchema as any).properties
+      ) {
+        const outProps = (a.outputSchema as any).properties as Record<string, any>;
+        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");
+    .join("\n\n");
 }
 
 function renderPlaybookSectionMarkdown(playbooks: PlaybookDefinition[]): string {
@@ -40,13 +94,16 @@ function renderPlaybookSectionMarkdown(playbooks: PlaybookDefinition[]): string
   const list = playbooks
     .map((p) => {
       const rel = `./playbooks/${basename(p.filePath)}`;
-      return `- **${p.id}** (\`${rel}\`): ${p.description || "任务指南"}`;
+      return `- **${p.id}** (\`${rel}\`): ${p.description || "业务操作指南"}`;
     })
     .join("\n");
   return `
-## 任务指南 (Playbook SOPs)
+## 业务操作规程
+
+> [!IMPORTANT]
+> **规程优先准则**：当处理复合业务任务时，智能体必须优先检查是否存在匹配场景的 Playbook。若存在规程，必须优先查阅并严格遵循规程界定的步骤时序与校验逻辑推进，严禁无序拼凑调用底层 Action。
 
-Playbook 为复杂任务提供逐步操作规程。详细 SOP 请阅读对应 Markdown 文档：
+Playbook SOPs 为复杂业务任务提供逐步指导规程。详细规程请查阅对应文档：
 
 ${list}
 `;
@@ -61,8 +118,8 @@ export function generateSourceSkillMd(
   const pkgId = config.id;
   const firstAction = actions[0]?.id || "sample.greet";
 
-  const actionListMd = renderActionListMarkdown(actions, { packageId: pkgId });
   const playbookSection = renderPlaybookSectionMarkdown(playbooks);
+  const actionListMd = renderActionListMarkdown(actions, { packageId: pkgId });
 
   return `---
 name: ${cleanName}
@@ -75,7 +132,7 @@ ${desc}
 
 ## ActionDock 运行时
 
-本技能为 **ActionDock 源码型技能包**。AI Agent 可直接通过已安装的 ActionDock 命令行工具 (\`ad\`) 执行其中的 Action。
+本技能为 **ActionDock 源码型技能包**。智能体可直接通过宿主环境中已安装的 ActionDock 命令行工具 \`ad\` 执行其中的 Action。
 
 ### 注册与链接
 
@@ -87,38 +144,75 @@ ad link "<skill_root>"
 
 > \`ad link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。
 
+### 动作参数契约按需调阅
+
+在调用未知参数的 Action 前，可在终端执行命令按需查阅该 Action 的输入输出模式与详细说明：
+
+\`\`\`bash
+ad action show ${pkgId}/${firstAction}
+\`\`\`
+
 ### 执行 Action
 
-为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID：
+为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID。
+
+推荐最佳实践：使用文件传递参数，杜绝终端引号转义问题：
+
+\`\`\`bash
+# 写入参数到临时文件并通过 --input-file 传递
+cat << 'EOF' > /tmp/input.json
+{
+  "param": "value"
+}
+EOF
+ad run ${pkgId}/${firstAction} --input-file /tmp/input.json
+\`\`\`
+
+亦可通过内联参数进行简易命令调用：
 
 \`\`\`bash
-# 格式：ad run <package-id>/<action-id> --input '<json>'
 ad run ${pkgId}/${firstAction} --input '{"param": "value"}'
 \`\`\`
 
 > **免注册本地执行**：
-> 若 Agent 工作目录已位于本 Skill 根目录，亦可直接免 link 执行：
+> 若工作目录已位于本技能根目录，亦可直接免 link 执行：
 > \`\`\`bash
 > cd <skill_root>
-> ad run <action-id> --input '<json>'
+> ad run <action-id> --input-file /tmp/input.json
 > \`\`\`
 
-所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON Envelope：
+### 结构化响应解析
+
+所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON 信封：
+
 \`\`\`json
+// 执行成功响应 (ok 为 true)
 {
   "ok": true,
   "runId": "01J...",
   "data": { ... }
 }
+
+// 执行失败响应 (ok 为 false)
+{
+  "ok": false,
+  "runId": "01J...",
+  "error": {
+    "code": "ACTION_EXECUTION_FAILED",
+    "message": "错误详细描述信息"
+  }
+}
 \`\`\`
-日志与诊断信息输出至 \`stderr\`。
 
+- \`stdout\`：标准 JSON 信封结果。当 \`ok\` 为 \`true\` 时，从 \`data\` 提取业务返回值推进后续步骤；当 \`ok\` 为 \`false\` 时，从 \`error\` 提取错误码与信息以判定自愈策略或上报。
+- \`stderr\`：执行日志与诊断跟踪信息。
+${playbookSection}
 ---
 
 ## Action 目录
 
 ${actionListMd}
-${playbookSection}
+
 ---
 
 ## 运行时配置与持久化状态
@@ -140,39 +234,26 @@ ad state get KEY --package ${pkgId}
 ## 故障排查与环境安装指引（按需查阅）
 
 > [!NOTE]
-> **按需排查原则**：默认宿主环境中已预置 \`ad\` 命令行工具。正常执行流程直接调用上述 Action 即可，**严禁在任务启动前盲目进行前置环境检查或体检**；仅在终端明确报错提示命令不存在（如 \`ad: command not found\`）时，方可按本节指引安装初始化。
+> **按需排查原则**：默认宿主环境中已预置 \`ad\` 命令行工具与 Node.js 运行环境。正常执行流程直接调用上述 Action 即可，**严禁在任务启动前盲目进行前置环境检查或体检**；仅在终端明确报错提示命令不存在（如 \`ad: command not found\`）时，方可按本节指引安装初始化。
 
 ### 命令行工具未找到时的安装指引
 
 若宿主环境未安装 \`ad\` 命令行工具，请依次按如下步骤完成安装：
 
-- **安装 Bun 运行时**（若系统未安装）：
-  \`\`\`bash
-  npm install -g bun
-  \`\`\`
-
+- **环境要求**：Node.js 版本大于等于 22.12.0（执行 \`node -v\` 确认）。
 - **全局安装 ActionDock 命令行工具**：
   \`\`\`bash
   npm install -g @actiondock/cli
   \`\`\`
-
 - **验证工具就绪**：
   \`\`\`bash
   ad --version
   \`\`\`
-
-- **源码本地开发模式**（若在本地源码仓库中贡献或开发）：
-  \`\`\`bash
-  cd packages/cli && npm link
-  cd ../sdk && bun link
-  \`\`\`
-
 - **环境诊断与体检**：
   安装完成后若仍遇到异常，执行体检命令排查：
   \`\`\`bash
   ad doctor
   \`\`\`
-
 - **完成安装后重新链接本技能**：
   \`\`\`bash
   ad link "<skill_root>"
@@ -189,8 +270,8 @@ export function generateStandaloneSkillMd(
   const { cleanName, desc } = getCleanSkillMetadata(config);
   const firstAction = actions[0]?.id || "sample.greet";
 
-  const actionListMd = renderActionListMarkdown(actions);
   const playbookSection = renderPlaybookSectionMarkdown(playbooks);
+  const actionListMd = renderActionListMarkdown(actions);
 
   return `---
 name: ${cleanName}
@@ -203,48 +284,78 @@ ${desc}
 
 ## 如何调用 Action
 
-使用 Skill 目录中自带的独立可执行文件 \`${binaryRelPath}\` 即可完成工具发现与调用。
+使用技能目录中自带的独立可执行程序 \`${binaryRelPath}\` 即可完成工具发现与调用。
 **该工具无需在系统预先安装任何依赖**（无需安装 Node.js、Bun、Python 或 Java）。
 
 ### 发现可用 Action 清单
+
 \`\`\`bash
 ${binaryRelPath} list --json
 \`\`\`
 
-### 查看 Action 结构与入参 Schema
+### 查看 Action 结构与入参规范
+
 \`\`\`bash
 ${binaryRelPath} describe <action-id> --json
 \`\`\`
 
 ### 执行 Action
+
+推荐最佳实践：使用文件传递参数，杜绝终端引号转义问题：
+
 \`\`\`bash
-${binaryRelPath} run <action-id> --input '{"param": "value"}'
+# 写入参数到临时文件并通过 --input-file 传递
+cat << 'EOF' > /tmp/input.json
+{
+  "param": "value"
+}
+EOF
+${binaryRelPath} run <action-id> --input-file /tmp/input.json
+\`\`\`
+
+亦可通过内联参数进行简易命令调用：
 
-# 示例：
+\`\`\`bash
 ${binaryRelPath} run ${firstAction} --input '{"param": "value"}'
 \`\`\`
 
+### 结构化响应解析
+
 所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON 结果：
+
 \`\`\`json
+// 执行成功响应 (ok 为 true)
 {
   "ok": true,
   "runId": "01J...",
   "data": { ... }
 }
+
+// 执行失败响应 (ok 为 false)
+{
+  "ok": false,
+  "runId": "01J...",
+  "error": {
+    "code": "ACTION_EXECUTION_FAILED",
+    "message": "错误详细描述信息"
+  }
+}
 \`\`\`
-日志与诊断信息输出至 \`stderr\`。
 
+- \`stdout\`：标准 JSON 结果信封。当 \`ok\` 为 \`true\` 时，从 \`data\` 提取业务数据；当 \`ok\` 为 \`false\` 时，从 \`error\` 读取错误原因以处理异常。
+- \`stderr\`：执行日志与诊断信息。
+${playbookSection}
 ---
 
 ## Action 目录
 
 ${actionListMd}
-${playbookSection}
+
 ---
 
 ## 运行时配置与持久化状态
 
-独立二进制会自动管理其本地 SQLite 数据库。如需检查或配置：
+独立二进制程序会自动管理其本地 SQLite 数据库。如需检查或配置：
 
 \`\`\`bash
 # 查看与设置配置项
@@ -273,29 +384,207 @@ export function generateSkillMd(
   return generateStandaloneSkillMd(config, actions, playbooks, optionsOrBinaryPath.binaryRelPath || "./bin/action-bin");
 }
 
+export interface CompositeSkillPackageInfo {
+  config: ProjectConfig;
+  actions: Array<{ id: string; description?: string }>;
+  playbooks: Array<{ id: string; name?: string; description?: string; filePath: string }>;
+  packageDir: string;
+}
+
+/**
+ * 生成多包聚合的复合模式 SKILL.md 文档。
+ */
+export function generateCompositeSkillMd(
+  bundleName: string,
+  description: string,
+  packages: CompositeSkillPackageInfo[]
+): string {
+  const cleanName = bundleName.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
+  const samplePkg = packages.find((p) => p.actions && p.actions.length > 0);
+  const sampleActionId = samplePkg
+    ? `${samplePkg.config.id}/${samplePkg.actions[0].id}`
+    : "sample.greet";
+
+  const actionSections = packages
+    .map((pkg) => {
+      const actList = pkg.actions
+        .map((a) => {
+          const desc = a.description ? `: ${a.description}` : "";
+          return `- \`${pkg.config.id}/${a.id}\`${desc}`;
+        })
+        .join("\n");
+      return `### ${pkg.config.name} (${pkg.config.id})\n${actList || "- 无可用 Action"}`;
+    })
+    .join("\n\n");
+
+  const playbookEntries: string[] = [];
+  for (const pkg of packages) {
+    for (const pb of pkg.playbooks) {
+      const relPath = `packages/${pkg.packageDir}/playbooks/${basename(pb.filePath)}`;
+      playbookEntries.push(`- [${pb.name || pb.id}](${relPath}): ${pb.description || "标准操作规程"}`);
+    }
+  }
+
+  const playbookSection =
+    playbookEntries.length > 0
+      ? `## 推荐操作规程\n\n涉及多步骤或业务流程时，优先遵循以下原位规程：\n\n${playbookEntries.join("\n")}\n\n---\n`
+      : "";
+
+  return `---
+name: ${cleanName}
+description: ${description}
+---
+
+# ${bundleName} 复合技能套件
+
+${description}
+
+## ActionDock 运行时初始化
+
+本技能为 **ActionDock 复合工作区技能包**，聚合了多个功能包。智能体在初次调用或初始化时，在当前技能根目录执行注册命令：
+
+\`\`\`bash
+ad link "<skill_root>"
+\`\`\`
+
+> \`ad link\` 会自动识别并注册工作区下的所有子包，使其中的 Action 随时可以通过完全限定标识调用。
+
+## 动作参数契约按需调阅
+
+为节省上下文开销，各 Action 的详细参数结构不静态内嵌在说明书中。在调用未知参数的 Action 前，可在终端执行命令查阅输入输出约束：
+
+\`\`\`bash
+ad action show ${sampleActionId}
+\`\`\`
+
+## 可用 Action 工具清单
+
+${actionSections}
+
+---
+
+${playbookSection}
+## 标准调用命令
+
+推荐使用参数文件传递内容，杜绝终端引号转义问题：
+
+\`\`\`bash
+cat << 'EOF' > /tmp/input.json
+{
+  "param": "value"
+}
+EOF
+ad run ${sampleActionId} --input-file /tmp/input.json
+\`\`\`
+
+### 结构化响应解析
+
+所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON 信封：
+
+\`\`\`json
+// 执行成功响应 (ok 为 true)
+{
+  "ok": true,
+  "runId": "01J...",
+  "data": { ... }
+}
+
+// 执行失败响应 (ok 为 false)
+{
+  "ok": false,
+  "runId": "01J...",
+  "error": {
+    "code": "ACTION_EXECUTION_FAILED",
+    "message": "错误详细描述信息"
+  }
+}
+\`\`\`
+`;
+}
+
+
+export interface GenerateSkillJsonOptions {
+  mode?: "source" | "standalone";
+  executable?: string;
+  target?: string;
+  playbooks?: PlaybookDefinition[];
+}
+
 export function generateSkillJson(
   config: ProjectConfig,
   actions: ActionDefinition[],
-  binaryName: string,
-  target: string
+  binaryNameOrOptions?: string | GenerateSkillJsonOptions,
+  target = "host",
+  playbooksList: PlaybookDefinition[] = []
 ): string {
-  const manifest = {
+  let mode: "source" | "standalone" = "source";
+  let executable: string | undefined;
+  let targetPlatform = target;
+  let playbooks = playbooksList;
+
+  if (typeof binaryNameOrOptions === "string") {
+    mode = "standalone";
+    executable = `./bin/${binaryNameOrOptions}`;
+  } else if (binaryNameOrOptions && typeof binaryNameOrOptions === "object") {
+    mode = binaryNameOrOptions.mode || (binaryNameOrOptions.executable ? "standalone" : "source");
+    executable = binaryNameOrOptions.executable;
+    targetPlatform = binaryNameOrOptions.target || target;
+    if (binaryNameOrOptions.playbooks) {
+      playbooks = binaryNameOrOptions.playbooks;
+    }
+  }
+
+  const manifest: Record<string, unknown> = {
     schemaVersion: "2.0.0",
     packageId: config.id,
     name: config.name,
     version: config.version,
     description: config.description,
-    target,
-    executable: `./bin/${binaryName}`,
-    actions: actions.map((a) => ({
-      id: a.id,
-      description: a.description,
-      inputSchema: a.inputSchema,
-      outputSchema: a.outputSchema,
-    })),
-    exportedAt: new Date().toISOString(),
+    mode,
   };
 
+  if (mode === "standalone" && executable) {
+    manifest.target = targetPlatform;
+    manifest.executable = executable;
+  }
+
+  manifest.actions = actions.map((a: any) => {
+    const item: Record<string, unknown> = {
+      id: a.id,
+    };
+    if (a.entry) {
+      item.entry = a.entry;
+    }
+    if (a.description) {
+      item.description = a.description;
+    }
+    if (a.inputSchema !== undefined) {
+      item.inputSchema = a.inputSchema;
+    }
+    if (a.outputSchema !== undefined) {
+      item.outputSchema = a.outputSchema;
+    }
+    if (a.uses) {
+      item.uses = a.uses;
+    }
+    if (a.tags) {
+      item.tags = a.tags;
+    }
+    if (a.annotations) {
+      item.annotations = a.annotations;
+    }
+    return item;
+  });
+
+  if (playbooks && playbooks.length > 0) {
+    manifest.playbooks = playbooks.map((p) => ({
+      id: p.id,
+      description: p.description,
+      entry: `playbooks/${basename(p.filePath)}`,
+    }));
+  }
+
+  manifest.exportedAt = new Date().toISOString();
+
   return JSON.stringify(manifest, null, 2) + "\n";
 }
-

package/src/index.ts

@@ -12,4 +12,5 @@ export * from "./schema/validator";
 export * from "./server";
 export * from "./storage";
 export * from "./utils";
+export type { ModuleLoader } from "./runtime";
 

package/src/project/init.ts

@@ -108,10 +108,10 @@ export function initProject(targetDir: string, options: InitOptions = {}): void
       node: ">=22.12.0",
     },
     dependencies: {
-      "@actiondock/sdk": "^2.0.9",
+      "@actiondock/sdk": "2.0.11-beta.0",
     },
     devDependencies: {
-      "@actiondock/testing": "^2.0.9",
+      "@actiondock/testing": "2.0.11-beta.0",
       "@types/node": "^22.12.0",
       "tsx": "^4.19.0",
       "typescript": "^5.7.0",
@@ -157,6 +157,7 @@ build/
 export default defineAction({
   id: "sample.greet",
   description: "Greeting action demonstrating basic input, config, and state usage",
+  tags: ["sample"],
 
   inputSchema: {
     type: "object",

package/src/project/loader.ts

@@ -5,6 +5,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import YAML from "yaml";
 import type { ActionDefinition } from "@actiondock/sdk";
+import { getModuleLoader } from "../runtime/module-loader";
 import type { PlaybookDefinition, PlaybookFrontmatter, ProjectConfig } from "./types";
 
 /**
@@ -273,13 +274,14 @@ export async function loadActions(
 
   const files = discoverActionFiles(projectRoot, actionsDir);
   const actions = new Map<string, ActionDefinition>();
+  const loader = getModuleLoader();
 
   for (const file of files) {
     try {
       // 动态导入，若缺失模块则自动触发依赖重装与二次重试
       let imported: any;
       try {
-        imported = await import(toImportSpecifier(file));
+        imported = await loader.load(file);
       } catch (err: any) {
         const msg = String(err.message || "");
         if (
@@ -291,7 +293,7 @@ export async function loadActions(
         ) {
           const installed = ensureProjectDependencies(projectRoot, true);
           if (installed) {
-            imported = await import(toImportSpecifier(file));
+            imported = await loader.load(file);
           } else {
             throw err;
           }
@@ -331,28 +333,65 @@ export interface ActionFileEntry {
 }
 
 /**
- * 加载并建立 Action ID 与其物理源码文件路径之间的映射关系（供构建打包器使用）。
+ * 加载并建立 Action ID 与其物理源码文件路径之间的映射关系（供构建打包器及清单同步使用）。
  */
 export async function loadActionFileMap(
   projectRoot: string,
-  actionsDir = "actions"
+  actionsDir = "actions",
+  options: { autoInstall?: boolean; strict?: boolean } = { autoInstall: true, strict: false }
 ): Promise<Map<string, ActionFileEntry>> {
+  if (options.autoInstall !== false) {
+    ensureProjectDependencies(projectRoot);
+  }
+
   const files = discoverActionFiles(projectRoot, actionsDir);
   const map = new Map<string, ActionFileEntry>();
+  const loader = getModuleLoader();
 
   for (const file of files) {
     try {
-      const imported = await import(toImportSpecifier(file));
+      let imported: any;
+      try {
+        imported = await loader.load(file);
+      } catch (err: any) {
+        const msg = String(err.message || "");
+        if (
+          options.autoInstall !== false &&
+          (msg.includes("Cannot find package") ||
+            msg.includes("Cannot find module") ||
+            msg.includes("ERR_MODULE_NOT_FOUND") ||
+            msg.includes("Could not resolve"))
+        ) {
+          const installed = ensureProjectDependencies(projectRoot, true);
+          if (installed) {
+            imported = await loader.load(file);
+          } else {
+            throw err;
+          }
+        } else {
+          throw err;
+        }
+      }
+
       const act = imported.default || imported.action;
       if (act && typeof act === "object" && typeof act.id === "string") {
+        if (map.has(act.id)) {
+          throw new Error(
+            `Duplicate action ID '${act.id}' found in ${file} (previously loaded from ${map.get(act.id)!.filePath})`
+          );
+        }
         map.set(act.id, {
           id: act.id,
           filePath: resolve(file),
           action: act,
         });
+      } else if (options.strict) {
+        console.warn(`[WARN] File ${file} does not export a valid default ActionDefinition`);
+      }
+    } catch (err: any) {
+      if (options.strict) {
+        throw new Error(`Failed to load action from ${file}: ${err.message}`);
       }
-    } catch {
-      // 忽略非 Action 导出的辅助模块
     }
   }