paper-piggy: Instructions file for Codex

PaperPiggy · 论文小猪 —— AI 开发 agent 总纲

你是接手这个项目的 AI agent。这份文件是你的唯一入口。 读完它 + docs/ARCHITECTURE.md + docs/MAINTENANCE.md，你就具备了动手的全部前提。 本文件与任何其他文档冲突时，以本文件为准。

---

0. 工作规则（最高优先级，先读这一节）

0.1 先调研，需要决策的问用户

任何涉及以下情形的动作，先给「问题 + 2~4 个选项 + 你的推荐 + 一句话理由」，等用户拍板，绝不自作主张执行：

• 删除数据、删除文件、删除目录
• 改动目录结构
• 花钱（批量 LLM 调用：嵌入 1400+ 篇、期刊分级、SAC 补生成，都是真金白银）
• 外部账号与发布（GitHub 建仓/推送/Release、密钥、云存储）
• 产品取舍（功能怎么做、UI 怎么改、默认值定成什么）

动手之前先调研。 不要看到一个文件名就开始改；先把相关链路读通，再动。 这条规则是用户明确要求写进项目指引的，不是建议，是要求。

0.1b ★ 用户机器上装了正式版应用 —— 那个目录你只读，绝不写

用户本人在这台机器上装了 PaperPiggy 正式版，和这个开发仓库是两码事：

	路径	你能做什么
开发仓库（本项目）	D:\Onedrive\AI\知识库应用	✅ 读、改、跑、打包 —— 所有修复都在这里做
用户的正式安装	D:\PaperPiggy\	👀 只读（看日志、看文件是否存在、复现问题）⛔ 绝不修改任何文件，不改代码、不改配置、不删数据、不"顺手帮他修一下"

用户反馈 bug 时的正确姿势：

1. 需要的话，只读地去安装目录看现象（日志、文件在不在、版本号）
2. 在 src\ 里定位并修复
3. 在开发态（build\py312\python.exe src\launcher.py）或临时目录里验证
4. 报告修好了 —— 用户自己会去更新他的应用，不用你代劳

这是用户明确要求的：开发文件和应用文件必须分开。他要改应用文件的话，会自己在应用文件夹里另开一个项目。 （理由也很实在：你在安装目录里的任何改动，都会在他下次更新时被覆盖，而且会让「到底跑的是哪份代码」变得不可知 —— 这正是旧铁律 sync_app.ps1 时代的幽灵 bug 来源，见 §3。）

0.2 花钱前先估算并报告

批量 LLM 调用之前，先估算「多少条 × 多少 token × 什么单价 ≈ 多少钱」，报给用户，等确认。 用户用的是硅基流动（SiliconFlow）。

0.3 _archive/ 是历史，不是待办

_archive/ 下的文档全部已实施完毕，每份开头都有「⛔ 归档件·请勿执行」戳。 它们是「当时为什么这么决定」的存档。不要照着它们重跑改造。 里面有几份写着「把这份文档整段发给一个新对话并从头到尾执行」——那是给 2026 年 7 月的那次对话的，不是给你的。

全仓 grep / 搜索时排除 _archive/，否则你会在过期副本里改错文件。

0.4 报告要诚实

跑失败了就说失败并贴输出；跳过了某步就说跳过；只有真正做完并验证过，才说做完了。 不要用「应该可以」「理论上」粉饰未经验证的改动。

0.5 两条硬约束（用户 2026-07-15 明确要求，写进指引长期生效）

① 每次 push / 发 GitHub Release 前，通读面向用户的文案，清掉过期表述和修订残留。 README / CHANGELOG / release notes 会被全世界看到。改文案时别留「修一半」的痕迹—— 典型反例：（…比如 D:\PaperPiggy\，不在你的 Zotero 文库旁边）多出两个文件夹 这种 把旧错误的否定式硬塞进括号、读起来别扭的句子。发布前整体读一遍，当成新读者第一次看。

② 绝不弹终端 / 控制台黑窗。 所有 subprocess.Popen/run 在 Windows 上必须 pythonw.exe + creationflags=0x08000000 （CREATE_NO_WINDOW）。以后加任何拉起进程的新功能（更新、导出、外部工具…）， 默认就得无窗。踩过：updater 的 _importable 少了这个 flag，升级时闪黑窗。