PaperForge — Agent Operating Guide

面向 AI Agent 的工作指示。项目文档在 project/，代码文档在 docs/。

0. 完成检查 — 对抗性审查 + 第一性原理

每个开发任务完成后（commit 前），必须运行以下检查：

0.1 对抗性审查（切换为批评者角色）

把自己当做专门挑错的审查者，不信任自己刚写的代码：

安全与边界：输入校验在哪？信任边界在哪？如果传恶意/畸形数据会怎样？
正确性：条件分支都覆盖了吗？负逻辑、空值、边界值？竞态条件？
错误处理：失败路径都处理了吗？异常后会留下脏状态吗？
隐藏依赖：有没有假设某个函数/变量/环境一定存在？如果它变了呢？
Spec 对齐：代码真的解决了需求里的问题，还是只修了症状？每条审查发现必须标注 severity（CRITICAL / MAJOR / MINOR），CRITICAL 必须修复才能提交。

⚠️ 对抗性审查产生的修改必须先讨论，不能直接改

对抗性审查发现的问题 → 先用第一性原理分析根因和方案 → 向用户报告并询问是否要修，不能直接上手改。

原因是：对抗性审查是挑错模式，倾向于过度工程化（为边缘情况加复杂逻辑）。用户了解全局优先级，可能认为当前方案"足够好"、风险可接受、或已有其他计划。直接改会浪费精力、引入未对齐的复杂度。

唯一例外：确认是 CRITICAL 安全漏洞或数据丢失 bug，可以先修再报告。

0.2 第一性原理检查

回归最基本的问题，质疑所有假设：

这真的是要解决的问题吗？ 还是我修了表面症状？
为什么现有方案不够？ 根因是什么？为什么不直接在根因上修？
有没有更简单的方法？ 标准库 / 平台功能 / 已有依赖能不能搞定？能不能删代码而不是加代码？
这个改动值的吗？ 复杂度 vs 收益合理吗？有没有过度设计？
如果从零开始，我还会这么设计吗？ 现有代码的哪些假设在误导我？

0.3 自动化验证

类型检查通过
已有测试全部通过（python -m pytest tests/ -q --tb=short）
新增代码有对应测试覆盖（至少一条断言走通新路径）
lint clean（ruff check paperforge/）

1. 工作指示

Codebase Memory 优先

有 codebase-memory-mcp 知识图，结构查询优先用 search_graph / trace_path，不用 grep/glob。

测试命令

# Python 全量
python -m pytest tests/ -q --tb=short

# 按模块
python -m pytest tests/ -q --tb=short -k "figure or table or role"
pytest tests/test_ocr_blocks.py -q --tb=short

# JS plugin
cd paperforge/plugin && npx vitest run

Ponytail 模式 — 始终默认激活

每次写代码前先激活：

1. 这东西真的需要写吗？（YAGNI）
2. 标准库能搞定吗？用标准库。
3. 平台原生功能覆盖了吗？用平台功能。
4. 已经装好的依赖能解决吗？用已有依赖。
5. 能不能一行写完？写一行。
6. 只有以上都否定，才写最少可行代码。

@ponytail: {limit, upgrade_path} 标注每个 shortcut 的上限。非平凡逻辑留一个可运行的自检。

PROJECT-MANAGEMENT 更新规则

每个会话结束前更新 PROJECT-MANAGEMENT.md：每条 fix 记录问题→根因→修复→结果→测试状态。同步 resolved/remaining issues。

文档地图

受众	文件
终端用户教程	docs/getting-started.md
命令参考	docs/COMMANDS.md
架构	docs/ARCHITECTURE.md
故障排除	docs/troubleshooting.md
项目计划/状态	`project/current/*.md`
设计文档	`docs/superpowers/specs/`

3.8 KiB Raw Blame History Unescape Escape