a27e3b8e43
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
186 lines
7.4 KiB
Markdown
186 lines
7.4 KiB
Markdown
---
|
||
name: project-memory
|
||
description: 项目整理 — 整理项目文档、主题、数据等后置资源，保持项目资产清晰可追溯
|
||
---
|
||
|
||
# 项目整理
|
||
|
||
本技能定义项目整理的变更检测、维护顺序、边界约束与日志要求。
|
||
|
||
## 🎯 目标
|
||
|
||
- 在不重复劳动的前提下持续维护项目的文档、主题、数据等后置资源
|
||
- 保持项目资产结构清晰、可追溯、可渐进扩展
|
||
- 通过日志记录维护动作，为后续协作提供依据
|
||
|
||
## 🔍 变更检测（增量扫描）
|
||
|
||
执行项目整理时，首先执行**增量变更检测**，而不是全量维护。
|
||
|
||
### 范围确定
|
||
|
||
用户可能附带范围说明，Agent 需按以下优先级确定扫描范围：
|
||
|
||
1. **用户明确指定范围**：用户直接点明了目标，例如：
|
||
- "帮我整理一下首页相关的文档"→ 仅扫描首页原型及其关联资源
|
||
- "同步一下主题和数据"→ 仅扫描 `src/themes/` 和 `src/database/`
|
||
- "更新 xxx-page 的文档"→ 仅扫描该原型及其关联文档
|
||
2. **用户模糊描述**：用户给出了方向但未精确指定，例如：
|
||
- "最近改的那些页面帮我整理一下"→ 按时间戳扫描最近变更的原型/组件
|
||
- "把文档都更新一下"→ 扫描所有文档及其关联的原型变更
|
||
3. **用户未指定范围（默认）**：执行全量增量扫描（见下方默认检测流程）
|
||
|
||
### 默认检测流程
|
||
|
||
当用户未指定范围时，执行以下默认流程：
|
||
|
||
1. **读取上次执行时间**：从 `src/docs/memory-log.md` 中获取最后一条日志的时间戳
|
||
2. **扫描变更文件**：以该时间戳为基准，检测自上次执行以来发生变更的文件
|
||
- 默认扫描范围：`src/components/`、`src/prototypes/`、`src/themes/`、`src/database/`、`src/docs/`、`src/common/`
|
||
- 使用 `find` 或 `git diff --name-only` 等方式获取变更文件列表
|
||
3. **分类变更**：将变更文件按类型归类
|
||
- 原型 / 组件变更（`src/prototypes/`、`src/components/`）
|
||
- 文档变更（`src/docs/`）
|
||
- 主题变更（`src/themes/`）
|
||
- 数据变更（`src/database/`）
|
||
- 公共模块变更（`src/common/`）
|
||
4. **生成建议清单**：根据变更文件关联分析，给出需要更新的建议
|
||
|
||
### 建议清单格式
|
||
|
||
向用户展示变更检测结果，格式如下：
|
||
|
||
```text
|
||
📋 上次项目整理：YYYY-MM-DD HH:mm
|
||
📝 检测到以下变更：
|
||
|
||
🔸 原型/组件变更：
|
||
- xxx-page（新增 / 修改）
|
||
- yyy-component（修改）
|
||
|
||
🔸 建议更新：
|
||
- [ ] 更新 project-overview.md 索引（新增了 xxx-page）
|
||
- [ ] 更新 page-map.md（页面结构变化）
|
||
- [ ] 同步 xxx 主题配置（关联组件已变更）
|
||
- [ ] 更新 orders.json 数据（页面数据源变化）
|
||
|
||
是否按以上建议执行？
|
||
```
|
||
|
||
### 首次执行
|
||
|
||
若 `memory-log.md` 不存在或为空（首次执行），则执行全量扫描，建议初始化所有后置资源。
|
||
|
||
## 🚦 执行边界
|
||
|
||
- 项目整理只处理页面或原型完成后的后置补充工作
|
||
- 不回头重做页面、原型或其主体实现
|
||
- 若已有文档结构不合理，可合并、拆分或补充子文档，但要保留总入口可追溯性
|
||
- 仅更新与变更文件相关的后置资源，不做无关的全量刷新
|
||
- 对用户沟通时，优先使用"我可以继续帮你整理并记住 xxx"这类自然表达
|
||
|
||
## 🧭 固定维护顺序
|
||
|
||
用户确认建议清单后，按以下顺序执行（仅执行与变更相关的步骤）：
|
||
|
||
### 1. Git 快照
|
||
|
||
- 先检查项目是否启用 git 版本管理
|
||
- 若是 git 仓库且存在未提交改动，先提交当前未提交版本
|
||
- 若无未提交改动，则跳过
|
||
- 快照提交信息固定格式：
|
||
|
||
```text
|
||
chore: snapshot before project-memory <YYYY-MM-DD HH:mm>
|
||
```
|
||
|
||
### 2. 项目说明入口
|
||
|
||
- 检查 `src/docs/project-overview.md` 是否存在
|
||
- 若不存在，则基于模板创建
|
||
- 若存在，则**仅更新与本次变更相关的部分**（如新增页面索引、调整阅读顺序等）
|
||
- `src/docs/project-overview.md` 必须保持轻量，只承担"项目总览 + 阅读索引 + 关键待办"职责
|
||
- 建议每次维护时顺手检查一次该文件行数
|
||
- 当该文件出现以下任一情况时，必须重新整理并优化：
|
||
- 文件行数已达到或超过 `1000` 行
|
||
- 明显可以拆分到专题子文档后再由总入口做索引
|
||
- 优化原则：优先采用"分包拆分 + 摘要汇总"的方式处理，保留高价值摘要，把细节迁移到专题子文档，在总入口中只保留索引、结论和必要待办；不使用单纯删减式压缩来处理主文档
|
||
- 优化目标：应通过拆分专题文档与收敛摘要，把总入口优先控制在 `800` 行以内
|
||
|
||
### 3. 子文档维护
|
||
|
||
- **仅维护与本次变更相关的专题子文档**
|
||
- 根据变更检测结果判断哪些子文档需要更新
|
||
- 优先维护以下建议文档（按需）：
|
||
- `page-map.md`
|
||
- `information-architecture.md`
|
||
- `business-flow.md`
|
||
- `data-model.md`
|
||
- `permission-model.md`
|
||
- `state-lifecycle.md`
|
||
|
||
### 4. 主题维护
|
||
|
||
- 仅在变更检测发现主题相关变更时执行
|
||
- 若项目已有主题，更新主题文档、主题索引与相关引用
|
||
- 若项目尚无主题，但当前场景需要主题支撑，则创建最小主题骨架
|
||
- 主题默认维护位置：`src/themes/`
|
||
|
||
### 5. 数据维护
|
||
|
||
- 仅在变更检测发现数据相关变更时执行
|
||
- 更新 `src/database/` 中与页面、文档、主题相关的数据
|
||
- 数据文件必须遵循 `src/database/README.md`
|
||
- 维护后需同步更新总入口中的数据索引
|
||
|
||
### 6. 维护日志
|
||
|
||
- 每次项目整理都要追加维护日志
|
||
- 日志默认文件：`src/docs/memory-log.md`
|
||
- 日志模板来源：`src/docs/templates/memory-log-template.md`
|
||
- 日志采用紧凑格式，一行一条，避免长段自然语言说明
|
||
- 当 `src/docs/memory-log.md` 达到或超过 `1000` 行时，必须先删除最旧的 `100` 行业务日志，再追加一条 `trim` 日志记录本次裁剪动作，最后再写入本次维护日志
|
||
- 裁剪日志也属于正式日志，不能省略
|
||
- 除命中上述裁剪规则外，日志只追加，不改写历史
|
||
|
||
## 📝 日志格式
|
||
|
||
日志固定为单行，字段顺序如下：
|
||
|
||
```text
|
||
YYYY-MM-DD HH:mm | kind | sum | doc | theme | data | git | todo
|
||
```
|
||
|
||
字段要求：
|
||
|
||
- `kind`：`upd` 表示普通维护，`trim` 表示日志裁剪
|
||
- `sum`：更新摘要，尽量控制在 `20` 字以内
|
||
- `doc`：文档变更，只写文件名、专题名或 `-`
|
||
- `theme`：主题变更，只写主题名、目录名或 `-`
|
||
- `data`：数据变更，只写数据文件名、表名或 `-`
|
||
- `git`：短提交号或 `-`
|
||
- `todo`：后续待办或 `-`
|
||
|
||
记录原则：
|
||
|
||
- 能用短词就不用长句，能用文件名就不用解释性段落
|
||
- 未变化字段统一写 `-`
|
||
- 若一次改动较多，优先记录"入口文档 / 主题 / 数据"的关键索引，不在日志中展开细节
|
||
|
||
示例：
|
||
|
||
```text
|
||
2026-03-16 14:20 | upd | 更新总览索引 | project-overview,page-map | - | orders.json | a1b2c3d | 补权限模型
|
||
2026-03-16 14:25 | trim | 删旧100行 | - | - | - | - | 保留较新记录
|
||
```
|
||
|
||
## ✨ 质量检查点
|
||
|
||
- [ ] 已执行增量变更检测并展示建议清单
|
||
- [ ] 用户已确认建议清单
|
||
- [ ] 若为 git 仓库且存在未提交改动，已先做快照提交
|
||
- [ ] 已检查或维护 `src/docs/project-overview.md`（仅变更相关部分）
|
||
- [ ] 已按需调整专题子文档结构（仅变更相关部分）
|
||
- [ ] 已同步维护主题与数据（仅变更相关部分）
|
||
- [ ] 已按紧凑格式追加 `src/docs/memory-log.md`
|