# opencode_config

**Repository Path**: miaoyinjun/opencode_config

## Basic Information

- **Project Name**: opencode_config
- **Description**: opencode + omo + deepseek大模型的个人配置，从26年2月份到现在，完成了一个中大型工业软件的开发。
1、特点是开发成本可控。
2、需求调研、代码开发用了西方哲学的方法论在展开讨论和辩论，尽量做到逻辑自洽，
3、用儒家的哲学观点规范ai的认知行为模式：知之为知之，不知为不知，如果所需知识超过自身边界，那么自觉交回人类编码权，不自作聪明。
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: develop
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 10
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenCode 配置仓库

> 编译器能告诉你语法对不对。Linter 能告诉你格式规不规范。但谁来告诉你——变量名叫 `data` 对不对？三层抽象套三层工厂是不是过度设计？第 12 版需求文档和用户真正需要的「数据看板」之间差了几个苏格拉底式追问？**这不是一份死配置。这是一个哲学驱动的可组合 AI 协作框架。**

编程最深的困境，几乎不在技术层面。命名混乱、过度工程、需求模糊、架构反复——这些让你加班到深夜的问题，每一个都精确对应着一个哲学家打磨了两千年的分析命题。这份配置把 9 个东西方哲学流派做成了**真正的工程分析工具**：每个流派含 L2 诊断 / L3 方法 / L4 案例三层结构，通过谛听（Diting）agent 统一调度。不是贴标签做文化比较，不是「哲学启发灵感」的模糊关联——是从诊断直达可操作的工程决策，每一步都可复现。

**模型无关，纯配置**：无构建系统，换模型只需改两个文件（`opencode.json` + `oh-my-openagent.json`），支持 OpenAI、Anthropic、Ollama 等任何 OpenAI 兼容接口。

**速览**：三层架构（编排/执行/知识）→ 28 智能体 + 60+ 技能 + 9 哲学流派 → 五明十智能力框架 → 中庸择法、中道破执。谛听在需要时自动分派最合适的哲学框架：说「这段代码设计合理吗」→ 自动选择；说「我不确定这个对不对」→ 苏格拉底 + 儒家并行；说「用道家分析这个 API」→ 直达指定流派。

如果你想让 AI 不只是执行工具而是思考伙伴——这是一个工程师在咖啡厅跟你解释他为什么把孔子、老子和苏格拉底写进了 AI 配置文件。

## 为什么哲学？

编程最深的困境，几乎都不在技术层面。编译器能告诉你语法对不对，但无法告诉你变量名叫 `data` 对不对。文档能告诉你 API 怎么调用，但无法告诉你这个 API 该不该存在。框架能帮你搭好脚手架，但无法告诉你三层抽象套三层工厂是不是过度工程。

这不是「编程之外」的问题。当你在两个技术方案之间纠结了两天，当你发现一个模糊的命名已经误导了三个新同事，当你对着 50 页需求文档仍然不知道用户到底要什么——你面对的不是技术问题，而是**两千年来哲学家一直在打磨的分析问题**。每一个技术决策的本质，都是认知判断、价值取舍和概念界定。而这些，恰是哲学的领地。

### 编程困境的哲学本质

每一个看似技术层面的纠结，背后都有一个精确的哲学命题：

| 你遇到的问题                   | 表象         | 哲学本质                               | 对应的哲学传统 |
| ------------------------------ | ------------ | -------------------------------------- | -------------- |
| 变量名叫 `data`、`info`、`tmp` | 命名不规范   | **正名问题**：名实不符，言不顺则事不成 | 儒家           |
| 三层抽象套三层工厂             | 过度工程     | **无为问题**：为学日益，为道日损       | 道家           |
| 纠结用 React 还是 Vue          | 技术选型纠结 | **初心被困**：思维定势遮蔽了问题本身   | 禅宗           |
| 需求文档写了 50 页还说不清楚   | 需求模糊     | **前提未审**：未经检视的假设驱动决策   | 苏格拉底       |
| 微服务拆了合、合了拆           | 架构反复     | **执于边见**：落于集中或分散两端       | 佛学中观       |
| 同一个词在不同模块含义不同     | 语义混乱     | **语言问题**：概念边界与指称不清晰     | 分析哲学       |
| 觉得工作没意义、职业倦怠       | 意义感丧失   | **存在追问**：此在为何而建？           | 欧陆哲学       |
| 架构评审时各说各话无法达成共识 | 标准缺失     | **评判依据**：没有共享的「好」的标准   | 古希腊哲学     |

每个编程困境的表面是一个技术选择，底层是一个**哲学问题在代码中的投影**。你换框架、重构、加抽象层——这些操作只改变了投影的形状，没有触及投影的来源。而哲学框架直接作用于投影的来源。

### 从哲学框架到可操作的工程决策

哲学不是「软技能」——它们是比任何编程范式都更早存在的精密分析方法。以下三个案例展示哲学框架如何从诊断直达决策，每一步都有具体的映射：

#### 案例一：儒家正名 → 模块重命名，认知效率提升 3 倍

**处境**：一个运行三年的项目中，`utils/` 目录有 47 个文件，`helpers/` 有 23 个，`common/` 有 18 个。新成员需要 3 周才能独立定位代码，老成员也经常「我记得有个函数处理日期格式，但忘了在哪个文件里」。

**框架**：孔子：「名不正，则言不顺；言不顺，则事不成。」（《论语·子路》）——名称不准确，表达就不清晰；表达不清晰，事情就做不成。儒家的「正名」不是咬文嚼字，而是**通过准确命名建立共享的认知结构**。

**分析**：

1. 逐个审视 `utils/helpers/common` 下的每个文件，回答一个问题：「这个文件**实际做了什么**？」——而非「它目前叫什么」。
2. 按实际功能重新归类：字符串处理的进 `string/`，HTTP 请求的进 `api/`，日期处理的进 `datetime/`。
3. 文件名反映核心动作：`formatDate` 而非 `dateUtils`，`fetchUser` 而非 `apiHelper`——名称本身即文档。

**决策**：执行系统性的「正名」重构——以实际功能而非便利性为依据重命名全部公共模块。这不是代码清理，是**认知结构的重建**。

**结果**：新成员代码定位时间从 3 周缩短到 1 周。PR 中不再有「这个函数为什么不放 utils 里」的争论——因为 `utils` 目录本身已经不存在了。

---

#### 案例二：道家无为 → API 从 12 参数到 4 参数，错误率下降 70%

**处境**：一个支付 API 有 12 个参数，其中 5 个必填、3 个条件必填、4 个可选。文档写了 8 页，但每次对接都有参数传错。团队抱怨「这个 API 太难用了」，产品经理要求「再加一个参数满足新场景」。

**框架**：老子：「为学日益，为道日损。损之又损，以至于无为。」（《道德经》第四十八章）——求学是每天增加，修道是每天减少。减少再减少，直到「不做」的状态。好的设计不是「能做很多」，而是**让用户不必做很多**。

**分析**：

1. 追踪每个参数的实际使用频率：4 个参数覆盖了 92% 的调用场景，其余 8 个仅出现在 8% 的边缘场景中。
2. 检查那 8 个参数是否可以由系统自动推断：其中 5 个可以（从上下文、默认值、已有数据中推导），3 个确实需要用户提供但仅在特定条件下。
3. 重新设计：核心 API 仅保留 4 个参数。边缘场景通过独立的、明确命名的扩展方法处理（如 `payWithSplit()`、`payWithDelay()`）。

**决策**：不做聚合式的超级 API，做分离式的精简 API。「无为」不是什么都不做——是**不做多余的事**。12 参数的 API 不是在帮用户，是在把系统的复杂性转嫁给用户。

**结果**：对接错误率下降 70%。新商户平均 15 分钟完成首次接入（原来 2 小时）。此后每当产品经理提出新参数需求，团队先问：「能不能不让用户传这个参数？」

---

#### 案例三：苏格拉底诘问 → 8 周需求缩为 2 周，交付物精确命中

**处境**：产品经理提出：「我们需要一个数据看板，展示所有核心业务指标。」团队评估 8 周工期。第 3 周 PM 看到原型：「不对，我想要的是能导出报表的。」第 5 周：「其实运营每天早上只需要看三个数字。」

**框架**：苏格拉底：「我唯一知道的就是我一无所知。」——苏格拉底式诘问（elenchus）的核心不是给出答案，而是**通过持续追问暴露隐含假设**，直到对方自己发现真正的问题是什么。

**分析**：

1. 「看板」——是指实时更新的还是每日快照？（答：每日就够了）
2. 「核心业务指标」——具体是哪几个？（答：日活、转化率、收入，就三个）
3. 「展示」——谁来展示？在什么设备上？什么时间看？（答：运营经理，早上到公司，手机上扫一眼）
4. 「所有」——有例外吗？哪些指标确实不需要？（答：其他指标每月月报才需要）

**决策**：不做 Web 看板。每天早上 8:30 发送一封邮件，正文三个数字，附 CSV 文件供进一步分析。苏格拉底没有发明这个方案——他只是**问到了真正的需求**。「看板」是方案包装，不是需求描述。诘问法的价值就是剥掉包装，露出真实需求。

**结果**：工期从 8 周缩到 2 周。运营经理说「这就是我想要的」。PM 此后在提需求前会先回答三个问题：谁用、何时用、用完后做什么决策。

---

这三个案例不是巧合——每一个都遵循同一条链路：**识别问题的哲学本质 → 应用该传统的方法框架 → 得出具体的工程决策**。这不是「哲学启发灵感」这种模糊关联，而是可复现的分析路径。

---

### 知之为知之：AI 对话的置信度规范

前三个案例展示了哲学框架如何解决**人的工程问题**。但 AI 协作体系中还有一个更根本的问题：**AI 自身的对话质量。** 当模型流畅地编造一个看似合理的回答时，用户无法区分「AI 确实掌握的」和「AI 正在猜测的」。这不是技术缺陷——这是一个哲学命题，孔子两千年前已经给出了答案。

#### 处境：AI 的「不知而以为知」比无知更危险

AI 模型在对话中天然倾向于过度自信。面对超出训练数据覆盖范围的问题，它不会沉默——它会用同等自信的语气编造一个「听起来对」的回答。用户说「帮我写一个 React 19 的新特性 demo」，模型可能流畅地输出一段代码，但 React 19 尚未发布——模型「不知道它不知道」，于是凭空生成了一个 API。

这不是概率模型的 bug，这是**没有元认知**。人类专家在面对不确定时会说「这一点我不太确定，我查一下再告诉你」——这种「知道自己不知道」的能力，是一切可靠知识交流的前提。AI 缺失的正是这一点。

#### 框架：知之为知之，不知为不知，是知也

> 子曰：「由，诲汝知之乎！知之为知之，不知为不知，是知也。」——《论语·为政》

孔子对子路的这段教诲，通常被理解为「诚实」——知道就说知道，不知道就说不知道。但它的哲学深度远不止于此。最后三个字「是知也」——**这才是真正的知**——揭示了一个颠覆性的观点：

**「知」的本质不是信息积累，而是对自身知识边界的清醒认知。** 一个人知道一万件事但对自己的知识盲区毫无意识，不如一个只知十件事但精确知道另外九十件事「需要查证」的人。前者是「不知而以为知」——孔子的原话是「不知为不知」的反面正是「不知而以为知」，而这恰恰是 AI 幻觉的哲学本质。

儒家不是要求全知，而是要求**元认知**——对自己「知道什么、不知道什么、需要验证什么」有精确的边界感。这正是 AI 对话最需要的能力。

#### 分析：五个可操作的置信度规范

将「知之为知之」从哲学原则转化为 AI 对话的可执行规范，形成五个层次：

**1. 反幻觉 — 从「我猜是 X」到「我不确定 X，让我查一下」**

这是最基础的一层。当 AI 不确定时，不是降低语气词的强度（「可能」「大概」「应该是」——这些不改变幻觉的本质），而是**主动声明不确定性，并切换到查证模式**。

> ❌ 幻觉模式：「React 19 引入了 `useOptimistic` 这个新 Hook，用法如下…」
> ✅ 知之为知之：「React 19 官方发布说明尚未覆盖到这一点。让我从 React RFC 和 Canary 版本的 CHANGELOG 中查找确认。」

区别不在于答案的对错——而在于答案的**置信度来源是透明的**。

**2. 置信度三级标注 — 让用户知道何时该信任、何时该验证**

每一段输出都携带隐含的置信度信号。将这个信号显式化：

| 置信度   | 标注                     | 示例                                                                                                              |
| -------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **确知** | 文档验证、源码确认       | 「React 18 的并发特性包括 `useTransition` 和 `useDeferredValue`（React 18 官方文档确认）」                        |
| **推测** | 基于模式推断，未独立验证 | 「根据 React 16→17→18 的演进模式，React 19 可能进一步优化调度器优先级队列（**推测，建议查阅 React 19 RFC**）」    |
| **不知** | 明确的知识盲区           | 「React 19 对 Suspense 的底层实现做了哪些改动——这一点我不知道。建议查阅 React Core Team 的架构决策记录（ADR）。」 |

关键：**推测可以输出，但不能伪装成确知。** 标注不是为了限制 AI 的表达，而是为了给用户一个可操作的信任模型——「这一段我可以直接采纳，这一段我需要先验证」。

**3. 知识边界声明 — 「我知道 X，不知道 Y，需要验证 Z」**

比单句标注更深一层：在复杂回答中，AI 应对整个回答的知识覆盖范围做一个总览声明。格式：

> **知识边界**：关于 React Fiber 架构，我知道其核心设计（可中断渲染、优先级调度、双缓冲树），不知道 React 19 对调度器算法的具体改动，需要验证 React 19 Canary 版本中是否已合并相关的 RFC 实现。

这不是示弱——这是**精确性**。一个附带边界声明的回答，比一个无边界但可能包含幻觉的回答，信息密度更高、可操作性更强。因为信任不再是「信或不信」的二元判断，而是「哪里信、哪里验」的精确导航。

**4. Handoff 触发 — 当超出边界时，主动交还而非强行编造**

这是最具实践价值的一层。当问题完全超出 AI 的知识覆盖范围时，不应强行输出一个「看起来完整」的回答，而应**主动触发 Handoff**：

> 「这个问题我无法给出可靠答案。你需要的是：
>
> - **具体能力**：查阅 React 19 调度器源码，对比 React 18 的差异
> - **建议渠道**：React Core Team 的 GitHub Discussion #12345，或 Dan Abramov 的 Twitter 线程 @2026-05
> - **我可以做的**：如果你提供源码片段或 PR 链接，我可以帮你做 diff 分析和逻辑推断。」

一个正确的 Handoff 比一个完整的幻觉回答**价值高一万倍**。因为幻觉回答会浪费用户的时间去验证一个错误的前提，而 Handoff 直接给出了通往正确答案的路径。

**5. 日新机制 — 每次「不知」都是边界的扩展**

> 汤之《盘铭》曰：「苟日新，日日新，又日新。」——《大学》

儒家将「日新」视为道德修养的核心——每天更新自己。应用在 AI 的知之为知之中：「不知」不是终点，而是边界的标记点。每次「我不知道 X」之后，下一次遇到同类问题时，AI 应该先查询再回答——边界在每一次诚实中向外扩展。

具体机制：

- 记录每一次「我无法确认」的知识点
- 在后续对话中遇到同类问题时，优先触发查证流程
- 知识边界不是静态的——它持续外扩，但外扩的前提是诚实地标定当前边界

#### 决策：在系统中嵌入置信度规范

将「知之为知之」从哲学抽象落地为系统行为：

1. **Agent Prompt 嵌入**：谛听（Diting）的持戒中，`不授记`（不预言绝对的是非）、`不戏论`（不陷入概念游戏）、`不推诿`（该深度分析就分派，不以空性搪塞）——这三条本质上都是「知之为知之」的具体化。Agent prompt 中必须声明：「当你不知道时，不要说『可能是』，要说『我不确定，让我查』。」

2. **儒家 `confucianism` 技能的六步自省协议**：该技能已内置六步协议，第一步即「标定知识边界」——在分析任何问题之前，先明确「我对此问题知道什么、不知道什么、需要查什么」。这不是可选的，是流程的第一步。

3. **苏格拉底 + 儒家并行触发**：当用户说「我不确定这个对不对」，谛听自动同时触发两个技能——苏格拉底诘问法追问假设（你为什么不确信？），儒家六步协议校准知识（你确切知道什么？需要验证什么？）。两个传统互补：一个问 Why，一个问 What。

4. **Handoff 规范写入所有分析技能**：九个哲学分析技能的输出格式中，必须包含「知识边界声明」一节——精确列出「确知 / 推测 / 不知」三个域。

#### 结果：信任不再依赖「概率」

实施「知之为知之」后，AI 输出的每一段分析都自带置信度。用户不再是「整段回答该不该信」的全有全无判断，而是：

- 「这一段是文档确认的 → 可以直接采纳」
- 「这一段是模式推断的 → 先跑个测试验证」
- 「这一段 AI 承认不知道 → 自己去查文档或问专家」
- 「这一段 AI 直接 Handoff 了 → 按照它给的渠道去找答案」

信息总量不变，但**信任的精度提升了两个数量级**。这不是降低了 AI 的能力——这是**让 AI 的能力变得真正可用**。因为可用性的前提不是「无所不能」，而是「可预期」。

孔子说「是知也」——这才是真正的知。两千五百年后的今天，这句话成了 AI 对话质量的基石。

---

### 东西方互补：一个问「如何」，一个问「为何」

九个哲学流派并非随机拼凑，它们恰好形成了一种根本的互补：

- **东方哲学（儒家、道家、佛学、禅宗）回答「如何」（How）**——如何正确地做事、如何减少摩擦、如何放下执念。儒家告诉你怎样命名才能让团队有序协作，道家告诉你怎样设计才能让用户感觉自然，禅宗告诉你怎样打破思维定势找到新路径。
- **西方哲学（苏格拉底、亚里士多德、分析哲学、欧陆哲学）回答「为何」（Why）**——为何这个方案是对的、何种条件下它成立、它的边界在哪里。苏格拉底诘问法追问「你为什么要这个」，亚里士多德四因说评估「这个架构为什么成立」，分析哲学检查「这个概念在不同语境下是否一致」。

「如何」没有「为何」的验证，会退化为盲目的最佳实践复制。「为何」没有「如何」的落地，会沉溺于无止境的概念辨析。两者并用，「如何」提供行动的路径，「为何」提供验证的标准——这就是为什么这个配置同时内置了九个东西方哲学流派，通过谛听（Diting）统一调度。

### 从古老的分析工具到工程流程

两千多年来，东西方哲学家已经为认知判断、价值取舍和概念界定打磨出了精密的方法论。这些方法论不是文化装饰——它们的分析精度和可操作性不亚于任何工程方法论：

| 哲学传统           | 编程中的工程等价物 | 解决什么问题                           | 可操作的输出           |
| ------------------ | ------------------ | -------------------------------------- | ---------------------- |
| 苏格拉底诘问法     | 需求澄清引擎       | 「你到底要什么？」— 追问原始问题       | 精炼的需求陈述         |
| 亚里士多德四因说   | 架构评估矩阵       | 质料因/形式因/动力因/目的因 — 四维评判 | 架构决策的理据清单     |
| 佛学缘起性空       | 依赖分析工具       | 一切组件因缘和合，无独立自性           | 耦合度可视化与简化路径 |
| 儒家「知之为知之」 | AI 置信度校准      | 六步自省协议，不含糊其辞               | 知识边界的明确声明     |
| 道家「无为而治」   | 代码简化方法论     | 代码行数负增长才是真优化               | 可删除代码的识别清单   |
| 分析哲学语言澄清   | 语义消歧           | 同一个词在不同模块含义是否一致         | 术语一致性审计报告     |
| 欧陆现象学直观     | 架构反思与 UX 审视 | 直面代码本身，悬置先入为主的判断       | 架构异味的现象学诊断   |
| 禅宗直指人心       | 思维定势突破       | 当已有方案走到死胡同时，跳出框架       | 全新的解决方案方向     |

**这就是此配置诞生的根本原因。** 当编程最深的困惑绕不开哲学问题，我们就应当把这些古老的分析工具直接嵌入工程流程。不是贴标签做文化比较——是每当你遇到命名混乱、过度设计、逻辑矛盾、需求模糊时，谛听会自动分派最合适的哲学框架，从诊断直达可操作的工程决策。

择法之中，用后即放。以下「设计哲学」章节将展开这个配置的三层架构和调度原则。

## 设计哲学

本配置不是一套固定的模型设置，而是一个**可组合的 AI 协作框架** — 模型、技能、智能体三者解耦，可按需替换任意一层。核心理念是让正确的能力在正确的时机介入：

```
用户意图 → 编排分解 → 按需调度 agent + skill → 并行执行 → 哲学审视 → 质量验收
```

> 🧘 **最大亮点：9 个哲学技能** — 不是文化装饰，而是完整的工程分析框架。每个技能含 L2 诊断 / L3 方法 / L4 案例三层结构，通过 谛听 agent 统一调度，中庸择法、中道破执。详见[哲学即工具](#-哲学即工具)。

**与模型无关**：框架本身不绑定任何模型。内置配置以 DeepSeek 为默认示例，但所有 agent→skill 映射、category→模型分配、推理深度策略均可通过 `oh-my-openagent.json` 自由调整。支持 OpenAI、Anthropic、Ollama 等任何 OpenAI 兼容接口。换模型只需改两个文件，见文末[模型更换指南](#模型更换指南)。

### 三层架构

| 层         | 职责                         | 载体                                             |
| ---------- | ---------------------------- | ------------------------------------------------ |
| **编排层** | 分解任务、分派代理、质量验收 | Sisyphus（工程编排）、谛听（哲学编排，含自迭代） |
| **执行层** | 加载技能、并行执行具体工作   | 11 个专业智能体 + 8 个 category                  |
| **知识层** | 注入领域专长、约束行为边界   | 54+ 技能 + 6 个 MCP 服务                         |

### 模型调度原则

按任务复杂度分配推理深度——重思考用强模型，轻任务用快模型。具体分配在 `oh-my-openagent.json` 的 `agents` 和 `categories` 两个字段中配置：

| 推理深度    | 典型任务                     | 示例 agent                     |
| ----------- | ---------------------------- | ------------------------------ |
| **max**     | 任务编排、深度审查、哲学统筹 | Sisyphus、Oracle、谛听         |
| **high**    | 编码执行、规划、前端开发     | Junior、Prometheus、Hephaestus |
| **default** | 搜索、文档查询、轻量修改     | Explore、Librarian、Quick      |

> 💡 换模型只需改 `opencode.json`（提供商+Key）和 `oh-my-openagent.json`（agent→模型映射）。支持 OpenAI、Anthropic、Ollama 等任何 OpenAI 兼容接口。

### 智能体分工矩阵

每个智能体配有专属技能栈，Sisyphus 自动选择最合适的代理执行任务：

| 角色      | 智能体          | 一句话                | 典型场景                            | 哲学技能                        |
| --------- | --------------- | --------------------- | ----------------------------------- | ------------------------------- |
| 🎯 主编排 | Sisyphus        | 分解→委派→验收        | 多文件实现、架构变更、特性开发      | socratic-dialogue, confucianism |
| 🔧 执行   | Sisyphus-Junior | 并行执行编码          | 被 Sisyphus 调度的具体编码任务      | —                               |
| 🎨 前端   | Hephaestus      | UI/UX、视觉 QA        | 页面构建、Playwright 测试、视觉回归 | —                               |
| 📋 规划   | Prometheus      | 计划编写、头脑风暴    | 多步骤任务分解、并行执行规划        | philosophical-analysis          |
| 🔮 审查   | Oracle          | 架构诊断、深度调试    | 复杂 bug、安全审查、架构决策        | analytic, socratic-dialogue     |
| 📚 查资料 | Librarian       | 文档查询、GitHub 搜索 | 陌生库的 API 用法、开源实现参考     | —                               |
| 🔍 探索   | Explore         | 代码库结构发现        | 找到某功能在哪里、理解模块关系      | —                               |
| 🧠 预判   | Metis           | 需求歧义检测          | 「用户到底想要什么？」意图分析      | socratic-dialogue               |
| ✅ 验收   | Momus           | 计划完整性审查        | 实施前的方案评审、边界条件检查      | analytic                        |
| 📁 隔离   | Atlas           | Git worktree 管理     | 特性分支的隔离工作区                | —                               |
| 🧘 哲学   | 谛听 (Diting)   | 9 流派统筹调度        | 设计决策、命名困惑、职业倦怠        | 全部 9 个哲学技能               |

### 哲学技能速查

哲学技能已按需分发至 5 个工作 agent，谛听保有全部 9 个用于深度统筹。选择 agent 即选择了对应的哲学视角：

| 如果你要…                    | 选择 agent | 自动获得的哲学技能                                         |
| ---------------------------- | ---------- | ---------------------------------------------------------- |
| 架构决策、命名规范、需求澄清 | Sisyphus   | socratic-dialogue（诘问假设）+ confucianism（正名+六步知） |
| 代码审查、深度调试、逻辑验证 | Oracle     | analytic（逻辑一致性）+ socratic-dialogue（调试辩证）      |
| 多方案对比、架构评审         | Prometheus | philosophical-analysis（多流派统筹）                       |
| 需求不明确、意图模糊         | Metis      | socratic-dialogue（追问澄清）                              |
| 方案完整性、契约验证         | Momus      | analytic（边界条件校验）                                   |
| 深度哲学分析、9 流派统筹     | 谛听       | 全部 9 个                                                  |

### 🧘 五明十智：工程能力的佛法映射

这不是文化装饰。佛教「五明」（五大学问）和「十智明」（十种智慧）提供了一个完整的工程师能力成长框架。从「学问」到「智慧」的质变——不是学新东西，是你已经会的东西「活过来」了。一段代码、一个 API、一次重构，每个日常操作里都藏着十智明的影子。以下是每门学问精通后自然呈现的智慧：

| 学问（五明/十明）      | → 精通后变成的智慧（十智明）         |
| ---------------------- | ------------------------------------ |
| 声明（语言学）         | → 分别言音智明（多语言的直觉理解）   |
| 医方明（诊断治疗）     | → 天眼智明（一眼看到系统哪里病了）   |
| 工巧明（工程技术）     | → 神力智明（工具和环境随心所欲）     |
| 因明（逻辑推理）       | → 真实智明（看到代码的数学本质）     |
| 内明（自我认知）       | → 灭定智明（知道何时停下的自我觉知） |
| 修辞 + 辞藻 + 韵律     | → 色身庄严智明（审美直觉）           |
| 戏剧（叙事）           | → 宿命智明（理解系统的叙事弧线）     |
| 星象（系统拓扑）       | → 未来际智明（预见系统的走向）       |
| 修辞（有效表达）       | → 他心智明（理解他人的表达意图）     |
| 辞藻（精确用词）+ 因明 | → 天耳智明（从噪音中辨识信号）       |

> 十智明不是新学的东西——是你已经学会的东西「活过来」了。一个好的工程师不是在「修炼十智明」，而是在做的每一件事里认出它们的影子。

### 使用心法

1. **信任分派** — 把任务描述清楚即可，编排器比你更了解哪个代理和技能最适合。不要说「用 X 技能做 Y」，说「我要实现 Y」。
2. **拥抱并行** — 独立子任务自动并行执行。不要一个接一个地提需求，一次说完，系统会拆解。
3. **验证闭环** — 每个任务结束后自动走审查流程（Oracle + Momus）。你看到的结果已经过了多层校验。
4. **哲思即工具** — 哲学技能已按需分发至 5 个 agent：Sisyphus 有苏格拉底+儒家（需求澄清/命名规范），Oracle 有分析哲学+苏格拉底（逻辑验证/调试辩证），Prometheus 有哲学综合（多角度架构评审），Metis 有苏格拉底（歧义追问），Momus 有分析哲学（契约校验）。谛听保有全部 9 个用于深度统筹。每个 agent 在需要时自动触发。
5. **中庸择法** — 一个流派够用不调两个，轻量问题不解构到 L4，分析必须抵达行动。在具体条件下击中精确的平衡点，不迷信任何单一方法论。
6. **用后即放** — 分析方法只是方便法门 (upāya)，不是真理。分析结束，方法放下。不要让工具变成新的执着。

### 54+ 技能生态

| 领域        | 技能                             | 用途                                  | 来源        |
| ----------- | -------------------------------- | ------------------------------------- | ----------- |
| 📄 文档处理 | `docx`                           | Word 文档创建/编辑/批注/修订          | 内置        |
| 📄 文档处理 | `pptx`                           | PPT 演示文稿创建/编辑/布局            | 内置        |
| 📄 文档处理 | `pdf`                            | PDF 提取/创建/合并/表单填写           | 内置        |
| 📄 文档处理 | `xlsx`                           | Excel 电子表格创建/公式/分析          | 内置        |
| 📄 文档处理 | `pdf-analysis`                   | PDF 深度分析（语义/实体/摘要）        | 内置        |
| 🖥 前端开发  | `frontend-dev`                   | React/Vue/Tailwind/性能/无障碍        | 内置        |
| 🖥 前端开发  | `frontend-design`                | 生产级前端 UI 生成，反 AI 模板风格    | power-pack  |
| 🖥 前端开发  | `frontend-ui-ux`                 | 设计师级 UI/UX 实现                   | 内置        |
| 🎨 设计     | `canvas-design`                  | PNG/PDF 原创视觉设计                  | 内置        |
| 🎨 设计     | `theme-factory`                  | 10 套预设主题，支持按需生成           | 内置        |
| 🎨 设计     | `brand-guidelines`               | Anthropic 品牌色/字体                 | 内置        |
| 🎨 设计     | `slack-gif-creator`              | Slack 动图 GIF 生成                   | 内置        |
| 🧠 哲学分析 | `philosophical-analysis`         | 多流派哲学统筹分析                    | 内置        |
| 🧠 哲学分析 | `buddhism`                       | 佛学哲学（缘起性空/中观）             | 内置        |
| 🧠 哲学分析 | `daoism`                         | 道家哲学（无为/自然）                 | 内置        |
| 🧠 哲学分析 | `confucianism`                   | 儒家哲学（仁义礼智信）                | 内置        |
| 🧠 哲学分析 | `analytic`                       | 分析哲学（逻辑实证/语言分析）         | 内置        |
| 🧠 哲学分析 | `continental`                    | 欧陆哲学（存在主义/现象学）           | 内置        |
| 🧠 哲学分析 | `ancient-greek`                  | 古希腊哲学（柏拉图/亚里士多德）       | 内置        |
| 🧠 哲学分析 | `socratic-dialogue`              | 苏格拉底式对话（诘问法）              | 内置        |
| 🧘 禅修实践 | `zen`                            | 禅宗 — 直指人心、公案、初心           | 内置        |
| ⚙️ 编辑器   | `editor-config`                  | Neovim + Emacs 配置大全               | 内置        |
| 🔧 终端运维 | `shell-ops`                      | 系统诊断/Git/文件/网络                | 内置        |
| 🐛 C++ 调试 | `cpp-debugger-zh`                | GDB/LLDB 中文调试指导                 | 内置        |
| 🔍 代码审查 | `code-review`                    | 多 Agent PR 审查，交叉验证            | power-pack  |
| 🔍 代码审查 | `security-review`                | OWASP 分类安全审查，必须 PoC          | power-pack  |
| 🔍 代码审查 | `code-reviewer`                  | 小范围改动快速审查                    | power-pack  |
| 🔍 代码审查 | `review-work`                    | 实施后审查（5 子代理并行）            | 内置        |
| 🔍 代码审查 | `remove-ai-slops`                | AI 生成代码异味清理                   | 内置        |
| 🚀 特性开发 | `feature-dev`                    | 七步引导式开发（探索→架构→实现→审查） | power-pack  |
| 🚀 特性开发 | `code-explorer`                  | 端到端代码追踪分析                    | power-pack  |
| 🚀 特性开发 | `code-architect`                 | 架构设计蓝图 + 文件级实施清单         | power-pack  |
| 🚀 特性开发 | `brainstorming`                  | 需求探索与方案构思                    | superpowers |
| 🚀 特性开发 | `writing-plans`                  | 多步骤任务计划编写                    | superpowers |
| 🚀 特性开发 | `executing-plans`                | 计划分步执行（带审查检查点）          | superpowers |
| 🚀 特性开发 | `subagent-driven-development`    | 并行子代理开发模式                    | superpowers |
| 🚀 特性开发 | `dispatching-parallel-agents`    | 独立任务并行派发                      | superpowers |
| 📦 技能开发 | `skill-creator`                  | SKILL.md 技能创作                     | power-pack  |
| 📦 技能开发 | `mcp-builder`                    | MCP 服务构建（Python/TypeScript）     | power-pack  |
| 📦 技能开发 | `customize-opencode`             | OpenCode 配置完整参考                 | 内置        |
| 📝 项目记忆 | `agents-md-improver`             | 审计和更新 AGENTS.md                  | power-pack  |
| 📝 项目记忆 | `agents-md-revise`               | 将会话知识写入项目规则                | power-pack  |
| 🌐 Web 测试 | `webapp-testing`                 | Playwright 浏览器自动化测试           | 内置        |
| 🌐 Web 测试 | `playwright`                     | 浏览器交互/截图/网络监控              | 内置        |
| 🔒 安全     | `security-research`              | 3 漏洞猎手 + 2 PoC 并行审计           | 内置        |
| 🐛 调试     | `debugging`                      | 假设驱动的系统调试工作流              | 内置        |
| 🐛 调试     | `systematic-debugging`           | bug 修复前结构化诊断                  | superpowers |
| 🧪 测试     | `test-driven-development`        | 实现前先写测试                        | superpowers |
| 🧪 测试     | `test-writing`                   | 测试编写指南与最佳实践                | 内置        |
| ✅ 质量     | `verification-before-completion` | 完成前强制验证                        | superpowers |
| ✅ 质量     | `requesting-code-review`         | 完成后请求审查                        | superpowers |
| ✅ 质量     | `receiving-code-review`          | 接收审查后严格验证                    | superpowers |
| ✅ 质量     | `visual-qa`                      | 视觉回归测试（Web + TUI）             | 内置        |
| 🔌 Git      | `git-master`                     | 原子提交/rebase/历史搜索              | 内置        |
| 🔌 Git      | `using-git-worktrees`            | Git worktree 工作隔离                 | superpowers |
| 🔌 Git      | `finishing-a-development-branch` | 分支完成后的合并/PR 决策              | superpowers |
| 🎯 GitNexus | `gitnexus-exploring`             | 代码图谱探索（执行流/架构）           | 内置        |
| 🎯 GitNexus | `gitnexus-debugging`             | 图谱辅助调试追踪                      | 内置        |
| 🎯 GitNexus | `gitnexus-refactoring`           | 图谱辅助安全重构                      | 内置        |
| 🎯 GitNexus | `gitnexus-impact-analysis`       | 改动影响范围分析                      | 内置        |
| 🎯 GitNexus | `gitnexus-pr-review`             | PR 审查与风险评估                     | 内置        |
| 🎯 GitNexus | `gitnexus-cli`                   | CLI 索引/分析命令                     | 内置        |
| 🎯 GitNexus | `gitnexus-guide`                 | GitNexus 工具与资源参考               | 内置        |

### 🧘 哲学即工具

谛听 + 9 个哲学技能不是文化装饰——它们是解决实际工程问题的分析框架。当你在架构决策、命名规范、技术选型中陷入纠结时，谛听自动分派最合适的哲学视角：

| 技能                     | 编程场景                                                                |
| ------------------------ | ----------------------------------------------------------------------- |
| \`socratic-dialogue\`    | 需求澄清 + 调试辩证 + 知识探索：诘问法挖掘隐含需求，与儒家六步协议联动  |
| `analytic`               | 逻辑验证：分析函数边界条件、类型系统完备性、API 契约一致性              |
| `continental`            | 架构反思 + 现象学直观：Husserl 本质还原直面代码，Merleau-Ponty 具身 UX  |
| `daoism`                 | 代码简化：无为而治 — 用最少的代码做最多的事，删减比添加更难             |
| \`confucianism\`         | 代码规范 + AI 认知自省：礼制即 convention，知之为知之六步协议（含日新） |
| `buddhism`               | 依赖分析 + 元编排：缘起性空、四圣谛、三句义、五明十智明                 |
| `ancient-greek`          | 设计评判：亚里士多德的本质/偶性、斯多葛的可控二分、柏拉图理型           |
| `zen`                    | 初心突破：当思维定势成了障碍 — 坐忘、公案、只管打坐                     |
| `philosophical-analysis` | 综合统筹：多流派交叉分析复杂架构决策，避免单一视角盲区                  |

> 💡 说「这段代码设计合理吗？」→ 谛听自动选择框架。说「用道家分析这个 API」→ 直达指定流派。说「我不确定这个对不对」→ 苏格拉底+儒家并行，诘问假设+校准知识。谛听以中庸择法、中道破执归一化所有方法论。

### 方法论归一：中庸择法，中道破执

谛听以两个核心原则统摄九家方法论：

- **中庸（世俗谛）**：择法之中（一法够用不调二）、深浅之中（L2诊断→L3方法→L4案例）、知行之中（分析必须抵达行动）
- **中道（胜义谛）**：一切方法皆空、缘起、假名。没有「正确的方法」——只有在此刻条件下最恰当的方法。用后即放，不执为真理。

### 基础设施插件

以上三层架构由 5 个核心插件支撑：

| 插件                  | 为什么重要                                                               |
| --------------------- | ------------------------------------------------------------------------ |
| **superpowers**       | 核心技能生态 — brainstorming、TDD、planning、code review 等 15+ 超级技能 |
| **oh-my-openagent**   | 智能体模型分配中枢 — 决定哪个任务用哪个模型、加载哪些技能                |
| **opencode-pty**      | 后台终端 — dev server、watch mode、长任务异步运行                        |
| **opencode-snippets** | 代码片段 — 跨项目复用常用代码                                            |
| **opencode-mem**      | 会话记忆 — 跨会话记住偏好和约定                                          |

---

## 部署指南

> **总览**：部署分三步 — ① 装软件 → ② 部署配置 → ③ 设密钥。约 10 分钟。

### 🤖 自动部署（AI 智能体可直接执行）

如果你是一个 AI 智能体，按以下流程自动化部署。每一步都有**检查命令**和**预期输出**，失败时停止并报告。

#### 0. 获取仓库地址

```
REPO_URL = 当前 git remote origin 地址
如果未克隆，询问用户提供仓库 URL（如 https://gitee.com/用户名/opencode_config.git）
```

#### 1. 检查并安装 Node.js

```bash
# 检查
node --version 2>/dev/null || echo "NOT_FOUND"
# 预期: v18.x.x 或更高；NOT_FOUND 则需要安装
```

如果输出 `NOT_FOUND` 或版本 < 18：

| 系统    | 检测命令            | 安装命令                                                                                                        |
| ------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| macOS   | `uname -s` = Darwin | `brew install node`（无 brew 则先装 brew）                                                                      |
| Linux   | `uname -s` = Linux  | Debian: `curl -fsSL https://deb.nodesource.com/setup_lts.x \| sudo -E bash - && sudo apt-get install -y nodejs` |
| Linux   |                     | Fedora: `curl -fsSL https://rpm.nodesource.com/setup_lts.x \| sudo bash - && sudo dnf install -y nodejs`        |
| Windows | 推荐 WSL2           | `wsl --install` 后按 Linux 步骤                                                                                 |

```bash
# 安装后验证
node --version && npm --version
# 预期: v22.x.x 和 10.x.x（或相近版本）
```

#### 2. 检查并安装 Git

```bash
git --version 2>/dev/null || echo "NOT_FOUND"
# 预期: git version 2.30.x 或更高
```

未安装时：macOS `brew install git` / Debian `sudo apt-get install -y git` / Fedora `sudo dnf install -y git`

#### 3. 安装 OpenCode CLI

```bash
npm install -g opencode
opencode --version
# 预期: opencode v1.x.x
```

#### 4. 克隆并部署配置

```bash
# 如果 ~/.config/opencode 已存在，先备份
test -d ~/.config/opencode && mv ~/.config/opencode ~/.config/opencode.backup.$(date +%Y%m%d%H%M%S)

# 克隆仓库（替换 REPO_URL）
git clone $REPO_URL ~/.config/opencode

# 安装依赖
cd ~/.config/opencode && npm install
# 预期: 无 error，added N packages

# 确认文件结构
ls ~/.config/opencode/opencode.json ~/.config/opencode/AGENTS.md ~/.config/opencode/oh-my-openagent.json
# 预期: 三个文件路径全部输出（无 No such file 错误）
```

#### 5. 配置 API 密钥（需要人工提供）

> **密钥接线原理**：`opencode.json` 用 `{env:DEEPSEEK_API_KEY}` 语法引用环境变量。设好环境变量，OpenCode 启动时自动读取。无需改任何配置文件。

```
⛔ AI 智能体：提示用户提供以下 Key，然后帮用户写入 shell 配置文件。

需要用户提供的 API Key：
  - DEEPSEEK_API_KEY（必需 — platform.deepseek.com → API Keys）
  - ZHIPUAI_API_KEY（可选 — open.bigmodel.cn → API Keys）
  - CONTEXT7_API_KEY（可选 — context7.com → Settings → API Key）

拿到 Key 后，追加到 shell 配置文件（先运行 echo $SHELL 确认用哪个）：

  # ~/.zshrc（或 ~/.bashrc）末尾添加：
  export DEEPSEEK_API_KEY="sk-用户提供的真实key"
  export ZHIPUAI_API_KEY="用户提供的真实key"
  export CONTEXT7_API_KEY="用户提供的真实key"

生效验证：
  source ~/.zshrc && echo $DEEPSEEK_API_KEY
  预期：输出 sk- 开头的字符串（非空）
```

#### 6. 个性化配置（使用 customize-opencode 技能）

本配置内置了 [`customize-opencode`](skills/development/customize-opencode/SKILL.md) 技能——一份 400+ 行的 OpenCode 配置完整参考，覆盖以下全部场景：

| 配置项                 | 技能指引内容                                                               |
| ---------------------- | -------------------------------------------------------------------------- |
| `opencode.json`        | 模型供应商、MCP 服务器、插件数组、权限规则、格式化工具、LSP、记忆压缩      |
| 智能体定义             | YAML frontmatter 结构、prompt 编写、mode 选择、权限覆盖、Markdown 文件格式 |
| `oh-my-openagent.json` | 智能体→模型映射、分类→模型映射、skills 注入、禁用项管理                    |
| MCP 服务               | 本地 stdio 配置、远程 HTTP/SSE 配置、OAuth 认证、环境变量引用              |
| 插件系统               | npm 包安装、本地文件加载、自动发现、依赖管理                               |
| 权限系统               | 通配符规则、智能体级覆盖、可用权限键列表                                   |

**AI 智能体部署后应执行**：

启动 OpenCode，然后输入以下命令逐一完成配置：

```
1.  "用 customize-opencode 技能，帮我检查当前 MCP 服务是否都正确配置"
    → 技能会验证 gitnexus、context7、playwright、filesystem 等 MCP 状态

2.  "用 customize-opencode 技能，帮我更新 filesystem MCP 的路径为 <用户项目目录>"
    → 技能会按规范修改 opencode.json 中的 command 数组

3.  "用 customize-opencode 技能，帮我检查环境变量 DEEPSEEK_API_KEY 是否正确加载"
    → 技能会检查 {env:变量名} 引用是否能正确解析

4.  "用 customize-opencode 技能，帮我从 themes/ 目录切换一个暗色主题"
    → 技能会指导如何合并主题色到 TUI 配置
```

**直接手动编辑**（如果不使用技能）：

```
opencode.json          → 模型/提供商、MCP 命令、插件列表、权限、格式化
oh-my-openagent.json   → 智能体模型分配（哪个智能体用哪个模型）
tui.json               → 当前终端配置（主题色 + 行为设置，用 customize-opencode 技能切换主题）
```

#### 7. 验证部署

```bash
# 启动测试
opencode --version && echo "✅ OpenCode 可执行"

# JSON 语法检查
python3 -m json.tool ~/.config/opencode/opencode.json > /dev/null && echo "✅ opencode.json" || echo "❌ JSON 语法错误"
python3 -m json.tool ~/.config/opencode/oh-my-openagent.json > /dev/null && echo "✅ oh-my-openagent.json" || echo "❌ JSON 语法错误"

# 依赖检查
test -d ~/.config/opencode/node_modules && echo "✅ 依赖已安装" || echo "❌ 运行 npm install"

# 密钥检查
test -n "$DEEPSEEK_API_KEY" && echo "✅ DEEPSEEK_API_KEY" || echo "⚠️  未设置 DeepSeek Key"

# 完整检查输出示例：
# ✅ OpenCode 可执行
# ✅ opencode.json
# ✅ oh-my-openagent.json
# ✅ 依赖已安装
# ✅ DEEPSEEK_API_KEY
```

全部 ✅ 后，运行 `opencode` 启动，然后在 OpenCode 中依次验证：

```
/mcp                         # 列出 MCP 服务，预期看到 6 个服务且状态正常
/agent                       # 列出智能体，预期看到 sisyphus/oracle/prometheus/hephaestus 等 13 个
/skill customize-opencode    # 加载配置技能，预期显示完整配置指南（验证技能可用）

# 配置自检——输入以下命令，由 customize-opencode 技能自动诊断：
用 customize-opencode 技能帮我检查当前配置是否完整：
  1. 所有 MCP 服务是否正常连接
  2. DEEPSEEK_API_KEY 环境变量是否正确设置
  3. JSON 配置文件语法是否合法
```

---

### 📖 手动分步指南

以下是面向人类的详细步骤。

#### 前置依赖

| 软件        | 最低版本 | 用途                      | 检查命令         |
| ----------- | -------- | ------------------------- | ---------------- |
| **Node.js** | >= 18    | OpenCode 运行时           | `node --version` |
| **npm**     | >= 9     | 随 Node.js 自带，安装依赖 | `npm --version`  |
| **Git**     | >= 2.30  | 克隆本仓库到本地          | `git --version`  |

以下软件 **按需** 安装，不影响 OpenCode 基本运行：

| 软件                  | 何时需要                                     |
| --------------------- | -------------------------------------------- |
| **Bun**               | 替代 npm，安装依赖更快（`bun install`）      |
| **clang-format**      | 项目中编辑 C / C++ 代码并启用格式化          |
| **Go + gofmt**        | 项目中编辑 Go 代码并启用格式化               |
| **Rust + rustfmt**    | 项目中编辑 Rust 代码并启用格式化             |
| **Playwright 浏览器** | 使用 `/webapp-testing` 技能做 Web 端到端测试 |

---

#### 第一步：安装 Node.js

> **为什么**：OpenCode 是一个 Node.js CLI 工具，需要 Node.js 运行时才能执行。

先检查是否已安装：

```bash
node --version    # 应输出 v18.x.x 或更高
npm --version     # 应输出 9.x.x 或更高
```

如果版本低于 18，或命令不存在，按你的操作系统选择安装方式。

#### macOS

**方式 A：Homebrew（最简单，推荐）**

如果没装过 Homebrew，先安装它：

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

然后用 Homebrew 安装 Node.js：

```bash
brew install node
```

安装完成后验证：

```bash
node --version   # 预期：v22.x.x 或 v20.x.x
npm --version    # 预期：10.x.x
```

**方式 B：nvm（需要切换 Node 版本时推荐）**

```bash
# 1. 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 2. 关闭当前终端，重新打开，或执行：
source ~/.zshrc

# 3. 安装 LTS 版本
nvm install --lts

# 4. 设为默认
nvm alias default lts/*

# 5. 验证
node --version
```

#### Linux

**Debian / Ubuntu**

```bash
# 1. 添加 NodeSource 官方软件源（提供最新 LTS 版本）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -

# 2. 安装
sudo apt-get install -y nodejs

# 3. 验证
node --version   # 预期：v22.x.x
npm --version    # 预期：10.x.x
```

**Fedora / RHEL / CentOS**

```bash
# 1. 添加 NodeSource 官方软件源
curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -

# 2. 安装
sudo dnf install -y nodejs

# 3. 验证
node --version
```

**Arch Linux**

```bash
sudo pacman -S nodejs npm
node --version
```

> **任何 Linux 发行版的备选方案**：使用 nvm（Node 版本管理器），步骤与 macOS 的「方式 B」完全相同。

#### Windows

**方式 A：直接安装 .msi（最简单）**

1. 打开浏览器，访问 [nodejs.org](https://nodejs.org/)
2. 点击绿色的 **LTS** 按钮，下载 `.msi` 安装文件
3. 双击运行，一路点 Next
4. **关键步骤**：在「Tools for Native Modules」页面，**勾选** 「Automatically install the necessary tools」— 这会安装 Python 和 C++ 编译工具链
5. 安装完成后，打开 PowerShell，验证：

```powershell
node --version
npm --version
```

**方式 B：WSL2（推荐给开发者）**

WSL2 让你在 Windows 上运行完整的 Linux 环境，OpenCode 在 WSL2 中体验最佳。

```powershell
# 1. 以管理员身份打开 PowerShell，安装 WSL2
wsl --install

# 2. 重启电脑

# 3. 重启后，系统会提示你创建 Linux 用户名和密码，按提示操作

# 4. 进入 WSL2 终端后，按 Ubuntu 方式安装 Node.js：
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 5. 验证
node --version
```

**方式 C：nvm-windows（需要切换 Node 版本时推荐）**

1. 打开 [nvm-windows 发布页](https://github.com/coreybutler/nvm-windows/releases)，下载最新 `nvm-setup.exe`
2. 双击安装（一直点 Next）
3. 打开 PowerShell（管理员），执行：

```powershell
nvm install lts
nvm use lts
node --version
```

---

#### 第二步：安装 Git

> **为什么**：本配置仓库托管在 GitHub，需要通过 `git clone` 下载到本地。

先检查是否已安装：

```bash
git --version   # 应输出 git version 2.30.x 或更高
```

如果已安装，跳过本节。如果未安装：

#### macOS

```bash
# 方式 A：Homebrew（推荐）
brew install git

# 方式 B：安装 Xcode Command Line Tools（自带 Git）
xcode-select --install

# 验证
git --version
```

#### Linux

```bash
# Debian / Ubuntu
sudo apt-get install -y git

# Fedora / RHEL
sudo dnf install -y git

# Arch
sudo pacman -S git

# 验证
git --version
```

#### Windows

1. 打开浏览器，访问 [git-scm.com/downloads/win](https://git-scm.com/downloads/win)
2. 下载安装包，双击运行
3. 安装选项建议：
   - **「Select Components」**：保持默认
   - **「Choosing the default editor」**：选你熟悉的编辑器（如 VSCode）
   - **「Adjusting your PATH」**：选 **「Git from the command line and also from 3rd-party software」**
   - **其余页面**：保持默认，一路 Next
4. 安装完成后，打开 PowerShell 验证：

```powershell
git --version
```

---

#### 第三步：安装 OpenCode CLI

> **为什么**：`opencode` 命令是启动 OpenCode 的入口。

```bash
# 全局安装（在任意目录执行）
npm install -g opencode
```

安装完成后验证：

```bash
opencode --version
# 预期输出类似：opencode v1.x.x
```

> **Windows 用户**：
>
> - 如果 PowerShell 报错「无法加载文件...因为在此系统上禁止运行脚本」，这是执行策略限制。以管理员身份打开 PowerShell，运行：
>   ```powershell
>   Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
>   ```
>   然后重新运行 `opencode --version`。
> - **强烈建议在 WSL2 中运行 OpenCode**。原生命令行（cmd / PowerShell）功能受限，部分 MCP 服务（如 PTY 后台进程）无法正常工作。

---

#### 第四步：部署本配置仓库

> **为什么**：本仓库包含了 AI 智能体定义、技能、插件配置等全部定制内容。放在 `~/.config/opencode/` 目录下，OpenCode 启动时会自动加载。

#### 4.1 决定仓库地址

你需要先 Fork 本仓库，或者直接克隆。

- **Fork（推荐）**：在 GitHub 上点击 Fork → 得到你自己的 `https://github.com/你的用户名/opencode-config.git` → 可以自由修改并提交
- **直接克隆**：使用原始仓库地址，但无法推送修改

下面以 Fork 后的地址为例。

#### 4.2 克隆到配置目录

```bash
# 将 <你的仓库地址> 替换为实际的 Git 地址
# 例如：git clone https://github.com/zhangsan/opencode-config.git ~/.config/opencode
git clone <你的仓库地址> ~/.config/opencode
```

> **如果 `~/.config/opencode/` 目录已存在**（之前配置过 OpenCode）：
>
> ```bash
> # 备份旧配置
> mv ~/.config/opencode ~/.config/opencode.backup.$(date +%Y%m%d)
>
> # 然后重新克隆
> git clone <你的仓库地址> ~/.config/opencode
> ```

#### 4.3 安装运行时依赖

```bash
cd ~/.config/opencode
npm install
```

这个命令做了什么：

- 读取 `package.json` 中的依赖列表
- 下载插件运行所需的 npm 包到 `node_modules/`
- 执行约 30 秒到 1 分钟

> **Windows + WSL2 用户注意**：
>
> - 以上命令全部在 WSL2 终端中执行
> - `~/.config/opencode/` 在 WSL2 中的实际路径是 `/home/你的用户名/.config/opencode/`
> - 不要把仓库克隆到 Windows 文件系统（如 `/mnt/c/`）— 会导致文件权限和符号链接问题

#### 4.4 确认文件结构

```bash
ls ~/.config/opencode/
```

预期看到以下文件：

```
AGENTS.md   opencode.json   oh-my-openagent.json   package.json   README.md
agents/     skills/         skill/                 themes/        commands/
```

如果看到了这些，说明配置部署成功。

#### 4.5 个性化定制（必做）

部署完成后，配置中仍有少量**个人化内容**需要修改。推荐使用本配置内置的 `customize-opencode` 技能来完成——它是一份 400+ 行的完整参考，覆盖 opencode.json 全部字段、智能体定义、MCP 配置、权限系统和插件管理。

**方式一：使用技能引导（推荐）**

启动 OpenCode 后输入：

```
用 customize-opencode 技能帮我完成部署后的个性化配置
```

技能会引导你逐步完成以下操作：

1. 检查 MCP 服务连接状态（GitNexus / Context7 / Playwright / Filesystem）
2. 更新 Filesystem MCP 允许访问的本地目录路径
3. 验证 API 密钥环境变量是否正确加载
4. 按需调整权限规则（如允许访问特定目录）
5. 从 66 个主题中选择切换终端配色

**方式二：手动编辑配置文件**

**Filesystem MCP 路径** — 编辑 `opencode.json`，将 `filesystem` MCP 的路径改为你自己的项目目录：

```json
"filesystem": {
  "type": "local",
  "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem",
    "/home/你的用户名/projects",
    "/home/你的用户名/work"
  ],
  "enabled": true
}
```

**Git 用户信息** — 如果尚未配置：

```bash
git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
```

---

#### 第五步：配置 API 密钥

> **密钥是如何工作的**

`opencode.json` 中通过 `{env:变量名}` 语法引用环境变量，OpenCode 启动时自动替换。配置链路如下：

```
~/.zshrc 设置环境变量           opencode.json 引用              OpenCode 运行时
────────────────────────────    ────────────────────────         ──────────────
export DEEPSEEK_API_KEY="sk-..."  →  {env:DEEPSEEK_API_KEY}  →  "sk-..."（真实 Key）
```

具体来说，`opencode.json` 中的 DeepSeek 提供商配置是这样的：

```json
"deepseek": {
  "options": {
    "apiKey": "{env:DEEPSEEK_API_KEY}",
    "baseURL": "https://api.deepseek.com/v1"
  },
  "models": {
    "deepseek-v4-pro": {
      "name": "DeepSeek V4 Pro",
      "limit": { "context": 1000000, "output": 32768 }
    },
    "deepseek-v4-flash": {
      "name": "DeepSeek V4 Flash",
      "limit": { "context": 1000000, "output": 32768 }
    }
  }
}
```

Context7 同理（MCP 配置中）：

```json
"context7": {
  "type": "remote",
  "url": "https://mcp.context7.com/mcp",
  "headers": {
    "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
  }
}
```

> **所以你只需要做一件事**：把 Key 写入 shell 配置文件，OpenCode 会自动从环境变量读取。

#### 5.1 获取 API Key

| 服务         | 作用               | 注册地址                                                                     | 费用                   |
| ------------ | ------------------ | ---------------------------------------------------------------------------- | ---------------------- |
| **DeepSeek** | 主模型，必需       | [platform.deepseek.com](https://platform.deepseek.com/) → 右上角「API Keys」 | 充值后按量计费，很便宜 |
| Context7     | 实时文档查询，可选 | [context7.com](https://context7.com/) → 注册 → Settings → API Key            | 免费额度               |

#### 5.2 写入 Shell 配置文件

打开你的 shell 配置文件。**不确定用哪个？** 先在终端运行 `echo $SHELL` 查看：

| 输出        | 配置文件路径                                      |
| ----------- | ------------------------------------------------- |
| `/bin/zsh`  | `~/.zshrc`                                        |
| `/bin/bash` | `~/.bashrc`（Linux）或 `~/.bash_profile`（macOS） |

用任意文本编辑器打开配置文件，在 **文件末尾** 添加以下内容：

```bash
# ===== OpenCode 配置 =====
# DeepSeek API Key（必需 — 主模型，不设置 OpenCode 无法工作）
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Context7 API Key（可选 — 删除或注释掉这行则无法查询最新文档）
export CONTEXT7_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

> **关键**：把 `sk-xxx...` 替换成你真实的 API Key，不要留占位符。

**具体操作示例（macOS / Linux）**：

```bash
# 用 nano 编辑器打开配置文件
nano ~/.zshrc

# 按方向键移动到文件末尾，粘贴上面的 export 语句
# 按 Ctrl+O 保存，按 Ctrl+X 退出
```

#### 5.3 让环境变量生效

```bash
# macOS / Linux：重新加载配置文件
source ~/.zshrc     # 如果用 zsh
source ~/.bashrc    # 如果用 bash

# 验证环境变量已设置（输出你的 Key 则表示成功）
echo $DEEPSEEK_API_KEY
```

> 如果 `echo $DEEPSEEK_API_KEY` 输出空行，说明配置没生效。检查：
>
> - 配置文件路径是否正确（`echo $SHELL` 确认）
> - `export` 语句是否在文件末尾且没有被注释（行首没有 `#`）
> - 是否执行了 `source` 命令

#### 5.4 Windows 用户的环境变量设置

**WSL2 用户**：按上面 Linux 的方式操作即可，配置文件在 WSL2 的 `~/.bashrc` 或 `~/.zshrc` 中。

**原生 PowerShell 用户**（不使用 WSL2）：

```powershell
# 以管理员身份打开 PowerShell，逐条执行：
[Environment]::SetEnvironmentVariable("DEEPSEEK_API_KEY", "sk-你的真实key", "User")
[Environment]::SetEnvironmentVariable("ZHIPUAI_API_KEY", "你的真实key", "User")
[Environment]::SetEnvironmentVariable("CONTEXT7_API_KEY", "你的真实key", "User")

# 关闭当前 PowerShell 窗口，重新打开，然后验证：
$env:DEEPSEEK_API_KEY
```

---

#### 第六步：（可选）安装额外工具

#### C/C++ 格式化工具

```bash
# macOS
brew install clang-format

# Linux (Debian/Ubuntu)
sudo apt-get install -y clang-format

# Windows：从 LLVM GitHub 下载安装
# https://github.com/llvm/llvm-project/releases
```

#### Playwright 浏览器（Web 测试用）

```bash
cd ~/.config/opencode
npx playwright install chromium
```

> 不需要 Web 测试可以跳过，不影响 OpenCode 正常使用。

---

#### 第七步：启动并验证

#### 7.1 首次启动

```bash
opencode
```

首次启动会：

1. 加载 `~/.config/opencode/opencode.json` 主配置
2. 加载 `AGENTS.md` 系统指令
3. 初始化插件（superpowers、oh-my-openagent 等）
4. 连接 MCP 服务（GitNexus、Context7 等）

启动成功后，你会看到一个 TUI（终端界面），底部有输入提示。

#### 7.2 运行验证命令

在 OpenCode 的输入框中依次输入以下命令，检查各项功能是否正常：

| 命令      | 作用              | 预期结果                                                                |
| --------- | ----------------- | ----------------------------------------------------------------------- |
| `/mcp`    | 列出 MCP 服务状态 | 看到 gitnexus、context7、playwright 等服务，状态为 ✓ connected 或已启用 |
| `/agent`  | 列出可用智能体    | 看到 sisyphus、oracle、prometheus、explore、librarian 等                |
| `/skills` | 列出可用技能      | 看到 docx、pdf、code-review、customize-opencode 等数十个技能            |

**正常情况**：所有命令都有输出，没有红色报错。

**如果某个 MCP 服务显示 ❌ 或 disconnected**：不影响基本使用。常见原因：

- `gitnexus` — 需要先安装 GitNexus CLI 并索引项目
- `playwright` — 需要先执行 `npx playwright install chromium`
- `context7` — 需要设置 `CONTEXT7_API_KEY` 环境变量

#### 7.3 简单功能测试

在 OpenCode 中输入一段话测试模型是否正常工作：

```
你好，请用中文回复：1+1 等于几？
```

如果 AI 正常回复，说明 DeepSeek API Key 配置正确。

---

#### 故障排查

#### OpenCode 无法启动 / 闪退

```bash
# 调试模式 1：跳过项目级配置，仅加载全局配置
OPENCODE_DISABLE_PROJECT_CONFIG=1 opencode

# 调试模式 2：跳过所有外部插件
OPENCODE_PURE=1 opencode

# 调试模式 3：完全跳过项目配置
OPENCODE_DISABLE_PROJECT_CONFIG=1 OPENCODE_PURE=1 opencode
```

#### 提示 JSON 解析错误

`opencode.json` 或 `oh-my-openagent.json` 有语法错误：

```bash
# 验证 JSON 语法
python3 -m json.tool ~/.config/opencode/opencode.json > /dev/null && echo "JSON 有效" || echo "JSON 无效"
python3 -m json.tool ~/.config/opencode/oh-my-openagent.json > /dev/null && echo "JSON 有效" || echo "JSON 无效"
```

#### 模型调用报错 / 无响应

1. 检查环境变量：`echo $DEEPSEEK_API_KEY` — 应输出你的 Key
2. 检查 Key 是否有效：[platform.deepseek.com](https://platform.deepseek.com/) → API Keys → 查看状态
3. 检查账户余额是否充足

#### 插件安装失败

```bash
cd ~/.config/opencode
rm -rf node_modules package-lock.json
npm install
```

## 目录结构

```
.
├── opencode.json              # 主配置：模型、MCP、插件、权限、格式化
├── AGENTS.md                  # 系统指令（每会话自动加载）
├── oh-my-openagent.json        # 智能体模型分配与分类配置
├── tui.json                   # 当前终端界面配置（主题色 + 行为设置）
├── README.md
│
├── agents/                    # 自定义智能体定义（Markdown + YAML frontmatter）
├── skills/                    # 28 个分类技能
│   ├── analysis/              # 10 个（9 哲学流派 + PDF 深度分析）
│   ├── automation/            # 1 个（文件整理）
│   ├── development/           # 12 个（代码审查、MCP 构建、Web 测试、编辑器配置等）
│   ├── document/              # 4 个（docx、pptx、pdf、xlsx）
│   └── goal-loop/             # 1 个（目标循环工作流）
├── skill/                     # GitNexus 技能（扁平结构，7 个）
│   ├── gitnexus-cli/          # CLI 命令
│   ├── gitnexus-debugging/    # 调试追踪
│   ├── gitnexus-exploring/    # 代码探索
│   ├── gitnexus-guide/        # 使用指南
│   ├── gitnexus-impact-analysis/ # 影响分析
│   ├── gitnexus-pr-review/    # PR 审查
│   └── gitnexus-refactoring/  # 安全重构
│
├── themes/                    # 66 个 TUI 配色主题（JSON）
├── assets/                    # 通知音效（MP3）
├── commands/                  # 自定义斜杠命令（/goal）
├── snippet/                   # 共享代码片段
│
├── .opencode/                 # 项目级配置
│   ├── docs/                  # 39 篇中文知识库（覆盖官方文档全部内容）
│   ├── command/               # 斜杠命令定义（/context）
│   └── plugin/                # 本地插件
│
└── 配置文件:
    ├── dcp.jsonc              # DCP 配置
    ├── smart-voice-notify.jsonc # 语音通知
    └── opencode-mem.jsonc     # 记忆配置
```

## 核心配置

### 模型

使用 DeepSeek 系列作为主力：

| 模型                         | 用途                                     | 上下文窗口 |
| ---------------------------- | ---------------------------------------- | ---------- |
| `deepseek/deepseek-v4-pro`   | 主模型 / 重度任务（Oracle、Plan 等）     | 1M tokens  |
| `deepseek/deepseek-v4-flash` | 轻度任务（Explore、Quick、Librarian 等） | 1M tokens  |

### 智能体架构

| 智能体              | 模型                          | 角色                                 |
| ------------------- | ----------------------------- | ------------------------------------ |
| Sisyphus            | deepseek-v4-pro (max reason)  | 主编排器 — 分解、委派、质量控制      |
| Sisyphus-Junior     | deepseek-v4-pro (high reason) | 任务执行器 — 并行执行具体工作        |
| Prometheus          | deepseek-v4-pro (high reason) | 实施规划 — 计划编写、头脑风暴        |
| Oracle              | deepseek-v4-pro (max reason)  | 只读顾问 — 调试、架构设计、代码审查  |
| Hephaestus          | deepseek-v4-pro (high reason) | 前端与 UI — 视觉工程、Playwright、QA |
| 谛听 (Diting)       | deepseek-v4-pro (max reason)  | 佛学哲学统筹者 — 中观智慧分派分析    |
| Librarian           | deepseek-v4-flash             | 外部参考 — 文档查询、GitHub 搜索     |
| Explore             | deepseek-v4-flash             | 上下文搜索 — 代码库结构探索          |
| Metis               | deepseek-v4-pro               | 预规划顾问 — 需求分析、歧义检测      |
| Momus               | deepseek-v4-pro               | 计划审查 — 完整性、可验证性评审      |
| Atlas               | deepseek-v4-pro               | 工作区管理 — git worktree 隔离       |
| Goal Worker / Judge | v4-pro / v4-flash             | 自治目标执行循环                     |

### 分类（Category）

| 分类                 | 模型                          | 适用场景                |
| -------------------- | ----------------------------- | ----------------------- |
| `visual-engineering` | deepseek-v4-flash             | 前端、UI/UX、设计、动画 |
| `ultrabrain`         | deepseek-v4-pro (max reason)  | 高难度逻辑问题          |
| `deep`               | deepseek-v4-pro (max reason)  | 深度研究 + 端到端实现   |
| `artistry`           | deepseek-v4-pro               | 创造性问题求解          |
| `unspecified-high`   | deepseek-v4-pro (high reason) | 通用高难度任务          |
| `quick`              | deepseek-v4-flash             | 单文件修改、拼写修正    |
| `unspecified-low`    | deepseek-v4-flash             | 通用低难度任务          |
| `writing`            | deepseek-v4-pro               | 文档、技术写作          |

> 💡 **本框架模型无关**。内置配置以 DeepSeek V4 系列为默认模型，但所有智能体和分类的模型分配可在 `oh-my-openagent.json` 中一键替换。支持 OpenAI、Anthropic、Ollama 等任何 OpenAI 兼容接口。详见下方「模型更换指南」。

## 模型更换指南

如果你想使用 **OpenAI**、**Anthropic**、**Ollama 本地模型** 或其他提供商替代 DeepSeek，只需修改 **两个文件**。

### 原理

模型配置由两层组成：

```
opencode.json          →  定义「有哪些模型可用」（提供商 + API Key + 模型列表）
oh-my-openagent.json   →  定义「哪个智能体用哪个模型」（agent → model 映射）
```

更换模型需要同步修改这两层。

### 步骤一：修改 opencode.json — 添加新提供商

在 `provider` 字段中添加你的提供商，同时可以保留或删除 DeepSeek：

```json
{
  "provider": {
    // ===== 保留 DeepSeek（可选，不需要则删除整个 deepseek 块）=====
    "deepseek": {
      "options": {
        "apiKey": "{env:DEEPSEEK_API_KEY}",
        "baseURL": "https://api.deepseek.com/v1"
      },
      "models": {
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" }
      }
    },

    // ===== 示例：添加 OpenAI =====
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}",
        "baseURL": "https://api.openai.com/v1"
      },
      "models": {
        "gpt-4o": { "name": "GPT-4o" },
        "gpt-4o-mini": { "name": "GPT-4o Mini" }
      }
    },

    // ===== 示例：添加 Anthropic =====
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-5": { "name": "Claude Sonnet 4.5" },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
      }
    },

    // ===== 示例：添加本地 Ollama =====
    "ollama": {
      "options": {
        "apiKey": "ollama",
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3": { "name": "Qwen 3" },
        "llama4": { "name": "Llama 4" }
      }
    }
  }
}
```

然后设置对应的环境变量：

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
# Ollama 无需 API Key，本地运行
```

### 步骤二：修改 oh-my-openagent.json — 切换智能体模型

把所有 `deepseek/deepseek-v4-pro` 替换为你的主力模型，`v4-flash` 替换为轻量模型。格式为 `提供商/模型ID`。

**当前（DeepSeek）** → **改为 OpenAI** 的对照：

| 智能体                            | 当前模型                     | OpenAI 对应          |
| --------------------------------- | ---------------------------- | -------------------- |
| sisyphus / oracle / prometheus    | `deepseek/deepseek-v4-pro`   | `openai/gpt-4o`      |
| sisyphus-junior / explore / quick | `deepseek/deepseek-v4-flash` | `openai/gpt-4o-mini` |

改为 Anthropic 的对照：

| 智能体                            | 当前模型                     | Anthropic 对应                |
| --------------------------------- | ---------------------------- | ----------------------------- |
| sisyphus / oracle / prometheus    | `deepseek/deepseek-v4-pro`   | `anthropic/claude-sonnet-4-5` |
| sisyphus-junior / explore / quick | `deepseek/deepseek-v4-flash` | `anthropic/claude-haiku-4-5`  |

> **批量替换技巧**：在 `oh-my-openagent.json` 中全局搜索替换：
>
> - `deepseek/deepseek-v4-pro` → 你的主力模型
> - `deepseek/deepseek-v4-flash` → 你的轻量模型
>
> `categories` 字段中的模型也一并替换。

### 步骤三：验证

```bash
# 检查 JSON 语法
python3 -m json.tool ~/.config/opencode/opencode.json > /dev/null && echo "✅"
python3 -m json.tool ~/.config/opencode/oh-my-openagent.json > /dev/null && echo "✅"

# 重启 OpenCode，测试模型是否可用
opencode
```

在 OpenCode 中输入「你好」，如果正常回复即更换成功。

## 插件

| 插件                                        | 功能                                                | 用法                                                             | 备注                            |
| ------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------- |
| `superpowers`                               | 核心技能生态（brainstorming、TDD、planning 等 15+） | 自动加载，无需手动干预                                           | —                               |
| `oh-my-openagent`                           | 智能体模型分配管理                                  | 自动生效，通过 `oh-my-openagent.json` 配置                       | —                               |
| `opencode-snippets`                         | 代码片段管理                                        | `#snippet-name` 自动展开                                         | —                               |
| `opencode-mem`                              | 跨会话记忆（本地向量数据库）                        | `memory` 工具自动调用                                            | Web UI: `http://localhost:4747` |
| `opencode-pty`                              | 后台终端（dev server、watch mode）                  | `pty_spawn` 启动后台进程                                         | —                               |
| `opencode-history-search`                   | 历史会话搜索                                        | `history-search` 工具                                            | —                               |
| `opencode-dcp`                              | 动态上下文裁剪，自动清理过期上下文                  | 自动生效                                                         | —                               |
| `@capybearista/opencode-adversarial-review` | 对抗性代码审查 — 挑战实现思路和设计决策             | `/adversarial-review` [`--scope`] [`--base <ref>`] [`focus ...`] | 子代理已配 DeepSeek V4 Pro      |
| `@slkiser/opencode-quota`                   | Token 用量与 DeepSeek 账户余额查询                  | `/quota` 仪表盘 / `/quota_status` 状态                           | 余额查询正常                    |
| `opencode-power-pack`                       | 11 个 Claude Code 技能移植版                        | `skill("skill-name")` 加载后使用                                 | 详见技能表                      |
| `opencode-cache-hit`                        | 缓存命中率 + 实时成本（侧边栏）                     | 侧边栏面板，读 `provider.cost` 定价                              | DeepSeek 定价准确 ✅            |
| `opencode-snip`                             | Shell 输出精简，节省 Token 60-90%                   | 自动给 git/npm/docker/go/cargo 加 `snip` 前缀                    | ⚠️ 需 `brew install snip`       |
| `loreish`                                   | 古爱尔兰语语言模型扩展                              | 自动加载                                                         | 本地自定义插件                  |
| `deepseek-balance`                          | DeepSeek 负载均衡                                   | 自动生效                                                         | 本地自定义插件                  |

> ⚠️ **`opencode-snip`** 必须先安装 CLI 依赖，否则插件加载失败：
>
> ```bash
> brew install snip
> ```

## MCP 服务

| 服务                | 类型 | 用途                                         |
| ------------------- | ---- | -------------------------------------------- |
| GitNexus            | 本地 | 代码知识图谱 — 分析、影响评估、PR 审查、重构 |
| Context7            | 远程 | 实时文档查询（React、Next.js、Tailwind 等）  |
| Sequential Thinking | 本地 | 复杂推理逐步分解                             |
| gh_grep             | 远程 | GitHub 百万仓库代码搜索                      |
| Playwright          | 本地 | 浏览器自动化与端到端测试                     |
| Filesystem          | 本地 | 工作区外目录文件操作                         |

## 格式化

| 工具         | 适用文件                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| Prettier     | `.js`, `.ts`, `.jsx`, `.tsx`, `.json`, `.css`, `.html`, `.md`, `.yaml`, `.yml`, `.vue`, `.mjs`, `.cjs` |
| clang-format | `.c`, `.cpp`, `.h`, `.hpp`, `.cc`, `.cxx`, `.hh`, `.hxx`                                               |
| gofmt        | `.go`                                                                                                  |
| rustfmt      | `.rs`                                                                                                  |

## 约定

- **文件/目录命名**: kebab-case
- **JSON 键名**: snake_case
- **Git 提交**: 约定式提交（中文 `<type>: <emoji> <subject>`）
- **Markdown**: ATX 标题（`#`），CommonMark
- **Python**: 2 空格缩进，UTF-8，推荐类型注解

## 知识库

完整的中文 OpenCode 知识库位于 [.opencode/docs/](.opencode/docs/) — 39 篇文档，覆盖：

- 快速开始、安装、配置
- 智能体（Agents）、MCP 服务
- 技能（Skills）、插件（Plugins）
- 斜杠命令、快捷键
- 会话管理、高级用法
- 故障排查、FAQ

## 相关链接

- [OpenCode 官方文档](https://opencode.ai/docs/)
- [OpenCode GitHub](https://github.com/anomalyco/opencode)
- [配置 Schema](https://opencode.ai/config.json)