tomevault-io 模块文档维护指南
系统概述
项目使用分层文档系统帮助AI快速定位代码模块，避免上下文被占满：
tap-agents/prompts/module-map.md- 根索引，列出所有模块和快速定位表tap-agents/prompts/modules/[模块名].md- 各模块详细文档
前置步骤
检查
tap-agents/tap-agents-configs.md是否存在- 如果不存在：提示用户参考 配置模板 创建
- 如果存在：读取「项目类型」「项目名称」「业务模块目录」「主要类后缀」「文件扩展名」
路径约定：本文档中所有以
tap-agents/开头的路径均指项目根目录下的对应路径。
AI的文档维护职责
规则1：新增模块时
当你在「业务模块目录」/下创建新的顶层文件夹（模块）时，必须：
- 在
tap-agents/prompts/modules/下创建对应的[模块名].md - 更新
tap-agents/prompts/module-map.md，添加模块描述 - 使用下方的简洁版模板
规则2：修改现有模块时
当你修改某个模块的代码时（新增主要类、修改核心功能），必须：
- 检查该模块的文档是否存在（
tap-agents/prompts/modules/[模块名].md） - 如果文档存在但内容过时，更新对应部分
- 如果文档不存在，创建它
- 在代码修改完成后，主动提示用户："已更新 [模块名] 文档"
主要类的定义：
使用配置文件中的「主要类后缀」、「文件扩展名」配置项。
不需要更新文档的情况：
- 仅修改UI样式、颜色、字体等视觉调整
- 修复bug但不改变功能逻辑
- 调整内部实现但不影响模块职责
规则3：重大重构时
当进行跨模块重构、删除模块、移动代码时，必须：
- 更新所有涉及模块的文档
- 在
module-map.md中标记废弃的模块 - 更新模块间的依赖关系描述
- 列出文档变更清单
规则4：文档-代码不一致处理
情况A：代码比文档新（最常见） 特征：
- 代码中有新增的类，但文档没有记录
- 代码中删除了某些类，但文档还在
- 功能实现已改变，文档描述过时
AI行为：
- 信任代码，自动更新文档
- 将文档同步到代码的当前状态
- 在"最后更新"中标记：
自动同步 - YYYY-MM-DD - 提示用户：
检测到 [模块名] 文档过期，已自动更新
情况B：无法判断谁是对的 特征：
- 文档和代码描述完全矛盾
- 关键类缺失但不确定是否应该存在
- 逻辑描述模糊
AI行为：
- 停止修改，询问用户
- 清晰说明矛盾点
- 提供选项让用户决策
情况C：文档明显错误 特征：
- 文件路径错误（指向不存在的文件）
- 类名拼写错误
- 明显的复制粘贴错误
AI行为：
- 直接修复文档错误
- 在"最后更新"中标记：
修复错误 - YYYY-MM-DD
规则5：自动维护模块文档（强制执行）
这是强制性规则，必须自动执行，不需要询问用户
核心原则：代码有修改 + 文档不存在 = 必须创建文档
触发条件：
只要在 「业务模块目录」/[模块名]/ 下进行了代码修改（无论大小、类型），且该模块没有对应的文档 tap-agents/prompts/modules/[模块名].md，就必须自动创建文档。
自动执行流程：
- 完成代码修改 - 修复 Bug、新增功能、调整样式等任何修改。
- 检查文档 - 自动检查
tap-agents/prompts/modules/[模块名].md是否存在。 - 创建文档 - 若文档不存在，立即创建完整文档（使用下方模板）。
- 通知用户 - 简短说明：
已创建 [模块名] 模块文档
执行示例：
场景：修复了 UI 样式，但文档不存在
用户：修复热榜页面背景图片显示问题
AI执行：
1. 修改代码：「业务模块目录」/Moment/HotEvents/XXXViewController.「文件扩展名」
2. 检查文档：tap-agents/prompts/modules/Moment.md 不存在
3. [触发规则] 创建文档：生成 Moment.md
4. 通知用户：已创建 Moment 模块文档
最终响应："背景图片问题已修复。已创建 Moment 模块文档"
注意： 如果文档已存在，则按规则2（更新文档）或规则（忽略微小修改）处理。本规则仅针对文档缺失的情况。
简洁版文档模板
# [模块名]
## 模块简介
一句话描述这个模块的作用和职责。
## 核心功能
- 功能1：简短描述
- 功能2：简短描述
- 功能3：简短描述
## 主要类/文件
| 文件名 | 说明 | 常用叫法/位置描述 |
| ----------------------- | ---------- | ---------------------- |
| XXXViewController | 主控制器 | 主页、首页 |
| XXXTopView | 顶部视图 | 头部、顶部区域、banner |
| XXXManager | 业务管理类 | 管理器、业务层 |
## 关键词
搜索关键词1, 关键词2, 关键词3
## 常用叫法映射（可选）
记录团队内部的口语化表达和对应的代码位置：
- "头部" / "顶部区域" → XXXTopView
- "底部按钮" / "操作栏" → XXXBottomView
- "列表" / "信息流" → XXXListViewController
## 最后更新
YYYY-MM-DD
使用示例
开发场景1：新增功能
用户：帮我在GameDetail模块添加分享功能
AI工作流：
1. 实现代码功能
2. 读取 tap-agents/prompts/modules/GameDetail.md
3. 在"核心功能"中添加"分享功能"
4. 在"主要类/文件"中添加新增的类
5. 更新"最后更新"时间
6. 提示："已完成分享功能，并更新了GameDetail模块文档"
开发场景2：定位需求
用户：修改评分显示样式
AI工作流：
1. 读取 tap-agents/prompts/module-map.md 查找"评分"关键词
2. 定位到相关模块
3. 读取 tap-agents/prompts/modules/[模块名].md 找到具体文件
4. 实现修改
5. 判断：仅样式修改，不需要更新文档
文档检查脚本使用
项目提供了两个辅助脚本用于检查文档状态：
何时建议用户运行脚本：
check-docs.py - 检查缺少文档的模块
- 用户询问"有哪些模块还没有文档"
- 用户想了解文档完成度
- 开发了新模块，想确认是否创建了文档
- 使用命令行参数：
python [check-docs.py 路径] --modules-dir [TapTap 业务根目录] --docs-dir [tap-agents/prompts/modules 文档目录]
check-stale-docs.py - 检查可能过期的文档
- 用户询问"哪些文档可能过期了"
- 长时间没有更新文档系统
- 想验证文档是否与代码同步
- 使用命令行参数：
python [check-stale-docs.py 路径] --modules-dir [TapTap 业务根目录] --docs-dir [tap-agents/prompts/modules 文档目录]
AI的职责：
- 当用户明确询问文档状态时，主动建议运行相应脚本
- 脚本运行后，根据结果提供建议（如：优先更新哪些模块）
- 不要在每次对话都建议运行脚本，只在必要时提及
Converted and distributed by TomeVault — claim your Tome and manage your conversions.