diagnosing-plugins
Use to diagnose and fix ZCode plugin and marketplace problems in the ZCode client. Applies when a plugin is not listed, adding a marketplace or installing a plugin fails, a plugin is enabled but its skills or commands are missing, a built-in plugin still appears after being disabled, a plugin is not enabled as expected, a plugin.json manifest has a parse error, a plugin name is invalid, a dependency is unresolved or blocked across marketplaces, or a sensitive configuration value cannot be entered in the interface. Provides the plugin lifecycle, manifest schema, how to manage plugins in the client, and a step-by-step localization and repair workflow.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 253
- Forks
- 20
01 前言 Front Matter
- name
- diagnosing-plugins
- description
- Use to diagnose and fix ZCode plugin and marketplace problems in the ZCode client. Applies when a plugin is not listed, adding a marketplace or installing a plugin fails, a plugin is enabled but its skills or commands are missing, a built-in plugin still appears after being disabled, a plugin is not enabled as expected, a plugin.json manifest has a parse error, a plugin name is invalid, a dependency is unresolved or blocked across marketplaces, or a sensitive configuration value cannot be entered in the interface. Provides the plugin lifecycle, manifest schema, how to manage plugins in the client, and a step-by-step localization and repair workflow.
03 SKILL.md 正文
Diagnosing Plugin Configuration
Goal: reduce any plugin problem to a single concrete fix.
Plugins are managed in Settings → Plugin Management — the Installed tab (enable/disable, view details, configure, uninstall) and the Discover tab (browse, install, and add marketplaces via the + button).
Key facts: enable/disable state is stored under
pluginsin~/.zcode/cli/config.json; the official marketplace iszcode-plugins-official; and for cloning marketplace repositories behind a proxy, ZCode reads the proxy fromZCODE_HTTP_PROXY(a barehttp_proxyis not used).
1. Plugin lifecycle and persistence
- Discovery sources (first match wins): inline directories, bundled official plugins, the official plugin cache, and marketplace-installed plugins. The entire subsystem is governed by the
plugins.enabledmaster switch. - Manifest location (probed in order):
.zcode-plugin/plugin.json(preferred), then.claude-plugin/plugin.json, then.codex-plugin/plugin.json. A plugin's identity is<name>@<marketplace>. - Enable/disable resolution: an explicit enable/disable entry always wins; only when no entry exists does the plugin's default-enabled status apply. A disabled plugin still appears in the list as disabled, but its components resolve to nothing.
- Persistence (all under
pluginsin~/.zcode/cli/config.json): the enable/disable map, per-plugin configuration values, and the list of suppressed (uninstalled) built-in plugins. Because a built-in plugin ships with the application and cannot be deleted, "uninstalling" one records a suppression marker that hides it from discovery. - Built-in seeding: on first launch, bundled official plugins are materialized into the plugin cache and registered in the official marketplace listing. This is idempotent and only re-materializes on a content or version change.
2. Manifest schema
- plugin.json: requires
name(matching^[a-z0-9][a-z0-9._-]{0,127}$); optionalversion(defaults to0.0.0),description,commands/skills/hooks/mcpServers, anduserConfig. - Recorded but not executed:
agents,channels,lspServers,outputStyles,settings. - Component paths are validated: an absolute path or one that escapes the plugin root is rejected as an invalid component path.
- userConfig:
typeis one ofstring,number,boolean,directory, orfile, withtitle,description,default,required, andsensitive. A sensitive value cannot currently be entered in the interface or persisted to the configuration file. - marketplace.json:
{ name, plugins[], pluginRoot?, allowCrossMarketplaceDependenciesOn? }. Eachplugins[].sourcemay be a relative path string or an object of kinddirectory,github,git,url, orgit-subdir;npmandpipare not supported.
3. Managing plugins in the client
- Install: on the Discover tab, find the plugin card and click Get; when done it shows Installed. New plugins are enabled by default.
- Enable / disable: on the Installed tab, toggle the switch on the plugin's row. Disabling removes all of its components from the session immediately.
- Configure: open the plugin's detail view and expand Advanced to fill in its configuration values (required fields are marked; sensitive fields cannot be entered here).
- Uninstall: from the detail view; a built-in plugin can only be disabled, not uninstalled.
- Add a marketplace: the
+button on the Discover tab accepts a GitHub repository, a Git URL, a local directory, or a file.
4. Common pitfalls (symptom → cause → fix)
- A plugin is not listed at all — its marketplace was never added, so there is no installation record or cache; or
plugins.enabledis false. → Add the marketplace on the Discover tab and install it, or setplugins.enabled: true. - Adding a marketplace or installing fails to clone — an error such as
RPC failed,timed out, orearly EOF(after retries). The clone process did not inherit the shell proxy. → SetZCODE_HTTP_PROXY=http://host:port(ZCode reads the proxy only from this variable; a barehttp_proxyis ignored). - Enabled but its skills or commands are missing — a component path escapes the plugin root, the plugin is actually disabled, or it is not being treated as enabled where the session reads it. → Open the plugin's detail view to see the invalid component, and make the manifest path relative and inside the plugin root.
- A built-in plugin still appears after being disabled, or returns after uninstalling — the suppression state was not applied where it was read. → Confirm the plugin id is in the suppressed-built-ins list in
~/.zcode/cli/config.json; restoring it removes that entry and re-seeds. - Not enabled as expected — listed as enabled but a skill reports "not found" in the session — the default-enabled set was not applied along the session's discovery path even though the listing shows it enabled. → Verify the plugin's skills are actually available in the session (via Settings → Skills and the
/menu), not only that the plugin shows as enabled. - Manifest parse error — the JSON is invalid, is not an object, or has a missing/invalid
name. → Fix it into a valid object whosenamematches the pattern. - Invalid plugin name — the name violates
^[a-z0-9][a-z0-9._-]{0,127}$. → Rename. - Unresolved or cross-marketplace dependency — a dependency lives in another marketplace not listed in
allowCrossMarketplaceDependenciesOn, is missing, or forms a cycle. → Add the target marketplace toallowCrossMarketplaceDependenciesOn, install the missing dependency's marketplace, or break the cycle. Dependencies are written asname@marketplace. - Version shows 0.0.0 or updates are not detected — Git/URL plugins often lack a top-level version, and official plugins track updates by commit. → Confirm the installed record and the manifest entry both carry their source revision.
- A sensitive configuration value cannot be set — the field is disabled with a note that it requires secure storage. There is no secure credential store yet. → Remove
sensitive: true, or provide the value out of band (for example via an environment variable); it cannot be persisted today. - A
filesystem/seasource reports "unsupported" — a built-in plugin's cache path is missing or stale. → Re-seed the plugin (clearing its cache entry so it is re-materialized on the next launch).
5. Localization workflow (in order)
- Is the subsystem on? Check
plugins.enabled(false means everything is empty). - Look at the plugin. On the Installed tab, confirm whether the plugin is present and enabled; open its detail view for its source, components, and any warnings.
- Classify by presence. Entirely absent → a marketplace or installation problem (confirm the marketplace was added and the plugin installed). Present but disabled → check the enable state against the default. Present and enabled but broken at runtime → a component-path problem (pitfall 3) or a session-versus-listing divergence (pitfall 5).
- Built-in issues. Compare the suppressed-built-ins list against what the official marketplace offers, and confirm the plugin cache is current.
- Installation and network. Reproduce the clone with the proxy set, confirming
ZCODE_HTTP_PROXY, and look for the retryable-error signatures. - Session-versus-listing divergence. If the plugin shows enabled but its capabilities are absent in the session, treat it as a discovery-path problem: confirm the plugin's skills and commands actually appear in the session (Settings → Skills, the
/menu), not merely that the plugin is enabled.
04 同仓库更多 Skills
plugin-mcp-ping
E2E workspace Plugin skill marker
zcode-configuration-guide
Use when configuring ZCode's extension resources (MCP servers, slash commands, skills, hooks, and plugins) or instruction files such as AGENTS.md in the ZCode client. Explains where each resource is configured at the user and workspace scope, the discovery order, precedence, and merge rules, plus guidance on which location to choose. Use when someone asks how to add an MCP server, command, skill, hook, plugin, or AGENTS.md instructions, where a configuration file lives, why a configuration is not taking effect, or needs routing to a specific diagnostic skill.
diagnosing-skills
Use to diagnose and fix ZCode skill configuration problems in the ZCode client. Applies when a skill is not discovered, is installed but does not trigger automatically, is shadowed by a higher-precedence skill of the same name, is disabled by configuration, has a SKILL.md frontmatter error, fails to load because its description is too long, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect skills in the client, common pitfalls, and a step-by-step localization and repair workflow.
diagnosing-mcp
Use to diagnose and fix ZCode MCP (Model Context Protocol) server configuration problems in the ZCode client. Applies when an MCP server will not connect, its tools (mcp__server__tool) do not appear, it shows as disabled or failed, connections time out, a command cannot be found, template variables are not expanded, or a server defined in a configuration file has no effect. Provides configuration locations, how to inspect status in Settings, common pitfalls, and a step-by-step localization and repair workflow.
diagnosing-hooks
Use to diagnose and fix ZCode hook configuration problems in the ZCode client. Applies when a hook does not trigger, an event name is wrong, a matcher does not match a tool name, a script is not executable, template variables are not expanded, a timeout unit is mistaken (seconds versus milliseconds), the command and process field styles are mixed, a hook's JSON output fails validation, a hook blocks the session unexpectedly, or configuration-file hooks are not enabled. Provides configuration sources, the hooks.json schema, how to inspect hooks in the client, and a step-by-step localization and repair workflow.
diagnosing-commands
Use to diagnose and fix ZCode custom slash-command (/command) configuration problems in the ZCode client. Applies when a command is missing, is overridden by a higher-precedence command of the same name, has a frontmatter parse error, is dropped for having an empty body, has an invalid name, does not substitute $ARGUMENTS/$1, uses a colon rather than a slash for nested names, has a misspelled frontmatter key, or disappears because the plugin providing it is disabled. Provides the discovery order, how to inspect commands in the client, common pitfalls, and a step-by-step localization and repair workflow.