nekodemy

文档维护与同步指南

使用 Cursor 等 AI 编辑器高效维护 nekodemy 文档项目，通过关键提示词模板快速同步文档与 N.E.K.O 项目代码，保持文档准确性和一致性。

📋 目录

文档项目概述

nekodemy 项目结构

nekodemy 是 N.E.K.O 项目的文档教程集合，包含：

nekodemy/
├── 01-getting-started.md          # 环境搭建指南
├── 02-git-github-guide.md         # Git 与 GitHub 指南
├── 03-project-structure.md        # 项目架构与目录结构
├── 04-development-basics.md       # 开发实战入门
├── 05-frontend-development.md     # 前端开发教程
├── 06-backend-development.md      # 后端开发教程
├── 07-document-maintenance.md     # 文档维护与同步指南（本文档）
├── 08-faq.md                      # 常见问题
└── README.md                      # 项目导航

文档维护目标

  1. 保持同步：确保文档与 N.E.K.O 项目代码一致
  2. 去重优化：避免文档间重复内容，使用引用链接
  3. 结构清晰：保持文档结构清晰易读
  4. 及时更新：当 N.E.K.O 项目变化时及时更新文档

使用 AI 编辑器维护文档

推荐使用 Cursor（基于 VS Code，专为 AI 辅助设计）来维护文档项目。

基本操作

  1. 打开文档项目：cd /path/to/nekodemy && cursor .
  2. 使用 Chat（Cmd/Ctrl + L）：询问问题、请求更新文档
  3. 使用 Composer（Cmd/Ctrl + I）：批量更新多个文档、同步引用链接

关键提示词模板

1. 根据 N.E.K.O 项目更新文档

更新项目结构文档

@03-project-structure.md 根据 N.E.K.O 项目更新本文档

请：
1. 检查 N.E.K.O 项目的实际目录结构
2. 对比文档中的结构描述
3. 更新不一致的部分
4. 添加新增的目录和文件
5. 删除不存在的目录和文件
6. 确保所有路径和文件名正确

更新技术栈版本

根据 N.E.K.O 项目的实际依赖更新所有文档中的技术栈版本

请检查：
- pyproject.toml 中的 Python 版本
- package.json 中的前端依赖版本
- 更新所有文档中提到的版本号

更新代码示例

@06-backend-development.md 根据 N.E.K.O 项目的 main_server.py 更新所有代码示例

请：
1. 检查实际使用的框架（FastAPI）
2. 更新所有路由示例为 FastAPI 格式
3. 更新异步处理示例
4. 确保代码可以直接运行

2. 文档去重和引用

去重并添加引用

@04-development-basics.md 去重并引用 01-03 已存在内容

请：
1. 删除与 01-03 文档重复的内容
2. 添加引用链接指向相关文档的具体章节
3. 保留文档独有的开发实践内容
4. 确保引用链接格式正确

检查重复内容

检查所有文档之间的重复内容，建议如何优化

请：
1. 识别重复的章节
2. 建议哪些内容应该合并
3. 建议如何添加引用链接
4. 保持文档的完整性

3. 文档结构优化

拆分长文档

@03-project-structure.md 将"目录结构详解"部分拆分为更易读的小节

请：
1. 按功能模块拆分（如：核心服务器、后端模块、前端模块等）
2. 添加清晰的子章节标题
3. 更新目录导航
4. 保持内容完整性

优化标题和简介

@03-project-structure.md 调整更好的标题简介

请：
1. 优化主标题，使其更清晰、更有吸引力
2. 改进简介，使其更准确地描述文档内容
3. 考虑是否需要调整文件名（保持编号格式）
4. 更新 README.md 中的引用

4. 同步项目变化

框架迁移同步

N.E.K.O 项目已从 Flask 迁移到 FastAPI，请更新所有相关文档

需要更新的文档：
1. 06-backend-development.md - 更新所有代码示例和框架说明
2. 04-development-basics.md - 更新第一个任务示例
3. 03-project-structure.md - 更新框架说明
4. README.md - 更新技术栈描述

请确保：
- 所有代码示例使用 FastAPI 格式
- 所有路由示例使用 @app.get/@app.post 等装饰器
- 更新异步处理说明

目录结构变化

N.E.K.O 项目结构已变化，请更新相关文档

变化内容：
- frontend/ 目录结构已更新（使用 npm workspaces）
- 新增了 docker/ 目录
- 删除了 agent_server.py

请更新：
1. 03-project-structure.md - 更新目录结构说明
2. 05-frontend-development.md - 更新前端结构说明
3. 04-development-basics.md - 更新文件路径

5. 批量更新操作

更新所有引用链接

更新所有文档中的引用链接

请：
1. 搜索所有包含旧文档引用的文件
2. 替换为新的引用
3. 检查链接格式是否正确
4. 更新 README.md 中的导航

统一术语

将所有文档中的 "react_web" 统一替换为 "frontend"

请：
1. 搜索所有文档
2. 替换术语
3. 确保上下文正确
4. 检查是否有遗漏

更新文档编号

文档已重新编号，请更新所有内部引用

请：
1. 检查文档编号变化
2. 更新所有文档中的引用链接
3. 确保链接格式正确

6. 添加新文档

创建新文档并更新导航

创建新的文档 07-document-maintenance.md，并更新 README.md

新文档内容：
- 如何使用 AI 编辑器维护 nekodemy 文档项目
- 关键提示词模板
- 文档同步工作流

请：
1. 创建新文档
2. 更新 README.md 添加导航链接
3. 更新其他文档中的"下一步"部分

7. 检查文档一致性

检查代码示例一致性

检查所有文档中的代码示例是否与实际项目代码一致

请：
1. 对比文档中的代码示例和 N.E.K.O 项目实际代码
2. 列出不一致的地方
3. 建议如何修复

检查链接有效性

检查所有文档中的内部链接是否有效

请：
1. 检查所有 markdown 链接
2. 验证文件是否存在
3. 验证锚点是否正确
4. 列出无效链接

文档同步工作流

日常维护流程

1. 检查项目变化

检查 N.E.K.O 项目最近的变化，更新相关文档

请：
1. 检查 N.E.K.O 项目的 git 提交历史
2. 识别可能影响文档的变化
3. 列出需要更新的文档
4. 提供更新建议

2. 同步代码示例

确保所有文档中的代码示例与实际项目代码一致

请：
1. 检查主要代码文件（main_server.py, frontend/ 等）
2. 对比文档中的示例
3. 更新不一致的示例

3. 更新引用链接

检查所有文档中的内部链接，确保有效

请：
1. 验证所有文件引用
2. 验证所有章节锚点
3. 修复无效链接

版本更新流程

项目大版本更新

N.E.K.O 项目已更新到新版本，请全面更新文档

重点关注：
1. 技术栈版本变化（Python、Node.js、框架版本）
2. API 变化（新增、删除、修改的端点）
3. 目录结构变化
4. 配置方式变化
5. 依赖管理方式变化

请：
1. 列出所有需要更新的文档
2. 提供详细的更新计划
3. 执行更新

文档重构

重构文档结构，使其更清晰易读

请：
1. 分析当前文档结构
2. 识别可以改进的地方
3. 提出重构方案
4. 执行重构
5. 更新所有引用链接

常见维护任务

任务 1：同步项目结构变化

场景：N.E.K.O 项目添加了新目录或文件

提示词：

@03-project-structure.md 根据 N.E.K.O 项目更新目录结构

新增内容：
- docker/ 目录（Docker 部署相关）
- specs/ 目录（打包配置）

请：
1. 添加新目录的说明
2. 更新目录树结构
3. 添加相关模块说明

任务 2：更新技术栈说明

场景：项目升级了依赖版本

提示词：

更新所有文档中的技术栈版本号

变化：
- React: 18.x → 19.1.1
- FastAPI: 0.100 → 0.115.9
- Python: 3.11 → 3.11+（支持 3.12）

请更新：
1. 03-project-structure.md 的项目概览
2. 05-frontend-development.md 的技术栈说明
3. 06-backend-development.md 的框架说明
4. README.md 的技术栈描述

任务 3：修复文档错误

场景：发现文档中的错误信息

提示词：

修复 06-backend-development.md 中的错误

问题：
- 第 50 行：提到了 Flask，应该改为 FastAPI
- 第 120 行：路由示例使用了 Flask 格式，应该改为 FastAPI

请：
1. 修复所有错误
2. 确保代码示例正确
3. 检查是否还有其他类似错误

任务 4：优化文档可读性

场景：文档过长或结构不清晰

提示词：

优化 05-frontend-development.md 的可读性

请：
1. 将长章节拆分为多个子章节
2. 添加清晰的标题层级
3. 更新目录导航
4. 保持内容完整性

任务 5：添加新功能文档

场景：N.E.K.O 项目添加了新功能

提示词：

N.E.K.O 项目新增了 Docker 部署功能，请更新相关文档

请：
1. 在 03-project-structure.md 中添加 docker/ 目录说明
2. 在 01-getting-started.md 中添加 Docker 部署选项
3. 创建或更新相关章节
4. 更新 README.md 的导航

最佳实践

提示词编写技巧

  1. 明确指定文件
    • ✅ 好：@03-project-structure.md 根据 N.E.K.O 项目更新
    • ❌ 不好：更新项目结构文档
  2. 提供具体上下文
    • ✅ 好：N.E.K.O 项目已从 Flask 迁移到 FastAPI，请更新 06-backend-development.md
    • ❌ 不好：更新后端文档
  3. 明确要求
    • ✅ 好：去重并引用 01-03 已存在内容，添加引用链接
    • ❌ 不好：优化文档
  4. 指定范围
    • ✅ 好：更新 01-04 文档中的环境配置说明
    • ❌ 不好：更新所有文档

使用 @ 符号引用文件

Cursor 支持使用 @文件名 引用文件，AI 可以读取文件内容：

@03-project-structure.md 根据实际项目更新本文档

使用 Composer 进行批量操作

对于需要更新多个文件的任务，使用 Composer（Cmd/Ctrl + I）：

更新所有文档中的技术栈版本号：
- React: 18.x → 19.x
- FastAPI: 0.100 → 0.115

涉及文件：
- 03-project-structure.md
- 05-frontend-development.md
- 06-backend-development.md
- README.md

检查更新结果

更新后，使用以下提示词检查：

检查刚才的更新是否正确

请：
1. 验证所有代码示例格式
2. 检查引用链接是否有效
3. 确保没有遗漏的内容
4. 检查文档格式是否正确

相关文档

在维护文档之前，建议先了解：

下一步

完成文档维护后，可以：

遇到问题？ 在 GitHub Issues 提交你的问题，我们会及时解答！