mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 06:50:53 +00:00
chore: cleanup stale files, update AGENTS.md, fix install wizard button crash
- Remove root setup_wizard.py (duplicate of paperforge/setup_wizard.py) - Remove token-usage-output.txt (runtime artifact) - Update AGENTS.md: worker architecture, directory structure, section numbering, test count 317->462 - Fix undefined 'home' variable in plugin main.js _preCheck causing modal to silently fail
This commit is contained in:
Research Assistant
parent
6d2c62ebf6
commit
dac097c7e6
4 changed files with 29 additions and 1754 deletions
56
AGENTS.md
56
AGENTS.md
|
|
@ -1,6 +1,6 @@
|
|||
# PaperForge - Agent Guide
|
||||
|
||||
> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。安装步骤见 [setup-guide.md](docs/setup-guide.md) 或快速版 [INSTALLATION.md](docs/INSTALLATION.md)。
|
||||
> 本文档面向 **安装完成后的新用户** 和 **AI Agent**。安装步骤见 [setup-guide.md](docs/setup-guide.md) 或快速版 [INSTALLATION.md](docs/INSTALLATION.md)。Docs 版本与 v1.4.13 对应。
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -12,7 +12,7 @@
|
|||
[ ] Obsidian 已打开当前 Vault
|
||||
[ ] PaperForge 已安装 (pip install git+https://github.com/LLLin000/PaperForge.git)
|
||||
[ ] PaddleOCR API Key 已配置（在 .env 中）
|
||||
[ ] 目录结构已创建（setup.py 会自动完成）
|
||||
[ ] 目录结构已创建（安装向导会自动完成）
|
||||
[ ] Zotero 数据目录已链接到 <system_dir>/Zotero
|
||||
```
|
||||
|
||||
|
|
@ -32,7 +32,7 @@ PaperForge 采用 **两层设计**：
|
|||
|
||||
| 层级 | 组件 | 触发方式 | 作用 |
|
||||
|------|------|----------|------|
|
||||
| **Worker 层** | `literature_pipeline.py`（4 个 workers） | Python CLI | 后台自动化 |
|
||||
| **Worker 层** | `paperforge/worker/`（7 个 worker 模块） | Python CLI | 后台自动化 |
|
||||
| **Agent 层** | `/pf-deep`, `/pf-paper` 命令 | 用户手动触发 | 交互式精读 |
|
||||
|
||||
**关键区别**：
|
||||
|
|
@ -93,16 +93,16 @@ Zotero 添加文献
|
|||
│
|
||||
├── <system_dir>/
|
||||
│ ├── PaperForge/
|
||||
│ │ ├── exports/ ← Better BibTeX 自动导出的 JSON
|
||||
│ │ │ └── library.json
|
||||
│ │ ├── ocr/ ← OCR 结果（每个文献一个子目录）
|
||||
│ │ │ └── ABCDEFG/ ← Zotero key 作为目录名
|
||||
│ │ │ ├── fulltext.md ← OCR 提取的全文
|
||||
│ │ │ ├── images/ ← 图表切割图片
|
||||
│ │ │ ├── meta.json ← OCR 元数据（含 ocr_status）
|
||||
│ │ │ └── figure-map.json ← 图表索引（自动创建）
|
||||
│ │ └── worker/scripts/
|
||||
│ │ └── literature_pipeline.py ← 核心脚本
|
||||
│ │ ├── exports/ ← Better BibTeX 自动导出的 JSON
|
||||
│ │ │ └── library.json
|
||||
│ │ ├── ocr/ ← OCR 结果（每个文献一个子目录）
|
||||
│ │ │ └── ABCDEFG/ ← Zotero key 作为目录名
|
||||
│ │ │ ├── fulltext.md ← OCR 提取的全文
|
||||
│ │ │ ├── images/ ← 图表切割图片
|
||||
│ │ │ ├── meta.json ← OCR 元数据（含 ocr_status）
|
||||
│ │ │ └── figure-map.json ← 图表索引（自动创建）
|
||||
│ │ ├── indexes/ ← 索引缓存（formal-library.json 等）
|
||||
│ │ └── config/ ← 领域-收藏夹映射等配置
|
||||
│ └── Zotero/ ← Junction/Symlink 到 Zotero 数据目录
|
||||
│
|
||||
├── <agent_config_dir>/ ← OpenCode Agent 配置（自动创建）
|
||||
|
|
@ -125,6 +125,10 @@ Zotero 添加文献
|
|||
| `<resources_dir>/<control_dir>/library-records/` | 文献状态跟踪（analyze, ocr_status 等） | sync（selection-sync 阶段）生成，用户修改状态 |
|
||||
| `<system_dir>/PaperForge/exports/` | Better BibTeX JSON 导出 | Zotero 自动导出 |
|
||||
| `<system_dir>/PaperForge/ocr/` | OCR 全文 + 图表切割 | ocr worker 生成 |
|
||||
| `<system_dir>/PaperForge/indexes/` | 索引缓存（formal-library.json） | sync 生成 |
|
||||
| `<system_dir>/PaperForge/config/` | 领域-收藏夹映射等 | 用户/安装向导配置 |
|
||||
| `<system_dir>/PaperForge/indexes/` | 索引缓存（formal-library.json） | sync 生成 |
|
||||
| `<system_dir>/PaperForge/config/` | 领域-收藏夹映射等 | 用户/安装向导配置 |
|
||||
| `<system_dir>/Zotero/` | Zotero 数据目录的链接 | 安装时手动创建 junction |
|
||||
|
||||
---
|
||||
|
|
@ -145,10 +149,8 @@ Zotero 添加文献
|
|||
# 仅根据现有 library-records 生成正式笔记
|
||||
paperforge sync --index
|
||||
# Legacy (备用):
|
||||
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
|
||||
# --vault "{vault路径}" selection-sync
|
||||
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
|
||||
# --vault "{vault路径}" index-refresh
|
||||
# python -m paperforge sync --selection --vault "{vault路径}"
|
||||
# python -m paperforge sync --index --vault "{vault路径}"
|
||||
```
|
||||
|
||||
### ocr
|
||||
|
|
@ -166,8 +168,7 @@ Zotero 添加文献
|
|||
# 诊断模式（不运行，仅检查状态）
|
||||
paperforge ocr --diagnose
|
||||
# Legacy (备用):
|
||||
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
|
||||
# --vault "{vault路径}" ocr
|
||||
# python -m paperforge ocr --vault "{vault路径}"
|
||||
```
|
||||
|
||||
### deep-reading
|
||||
|
|
@ -180,8 +181,7 @@ Zotero 添加文献
|
|||
paperforge deep-reading
|
||||
paperforge deep-reading --verbose # 显示阻塞条目的修复指令
|
||||
# Legacy (备用):
|
||||
# python <system_dir>/PaperForge/worker/scripts/literature_pipeline.py \
|
||||
# --vault "{vault路径}" deep-reading
|
||||
# python -m paperforge deep-reading --vault "{vault路径}"
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -328,7 +328,7 @@ pdf_link: "[[99_System/Zotero/storage/KEY/文件名.pdf]]"
|
|||
|
||||
---
|
||||
|
||||
## 7. 第一次使用指南（手把手）
|
||||
## 8. 第一次使用指南（手把手）
|
||||
|
||||
### Step 1: 确认 Zotero 有文献
|
||||
|
||||
|
|
@ -400,7 +400,7 @@ Agent 会自动：
|
|||
|
||||
---
|
||||
|
||||
## 8. 常用命令速查
|
||||
## 9. 常用命令速查
|
||||
|
||||
```bash
|
||||
# 检测 Zotero 新条目并生成正式笔记
|
||||
|
|
@ -459,7 +459,7 @@ paperforge doctor
|
|||
|
||||
---
|
||||
|
||||
## 9. 常见问题
|
||||
## 10. 常见问题
|
||||
|
||||
### Q: 运行 sync 后没有生成 library-records？
|
||||
- 检查 Better BibTeX JSON 导出路径是否正确
|
||||
|
|
@ -485,7 +485,7 @@ paperforge doctor
|
|||
|
||||
---
|
||||
|
||||
## 10. 升级与维护
|
||||
## 11. 升级与维护
|
||||
|
||||
### 更新 PaperForge 代码
|
||||
|
||||
|
|
@ -551,7 +551,7 @@ cp -r 新下载的代码/* <vault_path>/
|
|||
|
||||
---
|
||||
|
||||
## 11. 命令迁移说明（v1.1 → v1.2）
|
||||
## 12. 命令迁移说明（v1.1 → v1.2）
|
||||
|
||||
从 v1.2 开始，PaperForge 采用统一的命令接口：
|
||||
|
||||
|
|
@ -565,7 +565,7 @@ cp -r 新下载的代码/* <vault_path>/
|
|||
|
||||
---
|
||||
|
||||
## 12. 开发者指南（AI Agent 必读）
|
||||
## 13. 开发者指南（AI Agent 必读）
|
||||
|
||||
### 版本号管理
|
||||
|
||||
|
|
@ -630,7 +630,7 @@ gh release create v1.4.12 \
|
|||
# 提交前运行 ruff lint + format + 一致性审计
|
||||
ruff check --fix paperforge/ && ruff format paperforge/
|
||||
|
||||
# 运行测试（317 tests）
|
||||
# 运行测试（462 tests）
|
||||
pytest tests/ -q --tb=short
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1416,6 +1416,7 @@ class PaperForgeSettingTab extends PluginSettingTab {
|
|||
// Try common install locations
|
||||
const progFiles = process.env.ProgramFiles || '';
|
||||
const localAppData = process.env.LOCALAPPDATA || '';
|
||||
const home = process.env.USERPROFILE || process.env.HOME || '';
|
||||
const zotInstallDirs = [
|
||||
path.join(progFiles, 'Zotero'),
|
||||
path.join(progFiles, '(x86)', 'Zotero'),
|
||||
|
|
|
|||
1521
setup_wizard.py
1521
setup_wizard.py
File diff suppressed because it is too large
Load diff
|
|
@ -1,205 +0,0 @@
|
|||
═══════════════════════════════════════════════════════════════════════════
|
||||
Token Analysis: Session ses_22d6d418fffeTvHERtaFMo52d7
|
||||
Model: deepseek-v4-pro
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
|
||||
WARNINGS
|
||||
───────────────────────────────────────────────────
|
||||
- Pricing for 'deepseek/deepseek-v4-pro' was not found in models.json. Cost estimates use the default fallback rates ($1/M input, $3/M output, no cache pricing).
|
||||
|
||||
TOKEN BREAKDOWN BY CATEGORY
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
Estimated using tokenizer analysis of message content:
|
||||
|
||||
Input Categories:
|
||||
SYSTEM ██████████░░░░░░░░░░░░░░░░░░░░ 33.1% (42,306)
|
||||
USER ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0.1% (87)
|
||||
TOOLS ████████████████████░░░░░░░░░░ 66.8% (85,373)
|
||||
|
||||
Subtotal: 127,766 estimated input tokens
|
||||
Note: inferred system/overhead values are heuristic estimates from API telemetry.
|
||||
|
||||
Output Categories:
|
||||
REASONING ██████████████████████████████ 100.0% (2,621)
|
||||
|
||||
Subtotal: 2,621 estimated output tokens
|
||||
|
||||
Local Total: 130,387 tokens (estimated)
|
||||
|
||||
TOOL USAGE BREAKDOWN
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
read ████████████████████████████░░ 92.7% (79,168) 17x
|
||||
glob ██░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 6.1% (5,248) 4x
|
||||
bash ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0.9% (767) 2x
|
||||
grep ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 0.2% (190) 2x
|
||||
|
||||
TOP CONTRIBUTORS
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
• read 79,168 tokens (60.7%)
|
||||
• System (inferred from API telemetry) 42,306 tokens (32.4%)
|
||||
• glob 5,248 tokens (4.0%)
|
||||
• Reasoning#6 1,373 tokens (1.1%)
|
||||
• Reasoning#8 832 tokens (0.6%)
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
MOST RECENT API CALL
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Raw telemetry from last API response:
|
||||
Input (fresh): 2,582 tokens
|
||||
Cache read: 125,184 tokens
|
||||
Output: 249 tokens
|
||||
Reasoning: 89 tokens
|
||||
Provider total: 128,104 tokens
|
||||
Cost: $0.0238
|
||||
─────────────────────────────────────
|
||||
Total: 128,104 tokens
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
SESSION TOTALS (All 7 API calls)
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Assistant messages observed: 8 (structural count)
|
||||
|
||||
Total tokens processed across the entire session (for cost calculation):
|
||||
|
||||
Input tokens: 123,385 (fresh tokens across all calls)
|
||||
Cache read: 510,464 (cached tokens across all calls)
|
||||
Cache write: 0 (tokens written to cache)
|
||||
Output tokens: 1,683 (all model responses)
|
||||
Reasoning tokens: 1,789 (thinking/reasoning)
|
||||
─────────────────────────────────────
|
||||
Session Total: 637,321 tokens (for billing)
|
||||
Cache read calls: 7 / 7
|
||||
Cache write calls: 0 / 7
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
SESSION COST
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Token usage breakdown:
|
||||
Input tokens: 123,385
|
||||
Output tokens: 1,683
|
||||
Reasoning tokens: 1,789
|
||||
Cache read: 510,464
|
||||
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
ACTUAL COST (from API): $0.3008
|
||||
Estimated cost: $0.1338 (-55.5% diff)
|
||||
|
||||
Note: Actual cost from OpenCode includes provider-specific pricing
|
||||
and 200K+ context adjustments.
|
||||
|
||||
══════════════════════════════════════════════════════════════════════════
|
||||
AVAILABLE SKILLS (always-available context)
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
These skills were recovered from the skill tool metadata available to this session.
|
||||
|
||||
Skill Description Tokens
|
||||
───────────────────────────────────────────────────────────────────────
|
||||
defuddle Extract clean markdown content from web page… ~78
|
||||
academic-writing-dist… Analyze high-quality academic articles to ex… ~66
|
||||
gsd-oc-select-model Interactive model selection workflow with pa… ~49
|
||||
finishing-a-developme… Use when implementation is complete, all tes… ~46
|
||||
git-master Git expert. Detects commit styles, splits at… ~46
|
||||
frontend-ui-ux Designer-turned-developer persona. Crafts st… ~42
|
||||
brainstorming You MUST use this before any creative work -… ~39
|
||||
huashu-nuwa 女娲造人：输入人名/主题/甚至只是模糊需求，自动深度调研→思维框架提炼→生成可运行的人物… ~39
|
||||
dispatching-parallel-… Use when facing 2+ independent tasks that ca… ~28
|
||||
executing-plans Use when you have a written implementation p… ~25
|
||||
───────────────────────────────────────────────────────────────────────
|
||||
Total: ~458 tokens (10 skills available)
|
||||
|
||||
Note: Full skill tool description is ~1,346 tokens (includes boilerplate).
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
AVAILABLE SUBAGENTS (in task tool definition)
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
These subagents are embedded in the task tool description and consume tokens on every API call.
|
||||
|
||||
Subagent Description Tokens
|
||||
───────────────────────────────────────────────────────────────────────
|
||||
explore Fast agent specialized for exploring codebases. U… ~105
|
||||
gsd-doc-synthesizer Synthesizes classified planning docs into a singl… ~85
|
||||
gsd-domain-researcher Researches the business domain and real-world app… ~80
|
||||
gsd-eval-auditor Retroactive audit of an implemented AI phase's ev… ~80
|
||||
gsd-eval-planner Designs a structured evaluation strategy for an A… ~76
|
||||
gsd-ai-researcher Researches a chosen AI framework's official docs … ~73
|
||||
gsd-debug-session-man… Manages multi-cycle /gsd-debug checkpoint and con… ~69
|
||||
gsd-doc-classifier Classifies a single planning document as ADR, PRD… ~68
|
||||
gsd-framework-selector Presents an interactive decision matrix to surfac… ~61
|
||||
gsd-project-researcher Researches domain ecosystem before roadmap creati… ~51
|
||||
gsd-codebase-mapper Explores codebase and writes structured analysis … ~49
|
||||
gsd-ui-researcher Produces UI-SPEC.md design contract for frontend … ~47
|
||||
gsd-ui-checker Validates UI-SPEC.md design contracts against 6 q… ~46
|
||||
gsd-code-fixer Applies fixes to code review findings from REVIEW… ~45
|
||||
gsd-pattern-mapper Analyzes codebase for existing patterns and produ… ~45
|
||||
gsd-ui-auditor Retroactive 6-pillar visual audit of implemented … ~43
|
||||
gsd-code-reviewer Reviews source files for bugs, security issues, a… ~42
|
||||
gsd-doc-writer Writes and updates project documentation. Spawned… ~41
|
||||
gsd-phase-researcher Researches how to implement a phase before planni… ~41
|
||||
gsd-security-auditor Verifies threat mitigations from PLAN.md threat m… ~41
|
||||
gsd-executor Executes GSD plans with atomic commits, deviation… ~38
|
||||
gsd-research-synthesi… Synthesizes research outputs from parallel resear… ~38
|
||||
gsd-user-profiler Analyzes extracted session messages across 8 beha… ~38
|
||||
gsd-verifier Verifies phase goal achievement through goal-back… ~38
|
||||
gsd-plan-checker Verifies plans will achieve phase goal before exe… ~37
|
||||
gsd-roadmapper Creates project roadmaps with phase breakdown, re… ~37
|
||||
gsd-planner Creates executable phase plans with task breakdow… ~35
|
||||
gsd-advisor-researcher Researches a single gray area decision and return… ~34
|
||||
gsd-debugger Investigates bugs using scientific method, manage… ~34
|
||||
gsd-assumptions-analy… Deeply analyzes codebase for a phase and returns … ~33
|
||||
gsd-integration-check… Verifies cross-phase integration and E2E flows. C… ~32
|
||||
general General-purpose agent for researching complex que… ~28
|
||||
gsd-doc-verifier Verifies factual claims in generated docs against… ~28
|
||||
gsd-intel-updater Analyzes codebase and writes structured intel fil… ~25
|
||||
gsd-nyquist-auditor Fills Nyquist validation gaps by generating tests… ~25
|
||||
───────────────────────────────────────────────────────────────────────
|
||||
Total: ~1,688 tokens (35 subagents available)
|
||||
|
||||
Note: Full task tool description is ~2,540 tokens (includes instructions/examples).
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
TOOL DEFINITION COSTS (Estimated from argument analysis)
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Tool Est. Tokens Args Complexity
|
||||
───────────────────────────────────────────────────────────────────
|
||||
bash ~370 3 simple
|
||||
grep ~370 3 simple
|
||||
read ~340 2 simple
|
||||
glob ~340 2 simple
|
||||
tokenscope ~310 1 simple
|
||||
───────────────────────────────────────────────────────────────────
|
||||
Total: ~ 1,730 tokens (5 enabled tools)
|
||||
|
||||
Note: Estimates inferred from tool call arguments in this session.
|
||||
Actual schema tokens may vary +/-20%.
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
CACHE EFFICIENCY
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Token Distribution:
|
||||
Cache Read: 510,464 tokens ████████████████████████░░░░░░ 80.5%
|
||||
Fresh Input: 123,385 tokens ██████░░░░░░░░░░░░░░░░░░░░░░░░ 19.5%
|
||||
───────────────────────────────────────────────────────────────────
|
||||
Cache Hit Rate: 80.5% (cache read / (cache read + fresh input))
|
||||
|
||||
Cost Analysis (deepseek-v4-pro @ $1.00/M input, $0.00/M cache read, $0.00/M cache write):
|
||||
Without caching: $0.6338 (633,849 tokens x $1.00/M)
|
||||
With caching: $0.1234 (fresh x $1.00/M + cache read x $0.00/M + cache write x $0.00/M)
|
||||
───────────────────────────────────────────────────────────────────
|
||||
Cost Savings: $0.5105 (80.5% reduction)
|
||||
Effective Rate: $0.19/M tokens (vs. $1.00/M standard)
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
SUMMARY
|
||||
─────────────────────────────────────────────────────────────────────────
|
||||
|
||||
Cost Tokens API Calls
|
||||
Session: $ 0.3008 637,321 7
|
||||
|
||||
═══════════════════════════════════════════════════════════════════════════
|
||||
Loading…
Reference in a new issue