管理插件

插件把团队维护的技能说明、脚本和参考资料带进 Z Tag，再按 使用范围 或随连接器加载。插件的内容有三种来源：从 插件来源 同步，一个插件来源是 Git 仓库里的一个目录，可以同步出一个或多个插件；在控制台上传一个压缩包，它直接成为一个插件；或者在控制台填写远程 MCP 服务的地址，它们直接成为一个 MCP 插件。插件是什么、更新后从什么时候生效，见技能与插件。

谁可以做：组织插件由组织 Owner 在 组织管理 → 插件 新建和维护，Admin 可以查看。成员可以在 我的资源 → 插件 为自己和 ZAI 的私信建个人插件，操作与本页相同，见在控制台管理自己的资源。

前提

• 控制台侧栏没有 插件 时，表示这套 Z Tag 服务没有开启这项功能，请 Z Tag 管理员开启。Z Tag 管理员关闭这项功能后，ZAI 从下一条消息起不再加载任何插件，控制台里也不再显示插件；已同步的内容和使用范围都保留，重新开启后照常加载。
• 从 Git 同步时，同一归属（组织或你自己）的连接器里已经添加了 Git 仓库。仓库地址（HTTPS 或 SSH）和凭证在那里维护；没有可用的 Git 仓库时，新建页会提示 尚无 Git 仓库。
• 从 Git 同步还要求这套 Z Tag 服务配置了从 Git 同步插件。没有配置时只能上传：新建 里的 从 Git 同步 不可用，已有的插件来源不能修改或同步，已有的插件照常加载；需要时请 Z Tag 管理员配置。
• 插件的内容满足内容要求；上传的包另有包的要求。

新建插件

进入 插件，点 新建，选择 从 Git 同步、上传插件 或 填写 MCP 服务。上传见上传插件，填写 MCP 服务见填写 MCP 服务；选 从 Git 同步 后填写：

• 名称：最多 120 个字符，之后可以在详情页点名称旁的铅笔修改。
• Git 仓库：从同一归属的连接器里选一个 Git 仓库，列表按“连接器 / 仓库”显示。插件同步始终只读，即使仓库允许推送也不会推送。
• Git 引用类型 和 Git 引用：选分支、标签或提交，再填对应的名称或提交号，默认是分支 main。
• 仓库目录：插件所在的目录，默认 . 表示仓库根目录。
• 同步方式：手动同步 或 自动同步，默认手动，见保持同步。
• 同步网络（可选）：同步时使用哪份沙箱配置的网络，见同步网络。

点 创建并同步，建好的是一个插件来源，页面转到它的详情，状态是 等待首次同步。第一次同步成功后，同步出的插件列在插件来源的 同步出的插件 下，也出现在插件列表里。还没有同步出插件的插件来源（等待首次同步或同步失败）在 插件来源 标签里，见插件来源。

之后在插件来源详情修改来源配置（从插件详情的 概览 点 在插件来源中修改 过去），点 保存并同步 会立即重新同步。

上传插件

在 新建 里选 上传插件，填写：

• 插件文件：点 选择文件…，选一个 .zip、.plugin、.skill、.tar.gz 文件或单个 SKILL.md。大小上限见限制。
• 名称（可选）：留空时使用 plugin.json 或技能里的名称，之后可以在详情页点名称旁的铅笔修改。
• 插件标识（可选）：插件在同一归属里的唯一标识，创建后不能修改。只能用小写字母、数字和连字符（连字符不能连用，也不能在开头或结尾），最多 40 个字符，不能是 ztag 或以 ztag- 开头。留空时按包里的名称生成：有 plugin.json 时取它的 name；只有一个技能时取这个技能的 name；都没有时取压缩包里唯一的顶层文件夹名或文件名。名称不合规时自动转换成合规的写法；生成的插件标识已被占用时，页面会请你填写一个。
• 更新说明（可选）：写给维护者看的说明，显示在 版本 标签里。

点 上传并创建。包通过检查后成为插件的版本 1 并立即生效，页面转到插件详情；没有通过时，页面写明原因，点 查看要求 打开本页对应的说明，修正后重新选择文件上传。短时间内上传太多次时，页面会提示稍后再试。

上传较慢时可以点 停止上传。停止或网络中断时，文件可能已经送达，上传仍可能生效；再次上传同一个文件会得到同一个结果，不会重复创建插件。上传还没结束就离开页面时，控制台会先确认，离开后上传同样可能生效。

包的要求：

• 包的根目录要有 .claude-plugin/plugin.json，或者有一个 SKILL.md（.skill 包和单个 SKILL.md 都是这种）。整个包只有一个顶层文件夹时，按文件夹里面的内容判断；macOS 压缩时加入的 __MACOSX/ 和 .DS_Store 会去掉。
• 包里有不止一个 plugin.json、plugin.json 不在根目录、包里有插件市场清单（插件市场请放进 Git 仓库同步），或者包是 Codex 格式的插件时，上传失败。
• 文件名要用 UTF-8 编码，不能含 \、: 和控制字符，不能有只差大小写的同名文件；zip 里不能有加密的文件或符号链接。
• 其余要求与同步相同，见内容要求和限制。

Z Tag 把上传的包整理成统一的格式保存，下载当前包 得到的是整理后的 .tar.gz，文件内容与上传的相同。

要更新上传的插件，在它的详情点 上传新版本，选择新的文件，可以填写 更新说明，点 上传。新版本通过检查后立即成为当前生效的版本；内容与最新版本相同时不会新增版本。打开 上传新版本 之后如果有人上传了新版本，页面会写明现在最新是哪个版本，确认仍要用你的文件作为新版本时再点 上传。

填写 MCP 服务

团队自己运营或第三方提供的远程 MCP 服务不必打包：在 新建 里选 填写 MCP 服务，填写：

• 名称：最多 120 个字符，之后可以在详情页点名称旁的铅笔修改。
• 插件标识（可选）：规则同上传插件，留空时由名称生成。ZAI 看到的工具名由它和服务名称组成：mcp__plugin_<插件标识>_<服务名称>__<工具>。
• MCP 服务：每个服务填 服务名称（字母、数字、- 或 _，不以 _ 开头或结尾、不含连续的 __，同一插件内不重复）、以 https:// 开头的 地址，以及可选的 请求头 和 超时（单次工具调用最长等多少秒，1 到 3,600 秒，留空用默认值）。点 添加服务 可以填多个，上限见限制。
• 更新说明（可选）：显示在 版本 标签里。

点 创建插件，填写的服务成为插件的版本 1 并立即生效，页面转到插件详情。之后在详情点 编辑 MCP 服务 修改服务、地址、请求头或超时，点 保存 成为新的生效版本；内容与最新版本相同时不新增版本。打开编辑之后有人保存了新版本时，页面会写明现在最新是哪个版本。

填写的服务和包里 .mcp.json 声明的服务按同一套规则检查，见内容要求：

• 只支持用 Streamable HTTP 连接的 https 地址，不能是 localhost、127.0.0.1 这类本机地址。
• 地址和请求头里不能有凭证：Authorization、X-Api-Key、AppKey 等认证请求头，地址里的账号密码或 token、sign、ak 这类参数，看起来像令牌的值（例如以 Bearer 开头），以及 ${...} 变量，都会让保存失败。这项检查只认得出常见写法，写在地址路径里的密钥认不出来，同样不要这样写。
• 请求头只填 X-Region 这类不含凭证的值；Host、Content-Type、Accept、Mcp- 开头等由连接本身决定的请求头不能填。
• 需要凭证的服务，在同一使用范围的连接器里为服务地址添加凭证，例如 Bearer Token；ZAI 访问这个地址时，Z Tag 自动附上凭证，ZAI 和插件都看不到它。用 OAuth2 Client Credentials 换取令牌的服务，按服务的要求填写 Resource。
• 同一使用范围里的凭证对所有插件都生效，不按插件区分。

ZAI 开始处理一条消息时连接插件里的 MCP 服务，并知道每个服务有没有连上。服务没有连上时（例如没有覆盖它的凭证、服务拒绝访问），ZAI 照常回复，需要这个服务时会说明它不可用。

检查凭证

表单里每个地址下方、插件 内容 标签的 地址与凭证 一列都会显示：在 凭证检查范围 里新开的 Session 访问这个服务时，Z Tag 会怎样处理。检查带上服务的请求头，按 MCP 服务实际收到的 POST、GET、DELETE 请求判断。个人插件检查的是你的 个人范围。

组织插件的范围默认是 整个组织，这时只算加到整个组织的连接器和组织的默认沙箱配置。Workspace 或 Channel 可以加自己的连接器、换沙箱配置，结论可能不同，要看具体范围就换成那个 Workspace 或 Channel。成员的 个人范围 按各自的个人配置，组织插件这里不检查。

• 带凭证：自动附上写明的连接器里的那份凭证，凭证设了到期时间时一并写明。
• 无凭证放行：没有凭证覆盖这个地址，由域名或沙箱配置放行，访问时不附凭证。服务需要凭证时，点 在连接器里添加凭证，并把连接器加到这个范围。
• 方法不允许：凭证覆盖这个地址，但请求方法不够。MCP 服务会用到 POST、GET 和 DELETE，在凭证的 请求方法 里补上写明缺少的方法，或者留空。
• 部分请求受限：POST 请求带凭证，但 GET 或 DELETE 请求不同（例如被凭证的请求规则拒绝），逐个写明。
• 取决于请求内容：凭证的请求规则要看每条请求的内容，符合规则的请求带凭证，其余的会被拒绝或改用别的凭证。
• 会被拒绝：写明原因，例如凭证覆盖这个主机但不含这个路径、沙箱配置不允许访问、凭证已过期、需要的网络隧道不可用、内网地址没有经过网络隧道。

带凭证和无凭证放行时还会写明怎么连过去：经网络隧道（内网路由或连接器指定的隧道），或者直连。直连的地址要能从公网访问；企业内网里的 MCP 服务要先配好内网路由或隧道，否则访问会被拒绝。

检查只看连接器和沙箱配置，不会真的访问这个地址，也不知道服务自己是否接受这份凭证。它不影响保存：没有凭证的服务照常加载，ZAI 连不上时会说明。

插件来源

插件 页的 插件来源 标签列出这个归属的全部插件来源（插件列表在 本组织 标签，个人视图里叫 我的插件）：名称和 Git 仓库、同步状态（同步失败时写明原因）、最近同步成功的时间和提交号，以及同步出的插件。最近一次同步的内容没有通过检查的插件标 未通过检查，已从清单里删掉的标 已不在清单中。还没有同步出插件的插件来源只在这里出现，本组织 标签上方会提示有几个，点 查看插件来源 过来。

点插件来源的名称打开它的详情：可以 立即同步、修改来源配置、删除插件来源；最近一次同步有没同步的清单条目（例如指向其他仓库的插件）或其他提示时，列在 最近一次同步的提示 下。

版本与内容

插件详情有 概览、内容、版本、使用范围 和 相关资源 几个标签：

• 概览：当前生效的版本号、插件标识、创建方式（从 Git 同步、上传或填写 MCP 服务）和说明，有包的插件可以 下载当前包。从 Git 同步的插件还显示插件来源、清单条目、Git 仓库，以及最近同步成功的时间和提交号。
• 版本：列出保留的版本，新的在前：版本号、生效中 标记、来源修订（Git 提交号，或上传内容的摘要）、时间和更新说明。Z Tag 保留当前生效的版本和上一个版本，更早的版本会在稍后自动清理，所以刚上传或同步后可能暂时看到更多版本。最近一次同步的内容没有通过检查时，这里写明是哪一次同步、什么原因；插件继续使用当前生效的版本，第一次同步就没通过时它还没有版本。
• 内容：一个版本里有什么，见下一节。

查看插件内容

内容 标签默认显示当前生效的版本，可以在上方切换版本，也可以在 版本 标签点 查看内容；链接里的版本已被清理时，显示当前生效的版本。

• 技能：每个技能的名称、目录和说明。标记提示技能声明了 hooks 或内联命令（不会执行），或者不会被自动选用。
• MCP 服务：版本里有通过检查的远程 MCP 服务时列出，包括服务名称、ZAI 看到的服务名（plugin_<插件标识>_<服务名称>）、地址、请求头名称和超时，以及每个地址在所选范围里会不会带上凭证（见检查凭证）。
• 已忽略：不会生效的组件，例如命令、子代理和用命令启动的本地 MCP 服务。
• 会被引擎读取的文件：包里会随技能进入 Session 工作目录的 .claude 目录、CLAUDE.md 和 AGENTS.md，引擎可能把它们当作指令或配置读取。
• 告警：不影响版本生效的问题，例如技能的 name 与目录名不一致。

在内容检查加入之前生成的版本没有这些信息，下一次同步或上传新版本后显示。

内容要求

• 插件按 Claude Code 插件的目录结构读取。有 .claude-plugin/plugin.json 时以它为准，它必须是一个 JSON 对象并写明 name（不含空格、@、: 和 /）。技能放在 skills/<技能名>/SKILL.md，plugin.json 的 skills 还可以列出别的技能目录。没有 plugin.json 时，有 skills/ 目录、.mcp.json 或根目录的 SKILL.md 就按这种结构读取；三样都没有时，目录里每个含 SKILL.md 的文件夹各算一个技能。根目录的 SKILL.md 只在没有 skills/ 目录、plugin.json 也没有列 skills 时，让整个插件成为一个技能。
• Session 只加载按上面的结构列出的技能，示例目录等其他位置的 SKILL.md 不会加载。技能用 name（不符合技能命名规范时用目录名）出现；与其他插件或 ZAI 自带的技能同名时用哪一个，见同名技能用哪一个。
• 每个 SKILL.md 开头都要有 YAML 格式的说明（frontmatter），至少写 description。说明写错、缺 description、技能名或技能目录名以 ztag- 开头、同一个插件里有两个技能同名（不区分大小写），或文件超过大小上限时，这个插件这一次的内容不会发布。说明里没加引号的值含有 : 等其他工具能接受的写法时，按加了引号读取。name 不符合技能命名规范时照常发布，技能改用目录名；name 与目录名不一致时也照常发布。
• 插件也可以只有参考资料、脚本等附属文件，没有技能。
• .mcp.json 和 plugin.json 的 mcpServers 里的远程 MCP 服务随插件加载，用法与填写 MCP 服务相同。配置会检查：配置里不能写凭证，Authorization 等认证请求头、地址里的账号密码或 token 参数、看起来像令牌的值、${...} 变量、headersHelper 和 oauth 都会让这一次的内容不发布；只认 type 为 http（或 streamable-http）的 https 地址，sse、ws 类型、本机地址、地址里有空格、Host 等由连接本身决定的请求头，或写了地址却没写 type 也不发布；用命令启动的本地服务不生效。需要凭证的服务把凭证放在连接器里。
• commands/、agents/、hooks/、bin/ 等其他 Claude Code 插件组件不会生效。plugin.json 的 userConfig 里有标为 sensitive 或 required 的选项时，这一次的内容不发布。
• 仓库目录里有 Claude Code 插件市场的清单 .claude-plugin/marketplace.json 时，清单里列出的每个插件分别同步成一个插件；指向其他仓库、网址或 npm 的插件不会同步。没有这个清单时，整个目录是一个插件。同一个插件来源同步出的插件共用来源配置：修改来源配置或点 立即同步，作用于这个来源的全部插件。
• 清单里的插件改名时，在清单的 renames 里写明旧名到新名，改名后的插件沿用原来的使用范围。从清单里删掉的插件不再加载，详情页提示它已不在插件来源的清单里，使用范围保留到你删除它；它重新出现在清单里时恢复加载。
• 仓库目录里不能有 Git 子模块，也不能有用 Git LFS 管理的文件，否则同步失败。连接器里 Git 仓库的 LFS 支持只用于 ZAI 在任务里拉取和推送代码。
• 目录里的符号链接只能指向插件目录内的文件或子目录，不能指向目录外，也不能再经过另一个符号链接。
• 只接受普通文件、目录和符号链接，不要依赖加载时运行构建脚本。

限制

• 插件压缩后不超过 8 MiB，展开后不超过 64 MiB。
• 最多 10,000 个条目（文件、目录和符号链接）。
• 每个文件或目录名不超过 255 字节（UTF-8 编码，一个汉字约占 3 字节）；从插件根目录算起的路径不超过 3,072 字节、128 层。
• 每个插件最多 100 个技能；每个 SKILL.md 不超过 1 MiB，开头的说明不超过 16 KiB。
• 每个插件最多配置 16 个远程 MCP 服务；plugin_<插件标识>_<服务名称> 超过 64 个字符，或服务名称以 _ 开头或结尾、含连续的 __ 的服务不加载，在控制台填写时不能保存。
• 一个 Session 里最多加载 32 个插件的 MCP 服务，请求头等配置合计不超过 64 KiB，超出的按插件顺序不加载。
• 使用 Claude Code 时，工具名 mcp__plugin_<插件标识>_<服务名称>__<工具> 超过 128 个字符的 MCP 服务这一轮不加载，ZAI 会说明它不可用。
• 同步时会按所选的 Git 引用拉取整个 Git 仓库，仓库超过 512 MiB 时同步失败，即使插件所在的目录很小。插件所在的仓库较大时，把插件放进专用的较小仓库。
• 插件市场清单最多列 100 个插件。

超过任一上限时同步失败或上传失败。

ZAI 只把插件当作技能使用，技能里的命令不会自动运行：

• SKILL.md 开头声明的 hooks 不会执行。
• 正文里的 !`命令` 和 ```! 代码块不会在加载技能时运行。使用 Claude Code 时，ZAI 读到的是占位文字 [shell command execution disabled by policy]；Codex 不识别这种写法，ZAI 读到原样的命令文字。需要先跑的命令，写成让 ZAI 执行的步骤。
• 技能目录里 Claude Code 插件的清单、命令、子代理和 MCP 服务配置都不会生效。

这些写法不会让同步失败；插件根目录的 MCP 服务配置要符合内容要求。

同步状态

插件列表、插件来源 标签、插件详情和插件来源详情显示同步状态，点 状态说明 打开本节：

同步失败时

插件来源详情和 插件来源 标签在 同步失败 下写明原因，点 查看排查方法 打开本节（原因是插件市场清单或仓库大小时，点 查看要求 打开对应的说明）。同步失败不影响已经发布的版本：ZAI 继续加载上一次同步成功的内容，即使你已经修改了来源配置；从没同步成功过的插件来源不会同步出插件，只列在 插件来源 标签里。可以用 当前生效 的版本号、下载当前包 和提交号核对正在使用的版本。

清单里只有某个插件的内容没通过检查时，插件来源仍显示 已同步，这个插件在插件来源里标 未通过检查，它的详情在 概览 和 版本 里写明原因，点 查看要求 打开对应的说明；它继续加载当前生效的版本，其他插件照常更新。插件第一次同步的内容就没通过检查时，它没有可用的版本，不会加载，插件列表里显示 同步失败；修正后点 立即同步。

按下面的顺序检查，修复后点 立即同步：

1. Git 引用 里的分支、标签或提交在仓库里存在；仓库目录 存在，并且是一个目录。
2. 所选 Git 仓库的地址和凭证有效，见Git 仓库。自建的 Git 服务使用自签证书时，在 Git 仓库里配置证书，见自建服务证书。
3. 内网仓库能从同步用的网络到达，见同步网络。
4. 仓库目录里没有 Git 子模块或 LFS 文件，符号链接没有越界；每个 SKILL.md 都有 description，MCP 服务配置里没有凭证，见内容要求。
5. 插件和它所在的仓库都没有超过大小上限。

保持同步

• 手动同步：Git 有更新后，在插件详情或插件来源详情点 立即同步。同步排队或进行中时，这个按钮不可用。
• 自动同步：Z Tag 定期重新拉取，默认约每 15 分钟一次（Z Tag 管理员可以调整），失败后也按同样的间隔重试。也可以随时点 立即同步。

同步网络

同步时，如果仓库所属的连接器指定了网络隧道，就经过这条隧道；隧道不可用时同步失败，不会改走其他路线。连接器没有指定网络隧道时，使用 同步网络 所选沙箱配置的内网路由；留空（使用默认沙箱配置）时，使用所属一方的默认沙箱配置；默认沙箱配置已取消时没有内网路由可走，内网路由要求 为 必须经内网路由 的仓库同步失败，其余仓库照常同步。内网 Git 请确认其中一条能到达仓库，网络设置见沙箱配置与网络隧道。

同步用的仓库凭证和网络只用于同步，ZAI 使用这个插件时拿不到它们。

选择在哪里加载

• 在插件详情的 使用范围 标签里添加 Channel、Workspace 或整个组织；也可以在 范围设置 里选好范围后添加插件。
• 在插件详情 使用范围 标签下方的 添加到连接器 里选一个连接器，或在连接器详情点页头的 添加访问，从 插件 分组里添加，让访问能力和做法一起提供。加到连接器只决定插件在哪里加载，不影响同步用的凭证和网络。
• 在 范围设置 → 全体成员 → 资源 里添加这个插件，组织插件就进入每位成员的 个人范围，在他和 ZAI 的私信里加载，包括以后加入的成员，见授权给全体成员。
• 组织插件不能单独授权给某一位成员。它可以随授权给成员的连接器，进入这位成员的 个人范围。

同一个范围里有同名技能或插件标识相同的插件时只加载一个，规则见同名技能用哪一个。在 范围设置 里选中一个范围后，没有完整加载的插件在状态旁标 被遮蔽（整个插件没有加载）或 N 个技能被遮蔽，把指针移到标记上或用键盘聚焦它，可以看到由哪个插件提供。这里不显示插件技能替换 ZAI 自带技能的情况。

资源在各层怎样合并，见能力在哪里生效。

验证

控制台在详情页提示：启用、停用或换版后，进行中的 Session 从下一条消息起使用新内容；同一轮回复内不变。所以要验证更新或新启用的插件，等 ZAI 回复完正在进行的那一轮，在插件生效的聊天里发一条消息，让 ZAI 用这个插件做一个小任务，见技能与插件。

也可以问 ZAI “你现在加载了哪些插件？”，它会说出这个 Session 加载的插件、版本号和技能。

删除与依赖

• 插件来源选用的 Git 仓库、仓库所属的连接器，以及作为 同步网络 的沙箱配置都不能删除。删除它们时，控制台会列出占用它们的插件来源；点名称打开插件来源，改选其他 Git 仓库或同步网络，或删除插件来源。
• 在插件来源详情点 删除插件来源，会一并删除它同步出的全部插件和这些插件的使用范围。
• 删除一个整目录同步出的插件时，它的插件来源随之删除。插件市场清单里仍列着的插件不能单独删除，下一次同步会把它再建出来；先从清单里删掉它，或删除整个插件来源。
• 上传的插件可以直接删除，它的版本和使用范围一并删除。