OpenCode 运行时、配置、Plugin、Agent 与 Skill

本文整理当前 OpenCode 环境的实际组成、配置覆盖关系、Agent/Skill/Plugin/MCP 的边界，以及后续优化建议。

注意：版本、模型、Plugin 和 MCP 状态可能变化。排障时应以 opencode debug config、opencode debug info、opencode agent list、opencode debug skill 和 opencode mcp list 的实时输出为准。

一、当前运行环境

OpenCode

text

版本：1.17.18
全局配置：C:\Users\GhostCloud\.config\opencode\opencode.json
项目配置：<项目根目录>\opencode.jsonc

配置关系：

项目配置优先于全局配置。
对象通常深度合并，而不是简单整份覆盖。
数组字段需要单独验证；当前 Plugin 数组表现为全局和项目两边都加载。
配置中的 model 是默认值，不保证等于某次会话最终使用的模型。

当前项目默认值

项目配置声明：

text

默认 Agent：stage-5-release-orchestrator
默认模型：ghostcloud-glm/GLM-5.2

但观察到的本次会话实际模型是：

text

ghostcloud-gpt/gpt-5.6-sol

这说明最终运行模型可能被以下环节覆盖：

启动参数或启动器；
恢复的历史会话；
Plugin 的模型路由；
上层运行环境；
会话内模型切换。

因此应区分：

text

配置默认模型 ≠ 当前会话实际模型

查看最终合并配置：

bash

opencode debug config

查看当前运行环境与 Plugin：

bash

opencode debug info

二、当前 Plugin

当前实际加载：

Plugin	来源
`oh-my-openagent`	全局配置 `C:\Users\GhostCloud\.config\opencode\opencode.json`
`oh-my-opencode`	项目配置 `opencode.jsonc`

Plugin 可以在运行时注入或改变：

Agent；
Skill；
MCP；
工具；
权限；
模型路由；
System Prompt；
消息和生命周期钩子。

因此当前可见能力远多于项目 .opencode/agent/ 中的 5 个 Agent。

项目业务目录不等于原生 Plugin

项目中的：

text

plugins/stage-5-release/plugin.json
plugins/stage-5-release/README.md

只是项目业务描述目录，不会因为目录名为 plugins 就被 OpenCode 自动加载。

OpenCode 本地原生 Plugin 应放在：

text

.opencode/plugin/*.ts
.opencode/plugins/*.ts

或者明确写进 opencode.jsonc 的 plugin 数组。

双重增强 Plugin 的风险

同时加载 oh-my-openagent 和 oh-my-opencode 可能造成：

Agent 数量膨胀；
同类 Skill 重复；
权限规则多层叠加；
MCP 重复或来源不透明；
模型路由不容易理解；
System Prompt 变长；
排障困难。

建议只保留一个主要增强框架。对比排障时使用：

bash

opencode --pure

--pure 不加载外部 Plugin，可判断问题来自 OpenCode 本体还是 Plugin。

三、Agent

项目自定义 Agent

项目 .opencode/agent/ 中定义了 5 个 Agent：

Agent	类型/用途
`_skill-integration-sop`	Subagent，Skill 集成流程
`stage-5-release-orchestrator`	当前项目默认主 Agent，发布编排
`stage-5-release-code-review`	Subagent，代码审查
`stage-5-release-deploy`	Subagent，部署
`stage-5-release-cicd`	Subagent，CI/CD

默认主 Agent 的声明位于：

text

.opencode/agent/stage-5-release-orchestrator.md

其他 Agent 来源

当前运行时还可能出现三类 Agent：

OpenCode 内置：build、plan、general、explore。
OpenCode 内部隐藏：title、summary、compaction。
Plugin 注入：oracle、librarian、Sisyphus-Junior、Metis、Momus、multimodal-looker 等。

因此：

text

项目目录中的 Agent 数量 ≠ 当前运行时可用 Agent 数量

查看真实 Agent 列表：

bash

opencode agent list

查看某个 Agent 合并后的最终配置：

bash

opencode debug agent stage-5-release-orchestrator
opencode debug agent stage-5-release-deploy

默认 Agent 过度专业化

当前默认 Agent 是发布编排员：

json

{
  "default_agent": "stage-5-release-orchestrator"
}

它适合发布流程，但不适合普通配置、文档、开发和调研任务，因为其职责强调编排而非直接执行环节工作。

建议：

如果仓库只用于发布演示，保留现状；
如果仓库还承担日常维护，默认改为通用主 Agent；
发布时显式调用 @stage-5-release-orchestrator。

发布 Agent 权限

stage-5-release-deploy 当前允许较宽泛的：

text

kubectl *
docker *
helm *
curl *

生产环境建议采用分层权限：

操作	建议权限
查询、状态、日志	allow
创建、更新、部署	ask
删除、强制覆盖、集群级变更	deny 或强制人工批准

不要只依靠 Prompt 中“必须暂停”等软约束；应使用工具权限形成第二道硬门禁。

四、Skill

当前实际发现的 Skill

当前 OpenCode 真正发现了 4 个 Skill：

Skill	来源
`customize-opencode`	OpenCode 内置
`powershell-reliable`	`C:\Users\GhostCloud\.config\opencode\skills\powershell-reliable\SKILL.md`
`security-research`	Plugin 缓存目录
`security-review`	Plugin 缓存目录

查看真实可用 Skill：

bash

opencode debug skill

需要区分三种状态：

text

文件存在 ≠ 被 OpenCode 发现 ≠ 本次对话已加载

Skill 一般是按需加载的操作手册。运行时通常先向模型暴露名称和描述，匹配任务后才加载正文；并非始终把所有 SKILL.md 全文塞进上下文。

Nacos Skill 尚未接入标准链路

项目中存在：

text

nacos-skill-registry/SKILL.md

但它不在标准 Skill 目录中，项目配置也没有注册 skills.paths，因此不会出现在 opencode debug skill 中，目前不是 OpenCode 原生可调用 Skill。

推荐方案 A：移动到项目标准目录：

text

.opencode/
├── agent/
├── commands/
├── plugins/
└── skills/
    └── nacos-skill-registry/
        └── SKILL.md

方案 B：通过配置注册额外扫描路径：

jsonc

{
  "skills": {
    "paths": [
      "~/.skills",
      "./nacos-skill-registry"
    ]
  }
}

推荐方案 A，目录语义更明确，也更不依赖未来版本的路径扫描细节。

用户级通用 Skill 目录

通用 Skill 建议安装到：

text

C:\Users\GhostCloud\.config\opencode\skills\<skill-name>\SKILL.md

项目专用 Skill 建议安装到：

text

<项目根目录>\.opencode\skills\<skill-name>\SKILL.md

五、MCP

当前实际状态：

MCP	状态	用途
`websearch`	connected	Exa Web 搜索
`context7`	connected	当前库/框架文档
`grep_app`	connected	公开代码库真实用例
`lsp`	connected	符号、定义、引用、诊断
`codegraph`	disabled	代码图谱，当前禁用

查看：

bash

opencode mcp list

这些 MCP 大部分可能由 Plugin 注入，不一定直接写在项目 opencode.jsonc 中。排障时需要同时检查 Plugin 与最终合并配置。

六、概念边界

概念	作用	类比
Agent	定义谁负责、如何思考、能用哪些权限	岗位/员工
Skill	匹配任务后按需加载的详细 SOP	工作手册
Command	用户主动执行的固定入口，如 `/deploy`	快捷按钮
Plugin	注入或改变 Agent、工具、MCP、权限和消息	扩展程序
MCP	连接外部工具和服务	外部系统接口
Provider/Model	模型服务商和具体模型	大脑供应商
`AGENTS.md` / instructions	全项目都要遵守的规则	项目制度

典型调用链：

text

用户提出任务
  ↓
Primary Agent 接单
  ↓
判断是否需要 Skill
  ↓
按需加载 Skill SOP
  ↓
必要时委派 Subagent
  ↓
使用内置工具或 MCP
  ↓
Plugin 执行权限、消息、工具和生命周期钩子
  ↓
返回并验证结果

七、配置职责建议

全局配置适合存放

Provider；
Secret 文件引用；
通用 Skill；
一个主要增强 Plugin；
通用权限；
通用 MCP。

项目配置适合存放

项目默认 Agent；
项目专用 Agent；
项目专用 Skill；
项目 instructions；
项目特有 MCP；
项目默认模型名称。

当前项目重复定义整套 Provider，便于独立运行，但维护成本较高。建议全局统一定义公司 Provider，项目只指定 model；只有项目确实需要特殊模型服务时才新增 Provider。

八、Secret 管理

不要把 API Key、Token 或认证 Header 明文写进可提交配置。Provider 推荐引用独立 Secret 文件：

jsonc

{
  "options": {
    "baseURL": "{file:~/.config/opencode/secrets/ghostcloud_base_url}",
    "apiKey": "{file:~/.config/opencode/secrets/ghostcloud_glm_key}",
    "headers": {
      "Authorization": "Bearer {file:~/.config/opencode/secrets/ghostcloud_glm_key}"
    }
  }
}

如果密钥曾经明文出现在配置、日志、提交或聊天中，应：

立即轮换旧 Key；
将新 Key 写入 Secret 文件；
检查 Git 历史和日志是否残留；
确保 Secret 文件进入 .gitignore；
完全退出并重启 OpenCode。

九、最佳使用方式

按复杂度分层

text

简单问题
→ 默认 Agent 直接处理

明确专业任务
→ @指定 Agent + 输入 + 验收标准

重复工作
→ 做成 Skill 或 Command

复杂任务
→ 主 Agent 拆解，Explore/Librarian 调研，专业 Subagent 执行

高风险操作
→ Plan → 人工确认 → 执行 → 验证 → 回滚预案

高质量任务描述模板

text

目标：
范围：
不能改什么：
参考文件：
验收命令：
是否允许联网：
是否允许修改配置：

示例：

text

请检查当前分支相对 main 的改动。
只做代码审查，不修改文件。
重点检查权限绕过、部署回滚和生产暂停点。
运行现有测试，并按严重程度列出问题和文件行号。

十、常用自检命令

bash

# 当前版本
opencode --version

# 最终合并后的配置
opencode debug config

# 当前真正发现的 Skill
opencode debug skill

# 当前可用 Agent
opencode agent list

# 查看某个 Agent 的最终配置
opencode debug agent stage-5-release-orchestrator
opencode debug agent stage-5-release-deploy

# 当前 MCP 状态
opencode mcp list

# 当前实际加载的 Plugin 和运行环境
opencode debug info

# 配置、缓存、数据等目录
opencode debug paths

# 不加载外部 Plugin，用于隔离排障
opencode --pure

十一、优化优先级

P0：立即处理

轮换任何曾明文保存的 API Key。
改为 Secret 文件引用。
检查生产部署 Agent 的危险命令权限。

P1：降低复杂度

在 oh-my-openagent 和 oh-my-opencode 中选择一个主要 Plugin。
使用 opencode --pure 做能力和问题对比。
重新考虑是否让发布编排 Agent 作为项目默认 Agent。

P2：规范结构

将 Nacos Skill 移到 .opencode/skills/nacos-skill-registry/。
全局只保留通用 Provider、Skill、MCP 和权限。
项目只保留项目专用 Agent、Skill、instructions 和模型选择。

P3：持续验证

每次配置变更后：

完全退出并重启 OpenCode；
执行 opencode debug config；
执行 opencode debug info；
检查 Agent、Skill、MCP 实际清单；
运行一项最小真实任务，确认模型、权限和工具链符合预期。

十二、整体判断

当前环境不是“原生 OpenCode + 几个简单 Agent”，而是：

text

OpenCode 本体
+ 项目发布 Agent
+ 两套增强 Plugin
+ Plugin 注入的 Agent / Skill / MCP / 权限

优点是能力强、专业分工丰富；代价是来源和覆盖关系不够透明。最优先应处理：

Secret 安全；
只保留一个主要增强 Plugin；
规范 Skill 目录；
重新选择默认 Agent；
收紧部署权限。

OpenCode 运行时、配置、Plugin、Agent 与 Skill ​

一、当前运行环境 ​

OpenCode ​

当前项目默认值 ​

二、当前 Plugin ​

项目业务目录不等于原生 Plugin ​

双重增强 Plugin 的风险 ​

三、Agent ​

项目自定义 Agent ​

其他 Agent 来源 ​

默认 Agent 过度专业化 ​

发布 Agent 权限 ​

四、Skill ​

当前实际发现的 Skill ​

Nacos Skill 尚未接入标准链路 ​

用户级通用 Skill 目录 ​

五、MCP ​

六、概念边界 ​

七、配置职责建议 ​

全局配置适合存放 ​

项目配置适合存放 ​

八、Secret 管理 ​

九、最佳使用方式 ​

按复杂度分层 ​

高质量任务描述模板 ​

十、常用自检命令 ​

十一、优化优先级 ​

P0：立即处理 ​

P1：降低复杂度 ​

P2：规范结构 ​

P3：持续验证 ​

十二、整体判断 ​

相关笔记 ​

OpenCode 运行时、配置、Plugin、Agent 与 Skill

一、当前运行环境

OpenCode

当前项目默认值

二、当前 Plugin

项目业务目录不等于原生 Plugin

双重增强 Plugin 的风险

三、Agent

项目自定义 Agent

其他 Agent 来源

默认 Agent 过度专业化

发布 Agent 权限

四、Skill

当前实际发现的 Skill

Nacos Skill 尚未接入标准链路

用户级通用 Skill 目录

五、MCP

六、概念边界

七、配置职责建议

全局配置适合存放

项目配置适合存放

八、Secret 管理

九、最佳使用方式

按复杂度分层

高质量任务描述模板

十、常用自检命令

十一、优化优先级

P0：立即处理

P1：降低复杂度

P2：规范结构

P3：持续验证

十二、整体判断

相关笔记