代码语言

知识点思维导图

36 个知识节点

参考资料

项目实战（20） - 避坑指南与最佳实践

读完后，你应能完成以下任务：

绘制“项目实战（20） - 避坑指南与最佳实践 / 安装 / 启动阶段”的关键对象与数据流，解释“混用 npx 和 pnpm 前缀：npx 装的就一直用 npx paperclipai；”，并用源码位置、日志或 Trace 标注证据。

为“项目实战（20） - 避坑指南与最佳实践 / 建公司 / 招 Agent 阶段”设计正常与异常输入，验证“cwd 用相对路径或指向敏感目录：必须绝对路径 + 受控目录（因默认跳过权限）。”，输出首个偏差位置与回归测试结果。

实现“项目实战（20） - 避坑指南与最佳实践 / 运行 / 协作阶段（最容易卡的地方）”的最小代码或配置，检验“Agent 重试 409：任务有主了，必须换任务，绝不重试。”，输出命令、结果与 Diff，并说明不适用边界。

本章目标：把全书的坑和最佳实践收口成一份「自检清单」。新手避开高频坑，运营中按图索骥。这一章既是结尾，也是你日常运营时回头翻的「体检表」。

读到这里，你已经走完了从认识到上线的完整路径。这一章不引入新知识，而是把散落各章的经验按场景重新组织，方便你查。

一、先建立全局：避坑指南与最佳实践是什么？

理解“避坑指南与最佳实践”，先要把标题中的对象放进同一条处理链：它接收什么输入，经过哪些状态变化，最终用什么证据判断结果。下表不另造概念，只把作者正文已经解释的章节按依赖顺序连起来。

“避坑指南与最佳实践”的第一个核心判断是：混用 npx 和 pnpm 前缀：npx 装的就一直用 npx paperclipai；。先弄清这个判断中的对象和输入输出，后面的实现、故障和验收才有共同语境。

顺序	章节	读完本节应抓住的结论
1	安装 / 启动阶段	混用 npx 和 pnpm 前缀：npx 装的就一直用 npx paperclipai；
2	建公司 / 招 Agent 阶段	cwd 用相对路径或指向敏感目录：必须绝对路径 + 受控目录（因默认跳过权限）。
3	运行 / 协作阶段（最容易卡的地方）	Agent 重试 409：任务有主了，必须换任务，绝不重试。
4	治理 / 审批阶段	完全关掉审批：失控风险，至少留 CEO 策略审批 + 预算硬停。
5	成本阶段	预算单位填错（元当分）：$50 填 50 立刻被硬停。
6	部署 / 上线阶段	公网必须 authenticated + public。

1.1 核心对象之间怎样衔接

flowchart LR
  S1["安装 / 启动阶段"] --> S2
  S2["建公司 / 招 Agent 阶段"] --> S3
  S3["运行 / 协作阶段（最容易卡的地方）"] --> S4
  S4["治理 / 审批阶段"] --> S5
  S5["成本阶段"]

这张图只表达本文的讲解顺序，不替代正文机制。判断“避坑指南与最佳实践”是否真正掌握，需要能从最后一个结果沿图回到前面每个章节的输入、状态变化和证据。

1.2 再看失败：问题最早会出现在哪一步？

在“避坑指南与最佳实践”的对象和顺序已经明确后，再看可观察的失败：条件缺失、结果不可复现或失败后责任不清。定位时不从最后一条错误猜原因，而是沿上图找第一个偏离正文结论的节点。

二、安装 / 启动阶段

2.1 高频坑

混用 npx 和 pnpm 前缀：npx 装的就一直用 npx paperclipai；pnpm paperclipai 只在克隆的源码仓库里有效。
Node 版本 < 20：装/启动报错，先 node -v。
端口 3100 被占：paperclipai configure 换端口，或关掉占用进程。
删 ~/.paperclip/ 重置，连数据一起删：这目录装着所有公司/任务/产物，删前确认。

2.2 自检

□ node -v ≥ 20
□ 前缀用对（npx 装的用 npx）
□ 跑起来看到 UI http://127.0.0.1:3100
□ 出问题先看 ~/.paperclip/instances/default/logs/server.log

三、建公司 / 招 Agent 阶段

3.1 高频坑

目标写太虚：「做个好社区」拆不出有效任务。要具体可衡量。
一上来铺一堆 Agent：先 CEO 跑通闭环再扩。
给规划型角色用 process 适配器：CEO/工程师/QA 要用 claude_local（能 agentic）。
cwd 用相对路径或指向敏感目录：必须绝对路径 + 受控目录（因默认跳过权限）。
预算单位填错：单位是分，$50 = 5000，填 50 几乎立刻被硬停。
配完不点 Test Environment：环境问题事后查日志，远不如提前自检。

3.2 自检

□ 目标具体、可衡量（有指标）
□ 从 CEO + 必要的 1-2 个下属开始
□ 规划型角色用 claude_local / codex_local
□ 每个 Agent 独立绝对路径 cwd
□ 预算单位是分，两级（公司 + Agent）都设
□ 配完点 Test Environment 自检通过

四、运行 / 协作阶段（最容易卡的地方）

4.1 高频坑

公司「不动」：八成 CEO 策略在等审批 → 去 Approvals 页。
CEO 派活了下游不动：查下游 wakeOnAssignment 有没有开。
两个 Agent 互相等卡死：任务树断了，子任务没挂 parentId，完成事件传不上去。
Agent 重试 409：任务有主了，必须换任务，绝不重试。
手动 PATCH 任务到 in_progress：绕过签出，破坏单负责人保证，必须走 checkout。
用 @提及代替分配任务：@ 是沟通/唤醒，分活要建任务，滥用 @ 还烧预算。
取消跨团队任务：铁律禁止，交回经理处理。
Agent 卡住默不作声：必须置 blocked + 评论 blocker + 上报。

4.2 ⭐ 协作卡壳排查口诀（第 08 章核心）

协作不起来，先查两点：① 任务树挂好了吗（parentId）？② 下游会自动醒吗（wakeOnAssignment）？ 这两点解决绝大多数卡壳。别一上来就改 prompt。

4.3 自检

□ 公司不动 → 先看 Approvals 队列
□ 子任务都设了 parentId（有目标加 goalId）
□ 下游 Agent 开了 wakeOnAssignment
□ 干活前先 checkout，409 换任务不重试
□ 每次心跳留 durable 进展（评论/文档/产物）+ 下一步
□ 卡住就 blocked + 评论 + 上报，不沉默

五、治理 / 审批阶段

5.1 高频坑

审批不看 payload 就批：雇人审批藏着适配器配置和预算，闭眼批可能放进烧钱/配错的 Agent。
动不动 Terminate：不可逆。临时停用 pause。
所有动作都开审批：被审批淹没，失去自动化意义。
完全关掉审批：失控风险，至少留 CEO 策略审批 + 预算硬停。

5.2 原则

靠近「方向」和「钱」的决策要把关，靠近「执行」的要放权。

5.3 自检

□ CEO 策略审批：开
□ 雇人审批：初期开，信任后放
□ 日常执行：放权
□ 审批时认真看 payload 和关联任务
□ 临时停用优先 pause，慎用 terminate

六、成本阶段

6.1 高频坑

预算单位填错（元当分）：$50 填 50 立刻被硬停。
看到成本 0 以为免费：订阅登录不走按量计费，订阅本身有额度。
只设公司预算不设 Agent 预算：单个 Agent 可能空烧吃光公司预算。
从不看 burn rate：月底超支才发现。

6.2 自检

□ 预算单位是分，$50 = 5000
□ 公司级 + Agent 级两级预算都设
□ 分清 API Key（计费）还是订阅（可能显示 0）
□ 定期看看板的花费和 burn rate
□ 异常烧钱去 activity 审计查根因

七、部署 / 上线阶段

7.1 高频坑（含安全红线）

🚨 把免登录的 local_trusted 暴露到公网：谁都能控制你的公司。公网必须 authenticated + public。
切认证模式忘了认领董事会：访问 board-claim URL 绑定账号。
密钥写明文进 Agent 配置：用 env 密钥引用，明文会进数据库/导出包。
丢/乱备份 master.key：它能解密所有密钥，丢了全废、泄露全泄。
生产用内嵌数据库不做外部备份：生产切外部 PostgreSQL。
靠终端窗口维持运行：窗口关就停，长期运行用 Docker。

7.2 自检

□ 模式选对：本地 local_trusted / 远程 authenticated+private / 公网 authenticated+public
□ 绝不把 local_trusted 暴露公网
□ 远程优先 Tailscale（private + tailnet）
□ 切认证模式后完成 board-claim
□ 密钥全走引用，master.key 安全备份
□ 生产：Docker + 外部 PostgreSQL + 对象存储
□ 部署后跑 paperclipai doctor

八、贯穿全书的 7 条「黄金法则」

如果只记 7 条，记这些：

目标决定一切：具体可衡量的目标 + 你的「品味输入」，是产出质量的天花板。
从小开始：先 CEO 跑通闭环，再扩团队。
选对大脑：规划型用 Claude/Codex，执行型用 process/http。
干活前先 checkout，409 绝不重试：这是协作不打架的根。
任务树要完整：子任务永远挂 parentId，否则协作流转断。
靠近钱和方向的把关，靠近执行的放权：治理的平衡点。
安全红线：免登录模式绝不上公网；密钥永远引用不明文。

九、出问题时的排查顺序（总流程图）

公司/Agent 行为异常
        │
        ▼
① 看 Approvals：有没有待审批卡着？（公司不动最常见原因）
        │ 无
        ▼
② 看协作两点：parentId 挂对了吗？wakeOnAssignment 开了吗？
        │ 都对
        ▼
③ 看预算：是不是 burn 到 100% 被 paused 了？
        │ 没超
        ▼
④ 看 Run record / logs：心跳到底报了什么错？
        │
        ▼
⑤ 看 activity 审计：谁在什么时候做了什么改动？

按这个顺序查，比盲改 prompt 高效得多。

十、动手验证：先跑通避坑指南与最佳实践，再改变一个变量

前面的章节已经建立问题、概念和机制。现在把“避坑指南与最佳实践”放进同一套基线中运行；本节不再引入新术语，只验证前文结论能否被复现。

10.1 基线与候选只允许一个变量不同

验证“避坑指南与最佳实践”时，先固定样本、基线、候选、成功标准和失败边界。候选方案只能改变本次要验证的变量；如果同时更换数据、依赖和配置，即使结果改善，也不能知道是哪一项产生作用。

执行“避坑指南与最佳实践”时，动作是：同环境运行基线与候选，记录输入、中间状态和异常。原始结果不能只保留截图或汇总分数，必须同步保存：可重放命令、结构化日志、输出 Diff、失败样本、版本，使下一次复查可以在同一输入上重放。

实验要素	本文要求
固定条件	固定样本、基线、候选、成功标准和失败边界
唯一变量	本次候选方案与基线之间的一项明确差异
原始证据	可重放命令、结构化日志、输出 Diff、失败样本、版本
通过阈值	结果符合结论条件，异常输入可解释、可恢复
立即停止	条件缺失、结果不可复现或失败后责任不清

10.2 执行前先排除不可比较条件

“避坑指南与最佳实践”开始前先确认下面四项；任一项不成立，都应先修复实验条件，而不是解释结果。

基线能够在“避坑指南与最佳实践”的当前环境重复运行。
候选只改变一个与“避坑指南与最佳实践”结论直接相关的条件。
“避坑指南与最佳实践”的基线和候选使用同一批输入、同一版本依赖与同一通过阈值。
“避坑指南与最佳实践”的原始输出和失败现场不会被重试、格式化或汇总覆盖。

10.3 执行后先核对证据完整性

结果出来后先检查证据，再讨论“避坑指南与最佳实践”是否通过。缺少中间状态时，最终输出只能说明现象，不能证明机制。

检查项	当前文章的判定
输入可追溯	固定样本、基线、候选、成功标准和失败边界
过程可回放	同环境运行基线与候选，记录输入、中间状态和异常
结果可审计	可重放命令、结构化日志、输出 Diff、失败样本、版本

“避坑指南与最佳实践”的一次合格基线对照按以下顺序执行：

保存“避坑指南与最佳实践”基线版本及输入摘要，确认基线本身可以重复运行。
写下“避坑指南与最佳实践”候选方案唯一变化的变量，以及它预期影响的指标。
在同一环境执行“避坑指南与最佳实践”：同环境运行基线与候选，记录输入、中间状态和异常。
为“避坑指南与最佳实践”保存：可重放命令、结构化日志、输出 Diff、失败样本、版本。
使用“避坑指南与最佳实践”预登记条件判断：结果符合结论条件，异常输入可解释、可恢复。
如果“避坑指南与最佳实践”未通过，不修改第二个变量，先恢复基线并保留失败现场。

十一、用一张矩阵验证避坑指南与最佳实践的关键结论

矩阵按正文顺序列出“避坑指南与最佳实践”的结论。一次实验只选择一行，只改变这一行对应的条件；不要把多行合并成一个无法归因的大实验。

正文章节	已解释的结论	本轮唯一变量	必须保存的证据
安装 / 启动阶段	混用 npx 和 pnpm 前缀：npx 装的就一直用 npx paperclipai；	只改变与“安装 / 启动阶段”相关的条件	可重放命令、结构化日志、输出 Diff、失败样本、版本
建公司 / 招 Agent 阶段	cwd 用相对路径或指向敏感目录：必须绝对路径 + 受控目录（因默认跳过权限）。	只改变与“建公司 / 招 Agent 阶段”相关的条件	可重放命令、结构化日志、输出 Diff、失败样本、版本
运行 / 协作阶段（最容易卡的地方）	Agent 重试 409：任务有主了，必须换任务，绝不重试。	只改变与“运行 / 协作阶段（最容易卡的地方）”相关的条件	可重放命令、结构化日志、输出 Diff、失败样本、版本
治理 / 审批阶段	完全关掉审批：失控风险，至少留 CEO 策略审批 + 预算硬停。	只改变与“治理 / 审批阶段”相关的条件	可重放命令、结构化日志、输出 Diff、失败样本、版本
成本阶段	预算单位填错（元当分）：$50 填 50 立刻被硬停。	只改变与“成本阶段”相关的条件	可重放命令、结构化日志、输出 Diff、失败样本、版本
部署 / 上线阶段	公网必须 authenticated + public。	只改变与“部署 / 上线阶段”相关的条件	可重放命令、结构化日志、输出 Diff、失败样本、版本

11.1 记录本次实际实验

下面的记录用于“避坑指南与最佳实践”当前这一次实验，不是第二套知识目录。先从矩阵选择一个章节，再填写实际值；没有填写的字段表示尚未验证。

topic: "避坑指南与最佳实践"
selected_chapter: required
claim_from_article: required
baseline_version: required
changed_condition: exactly_one
execution: "同环境运行基线与候选，记录输入、中间状态和异常"
evidence: "可重放命令、结构化日志、输出 Diff、失败样本、版本"
pass_when: "结果符合结论条件，异常输入可解释、可恢复"
stop_when: "条件缺失、结果不可复现或失败后责任不清"
observed_result: required
first_deviation: null_or_evidence
recovery_replay: required_after_failure

11.2 边界实验必须证明能够停止和恢复

成功路径只能证明“避坑指南与最佳实践”在当前样本上工作，不能证明它可以进入生产。边界实验需要主动制造：条件缺失、结果不可复现或失败后责任不清，并观察系统是否在产生不可逆副作用前停止。

场景	只改变什么	应保存什么	通过标准
正常路径	使用已知有效输入	可重放命令、结构化日志、输出 Diff、失败样本、版本	结果符合结论条件，异常输入可解释、可恢复
边界路径	把一个输入推进到约束临界值	临界值前后的输出与指标	不静默降级，不把部分结果冒充成功
明确失败	注入：条件缺失、结果不可复现或失败后责任不清	原始错误、首个异常阶段和最终状态	失败被正确分类且没有扩大副作用
恢复重放	执行：保留基线，缩小变量；根因确认前不扩大范围	原失败样本的复测证据	原样本恢复，正常样本没有回归

恢复动作不是简单重启。对于“避坑指南与最佳实践”，第一步是：保留基线，缩小变量；根因确认前不扩大范围。完成后使用原始失败样本复测；只验证一个新样本成功，不能证明触发条件已经消失。

“避坑指南与最佳实践”边界实验结束后，应把正常、临界、失败和恢复四类记录放在同一个运行批次中。这样才能区分“候选方案真的修复问题”和“环境变化让问题暂时没有出现”。

十二、避坑指南与最佳实践的结果解释

解释“避坑指南与最佳实践”实验时先看首个偏差，而不是最后一条错误。最后的异常通常只是上游状态错误的结果；从末端反推容易误把症状当根因。

观察结果	可以支持的判断	下一步
主链路没有达到预期	条件缺失、结果不可复现或失败后责任不清	先执行：保留基线，缩小变量；根因确认前不扩大范围
异常链路无法恢复	条件缺失、结果不可复现或失败后责任不清	先执行：保留基线，缩小变量；根因确认前不扩大范围
新样本成功但原样本仍失败	修复没有覆盖原始触发条件	固定原失败输入，恢复基线后重新比较
指标改善但证据无法回链	数据、版本或中间状态没有固定	暂停发布，补齐可追溯记录后重跑

“避坑指南与最佳实践”只有同时满足“结果符合结论条件，异常输入可解释、可恢复”，并且没有出现“条件缺失、结果不可复现或失败后责任不清”，才可以认为主链路通过。这里的“通过”只对当前固定版本、样本和环境有效，不能外推到尚未测试的容量、权限或数据分布。

如果“避坑指南与最佳实践”候选方案与基线差异很小，先检查证据分辨率是否足够；如果差异很大，先排除数据泄漏、环境漂移和版本不一致。两种情况都不能只看一个汇总均值，需要回到逐样本输出和中间状态。

“避坑指南与最佳实践”故障定位完成后，记录“现象、首个偏差、根因、改动、原样本复测”五项。缺少原样本复测时，只能标记为待观察，不能标记为已解决。

十三、避坑指南与最佳实践的发布判断

发布判断需要把“避坑指南与最佳实践”的质量、失败边界和恢复能力放在同一份记录中。以下任一条件缺失，都应停止扩量，而不是用“基本正常”替代证据。

“避坑指南与最佳实践”的基线与候选只存在一个计划内变量。
“避坑指南与最佳实践”的输入、代码、依赖、配置和数据版本可以追溯。
“避坑指南与最佳实践”的正常、临界、失败和恢复样本使用同一套断言。
“避坑指南与最佳实践”的原始输出、中间状态和失败现场已经保留。
“避坑指南与最佳实践”的日志、Trace、截图和测试数据已经脱敏。
“避坑指南与最佳实践”的停止条件、负责人和回滚入口已经演练。
“避坑指南与最佳实践”尚未覆盖的输入、权限、容量和外部依赖已经登记。

最终记录至少包含基线版本、唯一变量、原始证据、首个偏差、恢复复测和发布责任人。没有参与本次修改的人如果不能据此重放“避坑指南与最佳实践”的判断，就不能发布。

十四、总结

安装 / 启动阶段：混用 npx 和 pnpm 前缀：npx 装的就一直用 npx paperclipai；
建公司 / 招 Agent 阶段：cwd 用相对路径或指向敏感目录：必须绝对路径 + 受控目录（因默认跳过权限）。
运行 / 协作阶段（最容易卡的地方）：Agent 重试 409：任务有主了，必须换任务，绝不重试。
治理 / 审批阶段：完全关掉审批：失控风险，至少留 CEO 策略审批 + 预算硬停。
成本阶段：预算单位填错（元当分）：$50 填 50 立刻被硬停。
部署 / 上线阶段：公网必须 authenticated + public。