# 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 行为约束 |