docs: 更新文档结构和内容，添加新功能说明（新增区分开发版和稳定版）

Author: xerrors

AGENTS.md

@@ -28,4 +28,4 @@ Yuxi-Know 是一个基于知识图谱和向量数据库的智能知识库系统
 
 - 如果需要新建说明文档（仅开发者可见，非必要不创建），则保存在 `docs/vibe` 文件夹下面
 - 测试脚本可以放在 test 文件夹下面，可以从 docker 中启动测试（不要使用本地 Python 环境）
-- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中
+- 代码更新后要检查文档部分是否有需要更新的地方，文档的目录定义在 `docs/.vitepress/config.mts` 中。文档应该更新最新版（`docs/latest`）

docs/.vitepress/config.mts

@@ -5,8 +5,8 @@ import markdownItTaskCheckbox from 'markdown-it-task-checkbox'
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   lang: 'zh-CN',
-  title: "Yuxi-Know Docs",
-  description: "文档中心",
+  title: "Yuxi-Know",
+  description: "语析",
   base: '/Yuxi-Know/',
   markdown: {
     config: (md) => {
@@ -17,40 +17,76 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     logo: "/favicon.svg",
     nav: [
-      { text: '快速开始', link: '/intro/quick-start' },
-    ],
-
-    sidebar: [
-      {
-        text: '简介',
-        items: [
-          { text: '什么是 Yuxi-Know？', link: '/intro/project-overview' },
-          { text: '快速开始', link: '/intro/quick-start' },
-          { text: '模型配置', link: '/intro/model-config' },
-          { text: '知识库与知识图谱', link: '/intro/knowledge-base' }
-        ]
-      },
       {
-        text: '高级配置',
+        text: 'Version',
         items: [
-          { text: '配置系统详解', link: '/advanced/configuration' },
-          { text: '文档解析', link: '/advanced/document-processing' },
-          { text: '智能体', link: '/advanced/agents-config' },
-          { text: '品牌自定义', link: '/advanced/branding' },
-          { text: '其他配置', link: '/advanced/misc' }
-        ]
-      },
-      {
-        text: '更新日志',
-        items: [
-          { text: '版本说明 v0.3', link: '/changelog/0.3-release-notes' },
-          { text: '路线图', link: '/changelog/roadmap' },
-          { text: '参与贡献', link: '/changelog/contributing' },
-          { text: '常见问题', link: '/changelog/faq' }
+          { text: 'Latest (开发版)', link: '/latest/intro/quick-start' },
+          { text: 'v0.3.0 (稳定版)', link: '/v0.3.0/intro/quick-start' }
         ]
       }
     ],
 
+    sidebar: {
+      '/latest/': [
+        {
+          text: '简介',
+          items: [
+            { text: '什么是 Yuxi-Know？', link: '/latest/intro/project-overview' },
+            { text: '快速开始', link: '/latest/intro/quick-start' },
+            { text: '模型配置', link: '/latest/intro/model-config' },
+            { text: '知识库与知识图谱', link: '/latest/intro/knowledge-base' }
+          ]
+        },
+        {
+          text: '高级配置',
+          items: [
+            { text: '配置系统详解', link: '/latest/advanced/configuration' },
+            { text: '文档解析', link: '/latest/advanced/document-processing' },
+            { text: '智能体', link: '/latest/advanced/agents-config' },
+            { text: '品牌自定义', link: '/latest/advanced/branding' },
+            { text: '其他配置', link: '/latest/advanced/misc' }
+          ]
+        },
+        {
+          text: '更新日志',
+          items: [
+            { text: '路线图', link: '/latest/changelog/roadmap' },
+            { text: '参与贡献', link: '/latest/changelog/contributing' },
+            { text: '常见问题', link: '/latest/changelog/faq' }
+          ]
+        }
+      ],
+      '/v0.3.0/': [
+        {
+          text: '简介',
+          items: [
+            { text: '什么是 Yuxi-Know？', link: '/v0.3.0/intro/project-overview' },
+            { text: '快速开始', link: '/v0.3.0/intro/quick-start' },
+            { text: '模型配置', link: '/v0.3.0/intro/model-config' },
+            { text: '知识库与知识图谱', link: '/v0.3.0/intro/knowledge-base' }
+          ]
+        },
+        {
+          text: '高级配置',
+          items: [
+            { text: '配置系统详解', link: '/v0.3.0/advanced/configuration' },
+            { text: '文档解析', link: '/v0.3.0/advanced/document-processing' },
+            { text: '智能体', link: '/v0.3.0/advanced/agents-config' },
+            { text: '品牌自定义', link: '/v0.3.0/advanced/branding' },
+            { text: '其他配置', link: '/v0.3.0/advanced/misc' }
+          ]
+        },
+        {
+          text: '更新日志',
+          items: [
+            { text: '版本说明 v0.3', link: '/v0.3.0/changelog/0.3-release-notes' },
+            { text: '参与贡献', link: '/v0.3.0/changelog/contributing' },
+            { text: '常见问题', link: '/v0.3.0/changelog/faq' }
+          ]
+        }
+      ]
+    },
+
     socialLinks: [
       { icon: 'github', link: 'https://github.com/xerrors/Yuxi-Know' }
     ],

docs/index.md

@@ -11,11 +11,11 @@ hero:
     alt: VitePress
   actions:
     - theme: brand
-      text: 快速开始
-      link: /intro/quick-start
+      text: Latest 文档
+      link: /latest/intro/quick-start
     - theme: alt
-      text: 在线演示
-      link: https://www.bilibili.com/video/BV1ETedzREgY/
+      text: v0.3.0 文档
+      link: /v0.3.0/intro/quick-start
 
 features:
   - title: 🤖 智能体与模型
@@ -32,12 +32,12 @@ features:
     details: 完整的测试套件、API 文档、监控日志，适合企业级部署和使用
 ---
 
-
-
-## 轻松部署
+## 快速开始
 
 ```sh
 docker compose up --build -d
 ```
 
-查看端口与服务说明：高级配置 → 其他配置 → 服务端口。
+## 在线演示
+
+观看视频演示：[Bilibili](https://www.bilibili.com/video/BV1DF14BTETq)

docs/advanced/agents-config.md docs/latest/advanced/agents-config.mddocs/advanced/agents-config.md renamed to docs/latest/advanced/agents-config.md

@@ -0,0 +1,125 @@
+# 参与贡献
+
+感谢所有贡献者的支持！
+
+<a href="https://github.com/xerrors/Yuxi-Know/contributors">
+    <img src="https://contributors.nn.ci/api?repo=xerrors/Yuxi-Know" alt="贡献者名单">
+</a>
+
+## 如何贡献
+
+### 1. Fork 项目
+
+在 GitHub 上 Fork 本项目到你的账户。
+
+### 2. 创建分支
+
+```bash
+git checkout -b feature/amazing-feature
+```
+
+### 3. 提交更改
+
+```bash
+git commit -m 'feat: Add some amazing feature'
+```
+
+### 4. 推送分支
+
+```bash
+git push origin feature/amazing-feature
+```
+
+### 5. 创建 PR
+
+在 GitHub 上创建 Pull Request，详细描述你的更改内容。
+
+## 开发指南
+
+### 代码规范
+
+- 遵循项目代码规范
+- Python 代码使用 `make format` 格式化
+- 使用 `make lint` 检查代码质量
+- 添加必要的测试用例
+- 更新相关文档
+
+### 提交规范
+
+使用清晰的提交信息：
+
+```
+feat: 添加新功能
+fix: 修复 bug
+docs: 更新文档
+style: 代码格式调整
+refactor: 代码重构
+test: 添加测试
+chore: 构建过程或辅助工具的变动
+```
+
+
+## 🐞 Bug 修复发布流程
+
+如果在发布 `v0.3.0` 后发现 bug：
+
+### ✅ 情况 1：main 上没有未完成的新功能
+
+直接在 main 修复并发布：
+
+```bash
+git commit -m "fix: resolve config parser crash"
+git tag -a v0.3.1 -m "Hotfix v0.3.1"
+git push origin main --tags
+```
+
+### ⚙️ 情况 2：main 上已有新功能未完成
+
+从上一个 tag 建立 hotfix 分支：
+
+```bash
+git checkout -b hotfix/0.3.1 v0.3.0
+# 修复问题
+git commit -m "fix: resolve config parser crash"
+git push origin hotfix/0.3.1
+
+# 测试后合并回 main 并打 tag
+git checkout main
+git merge --no-ff hotfix/0.3.1
+git tag -a v0.3.1 -m "Hotfix v0.3.1"
+git push origin main --tags
+
+# 删除临时分支
+git branch -d hotfix/0.3.1
+git push origin --delete hotfix/0.3.1
+```
+
+
+### 测试要求
+
+::: tip 测试
+- `make lint` / `make format` 保持代码整洁
+- `cp test/.env.test.example test/.env.test` 配置测试凭据
+- `make router-tests` 运行集成路由测试，支持 `PYTEST_ARGS="-k chat_router"`
+- `uv run --group test pytest test/api` 可直接运行 pytest（容器内）
+:::
+
+<details>
+<summary>常用命令</summary>
+
+```bash
+# 全量路由测试
+make router-tests
+
+# 仅运行知识库相关用例
+make router-tests PYTEST_ARGS="-k knowledge_router"
+
+# 不经过 Makefile，直接调用 pytest
+uv run --group test pytest test/api -vv
+```
+
+</details>
+
+## 许可证
+
+本项目基于 MIT License 开源，贡献的代码将遵循相同的许可证。

docs/advanced/branding.md docs/latest/advanced/branding.mddocs/advanced/branding.md renamed to docs/latest/advanced/branding.md

@@ -0,0 +1,41 @@
+# 常见问题
+
+以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。
+
+- 首次运行如何创建管理员？
+  - Web 首次启动会引导初始化；也可调用 API：
+    - `GET /api/auth/check-first-run` → `first_run=true` 时
+    - `POST /api/auth/initialize` 提交 `user_id` 与 `password`
+  - 无默认账号，初始化后使用创建的超级管理员登录
+
+- 镜像拉取/构建失败？
+  - 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY`
+  - 若已配置代理仍失败，可临时取消代理后重试
+  - 参考：介绍 → 快速开始 → 故障排除
+
+- 服务端口与访问地址？
+  - Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs`
+  - 端口一览与说明见：高级配置 → 其他配置 → 服务端口
+
+- Milvus/Neo4j 启动或连接失败？
+  - 重启：`docker compose up milvus -d && docker restart api-dev`
+  - Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474`
+
+- OCR 模型或服务不可用？
+  - RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型
+  - MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本
+  - 参考：高级配置 → 文档解析
+
+- 支持的文件类型与常见入库失败？
+  - 查询：`GET /api/knowledge/files/supported-types`
+  - 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪
+
+- 批量上传与转换示例？
+  - 上传入库：`uv run scripts/batch_upload.py upload --db-id <id> --directory <dir> --username <u> --password <p> --base-url http://127.0.0.1:5050/api`
+  - 参考：高级配置 → 文档解析
+
+- 登录失败被锁定？
+  - 多次失败会临时锁定账户，请根据提示等待后重试
+
+- 如何查看日志和状态？
+  - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志