@work2cn/core

work2 技能市场框架的协议内核，为技能开发者提供类型定义和辅助函数。

安装

npm install @work2cn/core

快速开始

const { defineSkill, createInitSuccess, createStatusResponse } = require("@work2cn/core");

module.exports = defineSkill({
  slug: "my-skill",
  displayName: "我的技能",
  targets: ["claude-code"],

  lifecycle: {
    async init(args) {
      await saveConfig(args);
      return createInitSuccess({ skill: "my-skill", summary: args });
    },
    async status() {
      const config = await loadConfig();
      return createStatusResponse({ configured: !!config });
    }
  }
});

API 参考

defineSkill(config)

定义一个技能包。

interface SkillConfig {
  // 必填
  slug: string;              // 技能唯一标识 (kebab-case)
  displayName: string;       // 显示名称
  targets: TargetPlatform[]; // 支持的平台: "claude-code" | "openclaw" | "codex"
  lifecycle: LifecycleFunctions;

  // 可选
  description?: string;
  version?: string;
  author?: string;
  configSchema?: ConfigSchema;
}

生命周期函数

| 函数 | 必需 | 说明 | |------|------|------| | init(args) | ✅ | 接收用户配置，执行初始化 | | status() | ✅ | 检查当前配置状态 | | verify(args) | ❌ | 验证回调（用于验证码等场景） | | enable() | ❌ | 启用技能 | | disable() | ❌ | 禁用技能 |

配置 Schema

定义技能需要的配置字段，用于 Web 端渲染表单：

configSchema: {
  fields: [
    {
      key: "apiKey",
      label: "API Key",
      inputType: "password",  // text | password | email | number | textarea | select | checkbox | url
      required: true,
      placeholder: "请输入 API Key",
      help: {
        text: "如何获取？",
        url: "https://example.com/docs",
        steps: ["步骤1", "步骤2"]
      },
      rules: {
        minLength: 10,
        maxLength: 100,
        pattern: "^sk-",
        patternMessage: "API Key 必须以 sk- 开头"
      }
    }
  ]
}

响应构建器

createInitSuccess(options?)

配置成功完成时返回：

return createInitSuccess({
  skill: "my-skill",
  summary: { email: "[email protected]" },
  configPath: "/path/to/config.json"
});

// 输出:
// { ok: true, status: "completed", skill: "my-skill", summary: {...}, updatedAt: "..." }

createInitFailed(error, options?)

配置失败时返回：

return createInitFailed("邮箱格式不正确", { skill: "my-skill" });

// 输出:
// { ok: false, status: "failed", error: "邮箱格式不正确", skill: "my-skill" }

createInitPending(interaction, options?)

需要用户交互时返回（OAuth、扫码、验证码等）：

// OAuth 场景
return createInitPending({
  type: "oauth",
  title: "授权登录",
  authUrl: "https://example.com/oauth/authorize?...",
  callbackUrl: "https://work2.cn/callback"
});

// 扫码场景
return createInitPending({
  type: "qrcode",
  title: "扫码登录",
  qrcode: { url: "https://example.com/qr.png" },
  pollUrl: "/api/check-status",
  pollInterval: 2000,
  expiresAt: "2026-04-03T12:00:00Z"
});

// 验证码场景
return createInitPending({
  type: "verify_code",
  title: "验证邮箱",
  message: "验证码已发送",
  codeLength: 6,
  codeSentTo: "t***@qq.com",
  submitAction: "verify"
});

交互类型：oauth | qrcode | verify_code | upload | manual

createStatusResponse(options)

状态检查时返回：

// 已配置
return createStatusResponse({
  configured: true,
  skill: "my-skill",
  summary: { email: "[email protected]" }
});

// 未配置
return createStatusResponse({
  configured: false,
  configExists: true,
  missing: ["apiKey"],
  invalid: ["email"]
});

createRuntimeEvent(options)

技能运行时需要用户干预时返回：

return createRuntimeEvent({
  event: "auth_expired",      // 事件类型
  severity: "blocking",       // blocking | warning | info
  message: "授权已过期，请重新登录",
  interaction: {
    type: "qrcode",
    title: "重新授权",
    qrcode: { url: "https://..." }
  },
  resumeAction: "retry",      // 用户完成后调用的 action
  resumeArgs: { ... },        // 恢复时传递的参数
  skill: "my-skill"
});

事件类型：auth_required | auth_expired | verification | user_action | rate_limited | captcha

完整示例

const {
  defineSkill,
  createInitSuccess,
  createInitFailed,
  createInitPending,
  createStatusResponse,
  createRuntimeEvent
} = require("@work2cn/core");
const fs = require("fs");
const path = require("path");

const CONFIG_PATH = path.join(process.env.HOME, ".my-skill.json");

function loadConfig() {
  try {
    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"));
  } catch {
    return null;
  }
}

function saveConfig(config) {
  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
}

module.exports = defineSkill({
  slug: "my-skill",
  displayName: "我的技能",
  description: "这是一个示例技能",
  version: "1.0.0",
  targets: ["claude-code", "openclaw"],

  configSchema: {
    fields: [
      {
        key: "email",
        label: "邮箱地址",
        inputType: "email",
        required: true,
        showInSummary: true
      },
      {
        key: "token",
        label: "访问令牌",
        inputType: "password",
        required: true
      }
    ]
  },

  lifecycle: {
    async init(args) {
      // 验证输入
      if (!args.email || !args.email.includes("@")) {
        return createInitFailed("请输入有效的邮箱地址");
      }

      // 如果需要 OAuth 授权
      if (args.needOAuth) {
        return createInitPending({
          type: "oauth",
          title: "授权登录",
          authUrl: `https://example.com/oauth?email=${args.email}`
        });
      }

      // 保存配置
      saveConfig({ email: args.email, token: args.token });

      return createInitSuccess({
        skill: "my-skill",
        summary: { email: args.email },
        configPath: CONFIG_PATH
      });
    },

    async status() {
      const config = loadConfig();

      if (!config) {
        return createStatusResponse({
          configured: false,
          skill: "my-skill",
          missing: ["email", "token"]
        });
      }

      return createStatusResponse({
        configured: true,
        skill: "my-skill",
        summary: { email: config.email }
      });
    },

    async verify(args) {
      // 处理验证码回调
      if (args.code === "123456") {
        saveConfig({ verified: true });
        return createInitSuccess({ skill: "my-skill" });
      }
      return createInitFailed("验证码错误");
    }
  }
});

技能包结构

my-skill/
├── package.json      # npm 配置，dependencies 包含 @work2cn/core
├── index.js          # 入口文件，使用 defineSkill() 导出技能
├── SKILL.md          # AI 提示词，描述技能能力供 AI 理解
└── src/              # 业务逻辑（可选）
    ├── send.js       # 业务函数，由 AI 按需调用
    └── utils.js

注意事项

1. 技能业务函数由 AI 调用：lifecycle 只处理配置相关逻辑，实际业务（如发邮件）写在单独的脚本中，由 AI 根据 SKILL.md 理解后调用

2. 使用响应构建器：始终使用 createInitSuccess() 等函数构建响应，确保格式正确

3. eventId 自动生成：createInitPending() 和 createRuntimeEvent() 会自动生成 eventId，用于回调匹配

4. 运行时事件：如果业务执行中发现需要用户干预（如 token 过期），返回 createRuntimeEvent()

TypeScript 支持

包含完整的类型定义：

import {
  defineSkill,
  SkillConfig,
  InitResponse,
  StatusResponse,
  RuntimeEventResponse,
  ConfigField
} from "@work2cn/core";

协议版本

当前版本：2.0.0

const { PROTOCOL_VERSION } = require("@work2cn/core");
console.log(PROTOCOL_VERSION); // "2.0.0"