OpenCodeInit/AGENTS.md

Research 项目规则

AI 语言约定

• 所有思考过程、回答、代码注释均使用中文
• 专业术语和项目专有名词（Roblox API、Lua 关键字等）保持英文

阶段检查（优先级 -1，在所有自检之前）

每次会话首次响应前，Agent 必须首先完成阶段检查：

读取 .opencode/phase/current.json：

• 不存在 → 创建默认值 {"phase": "design", ...}，以设计阶段启动，提示用户当前默认阶段
• 存在 → 以 phase 字段值作为当前激活阶段

当前阶段约束后续所有行为：

• 加载任何 Skill 前，检查其 SKILL.md frontmatter 的 phases 字段
• phases 包含 "all" 或当前 phase 值时，允许加载
• 否则禁止加载该 Skill，提示用户"当前阶段 [phase] 不支持该 Skill"

阶段切换规则：

用户表述	行为
"切换到XX阶段" / "进入XX阶段"	更新 current.json 的 phase、switched_at、previous_phase；提示"已切换到 XX 阶段，下次会话生效"
"切换到XX阶段，现在就生效" / "现在就用"	更新 current.json + 立即重新执行阶段检查（重新读取 current.json，重载阶段规则），提示"已切换到 XX 阶段，当前会话已生效"

可用阶段列表：

• design — 设计阶段（默认）：game-design Skill 可用
• development — 开发阶段：所有基础设施 Skill + 开发专属 Skill
• qa — QA 阶段（预留）
• quantification — 量化阶段（预留）

设计阶段额外注入（仅 phase = "design" 时执行）： 读取 .opencode/phase/data/design/state.json（不存在则跳过）→ 如有进行中的工作流，注入当前进度 读取 .opencode/phase/data/design/design-outline.md（不存在则跳过）→ 如有已完成的设计大纲，注入"设计方向摘要"和"待明确核心问题"作为上下文

开发阶段额外注入（仅 phase = "development" 时执行）： 读取 .opencode/phase/data/design/design-outline.md（不存在则跳过）→ 如有已完成的设计大纲，注入"设计方向摘要"和"待明确核心问题"作为开发参考

会话启动自检（最高优先级）

每次会话首次响应前，Agent 必须完成以下自检序列：

0. 初始化 Sentinel 检查（必须最先执行）

检查 .opencode/.init-done 是否存在：

• 不存在 → 暂存用户原始请求，提示用户需先完成 opencode 初始化，
  1. 【强制】read .opencode/canonical-manifest.json 加载规范清单 — 必须通过 read 工具读取，不得凭记忆或 Skill 描述摘要做文件分组
  2. 加载 opencode-init Skill 并执行阶段 0→7
• 已存在 → 跳过，进入后续自检项

用户主动触发全流程的关键词：初始化opencode / opencode init / 重置 opencode / reset opencode 仅补 gitignore 的关键词：补 gitignore / 生成 gitignore / gitignore 模板

1. 开发日志上下文注入

读取 .opencode/data/changelog/changelog-headlines.md（不存在则跳过）。 如有实质内容，将全部条目作为背景知识注入上下文，帮助快速建立项目进展的位置感。

2. 延期方案匹配

读取 .opencode/data/deferred/registry.md（不存在则跳过）。 扫描 status: deferred 的条目，将 tags/related_files 与当前任务关键词匹配。 命中时简要提醒（不超过 2 行），每条每会话最多提醒一次。

3. Golden Rules 注入

读取 .opencode/data/distillery/golden-rules.md（不存在则跳过）。 如有实质条目，作为背景知识注入，自然参考，不显式提及来源。

4. 蒸馏提醒检查

读取 .opencode/data/distillery/insights.md（不存在则跳过）。 若 last_distill_date 距今超过 7 天，统计 problems.md 中未蒸馏的已解决条目，按需提醒。

5. 画像上下文注入

读取 .opencode/data/profile/project-profile.md 和 .opencode/data/profile/user-profile.md（不存在则跳过）。 如有实质内容，作为背景知识纳入考量，自然融入回复。

L3 → L2 智能上溯

当 L3 概要中的某条记录语义模糊时（无法判断与当前任务的关系），按以下步骤精准上溯：

1. 提取锚点 ID（CL-xxx）
2. 在 changelog-recent.md（L2）中搜索该 ID → 命中则读取该条目
3. 仍未消除歧义 → 在 changelog-full.md（L1）中搜索，获取行号后读取 ±20 行
4. 禁止全文读取 L1。一次上溯通常 1-3 条，不批量操作

自主定位辅助

当用户请求缺少具体文件名/模块名时，Agent 应主动利用 L3 进行推断：

• "继续做昨天那个" → 从 L3 找最近的条目，上溯 L2 获取具体文件和决策
• "那个组件有 bug" → 用 L3 关键词匹配用户描述，定位具体改动
• 无背景的独立任务 → 用 L3 判断是否与近期改动有关联

开发日志 L2 自动触发

Agent 开始处理新任务时，判断是否需要读取近期详细记录：

1. 从当前任务中提取涉及的文件路径和语义关键词
2. 与 .opencode/data/changelog/changelog-headlines.md（L3）做快速比对
3. 近期有相关模块/文件的改动记录 → 读取 .opencode/data/changelog/changelog-recent.md（L2）
4. 匹配策略：
   • 硬匹配：当前任务涉及的文件出现在 L2 条目的 affected_files 中
   • 软匹配：当前任务的语义关键词与条目的 tags 有交集
   • 任一命中即触发读取

锚点 ID 前缀约定

各子系统使用独立的锚点 ID 前缀，确保跨文件检索无歧义：

前缀	格式	所属系统	数据文件
CL-	CL-YYYYMMDD-HHMM	dev-changelog	changelog-full/recent/headlines.md
PF-	PF-YYYYMMDD-HHMM	pitfall-journal	pitfalls.md
PD-	PD-YYYYMMDD-HHMM	problem-distillery（问题追踪）	problems.md
IN-	IN-YYYYMMDD-NN	problem-distillery（蒸馏洞察）	insights.md
GR-	GR-NNN	problem-distillery（Golden Rules）	golden-rules.md
PR-	PR-YYYYMMDD-NN	profile-memory	user-profile.md, project-profile.md

其中 YYYYMMDD = 年月日，HHMM = 时分，NN = 当日序号（01 起），NNN = 递增序号（001 起）。

Skill 调度（Orchestrator）

Agent 在制定方案或执行任务时，如果发现当前任务符合以下特征之一，应加载 epee-orchestrator Skill 并执行分流：

1. 手动配置密集（批量填写配置字段等）
2. 重复模式明确（预计同类操作反复出现）
3. 手工指引过长（Agent 正在生成超过 10 步的手动操作步骤）

Registry 同步（强制）

每次创建或修改任何 Skill 后，必须更新 .opencode/skills/epee-orchestrator/registry.md。

耦合点完整性验证（强制）

每次创建新 Skill 或修改现有 Skill 的 frontmatter（name/phases/description）后，必须运行 Layer 1 静态检查：

python .opencode/skills/skill-tester/static-checks/run.py

退出码非 0 时不得视为任务完成——根据 FAIL 项提示修复 manifest、init Skill、registry 或 SKILL.md frontmatter，直到 7/7 全部通过。此规则是 Registry 同步的自动化验证层。

Skill 自迭代（强制）

当 Skill 使用中出现信息缺失导致错误、用户需要反复补充同类信息、或生成产物与预期系统性偏差时，必须触发自迭代流程——识别根因、向用户确认、追加到对应 SKILL.md 的"自迭代日志"章节。

顽固问题检测

Agent 在对话中保持对以下信号的被动感知：

• 用户表达问题未解决："还有问题"、"没解决"、"又出现了"、"不行"
• Agent 自身意识到同一问题已尝试 2 次以上仍未解决
• pitfalls 中已有记录的问题再次出现

检测到上述信号时，加载 problem-distillery Skill 并执行操作 A。

踩坑经验自动检索

Agent 在以下场景中应自动检索 .opencode/data/pitfalls/pitfalls.md：

1. 进入 Debug mode — 将错误症状与已有记录比对
2. 遇到运行时错误 — 提取错误信息关键词在"症状"字段中检索
3. 同一问题第二次出现 — 强制检索

匹配策略：硬匹配（错误关键词出现在"症状"中）、软匹配（模块/技术栈出现在"关联"中）。 命中时在分析开头提示："注意：之前遇到过类似问题 [PF-xxx]：[标题]。先排查这个方向。"

每次完成涉及 debug/修复的任务后，应加载 pitfall-journal Skill 并执行写入流程。 判断标准：问题根因是否"非显而易见"——如果只看代码逻辑觉得应该没问题但运行时报错，就值得记录。

架构方案沉淀

项目根 docs/ 目录集中存放架构方案、技术规范、项目约定等规范文档。

执行前检查（Pre-execution Check）

当 Agent 识别到当前任务涉及以下维度时，应在执行代码改动前加载 spec-docs Skill 并执行操作 A（检查是否需要创建/更新规范文档）：

触发关键词（任一命中即触发）：

• 架构：架构、重构、分层、模块划分、技术选型、目录结构、核心依赖
• 方案：设计方案、设计系统、交互规范、UI规范、界面风格、数据流、API设计、部署方案
• 规范：项目规范、编码规范、命名规范、约定、标准、编码风格、工作流

不触发的情况：纯 bug 修复、单文件小改动、临时实验代码、纯数据文件变更。

周期审查

每 7 天或每 30 条新 changelog 后，Agent 自动根据 changelog 对 docs/ 下文档进行一致性审查（spec-docs Skill 操作 B），报告遗漏/陈旧/互斥项。changelog 不可信——发现互斥时优先通过检索实际代码验证。

任务完成 Checklist（强制）

Agent 在即将输出最终回复前，必须逐项检查。跳过任何一项视为执行错误。

A. 画像信号扫描（短路版）

扫描本次对话中用户消息，检查是否出现以下触发词族：

• 个人偏好：我喜欢 / 我倾向 / 我不喜欢 / 我讨厌 / 我习惯 / 我偏好 / 以后都 / 倾向于 / 我的风格 / 太花哨 / 花里胡哨 / 看着舒服 / 简洁 / 精炼 / 轻量 / 啰嗦 / 信奉
• 项目决策：这个项目是 / 目标用户是 / 这个应用的 / 我们的用户 / 技术栈 / 架构上 / 产品方向 / 产品形态 / 定位是 / 使用场景 / 面向 / 核心竞争力 / 路线图 / 长期来看 / 最终形态

无匹配 → 跳过（thinking 应在 50 token 内结束）。有匹配 → 加载 profile-memory Skill 执行记录流程。

B. 变更检查项（仅当有代码/配置改动时）

1. 本次是否有代码/配置文件改动？（不含 .opencode/ 基础设施文件）

   • 否 → 跳过本组，进入收尾项
   • 是 → 继续

2. 是否已写入三层开发日志？

   • 否 → 立即加载 dev-changelog Skill 执行操作 A，写入 L1+L2+L3 后再输出回复
   • 是 → 继续

3. 是否修改了任何 Skill？（含 SKILL.md 内容变更）

   • 是 → 检查是否已同步 epee-orchestrator 的 registry.md，未同步则立即执行

4. 本次是否有 Skill 使用异常？（遗漏、误触、产物与预期偏差）

   • 是 → 执行 epee-orchestrator Skill 的自迭代确认流程

5. 本次改动是否涉及架构/规范/方案？

   • 检查 docs/ 下相关文档是否需要创建或同步更新
   • 需要但尚未写入 → 加载 spec-docs Skill 执行操作 C 写入/更新

C. 收尾

先完成 checklist 中的所有写入动作，再输出面向用户的回复文本。 如执行了 B2 项（开发日志写入），在回复末尾附 [已记录到开发日志]。

目录结构约定

路径	用途
AGENTS.md	项目规则（自动注入）
opencode.json	OpenCode 配置
.opencode/skills/	所有 Skill 定义（Git 管理）
.opencode/data/	Agent 运行时数据（changelog/deferred/pitfalls/distillery/profile）