# Research 项目规则

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

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

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

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

检查 `.opencode/.init-done` 是否存在：
- **不存在** → 暂存用户原始请求，提示用户需先完成 opencode 初始化，加载 `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 使用中出现信息缺失导致错误、用户需要反复补充同类信息、或生成产物与预期系统性偏差时，必须触发自迭代流程——识别根因、向用户确认、追加到对应 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） |