GitHub_Trending/skills4/skillsAPI文档：开发者必备的接口参考手册

【免费下载链接】skills Skills Catalog for Codex 【免费下载链接】skills 项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

GitHub_Trending/skills4/skills 是一个面向开发者的技能目录项目，提供了丰富的接口和工具，帮助开发者构建和管理 AI 代理技能。本 API 文档将详细介绍该项目的核心接口、使用方法和最佳实践，是开发者集成和扩展技能功能的必备参考手册。

快速入门：如何开始使用 skills API

要开始使用 skills API，首先需要安装相关技能。项目中的技能分为系统技能、精选技能和实验性技能。系统技能位于 skills/.system/ 目录下，会自动安装在最新版本的 Codex 中。

对于精选技能和实验性技能，可以使用 Codex 内部的 $skill-installer 命令进行安装。例如，安装精选技能：

$skill-installer gh-address-comments

安装实验性技能则需要指定技能文件夹路径或 GitHub 目录 URL：

$skill-installer install the create-plan skill from the .experimental folder

或

$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

安装完成后，重启 Codex 即可使用新安装的技能。

核心 API 接口详解

Agent 类：构建 AI 代理的基础

AIChatAgent：智能聊天代理

AIChatAgent 是用于构建具有自动流式传输、消息历史管理和工具调用功能的 AI 聊天代理的核心类。以下是一个基本示例：

import { AIChatAgent } from "agents";
import { openai } from "@ai-sdk/openai";

export class ChatAgent extends AIChatAgent<Env> {
  async onChatMessage(onFinish) {
    return this.streamText({
      model: openai("gpt-4"),
      messages: this.messages, // 自动管理的消息历史
      tools: {
        getWeather: {
          description: "获取天气信息",
          parameters: z.object({ city: z.string() }),
          execute: async ({ city }) => `Sunny, 72°F in ${city}`
        }
      },
      onFinish, // 将响应持久化到 this.messages
    });
  }
}
Agent 基类：自定义代理的灵活选择

Agent 基类提供了构建自定义代理的全部控制权，适用于需要处理 WebSocket、电子邮件和 SQL 等复杂逻辑的场景。定义一个自定义代理类如下：

import { Agent } from "agents";

export class MyAgent extends Agent<Env, State> {
  // 生命周期方法将在下方介绍
}

类型参数：Agent<Env, State, ConnState>，分别表示环境绑定、代理状态和连接状态。

生命周期钩子：代理的事件处理

Agent 类提供了多个生命周期钩子，用于处理不同的事件：

  • onStart(): 初始化或重启代理时调用，适合执行创建表等初始化操作。
  • onRequest(req: Request): 处理 HTTP 请求，可用于构建 API 端点。
  • onConnect(conn: Connection , ctx: ConnectionContext) : 处理 WebSocket 连接。
  • onMessage(conn: Connection , msg: WSMessage) : 处理 WebSocket 消息。
  • onEmail(email: AgentEmail): 处理电子邮件路由。

示例代码展示了如何使用这些钩子：

onStart() { // 初始化/重启
  this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT, name TEXT)`;
}

async onRequest(req: Request) { // HTTP 处理
  const {pathname} = new URL(req.url);
  if (pathname === "/users") return Response.json(this.sql<{id,name}>`SELECT * FROM users`);
  return new Response("Not found", {status: 404});
}

async onConnect(conn: Connection<ConnState>, ctx: ConnectionContext) { // WebSocket 连接
  conn.accept();
  conn.setState({userId: ctx.request.headers.get("X-User-ID")});
  conn.send(JSON.stringify({type: "connected", state: this.state}));
}

状态管理、SQL 操作与任务调度

状态管理

代理状态可以通过 setState 方法进行管理，状态会自动同步：

this.setState({count: 42}); // 设置状态
this.setState({...this.state, count: this.state.count + 1}); // 更新状态
SQL 操作

Agent 提供了安全的 SQL 操作方法，支持参数化查询以防止注入攻击：

// 创建表
this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`;
// 插入数据
this.sql`INSERT INTO users (id,name) VALUES (${userId},${name})`;
// 查询数据
const users = this.sql<{id,name}>`SELECT * FROM users WHERE id = ${userId}`;
任务调度

可以使用 schedule 方法安排任务在未来执行，支持日期、延迟时间和 cron 表达式：

// 在指定日期执行
await this.schedule(new Date("2026-12-25"), "sendGreeting", {msg:"Hi"});
// 延迟指定秒数执行
await this.schedule(60, "checkStatus", {});
// 使用 cron 表达式定时执行
await this.schedule("0 0 * * *", "dailyCleanup", {});
// 取消调度
await this.cancelSchedule(scheduleId);

RPC 方法：@callable 装饰器

使用 @callable 装饰器可以将方法暴露为远程过程调用（RPC）接口，方便客户端调用：

import { Agent, callable } from "agents";

export class MyAgent extends Agent<Env> {
  @callable()
  async processTask(input: {text: string}): Promise<{result: string}> {
    return { result: await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt: input.text}) };
  }
}

客户端可以直接调用这些方法：

const result = await agent.processTask({ text: "Hello" });

注意：RPC 方法必须返回可 JSON 序列化的值。

高级功能：连接管理与 AI 集成

连接管理

Agent 可以管理多个 WebSocket 连接，并进行消息广播等操作：

// 广播消息
this.connections.forEach(c => c.send(JSON.stringify(msg)));
// 设置连接状态
conn.setState({userId:"123"});
// 关闭连接
conn.close(1000, "Goodbye");

AI 集成

Agent 可以集成多种 AI 模型，如 Workers AI 和 OpenAI 模型：

// 使用 Workers AI
const r = await this.env.AI.run("@cf/meta/llama-3.1-8b-instruct", {prompt});

// 手动流式传输（推荐使用 AIChatAgent 进行自动流式传输）
const stream = await client.chat.completions.create({model: "gpt-4", messages, stream: true});
for await (const chunk of stream) {
  if (chunk.choices[0]?.delta?.content) conn.send(JSON.stringify({chunk: chunk.choices[0].delta.content}));
}

React 客户端钩子：构建前端界面

项目提供了 React 客户端钩子，简化与代理的交互：

useAgent：WebSocket 连接与 RPC 调用

import { useAgent } from "agents/react";
const agent = useAgent({ agent: "MyAgent", name: "user-123" }); // name 用于 idFromName
const result = await agent.processTask({ text: "Hello" }); // 调用 @callable 方法
// agent.readyState: 0=连接中, 1=已连接, 2=关闭中, 3=已关闭

useAgentChat：AI 聊天 UI 组件

import { useAgentChat } from "agents/ai-react";
const agent = useAgent({ agent: "ChatAgent" });
const { messages, input, handleInputChange, handleSubmit, isLoading, stop, clearHistory } =
  useAgentChat({
    agent,
    maxSteps: 5,        // 最大工具迭代次数
    resume: true,       // 断开连接后自动恢复
    onToolCall: async (toolCall) => {
      // 客户端工具（人工介入）
      if (toolCall.toolName === "confirm") return { ok: window.confirm("继续操作？") };
    }
  });
// status: "ready" | "submitted" | "streaming" | "error"

实际应用示例：构建天气查询代理

以下是一个使用 AIChatAgent 构建天气查询代理的完整示例：

import { AIChatAgent } from "agents";
import { openai } from "@ai-sdk/openai";
import { z } from "zod";

export class WeatherAgent extends AIChatAgent<Env> {
  async onChatMessage(onFinish) {
    return this.streamText({
      model: openai("gpt-4"),
      messages: this.messages,
      tools: {
        getWeather: {
          description: "获取指定城市的天气信息",
          parameters: z.object({ city: z.string().describe("城市名称") }),
          execute: async ({ city }) => {
            // 实际应用中这里会调用天气 API
            return `晴天，${city}当前温度 25°C，湿度 60%`;
          }
        }
      },
      onFinish,
    });
  }
}

客户端可以通过以下方式与该代理交互：

import { useAgent } from "agents/react";

function WeatherChat() {
  const agent = useAgent({ agent: "WeatherAgent" });
  const { messages, input, handleInputChange, handleSubmit } = useAgentChat({ agent });

  return (
    <div>
      <div>
        {messages.map((msg, i) => (
          <div key={i}>{msg.role}: {msg.content}</div>
        ))}
      </div>
      <input value={input} onChange={handleInputChange} />
      <button onClick={handleSubmit}>发送</button>
    </div>
  );
}

常见问题与解决方案

如何安装技能？

技能安装可以通过 $skill-installer 命令进行。系统技能位于 skills/.system/ 目录，会自动安装。精选技能和实验性技能需要手动安装，具体方法参见快速入门部分。

如何处理代理状态持久化？

Agent 的状态通过 setState 方法进行管理，状态会自动同步和持久化。对于复杂的状态管理，可以结合 SQL 数据库进行存储。

如何调试代理？

可以使用 getCurrentAgent 方法获取当前代理实例，并在生命周期钩子中添加日志输出：

const agent = getCurrentAgent<MyAgent>(); // 获取当前实例
console.log("Agent state:", agent.state);

总结

GitHub_Trending/skills4/skills API 提供了强大而灵活的工具，帮助开发者构建和管理 AI 代理技能。通过本文档介绍的 Agent 类、生命周期钩子、状态管理、SQL 操作、RPC 方法和客户端钩子，开发者可以快速构建功能丰富的 AI 应用。无论是构建聊天机器人、自动化工具还是复杂的分布式系统，skills API 都能提供坚实的基础和丰富的功能支持。

要获取更多详细信息，可以参考项目中的官方文档：skills/.curated/cloudflare-deploy/references/agents-sdk/api.md。

【免费下载链接】skills Skills Catalog for Codex 【免费下载链接】skills 项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区