Project Memory 项目记忆管理（增强版）
概述
此 skill 采用增强版模块化文件结构管理项目记忆，解决两个核心问题：
- 上下文溢出 - 主文件保持在30行以内，详细内容分散到子文件
- 组件重复定义 - dev-docs/ 目录记录所有组件定义，新会话必须加载
核心设计
新会话启动
↓
读取 project-memory.md（<30行）
读取 dev-docs/index.md（组件索引）
↓
AI知道已有哪些组件，不会重复创建
↓
按需读取 01-06-xxx.md 详细文档
文件结构
project-root/
└── .memory/
├── project-memory.md # 主文件（<30行，索引+当前计划）必需
├── 00-index.md # 文件导航和快速链接
├── 01-project-background.md # 项目背景（按需读取）
├── 02-requirements.md # 需求方案（按需读取）
├── 03-dev-specs.md # 开发规范（按需读取）
├── 04-tech-stack.md # 技术栈详情（按需读取）
├── 05-database-schema.md # 数据库定义（按需读取）
├── 06-project-structure.md # 项目结构（按需读取）
├── dev-docs/ # 开发文档（上下文必读）
│ ├── README.md
│ ├── index.md # 组件/API索引
│ ├── components/ # 公共组件文档
│ ├── hooks/ # 自定义Hooks文档
│ ├── utils/ # 工具函数文档
│ ├── api/ # API接口文档
│ └── database/ # 数据库表定义
└── archive/ # 归档目录
└── phase-1-xxx.md # 阶段归档（含dev-docs清单）
dev-docs/ 目录说明
为什么 dev-docs 必须上下文读取？
AI在开发过程中容易重复创建已存在的组件。通过将组件定义存储在 dev-docs/ 并在新会话时加载到上下文中，AI会知道：
- 已存在哪些组件及其完整定义
- 已有哪些工具函数可用
- 已定义哪些API接口
- 数据库表结构是什么
dev-docs 内容：
每个 .md 文件记录一个组件/函数/API/表的完整定义：
# Button 组件
## 功能
通用按钮组件，支持多种变体和尺寸。
## 代码定义
```typescript
interface ButtonProps {
variant?: 'primary' | 'secondary' | 'ghost';
size?: 'sm' | 'md' | 'lg';
disabled?: boolean;
onClick?: () => void;
children: React.ReactNode;
}
export function Button({ variant = 'primary', size = 'md', ...props }: ButtonProps) {
// 完整实现代码
}
使用示例
<Button variant="primary" size="lg" onClick={handleClick}>
提交
</Button>
参数说明
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| variant | string | 否 | 按钮样式 |
| size | string | 否 | 按钮尺寸 |
| ... | ... | ... | ... |
注意事项
- 使用 theme 中的颜色变量
- 支持键盘导航
### 主文件 (project-memory.md) 结构
```markdown
# 项目名称
## 项目索引
- **文件导航**: [查看详情](00-index.md)
- **项目背景**: [查看详情](01-project-background.md)
- **需求方案**: [查看详情](02-requirements.md)
- **开发规范**: [查看详情](03-dev-specs.md)
- **技术栈**: [查看详情](04-tech-stack.md)
- **数据库定义**: [查看详情](05-database-schema.md)
- **项目结构**: [查看详情](06-project-structure.md)
- **开发文档**: [查看 dev-docs/](dev-docs/)
## 当前阶段
**阶段 3: 商品管理** [进行中]
- [x] 任务1
- [x] 任务2
- [-] 任务3 (80%)
- [ ] 任务4
## 阶段历史
### 阶段 1: 初始化 [已完成]
- **完成时间**: 2024-01-10
- **主要成果**: 框架搭建完成
- **归档**: [查看详情](archive/phase-1-init.md)
## 最近更新
- **2024-01-26**: 完成xxx功能
核心原则
1. 新会话加载策略（优化版 - 低Token消耗）
新会话/跨会话恢复时：
必须读取（防止重复定义）：
✅ project-memory.md（<30行）
✅ dev-docs/index.md（精简索引，<30行）
可选读取（按需）：
- 01-project-background.md
- 02-requirements.md
- 03-dev-specs.md
- 04-tech-stack.md
- 05-database-schema.md
- 06-project-structure.md
- dev-docs/components/*.md（特定组件完整定义）
Token 优化效果：
| 内容 | 优化前 | 优化后 | 降低 |
|------|--------|--------|------|
| dev-docs/index.md | ~100行 | ~30行 | -70% |
| 主加载总行数 | ~130行 | ~60行 | -54% |
按需加载原则：
- index.md 仅包含：名称 + 一句话描述
- 完整定义存储在 dev-docs/{category}/{name}.md
- 需要时显式请求："查看 Button 组件完整定义"
2. dev-docs 更新规则
创建新组件时：
1. 先在 dev-docs/components/ 创建文档
2. 然后在项目中实现组件
3. 保持文档和代码同步
修改现有组件时：
1. 先更新 dev-docs/components/xxx.md
2. 然后修改组件代码
3. 智能归档
归档阶段时，自动收集 dev-docs/ 中的内容清单：
## 开发文档清单
### 公共组件 (5个)
- [Button](../dev-docs/components/Button.md)
- [Card](../dev-docs/components/Card.md)
- ...
### 数据库表 (3个)
- [users](../dev-docs/database/users.md)
- [products](../dev-docs/database/products.md)
- ...
使用场景
场景 1: 初始化项目记忆
用户: "初始化项目记忆"
Agent 操作:
1. 检查 .memory/ 目录是否存在
2. 创建增强版文件结构：
- 8个主文件（project-memory.md + 00-index.md + 01-06-xxx.md）
- dev-docs/ 目录（5个子目录 + README + index）
- archive/ 目录
3. 向用户展示创建结果
4. 说明 dev-docs/ 的使用方法
场景 2: 新会话恢复（加载dev-docs）
用户: （新会话）"继续开发"
Agent 操作:
1. 读取 .memory/project-memory.md（<30行）
2. 读取 .memory/dev-docs/index.md（组件索引）
3. 向用户汇报：
```
📁 项目：电商后台系统
📍 当前阶段：商品管理（80%）
📦 已有组件：Button, Card, Modal, Table（4个）
🔧 已有工具：formatDate, useAuth, fetchAPI（3个）
当前任务：
- [x] 商品CRUD
- [x] 图片上传
- [-] 库存管理（80%）
- [ ] 搜索功能
如需查看以下内容，请告诉我：
• 详细需求文档
• 开发规范约定
• 特定组件定义
• 数据库表结构
```
场景 3: 创建新组件
用户: "创建一个登录表单组件"
Agent 操作:
1. 检查 dev-docs/components/ 中是否已有类似组件
2. 如果没有：
- 在 dev-docs/components/LoginForm.md 中记录组件定义
- 在项目中实现 LoginForm 组件
3. 向用户说明："已在 dev-docs 中记录该组件，防止后续重复创建"
场景 4: 归档已完成阶段
用户: "归档阶段2"
Agent 操作:
1. 执行归档脚本
2. 自动收集当前 dev-docs/ 中的内容清单
3. 创建包含组件清单的归档文件
4. 更新主文件中的阶段历史
核心操作
1. 初始化项目记忆
脚本: init_memory.py
创建的文件（共8个主文件 + dev-docs目录）：
- project-memory.md（主文件，<30行）
- 00-index.md（文件导航）
- 01-06-xxx.md（6个详细文档）
- dev-docs/README.md（开发文档说明）
- dev-docs/index.md（组件索引）
- dev-docs/ 下的5个子目录
2. 读取项目记忆
脚本: read_memory.py
默认读取（防止重复定义）：
python scripts/read_memory.py
# 读取 project-memory.md + dev-docs/index.md
读取特定模块：
python scripts/read_memory.py --module 02-requirements
3. 更新项目记忆
脚本: update_memory.py
支持更新主文件或特定子文件。
自动更新 dev-docs 索引：
当在 dev-docs/ 目录下新增或修改组件、API、数据库表等文件后，运行以下命令更新索引：
# 扫描 dev-docs/ 目录并自动更新 index.md
python scripts/update_memory.py index
索引更新规则：
- 自动扫描 dev-docs/components/、hooks/、utils/、api/、database/ 目录
- 从每个 .md 文件的第一段非标题内容提取描述
- 生成包含链接的精简索引列表
- 没有文档的类别显示"暂无"
使用场景：
# 1. 创建新组件文档后
echo "# NewComponent..." > dev-docs/components/NewComponent.md
python scripts/update_memory.py index
# 2. 添加 API 文档后
echo "# /api/new-api..." > dev-docs/api/new-api.md
python scripts/update_memory.py index
# 3. 修改组件描述后（重新提取描述）
vim dev-docs/components/Button.md
python scripts/update_memory.py index
4. 归档阶段
脚本: archive_phase.py
# 归档阶段
python scripts/archive_phase.py archive --phase 2 --name "认证系统" --summary "完成JWT认证和权限管理"
# 查看归档列表
python scripts/archive_phase.py list
归档文件自动包含：
- 阶段总结
- 任务完成情况
- dev-docs清单（组件、hooks、utils、API、数据库表）
- 技术决策记录
最佳实践
上下文管理
- 新会话必须读取 dev-docs/index.md - 防止重复创建组件
- 按需读取详细文档 - 避免加载不需要的内容
- 更新时同步更新 dev-docs - 保持文档和代码一致
- 定期归档已完成阶段 - 保持主文件精简
文件大小控制
| 文件 | 建议大小 | 说明 |
|---|---|---|
| project-memory.md | <30行 | 主文件，轻量 |
| dev-docs/index.md | <100行 | 组件索引 |
| dev-docs/components/*.md | <150行 | 单个组件文档 |
| dev-docs/database/*.md | <100行 | 单表定义 |
| 01-06-xxx.md | <200行 | 详细文档 |
| archive/*.md | 不限 | 历史归档 |
跨会话恢复策略
新会话开始
↓
读取 project-memory.md（<30行）
读取 dev-docs/index.md（组件索引）
↓
汇报：项目名、当前阶段、已有组件、待办任务
↓
询问：是否需要详细背景/需求/特定组件定义？
↓
（用户明确需求后）按需读取子文件
示例对话
示例 1: 新会话恢复（加载dev-docs）
用户: （新会话）"继续开发电商项目"
Agent:
已读取项目记忆：
📁 项目：电商后台管理系统
📍 当前阶段：商品管理（阶段 3，80%）
📦 已有组件：Button, Card, Modal, Table, Form（5个）
🔧 已有Hooks：useAuth, useFetch, useModal（3个）
🛠️ 已有工具：formatDate, debounce, validate（3个）
🗄️ 已有数据库表：users, products, orders（3个）
当前进行中的任务：
- [x] 商品CRUD接口
- [x] 图片上传功能
- [-] 库存管理系统（80%）
- [ ] 商品搜索功能
- [ ] 批量操作功能
最近更新：
- 今天 14:30: 完成库存管理核心逻辑
- 昨天: 图片上传功能上线
---
如需查看以下内容，请告诉我：
• 项目背景详情
• 需求方案文档
• 开发规范约定
• 特定组件完整定义（如 Button 组件参数）
• 数据库表结构详情
示例 2: 创建新组件（检查dev-docs）
用户: "创建一个日期选择器组件"
Agent:
检查 dev-docs/components/... 发现已有：
- Button, Card, Modal, Table, Form
未找到日期选择器组件，开始创建：
1. 在 dev-docs/components/DatePicker.md 记录组件定义
2. 实现 DatePicker 组件代码
3. 更新 dev-docs/index.md 索引
✅ 已完成！组件定义已记录，后续会话将知道该组件存在。
辅助脚本
所有脚本位于 scripts/ 目录：
init_memory.py
初始化增强版项目记忆结构（8个主文件 + dev-docs目录）
read_memory.py
智能读取项目记忆
- 默认读取 project-memory.md + dev-docs/index.md
- --module 参数读取特定子文件
- --list 查看可用模块
update_memory.py
更新项目记忆，自动判断更新哪个文件
archive_phase.py
归档已完成阶段，自动收集dev-docs清单
python scripts/archive_phase.py archive --phase 2 --name "xxx" --summary "xxx"
