跳到主要内容

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
  1. 链接 Extension:
codely extensions link .

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

  1. 重启 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"
  1. 创建文件 commands/fs/grep-code.toml:
prompt = """
Please summarize the findings for the pattern `{{args}}`.

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

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

  1. 保存文件后,重启 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.
  1. 更新您的 gemini-extension.json 以加载此文件:
{
"name": "my-first-extension",
"version": "1.0.0",
"contextFileName": "GEMINI.md",
"mcpServers": {
"nodeServer": {
"command": "node",
"args": ["\$\{extensionPath\}\$\{/\}example.js"],
"cwd": "\$\{extensionPath\}"
}
}
}
  1. 重启 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"
  1. 创建 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.
  1. Codely CLI 会自动发现与您的 Extension 打包的技能。当模型识别出相关任务时,它会激活这些技能。

Step 8: 发布您的 Extension

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

常见问题

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

A: 使用 /extensions listcodely 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日