问题 链接到标题

每次启动 OpenCode，agent 对你的项目结构、主机信息、常用操作一无所知。

今天查过的主机列表，明天又要重新解释。这周写过的部署流程，下周 agent 又忘了。每次都在重复——低效且容易遗漏。

解决思路是用配置文件构建"静态记忆"：一次配置，提交 git，每个新会话自动生效。

什么是静态记忆架构 链接到标题

静态记忆 = 提交到 git 的配置文件，OpenCode 每次启动自动读取或按需加载。

它和"动态记忆"（MCP 插件、向量数据库）的区别：静态记忆没有运行时依赖，不消耗额外服务，修改就是改 .md 文件提交 git。

完整架构由四层组成：

~/.config/opencode/AGENTS.md          ← 全局层（个人规则）
./AGENTS.md                            ← 项目层（路由 + 懒加载规则）
.opencode/opencode.json                ← 配置层（instructions + 权限）
.opencode/skills/<name>/SKILL.md       ← 技能层（按需加载的工作流）
docs/*.md                              ← 内容层（按需读取的知识库）

下面逐层搭建。

第一层：全局 AGENTS.md 链接到标题

全局规则放在 ~/.config/opencode/AGENTS.md，所有项目都生效，不提交 git。

用中文回答问题。
回答简洁，不废话，不说"好的"、"明白了"等开场白。

适合放这里的内容：

  • 你的名字和称呼方式
  • 语言偏好
  • 通用的回复风格要求
  • 个人常用快捷键或工作流偏好

第二层：项目 AGENTS.md 链接到标题

项目根目录的 AGENTS.md 是静态记忆的核心。运行 opencode /init 可以自动生成骨架。

它只做两件事：定义懒加载规则 + 提供文档路由索引。

# DevOps.ai - 日常运维

## 懒加载规则

CRITICAL: 当遇到 `docs/xxx.md` 引用时，用 Read tool 按需加载。
- 不预加载所有文件，根据当前任务只读需要的
- 加载后视为强制指令

## 概述

管理多个节点（本机 + SSH 远程）执行日常任务和运维操作。

## 文档索引

- SSH 主机列表 → docs/hosts.md（已预载）
- PVE 集群节点及 GPU VM → docs/pve.md
- 数据库连接 → docs/databases.md
- 监控系统 → docs/monitoring.md
- 其他服务 → 详见 docs/ 目录

## 使用规则

- 敏感信息存 `.env`，使用前先 source 加载
- SSH 免密登录，直接 `ssh <hostname>`

关键原则：AGENTS.md 只做路由，不做百科。每个文档用一句话索引，细节交给 agent 按需读取。

第三层：opencode.json + instructions 链接到标题

项目级配置 .opencode/opencode.json 负责两件事：instructions 注入和权限控制。

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["docs/hosts.md"],
  "permission": {
    "skill": { "*": "allow" }
  }
}

instructions 中的文件每次会话自动合并到 context。什么文件适合放这里？

  • 文件小（小于 50 行）
  • 几乎每次操作都用得到

以 devops 项目为例，22 个文档 800+ 行，只把 hosts.md（36 行）放 instructions。其他文件让 agent 按需读取，不浪费 context 窗口。

第四层：docs/ 目录 链接到标题

每个服务一个 .md 文件，简洁、聚焦。

# PVE 集群

## 集群节点
| 节点 | GPU | 用途 |
|------|-----|------|
| n1 | RTX 4060 Ti | PVE 宿主机 |
| n2  | RTX 4060 Ti | PVE 宿主机 |

## GPU 直通 VM
| VM | 节点 | 用途 |
|----|------|------|
| vm1 | n1 | AI 推理服务 |

## 常用命令
ssh <node> sudo qm list
ssh <node> sudo qm start/stop/shutdown <vmid>

敏感信息（密码、密钥）存 .env，不在文档中出现。agent 只有涉及对应主题时才会 Read 对应的文件。

第五层：Skills（技能层） 链接到标题

如果说 docs 是知识库，skills 就是可执行的工作流。每个 skill 是一个 .opencode/skills/<name>/SKILL.md，通过 skill 工具按需加载。

实例：WOL（网络唤醒）Skill 链接到标题

有三台主机（node-a、node-b、node-c），有时关机需要远程唤醒。

---
name: wol
description: 网络唤醒 — 通过 SSH 中继发送 WOL Magic Packet 唤醒已关机的主机
---

## 原理
本地 → ssh <relay> wakeonlan → 广播 Magic Packet → 目标主机启动

## 主机列表
| 主机 | IP | MAC |
|------|-----|-----|
| node-a | 10.99.99.50 | aa:bb:cc:11:22:33 |
| node-b | 10.99.99.51 | dd:ee:ff:44:55:66 |

## 使用
ssh relay "wakeonlan -i 10.99.99.255 <MAC>"

## 验证
ssh node-a "hostname && uptime -p"

当用户说"帮我唤醒 node-a"，agent 检查可用 skills → 发现 wol 的 description 匹配 → 通过 skill 工具加载 SKILL.md → 按步骤执行。

docs 和 skills 怎么选 链接到标题

docs skills
内容 参考信息 可执行工作流
加载方式 agent 自己 Read skill tool 触发
适用场景 查端口、查地址 多步操作、带条件判断

简单参考信息放 docs，多步操作流程放 skills。

执行流程 链接到标题

用户说"检查下 PVE 集群状态"时的实际路径：

主 agent context:
├── AGENTS.md → "PVE 集群 → docs/pve.md"
├── hosts.md（instructions 预载）
└── 涉及 PVE → Read docs/pve.md → 执行命令

用户说"帮我唤醒 node-a"时的实际路径：

主 agent context:
├── AGENTS.md → 索引文档
├── hosts.md（预载）
├── 发现 node-a 关机 → 匹配 skill: wol
└── skill tool 加载 SKILL.md → 按步骤执行

收益 链接到标题

  • Token 节省：22 个文档 800+ 行不预加载，按需读取
  • 持久性：配置提交 git，每个会话自动生效
  • 模块化：AGENTS.md 路由、docs 知识库、skills 工作流，各司其职
  • 可维护：新增服务 = 加一行索引 + 一个 docs 文件；新增工作流 = 一个 skill 目录
  • 低门槛：只依赖 .md 文件和 .json 配置，不需要 MCP 服务器或第三方服务

对比 链接到标题

无静态记忆 有静态记忆
每会话 手动解释项目 自动注入
新增场景 次日"忘记" 改一行索引即可
复杂操作 每次手敲命令 skill 一键唤起
团队协作 各人各风格 配置提交 git，全员共享

总结 链接到标题

静态记忆架构的核心思路：用配置文件替 agent 记住项目，而不是让 agent 每次都重新学习。

四层文件各司其职：

  • 全局 AGENTS.md 管个人偏好
  • 项目 AGENTS.md 管路由和规则
  • opencode.json 注入最刚需的小文件
  • docs 目录管理知识库
  • skills 封装可复用的工作流

一次配置，之后每个新会话 agent 都像老员工一样熟悉项目。