---
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`