port-daddy

Port Daddy v3.8.2 — 真正好用的 Agent 协调

不适用于

• 生产部署编排、发布策略或 CI 发布门禁。
• Docker、Kubernetes、服务网格或云网络发现问题。
• 不涉及端口协调、工作抢救或共享状态工作流的单 Agent 本地工作。

你现在遇到的问题

你是一个 AI Agent。你正准备启动开发服务器。用哪个端口？3000？被占用了。3001？被另一个 Agent 抢先用了。你随便选了一个端口。现在没人能找到你的服务器。

与此同时，另一个 Agent 正在编辑和你相同的文件。你们都不知道这件事。你们都会提交，其中一个人会丢失工作成果。

还有第三个 Agent 在 20 分钟前崩溃了——当时它的迁移工作只完成了一半。它的工作成了孤儿，没人知道。

Port Daddy 在一个守护进程中解决所有这些问题。

决策树 — 选择合适的原语

从上到下阅读。第一个匹配的叶节点就是你的答案。如果跳过守护进程运行状态检查，后续每个判断都毫无意义。

flowchart TD
  A[I want to do something coordination-shaped] --> Up{pd status<br/>== running?}
  Up -- no --> Down[examples/06-debug-daemon-down.md]
  Up -- yes --> Scope{Scope?}

  Scope -- single agent, no shared state --> Out[Out of scope: just code.<br/>NOT for this skill.]
  Scope -- this agent, this session --> Life[Lifecycle path]
  Scope -- two+ agents, same repo --> Coord[Coordination path]
  Scope -- background cadence / fleet --> Fleet[Fleet path]
  Scope -- many agents, same harbor --> Swarm[Swarm path]

  Life --> L1{What do I need?}
  L1 -- "session boundary" --> L1a[pd begin / pd done<br/>schemas/note-shape.md]
  L1 -- "deterministic port" --> L1b[pd claim {project}:{stack}:{ctx}<br/>schemas/semantic-identity.md<br/>examples/07-port-collision.md]
  L1 -- "audit trail" --> L1c[pd note --type ...<br/>assets/session-note.template.md]
  L1 -- "what happened?" --> L1d[pd sitrep / catch_me_up MCP]

  Coord --> C1{Failure mode I'm preventing?}
  C1 -- "two agents edit same file" --> C1a[pd session files claim<br/>examples/02-two-agents-same-file.md]
  C1 -- "must be exclusive" --> C1b[pd with-lock<br/>or pd lock + pd unlock]
  C1 -- "agent-to-agent signal" --> C1c[pd pub + pd watch]
  C1 -- "DM a specific agent" --> C1d[pd inbox send<br/>or talk_to_agent MCP]
  C1 -- "agent died, finish their work" --> C1e[pd salvage claim<br/>schemas/salvage-entry.md<br/>examples/03-salvage]

  Fleet --> F1{Fleet exists?}
  F1 -- "no" --> F1a[pd fleet init + edit pd-fleet.yml<br/>assets/pd-fleet.starter.yml<br/>examples/04-fleet-from-zero.md]
  F1 -- "yes, broken" --> F1b[scripts/fleet-validate.sh<br/>schemas/pd-fleet.schema.md]
  F1 -- "yes, want it daemon-managed" --> F1c[POST /fleet/register<br/>survives terminal close]
  F1 -- "yes, want to chain agents" --> F1d[on_success: publish channel<br/>+ declare in channels:]

  Swarm --> S1{Shape of the data?}
  S1 -- "typed records, multi-reader" --> S1a[pd tuple out + pd tuple rd<br/>schemas/tuple-shape.md]
  S1 -- "exactly-once work" --> S1b[pd tuple in<br/>work-stealing<br/>examples/05-tuple-swarm-handoff.md]
  S1 -- "ambient gradient / heat" --> S1c[pd pheromone spray<br/>schemas/pheromone-signal.md]
  S1 -- "broadcast, ephemeral" --> S1d[pd pub on a harbor channel]

按顺序回答以下五个问题：

1. 守护进程在运行吗？ — pd status。如果没有运行，你就完全没有协调能力。先解决这个问题。
2. 范围是什么？ — 单会话、双 Agent、舰队（cadence），还是蜂群（many-in-harbor）？它们使用不同的原语；混用只是做做样子。
3. 我要防止哪种故障？ — 无声覆盖、端口冲突、Agent 死亡后工作丢失、信号遗漏？故障类型决定使用哪种原语。
4. 需要持久还是临时？ — 备注（永久）和无 TTL 的元组（直到被移除）是持久的。信息素和发布/订阅是临时的。选错会污染审计记录，或导致信号丢失。
5. 多方读取还是一次性领取？ — tuple rd 和 pub 会向多个接收方分发；tuple in 和 lock 则确保只有一个胜出者。弄错的话，要么丢失工作，要么重复工作。

故障模式分诊

问题已经发生时，直接看这里。

症状	可能原因	首要诊断	修复 / 操作手册
pd <anything> → Connection refused	守护进程未运行	pd status	examples/06-debug-daemon-down.md
pd status 永远挂起	守护进程卡在事件循环中	lsof ~/.port-daddy/daemon.sock；检查 daemon.log	执行 kill -9 $(cat ~/.port-daddy/daemon.pid)，然后运行 pd start
pd claim 返回了“错误的”端口	按设计由身份决定——它是正确的	运行 pd find <identity> 进行确认	使用不同的身份上下文，而不是不同的端口
pd begin 提示会话已处于活动状态	此 PID 有过期会话	pd whoami	运行 pd done 后重新运行 begin，或继续使用现有会话
pd session files claim 提示冲突	另一个 Agent 已经认领该文件	运行 pd swarm_awareness 或查看警告	examples/02-two-agents-same-file.md
提交时舰队 Agent 从未触发	fleet.name != basename(projectDir)（最常见）	scripts/fleet-validate.sh	修正 fleet.name；重新运行 pd fleet up
舰队 Agent 触发了但什么也没做	prompt 太模糊，或 allowedTools 阻止了所需操作	pd spawned 显示它运行了很短时间；检查其日志	明确提示词；扩大允许列表
pd salvage 显示大量积压	早已崩溃的 Agent 留下了过期条目	pd salvage --project <p>	使用 scripts/salvage-triage.sh 进行分诊；忽略明显已经失效的条目
pd tuple rd 没有返回任何内容	harbor 或模式结构错误	pd tuple scan --harbor <h>	语法请参见 schemas/tuple-shape.md
pd note 写入成功，但 pd notes 返回空结果	备注已加密，但密钥已更改	ls -la ~/.port-daddy/master.key，权限必须为 0600	从备份恢复密钥；否则备注将无法读取
信息素读数总是接近零	衰减速度超过喷洒频率	pd pheromone show --table <t> --id <i>	提高喷洒频率或增加 --strength；信息素不是数据库
两个 Agent 在同一个元组上执行 tuple in 都成功	Bug — 提交反馈	.spark/feedback/$(date +%F)-tuple-double-take.md	守护进程应该以原子方式领取；这是回归问题

L3 索引 — 深层知识所在之处

此文件是 L1/L2 入口。不要将深层参考资料直接粘贴到此处——按需加载：

需要	阅读
端到端实操场景	examples/INDEX.md（8 个场景：bootstrap、conflict、salvage、fleet、swarm、daemon-down、port-collision）
权威契约 / 数据结构	schemas/INDEX.md（semantic-identity、pd-fleet schema、tuple、note、pheromone、salvage、MCP 工具）
可直接运行的一次性辅助脚本	scripts/（preflight、session-resume、salvage-triage、fleet-validate、agent-handshake）
可复制并编辑的模板	assets/（pd-fleet.starter.yml、.portdaddyrc.starter、session-note.template.md）
完整 HTTP API（93 个以上端点）	references/api-reference.md
JavaScript SDK	references/sdk-reference.md
高级多 Agent 模式	references/multi-agent-patterns.md
.portdaddyrc 项目级配置	references/portdaddyrc-spec.md

快速开始（首先执行）

# 1. Start your session — ALWAYS do this first
pd begin "Building auth module"

# 2. Claim a port — deterministic, never conflicts
PORT=$(pd claim myapp:api:main -q)

# 3. Leave breadcrumbs for other agents
pd note "JWT validation working, moving to refresh tokens"

# 4. Check who else is working here
pd salvage --project myapp    # Any dead agents to rescue?

# 5. End cleanly
pd done

为什么这很重要

没有 Port Daddy：

• 每当两个 Agent 运行开发服务器时，都会发生端口冲突
• 没有记录 Agent 做过什么或作出了什么决定
• 崩溃的 Agent 会留下无人发现的孤立工作
• Agent 无法彼此发送信号
• 文件编辑冲突会悄无声息地毁掉工作

有了 Port Daddy：

• 确定性端口——相同身份始终获得相同端口
• 不可变备注——每项决定都有完整的审计跟踪
• 挽救队列——已停止运行的 Agent 的工作会被保留，并可供认领
• 发布/订阅 + 文件认领——Agent 协调工作时不会互相干扰
• 后台集群——QA、文档和测试会在每次提交时自动运行
• 二进制 IPC——通过 Unix 套接字实现亚微秒级心跳和信息素喷洒
• 信息素轨迹——随时间衰减的环境数值信号，用于检测争用
• 元组空间——供集群协调使用的共享类型化内存
• 语义字典树——以 O(k) 身份查找取代 SQL LIKE 扫描

行话辨别

• 如果任务只需要一个临时端口，且不需要共享会话状态，那么启动集群和信息素轨迹只是作秀，并非协调。
• 如果关键区需要强制互斥，请使用锁；建议式文件认领用于协商，而非保障安全。
• 如果故障出在容器入口、DNS 或生产服务发现上，Port Daddy 就不适合处理这一层问题。

可用的 MCP 工具

从这里开始（高层级，一个调用即可完成多项操作）：

工具	功能
begin_session	注册为 Agent 并以原子方式启动会话
end_session_full	结束会话并以原子方式注销
whoami	我是什么 Agent？当前会话是什么？我拥有哪些文件？
catch_me_up	我离开期间发生了什么？查看近期活动、备注和失效的 Agent
swarm_awareness	还有谁在这里工作？查看所有 Agent、会话和文件认领
file_heat	哪些文件正被 Agent 争抢？查看基于信息素的竞争情况图
talk_to_agent	按名称向特定的舰队 Agent 发送直接消息
claim_port	根据服务标识获取一个确定性端口
add_note	留下不可变的记录（备注永远不能删除）
acquire_lock	为临界区获取分布式锁
spawn_agent	启动一个在后台执行任务的 AI Agent
fleet_init	使用 git hooks 和 pd-fleet.yml 设置后台 Agent 舰队
pd_discover	按类别查找更多工具

Tuple 空间工具（共享的群体记忆）：

工具	功能
tuple_out	向共享空间写入带类型的 tuple（限定于 harbor）
tuple_read	读取与模式匹配的 tuple（非破坏性）
tuple_take	以原子方式读取并移除与模式匹配的 tuple
tuple_scan	列出 harbor 或全局空间中的所有 tuple
tuple_count	统计与模式匹配的 tuple 数量

按类别发现更多工具： 使用类别名称调用 pd_discover：magic、session-lifecycle、ports、sessions、notes、locks、messaging、agents、inbox、webhooks、integration、dns、briefing、tunnels、projects、changelog、activity、system、tuples、pheromone

集成信号： 使用 integration ready 和 integration needs 协调服务依赖关系。服务就绪后，请发出信号，以便其他 Agent 继续工作。

核心概念

语义标识：project:stack:context

每个服务都有一个语义名称。名称就是端口——确定性哈希意味着相同的标识始终映射到相同的端口。标识会编入内存中的 Adaptive Radix Tree，以实现 O(k) 查找（其中 k 是键的长度），取代 SQL LIKE 扫描。

pd claim myapp:api:main           # Always gets port 3142 (or whatever hash gives)
pd claim myapp:api:feature-auth   # Different port, same project
pd find 'myapp:*'                 # Prefix search — resolves through the trie, not SQL
pd find 'myapp:*:main'            # Wildcard — all stacks with context "main"

会话与备注

会话会跟踪每个 Agent 正在做什么。备注是不可变的——写入后，永远无法编辑或删除。这会形成一条 Agent 和人类都可以信赖的审计记录。备注在静态存储时会使用 AES-256-GCM 加密（主密钥位于 ~/.port-daddy/master.key，首次启动时自动生成）。

pd begin --identity myapp:api --purpose "Building auth"
pd note "Found SQL injection in token validation"
pd note "Patched. Tests green."
pd done

工作接管（失效 Agent 恢复）

Agent 崩溃后，其会话会进入待接管队列。其他 Agent 可以认领并继续这项工作：

pd salvage --project myapp        # See dead agents' context
pd salvage claim dead-agent-42    # Pick up their work

重要提示： 每次会话开始时都要检查 pd salvage。你或许可以接着崩溃的 Agent 未完成的工作继续，而不必从头开始。

文件认领（建议性）

pd session files claim src/auth/*.ts
# Another agent tries the same file:
pd session files claim src/auth/login.ts
# → CONFLICT: claimed by agent 'myapp:api'

认领仅提供建议——会发出警告，但不会锁定。硬锁会导致死锁；建议性认领则能促成沟通。

发布/订阅消息

Agent 通过频道互相发送信号：

# Agent A finishes database setup
pd pub myapp:events "database-ready"

# Agent B was watching
pd watch myapp:events --exec "npm run migrate"

分布式锁

用于确实必须互斥的操作：

pd with-lock deployment -- npm run deploy
# Or manually:
pd lock db-migration --ttl 300
pd unlock db-migration

二进制 IPC 协议（v3.8.2）

通过 Unix 域套接字和 MessagePack 编码进行高频 Agent 通信。IPC 通道与 HTTP API 并行运行——需要低延迟通信的 Agent（心跳、信息素喷洒、发布/订阅发布）会在守护进程运行时自动使用 IPC。

主要特性：

• 7 字节标头：[type:1][conv_id:4][payload_len:2] + MessagePack 负载
• 与 HTTP JSON 相比，带宽减少 70-80%
• 即发即弃操作的延迟约为 3us（HTTP 约为 200us）
• 13 种 FIPA 执行语：INFORM、REQUEST、QUERY_REF、REFUSE、FAILURE、NOT_UNDERSTOOD、SUBSCRIBE、UNSUBSCRIBE 等
• 即发即弃：心跳、信息素喷洒、发布/订阅发布（conv_id=0）
• 请求-响应：声明、锁、会话（使用 conv_id 进行关联）
• 发布/订阅订阅：断开连接时进行清理
• 自动重连：套接字断开时，客户端会重连并重放订阅
• SDK 快速路径：heartbeat()、pheromoneSpray()、publish() 在 IPC 可用时会自动使用

套接字位置： ~/.port-daddy/daemon.ipc

安全强化：

• 速率限制：每个连接每秒 500 帧
• 连接数限制：最多 256 个（超出时返回 REFUSE）
• 违规协议预算：3 次（格式错误的帧会导致断开连接）
• 通过写入队列和 drain 事件实现背压
• IPC 断开时释放锁

无需直接使用 IPC。SDK 和 CLI 会为高频路径操作透明地使用它。

Fleet：后台 Agent（v3.8.0）

在 YAML 中声明 Agent。它们会在 git 提交、cron 计划或发布/订阅消息触发时运行。崩溃后自动重启，并带有断路器。

pd fleet init     # Creates pd-fleet.yml + git hook
pd fleet up       # Starts the fleet
git commit -m "fix auth"  # QA, docs, cartographer fire automatically
pd fleet status   # What is the fleet doing?
pd fleet down     # Stop the fleet

入门 Fleet 包含：QA（查找漏洞）、Documentarian（同步文档）、Cartographer（跟踪路线图）、Spark（生成创意）、Spider（建立跨功能联系）。

# pd-fleet.yml
fleet:
  name: myapp
  harbor: "{project}:fleet"
  agents:
    qa:
      trigger: git:committed        # React to pub/sub events
      respawn: true                  # Auto-restart on crash
      max_respawns: 3               # Circuit breaker
      backend: claude-cli
      allowedTools: "Read,Grep,Glob,Bash(npm test*)"
      prompt: "Review the last commit for bugs..."

    gardener:
      schedule: "*/10 * * * *"      # Or run on a cron schedule
      backend: custom
      prompt: "git status --porcelain"
      on_success: publish git:status  # Chain agents via channels

  channels:
    git:committed:
      description: "Fired after a successful commit"
      consumers: [qa]

主要特性：

• 适用于任何大模型后端：claude-cli、ollama、gemini、aider、custom
• 模板变量（{project}）从 YAML 上下文中解析
• on_success: publish <channel> 通过发布/订阅连接 Agent（启动时会验证 DAG 拓扑）
• 执行 pd fleet up 时会自动创建 Fleet harbor——所有 Agent 共用一个语义命名空间
• 每个 Agent 都具备完整的 PD 协调能力：注册、会话、心跳、崩溃后清理
• 使用 respawn: true 和 max_respawns 断路器实现自动重启

元组空间：共享群体记忆（v3.8.0）

Agent 将带类型的元组写入共享空间。其他 Agent 可按模式查询。基于 Linda（Gelernter，1985）。按 harbor 隔离 Fleet。使用 TTL 自动过期。

# Spider writes a connection it discovered
pd tuple out '["connection", "trie+pubsub=routing", "spider", 0.9]' --harbor myapp:fleet

# Spark reads all connections with confidence > 0.7
pd tuple rd '["connection", "*", "*", ">0.7"]' --harbor myapp:fleet

# Take (remove) a processed task from the space
pd tuple in '["task", "build-auth", "pending"]'

# Scan all tuples in a harbor
pd tuple scan --harbor myapp:fleet

# Count tuples
pd tuple count --harbor myapp:fleet

模式匹配支持：精确值、* 通配符、>N/<N 数值比较、myapp:* 语义身份前缀。

HTTP API：

• POST /tuples — 写入元组（请求体：{ tuple, harbor?, writtenBy?, ttl? }）
• GET /tuples — 按模式读取（查询参数：pattern、harbor、limit）
• DELETE /tuples — 按模式获取元组（破坏性读取）
• GET /tuples/scan — 列出 harbor 中的所有元组
• GET /tuples/count — 统计元组数量

信息素轨迹：环境信号（v3.8.0）

Agent 在实体上喷洒数值信号（0-1）。读取时信号会随时间呈指数衰减，从而在无需轮询的情况下形成环境感知。

# Spray a signal onto a service
pd pheromone spray --table services --id myapp:api --key urgency --strength 0.8

# Sniff pheromone values (applies read-time decay)
pd pheromone sniff --table services --id myapp:api

# View file heat map (which files are most contested)
pd pheromone files

# List all non-zero pheromone trails
pd pheromone list

使用场景：检测文件竞争、评估 Agent 声誉、识别高频路径、自适应阈值。

HTTP API：

• POST /pheromone/spray — 设置信息素值（请求体：{ table, id, key, strength }）
• GET /pheromone/:table/:id — 读取信息素值（读取时应用衰减）
• GET /pheromone — 列出所有非零信息素
• GET /pheromone/files — 根据会话文件声明生成文件热度图（查询参数：path、depth）

The Arbiter：运行时不变量强制执行（v3.8.0）

The Arbiter 会根据 TLA+ 规范中形式化推导出的 6 项不变量，监控每次状态转换：

• PID 抢占 — 进程无法占用其他进程的端口
• 能力升级 — Agent 不能超出声明的能力范围
• 笔记单调性 — 笔记只能追加，不能删除
• 托管资金为正 — 加密笔记托管余额始终为正
• 锁所有者有效性 — 只有所有者才能释放锁
• 心跳时效性 — 清除失联的 Agent

在严格模式下，严重违规会触发弃船救援。

pd arbiter status         # Check rules and violation count
pd arbiter violations     # List recorded violations

运行时文件位置（v3.8.2）

所有运行时文件都位于 ~/.port-daddy/（而非 /tmp/）。这样可以杜绝符号链接攻击，不受 /tmp/ 清理影响，并通过将目录权限设为 0700 来保护用户隐私。

文件	用途
~/.port-daddy/daemon.sock	HTTP Unix 套接字（CLI、SDK、MCP）
~/.port-daddy/daemon.ipc	二进制 IPC 套接字（Agent 热路径）
~/.port-daddy/daemon.pid	PID 文件
~/.port-daddy/daemon.port	TCP 端口文件（用于发现仪表板）
~/.port-daddy/master.key	用于加密笔记的 AES-256-GCM 主密钥

通过环境变量覆盖：PORT_DADDY_SOCK、PORT_DADDY_IPC、PORT_DADDY_PORT_FILE。

CLI 快速参考

命令	用途
会话生命周期
pd begin / pd done	开始/结束会话（包含 Agent 注册）
pd whoami	当前 Agent 和会话上下文
pd note / pd notes	写入/读取不可变笔记
端口管理
pd claim / pd release	申请/释放确定性端口
pd find	通配符服务搜索（由 trie 加速）
协作
pd lock / pd unlock	分布式锁
pd with-lock	在锁定状态下运行命令并自动释放锁
pd pub / pd watch	发布/订阅消息
pd session files claim	文件声明（建议性）
集群与 Agent
pd fleet init	创建 pd-fleet.yml + git 钩子
pd fleet up/down/status	启动/停止/检查集群
pd spawn / pd spawned	启动/列出后台 Agent
pd spawn kill	终止已启动的 Agent
pd salvage	恢复已死亡的 Agent
蜂群记忆
pd tuple out/rd/in	写入/读取/取出元组
pd tuple scan/count	列出/统计元组
pd pheromone spray	为实体设置环境信号
pd pheromone sniff	读取信息素值（包含衰减）
pd pheromone list	列出所有非零信息素
pd pheromone files	文件热度图
系统
pd status	守护进程健康状况
pd version	版本和代码哈希
pd arbiter status	不变量强制执行状态
pd arbiter violations	列出记录的违规情况
pd dev start/stop/status	隔离的开发守护进程（端口 9877）

决策矩阵：何时使用哪种工具

问题	解决方案
开发服务器端口冲突	pd claim myapp:api -q
需要与其他 Agent 协作	pd begin + pd session files claim
Agent 间信号传递	pd pub + pd watch
向特定 Agent 发送直接消息	talk_to_agent MCP 工具或 pd inbox send
后台自动化	pd fleet init + pd fleet up
在多个 Agent 间共享知识	pd tuple out / pd tuple rd
跟踪资源的“热度”	pd pheromone spray / sniff
快速查看文件争用情况	file_heat MCP 工具或 pd pheromone files
崩溃的 Agent 留下了未完成的工作	pd salvage
排他性操作（部署、迁移）	pd with-lock
我离开期间发生了什么？	catch_me_up MCP 工具
现在还有谁在工作？	swarm_awareness MCP 工具
检查不变量违规	pd arbiter status

常见问题

Port Daddy 守护进程未运行

症状： 任何 pd 命令都返回 Connection refused 修复： 运行 pd start 或 pd install（安装为 launchd 服务，并在登录时自动启动）

端口已被占用

**症状：**你获得了一个端口，但它是“错误的”端口 **这是正确的行为。**相同身份始终对应相同端口。如果需要不同的端口，请使用不同的身份上下文：myapp:api:feature-x，而不是 myapp:api:main。

会话已处于活动状态

症状：pd begin 提示会话已存在 **解决方法：**调用 pd whoami 查看当前会话。可以对旧会话调用 pd done，也可以继续在其中工作。

文件声明冲突

**症状：**另一个 Agent 声明了你需要的文件 **解决方法：**这是系统正常运作的表现。检查 pd swarm_awareness，了解文件归属。通过 pd pub 协调，或处理不同的文件。

IPC 连接失败

**症状：**日志中出现与 IPC 相关的错误 **解决方法：**SDK 会自动回退到 HTTP。IPC 是一种优化，并非必需。检查 ~/.port-daddy/daemon.ipc 是否存在且权限正确（应仅对用户开放，由守护进程创建）。

质量门槛

在宣布任何由 PD 协调的工作“完成”之前：

• Agent 已注册身份（pd whoami 会返回一个身份）。
• 文件声明与实际编辑的文件相符。
• 每个基本里程碑至少有一条 progress 记录。
• 如果工作中途结束，则存在一条 handoff 记录（便于接手）。
• 已调用 pd done——让会话保持开放是最常见的内部试用违规行为。