admin
c1a17236c0
OpenNexus 文档索引
最新：2026-09-08 验收修复与全量回归。两项已复现缺陷已修复，现有自动化测试全部通过；完整生产化验收仍未通过。原始证据见验收报告与 Sync 测试部署。
第二阶段收尾：标准 Agent/RAG Benchmark 与报告页、函数图预览、三格式快照导出及真实 Provider/MCP 结果见实现与验收记录。当前分支尚未合并，不更改下文历史 main 基线。
本目录集中保存团队开发期间需要长期维护的架构、接口、实现、协作和问题复盘文档。文档按用途分类，避免设计约束、开发记录与故障复盘混放。
当前第三阶段分支已实现 Tauri/Rust 原生 Vault、Sync v1 和签名社区目录原型，并开始接入受认证的 Sidecar 与 Stronghold。生产插件隔离、完整同步客户端和发布门禁仍未完成，不能作为发布候选。最新状态见OpenNexus 生产化实施进度，历史证据见第三阶段实施与验收记录。
仓库入口文档：项目 README、前端 README、后端 README。
目录分类
| 目录 | 内容 | 适用场景 |
|---|---|---|
architecture/ |
技术栈、阶段目标与团队分工 | 确认整体边界、模块依赖和阶段范围 |
contracts/ |
前后端接口契约与页面需求 | 开发前对齐 DTO、路由、事件和交互 |
development/ |
各模块的实现说明 | 阅读现有代码、联调和扩展功能 |
guides/ |
Git、测试、注释和 CI/CD 规范 | 日常开发、提交、审阅和发布 |
retrospectives/ |
审阅发现的问题与修复复盘 | 排查同类问题、撰写总结或博客 |
architecture：架构与分工
contracts：契约与需求
- 后端接口契约
- 第二阶段接口契约
- 前端页面需求说明
- Tauri / Rust 桌面客户端需求说明（第三阶段，计划）
- Rust Host v1 预览契约
- Sync Protocol v1 契约
- Community Catalog v1 契约
运行中的后端以 /openapi.json 为机器可读事实来源。接口契约用于描述设计意图、联调约束和实现状态；两者不一致时，应先确认代码行为，再在同一个 PR 中同步修正文档或实现。
development：开发说明
guides：团队协作规范
retrospectives：问题与修复复盘
- 后端全面审阅问题与修复复盘
- Agent Core 第二阶段问题与修复复盘
- Knowledge 与 Retrieval Core 问题与修复复盘
- Plugin Command 与 Settings 问题与修复复盘
- 前端合并审阅问题与修复复盘
- 阶段 F：Embedding 与知识库问题与解决方案
推荐阅读顺序
新成员或新阶段开始时，建议按以下顺序阅读：
- 技术栈说明和当前阶段分工表；
- 所负责功能对应的接口契约；
- 对应模块的开发说明；
- Git、CI/CD、测试及注释规范；
- 与当前任务相关的问题复盘。
维护规则
-
新文档先判断用途，再放入对应分类目录，不在
docs/根目录继续堆放业务文档。 -
移动或重命名文档时，同步修正仓库内全部链接，并执行本地链接检查。
-
接口、数据结构或事件格式发生变化时，同一个 PR 内同步更新契约和相关开发说明。
-
问题复盘至少写清原因、后果、解决思路、实际方案和验证结果。
-
.local-plans/只保存个人或阶段性的本地计划，不属于正式团队文档，不应提交到远程仓库。 -
文档中的“计划实现”和“已经实现”必须明确区分；实现状态以代码、测试和运行时契约为准。