mirror of
https://github.com/lllin000/PaperForge.git
synced 2026-07-22 17:00:23 +00:00
99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# 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 自动化验证
|
||
|
||
1. 类型检查通过
|
||
2. 已有测试全部通过（`python -m pytest tests/ -q --tb=short`）
|
||
3. 新增代码有对应测试覆盖（至少一条断言走通新路径）
|
||
4. lint clean（`ruff check paperforge/`）
|
||
|
||
---
|
||
|
||
## 1. 工作指示
|
||
|
||
### Codebase Memory 优先
|
||
|
||
有 `codebase-memory-mcp` 知识图，结构查询优先用 `search_graph` / `trace_path`，不用 grep/glob。
|
||
|
||
### 测试命令
|
||
|
||
```bash
|
||
# 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/getting-started.md) |
|
||
| 命令参考 | [docs/COMMANDS.md](docs/COMMANDS.md) |
|
||
| 架构 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
|
||
| 故障排除 | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
||
| 项目计划/状态 | `project/current/*.md` |
|
||
| 设计文档 | `docs/superpowers/specs/` |
|