Service Ability Creator

---
name: service-ability-creator
description: 指导 OpenClaw Agent 开发和升级“面向 AI 的服务 (Service for AI)”。该技能专注于创建无前端页面、通过 ServiceAbility.MD 实现能力自发现的闭环服务，确保逻辑合理、简洁优美且易于模型理解。
version: 1.2.0
author: Manus AI
triggers:
  - OpenClaw Service
  - ServiceAbility.MD
  - AI Agent Skill
  - Develop AI Service
tools_required:
  - file
  - shell
  - default_api
---

# Service Ability Creator (OpenClaw Edition)

本技能旨在指导 **OpenClaw Agent** 开发一种特殊的服务形态：**面向 AI 的服务 (Service for AI)**。这类服务不提供传统的用户界面 (UI)，而是通过结构化的 `ServiceAbility.MD` 文件向其他 AI Agent 宣告其能力，实现自动化的能力发现与调用。

## 核心原则

| 原则 | 描述 |
| :--- | :--- |
| **AI 优先 (AI-First)** | 服务设计以机器解析和自动化调用为核心，而非人类阅读。 |
| **自发现性 (Self-Discoverability)** | 服务必须在根路径 `/` 或 `/ServiceAbility.MD` 默认返回能力说明文件。 |
| **闭环性 (Closed-Loop)** | 提供从请求处理到结果返回的完整业务逻辑，并包含反馈机制。 |
| **生产级标准 (Production-Grade)** | 遵循 S.A.F.E. 分析方法，确保安全、可用、容错与演进性。 |

---

## 开发工作流 (C.O.R.E. Build Flow)

按照以下四个阶段构建您的 OpenClaw AI 服务。每个阶段都应确保逻辑的简洁与优美。

### 1. 配置与定义 (Configuration)
> **目标**：确立服务的“合同”与环境。

- **定义 ServiceAbility**：参考 `assets/ServiceAbility.MD.template` 编写服务说明。
  - 明确 Meta 信息（名称、版本、描述）。
  - 定义核心功能与接口规范（路径、方法、参数、返回格式）。
  - 设定数据治理原则（数据程序分离、测试/生产隔离）。
- **环境初始化**：
  - 推荐技术栈：FastAPI (Python) 或 Express (Node.js)。
  - 建立标准目录结构：`core/` (逻辑), `data/` (存储), `config/` (配置), `ServiceAbility.MD` (合同)。

### 2. 核心实现 (Operation)
> **目标**：构建闭环的业务逻辑。

- **实现自发现接口**：
  - `GET /` 或 `GET /ServiceAbility.MD`：直接返回 `ServiceAbility.MD` 文件内容。
  - `GET /info`：返回实时元数据（如版本、健康状态、动态配置）。
- **开发业务接口**：
  - 严格遵循 `ServiceAbility.MD` 定义的 RESTful 风格。
  - 实现结构化日志记录（推荐 JSONL 格式）。
- **集成反馈机制**：
  - 实现 `/api/v1/feedback` 接口，允许调用方 AI 报告异常或建议。

### 3. 评审与验证 (Review)
> **目标**：确保服务的健壮性与安全性。

- **自动化测试**：执行单元测试与集成测试，验证接口返回是否符合 `ServiceAbility.MD` 规范。
- **S.A.F.E. 审计**：
  - **Security**：验证 API Key 鉴权与输入校验。
  - **Availability**：检查错误处理与超时机制。
  - **Fault-tolerance**：验证异常情况下的结构化错误返回。

---

## 产出标准 (Output Specification)

一个优秀的 OpenClaw AI 服务应满足以下清单：

- [ ] **自描述**：根路径及 `/ServiceAbility.MD` 必须返回有效的 Markdown 说明。
- [ ] **规范化**：接口路径、参数、错误码与 `ServiceAbility.MD` 严格一致。
- [ ] **数据分离**：代码中无硬编码配置，业务数据存储于独立目录或数据库。
- [ ] **闭环反馈**：具备 `/info` 状态接口和反馈收集接口。
- [ ] **健壮性**：拥有完善的错误捕获，返回机器可读的结构化 JSON 错误信息。
- [ ] **隔离性**：测试环境与生产环境的数据、配置完全隔离。

## 参考资源

- **标准规范**：`references/ServiceAbility_Standard_Specification.md`
- **能力模板**：`assets/ServiceAbility.MD.template`
- **实现示例**：`references/example_implementation.md`
- **核心概念**：`references/SAFE_CORE_Concepts.md`

---
*注：本技能是通用的服务创建指南，旨在帮助 OpenClaw Agent 构建可被生态系统理解的高质量后端能力。*