构建pi-mono扩展生态：从基础开发到企业级集成

2026-03-12 03:46:55作者：邵娇湘

一、基础认知：pi-mono扩展生态系统

📌 本节将掌握：1.扩展系统核心概念 2.扩展类型与应用场景 3.开发环境搭建流程

理解扩展架构：插件化设计理念

pi-mono采用微内核架构（Microkernel Architecture），其核心包含事件总线、扩展管理器和工具注册表三大组件。扩展作为独立模块，通过明确定义的接口与核心系统交互，实现功能的灵活扩展。这种设计使系统保持轻量级的同时，允许开发者根据需求添加新功能。

扩展系统主要解决以下核心问题：

功能模块化，避免核心系统臃肿
支持第三方开发者生态建设
实现按需加载，优化资源占用
提供版本隔离，确保系统稳定性

扩展类型与应用场景

pi-mono支持多种扩展类型，适用于不同业务需求：

扩展类型	用途描述	典型场景
工具扩展	提供新的工具函数	数据处理、API调用、文件操作
界面扩展	自定义UI组件	特殊数据可视化、交互式表单
工作流扩展	定义自动化流程	代码审查、部署流水线、数据同步
模型扩展	集成新的AI模型	特定领域模型、私有部署模型

开发环境快速搭建

开始扩展开发前，需准备以下环境：

# 1. 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/pi/pi-mono
cd pi-mono

# 2. 安装依赖
npm install

# 3. 构建核心库
npm run build:core

# 4. 创建扩展开发模板
npx pi create-extension my-first-extension

[!TIP] 推荐使用Visual Studio Code并安装项目根目录下的.vscode/extensions.json中推荐的扩展，获得完整的开发体验。

二、核心功能：扩展开发核心技术

📌 本节将掌握：1.扩展注册机制 2.上下文访问方法 3.事件通信模式 4.UI组件开发

扩展注册与生命周期管理

每个扩展必须实现标准的生命周期接口，确保与核心系统正确交互：

// src/extensions/my-extension/index.ts
import { Extension, ExtensionContext } from "@mariozechner/pi-coding-agent";

export default class MyExtension implements Extension {
  // 扩展元数据
  metadata = {
    id: "my-extension",
    name: "我的第一个扩展",
    version: "1.0.0",
    author: "开发者名称",
    description: "演示扩展基本功能"
  };

  // 扩展激活时调用
  async activate(context: ExtensionContext) {
    console.log("我的扩展已激活");
    
    // 注册工具
    context.tools.registerTool(createMyTool());
    
    // 注册命令
    context.commands.registerCommand("my-extension.hello", () => {
      context.ui.showMessage("Hello from my extension!");
    });
    
    // 订阅事件
    context.events.on("session.started", () => {
      console.log("新会话已开始");
    });
  }

  // 扩展停用时调用
  async deactivate() {
    console.log("我的扩展已停用");
    // 清理资源、取消事件订阅等
  }
}

扩展生命周期包含以下阶段：

安装：扩展被添加到系统中
激活：扩展被加载并准备就绪
运行：扩展正常提供功能
停用：扩展被卸载或系统关闭

上下文访问与资源管理

扩展通过上下文对象访问pi-mono核心功能，实现与系统的深度集成：

async execute(ctx: ToolContext, params) {
  // 1. 访问用户配置
  const apiEndpoint = await ctx.settings.get("my-extension.api-endpoint");
  
  // 2. 使用文件系统工具
  const fileContent = await ctx.tools.readFile(params.filePath);
  
  // 3. 显示用户界面提示
  const userConfirm = await ctx.ui.showConfirm("确定要执行此操作吗？");
  if (!userConfirm) return "操作已取消";
  
  // 4. 使用缓存服务
  const cacheKey = `data:${params.id}`;
  const cachedData = await ctx.cache.get(cacheKey);
  if (cachedData) return cachedData;
  
  // 5. 执行耗时操作
  const result = await longRunningOperation(params.data);
  
  // 6. 缓存结果（1小时）
  await ctx.cache.set(cacheKey, result, { ttl: 3600 });
  
  return result;
}

[!WARNING] 上下文对象包含敏感操作权限，扩展应遵循最小权限原则，只请求必要的功能访问权。

事件总线与跨扩展通信

事件总线（Event Bus）——组件间通信的消息枢纽，允许不同扩展和系统组件之间进行松耦合通信：

// 发送事件
ctx.events.emit("data.processed", {
  source: "my-extension",
  data: processedResult,
  timestamp: new Date()
});

// 监听事件
ctx.events.on("file.changed", (event) => {
  if (event.path.endsWith(".md")) {
    console.log("检测到Markdown文件变更:", event.path);
    // 处理文件变更逻辑
  }
});

// 一次性事件监听
ctx.events.once("session.closed", () => {
  console.log("会话已关闭，执行清理工作");
});

// 事件过滤
ctx.events.on("tool.executed", (event) => {
  if (event.toolName === "data-parser") {
    logToolUsage(event);
  }
});

常见系统事件包括：

session.started - 新会话开始
tool.executed - 工具执行完成
message.received - 收到新消息
extension.activated - 扩展被激活

交互式UI组件开发

pi-mono提供了丰富的UI组件库，用于创建交互式扩展界面：

// 创建自定义选择器组件
async function showCustomSelector(ctx: ExtensionContext) {
  const items = [
    { id: "option1", label: "选项一", description: "这是第一个选项" },
    { id: "option2", label: "选项二", description: "这是第二个选项" }
  ];
  
  const result = await ctx.ui.showSelectList({
    title: "自定义选择器",
    message: "请选择一个选项",
    items,
    pageSize: 5,
    searchable: true
  });
  
  if (result) {
    ctx.ui.showMessage(`你选择了: ${result.label}`);
  } else {
    ctx.ui.showMessage("你取消了选择");
  }
}

// 创建进度指示器
async function showProgress(ctx: ExtensionContext) {
  const progress = ctx.ui.createProgressBar({
    title: "数据处理中",
    total: 100,
    label: "处理进度"
  });
  
  try {
    for (let i = 0; i <= 100; i += 10) {
      await new Promise(resolve => setTimeout(resolve, 500));
      progress.update(i, `已完成 ${i}%`);
    }
    progress.complete("数据处理完成");
  } catch (error) {
    progress.fail("处理失败");
  }
}

图1：pi-mono交互式模式界面，展示了工具和扩展的使用环境

三、实战案例：构建企业级扩展

📌 本节将掌握：1.第三方API集成完整流程 2.身份认证实现方案 3.扩展测试与调试方法 4.项目结构最佳实践

案例一：GitHub Issue管理扩展

项目结构：

my-github-extension/
├── src/
│   ├── index.ts          # 扩展入口
│   ├── github-api.ts     # API封装
│   ├── auth.ts           # 认证逻辑
│   ├── tools/            # 工具定义
│   │   ├── issue-creator.ts
│   │   ├── issue-list.ts
│   │   └── pr-manager.ts
│   └── ui/               # UI组件
│       ├── issue-form.ts
│       └── pr-view.ts
├── package.json
└── tsconfig.json

认证实现：

// src/auth.ts
import { OAuth2 } from "@mariozechner/pi-ai";

export class GitHubAuth {
  private oauth: OAuth2;
  
  constructor(private ctx: ExtensionContext) {
    this.oauth = new OAuth2({
      clientId: "YOUR_CLIENT_ID",
      authorizationEndpoint: "https://github.com/login/oauth/authorize",
      tokenEndpoint: "https://github.com/login/oauth/access_token",
      scope: "repo issues",
      storageKey: "github-token"
    });
  }
  
  async getToken(): Promise<string> {
    // 尝试从存储获取
    let token = await this.ctx.authStorage.get(this.oauth.storageKey);
    
    if (!token) {
      // 启动OAuth流程
      const authUrl = this.oauth.getAuthorizationUrl();
      this.ctx.ui.showExternalLink(authUrl);
      
      // 等待用户授权
      token = await this.oauth.waitForToken();
      
      // 保存令牌
      await this.ctx.authStorage.set(this.oauth.storageKey, token);
    }
    
    return token;
  }
  
  async clearToken() {
    await this.ctx.authStorage.delete(this.oauth.storageKey);
  }
}

API调用工具：

// src/tools/issue-creator.ts
import { Tool } from "@mariozechner/pi-coding-agent";
import { GitHubAuth } from "../auth";
import { GitHubAPI } from "../github-api";

export function createIssueCreatorTool(ctx): Tool {
  const auth = new GitHubAuth(ctx);
  const api = new GitHubAPI(auth);
  
  return {
    name: "github_create_issue",
    description: "在GitHub仓库中创建新issue",
    parameters: {
      type: "object",
      properties: {
        owner: { type: "string", description: "仓库所有者" },
        repo: { type: "string", description: "仓库名称" },
        title: { type: "string", description: "Issue标题" },
        body: { type: "string", description: "Issue内容" },
        labels: { type: "array", items: { type: "string" }, description: "标签列表" }
      },
      required: ["owner", "repo", "title"]
    },
    async execute(ctx, params) {
      try {
        const issue = await api.createIssue({
          owner: params.owner,
          repo: params.repo,
          title: params.title,
          body: params.body || "",
          labels: params.labels || []
        });
        
        return `Issue创建成功: #${issue.number} - ${issue.html_url}`;
      } catch (error) {
        ctx.ui.showError(`创建Issue失败: ${error.message}`);
        throw error;
      }
    }
  };
}

案例二：企业内部API集成扩展

错误处理策略：

// API错误处理中间层
class ApiErrorHandler {
  private retryCount = 3;
  private retryDelay = 1000; // 初始延迟1秒
  
  async executeWithRetry<T>(fn: () => Promise<T>): Promise<T> {
    let lastError: Error;
    
    for (let i = 0; i < this.retryCount; i++) {
      try {
        return await fn();
      } catch (error) {
        lastError = error as Error;
        
        // 判断是否可重试
        if (!this.isRetryable(error)) {
          break;
        }
        
        // 指数退避重试
        const delay = this.retryDelay * Math.pow(2, i);
        this.ctx.ui.showMessage(`API请求失败，${i+1}/${this.retryCount}重试中...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
    
    // 错误分类处理
    this.handleError(lastError);
    throw lastError;
  }
  
  private isRetryable(error): boolean {
    // 检查状态码是否是可重试的
    if (error.statusCode) {
      return [429, 500, 502, 503, 504].includes(error.statusCode);
    }
    // 网络错误也可重试
    return error.message.includes("Network Error");
  }
  
  private handleError(error) {
    switch (error.statusCode) {
      case 401:
        this.ctx.ui.showError("认证失败，请重新登录");
        this.ctx.events.emit("auth.required");
        break;
      case 403:
        this.ctx.ui.showError("权限不足，无法执行此操作");
        break;
      case 404:
        this.ctx.ui.showError("请求的资源不存在");
        break;
      case 429:
        this.ctx.ui.showError("请求过于频繁，请稍后再试");
        break;
      default:
        this.ctx.ui.showError(`API错误: ${error.message}`);
    }
  }
}

扩展测试与调试

单元测试：

// __tests__/github-api.test.ts
import { describe, it, expect, vi, beforeEach } from "vitest";
import { GitHubAPI } from "../src/github-api";

describe("GitHubAPI", () => {
  let api: GitHubAPI;
  let mockAuth;
  
  beforeEach(() => {
    // 创建模拟认证对象
    mockAuth = {
      getToken: vi.fn().mockResolvedValue("test-token")
    };
    
    // 模拟fetch
    global.fetch = vi.fn().mockResolvedValue({
      json: () => Promise.resolve({ id: 1, title: "Test Issue" }),
      ok: true,
      status: 201
    });
    
    api = new GitHubAPI(mockAuth);
  });
  
  it("should create an issue successfully", async () => {
    const result = await api.createIssue({
      owner: "test-owner",
      repo: "test-repo",
      title: "Test Issue"
    });
    
    expect(fetch).toHaveBeenCalledWith(
      "https://api.github.com/repos/test-owner/test-repo/issues",
      expect.objectContaining({
        method: "POST",
        headers: expect.objectContaining({
          Authorization: "token test-token"
        }),
        body: JSON.stringify({ title: "Test Issue", body: "" })
      })
    );
    
    expect(result).toEqual({ id: 1, title: "Test Issue" });
  });
});

调试配置：

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "扩展开发",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/pi",
      "args": ["--dev", "--extension", "${workspaceFolder}/my-extension"],
      "cwd": "${workspaceFolder}",
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/my-extension/dist/**/*.js"]
    }
  ]
}

四、进阶技巧：性能优化与版本管理

📌 本节将掌握：1.扩展性能测试方法 2.资源缓存策略 3.版本兼容性处理 4.扩展打包与分发

扩展性能测试方法论

性能测试是确保扩展在各种条件下保持响应性的关键步骤：

// src/utils/performance-tester.ts
export class ExtensionPerformanceTester {
  private results = {};
  
  async measure(name: string, fn: () => Promise<any>) {
    const start = performance.now();
    const result = await fn();
    const end = performance.now();
    
    this.results[name] = {
      duration: end - start,
      timestamp: new Date().toISOString()
    };
    
    return result;
  }
  
  // 测试工具执行性能
  async testToolPerformance(tool, paramsList) {
    for (const [i, params] of paramsList.entries()) {
      await this.measure(`tool.${tool.name}.run.${i}`, () => 
        tool.execute(params)
      );
    }
    
    // 生成性能报告
    return this.generateReport();
  }
  
  // 生成性能报告
  generateReport() {
    const report = {
      summary: {
        totalTests: Object.keys(this.results).length,
        totalDuration: Object.values(this.results)
          .reduce((sum, r) => sum + r.duration, 0),
        averageDuration: Object.values(this.results)
          .reduce((sum, r) => sum + r.duration, 0) / Object.keys(this.results).length
      },
      details: this.results
    };
    
    // 记录性能数据
    this.ctx.log.info("性能测试报告", report);
    return report;
  }
}

[!TIP] 重点关注工具执行时间、内存使用和事件处理延迟，这些指标直接影响用户体验。

高级缓存策略实现

有效的缓存策略可以显著提升扩展性能，减少API调用次数：

// src/utils/cache-manager.ts
export class AdvancedCacheManager {
  constructor(private ctx) {}
  
  // 带版本控制的缓存键
  private getVersionedKey(baseKey: string, version = "v1") {
    return `${version}:${baseKey}`;
  }
  
  // 智能缓存
  async smartCache<T>(
    key: string, 
    fetchFn: () => Promise<T>, 
    options: { 
      ttl?: number, 
      version?: string,
      staleWhileRevalidate?: boolean 
    } = {}
  ): Promise<T> {
    const { 
      ttl = 3600, 
      version = "v1",
      staleWhileRevalidate = false
    } = options;
    
    const cacheKey = this.getVersionedKey(key, version);
    
    // 尝试获取缓存
    const cached = await this.ctx.cache.get(cacheKey);
    if (cached) {
      // 如果启用了后台刷新，在返回缓存的同时异步更新
      if (staleWhileRevalidate) {
        fetchFn().then(freshData => {
          this.ctx.cache.set(cacheKey, freshData, { ttl });
        }).catch(err => {
          this.ctx.log.warn("缓存后台刷新失败", err);
        });
      }
      return cached;
    }
    
    // 缓存未命中，获取新数据
    const data = await fetchFn();
    await this.ctx.cache.set(cacheKey, data, { ttl });
    return data;
  }
  
  // 批量缓存
  async batchCache<T>(
    keys: string[],
    fetchFn: (keys: string[]) => Promise<Record<string, T>>,
    options = {}
  ): Promise<Record<string, T>> {
    const results = {};
    const missingKeys = [];
    
    // 先检查已有缓存
    for (const key of keys) {
      const cacheKey = this.getVersionedKey(key, options.version);
      const cached = await this.ctx.cache.get(cacheKey);
      
      if (cached) {
        results[key] = cached;
      } else {
        missingKeys.push(key);
      }
    }
    
    // 只获取缺失的数据
    if (missingKeys.length > 0) {
      const freshData = await fetchFn(missingKeys);
      
      // 缓存新获取的数据
      for (const [key, value] of Object.entries(freshData)) {
        const cacheKey = this.getVersionedKey(key, options.version);
        await this.ctx.cache.set(cacheKey, value, { ttl: options.ttl });
        results[key] = value;
      }
    }
    
    return results;
  }
}

版本兼容性管理

处理不同版本的pi-mono核心系统是扩展开发的重要挑战：

// src/compatibility.ts
import semver from "semver";

export class CompatibilityManager {
  private coreVersion: string;
  
  constructor(private ctx) {
    this.coreVersion = ctx.environment.coreVersion;
  }
  
  // 检查核心版本是否兼容
  isCompatible(minVersion: string, maxVersion?: string): boolean {
    if (!semver.valid(this.coreVersion)) {
      this.ctx.log.warn("无法确定核心版本，假设兼容");
      return true;
    }
    
    if (!semver.satisfies(this.coreVersion, `>=${minVersion}`)) {
      return false;
    }
    
    if (maxVersion && !semver.satisfies(this.coreVersion, `<${maxVersion}`)) {
      return false;
    }
    
    return true;
  }
  
  // 获取兼容的API实现
  getCompatibleApi(apiName: string, implementations: Record<string, any>): any {
    // 实现按版本排序
    const sortedVersions = Object.keys(implementations).sort(semver.rcompare);
    
    for (const version of sortedVersions) {
      if (semver.gte(this.coreVersion, version)) {
        return implementations[version];
      }
    }
    
    // 默认返回最早的实现
    return implementations[sortedVersions[sortedVersions.length - 1]];
  }
  
  // 处理API变更
  adaptToCoreChanges() {
    // 示例：处理工具注册API变更
    if (semver.lt(this.coreVersion, "0.9.3")) {
      // 旧版本API
      this.ctx.tools.register = (tool) => {
        this.ctx.registerTool(tool);
      };
    } else {
      // 新版本API保持不变
    }
  }
}

扩展打包与分发

将扩展打包为可分发格式，便于安装和共享：

// package.json
{
  "name": "pi-github-extension",
  "version": "1.0.0",
  "main": "dist/index.js",
  "pi": {
    "type": "extension",
    "compatibility": {
      "core": ">=0.9.3 <2.0.0"
    },
    "contributes": {
      "tools": [
        "dist/tools/issue-creator.js",
        "dist/tools/issue-list.js",
        "dist/tools/pr-manager.js"
      ],
      "commands": [
        {
          "command": "github.openIssue",
          "title": "GitHub: 创建新Issue"
        }
      ]
    }
  },
  "scripts": {
    "build": "tsc",
    "package": "npx pi-package-extension --out github-extension.pixt"
  },
  "dependencies": {
    "@mariozechner/pi-coding-agent": ">=0.9.3"
  }
}

五、最佳实践：企业级扩展开发指南

📌 本节将掌握：1.代码质量保障措施 2.安全最佳实践 3.用户体验设计原则 4.扩展维护与迭代策略

代码质量与可维护性

维护高质量代码是长期项目成功的关键：

// 扩展开发检查清单 (Checklist)
export const EXTENSION_CHECKLIST = [
  // 功能完整性
  "所有工具都有完整的参数验证",
  "错误处理覆盖所有可能的异常情况",
  "提供详细的日志输出",
  "实现适当的缓存策略",
  
  // 代码质量
  "通过所有单元测试 (覆盖率 > 80%)",
  "通过代码风格检查",
  "无安全漏洞 (依赖库无高危CVE)",
  "代码注释完整清晰",
  
  // 兼容性
  "测试至少3个核心版本",
  "处理API弃用警告",
  "提供降级策略",
  
  // 用户体验
  "提供清晰的错误提示",
  "长时间操作显示进度指示",
  "关键操作需要用户确认",
  "支持键盘快捷键"
];

安全最佳实践

扩展开发中的安全考虑至关重要：

// src/security.ts
export class SecurityManager {
  // 验证用户输入
  validateUserInput(input: string): boolean {
    // 防止命令注入
    const commandInjectionPatterns = [
      /\b(rm|rmdir|del|mv|cp|mkdir|chmod|chown)\b/,
      /\|\|?\s*[a-z0-9]/i,
      /;\s*[a-z0-9]/i,
      /\$\([^)]*\)/,
      /`[^`]*`/
    ];
    
    for (const pattern of commandInjectionPatterns) {
      if (pattern.test(input)) {
        this.ctx.log.warn("检测到潜在的命令注入攻击", input);
        return false;
      }
    }
    
    return true;
  }
  
  // 安全的文件路径处理
  sanitizeFilePath(path: string, baseDir: string): string {
    const resolvedPath = path.resolve(baseDir, path);
    
    // 防止路径遍历攻击
    if (!resolvedPath.startsWith(baseDir)) {
      throw new Error("访问被拒绝：路径超出允许范围");
    }
    
    return resolvedPath;
  }
  
  // 数据脱敏
  redactSensitiveData(data: string): string {
    // 脱敏API密钥
    return data.replace(/(api_key|token|secret)[\s:=]+[a-zA-Z0-9]{8,}/gi, 
      (match, key) => `${key}=***`);
  }
}

[!WARNING] 永远不要在前端代码中硬编码API密钥或敏感凭证，应使用pi-mono的安全存储机制。

扩展用户体验设计

优秀的用户体验是扩展成功的关键因素：

// src/ui/experience-optimizations.ts
export class UXOptimizer {
  // 渐进式结果展示
  async showProgressiveResults(operation: Promise<any>, steps: string[]) {
    const progress = this.ctx.ui.createProgressBar({
      title: "处理中",
      total: steps.length
    });
    
    let stepIndex = 0;
    
    // 定期更新进度
    const progressInterval = setInterval(() => {
      if (stepIndex < steps.length) {
        progress.update(stepIndex + 1, steps[stepIndex]);
        stepIndex++;
      }
    }, 1500);
    
    try {
      const result = await operation;
      clearInterval(progressInterval);
      progress.complete("处理完成");
      return result;
    } catch (error) {
      clearInterval(progressInterval);
      progress.fail("处理失败");
      throw error;
    }
  }
  
  // 智能提示系统
  suggestNextActions(context: any) {
    // 根据当前上下文提供智能建议
    if (context.lastAction === "createIssue") {
      return [
        { 
          label: "创建Pull Request", 
          command: "github.createPullRequest",
          description: "为刚刚创建的issue创建对应的PR"
        },
        { 
          label: "设置提醒", 
          command: "reminder.set",
          description: "为这个issue设置截止日期提醒"
        }
      ];
    }
    
    return [];
  }
}

图2：pi-mono会话树视图，展示了工具调用历史和上下文切换

扩展维护与迭代策略

长期维护扩展需要系统化的方法：

// src/updater.ts
export class ExtensionUpdater {
  private updateCheckInterval = 24 * 60 * 60 * 1000; // 24小时
  private lastCheckTime = 0;
  
  constructor(private ctx) {
    // 设置定期检查更新
    this.scheduleUpdateCheck();
  }
  
  private scheduleUpdateCheck() {
    setInterval(() => this.checkForUpdates(), this.updateCheckInterval);
  }
  
  async checkForUpdates(force = false): Promise<boolean> {
    const now = Date.now();
    if (!force && now - this.lastCheckTime < this.updateCheckInterval) {
      return false; // 未到检查时间
    }
    
    this.lastCheckTime = now;
    
    try {
      const response = await fetch("https://extensions.pi-mono.org/extensions/my-github-extension/latest");
      const latest = await response.json();
      
      // 比较版本
      if (semver.gt(latest.version, this.ctx.extension.metadata.version)) {
        this.notifyUpdateAvailable(latest);
        return true;
      }
    } catch (error) {
      this.ctx.log.warn("更新检查失败", error);
    }
    
    return false;
  }
  
  private async notifyUpdateAvailable(update) {
    const result = await this.ctx.ui.showConfirm({
      title: "扩展更新可用",
      message: `我的GitHub扩展有新版本 ${update.version} 可用。是否更新？`,
      detail: update.changelog,
      confirmLabel: "立即更新",
      cancelLabel: "稍后"
    });
    
    if (result) {
      await this.performUpdate(update);
    }
  }
  
  private async performUpdate(update) {
    try {
      const progress = this.ctx.ui.createProgressBar({
        title: "更新扩展",
        total: 100,
        label: "下载中"
      });
      
      // 模拟更新过程
      for (let i = 0; i <= 100; i += 10) {
        await new Promise(resolve => setTimeout(resolve, 300));
        progress.update(i);
      }
      
      progress.complete("更新完成");
      this.ctx.ui.showMessage("扩展已更新，将在下次启动时生效");
    } catch (error) {
      this.ctx.ui.showError(`更新失败: ${error.message}`);
    }
  }
}

官方API文档速查表

API类别	核心方法	描述	参数	返回值
工具注册	`registerTool(tool: Tool)`	注册新工具	Tool对象	void
事件处理	`events.on(event: string, handler: Function)`	监听事件	事件名, 处理函数	取消订阅函数
UI交互	`ui.showMessage(message: string)`	显示消息	消息内容	Promise
配置管理	`settings.get(key: string)`	获取配置值	配置键	Promise
缓存服务	`cache.set(key: string, value: any, options?: CacheOptions)`	设置缓存	键, 值, 选项	Promise
文件操作	`tools.readFile(path: string)`	读取文件内容	文件路径	Promise
认证存储	`authStorage.set(key: string, value: string)`	存储认证数据	键, 值	Promise