paperclip-dev

Paperclip 开发

本技能涵盖本地 Paperclip 实例的日常开发和运维工作流。假设你正在 Paperclip 仓库检出目录中操作，且 origin 指向 [email protected]:paperclipai/paperclip.git。

开源规范： 此仓库面向公众。请将推送到 origin 的所有内容视为可公开发布的内容。切勿提交或推送机密、API 密钥、令牌、私人日志、个人身份信息、客户数据，或应保密的机器本地配置。也请保持 git 历史整洁：避免推送一次性分支、嘈杂的检查点提交，或无需共享到上游的试验性工作。

必须遵守： 在运行任何 CLI 命令、构建、测试或管理工作树之前，必须先阅读 Paperclip 仓库中的 doc/DEVELOPING.md。该文档是所有 paperclipai CLI 命令及其选项、构建和测试工作流、数据库操作、工作树管理和诊断的权威参考。不要猜测标志或选项——请先阅读文档。

常用命令速查

以下是最常用的命令。完整的选项表和详细信息请参阅 doc/DEVELOPING.md。

任务	命令
启动服务（首次或常规启动）	npx paperclipai run
开发模式并热重载	pnpm dev
停止开发服务器	pnpm dev:stop
构建	pnpm build
类型检查	pnpm typecheck
运行测试	pnpm test
运行迁移	pnpm db:migrate
重新生成 Drizzle 客户端	pnpm db:generate
备份数据库	npx paperclipai db:backup
健康检查	npx paperclipai doctor --repair
打印环境变量	npx paperclipai env
触发 Agent 心跳	npx paperclipai heartbeat run --agent-id <id>
在本地安装 Agent 技能	npx paperclipai agent local-cli <agent> --company-id <id>

从 Master 拉取

git fetch origin && git pull origin master
pnpm install && pnpm build

如果有架构变更合并，还需运行 pnpm db:generate && pnpm db:migrate。

工作树

Paperclip 工作树将 git 工作树与隔离的 Paperclip 实例结合起来——每个工作树都有自己的数据库、服务器端口和从主实例初始化的环境。

必须遵守： 在创建或管理工作树之前，必须先阅读 doc/DEVELOPING.md 中的“工作树本地实例”和“工作树 CLI 参考”部分。该文档是所有工作树命令及其选项、种子模式和环境变量的权威参考。

何时使用工作树

• 启动需要独立 Paperclip 环境的功能分支
• 并行运行 Agent 工作，避免与主实例相互影响
• 合并前隔离测试 Paperclip 更改

命令概览

CLI 分为两个层级（完整的选项表请参阅 doc/DEVELOPING.md）：

命令	用途
worktree:make <name>	一步创建工作树和隔离实例
worktree:list	列出工作树及其 Paperclip 状态
worktree:merge-history	预览/导入工作树之间的问题历史记录
worktree:cleanup <name>	移除工作树、分支和实例数据
worktree init	在现有工作树中初始化实例
worktree env	打印工作树实例的 shell 导出语句
worktree reseed	使用另一个实例刷新工作树数据库
worktree repair	修复损坏或缺失的工作树实例元数据

典型工作流

# 1. Create a worktree for a feature
npx paperclipai worktree:make my-feature --start-point origin/main

# 2. Move into the worktree (path printed by worktree:make) and source the environment
cd <worktree-path>
eval "$(npx paperclipai worktree env)"

# 3. Start the isolated Paperclip server
npx paperclipai run

# 4. Do your work

# 5. When done, merge history back if needed
npx paperclipai worktree:merge-history --from paperclip-my-feature --to current --apply

# 6. Clean up
npx paperclipai worktree:cleanup my-feature

Fork — 优先推送到用户 Fork

如果用户已将 paperclipai/paperclip 的个人 Fork 配置为 git 远程仓库，请将功能分支推送到该 Fork，而不是在主仓库中创建分支。这样可以保持上游分支列表整洁，也符合标准的开源贡献流程。

检测 fork 远程仓库

推送或创建 PR 之前，列出远程仓库，并检查是否有一个指向非 paperclipai GitHub fork 的远程仓库：

git remote -v

将 URL 指向 github.com:<user>/paperclip（或 github.com/<user>/paperclip.git）的任何远程仓库视为用户的 fork。常见名称有 fork、<username> 或 myfork。指向 paperclipai/paperclip 的 origin 或 upstream 是规范上游仓库——如果存在 fork，请勿向其推送功能分支。

推送到 fork

# Push the current branch to the user's fork and set upstream
git push -u <fork-remote> HEAD

然后从 fork 分支创建 PR：

gh pr create --repo paperclipai/paperclip --head <fork-owner>:<branch-name> ...

从跟踪 fork 的分支运行时，gh pr create 通常会自动确定 head 引用；如果无法确定，显式使用 --head <owner>:<branch> 是可靠的备用方式。

不存在 fork 时

如果 git remote -v 只显示 paperclipai/paperclip 远程仓库（没有用户的 fork），则像之前一样，将分支推送到 origin。请勿擅自替用户创建 fork——先征求同意。

保持 fork 为最新状态

指向 paperclipai/paperclip 的规范远程仓库可能名为 origin 或 upstream，具体取决于用户如何设置仓库。按照“检测 fork 远程仓库”步骤中的相同方法识别它，然后从该远程仓库获取并向其推送，以确保无论采用哪种命名方式，同步都能正常工作：

UPSTREAM_REMOTE=$(git remote -v | awk '/paperclipai\/paperclip.*\(fetch\)/{print $1; exit}')
git fetch "$UPSTREAM_REMOTE"
git push <fork-remote> "${UPSTREAM_REMOTE}/master:master"

Pull Requests

强制预检： 创建任何 pull request 之前，必须先阅读下列规范源文件。在阅读这些文件并确认 PR 正文符合每个必需章节之前，请勿运行 gh pr create。

第 1 步 — 阅读规范文件

创建 PR 之前，必须阅读以下三个文件：

1. .github/PULL_REQUEST_TEMPLATE.md — PR 正文的必需结构
2. CONTRIBUTING.md — 贡献规范、PR 要求和思路路径示例
3. .github/workflows/pr.yml — 阻止合并的 CI 检查

第 2 步 — 根据此清单检查 PR 正文

阅读模板后，确认 --body 包含以下每个章节（名称必须完全一致）：

• ## Thinking Path — 使用引用块格式，包含 5-8 个推理步骤
• ## What Changed — 列出具体变更
• ## Verification — 说明审阅者如何确认功能正常
• ## Risks — 说明可能出现的问题
• ## Model Used — 提供服务商、模型 ID、版本和能力
• ## Checklist — 从模板复制并勾选完成的事项

如果缺少任何章节，或任何章节内容为空，请勿提交 PR。返回并补全内容。

第 3 步 — 创建 PR

只有完成第 1 步和第 2 步后，才能运行 gh pr create。使用模板内容作为 --body 的结构——不要撰写自由格式的摘要。

硬性规则 — 不得绕过

制定这些规则是因为 Agent 曾在 CLI 失败后擅自变通，造成了实际损失。请严格遵守。

1. CLI 是操作工作树和数据库的唯一接口。 所有工作树和数据库操作都必须通过 npx paperclipai / pnpm paperclipai 命令完成。严禁：

   • 运行 pg_dump、pg_restore、psql、createdb、dropdb 或任何原始 postgres 命令
   • 手动设置 DATABASE_URL，让工作树服务指向另一个实例的数据库
   • 对任何 .paperclip/、.paperclip-worktrees/ 或 db/ 目录运行 rm -rf
   • 直接操作内嵌的 postgres 数据目录
   • 按 PID 终止 postgres 进程

2. 如果 CLI 命令失败，请停止并报告。 不得尝试变通。如果 worktree:make、worktree reseed、worktree init、worktree:cleanup 或任何其他 paperclipai 命令失败：

   • 在任务评论中报告确切的错误消息
   • 将任务设为 blocked
   • 建议运行 npx paperclipai doctor --repair，或从头重新创建工作树
   • 不得尝试手动复现 CLI 的操作

3. 绝不在多个实例间共用数据库。 每个工作树实例都必须使用独立的数据库。绝不要覆盖 DATABASE_URL，让一个实例指向另一个实例的数据库。这会破坏隔离性，并可能损坏生产数据。

4. 在工作树中启动开发服务器前，必须先完成设置。 正确顺序如下：

   # If the worktree already exists but has no running instance:
   cd <worktree-path>
   eval "$(npx paperclipai worktree env)"
   pnpm install && pnpm build
   npx paperclipai run          # or pnpm dev
   
   # If the worktree needs a fresh database:
   npx paperclipai worktree reseed --seed-mode full
   
   # If the worktree is broken beyond repair:
   npx paperclipai worktree:cleanup <name>
   npx paperclipai worktree:make <name> --seed-mode full
   

   如果任何步骤失败，请遵循规则 2——停止并报告。

5. 播种数据必须通过 CLI 操作。 如果需要从主实例为工作树数据库播种，请使用 worktree reseed，或通过 worktree:make --seed-mode full 重新创建。完整的选项表请参阅 doc/DEVELOPING.md。绝不要尝试手动复制数据库。

持久运行的开发服务器（用于手动测试）

如果 Agent 需要启动一个在当前心跳结束后仍继续运行的开发服务器——例如，供人工或 QA Agent 手动测试——则必须在分离会话中启动服务器进程。直接从心跳 Shell 启动的进程会在心跳结束时被终止。

使用 tmux 持久运行服务器

# 1. cd into the worktree (or main repo) and source the environment
cd <worktree-path>
eval "$(npx paperclipai worktree env)"   # skip if using the primary instance

# 2. Start the dev server in a named, detached tmux session
tmux new-session -d -s <session-name> 'pnpm dev'

# Example with a descriptive name:
tmux new-session -d -s auth-fix-3102 'pnpm dev'

管理会话

任务	命令
检查会话是否仍在运行	tmux has-session -t <session-name> 2>/dev/null && echo running
查看服务器输出	tmux capture-pane -t <session-name> -p
终止会话	tmux kill-session -t <session-name>
列出所有 tmux 会话	tmux list-sessions

验证服务器是否可访问

启动后，在报告成功之前，请确认端口正在监听：

# Wait briefly for startup, then verify
sleep 3
curl -sf http://127.0.0.1:<port>/api/health && echo "Server is up"
lsof -nP -iTCP:<port> -sTCP:LISTEN

关键规则

1. 如果开发服务器需要在心跳结束后继续运行，务必使用 tmux（或等效工具）。 直接从 Agent Shell 启动的服务器会在心跳结束时终止，即使它刚才看起来运行正常。
2. 使用描述性名称命名会话——包含工作树名称和端口（例如 auth-fix-3102）。
3. 报告 URL 前，先确认服务器正在监听。
4. 不要单独使用 nohup 或 &——对于可能会终止整个进程组的 Agent Shell，这些方式并不可靠。
5. 完成后清理——测试结束时终止 tmux 会话。

常见错误

错误	修复方法
服务无法启动	运行 npx paperclipai doctor --repair 进行诊断并自动修复
忘记加载工作树环境	进入工作树目录后运行 eval "$(npx paperclipai worktree env)"
拉取后依赖项过期	拉取后运行 pnpm install && pnpm build
拉取后架构过期	运行 pnpm db:generate && pnpm db:migrate
目标数据库运行时重新填充数据	先停止目标服务，或使用 --allow-live-target
清理时存在未合并的提交	先合并或推送；如果确定要丢弃，则使用 --force
Agent 针对错误的实例运行	确认 PAPERCLIP_API_URL 指向正确的端口
CLI 命令失败	不要尝试绕过问题——报告错误并阻止操作（参见上文“硬性规则”）
Agent 尝试手动执行 postgres 操作	绝对不要这样做——所有数据库操作都必须通过 CLI 执行（参见上文“硬性规则”）
开发服务器在心跳间隔期间退出	在分离的 tmux 会话中启动——参见上文“持久运行的开发服务器”
存在 fork 时，仍将功能分支推送到 paperclipai/paperclip	改为推送到用户的 fork 远程仓库——参见上文“Fork”