一个 PostgreSQL 巡检 Skill，如何在 Opsx 中被 OpenCode 真正用起来

最近我在 Opsx 中导入了一套 PostgreSQL 巡检 Skill。

它不是一段单独的提示词，而是一个完整目录：里面有 800 多行的 SKILL.md、一份 2,000 多行的 Shell 脚本，还有数据库连接配置示例。过去，这类东西通常放在 DBA 的电脑、运维仓库或者某台服务器上。谁要用，谁就把文件复制过去，再根据目标数据库调整环境。

这一次我想验证的是另一件事：能不能让 Opsx 保存完整的巡检方法，在任务发生时，把 Skill、数据库资产和执行环境组合起来，再交给 OpenCode 和 LLM 使用？

如果这条链路成立，留下来的就不只是一份健康报告，而是一项可以继续交给不同 Agent、不同 LLM 和不同 PostgreSQL 资产使用的平台能力。

这次实践使用了两个真实对象：

• kw_156：导入 Opsx 的 db-server-healthcheck-postgresql Skill；
• issue_122：使用该 Skill 执行 PostgreSQL 健康巡检的 Issue。

巡检已经完成，整体结论为 Warning。数据库当时没有阻塞、长事务、严重表膨胀或 XID 回卷风险，但磁盘、WAL 归档、日志、安全配置、部分表结构以及 PostgreSQL 版本都存在需要继续处理的问题。

Skill 是 Multi-Agent 平台的基础设施

对于任何 Multi-Agent 或 AI 平台，Agent 和 LLM 只解决了“由谁思考、由谁执行”的问题。平台还必须回答另一个问题：专业能力从哪里来，又怎样被不同执行端复用？

这个承载专业能力的基本单元就是 Skill。数据库巡检、Kubernetes 排障、日志分析、备份校验等任务，都不应该每次只依靠 LLM 临时生成命令，而需要已经验证过的说明、脚本、参考资料、阈值和安全边界。

因此，内置 Skill 和导入外部 Skill 不是锦上添花，而是 Multi-Agent 平台的基础能力。如果 Skill 仍然分别安装在 OpenCode、Claude Code 或其他 Agent 的本地目录中，就会出现新的孤岛：

同一项运维能力
  → 在不同 Agent 中复制多份
  → 内容和版本逐渐不一致
  → 更换 Agent 或 LLM 后重新配置
  → 使用记录和改进经验无法回到平台

Opsx 支持内置 Skill，也支持把已有 .skill 和 .zip 包导入平台。更重要的是，Opsx 将 Skill 作为 Knowledge 体系中的一等对象集中管理，而不是把它附属于某个 Agent。

在页面上，可以完成一套 Skill 的创建、导入、查询、查看、修改和删除；进入详情后，还能查看目录树，编辑 SKILL.md，增加、修改或删除配套脚本和资源文件。版本、Manifest、状态和 Audit 都由 Opsx 保存。

Opsx 持有 Skill
  ├── 页面统一增删改查
  ├── Workspace 范围内共享和治理
  ├── 保存版本、文件、Manifest 与审计记录
  └── 执行时适配 OpenCode、Claude Code、Codex 等不同 Agent

Agent / LLM
  └── 作为可替换的执行和推理能力使用 Skill

这样一来，切换 Agent 或 LLM 不等于迁移整套运维方法。平台保存能力，Agent 和 LLM 消费能力。这是 Opsx 支持 Any Agent · Any LLM · Shell 的必要基础。

一个巡检脚本为什么还不够

PostgreSQL 巡检并不缺 SQL，也不缺开源脚本。真正难以复用的，是脚本周围的那些知识：

• 什么时候应该检查连接数，什么比例需要告警；
• 缓存命中率、死元组、XID Age 应该怎样解释；
• 主库、备库和单节点实例分别应该检查哪些复制指标；
• 某个查询在不同 PostgreSQL 版本中是否兼容；
• 缺少凭据时应该停止，还是允许继续寻找其他连接路径；
• 哪些动作只是查询，哪些建议可能触发重启或业务风险。

只把脚本交给 Agent，它可能会运行，却不一定理解边界和结果。只把方法写进 Prompt，LLM 又要临时生成大量 SQL，稳定性和完整性都难以保证。

因此，这套 Skill 同时包含了两部分：

SKILL.md
  适用场景、连接规则、检查菜单、阈值、安全要求、结果解释

pg_health_check.sh
  按固定规则执行连接、锁、WAL、Vacuum、索引、配置等检查

LLM 负责理解任务、选择工具、处理环境差异和解释异常；Shell 负责重复、稳定地执行巡检基线。两者并不是互相替代的关系。

但文件一多，新的问题也出现了：怎样保证 SKILL.md、脚本和配套资源始终属于同一个版本？怎样把它完整交给 OpenCode，而不是让人再次登录服务器复制目录？

这正是 Opsx 导入多文件 Skill 要解决的问题。

kw_156：把整个目录导入，而不是粘贴一段 Markdown

Opsx 支持导入 .skill 或 .zip 格式的 Skill 包。它会在压缩包中定位 SKILL.md，将其作为主入口，同时保留同一目录下的配套文件和相对路径。

kw_156 实际保存的目录如下：

db-server-healthcheck-postgresql/
├── SKILL.md
├── scripts/
│   └── pg_health_check.sh
└── assets/
    └── db_config.env

完整 Bundle 的 Manifest 大小为 89,846 bytes。本文核对时，kw_156 是 active、shared 状态，版本为 v6。

导入过程中，Opsx 还会处理一些不太显眼但很重要的工程问题：

读取 SKILL.md Front Matter
  → 得到 Skill 名称和用途

校验配套文件相对路径
  → 拒绝绝对路径、.. 路径穿越和保留文件名冲突

计算每个文件的 SHA-256
  → 标识单个文件内容

生成整个 Bundle 的 Manifest Hash
  → 标识这一版完整 Skill

当前实现限制最多 128 个配套文件，单文件不超过 1 MiB，配套文件总量不超过 8 MiB。导入动作也会进入 Audit。

这些并不是为了把 Skill 做成一个普通的“附件管理”功能。它真正解决的是 Skill 的身份、完整性和治理问题：脚本更新后，不能继续搭配旧说明；Agent 执行时，也不能只拿到文件名却缺少真实内容。

过去复制到个人目录中的 Skill 很容易变成一项个人能力。进入 Opsx 后，它才有机会成为 Workspace 中可以持续使用、可以审计、可以更新的运维知识。

Skill 只有和资产结合，才是运维能力

导入成功并不等于可以立即巡检。Skill 说明“怎样检查 PostgreSQL”，却不知道这次应该检查哪一套数据库、属于什么环境、运行在哪台主机，也不知道应该通过哪个 Runtime 触达。

这些信息来自 Opsx 的 Asset 和 Asset Graph。

issue_122 绑定的目标资产是 db-postgres。在任务开始前，Opsx 已经知道：

Issue Plan 又显式指定了 kw_156。于是，一次巡检所需的上下文被组合起来：

db-postgres
  确定巡检对象、环境和业务关系

mes-app-01
  确定从哪里触达这个对象，以及有哪些执行能力

kw_156
  提供 PostgreSQL 巡检方法、脚本和判断标准

issue_122
  保存本次目标、安全要求、执行过程、证据和结论

这也是普通聊天式 AI 和 Opsx 之间非常实际的区别。

如果只打开一个 LLM 对话，我需要自己提供主机、数据库、端口、脚本位置、依赖关系和历史背景。信息少了，模型只能猜；信息多了，又会形成一段难以维护的巨大 Prompt。

Opsx 先解析真实资产，再把平台已经保存的 Skill 交给正确 Runtime。LLM 仍然需要推理，但目标环境和执行路径不再完全依赖它临场判断。

OpenCode 拿到的是一个可以执行的 Skill 目录

issue_122 选择 OpenCode 作为 Runner。派发任务时，Opsx 不只是把 SKILL.md 作为参考文本发给它，还会把配套脚本和资源文件保持原目录结构，写入 OpenCode 能原生发现的位置：

$WORKSPACE/.opencode/skills/
└── db-server-healthcheck-postgresql/
    ├── SKILL.md
    ├── scripts/pg_health_check.sh
    └── assets/db_config.env

执行记录验证了这三个文件确实出现在目标 Runtime，文件大小与 Opsx 中保存的 Bundle 一致。OpenCode 启动后首先加载 db-server-healthcheck-postgresql，随后读取配置示例和巡检脚本。

这一步是整个案例里最关键的连接点：

Opsx 中的平台知识
  → Runtime 上的 Agent 原生目录
  → Agent 可以发现并调用的实际工具

不同 Agent 的 Skill 目录可以不同。OpenCode 使用 .opencode/skills/，Claude Code、Codex 等 Runner 可以由各自的适配器写入对应目录。Opsx 保存规范内容，Agent 只是使用它的执行端。

因此，以后即使替换 OpenCode 或底层 LLM，也不需要把 PostgreSQL 巡检方法重新变成另一份私有配置。变化的是执行工具，保留下来的是 Skill、资产上下文和使用记录。

AI 在这次巡检中究竟做了什么

任务没有要求 OpenCode 自由发挥，而是设置了明确边界：必须使用 kw_156，先确认连接和工具条件，只允许执行只读诊断，缺少前置条件时停止，不得猜测凭据，最终报告必须给出证据、严重程度和建议。

Skill 对数据库连接也规定了顺序：

命名连接别名
  → 任务明确提供的连接参数
  → PGHOST / PGPORT / PGUSER / PGDATABASE 等环境变量
  → 都不存在时请求人提供前置条件

OpenCode 在目标 Runtime 确认 PostgreSQL 实例后，先执行 Skill 中的综合巡检脚本。脚本覆盖 10 个方面：

• 实例概况；
• 性能指标；
• 备份与恢复；
• 数据库对象；
• 安全；
• 会话与锁；
• 事务与回卷；
• 日志与审计；
• 关键配置；
• SQL 性能。

脚本给出了稳定的检查基线，但报告并没有停在脚本输出。LLM 根据现场结果继续补查了宿主机磁盘和内存、容器资源、重启策略、空闲会话、序列使用率、无主键表的 Heap 与 TOAST 占用、数据目录权限和有效认证规则。

这部分体现了 Agent 的价值：真实环境不会完全符合脚本作者的预期，数据库版本、工具安装方式和部署结构也会变化。LLM 可以读取命令反馈，调整查询，再围绕异常继续调查；Shell 脚本则保证核心检查项不会随着模型的一次回答而随意增减。

正式执行 exec_1537 用时约 9 分 52 秒，状态为 completed。Opsx 保存了 Skill 加载、文件读取、命令执行和最终报告，因此报告中的判断可以回到原始证据，而不是只剩一段无法复核的 AI 总结。

报告没有只给一个“健康”或“不健康”

这套 PostgreSQL 在巡检时没有严重的运行故障。连接使用率为 22%，业务库缓存命中率为 100%；没有阻塞锁、等待锁、长事务、死锁和临近 XID 回卷的问题，Autovacuum 也处于开启状态。

但从恢复能力、安全和长期维护角度看，它并不适合被简单标记为“健康”。报告给出的主要发现如下：

AI 报告的意义不是给配置参数下一个简单结论，而是把事实和建议分开。

例如，当前 shared_buffers 相对宿主机内存偏低，但这台主机还运行其他服务，容器也没有独立资源限制，不能机械地按照“宿主机内存的 25%”直接修改。logging_collector=off 只能证明 PostgreSQL 没有生成自己的文件日志，是否已经通过 Docker Logging Driver 或外部平台留存，还需要人继续核对。

这类判断正是专业人员不能缺席的地方。Skill 提供标准，LLM 给出线索和解释，人负责补充架构事实、评估业务影响并决定是否行动。

巡检到此为止，整改仍然由人决定

OpenCode 给出了 WAL 归档、磁盘清理、SSL、认证方式、日志、超时、容器重启策略和版本升级等建议，但没有自动执行整改。

这是刻意保留的边界。查询系统视图与修改 postgresql.conf、pg_hba.conf、表结构或容器策略，风险完全不同。特别是给已有业务表增加主键，必须先检查重复数据、应用 SQL、写入链路和停机窗口。

截至本文核对时，issue_122 仍处于 in_review。Execution 已经完成，报告已经返回，但整改项还需要人工确认。因此，文章只能说“发现了问题并给出建议”，不能写成“数据库已经完成治理”。

这次执行也暴露了值得继续收紧的权限边界。

数据库诊断 SQL 都是只读查询，没有修改数据、参数和表结构；不过，为了执行脚本，Agent 曾将 pg_health_check.sh 复制到容器临时目录并设置执行权限。它没有改变数据库持久数据和配置，但严格来说产生了临时文件变更。

同时，执行路径具备宿主机 sudo docker 和容器内 PostgreSQL 管理权限。Prompt 限制了只读动作，实际命令也没有写数据库，但这仍然不是理想的最小权限模型。

如果要把该 Skill 用于更多生产数据库，我会先补齐：

专用只读巡检账号
  + Runtime Secret 管理连接信息
  + 允许访问的系统视图和 Shell 命令边界
  + Skill 版本审核与兼容性测试
  + 结构化巡检结果与人工审批

AI 不是安全边界。Opsx 能把 Skill 送到真实资产只是第一步，长期价值还来自平台对资产、Runtime、Secret、执行证据和审核状态的持续治理。

PostgreSQL 巡检只是一个开始

如果只是完成一次 PostgreSQL 巡检，把脚本复制到服务器上运行也能得到结果。但复制结束后，方法仍然依赖那台机器和执行它的人。

这次实践发生了一个更有意义的变化：

这与 Opsx Landing Page 中的产品设计是一致的：Opsx 先识别资产，复用已经学到的方法，再让合适的 Agent 或 Shell 通过明确的 Runtime 行动。执行结果返回平台，而不是留在某个 Agent 的独立会话里。

在这个案例中，Opsx 是控制中枢，db-postgres 和 Asset Graph 提供确定性环境，kw_156 保存巡检方法，OpenCode 和 LLM 负责调查与解释，Shell 脚本负责稳定执行，issue_122 则保留整个任务的上下文和证据。

一次巡检结束后，健康数据会过时，但 Skill 不会随报告一起消失。下一次面对另一套 PostgreSQL，Opsx 仍然可以从同一套方法开始，再结合新的资产事实执行。

而 PostgreSQL 巡检只验证了这套机制的一个具体场景。只要把专业方法整理成包含说明、脚本、参考资料和资源模板的 Skill，后续还可以继续导入更多能力，例如：

• MySQL、MogDB、Redis 和 Elasticsearch 健康巡检；
• Kubernetes 工作负载排障与发布检查；
• Nginx、网关、证书和域名链路诊断；
• 日志分析、容量评估、备份恢复验证；
• 云资源盘点、安全基线和成本检查；
• 应用发布、回滚和变更后的验证流程。

这些只是可扩展方向，并不表示 Opsx 已经自动拥有所有专业能力。第一次引入某个领域的 Skill，仍然需要专业人员审核方法、脚本、权限和适用版本；但一旦通过验证，它就可以由 Opsx 中心化保存，再与不同 Asset、Runtime、Agent 和 LLM 组合使用。

平台中的 Skill 越丰富，Opsx 可以完成的任务边界就越宽；同一 Skill 被更多 Issue 使用后，现场证据和人工反馈又能帮助继续修正它。这样积累的不是某个 Agent 的私人技巧，而是组织可以持续维护和复用的运维能力库。

这才是这次实践真正验证的价值：执行工具可以替换，Skill 可以持续扩展，平台保存的资产上下文、专业方法和使用经验会不断积累。