157 lines
7.8 KiB
Markdown
157 lines
7.8 KiB
Markdown
# 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 并执行写入流程。
|
||
判断标准：问题根因是否"非显而易见"——如果只看代码逻辑觉得应该没问题但运行时报错，就值得记录。
|
||
|
||
## 任务完成 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 的自迭代确认流程
|
||
|
||
### C. 收尾
|
||
先完成 checklist 中的所有写入动作，再输出面向用户的回复文本。
|
||
如执行了 B2 项（开发日志写入），在回复末尾附 `[已记录到开发日志]`。
|
||
|
||
## 目录结构约定
|
||
|
||
| 路径 | 用途 |
|
||
|------|------|
|
||
| `AGENTS.md` | 项目规则（自动注入） |
|
||
| `opencode.json` | OpenCode 配置 |
|
||
| `.opencode/skills/` | 所有 Skill 定义（Git 管理） |
|
||
| `.opencode/data/` | Agent 运行时数据（changelog/deferred/pitfalls/distillery/profile） |
|