215 lines
12 KiB
Markdown
215 lines
12 KiB
Markdown
# 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 使用中出现信息缺失导致错误、用户需要反复补充同类信息、或生成产物与预期系统性偏差时，必须触发自迭代流程——识别根因、向用户确认、追加到对应 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） |
|