主权个人必看的 OpenCode 教程之第三课（2026版）
-
主权个人必看的 OpenCode 教程之第三课（2026版）
目录- 📐 技术体系全景
- 1.1 上下文窗口（Context Window）
- 🔬 技术原理
- 📊 场景示例
- ✅ 技术要点总结
- 1.2 Agent 模式（Plan vs Build）
- 🔬 技术原理
- 📊 场景示例
- ✅ 技术要点总结
- 1.3 工具系统（Tools）
- 🔬 技术原理
- 📊 场景示例
- ✅ 技术要点总结
- 1.4 文件系统（File System）
- 🔬 技术原理
- 📊 场景示例
- ✅ 技术要点总结
- 2.1 @ 引用机制
- 🔬 技术原理
- 📊 场景示例
- 🔧 高级用法
- ✅ 技术要点总结
- 2.2 渐进式披露（Progressive Disclosure）
- 🔬 技术原理
- 📊 场景示例
- 🔧 实现渐进式披露的技术手段
- ✅ 技术要点总结
- 3.1 Agent 配置
- 🔬 技术原理
- 📊 场景示例
- 🔧 高级配置技巧
- ✅ 技术要点总结
- 3.2 Skill 系统
- 🔬 技术原理
- 📊 场景示例
- 🔧 Skill 权限配置
- ✅ 技术要点总结
- 3.3 Command 系统
- 🔬 技术原理
- 📊 场景示例
- 🔧 高级配置
- ✅ 技术要点总结
- 4.1 权限控制
- 🔬 技术原理
- 📊 场景示例
- ✅ 技术要点总结
- 4.2 CLI 自动化
- 🔬 技术原理
- 📊 场景示例
- ✅ 技术要点总结
- 4.3 MCP 协议（Model Context Protocol）
- 🔬 技术原理
- ⚠️ 注意事项
- 总结
- 技术体系回顾
在本节课中，Brave试图教会你，如何应用OpenCode的技术体系，实现人机协同。场景会变，技术不会。这是一节教你掌握"与 AI 协作的底层技术"的课程。 一旦掌握这套技术体系，你可以将其应用于任何场景：
领域 应用示例 学术研究 文献综述、论文写作、数据分析、引用管理 软件开发 代码审查、架构设计、文档生成、测试编写 数据分析 SQL 查询、可视化报告、指标计算、趋势分析 内容创作 文章撰写、翻译润色、脚本创作、文案设计 流程自动化 批量处理、定时任务、CI/CD 集成、报告生成 核心洞察：OpenCode 的价值不是"更聪明的 ChatGPT"，而是解决了网页版 AI 的三个根本局限：
局限 网页版 AI OpenCode 解决方案 易失性 对话关闭即消失 文件系统持久化 重复性 每次重新描述需求 Agent/Skill/Command 复用 失控性 无法精确控制输入 @ 引用 + 渐进式披露 📐 技术体系全景
┌─────────────────────────────────────────────────────────────────────────┐ │ 第四层：自动化与扩展 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ CLI 自动化 │ │ MCP 协议 │ │ 权限控制 │ │ │ │ 脚本化调用 │ │ 外部工具集成 │ │ 安全边界 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ├─────────────────────────────────────────────────────────────────────────┤ │ 第三层：持久化与复用 │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Agent 配置 │ │ Skill 系统 │ │ Command 系统│ │ │ │ 固化 AI 人格 │ │ 专业知识包 │ │ 快捷命令 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ├─────────────────────────────────────────────────────────────────────────┤ │ 第二层：上下文管理 │ │ ┌────────────────────────────┐ ┌────────────────────────────┐ │ │ │ @ 引用机制 │ │ 渐进式披露 │ │ │ │ 将外部信息精确注入上下文 │ │ 按需加载，保持注意力集中 │ │ │ └───────────────────────────┘ └────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────────────────┤ │ 第一层：基础原理 │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ 上下文窗口 │ │ Agent 模式 │ │ 工具系统 │ │ 文件系统 │ │ │ │ 注意力机制 │ │ Plan/Build│ │ 读写搜索 │ │ 持久化 │ │ │ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘学习路径：
阶段 时间 内容 达成目标 入门 1-2 周 第一层 + 2.1 能够高效使用 OpenCode 完成日常任务 进阶 2-4 周 第二层 + 第三层 能够创建可复用的 Agent/Skill/Command 高级 4+ 周 第四层 能够构建自动化工作流和扩展系统 第一层：基础原理
本层目标：理解 OpenCode 的底层工作机制，为后续技术打下坚实基础。
1.1 上下文窗口（Context Window）
💡 一句话：上下文窗口是 AI 的"工作记忆"——它决定了 AI 能同时"看到"多少信息，也是所有上下文管理技术的出发点。
🔬 技术原理
什么是上下文窗口？
大语言模型（LLM）在处理你的请求时，需要把所有相关信息放入一个"窗口"进行处理。这个窗口包含：
┌─────────────────────────────────────────────────────────────┐ │ 上下文窗口（Context Window） │ ├─────────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 系统提示词（System Prompt） │ │ │ │ - OpenCode 的基础指令 │ │ │ │ - Agent 配置内容 │ │ │ │ - 可用工具的定义 │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 对话历史（Conversation History） │ │ │ │ - 之前的问答记录 │ │ │ │ - 工具调用和结果 │ │ │ └─────────────────────────────────────────────────────┘ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ 当前输入（Current Input） │ │ │ │ - 你的提示词 │ │ │ │ - @ 引用的文件内容 │ │ │ └─────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 容量上限：Claude 200K tokens / GPT-4.1 400K tokens │ │ ⚠️ 注意：更大 ≠ 更好 │ └─────────────────────────────────────────────────────────────┘关键洞察：为什么"更多信息"反而效果更差？
这是理解 OpenCode 所有上下文管理技术的核心洞察。
"给 LLM 更多上下文往往会让它在指令遵循任务上表现更差，而不是更好。问题不在于上下文窗口大小——而在于注意力。当前的 LLM 在跨大上下文保持注意力方面出奇地差。"
类比理解：想象你在一个嘈杂的房间里听人说话。房间里有 3 个人说话，你能听清每个人；但如果有 30 个人同时说话，你可能一个都听不清。LLM 的"注意力"也是如此。
实验证据：
上下文大小 指令遵循准确率 原因分析 适量（~10K tokens） 95%+ 注意力集中 中等（~50K tokens） 80-90% 开始分散 大量（~100K+ tokens） 60-80% 严重分散，可能遗漏关键指令 上下文窗口的三个核心特性
特性 说明 实践意义 有限性 窗口有容量上限 需要选择性地加载信息 竞争性 所有内容共享注意力 无关内容会稀释对关键信息的注意力 即时性 每次请求重新构建 需要持久化机制保存重要信息 📊 场景示例
场景 ❌ 错误做法 ✅ 正确做法 技术原理 学术论文分析 把整篇 50 页论文丢给 AI 先看目录结构，再按需读取特定章节 渐进式披露 代码库审查 把整个项目塞进上下文 用 glob/grep 定位相关文件 精确引用 数据表查询 导入所有表的 schema 先了解需要哪些表，再读取对应结构 按需加载 翻译长文档 一次性翻译全文 分段翻译，保持术语一致 分治策略 ✅ 技术要点总结
- 上下文是稀缺资源——不是越多越好，而是越精确越好
- 注意力会分散——无关内容会干扰 AI 对关键指令的遵循
- 按需加载——只在需要时引入相关信息（这就是渐进式披露的理论基础）
- 需要持久化——重要信息应该保存在文件系统中，而不是依赖对话历史
1.2 Agent 模式（Plan vs Build）
💡 一句话：Plan 模式专注思考，Build 模式执行操作——这不仅是权限区分，更是上下文管理策略的不同。
🔬 技术原理
模式的本质
很多人以为 Plan 和 Build 只是"只读 vs 可写"的区别。这只对了一半。
更深层的区别在于上下文构成的不同：
维度 Plan 模式 Build 模式 工具权限 只读工具（read, glob, grep, list） 完整工具（+ write, edit, bash） 系统提示词 精简版，强调分析规划 完整版，包含工具使用指南 AI 注意力分配 ~100% 在你的问题上 部分注意力在"如何使用工具"上 输出倾向 分析、建议、方案 执行、创建、修改 为什么要分离"想"和"做"？
"将复杂任务分解为更简单的子任务"是提升 LLM 输出质量的核心策略之一。
Plan-Build 模式就是这一原则在工具层面的实现：
复杂任务 │ ▼ ┌─────────────────┐ ┌─────────────────┐ │ Plan 阶段 │ → │ Build 阶段 │ │ - 分析需求 │ │ - 执行方案 │ │ - 探索方案 │ │ - 创建产物 │ │ - 确定结构 │ │ - 迭代修改 │ │ - 无副作用 │ │ - 持久化结果 │ └─────────────────┘ └─────────────────┘关键优势：
- Plan 阶段可以反复讨论——不会产生任何副作用（文件创建、代码执行）
- Build 阶段有明确目标——基于 Plan 阶段的结论执行，减少返工
- 错误成本降低——在 Plan 阶段发现问题比在 Build 阶段发现问题代价小得多
模式切换的技术细节
操作方式：按
Tab键切换模式，状态栏显示当前模式模式判断标准：
你的任务 推荐模式 原因 "帮我分析这个代码库的架构" Plan 分析任务，不需要修改 "设计一个论文的结构" Plan 规划任务，需要讨论 "给这个函数写单元测试" Build 需要创建文件 "重构这段代码" Build 需要修改文件 "这个方案可行吗？" Plan 评估任务 "按方案实现" Build 执行任务 📊 场景示例
场景一：学术论文写作
Plan 阶段（可能需要 30 分钟讨论） ├── 讨论研究问题的界定 ├── 确定论文的章节结构 ├── 分析每章的核心论点 ├── 评估论证逻辑的完整性 └── 确定需要的支撑材料 Build 阶段（基于 Plan 结果执行） ├── 创建论文目录结构 ├── 撰写各章节初稿 ├── 生成引用格式 ├── 创建图表 └── 迭代修改润色场景二：软件架构设计
Plan 阶段 ├── 分析需求和约束 ├── 评估技术选型（数据库、框架、部署方式） ├── 设计模块划分和接口 ├── 讨论扩展性和性能考量 └── 确定开发优先级 Build 阶段 ├── 创建项目结构 ├── 生成配置文件 ├── 编写核心模块代码 ├── 创建 API 接口 └── 编写测试用例场景三：数据分析项目
Plan 阶段 ├── 明确分析目标和业务问题 ├── 了解数据源和数据质量 ├── 设计分析思路和指标定义 ├── 确定可视化方案 └── 规划报告结构 Build 阶段 ├── 编写数据查询脚本 ├── 生成分析结果 ├── 创建可视化图表 ├── 撰写分析报告 └── 导出最终产物✅ 技术要点总结
- Plan 模式用于"思考"——分析、规划、探索、评估
- Build 模式用于"执行"——创建、修改、运行、输出
- 先 Plan 后 Build——这是一种工程纪律，能显著提升输出质量
- Plan 阶段无副作用——可以安全地反复讨论，直到方案确定
- 模式切换是主动行为——你需要有意识地选择当前应该处于什么模式
1.3 工具系统（Tools）
💡 一句话：工具是 AI 与外部世界交互的接口——理解每个工具的能力和限制，是高效使用 OpenCode 的基础。
🔬 技术原理
工具调用的工作流程
当你向 OpenCode 发送请求时，AI 并不是直接生成最终回复，而是经历一个"思考→调用→处理"的循环：
你的请求 │ ▼ ┌─────────────────────────────────────────────────────────┐ │ AI 理解意图 │ │ "用户想要查找项目中所有包含 TODO 的 Python 文件" │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ AI 选择工具 │ │ "这是内容搜索任务 → 使用 grep 工具" │ │ "需要限定文件类型 → 使用 type 参数" │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 工具执行 │ │ grep(pattern="TODO", type="py") │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ 结果返回 │ │ 找到 15 个匹配文件... │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ AI 处理结果，生成回复 │ │ （可能需要多轮工具调用） │ └─────────────────────────────────────────────────────────┘核心工具详解
📖 读取类工具
工具 功能 关键参数 技术限制 使用场景 read 读取文件内容 file_path（必需）<br>offset、limit（可选）默认最多 2000 行<br>超长行会被截断 查看代码、文档、配置文件 glob 按模式查找文件 pattern（必需）<br>path（可选）最多返回 100 条<br>按修改时间排序 查找特定类型/命名的文件 grep 按内容搜索文件 pattern（正则表达式）<br>type、glob（过滤）最多返回 100 条<br>遵守 .gitignore 查找包含特定内容的文件 list 列出目录结构 path（绝对路径）最多返回 100 个文件<br>有内置忽略列表 了解项目结构 技术细节：
read 工具的行为 ├── 默认读取前 2000 行 ├── 可以用 offset + limit 读取特定范围 ├── 超过 2000 字符的行会被截断 └── 返回带行号的内容（方便后续 edit） glob 工具行为 ├── 使用 glob 模式匹配（如 **/*.py） ├── 结果按文件修改时间排序（最新的在前） ├── 最多返回 100 条（超过会被截断） └── 比 grep 更快（不读取文件内容） grep 工具的行为 ├── 使用正则表达式匹配内容 ├── 基于 ripgrep（非常快） ├── 默认遵守 .gitignore 规则 └── 可以用 .ignore 文件覆盖忽略规则✏️ 写入类工具
工具 功能 关键参数 技术限制 使用场景 write 创建/覆盖文件 file_path、content覆盖前必须先 read 创建新文件、完全重写 edit 精确修改文件 old_string、new_stringold_string 必须唯一匹配 修改代码片段、更新配置 技术细节：
write 工具的行为 ├── 如果文件存在，会完全覆盖 ├── 对已存在的文件，必须先 read（安全机制） ├── 会自动创建不存在的父目录 └── 适合创建新文件或完全重写 edit 工具的行为 ├── 基于"查找-替换"机制 ├── old_string 必须在文件中唯一匹配 ├── 如果匹配多处，需要提供更多上下文使其唯一 ├── replace_all=true 可以替换所有匹配 └── 适合精确修改，保持文件其他部分不变⚙️ 执行类工具
工具 功能 关键参数 技术限制 使用场景 bash 执行 Shell 命令 commandtimeout（可选）workdir（可选）默认超时 2 分钟<br>输出最多 30000 字符 运行脚本、Git 操作、系统命令 技术细节：
bash 工具的行为 ├── 在持久化的 Shell 会话中执行 ├── 默认超时 120000ms（2 分钟） ├── 可以用 timeout 参数调整（最大 10 分钟） ├── workdir 参数指定工作目录（避免 cd &&） ├── 输出超过 30000 字符会被截断 └── 支持后台运行（run_in_background=true）工具选择策略
需求 推荐工具 原因 查找名为 *.config.js的文件glob 只需要文件名匹配，不需要读内容 查找包含 API_KEY的文件grep 需要按内容搜索 了解项目目录结构 list 快速获得树形结构 查看某个文件的内容 read 直接读取文件 创建新的配置文件 write 创建新文件 修改函数名 edit + replace_all精确替换，保持其他部分不变 运行测试 bash 执行系统命令 📊 场景示例
场景：代码审查工作流
步骤 1：了解项目结构 工具：list 目的：获得项目的整体结构 步骤 2：定位目标文件 工具：glob(pattern="src/**/*.ts") 目的：找到所有 TypeScript 源文件 步骤 3：搜索潜在问题 工具：grep(pattern="console\.log", type="ts") 目的：找到所有调试日志 步骤 4：读取具体文件 工具：read(file_path="src/api/handler.ts") 目的：查看具体实现 步骤 5：修改代码 工具：edit(old_string="console.log(...)", new_string="logger.debug(...)") 目的：替换调试日志为正式日志 步骤 6：运行测试 工具：bash(command="npm test") 目的：确认修改没有破坏功能✅ 技术要点总结
- 工具有限制——了解每个工具的返回上限和约束条件
- 工具有适用场景——选择正确的工具能显著提升效率
- 工具可以组合——复杂任务需要多个工具配合完成
- 工具调用有成本——每次调用都消耗时间和（可能的）上下文空间
- Plan 模式限制工具——只有只读工具可用，这是有意为之的设计
1.4 文件系统（File System）
💡 一句话：文件系统是 OpenCode 的"持久化层"——让 AI 的工作成果能够保存、复用、版本控制。
🔬 技术原理
网页版 AI 的根本局限
┌────────────────────────────────────────────────────────┐ │ 网页版 AI 对话 │ ├────────────────────────────────────────────────────────┤ │ │ │ 输入 ──────────────────────────────────→ 输出 │ │ │ │ │ ▼ │ │ ┌─────────────────┐ │ │ │ 内存（临时） │ │ │ │ 关闭即消失 │ │ │ └─────────────────┘ │ │ │ │ 问题： │ │ - 无法保存中间成果 │ │ - 无法引用历史内容 │ │ - 无法跨会话协作 │ │ - 每次都从零开始 │ │ │ └────────────────────────────────────────────────────────┘OpenCode + 文件系统的解决方案
┌────────────────────────────────────────────────────────┐ │ OpenCode + 文件系统 │ ├────────────────────────────────────────────────────────┤ │ │ │ 输入 ──────────────────────────────────→ 输出 │ │ ▲ │ │ │ │ │ ▼ ▼ │ │ │ ┌─────────────────┐ ┌──────────────┐ │ │ │ │ 上下文窗口 │ │ 文件系统 │ │ │ │ │ （工作记忆） │ │ （持久化） │ │ │ │ └─────────────────┘ └──────────────┘ │ │ │ │ │ │ └──────────── @ 引用 ──────────────────┘ │ │ │ │ 优势： │ │ - 工作成果持久保存 │ │ - 可以引用历史内容 │ │ - 支持跨会话协作 │ │ - 结合 Git 进行版本控制 │ │ │ └────────────────────────────────────────────────────────┘文件系统在 OpenCode 中的四大价值
价值 说明 技术实现 持久化 工作成果保存在本地磁盘 write/edit 工具写入文件 结构化 用目录层级组织不同类型内容 项目目录设计 可引用 将历史内容注入当前上下文 @ 引用机制 可追踪 跟踪修改历史，支持回滚 Git 集成 项目目录结构设计原则
通用项目结构：
project-root/ ├── .opencode/ # OpenCode 配置目录 │ ├── agent/ # Agent 配置 │ │ └── research-assistant.md │ ├── skill/ # Skill 定义 │ │ └── data-analysis/ │ │ └── SKILL.md │ └── command/ # 自定义命令 │ └── analyze.md │ ├── input/ # 输入材料（只读） │ ├── raw-data/ # 原始数据 │ ├── references/ # 参考文献 │ └── requirements/ # 需求文档 │ ├── working/ # 工作中间产物 │ ├── drafts/ # 草稿 │ ├── notes/ # 笔记 │ └── experiments/ # 实验性内容 │ ├── output/ # 最终产出物 │ ├── reports/ # 报告 │ ├── code/ # 代码 │ └── docs/ # 文档 │ ├── assets/ # 可复用资源 │ ├── templates/ # 模板 │ ├── glossary/ # 术语表 │ └── examples/ # 示例 │ ├── AGENTS.md # 项目级 Agent 配置（始终加载） └── .gitignore # Git 忽略配置设计原则：
原则 说明 示例 输入输出分离 原始材料和产出物分开存放 input/vsoutput/工作区隔离 中间产物不污染最终输出 working/目录资源复用 可复用的内容集中管理 assets/目录配置集中 OpenCode 配置统一放置 .opencode/目录📊 场景示例
场景一：学术研究项目
research-project/ ├── .opencode/ │ └── agent/ │ └── academic-writer.md # 学术写作 Agent ├── literature/ # 文献资料 │ ├── papers/ # 原始论文 PDF │ ├── notes/ # 阅读笔记 │ └── bibliography.bib # 参考文献库 ├── data/ # 研究数据 │ ├── raw/ # 原始数据 │ ├── processed/ # 处理后数据 │ └── analysis/ # 分析结果 ├── manuscript/ # 论文稿件 │ ├── outline.md # 论文大纲 │ ├── chapters/ # 各章节 │ │ ├── 01-introduction.md │ │ ├── 02-literature-review.md │ │ └── ... │ └── figures/ # 图表 ├── assets/ │ ├── templates/ # 论文模板 │ └── glossary.md # 术语表 └── AGENTS.md # 项目规范场景二：软件开发项目
software-project/ ├── .opencode/ # OpenCode 核心配置目录 (AI 增强目录) │ ├── agent/ # 智能体定义目录 │ │ ├── code-reviewer.md # 代码审查 Agent 配置文件 │ │ └── doc-writer.md # 文档编写 Agent 配置文件 │ └── skill/ # 技能库 (Skills) │ └── api-design/ # API 设计相关技能 │ └── SKILL.md # API 设计规范与指令 ├── src/ # 源代码目录 ├── tests/ # 测试代码目录 ├── docs/ # 项目文档目录 │ ├── api/ # 接口文档 (API Reference) │ ├── architecture/ # 架构设计文档 │ └── guides/ # 开发者/用户使用指南 ├── assets/ # 静态资源与规范资产 │ ├── coding-standards.md # 团队编码规范 │ └── templates/ # 各类代码或文档模板 └── AGENTS.md # 项目 Agent 规范总览与说明场景三：数据分析项目
analysis-project/ ├── .opencode/ │ └── skill/ │ └── sql-analysis/ │ ├── SKILL.md # SQL 分析技能 │ └── references/ │ ├── tables.md # 表结构 │ └── metrics.md # 指标定义 ├── data/ │ ├── sources/ # 数据源描述 │ └── exports/ # 导出数据 ├── queries/ # SQL 查询 │ ├── exploration/ # 探索性查询 │ └── production/ # 生产查询 ├── reports/ # 分析报告 │ ├── weekly/ # 周报 │ └── monthly/ # 月报 ├── assets/ │ └── chart-templates/ # 图表模板 └── AGENTS.md # 项目规范✅ 技术要点总结
- 文件系统实现持久化——工作成果不会随对话结束而消失
- 目录结构实现组织——不同类型的内容有清晰的归属
- @ 引用实现复用——历史内容可以轻松注入当前上下文
- Git 实现版本控制——支持追踪修改、对比版本、回滚操作
- 配置与内容分离——
.opencode/目录集中管理所有配置
第二层：上下文管理
本层目标：掌握控制 AI "看到什么" 的技术，实现精确的上下文管理。
2.1 @ 引用机制
💡 一句话：@ 引用让你精确控制 AI "看到什么"——将文件内容注入上下文，实现知识的即时调用。
🔬 技术原理
@ 引用的工作方式
当你在输入中使用
@文件路径时，OpenCode 会执行以下操作：你的输入： "@术语表.md 请按照术语表翻译这段文字：Machine Learning is..." ┌─────────────────────────────────┐ │ OpenCode 处理流程 │ └─────────────────────────────────┘ │ ┌───────────────────────────┼───────────────────────────┐ │ │ │ ▼ ▼ ▼ 识别 @ 引用 读取文件内容 构造完整提示词 "@术语表.md" "Machine Learning: 机器学习 "术语表.md 的内容: Neural Network: 神经网络 [完整内容] ..." 请按照术语表翻译..." │ ▼ ┌─────────────────────────────────┐ │ 发送给 AI（包含文件内容） │ └─────────────────────────────────┘引用类型详解
引用类型 语法 说明 注意事项 单文件引用 @file.md引用单个文件的完整内容 大文件会消耗大量上下文 多文件引用 @file1.md @file2.md同时引用多个文件 按顺序注入 目录引用 @src/引用整个目录的文件列表 慎用，可能内容过多 相对路径 @./docs/guide.md相对于当前工作目录 常用方式 绝对路径 @/home/user/file.md绝对路径引用 不推荐，降低可移植性 引用的技术细节
引用解析规则：
- @ 后面紧跟文件路径（无空格）
- 路径可以包含目录层级
- 支持相对路径和绝对路径
- 文件内容会被完整读取并注入
引用的上下文成本：
引用的文件内容会直接占用上下文窗口空间 示例： - 术语表.md（1KB）→ 约 250 tokens - 代码文件（10KB）→ 约 2500 tokens - 长文档（100KB）→ 约 25000 tokens ⚠️ 建议： - 引用前估算文件大小 - 大文件考虑只引用相关部分 - 使用渐进式披露策略📊 场景示例
场景一：学术翻译（术语一致性）
目录结构： translation-project/ ├── glossary.md # 术语表 ├── source/ │ └── paper.md # 原文 └── output/ └── translated.md # 译文 使用方式： @glossary.md @source/paper.md 请翻译这篇论文，要求： 1. 严格按照术语表中的译法 2. 保持原文的段落结构 3. 专有名词首次出现时标注原文术语表示例（
glossary.md）：# 机器学习术语表 | English | 中文 | 备注 | |---------|------|------| | Machine Learning | 机器学习 | | | Neural Network | 神经网络 | | | Deep Learning | 深度学习 | | | Gradient Descent | 梯度下降 | | | Overfitting | 过拟合 | | | Regularization | 正则化 | | | Backpropagation | 反向传播 | | | Epoch | 训练轮次 | 不译为"时代" | | Batch | 批次 | | | Learning Rate | 学习率 | |场景二：代码审查（规范遵循）
目录结构： project/ ├── .opencode/ │ └── coding-standards.md # 编码规范 ├── src/ │ └── feature.ts # 待审查代码 └── ... 使用方式： @.opencode/coding-standards.md @src/feature.ts 请审查这段代码，检查： 1. 是否符合编码规范 2. 潜在的 bug 和安全问题 3. 性能优化建议场景三：论文写作（基于大纲）
目录结构： thesis/ ├── outline.md # 论文大纲 ├── references.md # 参考文献要点 └── chapters/ └── chapter-2.md # 待写章节 使用方式： @outline.md @references.md 请根据大纲撰写第二章"文献综述"，要求： 1. 覆盖大纲中列出的所有主题 2. 引用 references.md 中的核心观点 3. 保持学术写作风格 保存到 chapters/chapter-2.md场景四：数据分析（表结构引用）
目录结构： analysis/ ```text analysis/ ├── schema/ │ ├── users.md # 用户表结构 │ ├── orders.md # 订单表结构 │ └── products.md # 产品表结构 └── queries/ └── monthly-revenue.sql # 月收入查询 使用方式： @schema/users.md @schema/orders.md 请写一个 SQL 查询，统计每个用户的月度消费总额，要求： 1. 只统计已完成的订单 2. 按用户 ID 和月份分组 3. 按消费金额降序排列🔧 高级用法
动态引用（结合命令模板）
在 Command 模板中使用 @ 引用：
# .opencode/command/review.md --- description: 代码审查 --- @.opencode/coding-standards.md @$1 请审查上述代码文件。使用：
/review src/feature.ts条件引用（AI 自主决定）
我需要分析这个数据，你可以： - 用 @schema/users.md 了解用户表结构 - 用 @schema/orders.md 了解订单表结构 请先判断需要哪些表，再读取对应的 schema。✅ 技术要点总结
- @ 引用将文件内容注入上下文——AI 能"看到"文件内容
- 引用会消耗上下文空间——大文件需要谨慎引用
- 引用是即时的——每次对话都需要重新引用
- 引用路径相对于工作目录——使用相对路径更可移植
- 可以同时引用多个文件——用空格分隔多个 @ 引用
2.2 渐进式披露（Progressive Disclosure）
💡 一句话：不要一次性加载所有信息——按需逐层披露，保持 AI 注意力集中，这是上下文管理的核心策略。
🔬 技术原理
问题回顾：为什么需要渐进式披露？
在 1.1 节我们学到：上下文越多，AI 表现往往越差（注意力分散问题）。
渐进式披露是解决这个问题的核心策略。
渐进式披露的定义
"渐进式披露是一种将添加到上下文窗口的内容限制在最小必要量的实践，并随着需要逐步添加更多细节。"
核心思想：像组织一本手册一样组织信息：
目录（始终可见） │ ├── 告诉读者这本书有什么 └── 帮助读者决定是否需要阅读 │ ▼ （如果需要） 章节内容（按需阅读） │ ├── 核心概念和流程 └── 关键规则和逻辑 │ ▼ （如果需要更多细节） 附录/参考资料（查阅式使用） │ ├── 完整规范 ├── 详细示例 └── 边缘情况处理三层渐进式披露架构
┌─────────────────────────────────────────────────────────────────┐ │ 第一层：元信息（约 100 词） │ │ ────────────────────────────────────────────────────────────── │ │ • 始终存在于上下文中 │ │ • 包含：名称、描述、触发条件 │ │ • 目的：帮助 AI 判断"是否需要加载这个知识" │ │ │ │ 示例： │ │ name: sql-analysis │ │ description: 用于业务数据分析，提供表结构和查询模式 │ └─────────────────────────────────────────────────────────────────┘ │ │ 任务匹配时加载 ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 第二层：核心指令（约 300-500 词） │ │ ────────────────────────────────────────────────────────────── │ │ • 任务匹配时加载到上下文 │ │ • 包含：工作流程、关键规则、决策逻辑 │ │ • 目的：指导 AI 完成任务的主要框架 │ │ │ │ 示例：SKILL.md 正文 │ │ - 工作流程：明确需求 → 选择数据源 → 应用过滤器 → 验证结果 │ │ - 必须规则：排除测试账户、只用完整周期 │ └─────────────────────────────────────────────────────────────────┘ │ │ 需要细节时读取 ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 第三层：详细文档（按需读取） │ │ ────────────────────────────────────────────────────────────── │ │ • 仅在需要具体细节时通过 read 工具加载 │ │ • 包含：完整规范、详细示例、边缘情况 │ │ • 目的：提供任务执行所需的具体信息 │ │ │ │ 示例：references/ 目录 │ │ - tables.md：所有表的详细结构 │ │ - examples.md：常用查询示例 │ │ - edge-cases.md：特殊情况处理 │ └─────────────────────────────────────────────────────────────────┘为什么三层结构有效？
层级 上下文成本 信息类型 加载时机 第一层 极低（~100 tokens） 元信息 始终 第二层 中等（~500-1000 tokens） 核心指令 任务匹配 第三层 按需（可能很大） 详细文档 显式读取 关键洞察：
- 第一层成本固定且极低——即使有 100 个 Skill，元信息总共也只占 ~10K tokens
- 第二层按需加载——只有匹配的 Skill 才会加载核心指令
- 第三层显式读取——AI 需要时才通过 read 工具获取，避免预加载
📊 场景示例
场景一：数据分析 Skill
错误做法（一次性加载所有信息）：
把所有表结构、所有查询示例、所有业务规则全部写在一个文件里， 每次数据分析任务都加载这个 50KB 的文件。 问题： - 上下文迅速被填满 - AI 注意力被无关表结构分散 - 可能遗漏关键的过滤规则正确做法（三层渐进式披露）：
第一层（始终可见）： --- name: sql-analysis description: | 用于业务数据分析：收入、用户、产品指标。 提供表结构、计算公式、标准过滤器。 --- 第二层（任务匹配时加载）： # SQL 分析技能 ## 工作流程 1. 明确分析目标 2. 选择正确的数据表 3. 应用标准过滤器 4. 验证结果合理性 ## 必须遵守的规则 - 排除测试账户：WHERE account != 'Test' - 只用完整周期 ## 数据表速查 | 分析类型 | 推荐表 | 详细结构 | |---------|-------|---------| | 收入分析 | monthly_revenue | → references/revenue.md | | 用户分析 | user_metrics | → references/users.md | | 产品分析 | product_usage | → references/products.md | 第三层（需要时读取）： references/ ├── revenue.md # 收入相关表的完整结构和示例查询 ├── users.md # 用户相关表的完整结构和示例查询 └── products.md # 产品相关表的完整结构和示例查询实际运行流程：
用户：帮我分析上季度的收入趋势 AI 处理流程： 1. 检查可用 Skill → 发现 sql-analysis 匹配 2. 加载 SKILL.md 核心指令 → 了解工作流程和必须规则 3. 判断需要收入表结构 → read references/revenue.md 4. 编写查询，应用必须规则 5. 返回结果场景二：学术写作 Skill
三层结构： 第一层： name: academic-writing description: 学术论文写作辅助，提供结构模板、引用格式、学术语言规范。 第二层（SKILL.md）： # 学术写作技能 ## 论文结构模板 - Introduction → Literature Review → Methodology → Results → Discussion → Conclusion ## 关键规则 - 使用 APA 7th 引用格式 - 避免第一人称（使用被动语态） - 每个论点需要引用支撑 ## 详细参考 - 引用格式详解 → references/citation-guide.md - 学术措辞词库 → references/academic-phrases.md - 各章节模板 → references/templates/ 第三层（references/）： ├── citation-guide.md # APA 格式完整指南 ├── academic-phrases.md # 学术措辞词库 └── templates/ ├── introduction.md # 引言模板 ├── methodology.md # 方法论模板 └── discussion.md # 讨论模板场景三：代码审查 Skill
三层结构： 第一层： name: code-review description: 代码审查辅助，检查规范遵循、安全漏洞、性能问题、可维护性。 第二层（SKILL.md）： # 代码审查技能 ## 审查清单 1. 规范检查：命名、格式、注释 2. 安全检查：注入、认证、数据暴露 3. 性能检查：算法复杂度、资源使用 4. 可维护性：模块化、测试覆盖 ## 严重程度分级 - Critical：必须修复 - Major：应该修复 - Minor：建议修复 - Info：信息提示 ## 详细参考 - 安全漏洞模式 → references/security-patterns.md - 性能反模式 → references/performance-antipatterns.md - 语言特定规范 → references/languages/ 第三层（references/）： ├── security-patterns.md ├── performance-antipatterns.md └── languages/ ├── python.md ├── javascript.md └── typescript.md🔧 实现渐进式披露的技术手段
手段 适用层级 说明 Skill description 第一层 简洁描述触发条件 SKILL.md 正文 第二层 核心工作流程和规则 references/ 目录 第三层 详细文档，按需读取 @ 引用 任意层 显式将内容注入上下文 AI 自主读取 第三层 AI 判断需要时自行调用 read ✅ 技术要点总结
- 信息分层是核心——区分"必须知道"、"可能需要"、"细节参考"
- 元信息成本极低——可以有很多 Skill 而不会撑爆上下文
- 按需加载是关键——只在任务需要时才加载相关内容
- 引用而非内联——详细内容放在独立文件，通过路径引用
- AI 可以自主获取——第三层内容可以由 AI 判断后自行读取
第三层：持久化与复用
本层目标：掌握将知识和工作流固化为可复用配置的技术，实现"一次配置，永久生效"。
3.1 Agent 配置
💡 一句话：Agent 配置让你"训练"一个专属 AI 人格——定义 AI 是谁、如何行为、遵循什么规范。
🔬 技术原理
Agent 的本质
Agent 不是一个独立的程序，而是一组持久化的指令集，它定义了：
维度 说明 示例 角色定位 AI 扮演什么角色 "你是资深代码审查员" 行为规范 AI 应该如何行动 "先分析再给建议" 输出风格 AI 的输出格式和语气 "使用 Markdown 表格，语气严谨" 约束条件 AI 不能做什么 "禁止编造参考文献" 工具权限 AI 可以使用哪些工具 "只允许读取，不允许修改" Agent 配置的存储位置
优先级（高 → 低）： 项目级配置（当前项目专用） .opencode/agent/*.md │ ├── 同名时覆盖全局配置 └── 适用于项目特定的 Agent ↓ 全局配置（所有项目共用） ~/.config/opencode/agent/*.md │ └── 适用于通用的、跨项目的 AgentAgent 配置文件格式
完整格式：
--- # ===== 必需字段 ===== name: research-assistant # Agent 标识符 description: 学术研究助手，专注于文献分析和论文写作 # 功能描述（显示在选择菜单中） # ===== 可选字段 ===== mode: subagent # primary（Tab切换）或 subagent（@调用） temperature: 0.3 # 0.0-1.0，越低越确定性，越高越有创意 model: anthropic/claude-sonnet-4 # 指定使用的模型 # 权限控制 permission: edit: ask # 编辑文件前需确认 bash: "git *": allow # 允许 git 命令 "*": deny # 禁止其他命令 # 工具控制 tools: skill: false # 禁用 Skill 工具 --- # 正文：Agent 的详细指令 ## 角色定位 你是一位资深的学术研究助手，具有以下专长： - 文献综述和分析 - 学术写作指导 - 引用格式规范 ## 工作原则 1. **严谨性优先**：所有观点必须有依据 2. **结构化表达**：使用清晰的层次结构 3. **主动确认**：不确定时先询问 ## 输出规范 - 使用 APA 7th 引用格式 - 保持学术语言风格 - 重要术语首次出现时标注英文原文 ## 禁止行为 - ❌ 编造参考文献 - ❌ 使用非学术化表达 - ❌ 给出没有依据的结论Frontmatter 字段详解
字段 类型 必需 说明 示例 namestring ✅ Agent 标识符，用于调用 research-assistantdescriptionstring ✅ 功能描述，显示在菜单中 学术研究助手modestring ❌ primary（Tab切换）或subagent（@调用）subagenttemperaturenumber ❌ 0.0-1.0，控制输出随机性 0.3modelstring ❌ 覆盖默认模型 anthropic/claude-opus-4-5permissionobject ❌ 工具权限控制 见下方 toolsobject ❌ 工具开关控制 { skill: false }hiddenboolean ❌ 是否在菜单中隐藏 truecolorstring ❌ 显示颜色 #FF5733permission 字段详解：
permission: # 工具级别权限 edit: ask # 编辑前确认 write: allow # 允许写入 bash: deny # 禁止执行命令 # 命令模式匹配 bash: "git *": allow # 允许 git 相关命令 "npm test": allow # 允许运行测试 "*": deny # 禁止其他命令 # Skill 权限 skill: "internal-*": deny # 禁止内部 Skill "*": allow # 允许其他 SkillAgent vs AGENTS.md
特性 AGENTS.md Agent 配置文件 位置 项目根目录 .opencode/agent/加载时机 始终加载 按名称调用 调用方式 自动生效 @agent-name或 Tab 切换适用场景 项目通用规范 特定角色/任务 复用范围 单项目 可全局复用 选择原则：
- 项目通用规范（代码风格、Git 规范）→ 放在 AGENTS.md
- 特定角色任务（代码审查员、学术助手）→ 放在 Agent 配置文件
📊 场景示例
场景一：学术研究助手
# .opencode/agent/academic.md --- name: academic description: ���术研究助手，专注于文献分析、论文写作、引用管理 mode: subagent temperature: 0.2 # 低温度，更严谨 --- # 学术研究助手 ## 核心能力 - 文献综述与分析 - 论文结构设计 - 学术写作指导 - 引用格式规范（APA, MLA, Chicago） ## 工作流程 1. **理解需求**：确认研究问题、范围、要求 2. **结构规划**：设计论文/报告的整体结构 3. **内容生成**：按章节撰写，保持逻辑连贯 4. **格式检查**：确保引用格式、术语使用规范 ## 输出规范 - 使用 Markdown 格式 - 引用使用 [Author, Year] 格式 - 首次出现的术语标注英文原文 - 每个论点需有文献支撑 ## 严格禁止 - ❌ 编造不存在的参考文献 - ❌ 使用口语化表达 - ❌ 给出没有依据的断言使用方式：
@academic 请帮我分析这篇论文的研究方法部分，评估其有效性场景二：代码审查员
# .opencode/agent/reviewer.md --- name: reviewer description: 代码审查专家，检查规范、安全、性能、可维护性 mode: subagent temperature: 0.1 # 极低温度，非常确定性 permission: edit: deny # 只读，不修改代码 write: deny bash: "git diff*": allow "git log*": allow "*": deny --- # 代码审查专家 ## 审查维度 1. **规范性**：命名、格式、注释 2. **安全性**：注入、认证、数据暴露 3. **性能**：算法复杂度、资源使用 4. **可维护性**：模块化、测试覆盖、文档 ## 严重程度分级 | 级别 | 定义 | 处理要求 | |------|------|---------| | 🔴 Critical | 必须立即修复 | 阻塞合并 | | 🟠 Major | 应该修复 | 建议本次修复 | | 🟡 Minor | 建议修复 | 可以后续处理 | | 🔵 Info | 信息提示 | 仅供参考 | ## 输出格式 每个问题按以下格式报告： - 文件：[文件路径] - 行号：[行号] - 级别：[严重程度] - 问题：[问题描述] - 建议：[修复建议]场景三：数据分析师
# .opencode/agent/analyst.md --- name: analyst description: 数据分析专家，擅长 SQL 查询、统计分析、可视化建议 mode: subagent temperature: 0.3 --- # 数据分析专家 ## 核心能力 - SQL 查询编写和优化 - 统计分析和假设检验 - 数据可视化建议 - 业务指标解读 ## 工作流程 1. **理解业务问题**：确认分析目标和决策用途 2. **数据探索**：了解数据结构和质量 3. **分析设计**：确定分析方法和指标 4. **执行分析**：编写查询、计算结果 5. **结果解读**：将数据发现转化为业务洞察 ## 输出规范 - SQL 查询附带注释说明 - 数值结果标注单位和时间范围 - 给出置信度或不确定性说明 - 建议下一步分析方向 ## 数据处理原则 - 始终排除测试/异常数据 - 明确数据的时间范围 - 处理缺失值时说明策略🔧 高级配置技巧
嵌套目录组织
.opencode/agent/ ├── research/ │ ├── academic.md # 调用：@research/academic │ └── literature-review.md # 调用：@research/literature-review ├── development/ │ ├── reviewer.md # 调用：@development/reviewer │ └── architect.md # 调用：@development/architect └── analysis/ ├── sql-analyst.md # 调用：@analysis/sql-analyst └── statistician.md # 调用：@analysis/statisticianPrimary 模式 Agent
--- name: default-assistant description: 默认助手 mode: primary # Tab 可切换到此 Agent ---Primary vs Subagent：
primary：可以通过 Tab 键切换，作为主要交互 Agentsubagent：通过 @name 调用，作为特定任务的专家
✅ 技术要点总结
- Agent 是持久化的指令集—定义 AI 的角色、行为、约束
- 配置文件位置决定作用范围——项目级 vs 全局
- Frontmatter 定义元配置——name、description 必需，其他可选
- 正文定义详细指令——角色、工作流程、输出规范、禁止行为
- 权限控制实现安全边界——allow/ask/deny 三级权限
3.2 Skill 系统
💡 一句话：Skill 是按需加载的专业知识包——只在任务匹配时占用上下文，是渐进式披露的核心实现。
🔬 技术原理
Skill 与 Agent 的本质区别
维度 Agent Skill 定义 AI 的"人格" AI 的"知识" 回答的问题 "AI 是谁" "AI 知道什么" 加载时机 显式调用或始终加载 语义匹配时自动加载 上下文成本 固定消耗 按需消耗 典型内容 角色、风格、行为规范 专业知识、工作流程、规则 类比理解：
- Agent = 雇佣一个人（他有特定的性格和工作方式）
- Skill = 给这个人一本手册（需要时翻阅，不需要时不占用脑容量）
Skill 的目录结构
.opencode/skill/ └── sql-analysis/ # Skill 名称（目录名） ├── SKILL.md # 必需：主文件（必须大写） └── references/ # 可选：详细文档目录 ├── tables.md # 表结构 ├── metrics.md # 指标定义 └── examples.md # 查询示例存储位置：
项目级（当前项目） .opencode/skill/*/SKILL.md 全局级（所有项目） ~/.config/opencode/skill/*/SKILL.md Claude 兼容格式 .claude/skills/*/SKILL.md ~/.claude/skills/*/SKILL.mdSKILL.md 格式详解
--- # ===== 必需字段 ===== name: sql-analysis description: | 用于业务数据分析：收入趋势、用户分群、产品指标。 提供：表结构、计算公式、标准过滤器。 适用：需要写 SQL 分析业务数据时。 不适用：数据库管理、DDL 操作、性能调优。 # ===== 可选字段 ===== license: MIT compatibility: opencode >= 1.0 metadata: author: your-name version: 1.0.0 --- # SQL 分析技能 ## 工作流程 1. 明确分析目标和业务问题 2. 选择正确的数据表 3. 应用标准过滤器 4. 验证结果合理性 ## 必须遵守的规则 - 排除测试账户：`WHERE account != 'Test'` - 只使用完整周期的数据 - 金额字段使用 DECIMAL 类型 ## 数据表速查 | 分析类型 | 推荐表 | 详细结构 | |---------|-------|---------| | 收入分析 | monthly_revenue | → `references/tables.md#revenue` | | 用户分析 | user_metrics | → `references/tables.md#users` | | 产品分析 | product_usage | → `references/tables.md#products` | ## 常用指标公式 - ARR = MRR × 12 - 用户留存率 = 期末活跃用户 / 期初用户 × 100% - 环比增长 = (本期 - 上期) / 上期 × 100% ## 需要更多信息时 - 完整表结构 → 读取 `references/tables.md` - 复杂查询示例 → 读取 `references/examples.md` - 指标详细定义 → 读取 `references/metrics.md`description 是触发的关键
AI 通过语义理解（不是关键词匹配）判断是否需要加载某个 Skill。
description 四要素：
要素 说明 示例 具体能力 这个 Skill 能做什么 "用于业务数据分析" 提供资源 包含什么信息 "提供表结构、计算公式" 适用场景 什么时候应该触发 "适用：需要写 SQL 分析数据时" 边界限制 什么时候不应该触发 "不适用：数据库管理、DDL 操作" 对比示例：
❌ 差的 description：
description: 帮助处理数据问题：太模糊，AI 无法判断何时触发
✅ 好的 description：
description: | 用于业务数据分析：收入趋势、ARR 计算、客户分群、产品使用指标。 提供：公司数据仓库表结构、指标计算公式、标准过滤器、常用查询模板。 适用：需要写 SQL 查询分析业务数据、理解公司指标定义、查询数据仓库。 不适用：数据库管理、DDL 操作、性能调优、通用 SQL 教学。Skill 的发现和加载机制
┌─────────────────────────────────────────────────────────────┐ │ OpenCode 启动时 │ ├─────────────────────────────────────────────────────────────┤ │ │ │ 扫描所有 Skill 目录 │ │ │ │ │ ▼ │ │ 提取 name + description │ │ │ │ │ ▼ │ │ 汇总到 skill 工具的描述中 │ │ │ │ <available_skills> │ │ <skill> │ │ <name>sql-analysis</name> │ │ <description>用于业务数据分析...</description> │ │ </skill> │ │ <skill> │ │ <name>code-review</name> │ │ <description>代码审查...</description> │ │ </skill> │ │ </available_skills> │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ 用户发送消息 ▼ ┌─────────────────────────────────────────────────────────────┐ │ 用户消息："帮我分析上季度的收入趋势" │ ├─────────────────────────────────────────────────────────────┤ │ │ │ AI 语义匹配：这是数据分析任务 │ │ │ │ │ ▼ │ │ 匹配到 sql-analysis Skill │ │ │ │ │ ▼ │ │ 调用 skill({ name: "sql-analysis" }) │ │ │ │ │ ▼ │ │ SKILL.md 内容加载到上下文 │ │ │ └────────────────────────────────────────────────────────────┘📊 场景示例
场景一：SQL 数据分析 Skill
.opencode/skill/sql-analysis/ ├── SKILL.md └── references/ ├── tables.md ├── metrics.md └── examples.mdSKILL.md（第二层：核心指令）：
--- name: sql-analysis description: | 用于业务数据分析：收入、用户、产品指标。 提供：表结构、计算公式、过滤器。 适用：写 SQL 查询、理解业务指标。 不适用：数据库管理、DDL、性能调优。 --- # SQL 分析技能 ## 工作流程 1. 明确分析目标 2. 选择数据表（见下方速查） 3. 应用必需过滤器 4. 验证结果合理性 ## 必需过滤器 所有查询必须： - 排除测试账户：`WHERE account != 'Test'` - 只用完整周期：`WHERE month <= DATE_TRUNC(CURRENT_DATE(), MONTH)` ## 数据表速查 | 分析需求 | 推荐表 | 详情 | |---------|-------|------| | 收入/ARR | monthly_revenue | → references/tables.md | | 用户指标 | user_metrics | → references/tables.md | | 产品使用 | product_usage | → references/tables.md | ## 常用公式 - ARR = MRR × 12 - 留存率 = 期末活跃 / 期初用户 × 100%references/tables.md（第三层：详细文档）：
# 数据表详细结构 ## monthly_revenue 表 收入相关的月度汇总数据。 | 字段 | 类型 | 说明 | |-----|------|------| | account_id | STRING | 账户唯一标识 | | month | DATE | 月份（每月第一天） | | mrr | DECIMAL | 月度经常性收入 | | arr | DECIMAL | 年度经常性收入 | | segment | STRING | 客户分群（Enterprise/SMB/Startup） | | region | STRING | 地区 | ### 常用查询示例 #### 按分群统计月收入 \`\`\`sql SELECT segment, DATE_TRUNC(month, MONTH) as period, SUM(mrr) as total_mrr, COUNT(DISTINCT account_id) as account_count FROM monthly_revenue WHERE account_id != 'Test' AND month >= '2024-01-01' GROUP BY 1, 2 ORDER BY 2 DESC, 3 DESC \`\`\` ## user_metrics 表 ...（更多表结构）场景二：学术写作 Skill
.opencode/skill/academic-writing/ ├── SKILL.md └── references/ ├── citation-formats.md ├── academic-phrases.md └── templates/ ├── introduction.md └── methodology.mdSKILL.md：
--- name: academic-writing description: | 学术论文写作辅助：结构设计、学术表达、引用格式。 提供：论文模板、学术措辞库、引用格式指南。 适用：撰写学术论文、研究报告、文献综述。 不适用：博客文章、营销文案、非学术写作。 --- # 学术写作技能 ## 论文结构模板 标准学术论文结构： 1. Introduction（引言） 2. Literature Review（文献综述） 3. Methodology（研究方法） 4. Results（结果） 5. Discussion（讨论） 6. Conclusion（结论） ## 写作规范 - 使用第三人称或被动语态 - 避免口语化表达 - 每个论点需有文献支撑 - 术语首次出现标注英文 ## 引用格式 默认使用 APA 7th。其他格式见 → references/citation-formats.md ## 学术措辞 常用学术表达 → references/academic-phrases.md ## 各章节模板 - 引言模板 → references/templates/introduction.md - 方法论模板 → references/templates/methodology.md场景三：代码审查 Skill
.opencode/skill/code-review/ ├── SKILL.md └── references/ ├── security-patterns.md ├── performance-antipatterns.md └── languages/ ├── python.md ├── javascript.md └── typescript.md🔧 Skill 权限配置
在
opencode.json中配置 Skill 权限：{ "permission": { "skill": { "sql-analysis": "allow", // 直接加载 "internal-*": "deny", // 隐藏内部 Skill "experimental-*": "ask", // 加载前询问 "*": "allow" // 其他默认允许 } } }权限值 行为 allow匹配时直接加载 ask加载前询问用户确认 deny完全隐藏，AI 看不到 ✅ 技术要点总结
- Skill 是按需加载的知识包——只在语义匹配时占用上下文
- 三层结构实现渐进式披露——description → SKILL.md → references/
- description 决定触发——必须包含能力、资源、适用场景、边界
- SKILL.md 必须大写——这是格式要求
- references/ 按需读取——详细内容由 AI 判断后自行获取
3.3 Command 系统
💡 一句话：Command 把常用提示词模板化为斜杠命令——一次定义，重复使用，支持参数化和动态内容。
🔬 技术原理
Command 的本质
Command 是提示词模板，通过变量占位符实现参数化，让你可以用简短的命令触发复杂的提示词。
传统方式： 每次都要输入完整的提示词... Command 方式： /analyze 用户留存率 │ ▼ 自动展开为完整的提示词模板 + 参数Command 的存储位置
项目级（当前项目） .opencode/command/*.md 全局级（所有项目） ~/.config/opencode/command/*.mdCommand 文件格式
--- # ===== 可选配置 ===== description: 数据分析快捷命令 # 命令描述 agent: analyst # 指定使用的 Agent model: anthropic/claude-sonnet-4 # 指定模型 subtask: true # 作为子任务执行（不污染主上下文） --- # 正文：提示词模板 请分析以下指标： 指标名称：$ARGUMENTS 分析要求： 1. 定义和计算方式 2. 历史趋势 3. 影响因素 4. 优化建议参数系统
占位符 说明 示例命令 值 $ARGUMENTS全部参数（字符串） /analyze 用户留存率用户留存率$1第一个参数 /translate en zhen$2第二个参数 /translate en zhzh$3第三个参数 /process a b cc$n第 n 个参数 以此类推 示例：
# .opencode/command/translate.md --- description: 翻译文件 --- 请将 $1 翻译成 $2： @$1 要求： - 保持原文格式 - 专业术语参考 @glossary.md使用：
/translate paper.md 中文展开后：
请将 paper.md 翻译成 中文： [paper.md 的内容] 要求： - 保持原文格式 - 专业术语参考 [glossary.md 的内容]Shell 输出注入
使用
!`command`语法将 Shell 命令的输出注入模板：# .opencode/command/review-changes.md --- description: 审查最近的代码变更 --- 最近的 Git 提交： !`git log --oneline -10` 变更的文件： !`git diff --name-only HEAD~5` 请审查这些变更，检查： 1. 代码质量 2. 潜在问题 3. 改进建议使用：
/review-changesAI 会看到实际的 git log 和 diff 输出。
📊 场景示例
场景一：学术文献综述命令
# .opencode/command/review.md --- description: 快速文献综述 agent: academic --- 请对以下研究主题进行文献综述： 主题：$ARGUMENTS 要求： 1. 覆盖最近 5 年的主要研究进展 2. 按研究方向/方法分类组织 3. 指出当前研究的空白和争议 4. 使用 APA 格式标注引用 5. 总结未来研究方向 输出格式： ## 研究概述 ## 主要研究方向 ### 方向一 ### 方向二 ## 研究空白与争议 ## 未来研究建议 ## 参考文献使用：
/review 深度学习在医学影像诊断中的应用场景二：SQL 查询生成命令
# .opencode/command/query.md --- description: 生成 SQL 查询 --- 请生成一个 SQL 查询来分析：$ARGUMENTS 参考表结构： @.opencode/skill/sql-analysis/references/tables.md 要求： 1. 应用标准过滤器（排除测试账户） 2. 添加清晰的注释 3. 考虑查询性能 4. 提供结果解读建议使用：
/query 各客户分群的月度收入趋势场景三：代码审查命令
# .opencode/command/cr.md --- description: 代码审查 agent: reviewer --- 请审查以下代码变更： 变更概述： !`git diff --stat HEAD~1` 详细变更： !`git diff HEAD~1` 审查维度： 1. 代码规范性 2. 潜在 Bug 3. 安全问题 4. 性能影响 5. 可维护性 请按严重程度（Critical/Major/Minor/Info）分类报告问题。使用：
/cr（自动审查最近一次提交）场景四：项目状态报告命令
# .opencode/command/status.md --- description: 生成项目状态报告 subtask: true --- # 项目状态报告 ## Git 状态 !`git status` ## 最近提交 !`git log --oneline -5` ## 待办事项 !`grep -r "TODO\|FIXME" --include="*.py" --include="*.js" --include="*.ts" . 2>/dev/null | head -20` 请基于以上信息生成一份简洁的项目状态报告，包括： 1. 当前工作进度 2. 待处理事项 3. 建议的下一步行动使用：
/status🔧 高级配置
subtask 模式
当设置
subtask: true时，命令会作为子任务执行，不会污染主对话的上下文：--- description: 深度分析（独立上下文） subtask: true --- 请进行深度分析...适用场景：
- 耗时的分析任务
- 需要大量上下文的任务
- 不希望影响主对话的任务
结合 @ 引用
在命令模板中使用 @ 引用：
--- description: 按规范编写代码 --- @.opencode/coding-standards.md 请按照上述编码规范，实现以下功能： $ARGUMENTS嵌套目录组织
.opencode/command/ ├── research/ │ ├── review.md # /research/review │ └── analyze.md # /research/analyze ├── code/ │ ├── cr.md # /code/cr │ └── refactor.md # /code/refactor └── data/ ├── query.md # /data/query └── report.md # /data/report✅ 技术要点总结
- Command 是提示词模板——将常用提示词固化为可复用的命令
- 支持参数化——$ARGUMENTS、$1、$2 等占位符
- 支持 Shell 注入——
!`command`动态获取系统信息 - 支持 @ 引用——在模板中引用文件
- 可指定 Agent——用
agent:指定处理命令的 Agent - 支持子任务模式——
subtask: true隔离上下文
第四层：自动化与扩展
本层目标：掌握将 OpenCode 集成到自动化流程中的技术，以及扩展 AI 能力边界的方法。
4.1 权限控制
💡 一句话：权限控制是安全边界——精确定义 AI 能做什么、需要确认什么、绝对禁止什么。
🔬 技术原理
三级权限模型
权限值 行为 适用场景 allow 直接执行，无需确认 安全操作、高频操作 ask 执行前请求用户确认 敏感操作、有副作用的操作 deny 完全禁止，即使 AI 尝试也会被拒绝 危险操作、越权操作 权限配置层级
全局配置（opencode.json） │ └── 定义默认权限 项目配置（.opencode/opencode.json） │ └── 覆盖全局配置 Agent 配置（.opencode/agent/*.md） │ └── 覆盖项目配置（针对特定 Agent）配置格式
在 opencode.json 中配置：
{ "permission": { // 工具级别权限 "read": "allow", "edit": "ask", "write": "ask", "bash": "ask", // 命令模式匹配（针对 bash） "bash": { "git status": "allow", "git diff*": "allow", "git log*": "allow", "npm test": "allow", "npm run build": "allow", "rm *": "deny", "*": "ask" }, // Skill 权限 "skill": { "internal-*": "deny", "experimental-*": "ask", "*": "allow" } } }在 Agent 配置中覆盖：
# .opencode/agent/readonly-analyst.md --- name: readonly-analyst description: 只读数据分析师（不能修改任何文件） permission: edit: deny write: deny bash: "psql *": "allow" # 允许数据库查询 "*": "deny" # 禁止其他命令 ---📊 场景示例
场景一：代码审查（只读模式）
# Agent 配置 --- name: code-reviewer permission: read: allow glob: allow grep: allow edit: deny # 禁止修改 write: deny # 禁止创建 bash: "git diff*": allow # 允许查看差异 "git log*": allow # 允许查看历史 "git blame*": allow # 允许查看责任 "*": deny # 禁止其他 ---场景二：生产环境操作（严格确认）
// opencode.json { "permission": { "bash": { "kubectl *": "ask", // K8s 命令需确认 "docker *": "ask", // Docker 命令需确认 "ssh *": "deny", // 禁止 SSH "rm -rf *": "deny", // 禁止递归删除 "*": "ask" } } }场景三：教学演示（完全安全）
{ "permission": { "read": "allow", "glob": "allow", "grep": "allow", "list": "allow", "edit": "deny", "write": "deny", "bash": "deny" } }✅ 技术要点总结
- 三级权限：allow（直接执行）、ask（确认后执行）、deny（禁止）
- 支持模式匹配：使用通配符匹配命令
- 层级覆盖：Agent 配置 > 项目配置 > 全局配置
- 最小权限原则：默认限制，按需开放
4.2 CLI 自动化
💡 一句话：CLI 让 OpenCode 可以非交互运行——集成到脚本、定时任务、CI/CD 流水线中。
🔬 技术原理
核心命令
# 非交互运行 opencode run "你的提示词" # 指定工作目录 opencode --cwd /path/to/project run "..." # 使用特定 Agent opencode run "@code-reviewer 审查最近的提交" # 读取文件作为输入 opencode run "分析这个文件" < input.txt # 输出到文件 opencode run "生成报告" > report.md📊 场景示例
场景一：每日代码质量报告
#!/bin/bash # daily-report.sh cd /path/to/project opencode run " @code-reviewer 请生成今日代码质量报告： 最近的提交： $(git log --oneline --since='1 day ago') 变更统计： $(git diff --stat HEAD~10) 请分析： 1. 代码质量趋势 2. 潜在风险点 3. 改进建议 " > reports/$(date +%Y-%m-%d)-quality-report.md设置 cron 定时执行：
0 9 * * * /path/to/daily-report.sh场景二：CI/CD 集成
# .github/workflows/code-review.yml name: AI Code Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 - name: Run AI Code Review run: | opencode run " @code-reviewer 请审查这个 PR 的变更： $(git diff origin/main...HEAD) 请检查： 1. 代码规范 2. 潜在 Bug 3. 安全问题 4. 性能影响 " > review-comments.md - name: Post Review Comments uses: actions/github-script@v6 with: script: | const fs = require('fs'); const review = fs.readFileSync('review-comments.md', 'utf8'); github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body: review });场景三：批量文件处理
#!/bin/bash # batch-translate.sh for file in docs/en/*.md; do filename=$(basename "$file") opencode run " @translator 请将以下英文文档翻译成中文，保持 Markdown 格式： $(cat "$file") " > "docs/zh/${filename}" echo "已翻译: $filename" done✅ 技术要点总结
opencode run支持非交互执行- 可以使用 Shell 管道和重定向
- 可以集成到 CI/CD 流水线
- 支持定时任务自动化
4.3 MCP 协议（Model Context Protocol）
💡 一句话：MCP 让 AI 能调用外部工具和数据源——扩展 AI 的能力边界，连接真实世界的系统。
🔬 技术原理
什么是 MCP？
MCP（Model Context Protocol）是一个开放协议，让 AI 应用能够安全地连接到外部数据源和工具。
┌─────────────────────────────────────────────────────────────┐ │ OpenCode │ ├─────────────────────────────────────────────────────────────┤ │ │ │ │ ▼ │ │ MCP 客户端 │ │ │ │ │ ┌───────────────┼───────────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 数据库 │ │ API 服务 │ │ 文件系统 │ │ │ │ MCP 服务器│ │ MCP 服务器│ │ MCP 服务器│ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ PostgreSQL 外部 API 特殊文件格式 │ └─────────────────────────────────────────────────────────────┘配置格 `置 MCP 服务器：
{ "m": { "type": "local", "commannpx", "-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/db" } }, "github": { "type": "local", "command": ["npx", "-y", "@modelcontextprotocol/server-github "env": { "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" } }, "filesystemlocal", "command": ["npx", "-y", "@modelfilesystem"], "args": ["/path/to/allowed/directory"] } } }常用 MCP 服务器
服务器 功能 包名 PostgreSQL 数据库查询 @modelcontextprotocol/server-postgresGitHub 仓库操作 @modelcontextprotocol/server-githubFilesystem 文件操作 @modelcontextprotocol/server-filesystemBrave 网络搜索 @anthropic/mcp-server-brave-searchPuppeteer 网页自动化 @anthropic/mcp-server-puppeteer⚠️ 注意事项
根据官方文档：
"MCP 工具会自动可用，但会占用上工具多了会更容易顶到上下文上限。"
建议：
- 只启用必要的 MCP 服务器
- 使用
enabled: false临时禁用不需要的服务器 - 大型项目考虑按任务类型切换置
总结
- MCP 扩展 AI 能力边界——连接数据库、API、外部服务
- 工具自动可用——配 用
- 注意上下文成本——每个 MCP 服务器都会消耗上下文空间
- 安置——使用环境变量存储敏感信息
📊 本节课程小结
技术体系回顾
第一层：基础原理 ├── 上下文窗口：AI 的工作记忆，理解"为什么更多信而更差" ├── Agent 模式：Plan 思考，Build 执行，分离关注点 ├── 工具系统：rea/grep/bash，AI 与世接口 └── 文件系统：持久化、结构化、可引用、可追踪 第二层：上下文管理 ├── @ 引用机制：精确控制 AI "看到什么" └── 渐进式披露：按需加载，保持注意力集中 第三层：持久化与复用 ├── Agent化 AI 人格，一次配置永久生效 ├── Skill 系统：按需加载的专业知识包 └── Command 系复用的提示词模板 第四层：自动化与扩展：安全边界，allow/ask/deny ├── CLI 自动化：脚本化、流水线集成 └── MCP 协议：扩展 AI 能力边界 -
0 回复
歡迎留言回复交流。
Log in to reply.