插件

cdg plugin 下的 install、status、update、uninstall 四个子命令用来安装、查看、更新和卸载 CodeDAG Guide 插件。插件能做什么、日常怎样管理，见管理 CodeDAG Guide 插件。

命令与目标 Agent

四个子命令用同一组选项指定处理哪个 Agent 的插件，不写时同时处理 Claude Code 和 Codex。

[目标] 的写法：

--all 不能与 --claude 或 --codex 同时使用，这样写时命令报错，不做任何操作。

目标 Agent 没有装在本机时，各命令的处理不同。写 --all 或省略目标时，install 与 update 跳过本机没装的 Agent，只处理装了的那个，两个都没装才报错；用 --claude 或 --codex 明确指定了本机没装的 Agent 时，这两个命令直接报错。status 总是列出指定的每个 Agent，没装的那个会提示先安装它。uninstall 不要求 Agent 仍在本机：即使 Agent 已经卸载，只要还留有插件配置，命令照样清理，只跳过需要由 Agent 自己完成的那部分卸载步骤。

这几个命令都不需要登录，也不要求当前目录是用 cdg init 初始化过的项目。安装和更新只对之后新开的 Agent 会话生效，已经开着的会话要先退出，再用 claude --resume 或 codex resume 恢复，才能用上新的插件。

cdg plugin install

cdg plugin install 为目标 Agent 安装插件，安装范围由 -s / --scope 决定，默认是 user。

# 为本机装有的所有 Agent 安装，User 范围
cdg plugin install
# 只为 Codex 安装，只在当前 checkout 中生效
cdg plugin install --codex -s local

三种范围的区别在于配置写在哪里、是否随仓库共享：

project 与 local 装在运行命令时所在的那个 checkout 里。命令会从当前目录向上找到仓库的根目录，所以在仓库的任意子目录中运行都可以；不在 Git 仓库中运行时，命令报错。user 范围在任何目录都能安装。

Project 范围写进仓库的文件受版本管理，在默认的隔离分支模式下要提交之后工作区才算干净；Local 范围写进仓库的文件由下面的忽略规则挡住，不会影响工作区。装完之后怎样处理这些文件，以及 Project 范围怎样在其他成员的电脑上生效，见选择安装范围。

已经装过插件时，install 不会重装，也不会改变范围。只要在当前位置能看到这个 Agent 的插件，不论它装在哪个范围，命令都只提示已经安装，然后跳过；例如装过 User 范围之后，在任何仓库里再运行 cdg plugin install --scope project 都不会生效。要换范围，见更换安装范围。命令发现上一次安装留下了没有清理干净的配置时同样会跳过，这时先运行 cdg plugin uninstall，再重新安装。

Local 范围写入的忽略规则

Local 范围安装成功时，CodeDAG 会在仓库的 info/exclude 里写一段受管 block，让 Git 忽略这些只留在本机的配置文件。你不需要自己配忽略规则，CodeDAG 也不会改动受版本管理的 .gitignore。每个插件各有一段 block，重复安装或修复安装时整段替换，block 之外的规则保持原样：

# BEGIN CODEDAG CLAUDE GUIDE (managed)
.claude/settings.local.json
# END CODEDAG CLAUDE GUIDE (managed)

# BEGIN CODEDAG CODEX GUIDE (managed)
.agents/plugins/marketplace.json
plugins/codedag/
# END CODEDAG CODEX GUIDE (managed)

block 写在 Git 实际读取的那一份 info/exclude 里：普通仓库是 <仓库根>/.git/info/exclude，linked worktree 用的是仓库共用 Git 目录下的 info/exclude，同一仓库的所有工作目录共用这一份。两家插件的 Local 范围因此都可以在 linked worktree 里安装。

忽略规则对已经被 Git 跟踪的文件不起作用，所以这些文件已经提交进仓库时，Local 范围安装以退出码 1 失败，既不改动文件也不写 block，报错前缀为 Failed to install CodeDAG plugin for <Agent>:：

• Claude Code： .claude/settings.local.json 已被跟踪时，原因是 Claude Code local installation is unavailable because .claude/settings.local.json is already tracked by Git. Use user or project scope instead.
• Codex： .agents/plugins/marketplace.json 或 plugins/codedag 已被跟踪时，原因是 Codex local installation is unavailable because .agents/plugins/marketplace.json or plugins/codedag is already tracked by Git. Use project scope instead.

cdg plugin status

cdg plugin status 只读取、不做任何修改，报告的是在当前位置能看到的安装。它为每个目标 Agent 输出一组字段：

运行的位置决定它检查哪些安装。在 Git 仓库中运行时，它检查这个 checkout 中 Project 与 Local 范围的安装，以及 User 范围的安装；在 Git 仓库之外运行时，只检查 User 范围的安装。所以要确认某个仓库里的 Agent 会话能否用上插件，就在那个仓库里运行。

插件在 Agent 里被停用时，Action 追加重新启用的办法。它和同步建议可以同时出现，同步建议在前：

  Enabled: false
  Sync: version record out of date
  Action: Run `cdg plugin update --codex`. Plugin is disabled. Open `/plugins` in a Codex session to re-enable it

重新启用只能在 Agent 自己那边完成：Claude Code 运行 claude plugin enable codedag@codedag，Codex 在会话里打开 /plugins。cdg plugin update 和修复安装都保留你的停用选择，不会替你打开。

版本兼容

插件与 CLI 各自升级，版本号不必相同；两者是否匹配，以插件声明的两个 CLI 版本为准：它支持的最低版本，以及它已经验证过的最新版本。cdg plugin status 把本机 CLI 的版本与已安装插件声明的这两个版本相比：

CLI 高于已验证版本不算不兼容，是因为新版 CLI 会保留已发布插件用到的命令、参数和含义。反过来，最新版的插件覆盖 CodeDAG 服务仍然支持的所有 CLI 版本，所以只要你的 CLI 仍受服务支持，更新到最新的插件就不会与它不兼容。

cdg plugin update

cdg plugin update 在插件原来的范围内把它更新到最新版本，默认保留你对插件技能文件的修改。更新同时保留你在 Agent 里对插件的启用或停用选择；安装损坏时，同一条命令会就地修复。目标 Agent 还没有装插件时，命令只提示安装命令，不会替你安装。这个命令没有 --scope 选项，换范围见更换安装范围。

# 更新本机两个 Agent 的插件
cdg plugin update
# 只更新 Codex 的插件，放弃对技能文件的修改
cdg plugin update --codex --reset-local-changes

更新需要替换插件内容时，命令会先把原来的插件副本备份一份，并在完成提示的 Previous copy backed up in directory: 一行给出备份所在的目录。备份都放在 CodeDAG 的全局目录里，不在仓库内，所以 Project 范围的插件更新之后 git status 仍然是干净的。Codex 插件的备份按安装范围分开存放：

<checkout-key> 由 checkout 根目录的路径生成，所以同一仓库的不同工作目录各有自己的备份目录。每个目录只保留最近的一份备份，下一次替换时会被覆盖，其中还想要的修改要及时移走。想长期保留的编排要求适合写进 CLAUDE.md 或 AGENTS.md，原因见更新插件。

cdg plugin uninstall

cdg plugin uninstall 没有 --scope 选项，卸载哪些安装由运行命令的位置决定；在 Git 仓库中运行时，User 范围的安装也会一并删除。

命令不能只卸载其中一个范围。在仓库里卸载之后，这台电脑上其他仓库的会话也用不上插件了；只想删除 User 范围的安装时，到 Git 仓库之外的目录运行。其他仓库或副本中的 Project 与 Local 配置不会被删除，要到对应的 checkout 里分别卸载。

从 Project 范围卸载会改动当前 checkout 中受版本管理的配置文件，这次改动同样需要提交。卸载 Local 范围的安装时，info/exclude 里那段受管 block 一并移除；同一仓库的其他工作目录还在用这段 block 时保留它，免得那边的文件变成未跟踪文件。加 --claude 或 --codex 时只卸载这一个 Agent 的插件，另一个 Agent 的插件与它的 block 都不受影响。

更换安装范围

已安装的插件不能直接改范围，要先卸载，再用新的 --scope 安装，最后开一个新的 Agent 会话。

两条命令都要在正确的位置运行。卸载要在能看到旧安装的地方进行：旧范围是 Project 或 Local 时，就是装有它的那个 checkout。新范围是 Project 或 Local 时，安装也要在目标 checkout 里运行。只换一个 Agent 时，两条命令都加上 --claude 或 --codex，另一个 Agent 的插件保持原样。

下面把 Claude Code 的插件从 User 范围换到仓库 ~/code/my-app 的 Project 范围：

cd ~/code/my-app
cdg plugin uninstall --claude
cdg plugin install --claude --scope project

因为卸载是在仓库中运行的，原来 User 范围的安装已经删除，这台电脑上的其他仓库不再有这个插件，需要时在那里另行安装。新写入的配置文件要提交到项目仓库，团队成员才能共享。

反过来，从 Project 范围换回 User 范围时，同样先在这个仓库里卸载，再用 --scope user 安装；这次卸载删除了仓库中的项目配置，这个改动同样要提交到项目仓库。

相关

• 管理 CodeDAG Guide 插件：安装范围怎么选、怎样确认插件已经生效，以及定制编排习惯时怎样不改动插件的技能文件。
• 让 Agent 帮你编排：装好插件之后，把目标交给 Agent，由它写工作流并提交。