# 追光AI — 规则体系索引

> 版本: v1.0 | 更新: 2026-10-01 | 所有 `.trae` 内容均在代码仓库 `zhuiguang-ai/.trae/` 内，跟着 git 走

## 一、这套规则解决什么问题

AI 代理**每次会话都是无状态的**（不记得上次讨论）。规则与知识库的唯一作用，就是把跨会话的持久上下文注入进来。
没有它们，AI 每次都会重新问、重新猜、重复踩坑 —— 迭代效率无法复利。

## 二、四层结构（单一事实源，互不复制）

| 层 | 载体 | 内容 | 何时加载 |
|----|------|------|---------|
| **L0 方法论** | `.trae/ai_coding_knowledge.json` | AI 编程效率的方法/工具/工作流/原则/反模式（**机器可解析**，不写业务） | 每次任务开始前 |
| **L1 协作规则** | `.trae/rules/ai_agent_rules.md`<br>`.trae/rules/ai_collaboration.md` | 启动加载顺序、小任务豁免、Plan-first 流程、验收标准、完成自动记录 | 每次任务开始前 / 收尾时 |
| **L2 工程标准** | `.trae/rules/project_rules.md` | 技术栈、数据获取、导航图片、无障碍、安全、定时任务、部署等硬规范 | 写代码时按需 |
| **L3 项目事实** | `.trae/knowledge_graph.jsonl`（MCP 源）<br>`.trae/knowledge_graph.json`（渲染版）<br>`.trae/knowledge/*`（能力/过程/成果自动记录） | 模块、部署、定时任务、仓库、约定、巡检问题等**事实** | 需要项目具体知识时 |

> ⚠️ **禁止跨层复制**：同一事实只允许有一个权威载体，其余位置只写引用。复制必然漂移（见反模式 `divergent-copies`）。

## 三、快速导航

| 我要… | 读哪个 |
|-------|--------|
| 开始一个开发任务 | [ai_agent_rules.md](ai_agent_rules.md) §0 |
| 知道怎么和 AI 协作、怎么算做完 | [ai_collaboration.md](ai_collaboration.md) |
| 查 AI 编程方法论 / 选工具 | `.trae/ai_coding_knowledge.json` |
| 查项目某个模块/部署/定时任务的事实 | `.trae/knowledge_graph.jsonl` |
| 查编码硬规范（安全/API/图片/无障碍） | [project_rules.md](project_rules.md) |
| 部署、运维、容器 | [project_rules.md](project_rules.md) §14–15（工程侧见 [specs/modules/09-devops.md](../specs/modules/09-devops.md)） |

## 四、自动化闭环

```
开发完成
   │
   ├─ npm run knowledge:update          ← 手动/收尾执行
   └─ git post-commit hook              ← 本机自动触发
          │
          ▼
   scripts/update-knowledge.mjs
          │
          ├─ .trae/knowledge/capabilities.json   能力特征（API/页面/组件/模型/脚本/任务/依赖）
          ├─ .trae/knowledge/dev_process.jsonl   开发过程（按提交追加）
          ├─ .trae/knowledge/artifacts.jsonl     模型成果（迁移/脚本/提交统计）
          └─ .trae/knowledge_graph.json / .jsonl 事实层增量 upsert
```

## 五、维护规则

1. **方法/工具层变化** → 改 `.trae/ai_coding_knowledge.json`，同步 [ai_collaboration.md](ai_collaboration.md)
2. **协作流程变化** → 改 [ai_collaboration.md](ai_collaboration.md)，同步更新 `ai_coding_knowledge.json` 中对应 `workflow:*`
3. **项目事实变化** → 跑 `npm run knowledge:update`，或直接维护 `.trae/knowledge_graph.jsonl`
4. **工程标准变化** → 改 [project_rules.md](project_rules.md)
5. **废弃而非删除**：用 `> **已废弃 (date)**` 标注并写明替代方案，保留至少一个大版本周期

## 六、版本历史

| 日期 | 版本 | 变更 |
|------|------|------|
| 2026-10-01 | v1.0 | 初始版本：建立四层结构；新增 AI 编程知识库、AI 代理规则、AI 协作流程、自动记录脚本 |