Extension

介绍

Tuanjie AI Extension 是一个强大的扩展系统，允许用户扩展 Codely CLI 的功能并与其他人共享这些能力。通过 Extension，您可以打包提示词（prompts）、MCP 服务器、自定义命令、主题、钩子（hooks）、子代理和代理技能，以一种易于安装和共享的方式提供给社区使用。

什么是 Extension？

Extension 是 Codely CLI 的功能扩展包，可以将多个功能组件打包在一起，方便安装和分发。

核心特性：

• 模块化：可以将多个功能组件打包在一起
• 可配置：支持设置和依赖管理
• 版本控制：支持版本管理和更新

Extension 能做什么？

Extension 提供了多种自定义 Codely CLI 的方式：

功能	说明	使用场景	触发方式
MCP 服务器	向模型暴露新工具和数据源的标准方式	当您需要模型执行新操作时，如从内部 API 获取数据、查询数据库或控制本地应用程序	模型
自定义命令	类似 /my-cmd 的快捷方式，执行预定义的提示词或 Shell 命令	用于重复性任务或保存常用复杂提示词，非常适合自动化	用户
上下文文件（codely.md）	包含指令的 Markdown 文件，在每个会话开始时加载到模型上下文中	定义扩展的"个性"、设置编码标准或提供模型应掌握的关键知识	CLI 提供给模型
代理技能（Agent Skills）	一组专门的指令和工作流，仅在需要时激活	用于复杂、偶尔执行的任务（如"创建 PR"或"安全审计"），避免在技能未被使用时 clutter 主上下文窗口	模型
钩子（Hooks）	在特定生命周期事件（如工具调用前/后）拦截和自定义 CLI 行为	当您想要根据模型正在执行的操作自动执行操作时，如验证工具参数、记录活动或修改模型的输入/输出	CLI
自定义主题	一组颜色定义，用于个性化 CLI 界面	为扩展提供独特的视觉识别，或提供专业的高对比度或主题化配色方案	用户（通过 /theme）

Extension 的优势

• 简化安装：一键安装多个功能组件
• 统一管理：所有扩展功能集中管理
• 社区共享：方便与团队和社区分享
• 版本控制：支持版本管理和更新

通过 GUI 使用 Extension

打开扩展管理

1. 打开命令输入框

   • 在主界面底部找到命令输入区域

2. 输入扩展管理命令

   • 输入 / 打开命令菜单
   • 选择 "Manage extension" 选项

3. 管理扩展

   • 您可以选择我们提供的 extension 直接使用
   • 也可以创建您自己的 extension

4. 使用扩展

   • 创建完成后，您新建的 extension 可以直接通过 @ 被调用

通过 CLI 使用 Extension

管理 Extension

您可以使用交互式命令验证已安装的 Extension 及其状态：

/extensions list

也可以在终端中使用命令组管理 Extension：

codely extensions list

安装 Extension

通过提供 GitHub 仓库 URL 安装 Extension：

codely extensions install https://github.com/your-username/your-extension

其他管理命令

卸载 Extension：

codely extensions uninstall <extension-name>

更新 Extension：

codely extensions update <extension-name>

查看 Extension 信息：

codely extensions info <extension-name>

安装 Extension 后，重启 Codely CLI 会话即可开始使用新功能。

如何创建 Extension

前置条件

在开始之前，请确保：

1. 已安装 Codely CLI
2. 对 Node.js 有基本了解

Step 1: 创建新 Extension

最简单的开始方式是使用内置模板。我们将使用 mcp-server 示例作为基础。

运行以下命令创建一个名为 my-first-extension 的新目录，包含模板文件：

codely extensions new my-first-extension mcp-server

这将创建一个具有以下结构的目录：

my-first-extension/
├── example.js
├── gemini-extension.json
└── package.json

Step 2: 理解 Extension 文件

您的 Extension 包含几个定义其行为的关键文件。

gemini-extension.json

清单文件告诉 Codely CLI 如何加载和使用您的 Extension。

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["\$\{extensionPath\}\$\{/\}example.js"],
      "cwd": "\$\{extensionPath\}"
    }
  }
}

• name: Extension 的唯一名称
• version: Extension 的版本
• mcpServers: 定义用于添加新工具的 Model Context Protocol (MCP) 服务器
• command, args, cwd: 指定如何启动服务器。${extensionPath} 变量会被替换为 Extension 目录的绝对路径

example.js

此文件包含 MCP 服务器的源代码。它使用 @modelcontextprotocol/sdk 来定义工具。

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});

// 注册一个名为 'fetch_posts' 的新工具
server.registerTool(
  'fetch_posts',
  {
    description: 'Fetches a list of posts from a public API.',
    inputSchema: z.object({}).shape,
  },
  async () => {
    const apiResponse = await fetch(
      'https://jsonplaceholder.typicode.com/posts',
    );
    const posts = await apiResponse.json();
    const response = { posts: posts.slice(0, 5) };
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response),
        },
      ],
    };
  },
);

const transport = new StdioServerTransport();
await server.connect(transport);

package.json

Node.js 项目的标准配置文件，定义了 Extension 的依赖项和脚本。

Step 3: 添加 Extension 设置

某些 Extension 需要配置，如 API 密钥或用户偏好。让我们添加一个 API 密钥的设置。

1. 打开 gemini-extension.json

2. 在配置中添加 settings 数组：

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "The API key for the service.",
      "envVar": "MY_SERVICE_API_KEY",
      "sensitive": true
    }
  ],
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["\$\{extensionPath\}\$\{/\}example.js"],
      "cwd": "\$\{extensionPath\}"
    }
  }
}

当用户安装此 Extension 时，Codely CLI 会提示他们输入"API Key"。该值将安全地存储在系统密钥链中（因为 sensitive 为 true），并作为 MY_SERVICE_API_KEY 环境变量注入到 MCP 服务器的进程中。

Step 4: 链接您的 Extension

将您的 Extension 链接到 Codely CLI 安装以进行本地开发。

1. 安装依赖：

cd my-first-extension
npm install

2. 链接 Extension：

codely extensions link .

link 命令会从 Codely CLI Extension 目录到您的开发目录创建一个符号链接。您所做的更改会立即反映出来。

3. 重启 Codely CLI 会话以使用新的 fetch_posts 工具。通过询问"fetch posts"来测试。

Step 5: 添加自定义命令

自定义命令为复杂提示词创建快捷方式。

1. 创建一个 commands 目录和命令组的子目录

macOS/Linux:

mkdir -p commands/fs

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "commands\fs"

2. 创建文件 commands/fs/grep-code.toml:

prompt = """
Please summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r {{args}} .}
"""

此命令 /fs:grep-code 接受一个参数，运行 grep shell 命令，并将结果通过管道传递给提示词进行摘要。

3. 保存文件后，重启 Codely CLI。运行 /fs:grep-code "some pattern" 来使用您的新命令。

Step 6: 添加自定义 GEMINI.md

通过向 Extension 添加 GEMINI.md 文件为模型提供持久上下文。这对于设置行为或提供重要的工具信息很有用。

1. 在 Extension 目录的根目录创建名为 GEMINI.md 的文件：

# My First Extension Instructions

You are an expert developer assistant. When the user asks you to fetch
posts, use the `fetch_posts` tool. Be concise in your responses.

2. 更新您的 gemini-extension.json 以加载此文件：

{
  "name": "my-first-extension",
  "version": "1.0.0",
  "contextFileName": "GEMINI.md",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["\$\{extensionPath\}\$\{/\}example.js"],
      "cwd": "\$\{extensionPath\}"
    }
  }
}

3. 重启 Codely CLI。现在，在 Extension 处于激活状态的每个会话中，模型都会拥有来自 GEMINI.md 文件的上下文。

Step 7: （可选）添加代理技能（Agent Skill）

代理技能（Agent Skills）打包专业知识和工作流。技能仅在需要时激活，从而节省上下文 Token。

1. 创建 skills 目录和技能的子目录

macOS/Linux:

mkdir -p skills/security-audit

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "skills\security-audit"

2. 创建 skills/security-audit/SKILL.md 文件：

---
name: security-audit
description:
  Expertise in auditing code for security vulnerabilities. Use when the user
  asks to "check for security issues" or "audit" their changes.
---

# Security Auditor

You are an expert security researcher. When auditing code:

1. Look for common vulnerabilities (OWASP Top 10).
2. Check for hardcoded secrets or API keys.
3. Suggest remediation steps for any findings.

3. Codely CLI 会自动发现与您的 Extension 打包的技能。当模型识别出相关任务时，它会激活这些技能。

Step 8: 发布您的 Extension

当您的 Extension 准备就绪时，可以通过 Git 仓库或 GitHub Releases 与其他人共享。有关详细说明，请参阅 Extension 发布指南，并了解如何在 Gallery 中列出您的 Extension。

常见问题

Q: 如何查看已安装的 Extension？

A: 使用 /extensions list 或 codely extensions list 命令可以查看所有已安装的 Extension 及其状态。

Q: Extension 和自定义命令有什么区别？

A: Extension 是一个打包系统，可以包含多个功能组件（如 MCP 服务器、自定义命令、技能等），而自定义命令只是 Extension 中的一种功能类型。

Q: 如何更新 Extension？

A: 使用 codely extensions update <extension-name> 命令可以更新指定的 Extension 到最新版本。

Q: Extension 的设置存储在哪里？

A: Extension 的设置存储在系统密钥链中，确保敏感信息的安全性。对于非敏感设置，则存储在配置文件中。

最佳实践

开发 Extension

1. 使用模板：从官方模板开始，确保结构正确
2. 本地测试：使用 codely extensions link . 进行本地开发测试
3. 版本管理：遵循语义化版本控制规范
4. 文档完善：为您的 Extension 编写清晰的文档和使用示例

分享 Extension

1. 开源发布：通过 GitHub 仓库发布您的 Extension
2. 描述清晰：在 README 中清楚说明 Extension 的功能和用途
3. 示例丰富：提供详细的使用示例和演示
4. 维护更新：及时修复 bug 和添加新功能

安全注意事项

1. 敏感数据：使用 sensitive: true 标记敏感设置
2. 代码审查：确保 MCP 服务器代码的安全性
3. 权限控制：为自定义命令设置适当的权限
4. 依赖检查：定期检查和更新依赖项

---

文档版本：2.0 最后更新：2026年3月25日