OpenClaw 开发系列:第11篇-高级实战 — 从零构建一个完整插件

{  "id": "github-assistant",  "name": "GitHub Assistant",  "version": "1.0.0",  "description": "GitHub project management assistant for OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "token": {        "type": "string",        "description": "GitHub Personal Access Token"      },      "defaultOwner": {        "type": "string",        "description": "Default repository owner"      },      "defaultRepo": {        "type": "string",        "description": "Default repository name"      },      "syncInterval": {        "type": "number",        "default": 300,        "description": "Sync interval in seconds"      },      "webhookSecret": {        "type": "string",        "description": "GitHub webhook secret for signature verification"      }    },    "required": ["token"]  },  "providerAuthChoices": [    {      "provider": "github",      "method": "token",      "choiceId": "github-token",      "choiceLabel": "GitHub Personal Access Token",      "optionKey": "token",      "cliFlag": "--github-token"    }  ],  "uiHints": {    "token": {      "label": "GitHub Token",      "placeholder": "ghp_xxxxxxxxxxxx",      "sensitive": true    },    "webhookSecret": {      "label": "Webhook Secret",      "placeholder": "whsec_...",      "sensitive": true    }  },  "contracts": {    "tools": ["github_search_issues", "github_create_issue"]  },  "skills": "skills"}

{  "name": "github-assistant",  "version": "1.0.0",  "type": "module",                    // 使用 ES Module（OpenClaw 插件要求）  "main": "./dist/index.js",          // 编译后的入口文件路径  "openclaw": {    "extensions": ["./src/index.ts"]  // OpenClaw 的插件入口（可以是 .ts）  },  "dependencies": {},                  // 运行时依赖（本项目没有额外的依赖）  "devDependencies": {    "typescript": "^5.4.0"            // 开发时需要 TypeScript  }}

// src/github-client.tsimport crypto from "crypto"; // Node.js 内置模块，用于 Webhook 签名验证export interface GitHubConfig {  token: string;  defaultOwner?: string;  defaultRepo?: string;}export class GitHubClient {  private config: GitHubConfig;  constructor(config: GitHubConfig) {    this.config = config;  }  private async request<T>(    path: string,    options: RequestInit = {}  ): Promise<T> {    const url = `https://api.github.com${path}`;    const response = await fetch(url, {      ...options,      headers: {        "Authorization": `Bearer ${this.config.token}`,        "Accept": "application/vnd.github.v3+json",        "Content-Type": "application/json",        ...options.headers,      },    });    if (!response.ok) {      const body = await response.text();      throw new Error(        `GitHub API error ${response.status}: ${body}`      );    }    return response.json() as Promise<T>;  }  async searchIssues(query: string, options: {    owner?: string;    repo?: string;    state?: "open" | "closed" | "all";    limit?: number;  } = {}): Promise<SearchResult> {    const owner = options.owner ?? this.config.defaultOwner;    const repo = options.repo ?? this.config.defaultRepo;    if (!owner || !repo) {      throw new Error(        "Repository owner and name are required. " +        "Set defaultOwner/defaultRepo in plugin config " +        "or specify them in the query."      );    }    const q = `${query} repo:${owner}/${repo}${options.state ? `is:${options.state}` : "is:open"}`;    return this.request<SearchResult>(      `/search/issues?q=${encodeURIComponent(q)}&per_page=${options.limit ?? 10}`    );  }  async createIssue(params: {    owner?: string;    repo?: string;    title: string;    body: string;    labels?: string[];  }): Promise<Issue> {    const owner = params.owner ?? this.config.defaultOwner;    const repo = params.repo ?? this.config.defaultRepo;    if (!owner || !repo) {      throw new Error("Repository owner and name are required.");    }    return this.request<Issue>(`/repos/${owner}/${repo}/issues`, {      method: "POST",      body: JSON.stringify({        title: params.title,        body: params.body,        labels: params.labels,      }),    });  }  async getRepo(owner: string, repo: string): Promise<Repo> {    return this.request<Repo>(`/repos/${owner}/${repo}`);  }  verifyWebhookSignature(    payload: string,    signature: string,    secret: string  ): boolean {    const expected = "sha256=" + crypto      .createHmac("sha256", secret)      .update(payload)      .digest("hex");    return crypto.timingSafeEqual(      Buffer.from(signature),      Buffer.from(expected)    );  }}// 类型定义interface SearchResult {  total_count: number;  items: Issue[];}interface Issue {  id: number;  number: number;  title: string;  body: string;  state: string;  labels: Array<{ name: string }>;  created_at: string;  updated_at: string;  html_url: string;  user: { login: string };}interface Repo {  full_name: string;  description: string;  stargazers_count: number;  open_issues_count: number;  updated_at: string;}

// src/tools.tsimport { Type } from "openclaw/plugin-sdk/typebox";import { GitHubClient } from "./github-client";import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";export function registerTools(  api: OpenClawPluginApi,  client: GitHubClient): void {  // 工具 1：搜索 Issues（必需工具）  api.registerTool({    name: "github_search_issues",    description:      "Search GitHub issues in a repository. Use this when the user " +      "asks about bugs, feature requests, or any issues in a GitHub project. " +      "Returns matching issues with title, state, labels, and description.",    parameters: Type.Object({      query: Type.String({        description: "Search query (supports GitHub search syntax)",      }),      state: Type.Optional(        Type.Union([          Type.Literal("open"),          Type.Literal("closed"),          Type.Literal("all"),        ], {          description: "Filter by issue state",        })      ),      limit: Type.Optional(        Type.Number({          description: "Maximum number of results",          default: 10,          minimum: 1,          maximum: 30,        })      ),    }),    async execute(_id, params) {      try {        const result = await client.searchIssues(params.query, {          state: params.state as "open" | "closed" | "all" | undefined,          limit: params.limit,        });        if (result.total_count === 0) {          return {            content: [              {                type: "text" as const,                text: "No issues found matching the query.",              },            ],          };        }        const issues = result.items.map((issue) => ({          number: issue.number,          title: issue.title,          state: issue.state,          labels: issue.labels.map((l) => l.name),          created: issue.created_at,          url: issue.html_url,          preview: issue.body?.substring(0, 200) ?? "",        }));        return {          content: [            {              type: "text" as const,              text: [                `Found ${result.total_count} issues. Top ${issues.length}:`,                "",                ...issues.map(                  (i) =>                    `#${i.number} [${i.state}] ${i.title}\n` +                    `  Labels: ${i.labels.join(", ") || "none"}\n` +                    `  Created: ${i.created}\n` +                    `  ${i.url}\n` +                    `  ${i.preview}...`                ),              ].join("\n"),            },          ],        };      } catch (error) {        return {          content: [            {              type: "text" as const,              text: `GitHub search failed: ${error instanceofError ? error.message : String(error)}`,            },          ],          isError: true,        };      }    },  });  // 工具 2：创建 Issue（可选工具，有副作用）  api.registerTool(    {      name: "github_create_issue",      description:        "Create a new GitHub issue. Use this when the user explicitly " +        "asks to create, file, or report a new issue.",      parameters: Type.Object({        title: Type.String({          description: "Issue title",        }),        body: Type.String({          description: "Issue body / description",        }),        labels: Type.Optional(          Type.Array(Type.String(), {            description: "Labels to apply",          })        ),      }),      async execute(_id, params) {        try {          const issue = await client.createIssue({            title: params.title,            body: params.body,            labels: params.labels,          });          return {            content: [              {                type: "text" as const,                text: `Issue created successfully:\n#${issue.number}${issue.title}\n${issue.html_url}`,              },            ],          };        } catch (error) {          return {            content: [              {                type: "text" as const,                text: `Failed to create issue: ${error instanceofError ? error.message : String(error)}`,              },            ],            isError: true,          };        }      },    },    { optional: true }  );}

// src/hooks.tsexport function registerHooks(api: OpenClawPluginApi): void {  // 工具调用审计  api.on("before_tool_call", async (context) => {    if (      context.toolName.startsWith("github_")    ) {      api.logger.info("GitHub tool call", {        tool: context.toolName,        params: sanitizeParams(context.parameters),        conversationId: context.conversationId,      });    }  });  // 消息后处理：为 GitHub 相关的回复添加仓库链接  api.on("message_sending", async (context) => {    const owner = (api.pluginConfig as { defaultOwner?: string })      ?.defaultOwner;    const repo = (api.pluginConfig as { defaultRepo?: string })      ?.defaultRepo;    if (owner && repo && context.message.text) {      // 检测回复中是否提到了 issue 编号      context.message.text = context.message.text.replace(        /#(\d+)/g,        `[#$1](https://github.com/${owner}/${repo}/issues/$1)`      );    }  });}function sanitizeParams(  params: Record<string, unknown>): Record<string, unknown> {  const sanitized = { ...params };  // 移除 token 等敏感字段  if ("token" in sanitized) sanitized.token = "***";  return sanitized;}import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";

// src/routes.tsimport { GitHubClient } from "./github-client";export function registerRoutes(  api: OpenClawPluginApi,  client: GitHubClient): void {  // Webhook 接收端点  api.registerHttpRoute({    method: "POST",    path: "/github-assistant/webhook",    handler: async (request, response) => {      const signature = request.headers["x-hub-signature-256"];      const secret = (api.pluginConfig as { webhookSecret?: string })        ?.webhookSecret;      if(secret && signature) {        if(          !client.verifyWebhookSignature(            request.rawBody,            signature,            secret          )        ) {          response.status(401).json({ error: "Invalid signature" });          return;        }      }      const event = request.headers["x-github-event"];      const payload = request.body;      api.logger.info("GitHub webhook received", { event });      // 处理不同事件类型      switch(event) {        case "issues":          await handleIssueEvent(payload);          break;        case "push":          await handlePushEvent(payload);          break;        default:          api.logger.info(`Unhandled GitHub event: ${event}`);      }      response.json({ received: true });    },  });  // 健康检查端点  api.registerHttpRoute({    method: "GET",    path: "/github-assistant/health",    handler: async (_req, response) => {      try {        const owner = (api.pluginConfig as { defaultOwner?: string })          ?.defaultOwner;        const repo = (api.pluginConfig as { defaultRepo?: string })          ?.defaultRepo;        let repoInfo = null;        if(owner && repo) {          repoInfo = await client.getRepo(owner, repo);        }        response.json({          status: "ok",          plugin: api.id,          repo: repoInfo            ? {                name: repoInfo.full_name,                openIssues: repoInfo.open_issues_count,                stars: repoInfo.stargazers_count,              }            : "not configured",        });      } catch(error) {        response.status(503).json({          status: "error",          error: error instanceof Error ? error.message : String(error),        });      }    },  });}async function handleIssueEvent(payload: Record<string, unknown>): Promise<void> {  // 处理 issue 事件  // 可以通知相关用户、更新内部状态等}async function handlePushEvent(payload: Record<string, unknown>): Promise<void> {  // 处理 push 事件}import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";

// src/service.tsimport { GitHubClient } from "./github-client";export function registerService(  api: OpenClawPluginApi,  client: GitHubClient): void {  api.registerService({    name: "github-sync",    description: "Periodically sync GitHub repository state",    async start(context) {      const intervalSec =        ((api.pluginConfig as { syncInterval?: number })?.syncInterval) ?? 300;      context.logger.info(`Sync service started (interval: ${intervalSec}s)`);      const interval = setInterval(async () => {        try {          const owner = (api.pluginConfig as { defaultOwner?: string })            ?.defaultOwner;          const repo = (api.pluginConfig as { defaultRepo?: string })            ?.defaultRepo;          if (owner && repo) {            const repoInfo = await client.getRepo(owner, repo);            context.logger.debug("Sync completed", {              openIssues: repoInfo.open_issues_count,            });          }        } catch (error) {          context.logger.error("Sync failed", {            error: error instanceof Error ? error.message : String(error),          });        }      }, intervalSec * 1000);      return { interval };    },    async stop(context, state) {      if (state?.interval) {        clearInterval(state.interval);      }      context.logger.info("Sync service stopped");    },  });}import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";

// src/cli.tsimport { GitHubClient } from "./github-client";export function registerCli(  api: OpenClawPluginApi,  client: GitHubClient): void {  api.registerCli(    (cli) => {      cli        .command("gh-status")        .description("Show GitHub Assistant status")        .action(async () => {          const config = api.pluginConfig as {            defaultOwner?: string;            defaultRepo?: string;            token?: string;          };          console.log("GitHub Assistant Status");          console.log("─".repeat(30));          console.log(`Owner: ${config.defaultOwner ?? "not set"}`);          console.log(`Repo:  ${config.defaultRepo ?? "not set"}`);          console.log(`Token: ${config.token ? "configured" : "not set"}`);          if (config.defaultOwner && config.defaultRepo) {            try {              const repo = await client.getRepo(                config.defaultOwner,                config.defaultRepo              );              console.log(`Stars: ${repo.stargazers_count}`);              console.log(`Open Issues: ${repo.open_issues_count}`);              console.log(`Last Updated: ${repo.updated_at}`);            } catch (error) {              console.error(                `Failed to fetch repo: ${error instanceofError ? error.message : String(error)}`              );            }          }        });      cli        .command("gh-search")        .description("Search GitHub issues from CLI")        .argument("<query>", "Search query")        .option("--state <state>", "Filter by state")        .action(async (query, options) => {          const result = await client.searchIssues(query, {            state: options.state as "open" | "closed" | "all" | undefined,          });          console.log(`Found ${result.total_count} issues:`);          for (const issue of result.items) {            console.log(              `  #${issue.number} [${issue.state}] ${issue.title}`            );          }        });    },    { name: "github-assistant" }  );}import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";

<!-- skills/code-review/SKILL.md -->---name: code-reviewdescription: Perform structured code review on GitHub PRs and code snippetstrigger: when user asks to review code, check a PR, or analyze code qualitytools: [github_search_issues, github_create_issue]---# Code Review Skill## When to Activate- User asks to "review this code" or "check this PR"- User shares a pull request URL or code snippet- User asks about code quality, bugs, or security issues## Review Process### 1. Gather ContextFirst, search for related existing issues:github_search_issues: query="[topic of the code]"textThis helps identify known issues, related work, or recurring patterns.### 2. Analyze the CodeExamine the code for:**Correctness**- Logic errors and edge cases- Null/undefined handling- Error handling completeness**Security**- Input validation- Authentication/authorization- SQL injection, XSS, path traversal- Secrets or credentials in code**Performance**- Unnecessary loops or computations- Memory leaks- N+1 query patterns**Readability**- Naming conventions- Function complexity- Documentation and comments### 3. Report FindingsStructure the review as:**Summary**: What the code does and overall assessment**Critical Issues** (must fix):- Security vulnerabilities- Data loss risks- Crashes or unrecoverable errors**Suggestions** (should fix):- Performance improvements- Error handling gaps- Code simplification**Nitpicks** (nice to have):- Naming suggestions- Style consistency- Documentation improvements### 4. Follow-upIf the review identifies actionable items and the user confirms,create a tracking issue:github_create_issue: title="Code review follow-up: [summary]" body="[detailed findings]"text## Rules- Always read the full code before commenting- Prioritize correctness and security- Be specific — reference line numbers or code sections- Distinguish between must-fix and nice-to-have

// src/index.tsimport { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";import { GitHubClient } from "./github-client";import { registerTools } from "./tools";import { registerHooks } from "./hooks";import { registerRoutes } from "./routes";import { registerService } from "./service";import { registerCli } from "./cli";interface GitHubAssistantConfig {  token: string;  defaultOwner?: string;  defaultRepo?: string;  syncInterval?: number;  webhookSecret?: string;}export default definePluginEntry({  id: "github-assistant",  name: "GitHub Assistant",  version: "1.0.0",  description: "GitHub project management assistant",  register(api) {    const config = api.pluginConfig as GitHubAssistantConfig;    if (!config.token) {      api.logger.error(        "GitHub token not configured. " +        "Set plugins.entries.github-assistant.config.token"      );      return;    }    // 初始化 GitHub 客户端    const client = new GitHubClient({      token: config.token,      defaultOwner: config.defaultOwner,      defaultRepo: config.defaultRepo,    });    api.logger.info(      `GitHub Assistant loaded` +      (config.defaultOwner ? ` for ${config.defaultOwner}/${config.defaultRepo}` : "")    );    // 注册所有能力    registerTools(api, client);    registerHooks(api);    registerRoutes(api, client);    registerService(api, client);    registerCli(api, client);  },});

# 编译 TypeScriptnpx tsc# 发布npm publish

# 安装并发布到 ClawHubopenclaw plugins publish ./github-assistant

# 从 npm 安装openclaw plugins install github-assistant# 从 ClawHub 安装openclaw plugins install github-assistant@clawhub# 本地安装（开发时）openclaw plugins install ./github-assistant

{  "tools": {    "allow": ["github_create_issue"]  }}

{  "plugins": {    "entries": {      "github-assistant": {        "config": {          "token": "ghp_xxxxxxxxxxxx",          "defaultOwner": "my-org",          "defaultRepo": "my-project",          "syncInterval": 600,          "webhookSecret": "whsec_xxx"        }      }    }  }}

import { createTestApi } from "openclaw/plugin-sdk/testing";describe("GitHub Assistant", () => {  it("registers search tool", () => {    const api = createTestApi();    // 加载插件    // 验证工具已注册  });  it("search tool returns results", async () => {    // 模拟 GitHub API 响应    // 调用工具执行函数    // 验证返回值格式  });});