仓库 →

Plugin 系统

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

核心概念

命令速查

命令作用
/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/ 目录,任意一边装的另一边立即可见。

装完之后

目录布局

~/.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 一致):

事件触发时机用途
UserPromptSubmit用户消息提交后,LLM 调用前注入额外上下文 / 路由 / 阻断
PreToolUse工具调用前校验、阻断、改参
PostToolUse工具调用后审计、副作用
SessionStartsession 启动预热、记录
SessionEndsession 结束清理、归档
Notification系统通知转发外部告警通道

UserPromptSubmit IO 协议

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

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

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

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

路径变量

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

这些是真实环境变量由 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 在昇腾上的适配

已知限制

下一步