mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 17:00:23 +00:00
75 lines
1.8 KiB
Markdown
75 lines
1.8 KiB
Markdown
|
# PaperForge 维护者指南
|
|||
|
|
|
|||
|
|
> 面向贡献者和维护者。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
paperforge/
|
|||
|
|
├── core/ PFResult 契约层
|
|||
|
|
├── adapters/ BBT 解析、frontmatter、路径
|
|||
|
|
├── services/ SyncService 编排
|
|||
|
|
├── worker/ OCR、sync、status、repair
|
|||
|
|
├── memory/ SQLite、ChromaDB、快照
|
|||
|
|
├── commands/ CLI 分发
|
|||
|
|
├── setup/ 安装向导
|
|||
|
|
├── schema/ field_registry.yaml
|
|||
|
|
├── doctor/ 字段校验
|
|||
|
|
├── plugin/ Obsidian 插件
|
|||
|
|
│ ├── main.js UI + 快照读取
|
|||
|
|
│ └── src/testable.js 提取的纯函数
|
|||
|
|
└── skills/paperforge/ Agent skill 文件
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 架构原则
|
|||
|
|
|
|||
|
|
1. Python 写 canonical 快照，JS 只读
|
|||
|
|
2. CLI 是所有命令的真相源
|
|||
|
|
3. `paperforge.json` 是路径真相源
|
|||
|
|
4. `formal-library.json` 是文献索引真相源
|
|||
|
|
|
|||
|
|
## 版本号
|
|||
|
|
|
|||
|
|
版本只在 `paperforge/__init__.py` 定义。升版本：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python scripts/bump.py patch
|
|||
|
|
python scripts/bump.py minor
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
自动更新：`__init__.py`、`manifest.json`、`versions.json`、git tag。
|
|||
|
|
|
|||
|
|
## 发布
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
python scripts/bump.py patch
|
|||
|
|
git push && git push --tags
|
|||
|
|
gh release create vX.Y.Z \
|
|||
|
|
--title "vX.Y.Z" \
|
|||
|
|
--notes "说明" \
|
|||
|
|
paperforge/plugin/main.js \
|
|||
|
|
paperforge/plugin/styles.css \
|
|||
|
|
paperforge/plugin/manifest.json \
|
|||
|
|
paperforge/plugin/versions.json
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 测试
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
ruff check --fix paperforge/ && ruff format paperforge/
|
|||
|
|
python -m pytest tests/unit/ tests/cli/ -v --tb=short
|
|||
|
|
cd paperforge/plugin && npx vitest run
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## i18n
|
|||
|
|
|
|||
|
|
插件文案在 `paperforge/plugin/main.js` 的 `LANG` 对象中。中文 keys 在 `LANG.zh`，英文在 `LANG.en`。代码用 `t('key')` 读取。
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
|
|||
|
|
- [架构](ARCHITECTURE.md)
|
|||
|
|
- [命令参考](COMMANDS.md)
|
|||
|
|
- [AGENTS.md](../AGENTS.md)
|