oh-my-openagent 学习路线

循序渐进的学习指南，帮助初学者逐步掌握该项目。

---

阶段 1: 理解项目定位（1-2 天）

• 阅读 README.md 了解项目目标和能力
• 阅读 AGENTS.md 全面了解架构概览
• 阅读 docs/guide/overview.md 和 docs/guide/installation.md
• 理解它是 OpenCode 的插件，本质是扩展 Claude Code 的多智能体编排系统

核心产出: 能用一句话说清项目是什么、解决什么问题。

---

阶段 2: 掌握入口流程（2-3 天）

从 src/index.ts 开始，跟踪初始化流程：

src/index.ts
  → src/plugin-config.ts       配置加载+校验
  → src/create-managers.ts     管理器创建
  → src/create-tools.ts        工具注册
  → src/create-hooks.ts        钩子组合
  → src/plugin-interface.ts    插件接口组装

每个文件读一遍核心导出函数，不深入细节。目标是理解 数据流走向。

核心产出: 能画出初始化流程图，说出每个步骤的职责。

---

阶段 3: 理解配置系统（2 天）

• 阅读 src/config/schema/ 了解 Zod v4 模式定义
• 阅读 src/plugin-handlers/ 的 6 阶段配置加载管道
• 理解三级别配置合并：项目级 → 用户级 → 默认值

关键概念:

• disabled_* 数组: Set 合并（拼接+去重）
• 其余字段: override 替换
• Zod safeParse() 自动填充默认值

核心产出: 理解配置从文件到运行时对象的完整链路。

---

阶段 4: 逐个攻破核心模块（每模块 2-3 天）

建议按以下顺序学习:

顺序	模块	学习重点
1	src/agents/	11 个智能体定义、工厂模式、Agent 模型匹配
2	src/plugin/hooks/	3 层钩子系统: Session(24) + Guard(14) + Transform(5) + Continuation(7) + Skill(2)
3	src/tools/	选 2-3 个工具查看 (hashline, delegate-task, background-task)
4	src/features/background-agent/	后台任务编排核心
5	src/features/skill-mcp-manager/	MCP 三层架构
6	src/openclaw/	外部集成 (Discord/Telegram)

核心产出: 能说清每个模块的职责、输入输出、关键函数。

---

阶段 5: CLI 和发布系统（2 天）

• src/cli/ — Commander.js 子命令 (install, run, doctor, mcp-oauth)
• script/ — 构建/发布自动化脚本
• packages/ — 11 个平台二进制发布

核心产出: 理解 CLI 子命令注册方式和发布管道。

---

阶段 6: 动手实践

• 用 bun test 运行测试套件，阅读测试模式 (given/when/then)
• 选一个小功能尝试修改，例如添加新钩子或新工具
• 参考 AGENTS.md 中 “Where to look” 表格定位代码位置

建议练习:

1. 读一个已有钩子的实现，理解其生命周期
2. 尝试添加一个简单的工具并注册
3. 运行一次完整 CI 流程理解质量门禁

---

关键概念速查

概念	说明
工厂模式	所有组件用 createXXX() 创建（工具、钩子、智能体）
三层级 MCP	内置远程 → Claude Code 配置 → 技能嵌入
双降级系统	model-fallback（主动） vs runtime-fallback（被动）
钩子层级	Session(24) → Guard(14) → Transform(5) → Continuation(7) → Skill(2)
单模块原则	不创建 utils.ts 或汇总文件，每个模块通过 index.ts barrel 导出
禁止模式	无 as any、@ts-ignore、@ts-expect-error

---

推荐阅读顺序

README.md → AGENTS.md → docs/guide/overview.md
  → src/index.ts → src/plugin-config.ts
  → src/config/schema/oh-my-open-code-config.ts
  → src/agents/index.ts + src/agents/builtin-agents.ts
  → src/plugin/hooks/create-core-hooks.ts
  → src/tools/index.ts (选 2-3 个)
  → src/features/background-agent/manager.ts
  → src/features/skill-mcp-manager/manager.ts
  → src/cli/index.ts