62 lines
3.6 KiB
Markdown
62 lines
3.6 KiB
Markdown
# 追光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 协作流程、自动记录脚本 |
|