4.0 KiB
4.0 KiB
NotesAgent 文档索引
本目录集中保存团队开发期间需要长期维护的架构、接口、实现、协作和问题复盘文档。文档按用途分类，避免设计约束、开发记录与故障复盘混放。
目录分类
| 目录 | 内容 | 适用场景 |
|---|---|---|
architecture/ |
技术栈、阶段目标与团队分工 | 确认整体边界、模块依赖和阶段范围 |
contracts/ |
前后端接口契约与页面需求 | 开发前对齐 DTO、路由、事件和交互 |
development/ |
各模块的实现说明 | 阅读现有代码、联调和扩展功能 |
guides/ |
Git、测试、注释和 CI/CD 规范 | 日常开发、提交、审阅和发布 |
retrospectives/ |
审阅发现的问题与修复复盘 | 排查同类问题、撰写总结或博客 |
architecture：架构与分工
contracts：契约与需求
运行中的后端以 /openapi.json 为机器可读事实来源。接口契约用于描述设计意图、联调约束和实现状态；两者不一致时，应先确认代码行为，再在同一个 PR 中同步修正文档或实现。
development：开发说明
- AI Core 与 Agent Core 开发说明
- Knowledge 与 Retrieval Core 开发说明
- 模型提供商与模型发现开发说明
- 前端壳子与接口层开发说明
- 前端写作体验优化开发说明
- 前端视觉与轻量动效优化开发说明
guides：团队协作规范
retrospectives：问题与修复复盘
推荐阅读顺序
新成员或新阶段开始时，建议按以下顺序阅读：
- 技术栈说明和当前阶段分工表；
- 所负责功能对应的接口契约；
- 对应模块的开发说明；
- Git、CI/CD、测试及注释规范；
- 与当前任务相关的问题复盘。
维护规则
- 新文档先判断用途，再放入对应分类目录，不在
docs/根目录继续堆放业务文档。 - 移动或重命名文档时，同步修正仓库内全部链接，并执行本地链接检查。
- 接口、数据结构或事件格式发生变化时，同一个 PR 内同步更新契约和相关开发说明。
- 问题复盘至少写清原因、后果、解决思路、实际方案和验证结果。
.local-plans/只保存个人或阶段性的本地计划，不属于正式团队文档，不应提交到远程仓库。- 文档中的“计划实现”和“已经实现”必须明确区分；实现状态以代码、测试和运行时契约为准。