# bsin-paas-skills

**Repository Path**: s11e-DAO/bsin-paas-skills

## Basic Information

- **Project Name**: bsin-paas-skills
- **Description**: bsin-paas系统的模块调用skills
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-08
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Bsin-PaaS Skills

> Bsin-PaaS 平台的能力开放层，将平台能力封装为可被 AI Agent、自动化系统和第三方应用调用的标准化 **Skill**。  
> Skill 可以通过两种主要方式提供给 Agent：  
> 1）经 Bsin 网关 + OpenClaw 调用（当前主路径）；  
> 2）通过 MCP（Model Context Protocol）实现为标准化工具，由支持 MCP 的 IDE/Agent 直接调用。

---

## 仓库结构

```
bsin-paas-skills/
├── README.md                 # 本文件
├── docs/                     # 设计规范、调用协议、集成说明（01～10）及操作指南
│   ├── 01～10                # Skill 设计、注册、协议、分类、集成等
│   ├── OPENCLAW_START_GUIDE.md   # OpenClaw 启动与 bsin-paas 配置详解
│   └── REVIEW_RECOMMENDATIONS.md  # 工程 Review 与修改建议
├── scripts/
│   └── openclaw-start.sh     # OpenClaw 启动脚本（自动设置 env）
├── skills/                   # 按模块划分的 Skill 定义（skills.json）
│   ├── upms/                 # 身份与权限（如 sign_test）
│   ├── crm/                  # 会员与业务（如 create_member）
│   ├── waas/                 # 区块链与资产（如 transfer_token）
│   ├── app-agent/            # AI Agent 相关
│   └── workflow/             # 工作流
└── examples/openclaw/        # OpenClaw 可直接使用的示例
    ├── bsin-paas/            # 通用调用示例（SKILL.md + invoke.js）
    └── bsin-paas-dev/        # 开发类 Skill（仅 SKILL.md）
```

Skill 的**能力定义**在 `skills/<模块>/skills.json`；**实际调用**通过网关，在 [OpenClaw](https://docs.openclaw.ai/) 中通过对话发起。各模块与 contextPath 的对应关系见 [skills/README.md](skills/README.md)。

---

## 如何直接使用 Skill

目前推荐两条使用路径：

1. 在 [OpenClaw](https://docs.openclaw.ai/) 中，通过网关调用 Skill（HTTP + 签名）  
2. 在支持 MCP 的 Agent/IDE 中，将本仓库作为 MCP Server 的能力来源（MCP 工具定义侧重映射到 `skills.json` 与网关 API）

下文先说明网关 + OpenClaw 路径，再补充 MCP 形态的说明。

在 [OpenClaw](https://docs.openclaw.ai/) 中通过**对话**调用 Bsin-PaaS 的 Skill。只需配置 **3 个参数**（网关地址 + AppKey + SecretKey），即可在对话里用自然语言触发（如「测试一下 UPMS 接口」）。

> **当前能力范围**：bsin-paas 示例**仅支持 sign_test**（UPMS 连通性测试）。其他 Skill（create_member、create_user 等）为设计定义，待网关/Runtime 实现后支持。

### 在 OpenClaw 中使用（对话中触发）

**若你本地已经部署了 OpenClaw，按下面顺序操作即可：**

| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 复制 Skill | 在本仓库根目录执行：`mkdir -p ~/.openclaw/workspace/skills/` 和 `cp -r examples/openclaw/bsin-paas ~/.openclaw/workspace/skills/`。 |
| 2 | 准备 3 个参数 | 向 Bsin 网关管理员获取：**网关基地址**（如 `http://127.0.0.1:9195`）、**AppKey（AK）**、**SecretKey（SK）**。invoke.js 会按 skill 自动拼接路径。 |
| 3 | 配置 openclaw.json | 编辑 `~/.openclaw/openclaw.json`，在 `skills.entries` 里增加 `bsin-paas`（见下方配置示例）。 |
| 4 | 启动 Gateway | 执行 `openclaw gateway start` 或 `openclaw gateway restart`。 |
| 5 | 测试 Skill | 运行 `openclaw tui`，在对话中输入「测试一下 UPMS 接口」；或访问 `http://127.0.0.1:18789/__openclaw__/canvas/`。 |

**步骤 3 配置示例**（[OpenClaw Skills 配置](https://docs.openclaw.ai/tools/skills-config)）：

```json5
{
  "skills": {
    "entries": {
      "bsin-paas": {
        "enabled": true,
        "apiKey": "替换为SecretKey",
        "env": {
          "BSIN_GATEWAY_URL": "http://127.0.0.1:9195",
          "BSIN_APP_KEY": "替换为AppKey",
          "BSIN_APP_SECRET": "替换为SecretKey"
        }
      }
    }
  }
}
```

| 字段 | 含义 | 示例值 |
|------|------|--------|
| `apiKey` | SecretKey（SK） | 由网关管理员分配的 SK |
| `BSIN_GATEWAY_URL` | 网关基地址（invoke.js 自动拼接路径） | `http://127.0.0.1:9195` |
| `BSIN_APP_KEY` | AppKey（AK） | 由网关管理员分配的 AK |
| `BSIN_APP_SECRET` | SecretKey（SK），与 `apiKey` 相同 | 与 apiKey 同值 |

将上述占位符替换为实际值。apiKey 与 SK 以明文保存，建议 `chmod 600 ~/.openclaw/openclaw.json`。

更多细节见 [examples/openclaw/README.md](examples/openclaw/README.md)、[OpenClaw 集成说明](docs/07-openclaw-integration.md) 与 [OpenClaw 启动操作指南](docs/OPENCLAW_START_GUIDE.md)。

### 通过 MCP 提供 Skill（可选形态）

对于支持 MCP（Model Context Protocol）的 IDE 或 Agent（如部分新版编辑器/Agent Runtime），可以将 Bsin-PaaS 的 Skill 暴露为 MCP 工具：

- **能力来源**：本仓库 `skills/<模块>/skills.json` 中定义的各 Skill（name、description、input_schema、output_schema 等）。  
- **MCP Server 职责**：
  - 读取 `skills.json`，将 Skill 元数据映射为 MCP 工具（tools）。
  - 按 MCP 调用协议接收 Agent 的 `tool.invoke` 请求，内部转为对 Bsin 网关的 HTTP 调用（与 OpenClaw invoke.js 类似）。
  - 处理鉴权：从环境变量中读取 `BSIN_GATEWAY_URL`、`BSIN_APP_KEY`、`BSIN_APP_SECRET`，按 [网关鉴权说明](docs/08-gateway-auth.md) 生成签名与请求头。
- **优势**：
  - 对 Agent/IDE 抽象为“本地工具”，无需显式拼接 HTTP 请求。
  - Skill 元数据与网关调用协议仍以本仓库为单一来源，避免重复维护。

一个典型的实现方式是：在单独的仓库/服务中实现 `bsin-paas-mcp-server`，将本仓库挂载为只读依赖目录，启动后通过 MCP 规范将 Skill 暴露出去；Agent 侧只需在配置中增加该 MCP Server 即可发现和调用 `bsin-paas` 的各类 Skill。

**常见问题**：若 bsin-paas 未出现在 OpenClaw 技能列表，请检查 Skill 是否已复制到 `~/.openclaw/workspace/skills/`、`openclaw.json` 中 `enabled: true`，并执行 `openclaw gateway restart`。详见 [OpenClaw 启动操作指南](docs/OPENCLAW_START_GUIDE.md)。

### 在 Cursor 中编辑 Skill

在 **Cursor** 里打开本仓库时，可修改 `examples/openclaw/bsin-paas/SKILL.md` 或相关配置，保存后到 OpenClaw 里「刷新 Skills」或重启 Gateway 即可生效（若已用 `extraDirs` 指向本仓库则可能自动检测变更）。实际调用需在 **OpenClaw** 应用里通过对话触发。

---

## 仓库定位

本仓库目前是 **Skill 能力的初步定义与实验仓库**，用于：

- 统一 Skill 的**设计规范、分类与调用协议**
- 明确 **Skill 注册与发现**、**Agent 调用流程** 的约定
- 提供**示例 Skill** 与文档，便于平台实现与 Agent 接入
- **支持在 [OpenClaw](https://docs.openclaw.ai/) 中直接使用**：通过桥接 Skill 或按 Bsin Skill 生成 OpenClaw SKILL.md，见 [OpenClaw 集成说明](docs/07-openclaw-integration.md) 与 [examples/openclaw](examples/openclaw)
- **各模块的 Skill 可放在本仓库**：在 [skills/](skills/) 下按模块分目录（如 `skills/upms/`、`skills/crm/`、`skills/waas/`），每目录内放 `skills.json`，便于统一维护与 Registry 聚合，见 [Skill 架构评估](docs/09-skill-architecture-evaluation.md) 方案 D。
- **单独写一个「模块接口开发」类 Skill**：仅需新建目录 + **SKILL.md**（无 invoke.js），用于在 Cursor/OpenClaw 中指导 AI 按 Bsin 规范开发接口。步骤与示例见 [如何单独写一个开发类 Skill](docs/10-how-to-write-a-dev-skill.md)，骨架见 [examples/openclaw/bsin-paas-dev/](examples/openclaw/bsin-paas-dev/)。

实现层面的 Registry / Gateway / Runtime 以 Bsin-PaaS 主仓库或相关服务为准；本仓库**以文档与能力定义为主**，随平台演进持续补充。

---

## 文档体系

以下内容在 `docs/` 下均有**独立文档**，便于查阅与协作。

| 文档 | 说明 |
|------|------|
| [Skill 设计规范](docs/01-skill-design-spec.md) | 元数据模型、必选/可选字段、设计原则、类型约定 |
| [Skill 注册与发现机制](docs/02-skill-registry.md) | Registry 职责、注册方式、存储与索引、发现 API |
| [Skill 调用协议](docs/03-skill-invocation-protocol.md) | 请求/响应格式、鉴权与签名、错误码、调用流程 |
| [Skill 分类体系](docs/04-skill-taxonomy.md) | 六大类能力清单（Identity/Business/Workflow/Data/Blockchain/AI） |
| [Agent 调用流程](docs/05-agent-call-flow.md) | Agent 发现 Skill、参数抽取、调用 Gateway、结果处理的端到端流程 |
| [示例 Skill](docs/06-example-skills.md) | create_member、create_user、run_workflow、knowledge_qa 等完整示例 |
| [OpenClaw 集成说明](docs/07-openclaw-integration.md) | 在 OpenClaw 中直接使用 Bsin Skill（字段映射、桥接 Skill、配置与示例） |
| [网关鉴权说明](docs/08-gateway-auth.md) | 仅需配置 **AppKey/SecretKey** 即可调用；ShenYu Sign 插件 1.0.0/2.0.0、签名算法与请求头 |
| [Skill 架构评估](docs/09-skill-architecture-evaluation.md) | bsin-server-apps 模块化下「每模块自带 Skill」与集中式对比，**推荐混合方案**与落地建议 |
| [如何单独写一个开发类 Skill](docs/10-how-to-write-a-dev-skill.md) | 从零做「Bsin-PaaS 模块接口开发」等**开发辅助** Skill（仅 SKILL.md、无 invoke），步骤与示例 |
| [OpenClaw 启动操作指南](docs/OPENCLAW_START_GUIDE.md) | bsin-paas 配置步骤、环境变量、故障排查 |
| [工程 Review 与修改建议](docs/REVIEW_RECOMMENDATIONS.md) | 文档一致性、能力范围说明、后续优化建议 |

**建议阅读顺序**：设计规范 → 分类体系 → 调用协议 → **网关鉴权**（对接网关时必读）→ 注册与发现 → Agent 调用流程 → 示例 Skill；使用 OpenClaw 时加阅 [OpenClaw 集成说明](docs/07-openclaw-integration.md)；**要单独写开发类 Skill**（如模块接口开发）时加阅 [如何单独写一个开发类 Skill](docs/10-how-to-write-a-dev-skill.md)。

---

## OpenClaw 快速开始（调用 bsin-paas Skill）

本仓库提供可直接放入 OpenClaw 的 Skill 示例：`examples/openclaw/bsin-paas/`（包含 `SKILL.md` + `invoke.js`）。**完整步骤**（复制目录 → 配置 3 个变量 → 刷新 → 对话触发）见上文 [如何直接使用 Skill](#如何直接使用-skill)。更多细节见 [examples/openclaw/README.md](examples/openclaw/README.md) 与 [OpenClaw 集成说明](docs/07-openclaw-integration.md)。

---

## 项目介绍（概要）

### 目标

通过**统一调用协议**，将 Bsin-PaaS 的核心能力（用户管理、工作流、区块链、数据分析等）封装为可组合的 Skill，实现：

- **AI Agent 自动化调用**：自然语言/意图驱动，自动选 Skill、填参、调用
- **跨系统流程编排**：多 Skill 组合成业务流程
- **SaaS 能力开放**：标准化 API，支持 AppKey、签名、限流
- **企业自动化运营**：减少人工操作，提升运营效率

系统目标：将 Bsin-PaaS 打造为 **AI Agent 时代的企业操作系统（Agent OS）**。

### 架构概览

```
AI Agent
   ↓
Skill Registry（注册与发现）
   ↓
Skill Gateway（鉴权、限流、日志）
   ↓
Skill Runtime（执行、编排）
   ↓
Bsin-PaaS Services
   ↓
Database / Blockchain
```

组件职责简述：

- **Skill Registry**：Skill 注册、元数据管理、搜索与发现 → 详见 [Skill 注册与发现机制](docs/02-skill-registry.md)
- **Skill Gateway**：AppKey 鉴权、签名校验、权限控制、限流、调用日志 → 详见 [Skill 调用协议](docs/03-skill-invocation-protocol.md)
- **Skill Runtime**：Skill 执行、下游 Service 调用、入参/出参转换

---

## 文档目录（本 README）

- [仓库结构](#仓库结构)
- [当前能力范围](#如何直接使用-skill)：仅 sign_test 可调用
- [如何直接使用 Skill](#如何直接使用-skill)（含 [在 Cursor 中编辑 Skill](#在-cursor-中编辑-skill)）
- [仓库定位](#仓库定位)
- [文档体系](#文档体系)
- [OpenClaw 快速开始](#openclaw-快速开始调用-bsin-paas-skill)
- [项目介绍（概要）](#项目介绍概要)
- [Skill 设计规范（摘要）](#skill-设计规范摘要)
- [Skill 分类体系（摘要）](#skill-分类体系摘要)
- [Skill 调用协议（摘要）](#skill-调用协议摘要)
- [Agent 调用流程（摘要）](#agent-调用流程摘要)
- [示例 Skill（摘要）](#示例-skill摘要)
- [故障排查](#故障排查)
- [未来规划](#未来规划)
- [附录](#附录)

---

## Skill 设计规范（摘要）

**Skill** = 业务能力 + 语义描述 + 输入/输出结构 + 权限控制。

必选字段：`name`、`description`、`input_schema`、`output_schema`、`permission_scope`。设计原则：任务级能力、原子可组合、语义可发现。

→ 完整说明见 [Skill 设计规范](docs/01-skill-design-spec.md)。

---

## Skill 分类体系（摘要）

| 分类 | 说明 | 示例 Skill |
|------|------|------------|
| Identity | 身份与权限（UPMS） | sign_test（连通性测试）、create_user、assign_role、create_tenant |
| Business | 业务能力（CRM/订单/会员） | create_customer、create_order、create_member |
| Workflow | 流程引擎 | create_workflow、run_workflow、get_workflow_status |
| Data | 数据能力 | query_data、generate_report、predict_sales |
| Blockchain | 区块链 | create_wallet、transfer_token、mint_nft |
| AI | AI 能力 | knowledge_search、knowledge_qa、decision_recommendation |

→ 完整清单见 [Skill 分类体系](docs/04-skill-taxonomy.md)。

---

## Skill 调用协议（摘要）

- **入口**：经 Bsin 网关调用；当前 sign_test 使用直连路径 `POST /upms/openApi/signTest`；未来可演进为统一入口 `POST /api/skills/invoke`。
- **请求体**：仅业务字段 `skill_name`、`params`；鉴权（timestamp、appKey、sign 等）在**请求头**，见 [网关鉴权说明](docs/08-gateway-auth.md)。
- **响应**：`code`（`0` 或 `"000000"` 为成功）、`message`、`data`（与 output_schema 对应）。sign_test 可能直接返回字符串 `"success"`。

→ 请求/响应细节、签名与错误码见 [Skill 调用协议](docs/03-skill-invocation-protocol.md)。

---

## Agent 调用流程（摘要）

1. 用户输入（自然语言）→ Agent 意图识别  
2. Agent 从 Registry 发现 Skill（如 create_member）  
3. 参数抽取/追问 → 按调用协议组包 → 请求 Gateway  
4. Gateway 鉴权、限流 → Runtime 映射到 Bsin 服务执行  
5. 结果返回 Agent → 解析 data → 生成回复给用户  

→ 端到端流程与安全约定见 [Agent 调用流程](docs/05-agent-call-flow.md)。

---

## 示例 Skill（摘要）

| Skill | 模块 | 说明 | 当前可调用 | 定义位置 |
|-------|------|------|:----------:|----------|
| sign_test | UPMS | 开放接口连通性测试，入参可选 message，出参 result（success） | ✓ | [skills/upms/skills.json](skills/upms/skills.json) |
| create_member | CRM | 创建会员，入参 name/phone，出参 member_id | 待实现 | [skills/crm/skills.json](skills/crm/skills.json) |
| transfer_token | WaaS | 代币转账 | 待实现 | [skills/waas/skills.json](skills/waas/skills.json) |
| create_user | UPMS | 创建用户（设计示例） | 待实现 | [示例 Skill](docs/06-example-skills.md#2-create_user创建用户) |
| run_workflow | Workflow | 发起工作流实例 | 待实现 | [示例 Skill](docs/06-example-skills.md#3-run_workflow发起流程) |
| knowledge_qa | AI | 知识库问答 | 待实现 | [示例 Skill](docs/06-example-skills.md#4-knowledge_qa知识库问答) |

→ 完整元数据与请求/响应见 [示例 Skill](docs/06-example-skills.md)；各模块目录见 [仓库结构](#仓库结构)。

---

## 未来规划

- **Skill Registry**：统一注册、版本、发现 API
- **Skill Marketplace**：开发者发布、企业安装与订阅
- **Skill Workflow**：多 Skill 编排与模板
- **Agent Runtime**：内置 Agent 执行环境

目标：构建 **AI Agent + PaaS** 的企业级操作系统。

---

## 附录

### 术语表

| 术语 | 说明 |
|------|------|
| Skill | 平台能力的标准化封装单元，可被 AI Agent 或应用按协议调用 |
| Skill Registry | Skill 的注册与发现中心 |
| Skill Gateway | 鉴权、限流、路由、日志的网关层 |
| Skill Runtime | Skill 执行与下游服务调用的运行时 |
| input_schema / output_schema | Skill 的入参/出参结构定义 |

### 相关链接

- Bsin-PaaS 总体架构与部署见主仓库文档
- Skill Gateway 实际 API 与签名规则以平台网关文档为准

### 文档版本

- 当前：能力定义与实验阶段；文档体系已补全上述文档
- 变更记录见 [CHANGELOG.md](CHANGELOG.md)