89 lines
3.7 KiB
Markdown
89 lines
3.7 KiB
Markdown
# AI Agent 规则（启动与查询）
|
||
|
||
> 版本: v1.0 | 更新: 2026-10-01
|
||
> 相关: [README.md](README.md) · [ai_collaboration.md](ai_collaboration.md) · `../ai_coding_knowledge.json`
|
||
|
||
目的：让 AI 在本项目中**每次任务开始前按固定顺序加载上下文**，开工前就知道方法、规范与既有事实，避免重复交代与重复踩坑。
|
||
|
||
---
|
||
|
||
## §0 启动加载顺序（最高优先级）
|
||
|
||
```
|
||
1. .trae/rules/README.md ← 索引：先看有哪些层
|
||
2. .trae/ai_coding_knowledge.json ← 方法层：按 entity.type 过滤（principle/method/workflow/anti_pattern/tool）
|
||
3. .trae/rules/ai_collaboration.md ← 流程层：Plan-first / 验收标准 / 完成自动记录
|
||
4. .trae/knowledge_graph.jsonl ← 事实层：按 name / observations 关键词检索相关实体（按需，不要全量读）
|
||
5. .trae/rules/project_rules.md ← 工程标准：与本次改动相关的章节
|
||
6. 具体源码（只读相关文件）
|
||
```
|
||
|
||
**原则**：上下文是预算（见 `principle:context-budget`）。第 4、5 步**按需**加载，不要一次性灌入全部历史。
|
||
|
||
## §1 小任务豁免清单
|
||
|
||
以下任务**无需**走完整启动流程，可直接执行：
|
||
|
||
| 豁免类型 | 示例 |
|
||
|---------|------|
|
||
| 拼写修正 | 修改变量名拼写 |
|
||
| 注释/文案 | 增删注释、改中文提示文案 |
|
||
| 格式调整 | 缩进、空行、引号风格 |
|
||
| 单值配置 | 改端口号、超时时间等单个常量 |
|
||
| 纯查询 | 「XX 在哪」「XX 是什么意思」（不改代码） |
|
||
| 已给完整方案 | 用户已提供明确的文件+改法 |
|
||
|
||
## §2 非小任务：强制先查知识库
|
||
|
||
不属于 §1 的任务，开工前**必须**先检索事实层：
|
||
|
||
```
|
||
步骤1 读 .trae/rules/README.md 确定应查哪一层
|
||
步骤2 在 .trae/knowledge_graph.jsonl 中按关键词检索（name / observations）
|
||
优先匹配：实体名 > observations 关键词 > entityType 批量
|
||
步骤3 命中则读取该实体 observations，确认规范/部署/踩坑/约束
|
||
步骤4 再开始 Explore → Plan → Implement → Verify（见 ai_collaboration.md）
|
||
```
|
||
|
||
### 检索优先级
|
||
|
||
| 优先级 | 方式 | 场景 |
|
||
|--------|------|------|
|
||
| 1 | 实体名精确匹配（如 `追光AI:容器化部署`） | 已知目标实体 |
|
||
| 2 | observations 关键词（如 `cron`、`8301`、`Prisma`） | 知道主题 |
|
||
| 3 | entityType 批量（如全部 `Issue`、全部 `ScheduledTask`） | 需要某类全貌 |
|
||
|
||
### 若 Knowledge Graph Memory MCP 不可用
|
||
|
||
直接读/写 `.trae/knowledge_graph.jsonl`（JSONL，一行一实体或关系）。改动后用 `npm run knowledge:update` 同步渲染版 `.json`。
|
||
|
||
## §3 查询后输出格式
|
||
|
||
命中实体时，在回复中简述（便于复核）：
|
||
|
||
```
|
||
[KG] 命中 N 条:
|
||
- Module: 追光AI:模块(09-运维与部署)
|
||
- Issue : 追光AI:巡检问题与处理(2026-10-01)
|
||
```
|
||
|
||
## §4 行为约束
|
||
|
||
### 必须
|
||
1. 非豁免任务**必须先检索知识库**再动手
|
||
2. 发现代码与已记录规范/事实冲突时**必须指出**，不得静默按代码走
|
||
3. 遇到新踩坑/新约束，**必须**在收尾时写入知识库（见 ai_collaboration.md §4）
|
||
4. 改动涉及部署/定时任务/数据模型时，**必须**同步更新对应实体
|
||
|
||
### 禁止
|
||
1. 禁止跳过检索直接改业务代码（豁免项除外）
|
||
2. 禁止把同一事实**复制**到多个文件（只写一处 + 其余引用）
|
||
3. 禁止忽略知识库中已记录的 `Issue` 实体而重复踩同一坑
|
||
4. 禁止在未跑门禁（`npx tsc --noEmit` + `npx vitest run`）的情况下声称完成
|
||
|
||
## §5 版本历史
|
||
|
||
| 日期 | 版本 | 变更 |
|
||
|------|------|------|
|
||
| 2026-10-01 | v1.0 | 初始版本：§0 启动加载顺序 + §1 豁免 + §2 强制检索 + §4 行为约束 |
|