Plugin 系统

Plugin 是一组 skill / 命令 / hook 的集合,通过 git 仓库分发。一行 /plugin install 就能把别人写好的工作流装到 AtomCode 里,装完即用。AtomCode 的 plugin 协议与 Claude Code 兼容,CC 生态的 plugin 仓库可以直接安装运行。

核心概念

Marketplace —— 一个 git 仓库,根目录有 .atomcode-plugin/marketplace.json 或 .claude-plugin/marketplace.json,声明它包含哪些 plugin。
Plugin —— marketplace 里的一个条目,可以是同仓库的子目录,也可以指向**外部 git 仓库**(url / github / git)或**本地路径**(local)。
Skill / 命令 / Hook —— plugin 安装后会贡献的三类资产。skill 与命令带 plugin-name: 命名空间(避免冲突),hook 按事件触发。

命令速查

命令	作用
`/plugin`	打开交互式插件管理器(上/下选择,回车确认,Esc 返回),可在里面浏览 marketplace、安装/卸载插件、添加/移除 marketplace
`/plugin marketplace add <url>`	克隆一个 git 仓库并注册为 marketplace
`/plugin marketplace remove <name>`	移除已注册的 marketplace(若其下还有已装插件会拒绝)
`/plugin marketplace update <name>`	拉取该 marketplace 仓库的最新提交,刷新可用插件列表
`/plugin marketplace list`	列出所有已注册的 marketplace
`/plugin install <plugin>@<marketplace>`	从指定 marketplace 安装一个插件
`/plugin uninstall <plugin>@<marketplace>`	卸载已安装的插件(保留 marketplace 注册)
`/plugin list`	列出本地已安装的所有插件
`/plugin reload`	重新加载所有插件(扫描磁盘变更、刷新 skill/hook 注册)

装一个 plugin

方式 1:交互式管理器(推荐)

在 TUI 中直接输入 /plugin(不带任何子命令),会打开一个全屏交互式管理器。通过方向键导航、回车确认:

/plugin
# → 打开管理器主菜单:
#   Browse & install    — 浏览 marketplace 中的插件,回车安装/卸载
#   Add marketplace…   — 输入 git URL 添加新 marketplace
#   Remove marketplace… — 选择并移除已注册的 marketplace
#   Installed (N)      — 查看已安装插件列表,回车卸载

安装插件时,已安装的会显示 ✓ 标记,回车即可切换安装/卸载。克隆和安装是异步的,操作期间底部会显示状态提示,完成后列表自动刷新。

方式 2:命令行子命令

# 1. 注册 marketplace(克隆其 git 仓库到本地)
/plugin marketplace add https://gitcode.com/gmq123/ascend-model-agent-plugin

# 2. 装其中的 plugin
/plugin install ascend-model-agent-plugin@ascend-model-agent-plugin

# 3. 列出已装
/plugin list

方式 3:CLI

atomcode plugin marketplace add <git-url>
atomcode plugin install <plugin>@<marketplace>
atomcode plugin list
atomcode plugin uninstall <plugin>@<marketplace>
atomcode plugin marketplace remove|update|list

CLI 与 TUI 共享 ~/.atomcode/plugins/ 目录,任意一边装的另一边立即可见。

装完之后

plugin 贡献的 skill 出现在 / 菜单,带 <plugin-name>: 前缀。例如 /ascend-model-agent-plugin:ascend-model-verification。
模型也能通过 UseSkill 工具自动调用这些 skill。
Hook 需信任后才激活 —— 安装时会打印该插件贡献的 hook 告知(但不运行),运行 atomcode plugin trust <name> 授权后,下次 session 启动时生效。详见Hook 信任流程。

目录布局

~/.atomcode/plugins/
├── marketplaces.json              # 注册的 marketplace 元数据
├── installed_plugins.json         # 已装 plugin 的状态记录
├── marketplaces/
│   └── <marketplace-name>/        # marketplace 仓库克隆
│       ├── .claude-plugin/marketplace.json
│       └── <plugin-subdir>/        # inline plugin
└── installed/
    └── <marketplace>/<plugin>/    # 外部 source 的 plugin 克隆

plugin.json 内嵌结构

每个 plugin 根目录(或 .claude-plugin/ / .atomcode-plugin/ 子目录)下的 plugin.json:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "干啥用的",
  "skills": ["./skills"],          // 也接受字符串 "skills"
  "commands": ["./commands"],
  "hooks": {                        // 也接受路径字符串 "hooks.json"
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "python \"${CLAUDE_PLUGIN_ROOT}/hook.py\"",
        "timeout": 5
      }]
    }]
  }
}

Hook 事件

plugin 可以挂以下事件(与 CC 一致)。事件名大小写/风格不敏感——loader 同时接受 PascalCase(PreToolUse、SessionStart)和 snake_case(pre_tool_use、session_start),两种拼写等价。

事件	触发时机	用途
`UserPromptSubmit`	用户消息提交后,LLM 调用前	注入额外上下文 / 路由 / 阻断
`PreToolUse`	工具调用前	校验、阻断、改参
`PostToolUse`	工具调用后	审计、副作用
`SessionStart`	session 启动	预热、记录
`SessionEnd`	session 结束	清理、归档
`Stop`	回合结束——正常停止、安全熔断、用户取消或限流暂停	通知插件回合已结束;触发后续动作
`StopFailure`	回合因 API/provider 错误(流失败/超时)而结束	通知插件回合失败;告警 / 记录
`Notification`	系统通知	转发外部告警通道

每个回合结束时都会触发 且仅触发一个 Stop/StopFailure——不会两个都触发,也不会都不触发。StopFailure 只保留给因为 API/provider 失败而结束的回合;回合中途的工具报错不会触发它(回合会继续,以真实的终态结束)。stdin payload 携带 hook_event_name、session_id、cwd、会话的 transcript_path(append-only JSONL 会话记录,非持久化运行为 null)、CC 风格的 stop_hook_active 标志(当另有一个终态 hook 配置并会同场触发时为 true——用它可以避免 Stop hook 递归地重新触发自己),以及 kernel 的 stop_reason(如 Stopped、ProviderError、Timeout、Cancelled),hook 无需再解析其他内容即可区分具体结果。

默认目录自动发现

plugin 的资产目录无需在 plugin.json 中逐一声明——loader 会按以下规则自动下钻:

Hooks — 优先读 hooks/hooks.json(CC 布局),其次回退到根目录的 hooks.json。
Skills — 自动扫描 skills/ 目录。
Commands — 自动扫描 commands/ 目录。

只有当路径不符合默认约定时(如自定义子目录名),才需要在 plugin.json 中显式声明 "skills"/"commands"/"hooks" 字段。

Hook 信任流程

为防止恶意插件静默执行任意命令,plugin hook 受信任门控保护:

安装时(/plugin install / atomcode plugin install)——打印 hook 内容告知,不立即运行 hook。
授权信任——用户确认后运行:
```
atomcode plugin trust <plugin-name>
```
AtomCode 记录当前 hook 命令集的哈希值。
下次 session 生效——受信任的 hook 在下次启动时加载并激活。
更新失效——插件更新后若 hook 命令有变动,哈希自动失效;需重新 trust 才能运行新版本 hook。

撤销信任:

atomcode plugin untrust <plugin-name>

UserPromptSubmit IO 协议

Hook 通过 stdin 拿到 JSON,通过 stdout 决定如何处理:

{
  "session_id": "...",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "用户输入的文本",
  "cwd": "/工作目录"
}

Hook 可以用以下方式响应(优先级由高到低):

退出码非零 —— 阻断 prompt,reason 取自 stderr。
stdout 输出 JSON {"decision": "block", "reason": "..."} —— 阻断,显式给原因。
stdout 输出 JSON {"hookSpecificOutput": {"additionalContext": "..."}} —— 把 additionalContext 追加到用户消息后,作为 LLM 的额外上下文。
stdout 输出纯文本 —— 整段作为 additionalContext 注入。
空 stdout / 不可解析 JSON —— 放行,prompt 原样进入 LLM。

AtomCode 解析 stdout 时,优先用最后一个非空行试 JSON;失败再回退到整段文本注入 —— 让 hook 脚本可以前置打印 debug 输出而不影响最终决策。

路径变量

Hook 命令字符串中可以引用以下环境变量(由 executor 注入):

${CLAUDE_PLUGIN_ROOT} —— plugin 安装目录绝对路径(CC 兼容)。
${ATOMCODE_PLUGIN_ROOT} —— 同上,atomcode 别名。

这些是真实环境变量由 shell 自身展开,不是字符串替换 —— 安装路径含空格、引号、$、; 都不会破命令。

Marketplace 管理

# 列出已注册的 marketplace
/plugin marketplace list

# 拉最新提交(更新该 marketplace 包含的 plugin 列表)
/plugin marketplace update <name>

# 移除(若该 marketplace 下还有 plugin 装着,会拒绝)
/plugin marketplace remove <name>

实战:装昇腾插件

/plugin marketplace add https://gitcode.com/gmq123/ascend-model-agent-plugin
# > cloning marketplace from https://gitcode.com/...
# > marketplace `ascend-model-agent-plugin` added at 7a59537 (1 plugins)

/plugin install ascend-model-agent-plugin@ascend-model-agent-plugin
# > installing `...`...
# > installed `ascend-model-agent-plugin@ascend-model-agent-plugin` — 23 skills loaded, 5 skipped

# 这个 plugin 装了一个 UserPromptSubmit hook(workflow_planner_hook.py),
# 当你说"帮我验证 Qwen3 在昇腾上的适配"时,它会注入一份 workflow JSON,
# 让模型按照 ascend-model-verification skill 链路执行。
帮我验证 Qwen3 在昇腾上的适配

已知限制

不支持的 CC 事件:PreCompact / SubagentStop 当前会被静默跳过。
多行 indent JSON 输出:hook 用 print(json.dumps(..., indent=2)) 输出多行 JSON 时,最后一行是 },我们的最后一行 JSON parser 会失败,回退到纯文本注入。功能上没问题(LLM 仍能读到内容),但不是结构化路径。建议 hook 作者用单行 json.dumps(...) 输出。
Skill 名校验严格:[a-z0-9_-],与 CC 一致。带 / 或大小写混合的 skill 名会被 skip。

下一步

Skills 扩展 —— 写自己的 skill,plugin 里也能用。
斜杠命令 —— 完整的 /plugin 命令列表。
MCP 集成 —— 接入外部工具的另一条路径,与 plugin 互补。