ben
/
huhan3000
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
huhan3000/documentation/文档系统归并优化方案.md

1164 lines
38 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 文档系统归并优化方案
## 1. 问题分析
通过对当前项目文档系统的全面分析，我们发现以下主要问题：
### 1.1 文档分散且结构重叠
- 同一主题的文档分散在多个文件夹中（如专题研究文件夹、核心研究文档、archive等）
- 存在功能重叠的目录结构（如core-theory与专题研究-理论分析部分内容重复）
- 缺少统一的文档分类标准和命名规范
### 1.2 版本管理混乱
- 存在多个版本的相似文档（如各AI模型生成的系列文档）
- 归档文件与活跃文件边界不清晰
- 缺乏明确的版本控制策略
### 1.3 检索和访问困难
- 文档量大且分散，难以快速定位所需内容
- 索引系统不完善，搜索效率低
- 缺少统一的文档入口和导航机制
### 1.4 维护成本高
- 文档更新和维护需要在多个位置同步
- 缺乏自动化工具支持大规模文档管理
- 新文档创建没有明确的存放规则
## 2. 优化目标
### 2.1 集中化与结构化
- 建立统一的文档存储结构，减少重复和冗余
- 实现按主题和功能的清晰分类体系
- 确保文档的层次结构合理且直观
### 2.2 标准化与规范化
- 制定统一的文档命名规范和格式要求
- 建立文档元数据标准（如标签、关键词、创建日期等）
- 确保文档内容的一致性和完整性
### 2.3 易检索与易访问
- 构建高效的索引和搜索系统
- 提供统一的文档入口和导航界面
- 实现按主题、关键词、作者等多维度检索
### 2.4 可维护与可扩展
- 设计易于维护和更新的文档管理流程
- 开发自动化工具支持文档处理和管理
- 确保系统能够适应未来的扩展需求
## 3. 文档分类体系
### 3.1 核心分类架构
```
/home/ben/code/huhan3000/docs/
├── 1-核心理论/
│ ├── 音韵考古学/
│ ├── 文明传播模型/
│ ├── KYM三链理论/
│ └── 爹学理论体系/
├── 2-专题研究/
│ ├── 孔子研究/
│ ├── 文化研究/
│ ├── 社会制度研究/
│ ├── 理论分析/
│ └── 历史研究/
├── 3-应用实践/
│ ├── 案例分析/
│ ├── 传播策略/
│ └── 可视化工具/
├── 4-学术成果/
│ ├── 学术论文/
│ ├── 研究报告/
│ └── 理论验证/
├── 5-资源库/
│ ├── 术语索引/
│ ├── 概念解释/
│ └── 外部参考文献/
└── 6-项目管理/
├── 项目计划/
├── 会议记录/
└── 开发文档/
```
### 3.2 文档类型定义
| 文档类型 | 描述 | 存储位置 | 命名规范 |
|---------|------|---------|----------|
| 核心理论文档 | 基础理论框架和方法论 | 1-核心理论/ | [主题]-[子主题]-理论框架.md |
| 研究报告 | 专题研究成果和分析 | 2-专题研究/ | [主题]-[具体研究点]-研究报告.md |
| 案例分析 | 理论应用案例 | 3-应用实践/案例分析/ | [案例名称]-案例分析.md |
| 学术论文 | 正式学术研究成果 | 4-学术成果/学术论文/ | [年份]-[论文标题].md |
| 索引文档 | 术语和概念索引 | 5-资源库/术语索引/ | [术语类别]-索引.md |
## 4. 归并策略
### 4.1 现有文档迁移计划
| 源目录 | 目标目录 | 处理方式 |
|--------|---------|----------|
| core-theory/ | 1-核心理论/ | 直接迁移并按主题分类 |
| 专题研究-*/ | 2-专题研究/对应子目录/ | 合并内容，保留高价值文档 |
| 核心研究文档/ | 2-专题研究/对应子目录/ | 作为主要内容来源，整合其他来源文档 |
| academic-papers/ | 4-学术成果/学术论文/ | 按论文类型重新分类 |
| 汇票/ | 2-专题研究/汇票研究/ | 合并为专题研究下的子类别 |
| 爹学整理中心/ | 1-核心理论/爹学理论体系/ | 提取核心理论内容，其余归档 |
| 胡汉三千年项目/ | 3-应用实践/工具开发/ | 保留工具和应用部分 |
### 4.2 文档合并原则
1. **内容去重**：识别并合并重复或高度相似的文档内容
2. **价值评估**：根据内容质量、完整性和相关性确定文档优先级
3. **结构一致性**：确保合并后的文档遵循统一的结构和格式
4. **引用完整性**：保留文档间的引用关系和交叉引用
5. **版本保留**：对重要文档的历史版本进行适当归档
### 4.3 元数据管理
为每个文档添加统一的元数据头部，包含以下信息：
```markdown
---
title: 文档标题
date: 创建日期
last_updated: 最后更新日期
author: 作者
tags: [标签1, 标签2, 标签3]
categories: [分类1, 分类2]
source: 原始文件路径
related_docs: [相关文档1, 相关文档2]
---
```
## 5. 索引与检索系统
### 5.1 中心化索引设计
建立以下中心化索引文档：
1. **主索引.md**：项目所有文档的总览和导航
2. **理论体系索引.md**：核心理论文档的结构化索引
3. **专题研究索引.md**：各专题研究内容的索引
4. **概念术语索引.md**：关键概念和术语的定义和引用
5. **人物索引.md**：研究中涉及的历史人物索引
6. **时间线索引.md**：按时间顺序组织的研究内容
### 5.2 检索增强策略
1. **全文检索支持**：使用文档系统支持全文检索
2. **标签体系**：建立多层级的标签体系，支持多维度筛选
3. **交叉引用**：在相关文档之间建立明确的交叉引用
4. **内容摘要**：为每个文档生成标准格式的内容摘要
5. **版本标记**：明确标识文档的版本状态和更新历史
## 6. 自动化工具开发
### 6.1 文档处理工具套件
开发以下自动化工具辅助文档管理：
1. **文档扫描与分类工具**：自动扫描并初步分类文档
2. **内容去重工具**：识别和标记重复内容
3. **元数据生成工具**：自动提取和生成文档元数据
4. **索引更新工具**：基于文档变更自动更新索引
5. **文档合并工具**：支持按规则合并多个文档
### 6.2 脚本示例：文档合并工具
```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
文档合并工具
功能：根据配置规则合并多个文档为一个合集
"""
import os
import re
import yaml
from datetime import datetime
# 加载配置
with open('merge_config.yaml', 'r', encoding='utf-8') as f:
config = yaml.safe_load(f)
# 合并文档函数
def merge_documents(source_dirs, output_file, title, introduction=""):
with open(output_file, 'w', encoding='utf-8') as out_f:
# 写入文档头部
out_f.write(f"# {title}\n\n")
out_f.write(f"*合并日期: {datetime.now().strftime('%Y-%m-%d')}*\n\n")
if introduction:
out_f.write(f"## 前言\n{introduction}\n\n")
# 遍历所有源目录
for source_dir in source_dirs:
if not os.path.exists(source_dir):
print(f"警告: 源目录 {source_dir} 不存在")
continue
# 获取并排序文档文件
doc_files = sorted([f for f in os.listdir(source_dir)
if f.endswith('.md') and not f.startswith('_')])
for doc_file in doc_files:
doc_path = os.path.join(source_dir, doc_file)
print(f"处理文件: {doc_path}")
# 读取文档内容
with open(doc_path, 'r', encoding='utf-8') as in_f:
content = in_f.read()
# 提取文档标题或使用文件名
title_match = re.search(r'^#\s+(.+)', content)
if title_match:
doc_title = title_match.group(1)
else:
doc_title = doc_file.replace('.md', '').replace('_', ' ')
# 写入章节
out_f.write(f"## {doc_title}\n\n")
# 写入内容（去除原标题行）
if title_match:
content = re.sub(r'^#\s+.+\n', '', content)
out_f.write(content)
out_f.write("\n\n---\n\n")
print(f"文档合并完成: {output_file}")
# 主执行逻辑
for merge_task in config.get('merge_tasks', []):
merge_documents(
merge_task['source_dirs'],
merge_task['output_file'],
merge_task['title'],
merge_task.get('introduction', '')
)
```
### 6.3 配置文件示例
```yaml
# merge_config.yaml
merge_tasks:
- title: "孔子研究合集"
source_dirs:
- "/home/ben/code/huhan3000/专题研究-孔子研究"
- "/home/ben/code/huhan3000/核心研究文档/孔子研究相关"
output_file: "/home/ben/code/huhan3000/docs/2-专题研究/孔子研究/孔子研究合集.md"
introduction: "本合集整合了所有孔子相关研究文档，按主题和重要性排序。"
- title: "理论分析合集"
source_dirs:
- "/home/ben/code/huhan3000/专题研究-理论分析"
- "/home/ben/code/huhan3000/core-theory/"
output_file: "/home/ben/code/huhan3000/docs/2-专题研究/理论分析/理论分析合集.md"
introduction: "本合集汇总了核心理论分析文档，是理解项目理论框架的关键资料。"
```
## 7. 实施计划
### 7.1 阶段一：准备与规划（1-2周）
1. **详细审计**：完成现有文档的全面审计和分类
2. **确定规范**：制定详细的文档命名、格式和元数据规范
3. **建立架构**：创建新的文档目录结构
4. **开发工具**：开发并测试文档处理自动化工具
### 7.2 阶段二：核心迁移（2-3周）
1. **核心理论迁移**：迁移和整合核心理论文档
2. **专题研究整合**：合并各专题研究内容
3. **建立索引**：创建初步的索引文档
4. **验证结构**：检查迁移后的文档结构和链接
### 7.3 阶段三：全面整合（3-4周）
1. **剩余文档迁移**：迁移剩余的学术论文、应用实践等文档
2. **内容优化**：优化合并后文档的内容和结构
3. **完善索引**：更新和完善索引系统
4. **自动化测试**：测试文档管理自动化工具
### 7.4 阶段四：验证与优化（1-2周）
1. **用户测试**：邀请核心团队成员测试新文档系统
2. **性能优化**：根据反馈优化文档结构和检索性能
3. **培训文档**：创建文档系统使用指南
4. **最终审核**：完成最终的质量审核和调整
## 8. 维护与更新机制
### 8.1 文档管理流程
1. **文档创建**：新文档创建必须遵循命名规范和存放位置规则
2. **审核机制**：重要文档需要经过审核才能纳入主文档库
3. **定期更新**：建立文档定期审核和更新机制
4. **归档策略**：制定旧版本文档的归档规则
### 8.2 质量控制
1. **格式检查**：使用自动化工具检查文档格式一致性
2. **链接验证**：定期验证文档间的链接有效性
3. **内容审核**：定期审核文档内容的准确性和完整性
4. **反馈收集**：建立用户反馈机制，持续改进文档质量
### 8.3 长期维护计划
1. **每周**：运行自动化工具更新索引和检查链接
2. **每月**：进行小规模文档整理和优化
3. **每季**：全面审核文档系统，调整结构和分类
4. **每年**：进行大型文档系统重构和优化
## 9. 预期效果
通过实施本优化方案，预计将实现以下效果：
1. **文档组织更加清晰**：统一的目录结构和分类体系
2. **检索效率显著提高**：完善的索引系统和多维度检索能力
3. **维护成本大幅降低**：自动化工具减少手动管理工作
4. **内容质量不断提升**：标准化的文档格式和质量控制机制
5. **团队协作更加高效**：清晰的文档管理流程和规范
本方案注重实用性和可扩展性，在保持现有文档价值的同时，建立更加科学、高效的文档管理体系，为项目的长期发展提供有力支持。
## 1. 当前文档系统分析
根据对项目的分析，目前存在以下问题：
1. **文档分散**：研究内容分散在多个专题文件夹中，查找和引用不便
2. **重复内容**：部分内容可能在多个文件中重复出现
3. **结构不一致**：不同文件夹的组织结构和命名方式不统一
4. **缺乏索引**：难以快速定位特定主题的相关内容
5. **维护困难**：随着研究深入，文档更新和管理变得复杂
## 2. 优化目标
1. 建立统一的文档组织结构
2. 创建自动化文档归并和索引工具
3. 实现内容的模块化管理
4. 建立版本控制和更新机制
5. 提供便捷的检索和引用功能
## 3. 文档归并方案
### 3.1 统一文档结构
建议采用以下文档结构：
```
/home/ben/code/huhan3000/
├── core-docs/ # 核心文档目录（替代现有的核心研究文档）
│ ├── 0-overview/ # 概述和介绍文档
│ ├── 1-theory/ # 理论框架文档
│ │ ├── kym-theory/ # KYM三链理论
│ │ ├── y-theory/ # Y音正统性理论
│ │ └── ...
│ ├── 2-topics/ # 专题研究文档
│ │ ├── confucius/ # 孔子研究
│ │ ├── cultural/ # 文化研究
│ │ ├── social/ # 社会制度研究
│ │ ├── bills/ # 汇票研究
│ │ └── ...
│ ├── 3-applications/ # 应用案例和分析
│ └── 4-archives/ # 历史版本和归档
├── tools/ # 工具脚本
│ ├── doc-merger/ # 文档归并工具
│ ├── index-generator/ # 索引生成工具
│ └── content-analyzer/ # 内容分析工具
├── docs-site/ # 文档网站源码
└── scripts/ # 现有脚本目录
```
### 3.2 文档分类与命名规范
#### 分类体系
1. **理论框架**：核心理论体系文档
2. **专题研究**：按主题分类的研究内容
3. **应用分析**：理论应用和案例研究
4. **参考资料**：引用和参考文档
5. **工作文档**：开发和研究过程文档
#### 命名规范
采用以下命名格式：
```
[类别前缀]-[主题代码]-[文档标题]-[版本号].md
```
例如：
- `TH-KYM-三链理论框架-v1.2.md`（理论类-KYM主题-文档标题-版本）
- `TP-CONF-孔子反周复商理论-v2.0.md`（专题类-孔子主题-文档标题-版本）
### 3.3 文档元数据标准
在每个文档开头添加标准化元数据：
```markdown
---
title: 文档标题
author: 作者/贡献者
created: 2023-01-01
updated: 2023-06-15
version: 1.2
category: 理论/专题/应用/参考/工作
tags: [标签1, 标签2, 标签3]
related_docs: [相关文档1, 相关文档2]
---
```
## 4. 自动化工具开发
### 4.1 文档归并工具
创建一个Python脚本，用于自动归并分散的文档：
```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""文档归并工具"""
import os
import re
import shutil
import yaml
from datetime import datetime
def load_config(config_file):
"""加载配置文件"""
with open(config_file, 'r', encoding='utf-8') as f:
return yaml.safe_load(f)
def extract_metadata(content):
"""从文档中提取元数据"""
metadata_match = re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL)
if metadata_match:
try:
return yaml.safe_load(metadata_match.group(1))
except:
return {}
return {}
def merge_documents(source_dir, target_dir, config):
"""归并文档"""
# 确保目标目录存在
os.makedirs(target_dir, exist_ok=True)
# 统计信息
stats = {
'processed': 0,
'merged': 0,
'skipped': 0,
'errors': 0
}
# 遍历源目录
for root, dirs, files in os.walk(source_dir):
for file in files:
if file.endswith('.md'):
stats['processed'] += 1
source_path = os.path.join(root, file)
try:
# 读取文件内容
with open(source_path, 'r', encoding='utf-8') as f:
content = f.read()
# 提取或生成元数据
metadata = extract_metadata(content)
if not metadata:
# 生成默认元数据
metadata = {
'title': file.replace('.md', ''),
'created': datetime.now().strftime('%Y-%m-%d'),
'updated': datetime.now().strftime('%Y-%m-%d'),
'version': '1.0',
'category': '未分类',
'tags': [],
'related_docs': []
}
# 确定文档类别和目标路径
category = metadata.get('category', '未分类')
target_category_dir = os.path.join(target_dir, category)
os.makedirs(target_category_dir, exist_ok=True)
# 生成新文件名
title = metadata['title']
version = metadata.get('version', '1.0')
new_filename = f"{category}-{title}-v{version}.md"
target_path = os.path.join(target_category_dir, new_filename)
# 写入新文件（添加或更新元数据）
with open(target_path, 'w', encoding='utf-8') as f:
f.write("---\n")
yaml.dump(metadata, f, allow_unicode=True)
f.write("---\n\n")
# 移除旧的元数据部分
if re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL):
content = re.sub(r'^---\s*(.*?)\s*---\s*', '', content, flags=re.DOTALL)
f.write(content)
stats['merged'] += 1
print(f"归并: {source_path} -> {target_path}")
except Exception as e:
stats['errors'] += 1
print(f"错误处理 {source_path}: {str(e)}")
return stats
def main():
"""主函数"""
config = {
'source_dirs': [
'/home/ben/code/huhan3000/专题研究-理论分析',
'/home/ben/code/huhan3000/专题研究-孔子研究',
'/home/ben/code/huhan3000/专题研究-文化研究',
'/home/ben/code/huhan3000/专题研究-社会制度',
'/home/ben/code/huhan3000/汇票',
'/home/ben/code/huhan3000/爹学整理中心'
],
'target_dir': '/home/ben/code/huhan3000/core-docs',
'backup': True
}
# 创建备份
if config['backup']:
backup_dir = f"{config['target_dir']}_backup_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
if os.path.exists(config['target_dir']):
shutil.copytree(config['target_dir'], backup_dir)
print(f"创建备份: {backup_dir}")
# 归并每个源目录
for source_dir in config['source_dirs']:
if os.path.exists(source_dir):
print(f"处理目录: {source_dir}")
stats = merge_documents(source_dir, config['target_dir'], config)
print(f"目录统计: 处理={stats['processed']}, 归并={stats['merged']}, 错误={stats['errors']}")
if __name__ == "__main__":
main()
```
### 4.2 索引生成工具
创建索引生成器，自动为归并后的文档创建索引：
```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""文档索引生成工具"""
import os
import re
import yaml
import json
from datetime import datetime
def extract_metadata(file_path):
"""从文件中提取元数据"""
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
metadata_match = re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL)
if metadata_match:
try:
metadata = yaml.safe_load(metadata_match.group(1))
# 添加文件路径
metadata['file_path'] = os.path.relpath(file_path)
# 提取文档摘要（前200个字符）
content_without_metadata = re.sub(r'^---\s*(.*?)\s*---\s*', '', content, flags=re.DOTALL)
metadata['summary'] = content_without_metadata.strip().split('\n')[0][:200] + '...' if content_without_metadata else ''
return metadata
except Exception as e:
print(f"提取元数据错误 {file_path}: {str(e)}")
# 如果没有元数据，返回基本信息
return {
'title': os.path.basename(file_path).replace('.md', ''),
'file_path': os.path.relpath(file_path),
'category': '未分类',
'tags': [],
'created': datetime.now().strftime('%Y-%m-%d')
}
def generate_index(docs_dir, output_file):
"""生成文档索引"""
index = {
'metadata': {
'generated': datetime.now().isoformat(),
'total_docs': 0,
'categories': {}
},
'documents': []
}
# 遍历文档目录
for root, dirs, files in os.walk(docs_dir):
for file in files:
if file.endswith('.md'):
file_path = os.path.join(root, file)
metadata = extract_metadata(file_path)
index['documents'].append(metadata)
# 更新统计信息
category = metadata.get('category', '未分类')
if category not in index['metadata']['categories']:
index['metadata']['categories'][category] = 0
index['metadata']['categories'][category] += 1
# 更新总文档数
index['metadata']['total_docs'] = len(index['documents'])
# 保存索引
with open(output_file, 'w', encoding='utf-8') as f:
json.dump(index, f, ensure_ascii=False, indent=2)
print(f"索引生成完成: {output_file}")
print(f"总文档数: {index['metadata']['total_docs']}")
print("分类统计:")
for category, count in index['metadata']['categories'].items():
print(f" - {category}: {count}")
def generate_md_index(docs_dir, output_file):
"""生成Markdown格式的索引"""
index = {
'metadata': {
'generated': datetime.now().isoformat(),
'total_docs': 0,
'categories': {}
},
'documents': []
}
# 遍历文档目录
for root, dirs, files in os.walk(docs_dir):
for file in files:
if file.endswith('.md'):
file_path = os.path.join(root, file)
metadata = extract_metadata(file_path)
index['documents'].append(metadata)
# 更新统计信息
category = metadata.get('category', '未分类')
if category not in index['metadata']['categories']:
index['metadata']['categories'][category] = []
index['metadata']['categories'][category].append(metadata)
# 更新总文档数
index['metadata']['total_docs'] = len(index['documents'])
# 生成Markdown内容
md_content = f"""# 文档索引
> 生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
> 总文档数: {index['metadata']['total_docs']}
## 分类索引
"""
# 按分类生成索引
for category, docs in sorted(index['metadata']['categories'].items()):
md_content += f"### {category} ({len(docs)})
\n"
for doc in sorted(docs, key=lambda x: x.get('title', '')):
title = doc.get('title', os.path.basename(doc['file_path']))
relative_path = os.path.relpath(doc['file_path'], docs_dir)
md_content += f"- [{title}]({relative_path})\n"
md_content += "\n"
# 保存Markdown索引
with open(output_file, 'w', encoding='utf-8') as f:
f.write(md_content)
print(f"Markdown索引生成完成: {output_file}")
def main():
"""主函数"""
docs_dir = '/home/ben/code/huhan3000/core-docs'
json_index_file = '/home/ben/code/huhan3000/core-docs/index.json'
md_index_file = '/home/ben/code/huhan3000/core-docs/文档索引.md'
generate_index(docs_dir, json_index_file)
generate_md_index(docs_dir, md_index_file)
if __name__ == "__main__":
main()
```
### 4.3 构建Shell脚本
创建一个整合上述工具的shell脚本：
```bash
#!/bin/bash
# 文档系统管理脚本
# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
echo -e "${BLUE}胡汉三千年项目文档系统管理工具${NC}"
echo -e "${BLUE}=============================${NC}"
# 设置变量
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
TOOLS_DIR="$PROJECT_DIR/tools/doc-tools"
CORE_DOCS_DIR="$PROJECT_DIR/core-docs"
LOG_FILE="$PROJECT_DIR/doc_management.log"
# 确保工具目录存在
mkdir -p "$TOOLS_DIR"
# 初始化日志
log() {
echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
}
# 检查Python环境
check_python() {
log "检查Python环境..."
if command -v python3 &> /dev/null; then
PYTHON_VERSION=$(python3 --version 2>&1)
log "找到Python: $PYTHON_VERSION"
return 0
else
log "${RED}错误: 未找到Python3${NC}"
return 1
fi
}
# 安装依赖
install_deps() {
log "安装必要依赖..."
pip3 install pyyaml --quiet
if [ $? -eq 0 ]; then
log "${GREEN}依赖安装成功${NC}"
return 0
else
log "${RED}依赖安装失败${NC}"
return 1
fi
}
# 创建归并工具
create_merger_tool() {
log "创建文档归并工具..."
cat > "$TOOLS_DIR/doc_merger.py" << 'EOF'
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""文档归并工具"""
import os
import re
import shutil
import yaml
from datetime import datetime
def load_config(config_file):
"""加载配置文件"""
with open(config_file, 'r', encoding='utf-8') as f:
return yaml.safe_load(f)
def extract_metadata(content):
"""从文档中提取元数据"""
metadata_match = re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL)
if metadata_match:
try:
return yaml.safe_load(metadata_match.group(1))
except:
return {}
return {}
def merge_documents(source_dir, target_dir, config):
"""归并文档"""
# 确保目标目录存在
os.makedirs(target_dir, exist_ok=True)
# 统计信息
stats = {
'processed': 0,
'merged': 0,
'skipped': 0,
'errors': 0
}
# 遍历源目录
for root, dirs, files in os.walk(source_dir):
for file in files:
if file.endswith('.md'):
stats['processed'] += 1
source_path = os.path.join(root, file)
try:
# 读取文件内容
with open(source_path, 'r', encoding='utf-8') as f:
content = f.read()
# 提取或生成元数据
metadata = extract_metadata(content)
if not metadata:
# 生成默认元数据
metadata = {
'title': file.replace('.md', ''),
'created': datetime.now().strftime('%Y-%m-%d'),
'updated': datetime.now().strftime('%Y-%m-%d'),
'version': '1.0',
'category': '未分类',
'tags': [],
'related_docs': []
}
# 确定文档类别和目标路径
category = metadata.get('category', '未分类')
target_category_dir = os.path.join(target_dir, category)
os.makedirs(target_category_dir, exist_ok=True)
# 生成新文件名
title = metadata['title']
version = metadata.get('version', '1.0')
new_filename = f"{category}-{title}-v{version}.md"
target_path = os.path.join(target_category_dir, new_filename)
# 写入新文件（添加或更新元数据）
with open(target_path, 'w', encoding='utf-8') as f:
f.write("---\n")
yaml.dump(metadata, f, allow_unicode=True)
f.write("---\n\n")
# 移除旧的元数据部分
if re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL):
content = re.sub(r'^---\s*(.*?)\s*---\s*', '', content, flags=re.DOTALL)
f.write(content)
stats['merged'] += 1
print(f"归并: {source_path} -> {target_path}")
except Exception as e:
stats['errors'] += 1
print(f"错误处理 {source_path}: {str(e)}")
return stats
def main():
"""主函数"""
config = {
'source_dirs': [
'/home/ben/code/huhan3000/专题研究-理论分析',
'/home/ben/code/huhan3000/专题研究-孔子研究',
'/home/ben/code/huhan3000/专题研究-文化研究',
'/home/ben/code/huhan3000/专题研究-社会制度',
'/home/ben/code/huhan3000/汇票',
'/home/ben/code/huhan3000/爹学整理中心'
],
'target_dir': '/home/ben/code/huhan3000/core-docs',
'backup': True
}
# 创建备份
if config['backup']:
backup_dir = f"{config['target_dir']}_backup_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
if os.path.exists(config['target_dir']):
shutil.copytree(config['target_dir'], backup_dir)
print(f"创建备份: {backup_dir}")
# 归并每个源目录
for source_dir in config['source_dirs']:
if os.path.exists(source_dir):
print(f"处理目录: {source_dir}")
stats = merge_documents(source_dir, config['target_dir'], config)
print(f"目录统计: 处理={stats['processed']}, 归并={stats['merged']}, 错误={stats['errors']}")
if __name__ == "__main__":
main()
EOF
chmod +x "$TOOLS_DIR/doc_merger.py"
log "${GREEN}文档归并工具已创建${NC}"
}
# 创建索引工具
create_index_tool() {
log "创建索引生成工具..."
cat > "$TOOLS_DIR/index_generator.py" << 'EOF'
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""文档索引生成工具"""
import os
import re
import yaml
import json
from datetime import datetime
def extract_metadata(file_path):
"""从文件中提取元数据"""
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
metadata_match = re.search(r'^---\s*(.*?)\s*---', content, re.DOTALL)
if metadata_match:
try:
metadata = yaml.safe_load(metadata_match.group(1))
# 添加文件路径
metadata['file_path'] = os.path.relpath(file_path)
# 提取文档摘要（前200个字符）
content_without_metadata = re.sub(r'^---\s*(.*?)\s*---\s*', '', content, flags=re.DOTALL)
metadata['summary'] = content_without_metadata.strip().split('\n')[0][:200] + '...' if content_without_metadata else ''
return metadata
except Exception as e:
print(f"提取元数据错误 {file_path}: {str(e)}")
# 如果没有元数据，返回基本信息
return {
'title': os.path.basename(file_path).replace('.md', ''),
'file_path': os.path.relpath(file_path),
'category': '未分类',
'tags': [],
'created': datetime.now().strftime('%Y-%m-%d')
}
def generate_index(docs_dir, output_file):
"""生成文档索引"""
index = {
'metadata': {
'generated': datetime.now().isoformat(),
'total_docs': 0,
'categories': {}
},
'documents': []
}
# 遍历文档目录
for root, dirs, files in os.walk(docs_dir):
for file in files:
if file.endswith('.md'):
file_path = os.path.join(root, file)
metadata = extract_metadata(file_path)
index['documents'].append(metadata)
# 更新统计信息
category = metadata.get('category', '未分类')
if category not in index['metadata']['categories']:
index['metadata']['categories'][category] = 0
index['metadata']['categories'][category] += 1
# 更新总文档数
index['metadata']['total_docs'] = len(index['documents'])
# 保存索引
with open(output_file, 'w', encoding='utf-8') as f:
json.dump(index, f, ensure_ascii=False, indent=2)
print(f"索引生成完成: {output_file}")
print(f"总文档数: {index['metadata']['total_docs']}")
print("分类统计:")
for category, count in index['metadata']['categories'].items():
print(f" - {category}: {count}")
def generate_md_index(docs_dir, output_file):
"""生成Markdown格式的索引"""
index = {
'metadata': {
'generated': datetime.now().isoformat(),
'total_docs': 0,
'categories': {}
},
'documents': []
}
# 遍历文档目录
for root, dirs, files in os.walk(docs_dir):
for file in files:
if file.endswith('.md'):
file_path = os.path.join(root, file)
metadata = extract_metadata(file_path)
index['documents'].append(metadata)
# 更新统计信息
category = metadata.get('category', '未分类')
if category not in index['metadata']['categories']:
index['metadata']['categories'][category] = []
index['metadata']['categories'][category].append(metadata)
# 更新总文档数
index['metadata']['total_docs'] = len(index['documents'])
# 生成Markdown内容
md_content = f"""# 文档索引
> 生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
> 总文档数: {index['metadata']['total_docs']}
## 分类索引
"""
# 按分类生成索引
for category, docs in sorted(index['metadata']['categories'].items()):
md_content += f"### {category} ({len(docs)})
\n"
for doc in sorted(docs, key=lambda x: x.get('title', '')):
title = doc.get('title', os.path.basename(doc['file_path']))
relative_path = os.path.relpath(doc['file_path'], docs_dir)
md_content += f"- [{title}]({relative_path})\n"
md_content += "\n"
# 保存Markdown索引
with open(output_file, 'w', encoding='utf-8') as f:
f.write(md_content)
print(f"Markdown索引生成完成: {output_file}")
def main():
"""主函数"""
docs_dir = '/home/ben/code/huhan3000/core-docs'
json_index_file = '/home/ben/code/huhan3000/core-docs/index.json'
md_index_file = '/home/ben/code/huhan3000/core-docs/文档索引.md'
generate_index(docs_dir, json_index_file)
generate_md_index(docs_dir, md_index_file)
if __name__ == "__main__":
main()
EOF
chmod +x "$TOOLS_DIR/index_generator.py"
log "${GREEN}索引生成工具已创建${NC}"
}
# 执行归并
run_merger() {
log "开始文档归并..."
python3 "$TOOLS_DIR/doc_merger.py"
if [ $? -eq 0 ]; then
log "${GREEN}文档归并完成${NC}"
return 0
else
log "${RED}文档归并失败${NC}"
return 1
fi
}
# 生成索引
generate_index() {
log "开始生成索引..."
python3 "$TOOLS_DIR/index_generator.py"
if [ $? -eq 0 ]; then
log "${GREEN}索引生成完成${NC}"
return 0
else
log "${RED}索引生成失败${NC}"
return 1
fi
}
# 创建配置文件
create_config() {
log "创建配置文件..."
cat > "$TOOLS_DIR/config.yaml" << 'EOF'
source_dirs:
- /home/ben/code/huhan3000/专题研究-理论分析
- /home/ben/code/huhan3000/专题研究-孔子研究
- /home/ben/code/huhan3000/专题研究-文化研究
- /home/ben/code/huhan3000/专题研究-社会制度
- /home/ben/code/huhan3000/汇票
- /home/ben/code/huhan3000/爹学整理中心
target_dir: /home/ben/code/huhan3000/core-docs
backup: true
categories:
- 理论框架
- 专题研究
- 应用分析
- 参考资料
- 工作文档
metadata_template:
title: ""
author: ""
created: ""
updated: ""
version: "1.0"
category: "未分类"
tags: []
related_docs: []
EOF
log "${GREEN}配置文件已创建${NC}"
}
# 显示帮助
show_help() {
echo -e "\n${BLUE}使用方法:${NC} $0 [选项]"
echo -e "\n${YELLOW}选项:${NC}"
echo -e " ${GREEN}--setup${NC} 设置文档管理环境"
echo -e " ${GREEN}--merge${NC} 执行文档归并"
echo -e " ${GREEN}--index${NC} 生成文档索引"
echo -e " ${GREEN}--full${NC} 执行完整流程（归并+索引）"
echo -e " ${GREEN}--help${NC} 显示此帮助信息"
echo -e "\n${YELLOW}示例:${NC}"
echo -e " $0 --setup # 初始化设置"
echo -e " $0 --full # 执行完整的文档归并和索引生成"
}
# 初始化环境
setup_environment() {
log "开始初始化环境..."
# 检查Python
if ! check_python; then
return 1
fi
# 安装依赖
if ! install_deps; then
return 1
fi
# 创建配置文件
create_config
# 创建工具
create_merger_tool
create_index_tool
# 创建目标目录
mkdir -p "$CORE_DOCS_DIR"
log "${GREEN}环境初始化完成${NC}"
return 0
}
# 主流程
main() {
if [ $# -eq 0 ]; then
show_help
return 1
fi
case "$1" in
--setup)
setup_environment
;;
--merge)
run_merger
;;
--index)
generate_index
;;
--full)
run_merger && generate_index
;;
--help)
show_help
;;
*)
echo -e "${RED}未知选项: $1${NC}"
show_help
return 1
;;
esac
}
main "$@"
Reference in New Issue View Git Blame Copy Permalink