huhan3000/unified-docs/USER_GUIDE.md

胡汉三千年统一文档管理系统用户指南

概述

统一文档管理系统旨在整合胡汉三千年项目中分散的文档资源，包括 core-docs、thematic-research 等目录，提供统一的文档管理、搜索、版本控制和索引功能。

系统架构

目录结构

unified-docs/
├── README.md                 # 系统概述
├── unified-index.md         # 统一索引文件
├── start-system.sh          # 系统启动脚本
├── config/
│   └── settings.json        # 系统配置
├── tools/
│   ├── doc-indexer.py       # 文档索引工具
│   ├── search-tool.py        # 搜索工具
│   ├── version-manager.py    # 版本管理工具
│   └── doc-migrator.py       # 文档迁移工具
└── .versions/               # 版本数据库

主要分类目录

1. 01-core-theory - 核心理论文档
2. 02-thematic-research - 专题研究文档
3. 03-historical-analysis - 历史分析文档
4. 04-cultural-comparison - 文化比较文档
5. 05-technical-implementation - 技术实现文档
6. 06-project-docs - 项目文档

快速开始

1. 系统状态检查

cd /home/ben/code/huhan3000/unified-docs
./start-system.sh status

2. 文档迁移（首次使用）

# 模拟迁移（预览迁移计划）
./start-system.sh migrate

# 实际迁移（需要确认）
# 系统会询问是否继续实际迁移

3. 更新文档索引

./start-system.sh index

4. 搜索文档

./start-system.sh search "音韵"
./start-system.sh search "文明传播"

5. 查看版本统计

./start-system.sh versions

工具使用说明

文档索引工具 (doc-indexer.py)

功能：自动扫描文档目录，生成统一的索引文件

使用方法：

cd /home/ben/code/huhan3000/unified-docs
python tools/doc-indexer.py

输出文件：

• unified-index.json - JSON格式索引
• unified-index.md - Markdown格式索引

搜索工具 (search-tool.py)

功能：提供全文搜索、关键词检索、标题搜索等功能

使用方法：

# 交互式搜索
python tools/search-tool.py

# 命令行搜索
python tools/search-tool.py "搜索关键词"

搜索模式：

• full_text - 全文搜索
• keyword - 关键词搜索
• title - 标题搜索
• category - 分类搜索

版本管理工具 (version-manager.py)

功能：文档版本控制、变更记录、版本比较和恢复

使用方法：

# 创建版本
python tools/version-manager.py create 文档路径 "版本注释"

# 列出版本
python tools/version-manager.py list [文档路径]

# 比较版本
python tools/version-manager.py compare 文档路径 版本1 版本2

# 恢复版本
python tools/version-manager.py restore 文档路径 版本号

# 查看统计
python tools/version-manager.py stats

# 批量创建版本
python tools/version-manager.py batch 目录路径 "批量注释"

文档迁移工具 (doc-migrator.py)

功能：从现有目录迁移文档到统一系统

使用方法：

# 完整迁移
python tools/doc-migrator.py migrate [--dry-run]

# 仅迁移core-docs
python tools/doc-migrator.py migrate-core [--dry-run]

# 仅迁移thematic-research
python tools/doc-migrator.py migrate-thematic [--dry-run]

# 查看迁移摘要
python tools/doc-migrator.py summary

分类规则

自动分类规则

系统根据文件路径和内容关键词自动分类：

关键词	目标分类
音韵	01-core-theory/01-phonological-archaeology
文明	01-core-theory/02-civilization-diffusion
方法	01-core-theory/03-methodology
理论	01-core-theory/05-theoretical-framework
实证	02-thematic-research/01-empirical-studies
历史	03-historical-analysis/01-historical-events
文化	04-cultural-comparison/01-cross-cultural
技术	05-technical-implementation/01-tools
项目	06-project-docs/01-management

手动分类

如需手动调整分类，可以：

1. 移动文件到正确的分类目录
2. 运行索引工具更新索引
3. 创建版本记录变更

维护指南

日常维护

1. 定期更新索引：文档变更后运行索引工具
2. 版本控制：重要修改前创建版本
3. 备份：系统自动维护版本备份

故障排除

问题：搜索工具找不到文档 解决：运行索引工具更新索引

问题：版本管理工具报错 解决：检查版本数据库文件完整性

问题：迁移工具分类错误 解决：手动移动文件并更新索引

性能优化

• 索引文件较大时，使用分类过滤搜索
• 定期清理旧版本（保留30天内的版本）
• 使用批量操作减少工具调用次数

最佳实践

文档命名规范

• 使用中文描述性文件名
• 包含关键词便于自动分类
• 避免特殊字符和空格

版本管理策略

• 重大修改前创建版本
• 添加有意义的版本注释
• 定期查看版本统计

搜索优化

• 使用具体的关键词
• 结合分类过滤
• 利用标题搜索提高精度

技术支持

系统要求

• Python 3.6+
• 标准库：hashlib, json, pathlib, shutil, datetime

问题反馈

如遇系统问题，请检查：

1. 依赖包是否完整
2. 文件权限是否正确
3. 配置文件是否存在

更新日志

v1.0.0 (2025-10-30)

• 初始版本发布
• 实现基本文档管理功能
• 提供完整的工具套件

---

本指南将随系统更新而更新，请定期查看最新版本。