OpenCode 学习注释文件追踪

记录 opencode-learn-comment/ 中的中文注释镜像文件，以及后续计划补充的目标文件。

更新记录

日期	操作	说明
2026-03-20	初始化文档	记录已注释和计划注释的文件
2026-03-20	结构调整	改为维护 opencode-learn-comment/ 注释镜像与版本状态
2026-03-26	状态整理	按实际镜像文件清单校正台账内容
2026-03-26	Skill专题	补充 skill 加载链路镜像与专题文档

---

已注释文件

当前项目版本参考 packages/opencode/package.json 中的 1.2.27，台账统一写为 v1.2.27。

infra/app.ts

• mirror: opencode-learn-comment/infra/app.ts
• version: v1.2.27
• status: active
• 作用: 基础设施入口
• 备注: 已从真实源码迁移为注释镜像副本，正式源码保持与 dev 同步

packages/opencode/src/agent/agent.ts

• mirror: opencode-learn-comment/packages/opencode/src/agent/agent.ts
• version: v1.2.27
• status: active
• 作用: Agent 核心系统，定义各种 Agent 类型及权限配置
• 备注: 已迁移为注释镜像副本，当前以 Agent 注册与权限合并流程为主

packages/opencode/src/command/index.ts

• mirror: opencode-learn-comment/packages/opencode/src/command/index.ts
• version: v1.2.27
• status: active
• 作用: 命令系统核心，定义内置命令与扩展命令加载
• 备注: 已迁移为注释镜像副本，当前以命令聚合与模板解析流程为主

packages/opencode/src/skill/skill.ts

• mirror: opencode-learn-comment/packages/opencode/src/skill/skill.ts
• version: v1.2.27
• status: active
• 作用: 技能系统核心，管理技能发现与加载
• 备注: 已迁移为注释镜像副本，当前以技能发现、扫描、缓存流程为主

packages/opencode/src/skill/index.ts

• mirror: opencode-learn-comment/packages/opencode/src/skill/index.ts
• version: v1.2.27
• status: active
• 作用: 当前 skill 主服务入口，负责发现、缓存、权限过滤与格式化
• 备注: 当前真实实现已集中到该文件，建议优先阅读

packages/opencode/src/skill/discovery.ts

• mirror: opencode-learn-comment/packages/opencode/src/skill/discovery.ts
• version: v1.2.27
• status: active
• 作用: 远程 skill 索引拉取与缓存下载
• 备注: 对应 cfg.skills.urls 场景，负责把远程 skill 转成本地目录

packages/opencode/src/session/prompt.ts

• mirror: opencode-learn-comment/packages/opencode/src/session/prompt.ts
• version: v1.2.27
• status: active
• 作用: 会话提示词系统，负责 Agent prompt 与消息组装
• 备注: 已迁移为注释镜像副本，摘要来自现有 Prompt 与会话内存学习文档

packages/opencode/src/tool/edit.ts

• mirror: opencode-learn-comment/packages/opencode/src/tool/edit.ts
• version: v1.2.27
• status: active
• 作用: 编辑工具核心，实现文件编辑、创建、删除等操作
• 备注: 已迁移为注释镜像副本，摘要来自文件替换与容错机制学习文档

packages/opencode/src/project/project.ts

• mirror: opencode-learn-comment/packages/opencode/src/project/project.ts
• version: v1.2.27
• status: active
• 作用: 项目模型解析与持久化，负责目录到 project 的映射
• 备注: 已新增注释镜像副本，重点解释 git/worktree、project id、sandbox 流程

packages/opencode/src/project/instance.ts

• mirror: opencode-learn-comment/packages/opencode/src/project/instance.ts
• version: v1.2.27
• status: active
• 作用: 实例上下文缓存与生命周期管理
• 备注: 已新增注释镜像副本，重点解释 instance 缓存、reload、dispose 流程

packages/opencode/src/tool/registry.ts

• mirror: opencode-learn-comment/packages/opencode/src/tool/registry.ts
• version: v1.2.27
• status: active
• 作用: 工具注册中心，负责汇总内建工具、插件工具、自定义工具
• 备注: 已新增注释镜像副本，重点解释 tool discovery、all()、tools() 选择逻辑

packages/opencode/src/tool/skill.ts

• mirror: opencode-learn-comment/packages/opencode/src/tool/skill.ts
• version: v1.2.27
• status: active
• 作用: skill 工具实现，按需把 skill 正文注入上下文
• 备注: 是模型真正加载 skill 内容的关键执行点

packages/opencode/src/provider/provider.ts

• mirror: opencode-learn-comment/packages/opencode/src/provider/provider.ts
• version: v1.2.27
• status: active
• 作用: provider 与模型管理中心
• 备注: 已新增镜像副本，当前先补总览摘要，后续分模块细化

packages/opencode/src/session/message-v2.ts

• mirror: opencode-learn-comment/packages/opencode/src/session/message-v2.ts
• version: v1.2.27
• status: active
• 作用: 会话消息与消息部件的核心结构定义
• 备注: 已新增镜像副本，当前先补总览摘要，后续分段细化

packages/opencode/src/session/system.ts

• mirror: opencode-learn-comment/packages/opencode/src/session/system.ts
• version: v1.2.27
• status: active
• 作用: system prompt 组装入口，向模型暴露可用 skill 列表
• 备注: 负责把 Skill.available() 格式化为系统提示词片段

---

学习文档

opencode-learn-docs/ 目录

文件	作用
项目结构概览.md	OpenCode 项目结构概览
会话内存分析.md	会话内存管理分析
文件替换核心功能详解.md	文件替换功能说明
文件写入与修改容错机制解析.md	文件写入与修改容错机制分析
会话Prompt核心机制解析.md	Prompt 机制学习笔记
Zod学习笔记.md	Zod 相关学习记录
AI-SDK更新报告.md	AI SDK 版本变动记录
Skill加载机制解析.md	Skill 发现、注入与命令映射学习文档

---

计划注释的文件

核心模块

• packages/opencode/src/session/ - 会话系统目录
• packages/opencode/src/provider/ - 提供商系统目录
• packages/opencode/src/file/ - 文件系统目录
• packages/opencode/src/tool/ - 工具系统目录
• packages/opencode/src/server/ - 服务器系统目录
• packages/opencode/src/mcp/ - MCP 协议目录
• packages/opencode/src/permission/ - 权限系统目录
• packages/opencode/src/bus/ - 事件总线目录

CLI 模块

• packages/opencode/src/cli/ - CLI 命令目录

配置模块

• packages/opencode/src/config/ - 配置系统目录

---

同步策略

由于项目更新频繁，采用以下策略：

1. 注释镜像统一放在 opencode-learn-comment/，不直接修改正式源码
2. 镜像路径严格对应真实源码路径，便于查找与同步
3. 每个镜像文件头写 source、branch、version、status、updated_at
4. 全局状态统一维护在本文件中
5. 每次同步 dev 后优先检查已注释文件是否需要更新状态

状态说明

• planned: 已列入计划，镜像文件还未建立
• active: 当前镜像可用
• stale: 上游变化较大，注释可能过期
• rebasing: 正在跟进上游重构
• done: 已完成一轮学习整理

---

备注

• 版本字段统一使用项目版本号，不再记录具体 commit
• 当前参考版本为 v1.2.27
• 本台账已于 2026-03-26 按 opencode-learn-comment/ 实际文件清单完成一次校正
• 后续新增镜像文件时，优先补文件头元信息，再更新本台账