Plugin

Hawa Code 支持通过插件（Plugin）和插件市场（Marketplace）扩展能力。插件以声明式目录分发，可包含 Skill、斜杠命令、Agent、Hooks、MCP Server、LSP Server 等组件；市场则是一个插件目录，方便集中管理和分发多个插件。

Claude Code 兼容：默认开启 settings.plugins.pluginClaudeCompat，Hawa Code 会同时识别 .hcode-plugin/ 和 .claude-plugin/ 目录，优先使用 .hcode-plugin/。因此可以直接复用大量 Claude Code 生态插件。

快速开始

1. 添加市场

# 本地目录
hcode plugin marketplace add ./my-marketplace

# GitHub 仓库简写
hcode plugin marketplace add owner/repo

# git URL
hcode plugin marketplace add https://github.com/owner/repo.git

# 直接指向 marketplace.json 的 URL
hcode plugin marketplace add https://example.com/marketplace.json

2. 安装插件

hcode plugin install demo-plugin@my-marketplace

3. 使用插件

安装并启用后，插件中的 Skill 和命令会自动注册：

Skill：在对话中通过 /插件名:Skill名 或 /Skill名 调用。
自定义命令：通过 /命令名 调用。
MCP Server：重启或刷新后通过 hcode mcp list 查看。

市场管理

市场是插件的集合，由一个 marketplace.json 文件描述。Hawa Code 支持通过 CLI 和交互式斜杠命令管理市场。

添加市场

hcode plugin marketplace add <source>

<source> 支持以下形式：

来源	示例
本地目录	`./my-marketplace`
GitHub 简写	`owner/repo`
git URL	`https://github.com/owner/repo.git` 或 `git@github.com:owner/repo.git`
marketplace.json URL	`https://example.com/marketplace.json`

移除市场

hcode plugin marketplace remove <name>

列出市场

hcode plugin marketplace list
hcode plugin marketplace list --json

更新市场

从来源重新拉取市场内容：

# 更新全部市场
hcode plugin marketplace update

# 更新指定市场
hcode plugin marketplace update my-marketplace

插件管理

安装插件

hcode plugin install <plugin[@marketplace]>

plugin：插件名称。
marketplace：可选，市场名称。省略时会在所有已知市场中查找；如果只有一个市场包含该插件，则自动使用该市场。

卸载插件

hcode plugin uninstall <plugin[@marketplace]>

可以指定完整 ID，也可以使用 plugin@marketplace 简写。

更新插件

# 更新全部插件
hcode plugin update

# 更新指定插件
hcode plugin update demo-plugin@my-marketplace

列出已安装插件

hcode plugin list
hcode plugin list --json

启用/禁用插件

hcode plugin enable <plugin[@marketplace]>
hcode plugin disable <plugin[@marketplace]>

禁用后插件的 Skill、命令、MCP 等组件不再生效，但文件仍保留在本地缓存中。

交互式管理器

在 Hawa Code 交互界面中输入：

/plugin

即可打开插件管理器，支持键盘操作：

← / →：切换标签页（Available / Installed / Marketplaces）。
↑ / ↓：选择列表项。
Enter：进入详情或执行安装/卸载/更新。
Esc：退出。

marketplace.json

市场的描述文件，默认位于市场根目录的 .hcode-plugin/marketplace.json；兼容模式下也支持 .claude-plugin/marketplace.json。

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "description": "我的 Hawa Code 插件市场",
  "plugins": [
    {
      "name": "quality-review-plugin",
      "source": "./plugins/quality-review-plugin",
      "description": "Adds a quality-review skill",
      "version": "1.0.0"
    }
  ]
}

插件来源（source）

plugins[].source 支持多种形式：

类型	示例
本地相对路径	`"./plugins/formatter"`
GitHub	`{ "source": "github", "repo": "owner/repo", "ref": "main", "sha": "..." }`
URL	`{ "source": "url", "url": "https://...", "ref": "..." }`
Git 子目录	`{ "source": "git-subdir", "url": "https://...", "path": "plugins/foo", "ref": "main" }`
npm	`{ "source": "npm", "package": "@org/pkg", "version": "1.0.0" }`

相对路径的解析基准是市场根目录（包含 .hcode-plugin/ 的目录），而不是 .hcode-plugin/ 本身。

plugin.json

单个插件的描述文件，位于插件根目录的 .hcode-plugin/plugin.json；兼容模式下也支持 .claude-plugin/plugin.json。

{
  "name": "quality-review-plugin",
  "version": "1.0.0",
  "description": "Adds a quality-review skill for quick code reviews",
  "author": { "name": "Your Name", "email": "you@example.com" },
  "homepage": "https://...",
  "repository": "https://...",
  "license": "MIT",
  "keywords": ["review", "quality"],
  "category": "productivity",
  "skills": "skills",
  "commands": "commands",
  "agents": "agents",
  "hooks": "hooks",
  "mcpServers": "mcp",
  "lspServers": "lsp",
  "permissions": ["read", "write"],
  "strict": true,
  "defaultEnabled": true
}

字段说明

字段	说明
`name`	插件唯一名称
`version`	版本号
`description`	描述
`author`	作者信息
`homepage` / `repository` / `license`	项目元数据
`keywords` / `category`	分类与标签
`skills`	Skill 目录路径，默认 `skills`
`commands`	自定义命令目录路径，默认 `commands`
`agents`	Agent 目录路径，默认 `agents`
`hooks`	Hooks 配置目录或内联对象
`mcpServers`	MCP Server 配置目录或内联对象
`lspServers`	LSP Server 配置目录或内联对象
`permissions`	插件所需权限列表
`strict`	`true` 时 `plugin.json` 优先；`false` 时市场条目完全覆盖
`defaultEnabled`	安装后是否默认启用，默认 `true`

strict 模式

strict: true（默认）：plugin.json 是组件定义的权威，市场条目仅补充信息。
strict: false：市场条目是完整定义，此时 plugin.json 不能再声明组件（skills、commands 等），否则安装会失败。

插件组件

插件可以包含以下扩展组件：

Skill

插件 skills 目录下的每个子目录（包含 SKILL.md）都会注册为一个 Skill。安装后可直接在对话中调用。详见 Skill 文档。

自定义命令

插件 commands 目录下的 .md 文件会注册为斜杠命令。命令名默认按 插件名:命令名 命名空间化。

Agent

插件 agents 目录下的定义会加入 Agent 扫描路径。

Hooks

hooks 字段可以是目录路径（该目录下需包含 hooks.json），也可以是内联的 HooksConfig 对象。支持 SessionStart 和 SessionEnd 钩子。

MCP Server

mcpServers 字段可以是目录路径（包含 JSON 配置文件），也可以是内联对象。插件注册的 MCP Server 名称会自动加上前缀：

plugin__<marketplace>__<plugin>__<server>

LSP Server

lspServers 字段用法与 MCP 类似，用于注册 LSP Server。

变量替换

MCP 和 Hook 配置中的字符串支持以下变量替换：

变量	替换为
`${HCODE_PLUGIN_ROOT}`	插件缓存目录
`${HCODE_PLUGIN_DATA}`	插件数据目录
`${CLAUDE_PLUGIN_ROOT}`	同 `${HCODE_PLUGIN_ROOT}`
`${CLAUDE_PLUGIN_DATA}`	同 `${HCODE_PLUGIN_DATA}`

配置

在 ~/.hcode/settings.json 或项目 .hcode/settings.json 中配置插件行为：

{
  "plugins": {
    "enabledPlugins": ["my-marketplace__demo-plugin@1.0.0"],
    "disabledPlugins": [],
    "pluginConfigs": {},
    "extraKnownMarketplaces": [
      { "name": "company", "source": "https://github.com/company/hawa-plugins" }
    ],
    "strictKnownMarketplaces": false,
    "pluginMarketplaceAllowlist": [],
    "pluginAutoUpdate": false,
    "pluginAutoUpdateInterval": 60,
    "pluginSandboxHooks": true,
    "pluginClaudeCompat": true
  }
}

配置项说明

配置项	说明
`enabledPlugins`	强制启用的插件 ID 列表
`disabledPlugins`	强制禁用的插件 ID 列表
`pluginConfigs`	每个插件的独立配置对象
`extraKnownMarketplaces`	额外预置的市场列表
`strictKnownMarketplaces`	`true` 时只接受已知市场；`false` 允许添加新市场
`pluginMarketplaceAllowlist`	市场来源 allowlist，支持 glob/regex
`pluginAutoUpdate`	是否开启后台自动更新市场与插件
`pluginAutoUpdateInterval`	自动更新间隔分钟数，默认 60
`pluginSandboxHooks`	是否在沙箱中执行 Hook 与 MCP 命令，默认 `true`
`pluginClaudeCompat`	是否兼容 `.claude-plugin/` 目录，默认 `true`

安全与权限

安装确认

安装插件前，Hawa Code 会展示来源、版本、所需权限和沙箱状态，需要用户确认。CLI 可通过 --yes 跳过确认（当前实现中部分路径已默认信任已知市场）。

Allowlist

通过 pluginMarketplaceAllowlist 可限制允许添加的市场来源，支持 glob 和正则表达式。

路径隔离

每个插件复制到独立的缓存目录，禁止 ../ 引用和越界 symlink。${HCODE_PLUGIN_ROOT} 和 ${HCODE_PLUGIN_DATA} 作为安全的变量替换入口。

沙箱执行

pluginSandboxHooks 默认开启，Hook 与 MCP 命令通过 Hawa Code 的沙箱机制执行，受 settings.sandbox 限制。

缓存目录

插件相关数据默认存放在 ~/.hcode/plugins/：

~/.hcode/plugins/
├── known_marketplaces.json
├── installed_plugins.json
├── marketplaces/<name>/          # 市场克隆/下载目录
├── installed/<marketplace>__<plugin>@<version>/  # 插件缓存
└── data/<marketplace>__<plugin>/                  # 插件持久数据

环境变量

环境变量	说明
`HCODE_PLUGIN_CACHE_DIR`	覆盖整个插件缓存根目录
`HCODE_PLUGIN_ROOT`	指向已安装插件目录
`HCODE_PLUGIN_DATA`	指向插件数据目录
`HCODE_PLUGIN_SEED_DIR`	预置插件目录，用于容器/CI
`HCODE_PLUGIN_GIT_TIMEOUT_MS`	git 操作超时，默认 120000ms
`HCODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE`	更新失败时保留旧缓存

命令速查

斜杠命令

/plugin marketplace add <source>
/plugin marketplace remove <name>
/plugin marketplace list
/plugin marketplace update [name]
/plugin install <plugin[@marketplace]>
/plugin uninstall <plugin[@marketplace]>
/plugin update [plugin[@marketplace]]
/plugin list
/plugin enable <plugin[@marketplace]>
/plugin disable <plugin[@marketplace]>

CLI

hcode plugin marketplace add <source>
hcode plugin marketplace remove <name>
hcode plugin marketplace list [--json]
hcode plugin marketplace update [name]
hcode plugin install <plugin[@marketplace]>
hcode plugin uninstall <plugin[@marketplace]>
hcode plugin update [plugin[@marketplace]]
hcode plugin list [--json]

手动验证示例

创建一个本地市场：

mkdir -p my-marketplace/.hcode-plugin
mkdir -p my-marketplace/plugins/demo-plugin/.hcode-plugin
mkdir -p my-marketplace/plugins/demo-plugin/skills/demo

写入 my-marketplace/.hcode-plugin/marketplace.json：

{
  "name": "my-marketplace",
  "owner": { "name": "Demo" },
  "plugins": [
    {
      "name": "demo-plugin",
      "source": "./plugins/demo-plugin",
      "version": "1.0.0"
    }
  ]
}

写入 my-marketplace/plugins/demo-plugin/.hcode-plugin/plugin.json：

{
  "name": "demo-plugin",
  "version": "1.0.0",
  "description": "A demo plugin"
}

写入 my-marketplace/plugins/demo-plugin/skills/demo/SKILL.md：

---
name: Demo
description: Say hello from plugin
---
Hello from plugin!

添加并安装：

hcode plugin marketplace add ./my-marketplace
hcode plugin install demo-plugin@my-marketplace

安装完成后，在 Hawa Code 中执行 /demo-plugin:Demo 即可看到效果。