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