# luoshu

**Repository Path**: dougio/luoshu

## Basic Information

- **Project Name**: luoshu
- **Description**: ontology knowledge base
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 洛书 (Luoshu)

个人知识库系统 - 基于 Ontology 思想的知识管理与术语发现系统。

**版本**: v0.1.0  
**最后更新**: 2026-04-03

---

## 🚀 快速开始（跨设备测试指南）

### 第一步：克隆项目

```bash
# 在你的另一台设备上执行
git clone https://gitee.com/dougio/luoshu.git
cd luoshu
```

### 第二步：配置 Python 环境

```bash
# 创建虚拟环境（推荐）
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt
```

### 第三步：配置 AI 服务

**方式 1：环境变量（推荐）**
```bash
export OPENCLAW_AI_API_KEY="sk-your-api-key"
export OPENCLAW_AI_API_URL="https://api.example.com/v1"
export OPENCLAW_AI_EMBEDDING_MODEL="text-embedding-3-small"
export OPENCLAW_AI_CHAT_MODEL="gpt-4o-mini"
```

**方式 2：配置文件**
```bash
# 复制配置文件模板
cp config/config.yaml config/config.local.yaml
# 编辑 config/config.local.yaml
```

### 第四步：初始化数据库

```bash
# 初始化数据库（创建表结构）
python -m src.cli.main init

# 或使用初始化脚本
python scripts/init_db.py
```

### 第五步：运行测试

```bash
# 运行所有测试
pytest tests/ -v

# 运行特定模块测试
pytest tests/test_database.py -v
pytest tests/test_vocabulary.py -v

# 查看测试覆盖率
pytest tests/ --cov=src --cov-report=html
# 覆盖率报告在 htmlcov/index.html
```

### 第六步：手动测试 CLI

```bash
# 查看帮助
python -m src.cli.main --help

# 查看待确认术语（应该显示空列表或已有术语）
python -m src.cli.main vocabulary pending

# 查看术语列表
python -m src.cli.main vocabulary list

# 测试术语发现（手动添加术语）
python -m src.cli.main vocabulary add "测试术语" --category 术 --desc "这是一个测试术语"

# 再次查看术语列表
python -m src.cli.main vocabulary list
```

---

## 📋 命令行参考

### 全局选项

```bash
python -m src.cli.main [OPTIONS] COMMAND [ARGS]...

Options:
  -c, --config PATH   配置文件路径
  -v, --verbose       启用详细输出
  --help              显示帮助信息
```

### 命令

#### `init` - 初始化数据库

```bash
python -m src.cli.main init
```

#### `import` - 导入内容

```bash
python -m src.cli.main import --type <article|note> --title "标题" [--file 文件路径] [--url 来源 URL]
```

#### `search` - 检索内容

```bash
python -m src.cli.main search "查询关键词" [--type all|article|note] [--limit 10]
```

#### `vocabulary pending` - 查看待确认术语

```bash
python -m src.cli.main vocabulary pending [--limit 10]
```

#### `vocabulary review` - 交互式批量确认术语

```bash
python -m src.cli.main vocabulary review [--batch-size 10]
```

**交互命令**：
- `y` - 确认术语
- `n` - 拒绝术语
- `e` - 编辑术语
- `s` - 跳过
- `q` - 退出

#### `vocabulary list` - 列出术语

```bash
python -m src.cli.main vocabulary list [--status pending|confirmed|rejected|all] [--category 法|术|器|all] [--limit 50]
```

#### `vocabulary add` - 手动添加术语

```bash
python -m src.cli.main vocabulary add "术语名称" --category <法|术|器> --desc "术语解释"
```

#### `version` - 显示版本信息

```bash
python -m src.cli.main version
```

---

## 🧪 测试验证清单

在另一台设备上测试时，请按以下清单验证：

### 基础功能
- [ ] 依赖安装成功（`pip install -r requirements.txt`）
- [ ] 数据库初始化成功（`python -m src.cli.main init`）
- [ ] CLI 帮助信息显示正常

### 术语管理
- [ ] `vocabulary pending` 显示待确认术语
- [ ] `vocabulary list` 列出所有术语
- [ ] `vocabulary add` 手动添加术语
- [ ] `vocabulary review` 交互式确认（如有待确认术语）

### 测试套件
- [ ] 所有测试通过（`pytest tests/ -v`）
- [ ] 测试覆盖率报告生成

### AI 集成（可选）
- [ ] 配置 AI API Key 后，术语发现功能正常
- [ ] AI 分类建议（法/术/器）准确

---

## 📁 项目结构

```
luoshu/
├── README.md                # 本文档
├── requirements.txt         # Python 依赖
├── pytest.ini              # pytest 配置
├── config/
│   └── config.yaml         # 配置文件模板
├── scripts/
│   ├── init_db.py          # 数据库初始化脚本
│   └── migrate_v0_to_v1.py # 数据库迁移脚本
├── src/
│   ├── __init__.py
│   ├── ai/
│   │   └── client.py       # AI 客户端
│   ├── cli/
│   │   └── main.py         # 命令行入口
│   ├── config/
│   │   └── config.py       # 配置管理
│   ├── storage/
│   │   └── database.py     # 数据库层
│   └── vocabulary/
│       └── manager.py      # 术语管理
├── tests/
│   ├── conftest.py         # pytest fixtures
│   ├── mocks.py            # Mock AI 服务
│   ├── test_*.py           # 测试用例
│   └── .gitkeep
├── docs/
│   ├── requirements.md     # 功能需求文档
│   └── vocabulary-design.md # 术语设计文档
├── data/                   # 数据库文件（.gitignore）
└── temp/                   # 临时文件（.gitignore）
```

---

## 🔧 故障排查

### 问题 1: 依赖安装失败
```bash
# 升级 pip
pip install --upgrade pip

# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 问题 2: 数据库初始化失败
```bash
# 检查 data 目录是否存在
ls -la data/

# 手动创建
mkdir -p data
python -m src.cli.main init
```

### 问题 3: AI API 调用失败
```bash
# 检查环境变量
echo $OPENCLAW_AI_API_KEY

# 测试连接
curl -H "Authorization: Bearer $OPENCLAW_AI_API_KEY" $OPENCLAW_AI_API_URL/models
```

### 问题 4: 测试失败
```bash
# 查看详细错误
pytest tests/ -v -s

# 运行单个测试
pytest tests/test_database.py::TestDatabaseSchema::test_content_table_created -v
```

---

## 📊 当前状态

| 模块 | 状态 | 说明 |
|------|------|------|
| 数据库层 | ✅ 完成 | 11 个表 + 事务 + 文件锁 |
| 配置管理 | ✅ 完成 | 环境变量 > config.yaml > 默认值 |
| AI 客户端 | ✅ 完成 | embed/extract_terms/generate_description/identify_intent |
| 术语管理 | ✅ 完成 | 发现/确认/拒绝/编辑/批量回顾 |
| CLI | ✅ 完成 | 7 个命令 |
| 测试框架 | ✅ 完成 | 100+ 测试用例 |
| P0 问题修复 | ✅ 完成 | 多义词支持 + 拒绝历史 |

---

## 📝 开发说明

### 运行迁移脚本

```bash
# 正向迁移（v0 -> v1）
python scripts/migrate_v0_to_v1.py --db data/luoshu.db

# 回滚迁移（v1 -> v0）
python scripts/migrate_v0_to_v1.py --db data/luoshu.db --rollback

# 验证迁移
python scripts/migrate_v0_to_v1.py --db data/luoshu.db --verify
```

### 代码质量检查

```bash
# 类型检查（如安装 mypy）
mypy src/

# 代码格式化（如安装 black）
black src/ tests/

# 导入检查
python -m py_compile src/**/*.py
```

---

## 📞 问题反馈

如遇到问题，请提供以下信息：
1. Python 版本：`python3 --version`
2. 操作系统：`uname -a` 或 `ver`
3. 错误信息：完整 traceback
4. 复现步骤：如何触发问题

---

## 📚 核心概念

### 三层知识模型

1. **第 1-2 层：内容层**
   - `content`: 文章、笔记
   - `entity`: 实体（人、事、物）
   - `relation`: 实体关系
   - `tag`: 标签

2. **第 3 层：术语层**
   - `vocabulary`: 术语词典（法/术/器分类）
   - `vocabulary_relation`: 术语关系
   - `vocabulary_learning_log`: 学习日志

### 术语分类（法/术/器）

- **法**: 方法论、原则、规律、理论
- **术**: 技术、方法、技巧、实践
- **器**: 工具、设备、资源、平台

---

## 📋 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `OPENCLAW_AI_API_KEY` | AI API 密钥 | - |
| `OPENCLAW_AI_API_URL` | AI API 地址 | `https://api.openai.com/v1` |
| `OPENCLAW_AI_EMBEDDING_MODEL` | 嵌入模型 | `text-embedding-3-small` |
| `OPENCLAW_AI_CHAT_MODEL` | 聊天模型 | `gpt-4o-mini` |
| `LUOSHU_DB_PATH` | 数据库路径 | `data/luoshu.db` |
| `LUOSHU_DB_TIMEOUT` | 数据库超时 | `30` |
| `LUOSHU_VOCAB_AUTO_CONFIRM` | 自动确认术语 | `false` |
| `LUOSHU_VOCAB_BATCH_SIZE` | 批量审核数量 | `10` |
| `LUOSHU_LOG_LEVEL` | 日志级别 | `INFO` |

### 配置文件

详见 `config/config.yaml`。

---

## 📄 许可证

MIT License

---

**洛书** - 让知识有序，让学习有方。