AI Agent 规则（启动与查询）

版本: v1.0 | 更新: 2026-10-01 相关: README.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 行为约束

必须

非豁免任务必须先检索知识库再动手
发现代码与已记录规范/事实冲突时必须指出，不得静默按代码走
遇到新踩坑/新约束，必须在收尾时写入知识库（见 ai_collaboration.md §4）
改动涉及部署/定时任务/数据模型时，必须同步更新对应实体

禁止

禁止跳过检索直接改业务代码（豁免项除外）
禁止把同一事实复制到多个文件（只写一处 + 其余引用）
禁止忽略知识库中已记录的 Issue 实体而重复踩同一坑
禁止在未跑门禁（npx tsc --noEmit + npx vitest run）的情况下声称完成

§5 版本历史

日期	版本	变更
2026-10-01	v1.0	初始版本：§0 启动加载顺序 + §1 豁免 + §2 强制检索 + §4 行为约束

3.7 KiB Raw Blame History Unescape Escape