# NotesAgent 文档索引

本目录集中保存团队开发期间需要长期维护的架构、接口、实现、协作和问题复盘文档。文档按用途分类，避免设计约束、开发记录与故障复盘混放。

当前文档基线为 2026-09-05：第一阶段和第二阶段 A～F 工程范围已经合并到 `main`，当前可运行形态仍为 Vue/Vite Web 前端与 FastAPI AI Core。Tauri/Rust Host、Stronghold、原生多 Vault 文件系统、生产级 MCP 沙箱和 Sync Server 尚未接入。

仓库入口文档：[项目 README](../README.md)、[前端 README](../frontend/README.md)、[后端 README](../backend/README.md)。

## 目录分类

| 目录 | 内容 | 适用场景 |
| --- | --- | --- |
| [`architecture/`](architecture/) | 技术栈、阶段目标与团队分工 | 确认整体边界、模块依赖和阶段范围 |
| [`contracts/`](contracts/) | 前后端接口契约与页面需求 | 开发前对齐 DTO、路由、事件和交互 |
| [`development/`](development/) | 各模块的实现说明 | 阅读现有代码、联调和扩展功能 |
| [`guides/`](guides/) | Git、测试、注释和 CI/CD 规范 | 日常开发、提交、审阅和发布 |
| [`retrospectives/`](retrospectives/) | 审阅发现的问题与修复复盘 | 排查同类问题、撰写总结或博客 |

## architecture：架构与分工

- [AI 笔记软件技术栈说明](architecture/AI笔记软件技术栈说明-团队版-v2.3.md)
- [第一阶段分工表](architecture/第一阶段分工表.md)
- [第二阶段团队分工表](architecture/第二阶段团队分工表.md)

## contracts：契约与需求

- [后端接口契约](contracts/后端接口契约-开发版.md)
- [第二阶段接口契约](contracts/第二阶段接口契约-开发版.md)
- [前端页面需求说明](contracts/前端页面需求说明-开发版.md)
- [Tauri / Rust 桌面客户端需求说明（第三阶段，计划）](contracts/Tauri-Rust桌面客户端需求说明-第三阶段.md)

运行中的后端以 `/openapi.json` 为机器可读事实来源。接口契约用于描述设计意图、联调约束和实现状态；两者不一致时，应先确认代码行为，再在同一个 PR 中同步修正文档或实现。

## development：开发说明

- [多模态管线与模型运行开发说明](development/多模态管线与模型运行开发说明.md)
- [阶段 F 收尾验收记录](development/阶段F收尾验收记录.md)
- [AI Core 与 Agent Core 开发说明](development/AI-Core与Agent-Core开发说明.md)
- [Knowledge 与 Retrieval Core 开发说明](development/Knowledge与Retrieval-Core开发说明.md)
- [Benchmark 开发说明](development/Benchmark开发说明.md)
- [模型提供商与模型发现开发说明](development/模型提供商与模型发现开发说明.md)
- [MCP Bridge 与 Plugin Host 开发说明](development/MCP-Bridge与Plugin-Host开发说明.md)
- [独立 MCP Server 配置中心开发说明](development/独立MCP-Server配置中心开发说明.md)
- [Plugin Command 与 Settings 开发说明](development/Plugin-Command与Settings开发说明.md)
- [前端壳子与接口层开发说明](development/前端壳子与接口层开发说明.md)
- [前端写作体验优化开发说明](development/前端写作体验优化开发说明.md)
- [前端视觉与轻量动效优化开发说明](development/前端视觉与轻量动效优化开发说明.md)

## guides：团队协作规范

- [Git 使用细则](guides/Git使用细则-团队开发版.md)
- [CI/CD 细则](guides/CI-CD细则-团队开发版.md)
- [代码注释与 TODO 约定](guides/代码注释与TODO约定.md)
- [第一阶段测试验证操作手册](guides/第一阶段测试验证操作手册.md)

## retrospectives：问题与修复复盘

- [后端全面审阅问题与修复复盘](retrospectives/后端全面审阅问题与修复复盘.md)
- [Agent Core 第二阶段问题与修复复盘](retrospectives/Agent-Core第二阶段问题与修复复盘.md)
- [Knowledge 与 Retrieval Core 问题与修复复盘](retrospectives/Knowledge与Retrieval-Core问题与修复复盘.md)
- [Plugin Command 与 Settings 问题与修复复盘](retrospectives/Plugin-Command与Settings问题与修复复盘.md)
- [前端合并审阅问题与修复复盘](retrospectives/前端合并审阅问题与修复复盘.md)
- [阶段 F：Embedding 与知识库问题与解决方案](retrospectives/阶段F-Embedding与知识库问题与解决方案.md)

## 推荐阅读顺序

新成员或新阶段开始时，建议按以下顺序阅读：

1. 技术栈说明和当前阶段分工表；
2. 所负责功能对应的接口契约；
3. 对应模块的开发说明；
4. Git、CI/CD、测试及注释规范；
5. 与当前任务相关的问题复盘。

## 维护规则

- 新文档先判断用途，再放入对应分类目录，不在 `docs/` 根目录继续堆放业务文档。
- 移动或重命名文档时，同步修正仓库内全部链接，并执行本地链接检查。
- 接口、数据结构或事件格式发生变化时，同一个 PR 内同步更新契约和相关开发说明。
- 问题复盘至少写清原因、后果、解决思路、实际方案和验证结果。
- `.local-plans/` 只保存个人或阶段性的本地计划，不属于正式团队文档，不应提交到远程仓库。
- 文档中的“计划实现”和“已经实现”必须明确区分；实现状态以代码、测试和运行时契约为准。