SDK 插件目录

按进程、会话或宿主信任范围加载插件，并检查实际插件集合。

This page has not been translated into English yet. The original Chinese version is shown below.

插件将 Skills、Hooks、MCP、自定义代理或 LSP 配置作为一组能力分发。只有单项扩展时可直接用 mcpServers、hooks 或 customAgents；需要一起版本化和部署多项扩展时再组织插件目录。

目录布局

my-plugin/
├── plugin.json
├── SKILL.md
├── hooks.json
├── .mcp.json
├── agents/
│   └── code-reviewer.md
└── skills/
    └── lint-fix/
        └── SKILL.md

目录需有插件 manifest 或顶层 SKILL.md。manifest 还可位于 .github/plugin.json 或 .github/plugin/plugin.json；其他子系统均可选，按插件实际提供的能力添加。LSP 配置使用 .lsp.json。完整 manifest 字段应查当前 runtime 的 /plugin 文档，不从目录示例推导未列出的 Schema。

选择加载范围

入口	作用范围与传递方式	路径要求
`--plugin-dir`	CLI 启动参数，固定该 runtime 进程的插件集合	路径由启动环境解析
会话 `pluginDirectories`	随 `session.create` / `session.resume` 经 JSON-RPC 传递	相对 `workingDirectory`，未设时相对 runtime 工作目录；建议绝对路径
客户端 `builtinPluginDirectories`	连接并验证协议后、`start` 返回和会话创建前注册宿主自带可信插件	必须是绝对路径

三种入口不能混为一个开关。builtinPluginDirectories 专供应用控制并信任的内置插件；普通用户提供的目录不应仅为方便就归入该信任范围。该选项省略或为空时不发对应 RPC。

随客户端启动 runtime

import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk";

const client = new CopilotClient({
  connection: RuntimeConnection.forStdio({
    args: [
      "--plugin-dir", "./plugins/code-reviewer",
      "--plugin-dir", "./plugins/lint-fix",
    ],
  }),
});
await client.start();

--plugin-dir 可以重复。通过 forUri 连接已有 runtime 时，SDK 不会替服务追加启动参数；应在启动服务器时传入参数，或选择会话级配置。

会话级显式目录

const session = await client.createSession({
  pluginDirectories: ["/opt/my-app/plugins/code-reviewer"],
});

会话选项通过 RPC 到达外部 runtime，目录也必须在那里可访问。无效路径会被记录并跳过，不会因此让会话创建失败，所以创建成功后仍要检查插件是否真的加载。

这是显式加载：即使 enableConfigDiscovery 为 false，目录中的代理和规则仍会加载。它们在会话来源优先级中位于项目来源之后、个人或 home 来源之前。不要把这里的会话范围误读为给共享 runtime 的每个会话都加同一插件。

控制环境中已有的插件

通过 CLI /plugin 或 installedPlugins 用户设置安装的插件属于环境中持久存在的配置。启动参数 --plugin-dir 是显式且临时的，优先于环境自动发现；和 marketplace 条目指向相同 cache path 时会去重。

官方给出的确定性启动方式是为 runtime 设置 COPILOT_PLUGIN_DIR_ONLY=true，再用 --plugin-dir 列出目录，抑制自动发现。此规则针对该启动模式，本页不推断它与所有会话或宿主内置加载入口组合后的优先级。

检查插件是否生效

const result = await session.rpc.plugins.list();
for (const plugin of result.plugins) {
  console.log(plugin.name, plugin.enabled);
}

启动参数加载的插件以所给目录作为 cache path；marketplace 插件带有来源信息。相同插件复制到两个不同目录可能加载两次，造成 Hooks 重复触发，不能依赖名称自动去重。

出现没有 manifest 或 SKILL.md 的错误时先修目录结构；插件存在但技能或代理不可见时，核对 manifest 声明或 agents/*.md、skills/*/SKILL.md 隐式布局。官方还提供 session.rpc.skills.reload() 用于重新读取技能变化，不必为每次技能编辑都重启。

插件代理可作为 task(agent_type=...) 的工作者交给 Fleet 调度。Fleet 专题仍以启动参数介绍插件注册，而插件目录专题已列出会话与宿主入口；使用新入口时应以匹配版本的 SDK/runtime 和专门参考为准。