Back to Details

walkie

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Walkie — Agent-to-Agent P2P Communication

Walkie — Agent间P2P通信

Core Workflow

核心工作流程

Every agent communication follows this pattern:
  1. Create/Join: Both agents connect to the same channel with a shared secret
  2. Send: Push messages to the channel
  3. Read: Pull messages (non-blocking or blocking)
  4. Cleanup: Leave the channel and stop the daemon when done
bash
undefined
每个Agent通信都遵循以下模式：
  1. 创建/加入：两个Agent通过共享密钥连接至同一频道
  2. 发送：向频道推送消息
  3. 读取：拉取消息（非阻塞或阻塞模式）
  4. 清理：完成操作后离开频道并停止守护进程
bash
undefined

Agent A

Agent A

walkie create ops-room -s mysecret walkie send ops-room "task complete, results at /tmp/output.json"
walkie create ops-room -s mysecret walkie send ops-room "任务完成，结果位于/tmp/output.json"

Agent B

Agent B

walkie join ops-room -s mysecret walkie read ops-room
walkie join ops-room -s mysecret walkie read ops-room

[14:30:05] a1b2c3d4: task complete, results at /tmp/output.json

[14:30:05] a1b2c3d4: 任务完成，结果位于/tmp/output.json

undefined
undefined

Essential Commands

关键命令

bash
undefined
bash
undefined

Channel management

频道管理

walkie create <channel> -s <secret> # Create a channel and listen for peers walkie join <channel> -s <secret> # Join an existing channel walkie leave <channel> # Leave a channel walkie stop # Stop the background daemon
walkie create <channel> -s <secret> # 创建频道并监听对等节点 walkie join <channel> -s <secret> # 加入现有频道 walkie leave <channel> # 离开频道 walkie stop # 停止后台守护进程

Messaging

消息操作

walkie send <channel> "message" # Send a message to all peers walkie read <channel> # Read pending messages (non-blocking) walkie read <channel> --wait # Block until a message arrives (default 30s) walkie read <channel> -w -t 60 # Block with custom timeout (seconds)
walkie send <channel> "message" # 向所有对等节点发送消息 walkie read <channel> # 读取待处理消息（非阻塞模式） walkie read <channel> --wait # 阻塞直到收到消息（默认30秒超时） walkie read <channel> -w -t 60 # 自定义超时时间的阻塞模式（秒）

Status

状态查询

walkie status # Show active channels, peers, buffered messages
undefined
walkie status # 显示活跃频道、对等节点和缓冲消息
undefined

Common Patterns

常见模式

Two-Agent Collaboration

双Agent协作

bash
undefined
bash
undefined

Agent A (coordinator)

Agent A（协调者）

walkie create task-room -s sharedsecret walkie send task-room "analyze /data/users.csv and report top 10" walkie read task-room --wait --timeout 120 # Wait for result
walkie create task-room -s sharedsecret walkie send task-room "分析/data/users.csv并上报前10条数据" walkie read task-room --wait --timeout 120 # 等待结果

Agent B (worker)

Agent B（执行者）

walkie join task-room -s sharedsecret walkie read task-room --wait # Get the task
walkie join task-room -s sharedsecret walkie read task-room --wait # 获取任务

... do the work ...

... 执行工作 ...

walkie send task-room "done: top 10 users saved to /tmp/report.txt"
undefined
walkie send task-room "完成：前10条用户数据已保存至/tmp/report.txt"
undefined

Polling Between Task Steps

任务步骤间轮询

Check for messages between work steps to receive course corrections, new data, or stop signals mid-operation.
bash
walkie join task-channel -s secret
在工作步骤之间检查消息，以便在操作过程中接收修正指令、新数据或停止信号。
bash
walkie join task-channel -s secret

Step 1: do work

步骤1：执行工作

walkie read task-channel # Non-blocking check
walkie read task-channel # 非阻塞检查

Step 2: do more work

步骤2：执行更多工作

walkie read task-channel # Non-blocking check
walkie read task-channel # 非阻塞检查

Step 3: report completion

步骤3：上报完成状态

walkie send task-channel "all steps complete"
undefined
walkie send task-channel "所有步骤已完成"
undefined

Hub-and-Spoke (One Coordinator, Many Workers)

星型架构（一个协调者，多个执行者）

bash
undefined
bash
undefined

Coordinator creates a shared channel

协调者创建共享频道

walkie create dispatch -s teamsecret
walkie create dispatch -s teamsecret

Workers all join the same channel

所有执行者加入同一个频道

walkie join dispatch -s teamsecret # Worker 1 walkie join dispatch -s teamsecret # Worker 2
walkie join dispatch -s teamsecret # 执行者1 walkie join dispatch -s teamsecret # 执行者2

Coordinator broadcasts tasks

协调者广播任务

walkie send dispatch "worker-1: process batch A" walkie send dispatch "worker-2: process batch B"
walkie send dispatch "worker-1: 处理批次A" walkie send dispatch "worker-2: 处理批次B"

Workers poll for their assignments

执行者轮询获取分配的任务

walkie read dispatch
undefined
walkie read dispatch
undefined

Blocking Wait for Response

阻塞等待响应

bash
walkie send task-room "what is the status?"
walkie read task-room --wait --timeout 60
bash
walkie send task-room "当前状态如何？"
walkie read task-room --wait --timeout 60

Blocks until a reply arrives or 60 seconds elapse

阻塞直到收到回复或60秒超时

undefined
undefined

Key Details

核心细节

  • Daemon auto-starts on first command, runs in background at 
    ~/.walkie/
  • Messages buffer locally — 
    walkie read
    drains the buffer, each message returned once
  • Channel = hash(name + secret) — both sides must use the same name and secret
  • Encrypted — all P2P connections use the Noise protocol via Hyperswarm
  • Peer discovery takes 1–15 seconds via DHT
  • No server — fully peer-to-peer, works across machines and networks
  • walkie read
    output format    : 
    [HH:MM:SS] <sender-id>: <message>
  • 守护进程自动启动：首次执行命令时自动启动，在后台
    ~/.walkie/
    目录运行
  • 消息本地缓冲 — 
    walkie read
    会清空缓冲，每条消息仅返回一次
  • 频道 = 哈希(名称 + 密钥) — 双方必须使用相同的名称和密钥
  • 加密传输 — 所有P2P连接通过Hyperswarm使用Noise协议加密
  • 对等节点发现：通过DHT需要1–15秒
  • 无服务器架构 — 完全点对点，可跨机器和网络工作
  • walkie read
    输出格式    ：
    [HH:MM:SS] <sender-id>: <message>

Cleanup

清理操作

Always clean up when done to avoid leaked daemon processes:
bash
walkie leave <channel>   # Leave specific channel
walkie stop              # Stop the daemon entirely
完成操作后务必进行清理，避免守护进程泄漏：
bash
walkie leave <channel>   # 离开指定频道
walkie stop              # 完全停止守护进程

Deep-Dive Documentation

深度文档

ReferenceWhen to Use
references/commands.mdFull command reference with all options and output formats
references/architecture.mdHow the daemon, IPC, and P2P layers work
references/polling-patterns.mdAgent polling strategies, multi-agent coordination patterns
参考文档使用场景
references/commands.md包含所有选项和输出格式的完整命令参考
references/architecture.md守护进程、IPC和P2P层的工作原理
references/polling-patterns.mdAgent轮询策略、多Agent协调模式

Ready-to-Use Templates

即用型模板

TemplateDescription
templates/two-agent-collab.shCoordinator sends task, worker executes and reports back
templates/delegated-task.shDelegate work to another agent and wait for result
templates/monitoring.shMonitor agent activity from a separate terminal
模板描述
templates/two-agent-collab.sh协调者发送任务，执行者执行并上报结果
templates/delegated-task.sh将工作委托给另一个Agent并等待结果
templates/monitoring.sh从独立终端监控Agent活动