PAPOP v6.3.1 · Portable Agent Project Operating Protocol

English · 实现原理 · 安装细节 · 从 V5 升级 · 账本格式（开发者） · 更新记录

PAPOP 是一套给 AI Agent 用的项目规则 + 记账工具。装好之后，你让 Agent 做一个要花好几天、好几次对话的项目，它不会做着做着忘了目标，也不会把你没批准的东西当成批准过。

先说两个词

• Agent： 能自己读写文件、运行命令、一步步把事做完的 AI。它和普通聊天机器人不同，会真的动手改你电脑上的文件。
• Harness： 你用来和 Agent 对话的那个软件，比如 Claude Code、Codex（ChatGPT 桌面版 / 命令行）、OpenCode、ZCode、DeepSeek Harness。你在 Harness 里选一个文件夹，Agent 就在这个文件夹里工作。

它解决什么问题

和 Agent 做一个大项目时，常见这些麻烦：

麻烦	为什么会这样	PAPOP 怎么办
聊久了，Agent 忘了最初要做什么	Agent 只记得当前对话；对话太长会被"压缩"，换一个新对话就全忘了	目标、计划、进度、你的每个决定都写进项目里的文件。新对话里 Agent 先读文件，再向你复述现状
你随口说了句"你帮我做吧"，它就当所有事都批准了	没有明确的"审批"环节	严格模式有 4 个关卡：确认需求、审批目标、审批每一阶段的计划、验收成果。每一关都要你明确表态
计划改了，它还拿旧的批准当依据	批准没和具体内容绑在一起	每次批准都和那一版的内容绑定；内容被改过，工具会拒绝继续
"当时为什么这么定"想不起来	聊天记录翻不到，或者已经被压缩	你的原话一字不改地记下来，可以按关键词查
同一个坑踩了一遍又一遍	新对话不知道以前出过什么问题	同一类问题第 3 次出现时，Agent 会问你要不要记成经验，以后先读经验再动手

记账全部由 papop 工具完成：编号、时间、状态都由工具写。Agent 只写内容（需求复述、目标、计划、交付说明），你只负责审批和验收。

用了之后是什么样子

• 你开一个新对话，只说"继续"，Agent 会告诉你：这个项目要做什么、做到第几阶段、你批准过什么、带了什么条件、现在在等谁。
• 每到需要你拍板的地方，Agent 会停下来，把要审的内容简要讲给你听，等你回复。
• 你说"停"，它立刻停手；换了对话也不会自己接着做，等你说"继续"。
• 删除文件、推送代码、部署、付费这类事，不管什么模式，它都会先问你。
• Agent 说"做完了"不算数，要你看过实际成果、说"验收通过"才算。

开始之前要准备什么

1. 一个 Harness，已经能正常和 Agent 对话。
2. Python 3.12 或更高版本。 安装器和 papop 工具都用它运行。
   • 不确定有没有：Windows 上按 Win + R，输入 cmd 回车，在黑色窗口里输入 python --version 回车。显示 Python 3.12.x 或更高就可以。
   • 没有：去 python.org 下载安装。Windows 安装时，记得勾选第一页底部的"Add python.exe to PATH"。
3. 一个专门放项目的文件夹，比如 D:\我的Agent项目。PAPOP 会把规则装进这个文件夹，以后在这里做的项目都受它管。这个文件夹叫工作区。

安装（只需一次，约 5 分钟）

1. 下载发布包 portable-agent-project-operating-protocol-v6.3.1.zip，完整解压到一个新文件夹。

2. Windows： 双击 install.bat。macOS / Linux： 在终端里进入解压后的文件夹，运行 sh install.sh。

3. 在弹出的窗口里依次选：

   窗口里的选项	怎么选
   1 · 安装范围	你已经有自己写的全局规则（比如 ~/.claude/CLAUDE.md），选"仅工作区"，PAPOP 不会动它们；没有，选"全局规则 + 工作区"，顺便装一套通用的 Agent 行为规则
   2 · Harness	装了的会自动勾上，一般不用改。选了"仅工作区"时这一项不可选
   3 · 工作区	点"浏览一个目录"，选你准备好的文件夹。每个工作区选一个默认模式：拿不准就选严格模式（下面"两种模式"有说明）

4. 点"检查并安装"。这一步只检查、不写文件，会列出每个文件是"新建""覆盖"还是"追加"。

5. 看一眼没问题，点"确认安装（开始写入）"。已有的同名文件会先备份到工作区的 .papop-backups/。

6. 在 Harness 里打开这个工作区文件夹，开一个新对话，问它："你加载了哪些规则？现在是什么模式？"它能答出 PAPOP 和你选的模式，就说明装好了。

没有图形界面的电脑会自动改用命令行问答，问的内容一样。更多细节（各 Harness 的全局目录、重复安装、卸载）见 安装细节。

第一个项目：从头走一遍

下面是在严格模式下做一个小项目的样子。你只需要用平常说话的方式回复，不用记任何命令。

1. 你说： "开始一个新项目：写一个打印 Hello 的脚本。" Agent 建好项目，先和你讨论需求：用什么语言、放在哪里、要不要别的功能。它不会一上来就写代码。
2. Agent 交来"需求复述"：把它理解的需求写成一段话请你确认。你说： "对。"（不对就直接说哪里不对。）
3. Agent 交来"Goal"：项目最终要什么、怎么算完成。你说： "批准。"
4. Agent 交来本阶段的"Plan"：这一阶段做什么、怎么验证。你说： "批准。"
5. Agent 施工，每做完一步记一句进展。这期间你可以不管，也可以随时插话。
6. Agent 交来"交付说明"：成果在哪、怎么验证的、结果如何。你去看实际成果，没问题就说"验收通过"，有问题就说哪里不行，它会返工。
7. 项目大的话，会从第 4 步开始进入下一阶段，直到 Goal 全部达成。
8. Agent 交来"完成申请"，逐条对照 Goal 写明怎么满足的。你说： "确认完成。"项目结束。

flowchart TD
    A[讨论需求] --> B{你确认需求复述}
    B -- 不对 --> A
    B -- 对 --> C{你审批 Goal}
    C -- 要改 --> C
    C -- 批准 --> D{你审批本阶段 Plan}
    D -- 要改 --> D
    D -- 批准 --> E[Agent 施工]
    E --> F{你验收交付}
    F -- 不通过 --> E
    F -- 通过 --> G{Goal 全部达成?}
    G -- 没有 --> D
    G -- 达成 --> H{你确认项目完成}
    H -- 还差点 --> D
    H -- 确认 --> I[项目完成]

Loading

什么时候该做什么

时间点	你要做的事
开始一个项目	说"开始一个新项目：……"，把最终想要什么说清楚。只是问问题、聊天时，Agent 不会建项目
Agent 交来需求复述、Goal、Plan	认真看，再回复（怎么回复见下一节）。同一时刻只有一项在等你，不用说编号
Agent 施工中	可以不管。想改做法、想停，随时说
Agent 说"做完了"、交来交付说明	打开实际成果看，别只看它的描述。满意说"验收通过"
Agent 要删文件、推送、部署、付费等	它会先停下来问你。看清楚它要做什么、影响什么，再说"可以"或"不行"
你想让它某件事之前先问你	直接说，比如"部署前先问我"。这条会一直记着，换对话也不忘
对话太长、想压缩上下文	最好在一个阶段验收完之后再压缩，这时记录最完整。压缩后它会自己重新读状态
换一个新对话继续	只说"继续"。听它复述现状，哪里不对马上纠正
想暂停、不做了	说"停"或"这个项目不做了"
项目重要，想留一份备份	说"备份一下这个项目"

关卡上怎么回复

• 同意： "批准""可以""行""没问题"都可以。
• 同意，但有条件： 直接说，比如"批准，但先别部署"。这个条件会一直显示在状态里，施工时 Agent 必须遵守。条件说得太含糊（比如"细节你看着办"），它会先问清楚。
• 要修改： 说哪里不行，比如"第 3 步换个做法"。你的原话会被记下，作为修改意见。
• 拿不准： 比如回一句"差不多吧"，Agent 会先问清楚，不会当成批准。

你没回复，不等于同意。Agent 绝不能替你批准，也不能把它自己的话当成你的原话。

两种模式

模式	适合谁	关卡由谁过
严格模式	想每一步都把关；第一次用 PAPOP 的人	需求复述、Goal、Plan、交付都等你
自主模式	愿意把项目交给 Agent，只在关键处看一眼	Agent 自己审核需求复述、Goal、Plan、交付，记为"自主通过"，和你的批准分开记录

自主模式也有几条它不能自己做主：

• 第一版需求复述和 Goal 之后，再改需求或 Goal，都要你批准。Agent 不能自己把目标改松；
• 项目完成只能由你确认；
• 下面这些事，两种模式都要先问你。

不管哪种模式，Agent 都必须先问你的事：

• 删除文件或数据、覆盖你的改动、改写版本历史这类做了就难撤回的事；
• 发送消息、发布、付费、推送代码、部署、改线上环境这类会影响到外面的事；
• 你在批准条件里限制过的事；
• 你说过"……之前先问我"的事。

安装时给工作区选的模式，只是新项目的默认值。项目建好后想换，跟它说"这个项目改成自主模式"（或严格模式）即可，它会记下你的原话再换，不会自己换。

中途改主意

你说	会发生什么
"第 2 步换个做法"	Agent 交一版新 Plan 等你批准。你不批准的话，旧 Plan 仍然有效，它按旧的继续做
"新的不行，旧的也先别按着做了"	它立刻停手，记一条"按旧版施工前先问我"，再改一版交给你。你批准新版后，这条限制才取消
"验收标准改一下"	Agent 交一版新 Goal。批准后，原来的 Plan 继续做
"我还想加一个功能"	Agent 交一份新的需求复述。你确认后，旧的 Goal 和 Plan 都作废，要重写 Goal；正在做的阶段没交付的部分记为"终止"

拿不准属于哪一种时，Agent 会问你。

停下来

情况	会发生什么
你说"停""先别做了"	立刻停手并记下你的原话。换了对话也不会自己接着做，等你说"继续"
Agent 卡住了（缺信息、缺权限）	它记下卡在哪、需要什么，然后告诉你
对外的动作结果不明（比如推送时断网）	它记下来，不会自己重做，先查清楚或问你
你说"这个项目不做了"	项目取消。以后你明确说要重新开始，它才会重新打开

想自己看一眼状态（可选）

一般不需要，Agent 会告诉你。想自己核对的话：

1. Windows 上打开工作区文件夹，在资源管理器顶部的地址栏输入 cmd，回车，会打开一个黑色窗口。

2. 输入下面这行，回车：

   .agent-protocol\tools\papop.cmd status
   

   macOS / Linux 在终端里进入工作区，运行 sh .agent-protocol/tools/papop.sh status。

它会显示项目名、第几阶段、现在在等谁、下一步是什么。顶部出现【在等你】【已暂停】这类标记时，说明需要你处理。这个命令只读，不会改任何东西。

文件放在哪里

你的工作区/
├── AGENTS.md                  给 Agent 看的规则
├── CLAUDE.md                  只有一行，让 Claude Code 也去读 AGENTS.md
├── .agent-protocol/tools/     papop 工具
├── .papop-backups/            安装时备份的旧文件
└── tasks/
    └── task1_20261026_项目名/  一个项目一个文件夹，换对话也一直用它
        ├── .agent-state/      记账的文件（"账本"），由工具写，请不要手改
        ├── UserInput/         你给 Agent 的文件，会先复制一份放在这里
        └── ……                  项目自己的文件

点号开头的文件夹（如 .agent-state）在有些系统里默认隐藏，看不到是正常的。

你让 Agent 看桌面上的某个文件时，它会先复制一份到项目的 UserInput/ 里再读，原件不动、不删。

备份与搬家

PAPOP 不会自动备份。 .agent-state/ 还默认被 Git 忽略，也就是说即使你用 Git，账本也不在版本库里。

• 备份： 对 Agent 说"备份一下这个项目"。它会打一个 ZIP 放到工作区的 papop-exports/ 里，告诉你路径。默认只打包账本；想连项目文件一起，就说"全部打包"。
• 搬到别的电脑或工作区： 在新的地方装好 PAPOP，把 ZIP 拷过去，对 Agent 说"把这个备份导进来：<ZIP 的路径>"。它导入后会先检查，再向你复述现状。新地方已有同名项目时，导入会被拒绝，不会覆盖。

也可以直接复制整个项目文件夹，记得带上隐藏的 .agent-state/。

常见问题

• 双击 install.bat 提示找不到 Python： 按上面"开始之前"装 Python，记得勾选"Add python.exe to PATH"，然后重新双击。
• 我已经有自己的全局规则，怕被覆盖： 安装范围选"仅工作区"。就算选了全局，覆盖前也会备份到 .papop-backups/。
• Agent 好像没按规则来： 先问它"你加载了哪些规则"。答不出 PAPOP，说明你打开的不是装了 PAPOP 的工作区，或者 Harness 没有读工作区的 AGENTS.md。
• 提示"另一个会话正在写这个项目"： 你同时开了两个对话在改同一个项目。等一会儿再试，不要删 .lock 文件。
• 提示账本对不上： 通常是有人手改了 .agent-state/ 里的文件。Agent 会检查并告诉你哪里不对，你同意后它再修复，修之前会留备份。
• 想升级到新版本： 用新版本的安装包对同一个工作区再装一次。旧规则会先备份，tasks/ 里的项目一个字节都不动。

PAPOP 不做什么

• 不防"故意使坏"的 Agent。 PAPOP 的前提是 Agent 遵守规则、你认真审 Plan。关卡靠 Agent 守规矩，工具不会强行拦截它运行的命令。
• 不接管 Harness。 不读你的聊天记录，不装钩子，不依赖任何一家 Harness 的特殊功能。
• 不保证极端情况下的安全，比如断电时正在写、项目放在网络盘上、多台电脑同时写同一个项目。同一台电脑上两个对话同时写，工具会加锁排队。
• 不导入 V5 的项目。 V5 的项目请用 V5 做完，见 从 V5 升级。

许可

MIT License © 2026 Canpu