┌─────────────────────────────────────────────────────────────────────────┐
│                        第四层：自动化与扩展                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                   │
│  │  CLI 自动化   │  │  MCP 协议    │  │  权限控制    │                   │
│  │  脚本化调用   │  │  外部工具集成 │  │  安全边界    │                   │
│  └──────────────┘  └──────────────┘  └──────────────┘                   │
├─────────────────────────────────────────────────────────────────────────┤
│                        第三层：持久化与复用                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐                   │
│  │  Agent 配置   │  │  Skill 系统  │  │  Command 系统│                   │
│  │  固化 AI 人格 │  │  专业知识包  │  │  快捷命令    │                   │
│  └──────────────┘  └──────────────┘  └──────────────┘                   │
├─────────────────────────────────────────────────────────────────────────┤
│                        第二层：上下文管理                                 │
│  ┌────────────────────────────┐  ┌────────────────────────────┐         │
│  │  @ 引用机制                  │  │  渐进式披露                 │         │
│  │  将外部信息精确注入上下文      │  │  按需加载，保持注意力集中    │         │
│  └───────────────────────────┘  └────────────────────────────┘         │
├─────────────────────────────────────────────────────────────────────────┤
│                        第一层：基础原理                                   │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐         │
│  │  上下文窗口 │  │  Agent 模式 │  │  工具系统  │  │  文件系统  │         │
│  │  注意力机制 │  │  Plan/Build│  │  读写搜索  │  │  持久化    │         │
│  └────────────┘  └────────────┘  └────────────┘  └────────────┘         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                    上下文窗口（Context Window）              │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 系统提示词（System Prompt）                          │    │
│  │ - OpenCode 的基础指令                               │    │
│  │ - Agent 配置内容                                    │    │
│  │ - 可用工具的定义                                    │    │
│  └─────────────────────────────────────────────────────┘    │
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 对话历史（Conversation History）                     │    │
│  │ - 之前的问答记录                                    │    │
│  │ - 工具调用和结果                                    │    │
│  └─────────────────────────────────────────────────────┘    │
│  ┌───────────────────────────────────────────────────┐    │
│  │ 当前输入（Current Input）                           │    │
│  │ - 你的提示词                                        │    │
│  │ - @ 引用的文件内容                                  │    │
│  └─────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────┤
│  容量上限：Claude 200K tokens / GPT-4.1 400K tokens         │
│  ⚠️ 注意：更大 ≠ 更好                                       │
└─────────────────────────────────────────────────────────────┘

复杂任务
    │
    ▼
┌─────────────────┐      ┌─────────────────┐
│   Plan 阶段      │  →   │   Build 阶段     │
│   - 分析需求     │      │   - 执行方案     │
│   - 探索方案     │      │   - 创建产物     │
│   - 确定结构     │      │   - 迭代修改     │
│   - 无副作用     │      │   - 持久化结果   │
└─────────────────┘      └─────────────────┘

Plan 阶段（可能需要 30 分钟讨论）
├── 讨论研究问题的界定
├── 确定论文的章节结构
├── 分析每章的核心论点
├── 评估论证逻辑的完整性
└── 确定需要的支撑材料

Build 阶段（基于 Plan 结果执行）
├── 创建论文目录结构
├── 撰写各章节初稿
├── 生成引用格式
├── 创建图表
└── 迭代修改润色

Plan 阶段
├── 分析需求和约束
├── 评估技术选型（数据库、框架、部署方式）
├── 设计模块划分和接口
├── 讨论扩展性和性能考量
└── 确定开发优先级

Build 阶段
├── 创建项目结构
├── 生成配置文件
├── 编写核心模块代码
├── 创建 API 接口
└── 编写测试用例

Plan 阶段
├── 明确分析目标和业务问题
├── 了解数据源和数据质量
├── 设计分析思路和指标定义
├── 确定可视化方案
└── 规划报告结构

Build 阶段
├── 编写数据查询脚本
├── 生成分析结果
├── 创建可视化图表
├── 撰写分析报告
└── 导出最终产物

你的请求
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│  AI 理解意图                                             │
│  "用户想要查找项目中所有包含 TODO 的 Python 文件"         │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│  AI 选择工具                                             │
│  "这是内容搜索任务 → 使用 grep 工具"                      │
│  "需要限定文件类型 → 使用 type 参数"                      │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│  工具执行                                                │
│  grep(pattern="TODO", type="py")                        │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│  结果返回                                                │
│  找到 15 个匹配文件...                                   │
└─────────────────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────────────────┐
│  AI 处理结果，生成回复                                    │
│  （可能需要多轮工具调用）                                 │
└─────────────────────────────────────────────────────────┘

read 工具的行为
├── 默认读取前 2000 行
├── 可以用 offset + limit 读取特定范围
├── 超过 2000 字符的行会被截断
└── 返回带行号的内容（方便后续 edit）

glob 工具行为
├── 使用 glob 模式匹配（如 **/*.py）
├── 结果按文件修改时间排序（最新的在前）
├── 最多返回 100 条（超过会被截断）
└── 比 grep 更快（不读取文件内容）

grep 工具的行为
├── 使用正则表达式匹配内容
├── 基于 ripgrep（非常快）
├── 默认遵守 .gitignore 规则
└── 可以用 .ignore 文件覆盖忽略规则

write 工具的行为
├── 如果文件存在，会完全覆盖
├── 对已存在的文件，必须先 read（安全机制）
├── 会自动创建不存在的父目录
└── 适合创建新文件或完全重写

edit 工具的行为
├── 基于"查找-替换"机制
├── old_string 必须在文件中唯一匹配
├── 如果匹配多处，需要提供更多上下文使其唯一
├── replace_all=true 可以替换所有匹配
└── 适合精确修改，保持文件其他部分不变

bash 工具的行为
├── 在持久化的 Shell 会话中执行 ├── 默认超时 120000ms（2 分钟）
├── 可以用 timeout 参数调整（最大 10 分钟）
├── workdir 参数指定工作目录（避免 cd &&） ├── 输出超过 30000 字符会被截断
└── 支持后台运行（run_in_background=true）

步骤 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")
目的：确认修改没有破坏功能

┌────────────────────────────────────────────────────────┐
│                    网页版 AI 对话                       │
├────────────────────────────────────────────────────────┤
│                                                        │
│    输入 ──────────────────────────────────→ 输出       │
│                        │                               │
│                        ▼                               │
│              ┌─────────────────┐                       │
│              │   内存（临时）   │                       │
│              │   关闭即消失    │                       │
│              └─────────────────┘                       │
│                                                        │
│    问题：                                              │
│    - 无法保存中间成果                                  │
│    - 无法引用历史内容                                  │
│    - 无法跨会话协作                                    │
│    - 每次都从零开始                                    │
│                                                        │
└────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────┐
│                 OpenCode + 文件系统                     │
├────────────────────────────────────────────────────────┤
│                                                        │
│    输入 ──────────────────────────────────→ 输出       │
│      ▲                 │                    │          │
│      │                 ▼                    ▼          │
│      │       ┌─────────────────┐    ┌──────────────┐   │
│      │       │   上下文窗口    │    │   文件系统   │   │
│      │       │   （工作记忆）  │    │   （持久化） │   │
│      │       └─────────────────┘    └──────────────┘   │
│      │                                      │          │
│      └──────────── @ 引用 ──────────────────┘          │
│                                                        │
│    优势：                                              │
│    - 工作成果持久保存                                  │
│    - 可以引用历史内容                                  │
│    - 支持跨会话协作                                    │
│    - 结合 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 忽略配置

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                           # 项目规范

你的输入：
"@术语表.md 请按照术语表翻译这段文字：Machine Learning is..." 
                    ┌─────────────────────────────────┐
                    │       OpenCode 处理流程          │
                    └─────────────────────────────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
        ▼                           ▼                           ▼
   识别 @ 引用              读取文件内容               构造完整提示词
   "@术语表.md"            "Machine Learning: 机器学习  "术语表.md 的内容:
                           Neural Network: 神经网络     [完整内容]
                           ..."                        
                                                       请按照术语表翻译..."                                     │
                                    ▼
                    ┌─────────────────────────────────┐
                    │    发送给 AI（包含文件内容）      │
                    └─────────────────────────────────┘

引用的文件内容会直接占用上下文窗口空间

示例：
- 术语表.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. 专有名词首次出现时标注原文

# 机器学习术语表 
| 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. 按消费金额降序排列

# .opencode/command/review.md ---
description: 代码审查
--- 
@.opencode/coding-standards.md @$1

请审查上述代码文件。

我需要分析这个数据，你可以：
- 用 @schema/users.md 了解用户表结构
- 用 @schema/orders.md 了解订单表结构
 请先判断需要哪些表，再读取对应的 schema。

目录（始终可见）
    │
    ├── 告诉读者这本书有什么
    └── 帮助读者决定是否需要阅读
    
          │
          ▼  （如果需要）
          
章节内容（按需阅读）
    │
    ├── 核心概念和流程
    └── 关键规则和逻辑
    
          │
          ▼  （如果需要更多细节）
          
附录/参考资料（查阅式使用）
    │
    ├── 完整规范
    ├── 详细示例
    └── 边缘情况处理

┌─────────────────────────────────────────────────────────────────┐
│  第一层：元信息（约 100 词）                                      │
│  ──────────────────────────────────────────────────────────────  │
│  • 始终存在于上下文中                                            │
│  • 包含：名称、描述、触发条件                                     │
│  • 目的：帮助 AI 判断"是否需要加载这个知识"                        │
│                                                                 │
│  示例：                                                          │
│  name: sql-analysis                                             │
│  description: 用于业务数据分析，提供表结构和查询模式               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ 任务匹配时加载
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  第二层：核心指令（约 300-500 词）                                 │
│  ──────────────────────────────────────────────────────────────  │
│  • 任务匹配时加载到上下文                                         │
│  • 包含：工作流程、关键规则、决策逻辑                              │
│  • 目的：指导 AI 完成任务的主要框架                               │
│                                                                 │
│  示例：SKILL.md 正文                                             │
│  - 工作流程：明确需求 → 选择数据源 → 应用过滤器 → 验证结果          │
│  - 必须规则：排除测试账户、只用完整周期                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ 需要细节时读取
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  第三层：详细文档（按需读取）                                      │
│  ──────────────────────────────────────────────────────────────  │
│  • 仅在需要具体细节时通过 read 工具加载                            │
│  • 包含：完整规范、详细示例、边缘情况                              │
│  • 目的：提供任务执行所需的具体信息                               │
│                                                                 │
│  示例：references/ 目录                                          │
│  - tables.md：所有表的详细结构                                    │
│  - examples.md：常用查询示例                                      │
│  - edge-cases.md：特殊情况处理                                    │
└─────────────────────────────────────────────────────────────────┘

把所有表结构、所有查询示例、所有业务规则全部写在一个文件里，
每次数据分析任务都加载这个 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. 返回结果

三层结构：

第一层：
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        # 讨论模板

三层结构：

第一层：
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

优先级（高 → 低）：

项目级配置（当前项目专用）
.opencode/agent/*.md
    │
    ├── 同名时覆盖全局配置
    └── 适用于项目特定的 Agent
    
          ↓
          
全局配置（所有项目共用）
~/.config/opencode/agent/*.md
    │
    └── 适用于通用的、跨项目的 Agent

---
# ===== 必需字段 =====
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 引用格式
- 保持学术语言风格
- 重要术语首次出现时标注英文原文

## 禁止行为
- ❌ 编造参考文献
- ❌ 使用非学术化表达
- ❌ 给出没有依据的结论

permission:
  # 工具级别权限
  edit: ask              # 编辑前确认
  write: allow           # 允许写入
  bash: deny             # 禁止执行命令
  
  # 命令模式匹配
  bash:
    "git *": allow       # 允许 git 相关命令
    "npm test": allow    # 允许运行测试
    "*": deny            # 禁止其他命令
  
  # Skill 权限
  skill:
    "internal-*": deny   # 禁止内部 Skill
    "*": allow           # 允许其他 Skill

# .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/statistician

---
name: default-assistant
description: 默认助手
mode: primary                 # Tab 可切换到此 Agent
---

.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.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: 帮助处理数据 

description: |
  用于业务数据分析：收入趋势、ARR 计算、客户分群、产品使用指标。
  提供：公司数据仓库表结构、指标计算公式、标准过滤器、常用查询模板。
  适用：需要写 SQL 查询分析业务数据、理解公司指标定义、查询数据仓库。
  不适用：数据库管理、DDL 操作、性能调优、通用 SQL 教学。

┌─────────────────────────────────────────────────────────────┐
│  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 内容加载到上下文                                   │
│                                                             │
└────────────────────────────────────────────────────────────┘

.opencode/skill/sql-analysis/
├── SKILL.md
└── references/
    ├── tables.md
    ├── metrics.md
    └── examples.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%

# 数据表详细结构 
## 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 表
...（更多表结构）

.opencode/skill/academic-writing/
├── SKILL.md
└── references/
    ├── citation-formats.md
    ├── academic-phrases.md
    └── templates/
        ├── introduction.md
        └── methodology.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

.opencode/skill/code-review/
├── SKILL.md
└── references/
    ├── security-patterns.md
    ├── performance-antipatterns.md
    └── languages/
        ├── python.md
        ├── javascript.md
        └── typescript.md

{
  "permission": {
    "skill": {
      "sql-analysis": "allow",       // 直接加载
      "internal-*": "deny",          // 隐藏内部 Skill
      "experimental-*": "ask",       // 加载前询问
      "*": "allow"                   // 其他默认允许
    }
  }
}

传统方式：
每次都要输入完整的提示词... 
Command 方式：
/analyze 用户留存率

        │
        ▼
        
自动展开为完整的提示词模板 + 参数

项目级（当前项目）
.opencode/command/*.md

全局级（所有项目）
~/.config/opencode/command/*.md

---
# ===== 可选配置 ===== description: 数据分析快捷命令        # 命令描述
agent: analyst                       # 指定使用的 Agent
model: anthropic/claude-sonnet-4     # 指定模型
subtask: true                        # 作为子任务执行（不污染主上下文）
--- 
# 正文：提示词模板 
请分析以下指标：

指标名称：$ARGUMENTS

分析要求：
1. 定义和计算方式
2. 历史趋势
3. 影响因素
4. 优化建议

# .opencode/command/translate.md ---
description: 翻译文件
--- 
请将 $1 翻译成 $2：

@$1

要求：
- 保持原文格式
- 专业术语参考 @glossary.md

请将 paper.md 翻译成 中文：

[paper.md 的内容]

要求：
- 保持原文格式
- 专业术语参考 [glossary.md 的内容]

# .opencode/command/review-changes.md ---
description: 审查最近的代码变更
--- 
最近的 Git 提交：
!`git log --oneline -10` 
变更的文件：
!`git diff --name-only HEAD~5` 
请审查这些变更，检查：
1. 代码质量
2. 潜在问题
3. 改进建议

# .opencode/command/review.md ---
description: 快速文献综述
agent: academic
--- 
请对以下研究主题进行文献综述：

主题：$ARGUMENTS

要求：
1. 覆盖最近 5 年的主要研究进展
2. 按研究方向/方法分类组织
3. 指出当前研究的空白和争议
4. 使用 APA 格式标注引用
5. 总结未来研究方向

输出格式：
## 研究概述 ## 主要研究方向 ### 方向一 ### 方向二 ## 研究空白与争议 ## 未来研究建议 ## 参考文献 

# .opencode/command/query.md ---
description: 生成 SQL 查询
--- 
请生成一个 SQL 查询来分析：$ARGUMENTS

参考表结构：
@.opencode/skill/sql-analysis/references/tables.md

要求：
1. 应用标准过滤器（排除测试账户）
2. 添加清晰的注释
3. 考虑查询性能
4. 提供结果解读建议

# .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）分类报告问题。

# .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. 建议的下一步行动

---
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

全局配置（opencode.json）
    │
    └── 定义默认权限
    
项目配置（.opencode/opencode.json）
    │
    └── 覆盖全局配置
    
Agent 配置（.opencode/agent/*.md）
    │
    └── 覆盖项目配置（针对特定 Agent）

{
  "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"
    }
  }
}

# .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"
  }
}

# 非交互运行 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

0 9 * * * /path/to/daily-report.sh

# .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                                │
├─────────────────────────────────────────────────────────────┤
│                          │                                   │
│                          ▼                                   │
│                    MCP 客户端                                 │
│                          │                                   │
│          ┌───────────────┼───────────────┐                   │
│          ▼               ▼               ▼                   │
│    ┌──────────┐   ┌──────────┐   ┌──────────┐               │
│    │ 数据库    │   │ API 服务 │   │ 文件系统  │               │
│    │ MCP 服务器│   │ MCP 服务器│   │ MCP 服务器│               │
│    └──────────┘   └──────────┘   └──────────┘               │
│          │               │               │                   │
│          ▼               ▼               ▼                   │
│    PostgreSQL      外部 API        特殊文件格式               │
└─────────────────────────────────────────────────────────────┘

{
  "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"]
    }
  }
}

第一层：基础原理
├── 上下文窗口：AI 的工作记忆，理解"为什么更多信而更差" ├── Agent 模式：Plan 思考，Build 执行，分离关注点
├── 工具系统：rea/grep/bash，AI 与世接口
└── 文件系统：持久化、结构化、可引用、可追踪

第二层：上下文管理
├── @ 引用机制：精确控制 AI "看到什么" └── 渐进式披露：按需加载，保持注意力集中

第三层：持久化与复用
├── Agent化 AI 人格，一次配置永久生效
├── Skill 系统：按需加载的专业知识包
└── Command 系复用的提示词模板

第四层：自动化与扩展：安全边界，allow/ask/deny
├── CLI 自动化：脚本化、流水线集成
└── MCP 协议：扩展 AI 能力边界