项目整理

本技能定义项目整理的变更检测、维护顺序、边界约束与日志要求。

🎯 目标

• 在不重复劳动的前提下持续维护项目的文档、主题、数据等后置资源
• 保持项目资产结构清晰、可追溯、可渐进扩展
• 通过日志记录维护动作，为后续协作提供依据

🔍 变更检测（增量扫描）

执行项目整理时，首先执行增量变更检测，而不是全量维护。

范围确定

用户可能附带范围说明，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. 生成建议清单：根据变更文件关联分析，给出需要更新的建议

建议清单格式

向用户展示变更检测结果，格式如下：

📋 上次项目整理：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 仓库且存在未提交改动，先提交当前未提交版本
• 若无未提交改动，则跳过
• 快照提交信息固定格式：

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 日志记录本次裁剪动作，最后再写入本次维护日志
• 裁剪日志也属于正式日志，不能省略
• 除命中上述裁剪规则外，日志只追加，不改写历史

📝 日志格式

日志固定为单行，字段顺序如下：

YYYY-MM-DD HH:mm | kind | sum | doc | theme | data | git | todo

字段要求：

• kind：upd 表示普通维护，trim 表示日志裁剪
• sum：更新摘要，尽量控制在 20 字以内
• doc：文档变更，只写文件名、专题名或 -
• theme：主题变更，只写主题名、目录名或 -
• data：数据变更，只写数据文件名、表名或 -
• git：短提交号或 -
• todo：后续待办或 -

记录原则：

• 能用短词就不用长句，能用文件名就不用解释性段落
• 未变化字段统一写 -
• 若一次改动较多，优先记录"入口文档 / 主题 / 数据"的关键索引，不在日志中展开细节

示例：

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