opencode-ts

Opencode TypeScript

像 opencode 核心团队一样编写代码。此技能包含从仓库中提取的真实代码——完整的实现，而非抽象规则。根据你的任务，按以下工作流操作。

---

实现（新代码）

按顺序完成以下阶段：

1. 熟悉 — 代码应该放在哪里？

加载 architecture.md。查明：

• 哪个模块负责此行为
• 依赖方向允许什么
• 应遵循什么文件命名约定
• 这是新模块，还是对现有模块的扩展

2. 搜集 — 已经有哪些内容？

加载 helpers-deep-dive.md。编写任何工具函数之前：

• 检查它是否已存在于 util/、effect/、bus/、sync/ 中
• 查看用法矩阵，了解其他模块如何使用它
• 如果已存在，就直接使用。如果不存在，先内联实现——只有在多次遇到不便时才提取出来。

快速查找请参阅：primitives.md（内容更精简，仅包含导入路径和签名）

3. 构建 — 编写代码

加载与你要构建的内容相对应的参考文档：

构建内容……	加载此文档
服务模块（命名空间 + Effect 服务 + 模式 + 事件）	service-module.md
工具或工具行为修改	tool-module.md
数据库表、模式、事件、错误类型	schemas-and-state.md
服务端路由、配置、插件、项目生命周期	server-and-routes.md
测试	test-writing.md

4. 检查关卡 — 代码必须通过以下所有检查才能继续

加载 style-dna.md。如果以下任意检查未通过，必须先修复代码，再进入 Review 阶段：

• 在含义明确时使用单词变量名
• 不使用 try/catch、else 或 any，不进行不必要的解构
• 使用 const + 三元表达式，而非 let + 变更
• 使用 snake_case 的 Drizzle 字段；边界模式使用 .annotate({ identifier })，字段使用 .annotate({ description })
• DTO、事件、工具参数使用 Effect Schema（Schema.Struct/Schema.Schema.Type），而非 Zod
• 服务使用 Effect，而非普通的 async 类
• 模块以 export * as X from "." 结尾——不使用文件内的 export namespace X {}
• 差异中不包含第 7 节（“可以编译但会被拒绝的内容”）中的任何模式

任何检查未通过都不得继续。 返回第 3 阶段并修复。

5. Review 关卡 — 出现以下任一情况时，必须拒绝此差异

加载 review-voice.md。差异中不得包含以下任何内容。如有，提交前必须修复：

• 修改任务范围之外的文件
• 使用 as any 或 as unknown as 类型断言
• 自定义工具函数重复实现了社区原语或 @/util/* 帮助函数
• 应放在 models.dev 中的特定 Provider 代码
• 删除代码却未在提交中清楚说明原因
• 未解释的变量重命名或结构变更
• 核心团队会要求移除的抽象（请检查 refactoring-patterns.md）

---

重构（修改现有代码）

1. 熟悉 — 哪些内容会受到影响？

加载 architecture.md。修改之前，先梳理影响范围。

2. 研读 — 这里适用哪种模式？

加载 refactoring-patterns.md。从顶部的决策矩阵开始——将你发现的代码异味与正确的模式对应起来。然后阅读具体模式章节中的真实重构前后差异：

• 简化模式（移除不必要的抽象）
• 整合模式（Bun → Node 迁移）
• 提取模式（提取可复用的工具函数）
• 迁移模式（迁移到 Effect 服务）
• 删除模式（移除无用代码）
• 稳定化模式（修复顺序或竞争条件）
• 变体消除（移除特殊情况）

3. 收集——现有工具能否替代这段代码？

加载 helpers-deep-dive.md。最好的重构往往是用一次工具调用替换 20 行代码。

4. 检查 + 审查

与实现阶段的第 4—5 步相同：先看 style-dna.md，再看 review-voice.md。

---

关键决策（始终遵循）

• 必须使用 Effect——所有服务都使用 Context.Service / Layer / makeRuntime。不要使用普通的异步类。
• 一个模块，一个自有 barrel——编写扁平的顶层导出（schemas、Interface、Service、layer、defaultLayer），然后以 export * as X from "." 结束文件。使用方仍然写 import { X } from "@/x" → X.Service；barrel 就是命名空间。opencode 已弃用文件内的 export namespace X {}。
• 处处使用 Effect Schema——DTO、事件和工具参数使用 Schema.Struct + Schema.Schema.Type<typeof X>；在边界 schema 上使用 .annotate({ identifier })，在字段上使用 .annotate({ description })。Effect 错误使用 Schema.TaggedErrorClass。品牌 ID 使用 @opencode-ai/core/schema 中的 Newtype<Self>()("Name", Schema.String.check(...))。Zod 不再用作边界工具。
• 写入采用事件溯源——修改通过 SyncEvent.run → 投影器 → SQLite。仅非事件溯源功能可以直接写入数据库。
• 测试中不使用 mock——使用 tmpdir + Instance.provide + 真实服务。仅对外部 SDK 使用 mock。
• 变量使用单词——state、pending、info、row、cfg、tx。只有在含义确实容易混淆时才使用多词变量。

---

参考索引

文件	大小	内容
style-dna.md	18K	强制风格规则、命名、控制流、14 个审查陷阱
primitives.md	22K	快速查阅：所有工具及其导入路径和签名
helpers-deep-dive.md	~40K	完整深入讲解：所有工具、所有使用位置，以及不该使用的情况
architecture.md	~30K	模块图、依赖关系图、数据流、文件约定
service-module.md	27K	完整的 Question + Permission 实现
tool-module.md	28K	完整的工具实现、注册表、提示词循环
test-writing.md	42K	5 个完整测试文件，涵盖所有 fixture 模式
schemas-and-state.md	36K	SQL 表、Effect Schema（Struct/annotate/Newtype）、SyncEvent 流程、错误
server-and-routes.md	32K	路由、配置、插件、项目生命周期
review-voice.md	~25K	Dax + Aiden 的真实 PR 审查评论
refactoring-patterns.md	~25K	清理提交中的真实前后对比差异