@actiondock/core 2.0.0

package/src/doctor/index.ts

@@ -0,0 +1,2 @@
+export * from "./doctor";
+export * from "./types";

package/src/doctor/types.ts

@@ -0,0 +1,25 @@
+export type CheckStatus = "ok" | "warn" | "error";
+
+export interface DoctorCheckItem {
+  id: string;
+  category: "runtime" | "storage" | "registry" | "project";
+  name: string;
+  status: CheckStatus;
+  message: string;
+  detail?: string;
+  fix?: string;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  hasProject: boolean;
+  projectRoot?: string;
+  packageId?: string;
+  summary: {
+    total: number;
+    ok: number;
+    warn: number;
+    error: number;
+  };
+  checks: DoctorCheckItem[];
+}

package/src/export/index.ts

@@ -0,0 +1,2 @@
+export * from "./skill";
+export * from "./templates";

package/src/export/skill.ts

@@ -0,0 +1,349 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { buildProject } from "../build/builder";
+import {
+  discoverPlaybookFiles,
+  loadActionFileMap,
+  loadActions,
+  loadPlaybooks,
+  loadProjectConfig,
+} from "../project/loader";
+import type { ProjectConfig } from "../project/types";
+import { getPackageSlug } from "../utils";
+import { generateSkillJson, generateSkillMd, generateSourceSkillMd, generateStandaloneSkillMd } from "./templates";
+
+/**
+ * 导出 Agent Skill 产物时的配置选项。
+ */
+export interface ExportSkillOptions {
+  /** 源码项目根目录 */
+  projectRoot: string;
+  /** 导出模式：source (源码模式) 或 standalone (独立二进制模式) */
+  mode?: "source" | "standalone";
+  /** 是否强制独立二进制模式 */
+  standalone?: boolean;
+  /** 二进制编译目标架构（默认 host） */
+  target?: string;
+  /** 导出目录路径（默认 dist/skills/） */
+  outDir?: string;
+  /** 是否自动压缩打包为 .skill.tar.gz 归档包 */
+  archive?: boolean;
+  /** 按需挑选的 Playbook 列表（触发 Playbook-driven 最小化依赖 Tree-shaking 导出） */
+  playbooks?: string[];
+  /** 显式挑选导出的 Action ID 清单 */
+  actions?: string[];
+  /** 独立模式下是否开启代码混淆压缩 */
+  minify?: boolean;
+  /** 独立模式下是否编译为字节码 */
+  bytecode?: boolean;
+}
+
+/**
+ * Skill 导出完成后的产物描述结果。
+ */
+export interface ExportSkillResult {
+  /** 所属 Package ID */
+  packageId: string;
+  /** 版本号 */
+  version: string;
+  /** 导出模式 */
+  mode: "source" | "standalone";
+  /** 目标架构 */
+  target: string;
+  /** 生成的 Skill 目录绝对路径 */
+  skillDir: string;
+  /** 若开启了 archive，生成的 tar.gz 归档文件绝对路径 */
+  archivePath?: string;
+  /** 导出的 Action 数量 */
+  actionsCount: number;
+  /** 导出的 Playbook 数量 */
+  playbooksCount: number;
+}
+
+/**
+ * 将 ActionDock 项目导出为兼容各大 AI Agent 平台（如 Claude Desktop / Antigravity / Open-Interpreter 等）的通用 Agent Skill 规范包。
+ * 
+ * 支持两种模式：
+ * 1. source 源码模式：导出 SKILL.md + actiondock.json + 源码文件，配合 CLI 直接执行。
+ * 2. standalone 独立模式：导出 SKILL.md + 单文件独立二进制可执行文件，目标环境零依赖即跑。
+ * 
+ * 支持 Playbook 驱动的最小化 Tree-shaking 依赖裁剪。
+ * 
+ * @param options 导出配置选项
+ * @returns 导出产物详细结果
+ */
+export async function exportSkill(
+  options: ExportSkillOptions
+): Promise<ExportSkillResult> {
+  const root = resolve(options.projectRoot);
+  const config = loadProjectConfig(root);
+  const mode: "source" | "standalone" =
+    options.standalone || options.mode === "standalone" ? "standalone" : "source";
+  const target = options.target || "host";
+
+  const actionsMap = await loadActions(root, config.actionsDir);
+  const playbooksMap = loadPlaybooks(root, config.playbooksDir);
+
+  // Map each action ID to its corresponding source file path
+  const actionFileMap = await loadActionFileMap(root, config.actionsDir);
+
+  let selectedPlaybooks = Array.from(playbooksMap.values());
+  let selectedActions = Array.from(actionsMap.values());
+
+  // 1. If playbooks are explicitly specified (Playbook-driven minimal export)
+  if (options.playbooks && options.playbooks.length > 0) {
+    const specifiedPlaybookIds = new Set(options.playbooks);
+    const pbList = [];
+    for (const id of specifiedPlaybookIds) {
+      const pb = playbooksMap.get(id);
+      if (!pb) {
+        throw new Error(
+          `Playbook '${id}' specified in export options not found in project`
+        );
+      }
+      pbList.push(pb);
+    }
+    selectedPlaybooks = pbList;
+
+    // If actions were not explicitly specified, derive required actions from selected playbooks
+    if (!options.actions || options.actions.length === 0) {
+      const requiredActions = new Set<string>();
+      for (const pb of selectedPlaybooks) {
+        if (pb.actions) {
+          for (const act of pb.actions) {
+            requiredActions.add(act);
+          }
+        }
+      }
+      if (requiredActions.size > 0) {
+        for (const actId of requiredActions) {
+          if (!actionsMap.has(actId)) {
+            console.warn(
+              `[WARN] Action '${actId}' referenced in playbook is not found in project`
+            );
+          }
+        }
+        selectedActions = Array.from(actionsMap.values()).filter((a) =>
+          requiredActions.has(a.id)
+        );
+      }
+    }
+  }
+
+  // 2. If actions are explicitly specified (Action-driven export)
+  if (options.actions && options.actions.length > 0) {
+    const specifiedActionIds = new Set(options.actions);
+    for (const actId of specifiedActionIds) {
+      if (!actionsMap.has(actId)) {
+        throw new Error(
+          `Action '${actId}' specified in export options not found in project`
+        );
+      }
+    }
+    selectedActions = Array.from(actionsMap.values()).filter((a) =>
+      specifiedActionIds.has(a.id)
+    );
+
+    // If playbooks were not explicitly specified, tree-shake playbooks whose required actions are not included
+    if (!options.playbooks || options.playbooks.length === 0) {
+      selectedPlaybooks = selectedPlaybooks.filter((pb) => {
+        if (!pb.actions || pb.actions.length === 0) return true;
+        return pb.actions.every((a) => specifiedActionIds.has(a));
+      });
+    }
+  }
+
+  const pkgSlug = getPackageSlug(config.id);
+
+  const targetSuffix = mode === "standalone" && target !== "host" ? `-${target}` : "";
+  const skillFolderName = `${pkgSlug}-skill${targetSuffix}`;
+  const defaultSkillDir = join(root, "dist", skillFolderName);
+  const skillDir = resolve(options.outDir || defaultSkillDir);
+
+  const playbooksDestDir = join(skillDir, "playbooks");
+
+  if (mode === "source") {
+    // ----------------------------------------------------
+    // SOURCE SKILL EXPORT (Default)
+    // Structure: SKILL.md + actiondock.json + package.json + actions/* + playbooks/*
+    // ----------------------------------------------------
+    const actionsDestDir = join(skillDir, "actions");
+    mkdirSync(actionsDestDir, { recursive: true });
+    if (selectedPlaybooks.length > 0) {
+      mkdirSync(playbooksDestDir, { recursive: true });
+    }
+
+    // 1. Generate SKILL.md for Source Package
+    const skillMd = generateSourceSkillMd(
+      config,
+      selectedActions,
+      selectedPlaybooks
+    );
+    writeFileSync(join(skillDir, "SKILL.md"), skillMd, "utf-8");
+
+    // 2. Export tailored actiondock.json
+    const exportedConfig: Partial<ProjectConfig> = {
+      id: config.id,
+      name: config.name,
+      version: config.version,
+      description: config.description,
+      actionsDir: "actions",
+      playbooksDir: "playbooks",
+    };
+    if (config.config) {
+      exportedConfig.config = config.config;
+    }
+    writeFileSync(
+      join(skillDir, "actiondock.json"),
+      JSON.stringify(exportedConfig, null, 2) + "\n",
+      "utf-8"
+    );
+
+    // 3. Export package.json
+    const projectPkgJsonPath = join(root, "package.json");
+    if (existsSync(projectPkgJsonPath)) {
+      try {
+        const rawPkg = readFileSync(projectPkgJsonPath, "utf-8");
+        const parsedPkg = JSON.parse(rawPkg);
+        const exportedPkg = {
+          name: parsedPkg.name || pkgSlug,
+          version: config.version || parsedPkg.version || "0.1.0",
+          description: config.description || parsedPkg.description,
+          type: "module",
+          dependencies: parsedPkg.dependencies || {
+            "@actiondock/sdk": "^2.0.0",
+          },
+          devDependencies: parsedPkg.devDependencies,
+        };
+        writeFileSync(
+          join(skillDir, "package.json"),
+          JSON.stringify(exportedPkg, null, 2) + "\n",
+          "utf-8"
+        );
+      } catch {
+        copyFileSync(projectPkgJsonPath, join(skillDir, "package.json"));
+      }
+    } else {
+      const minimalPkg = {
+        name: pkgSlug,
+        version: config.version,
+        description: config.description,
+        type: "module",
+        dependencies: {
+          "@actiondock/sdk": "^2.0.0",
+        },
+      };
+      writeFileSync(
+        join(skillDir, "package.json"),
+        JSON.stringify(minimalPkg, null, 2) + "\n",
+        "utf-8"
+      );
+    }
+
+    // 4. Copy tsconfig.json if available
+    const tsconfigPath = join(root, "tsconfig.json");
+    if (existsSync(tsconfigPath)) {
+      copyFileSync(tsconfigPath, join(skillDir, "tsconfig.json"));
+    }
+
+    // 5. Copy selected action source files
+    for (const act of selectedActions) {
+      const entry = actionFileMap.get(act.id);
+      const srcPath = entry?.filePath;
+      if (srcPath && existsSync(srcPath)) {
+        copyFileSync(srcPath, join(actionsDestDir, basename(srcPath)));
+      }
+    }
+
+    // 6. Copy selected playbooks
+    for (const pb of selectedPlaybooks) {
+      if (pb.filePath && existsSync(pb.filePath)) {
+        const filename = basename(pb.filePath);
+        copyFileSync(pb.filePath, join(playbooksDestDir, filename));
+      }
+    }
+  } else {
+    // ----------------------------------------------------
+    // STANDALONE SKILL EXPORT (--standalone)
+    // Structure: SKILL.md + actiondock.skill.json + bin/<binary> + playbooks/*
+    // ----------------------------------------------------
+    const binDir = join(skillDir, "bin");
+    mkdirSync(binDir, { recursive: true });
+    if (selectedPlaybooks.length > 0) {
+      mkdirSync(playbooksDestDir, { recursive: true });
+    }
+
+    const binaryName = pkgSlug;
+    const binaryPath = join(binDir, binaryName);
+
+    // Build standalone binary with selected actions
+    const buildRes = await buildProject({
+      projectRoot: root,
+      target: options.target,
+      outfile: binaryPath,
+      actions: selectedActions.map((a) => a.id),
+      minify: options.minify,
+      bytecode: options.bytecode,
+    });
+
+    const actualBinaryName = basename(buildRes.executablePath);
+
+    // Generate SKILL.md for Standalone Binary
+    const skillMd = generateStandaloneSkillMd(
+      config,
+      selectedActions,
+      selectedPlaybooks,
+      `./bin/${actualBinaryName}`
+    );
+    writeFileSync(join(skillDir, "SKILL.md"), skillMd, "utf-8");
+
+    // Generate actiondock.skill.json
+    const skillJson = generateSkillJson(
+      config,
+      selectedActions,
+      actualBinaryName,
+      target
+    );
+    writeFileSync(join(skillDir, "actiondock.skill.json"), skillJson, "utf-8");
+
+    // Copy selected playbooks
+    for (const pb of selectedPlaybooks) {
+      if (pb.filePath && existsSync(pb.filePath)) {
+        const filename = basename(pb.filePath);
+        copyFileSync(pb.filePath, join(playbooksDestDir, filename));
+      }
+    }
+  }
+
+  let archivePath: string | undefined;
+  if (options.archive) {
+    const zipName = `${skillFolderName}.zip`;
+    archivePath = join(dirname(skillDir), zipName);
+    const zipProc = Bun.spawnSync(
+      ["zip", "-r", archivePath, basename(skillDir)],
+      {
+        cwd: dirname(skillDir),
+        stdout: "pipe",
+        stderr: "pipe",
+      }
+    );
+    if (zipProc.exitCode !== 0) {
+      console.warn(
+        `[WARN] Failed to create zip archive: ${zipProc.stderr.toString()}`
+      );
+      archivePath = undefined;
+    }
+  }
+
+  return {
+    packageId: config.id,
+    version: config.version,
+    mode,
+    target,
+    skillDir,
+    archivePath,
+    actionsCount: selectedActions.length,
+    playbooksCount: selectedPlaybooks.length,
+  };
+}
+

package/src/export/templates.ts

@@ -0,0 +1,258 @@
+import { basename } from "node:path";
+import type { ActionDefinition } from "@actiondock/sdk";
+import type { PlaybookDefinition, ProjectConfig } from "../project/types";
+
+function getCleanSkillMetadata(config: ProjectConfig) {
+  const cleanName = config.id.replace(/[^a-zA-Z0-9-_]/g, "-").toLowerCase();
+  const desc = config.description || `AI Agent skill for ${config.name} (${config.id})`;
+  return { cleanName, desc };
+}
+
+function renderActionListMarkdown(
+  actions: ActionDefinition[],
+  options: { packageId?: string } = {}
+): string {
+  return actions
+    .map((a) => {
+      const aDesc = a.description ? ` - ${a.description}` : "";
+      let params = "";
+      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 idLabel = options.packageId
+        ? `\`${options.packageId}/${a.id}\` (或 \`${a.id}\`)`
+        : `\`${a.id}\``;
+      return `* ${idLabel}${aDesc}${params}`;
+    })
+    .join("\n");
+}
+
+function renderPlaybookSectionMarkdown(playbooks: PlaybookDefinition[]): string {
+  if (playbooks.length === 0) return "";
+  const list = playbooks
+    .map((p) => {
+      const rel = `./playbooks/${basename(p.filePath)}`;
+      return `* **${p.id}** (\`${rel}\`): ${p.description || "任务指南"}`;
+    })
+    .join("\n");
+  return `
+## 任务指南 (Playbook SOPs)
+
+Playbook 为复杂任务提供逐步操作规程。详细 SOP 请阅读对应 Markdown 文档：
+
+${list}
+`;
+}
+
+export function generateSourceSkillMd(
+  config: ProjectConfig,
+  actions: ActionDefinition[],
+  playbooks: PlaybookDefinition[]
+): string {
+  const { cleanName, desc } = getCleanSkillMetadata(config);
+  const pkgId = config.id;
+  const firstAction = actions[0]?.id || "sample.greet";
+
+  const actionListMd = renderActionListMarkdown(actions, { packageId: pkgId });
+  const playbookSection = renderPlaybookSectionMarkdown(playbooks);
+
+  return `---
+name: ${cleanName}
+description: ${desc}
+---
+
+# ${config.name} (${config.id})
+
+${desc}
+
+## ActionDock 运行时 (ActionDock Runtime)
+
+本技能为 **ActionDock 源码型 Package (Source Skill)**。AI Agent 可直接通过已安装的 ActionDock 命令行工具 (\`ac\`) 执行其中的 Action。
+
+### 注册与链接 (Idempotent Setup)
+
+在初次调用或初始化时，将包含本 \`SKILL.md\` 的目录解析为 \`<skill_root>\` 并完成注册：
+
+\`\`\`bash
+ac link "<skill_root>"
+\`\`\`
+
+> \`ac link\` 天然具备幂等性，同一 Package 多次执行会直接更新路径，可安全重复调用。
+
+### 执行 Action (统一推荐 Package-Qualified ID)
+
+为避免多技能之间的 Action ID 命名冲突，建议统一使用带有 Package 前缀的完全限定 ID：
+
+\`\`\`bash
+# 格式：ac run <package-id>/<action-id> --input '<json>'
+ac run ${pkgId}/${firstAction} --input '{"param": "value"}'
+\`\`\`
+
+> **免注册本地执行 (Direct Execution Alternative)**:
+> 若 Agent 工作目录已位于本 Skill 根目录，亦可直接免 link 执行：
+> \`\`\`bash
+> cd <skill_root>
+> ac run <action-id> --input '<json>'
+> \`\`\`
+
+所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON Envelope：
+\`\`\`json
+{
+  "ok": true,
+  "runId": "01J...",
+  "data": { ... }
+}
+\`\`\`
+日志与诊断信息输出至 \`stderr\`。
+
+---
+
+## Action 目录
+
+${actionListMd}
+${playbookSection}
+---
+
+## 运行时配置与持久化状态
+
+如需检查或配置该 Package 的运行时参数与持久化数据：
+
+\`\`\`bash
+# 查看与设置配置项
+ac config list --package ${pkgId}
+ac config set KEY VALUE --package ${pkgId}
+
+# 查看与检索状态数据
+ac state list --package ${pkgId}
+ac state get KEY --package ${pkgId}
+\`\`\`
+`;
+}
+
+export function generateStandaloneSkillMd(
+  config: ProjectConfig,
+  actions: ActionDefinition[],
+  playbooks: PlaybookDefinition[],
+  binaryRelPath = "./bin/action-bin"
+): string {
+  const { cleanName, desc } = getCleanSkillMetadata(config);
+  const firstAction = actions[0]?.id || "sample.greet";
+
+  const actionListMd = renderActionListMarkdown(actions);
+  const playbookSection = renderPlaybookSectionMarkdown(playbooks);
+
+  return `---
+name: ${cleanName}
+description: ${desc}
+---
+
+# ${config.name} (${config.id})
+
+${desc}
+
+## 如何调用 Action
+
+使用 Skill 目录中自带的独立可执行文件 \`${binaryRelPath}\` 即可完成工具发现与调用。
+**该工具无需在系统预先安装任何依赖**（无需安装 Node.js、Bun、Python 或 Java）。
+
+### 发现可用 Action 清单
+\`\`\`bash
+${binaryRelPath} list --json
+\`\`\`
+
+### 查看 Action 结构与入参 Schema
+\`\`\`bash
+${binaryRelPath} describe <action-id> --json
+\`\`\`
+
+### 执行 Action
+\`\`\`bash
+${binaryRelPath} run <action-id> --input '{"param": "value"}'
+
+# 示例：
+${binaryRelPath} run ${firstAction} --input '{"param": "value"}'
+\`\`\`
+
+所有 Action 执行结果均在 \`stdout\` 输出标准格式的 JSON 结果：
+\`\`\`json
+{
+  "ok": true,
+  "runId": "01J...",
+  "data": { ... }
+}
+\`\`\`
+日志与诊断信息输出至 \`stderr\`。
+
+---
+
+## Action 目录
+
+${actionListMd}
+${playbookSection}
+---
+
+## 运行时配置与持久化状态
+
+独立二进制会自动管理其本地 SQLite 数据库。如需检查或配置：
+
+\`\`\`bash
+# 查看与设置配置项
+${binaryRelPath} config list
+${binaryRelPath} config set KEY VALUE
+
+# 查看与检索状态数据
+${binaryRelPath} state list
+${binaryRelPath} state get KEY
+\`\`\`
+`;
+}
+
+export function generateSkillMd(
+  config: ProjectConfig,
+  actions: ActionDefinition[],
+  playbooks: PlaybookDefinition[],
+  optionsOrBinaryPath: string | { mode?: "source" | "standalone"; binaryRelPath?: string } = "./bin/action-bin"
+): string {
+  if (typeof optionsOrBinaryPath === "string") {
+    return generateStandaloneSkillMd(config, actions, playbooks, optionsOrBinaryPath);
+  }
+  if (optionsOrBinaryPath.mode === "source") {
+    return generateSourceSkillMd(config, actions, playbooks);
+  }
+  return generateStandaloneSkillMd(config, actions, playbooks, optionsOrBinaryPath.binaryRelPath || "./bin/action-bin");
+}
+
+export function generateSkillJson(
+  config: ProjectConfig,
+  actions: ActionDefinition[],
+  binaryName: string,
+  target: string
+): string {
+  const manifest = {
+    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(),
+  };
+
+  return JSON.stringify(manifest, null, 2) + "\n";
+}
+

package/src/filter/index.ts

@@ -0,0 +1 @@
+export * from "./intent";