paperclip-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paperclip Dev

Paperclip 开发与运维

This skill covers the day-to-day workflows for developing and operating a local Paperclip instance. It assumes you are working inside the Paperclip repo checkout with

origin

pointing to

git@github.com:paperclipai/paperclip.git

OPEN SOURCE HYGIENE: This repository is public-facing. Treat anything you push to
origin
as publishable. Never commit or push secrets, API keys, tokens, private logs, PII, customer data, or machine-local configuration that should stay private. Keep git history tidy as well: avoid pushing throwaway branches, noisy checkpoint commits, or speculative work that does not need to be shared upstream.

MANDATORY: Before running any CLI command, building, testing, or managing worktrees, you MUST read
doc/DEVELOPING.md
in the Paperclip repo. It is the canonical reference for all
paperclipai
CLI commands, their options, build/test workflows, database operations, worktree management, and diagnostics. Do NOT guess at flags or options — read the doc first.

本技能涵盖开发和运维本地Paperclip实例的日常工作流程。假设你已在Paperclip代码仓库的检出目录中工作，且

origin

指向

git@github.com:paperclipai/paperclip.git

。

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

强制要求： 在运行任何CLI命令、构建、测试或管理工作树之前，你必须阅读Paperclip仓库中的
doc/DEVELOPING.md
文件。它是所有
paperclipai
CLI命令、选项、构建/测试流程、数据库操作、工作树管理及诊断的权威参考文档。请勿猜测参数或选项——先阅读文档。

Quick Command Reference

快速命令参考

These are the most common commands. For full option tables and details, see

doc/DEVELOPING.md

Task	Command
Start server (first time or normal)	`npx paperclipai run`
Dev mode with hot reload	`pnpm dev`
Stop dev server	`pnpm dev:stop`
Build	`pnpm build`
Type-check	`pnpm typecheck`
Run tests	`pnpm test`
Run migrations	`pnpm db:migrate`
Regenerate Drizzle client	`pnpm db:generate`
Back up database	`npx paperclipai db:backup`
Health check	`npx paperclipai doctor --repair`
Print env vars	`npx paperclipai env`
Trigger agent heartbeat	`npx paperclipai heartbeat run --agent-id <id>`
Install agent skills locally	`npx paperclipai agent local-cli <agent> --company-id <id>`

以下是最常用的命令。完整的参数表和详细信息请查阅

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>`

Pulling from Master

从Master分支拉取更新

bash

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

If schema changes landed, also run

pnpm db:generate && pnpm db:migrate

bash

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

如果有 schema 变更，还需运行

pnpm db:generate && pnpm db:migrate

。

Worktrees

工作树（Worktrees）

Paperclip worktrees combine git worktrees with isolated Paperclip instances — each gets its own database, server port, and environment seeded from the primary instance.

MANDATORY: Before creating or managing worktrees, you MUST read the "Worktree-local Instances" and "Worktree CLI Reference" sections in
doc/DEVELOPING.md
. That is the canonical reference for all worktree commands, their options, seed modes, and environment variables.

Paperclip工作树将git工作树与独立的Paperclip实例结合——每个工作树拥有自己的数据库、服务器端口，并从主实例继承环境配置。

强制要求： 在创建或管理工作树之前，你必须阅读
doc/DEVELOPING.md
中的“Worktree-local Instances”和“Worktree CLI Reference”章节。这是所有工作树命令、选项、种子模式及环境变量的权威参考。

When to Use Worktrees

何时使用工作树

Starting a feature branch that needs its own Paperclip environment
Running parallel agent work without cross-contaminating the primary instance
Testing Paperclip changes in isolation before merging

启动需要独立Paperclip环境的功能分支
在不干扰主实例的情况下并行运行Agent工作
在合并前隔离测试Paperclip的变更

Command Overview

命令概述

The CLI has two tiers (see

doc/DEVELOPING.md

for full option tables):

Command	Purpose
`worktree:make <name>`	Create worktree + isolated instance in one step
`worktree:list`	List worktrees and their Paperclip status
`worktree:merge-history`	Preview/import issue history between worktrees
`worktree:cleanup <name>`	Remove worktree, branch, and instance data
`worktree init`	Bootstrap instance inside existing worktree
`worktree env`	Print shell exports for worktree instance
`worktree reseed`	Refresh worktree DB from another instance
`worktree repair`	Fix broken/missing worktree instance metadata

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`	修复损坏/缺失的工作树实例元数据

Typical Workflow

典型工作流程

bash

undefined

bash

undefined

1. Create a worktree for a feature

1. 为功能创建工作树

npx paperclipai worktree:make my-feature --start-point origin/main

2. Move into the worktree (path printed by worktree:make) and source the environment

2. 进入工作树（路径由worktree:make输出）并加载环境配置

cd <worktree-path> eval "$(npx paperclipai worktree env)"

3. Start the isolated Paperclip server

3. 启动独立的Paperclip服务器

npx paperclipai run

4. Do your work

4. 开展工作

5. When done, merge history back if needed

5. 完成后，如有需要合并历史记录

npx paperclipai worktree:merge-history --from paperclip-my-feature --to current --apply

6. Clean up

6. 清理工作树

npx paperclipai worktree:cleanup my-feature

undefined

npx paperclipai worktree:cleanup my-feature

undefined

Forks — Prefer Pushing to a User Fork

分支仓库——优先推送到用户分支仓库

If the user has a personal fork of

paperclipai/paperclip

configured as a git remote, push your feature branches to that fork instead of creating branches on the main repo. This keeps the upstream branch list clean and matches the standard open-source contribution flow.

如果用户已将

paperclipai/paperclip

的个人分支仓库配置为git远程仓库，请将功能分支推送到该分支仓库，而非主仓库创建分支。这能保持上游分支列表整洁，符合标准的开源贡献流程。

Detect a fork remote

检测分支仓库远程

Before pushing or creating a PR, list remotes and check for one that points at a non-

paperclipai

GitHub fork:

bash

git remote -v

Treat any remote whose URL points to

github.com:<user>/paperclip

(or

github.com/<user>/paperclip.git

) as the user's fork. Common names are

fork

<username>

, or

myfork

. The remote named

origin

upstream

that points at

paperclipai/paperclip

is the canonical upstream — do not push feature branches there if a fork exists.

在推送或创建PR之前，列出远程仓库并检查是否存在指向非

paperclipai

的GitHub分支仓库：

bash

git remote -v

将任何URL指向

github.com:<user>/paperclip

（或

github.com:<user>/paperclip.git

）的远程仓库视为用户的分支仓库。常见名称为

fork

、

<username>

或

myfork

。指向

paperclipai/paperclip

的

origin

或

upstream

远程仓库是官方上游仓库——如果存在分支仓库，请勿将功能分支推送到此处。

Pushing to the fork

推送到分支仓库

bash

undefined

bash

undefined

Push the current branch to the user's fork and set upstream

将当前分支推送到用户的分支仓库并设置上游

git push -u <fork-remote> HEAD


Then create the PR from the fork branch:

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

gh pr create

usually figures out the head ref automatically when run from a branch tracking the fork; the explicit

--head <owner>:<branch>

form is the reliable fallback when it does not.

git push -u <fork-remote> HEAD


然后从分支仓库分支创建PR：

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

当从跟踪分支仓库的分支运行时，

gh pr create

通常会自动识别头引用；如果无法识别，显式的

--head <owner>:<branch>

格式是可靠的备选方案。

When no fork exists

无分支仓库的情况

git remote -v

shows only

paperclipai/paperclip

remotes (no user fork), fall back to pushing branches to

origin

as before. Do NOT create a fork on the user's behalf — ask first.

如果

git remote -v

仅显示

paperclipai/paperclip

远程仓库（无用户分支仓库），则退回到之前的方式，将分支推送到

origin

。请勿代表用户创建分支仓库——先询问用户。

Keeping the fork up to date

保持分支仓库同步

The canonical remote that points at

paperclipai/paperclip

may be named

origin

upstream

depending on how the user set up the repo. Detect it the same way as in the "Detect a fork remote" step, then fetch and push from/with that remote so the sync works under either convention:

bash

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

指向

paperclipai/paperclip

的官方远程仓库可能被命名为

origin

或

upstream

，具体取决于用户的仓库设置方式。按照“检测分支仓库远程”步骤的方式识别它，然后从该远程仓库拉取并推送到分支仓库，以便在两种命名约定下都能正常同步：

bash

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

拉取请求（PR）

MANDATORY PRE-FLIGHT: Before creating ANY pull request, you MUST read the canonical source files listed below. Do NOT run
gh pr create
until you have read these files and verified your PR body matches every required section.

强制预检： 在创建任何拉取请求之前，你必须阅读以下列出的权威源文件。在阅读这些文件并确认你的PR正文符合所有必填部分之前，请勿运行
gh pr create
。

Step 1 — Read the canonical files

步骤1 — 阅读权威文件

You MUST read all three of these files before creating a PR:

.github/PULL_REQUEST_TEMPLATE.md
— the required PR body structure
CONTRIBUTING.md
— contribution conventions, PR requirements, and thinking-path examples
.github/workflows/pr.yml
— CI checks that gate merge

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

.github/PULL_REQUEST_TEMPLATE.md
— 必填的PR正文结构
CONTRIBUTING.md
— 贡献规范、PR要求及思考路径示例
.github/workflows/pr.yml
— 控制合并的CI检查

Step 2 — Validate your PR body against this checklist

步骤2 — 验证PR正文是否符合检查清单

After reading the template, verify your

--body

includes every one of these sections (names must match exactly):

```
## Thinking Path
```
— blockquote style, 5-8 reasoning steps
```
## What Changed
```
— bullet list of concrete changes
```
## Verification
```
— how a reviewer confirms this works
```
## Risks
```
— what could go wrong
```
## Model Used
```
— provider, model ID, version, capabilities
```
## Checklist
```
— copied from the template, items checked off

If any section is missing or empty, do NOT submit the PR. Go back and fill it in.

阅读模板后，确认你的

--body

包含以下所有部分（名称必须完全匹配）：

```
## Thinking Path
```
— 引用块格式，5-8条推理步骤
```
## What Changed
```
— 具体变更的项目符号列表
```
## Verification
```
— 评审者确认功能正常的方式
```
## Risks
```
— 可能出现的问题
```
## Model Used
```
— 提供商、模型ID、版本、功能
```
## Checklist
```
— 从模板复制的检查清单，并勾选相应项目

如果任何部分缺失或为空，请勿提交PR。返回并补充完整。

Step 3 — Create the PR

步骤3 — 创建PR

Only after completing Steps 1 and 2, run

gh pr create

. Use the template contents as the structure for

--body

— do not write a freeform summary.

仅在完成步骤1和步骤2后，运行

gh pr create

。使用模板内容作为

--body

的结构——请勿撰写自由格式的摘要。

Hard Rules — Do NOT Bypass

严格规则——请勿违反

These rules exist because agents have caused real damage by improvising around CLI failures. Follow them exactly.

CLI is the only interface to worktrees and databases. All worktree and database operations MUST go through
```
npx paperclipai
```
/
```
pnpm paperclipai
```
commands. You MUST NOT:
- Run
```
pg_dump
```
  ,
```
pg_restore
```
  ,
```
psql
```
  ,
```
createdb
```
  ,
```
dropdb
```
  , or any raw postgres commands
- Manually set
```
DATABASE_URL
```
  to point a worktree server at another instance's database
- Run
```
rm -rf
```
  on any
```
.paperclip/
```
  ,
```
.paperclip-worktrees/
```
  , or
```
db/
```
  directory
- Directly manipulate embedded postgres data directories
- Kill postgres processes by PID
If a CLI command fails, stop and report. Do NOT attempt workarounds. If
```
worktree:make
```
,
```
worktree reseed
```
,
```
worktree init
```
,
```
worktree:cleanup
```
, or any other
```
paperclipai
```
command fails:
- Report the exact error message in your task comment
- Set the task to
```
blocked
```
- Suggest running
```
npx paperclipai doctor --repair
```
  or recreating the worktree from scratch
- Do NOT try to manually replicate what the CLI does
Never share databases between instances. Each worktree instance gets its own isolated database. Never override
```
DATABASE_URL
```
to point one instance at another's database. This destroys isolation and can corrupt production data.

Starting a dev server in a worktree requires setup first. The correct sequence is:

bash

# 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

If any step fails, follow rule 2 — stop and report.

Seeding is a CLI operation. When asked to seed a worktree database from the main instance, use
```
worktree reseed
```
or recreate with
```
worktree:make --seed-mode full
```
. Read
```
doc/DEVELOPING.md
```
for the full option tables. Never attempt manual database copying.

这些规则的存在是因为Agent曾因随意绕过CLI故障造成实际损害。请严格遵守。

CLI是操作工作树和数据库的唯一接口。 所有工作树和数据库操作必须通过
```
npx paperclipai
```
/
```
pnpm paperclipai
```
命令执行。你不得：
- 运行
```
pg_dump
```
  、
```
pg_restore
```
  、
```
psql
```
  、
```
createdb
```
  、
```
dropdb
```
  或任何原始postgres命令
- 手动设置
```
DATABASE_URL
```
  ，使工作树服务器指向其他实例的数据库
- 对任何
```
.paperclip/
```
  、
```
.paperclip-worktrees/
```
  或
```
db/
```
  目录运行
```
rm -rf
```
- 直接操作嵌入式postgres数据目录
- 通过PID终止postgres进程
如果CLI命令失败，请停止并报告。 请勿尝试变通方法。如果
```
worktree:make
```
、
```
worktree reseed
```
、
```
worktree init
```
、
```
worktree:cleanup
```
或任何其他
```
paperclipai
```
命令失败：
- 在任务评论中报告确切的错误消息
- 将任务设置为
```
blocked
```
  状态
- 建议运行
```
npx paperclipai doctor --repair
```
  或从头重新创建工作树
- 请勿尝试手动复制CLI的操作
切勿在实例之间共享数据库。 每个工作树实例都有自己的独立数据库。切勿覆盖
```
DATABASE_URL
```
，使一个实例指向另一个实例的数据库。这会破坏隔离性，并可能损坏生产数据。

在工作树中启动开发服务器需要先完成设置。 正确的步骤顺序是：

bash

# 如果工作树已存在但无运行中的实例：
cd <worktree-path>
eval "$(npx paperclipai worktree env)"   # 使用主实例时可跳过
pnpm install && pnpm build
npx paperclipai run          # 或 pnpm dev

# 如果工作树需要全新数据库：
npx paperclipai worktree reseed --seed-mode full

# 如果工作树损坏无法修复：
npx paperclipai worktree:cleanup <name>
npx paperclipai worktree:make <name> --seed-mode full

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

数据种子是CLI操作。 当需要从主实例为工作树数据库播种时，请使用
```
worktree reseed
```
或通过
```
worktree:make --seed-mode full
```
重新创建。查阅
```
doc/DEVELOPING.md
```
获取完整参数表。切勿尝试手动复制数据库。

Persistent Dev Servers (for Manual Testing)

持久化开发服务器（用于手动测试）

When an agent needs to start a dev server that outlives the current heartbeat — for example, so a human or QA agent can manually test against it — the server process must be launched in a detached session. A process started directly from a heartbeat shell is killed when the heartbeat exits.

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

Use

tmux

for persistent servers

使用

tmux

运行持久化服务器

bash

undefined

bash

undefined

1. cd into the worktree (or main repo) and source the environment

1. 进入工作树（或主仓库）并加载环境配置

cd <worktree-path> eval "$(npx paperclipai worktree env)" # skip if using the primary instance

cd <worktree-path> eval "$(npx paperclipai worktree env)" # 使用主实例时可跳过

2. Start the dev server in a named, detached tmux session

2. 在命名的分离tmux会话中启动开发服务器

tmux new-session -d -s <session-name> 'pnpm dev'

Example with a descriptive name:

示例：使用描述性名称

tmux new-session -d -s auth-fix-3102 'pnpm dev'

undefined

tmux new-session -d -s auth-fix-3102 'pnpm dev'

undefined

Managing the session

管理会话

Task	Command
Check if the session is alive	`tmux has-session -t <session-name> 2>/dev/null && echo running`
View server output	`tmux capture-pane -t <session-name> -p`
Kill the session	`tmux kill-session -t <session-name>`
List all tmux sessions	`tmux list-sessions`

任务	命令
检查会话是否运行	`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`

Verifying the server is reachable

验证服务器是否可访问

After launching, confirm the port is listening before reporting success:

bash

undefined

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

bash

undefined

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

undefined

sleep 3 curl -sf http://127.0.0.1:<port>/api/health && echo "Server is up" lsof -nP -iTCP:<port> -sTCP:LISTEN

undefined

Key rules

关键规则

Always use
tmux
(or equivalent) when a dev server needs to stay running after the heartbeat ends. A server started directly from the agent shell will die when the heartbeat exits, even if it appeared healthy moments before.
Name the session descriptively — include the worktree name and port (e.g.,
```
auth-fix-3102
```
).
Verify the server is listening before reporting the URL to anyone.
Do not use
nohup
or
&
alone — these are unreliable for agent shells that may have their entire process group killed.
Clean up when done — kill the tmux session when the testing is complete.

始终使用
tmux
（或类似工具）当开发服务器需要在心跳结束后继续运行时。直接从Agent Shell启动的服务器会在心跳结束时终止，即使片刻前看起来运行正常。
为会话命名时要有描述性 ——包含工作树名称和端口（例如
```
auth-fix-3102
```
）。
在向他人报告URL前验证服务器正在监听。
请勿单独使用
nohup
或
&
——这些方法在Agent Shell可能被终止整个进程组的情况下不可靠。
使用完成后清理 ——测试完成后终止tmux会话。

Common Mistakes

常见错误

Mistake	Fix
Server won't start	Run `npx paperclipai doctor --repair` to diagnose and auto-fix
Forgetting to source worktree env	Run `eval "$(npx paperclipai worktree env)"` after cd-ing into the worktree
Stale dependencies after pull	Run `pnpm install && pnpm build` after pulling
Schema out of date after pull	Run `pnpm db:generate && pnpm db:migrate`
Reseeding while target DB is running	Stop the target server first, or use `--allow-live-target`
Cleaning up with unmerged commits	Merge or push first, or use `--force` if intentionally discarding
Running agents against wrong instance	Verify `PAPERCLIP_API_URL` points to the correct port
CLI command fails	Do NOT work around it — report the error and block (see Hard Rules above)
Agent tries manual postgres operations	NEVER do this — all DB ops go through the CLI (see Hard Rules above)
Dev server dies between heartbeats	Launch in a detached `tmux` session — see "Persistent Dev Servers" above
Pushed feature branch to `paperclipai/paperclip` when a fork exists	Push to the user's fork remote instead — see "Forks" above

错误	修复方法
服务器无法启动	运行 `npx paperclipai doctor --repair` 进行诊断并自动修复
忘记加载工作树环境配置	进入工作树后运行 `eval "$(npx paperclipai worktree env)"`
拉取更新后依赖过期	拉取后运行 `pnpm install && pnpm build`
拉取更新后Schema过时	运行 `pnpm db:generate && pnpm db:migrate`
目标数据库运行时进行播种	先停止目标服务器，或使用 `--allow-live-target` 参数
清理时存在未合并的提交	先合并或推送，或如果有意丢弃则使用 `--force` 参数
Agent针对错误实例运行	验证 `PAPERCLIP_API_URL` 指向正确的端口
CLI命令失败	请勿尝试变通——报告错误并设置任务为阻塞状态（见上文严格规则）
Agent尝试手动postgres操作	绝对禁止——所有数据库操作必须通过CLI执行（见上文严格规则）
开发服务器在心跳间隔期间终止	在分离的 `tmux` 会话中启动——见上文“持久化开发服务器”部分
存在分支仓库时仍将功能分支推送到 `paperclipai/paperclip`	改为推送到用户的分支仓库远程——见上文“分支仓库”部分

paperclip-dev

Original

Translation

Paperclip Dev

Paperclip 开发与运维

Quick Command Reference

快速命令参考

Pulling from Master

从Master分支拉取更新

Worktrees

工作树（Worktrees）

When to Use Worktrees

何时使用工作树

Command Overview

命令概述

Typical Workflow

典型工作流程

1. Create a worktree for a feature

1. 为功能创建工作树

2. Move into the worktree (path printed by worktree:make) and source the environment

2. 进入工作树（路径由worktree:make输出）并加载环境配置

3. Start the isolated Paperclip server

3. 启动独立的Paperclip服务器

4. Do your work

4. 开展工作

5. When done, merge history back if needed

5. 完成后，如有需要合并历史记录

6. Clean up

6. 清理工作树

Forks — Prefer Pushing to a User Fork

分支仓库——优先推送到用户分支仓库

Detect a fork remote

检测分支仓库远程

Pushing to the fork

推送到分支仓库

Push the current branch to the user's fork and set upstream

将当前分支推送到用户的分支仓库并设置上游

When no fork exists

无分支仓库的情况

Keeping the fork up to date

保持分支仓库同步

Pull Requests

拉取请求（PR）

Step 1 — Read the canonical files

步骤1 — 阅读权威文件

Step 2 — Validate your PR body against this checklist

步骤2 — 验证PR正文是否符合检查清单

Step 3 — Create the PR

步骤3 — 创建PR

Hard Rules — Do NOT Bypass

严格规则——请勿违反

Persistent Dev Servers (for Manual Testing)

持久化开发服务器（用于手动测试）

Use tmux for persistent servers

使用tmux运行持久化服务器

1. cd into the worktree (or main repo) and source the environment

1. 进入工作树（或主仓库）并加载环境配置

2. Start the dev server in a named, detached tmux session

2. 在命名的分离tmux会话中启动开发服务器

Example with a descriptive name:

示例：使用描述性名称

Managing the session

管理会话

Verifying the server is reachable

验证服务器是否可访问

Wait briefly for startup, then verify

等待启动完成，然后验证

Key rules

关键规则

Common Mistakes

常见错误

Use
`tmux`
for persistent servers

使用
`tmux`
运行持久化服务器