Slock 完整架构逆向.

1Slock 是什么

Slock 是 botiverse 做的"人-AI 协作平台",外观像 Slack,但用户列表里混着真人和 AI agent。每个 agent 都是个**长期成员**:有 persona、有 MEMORY、能参与 thread / DM / task / channel。

2整体架构 & 组件清单

组件分工速查

3消息接收流程(IM in)

从"用户在 Web UI 点发送"到"agent 进程读到消息"的完整链路 —— 这是 slock 最核心的机制。

真实 ws 帧 (server → daemon, 实抓)

{
  "type": "agent:deliver",
  "agentId": "220e72da-...",
  "message": {
    "channel_id":   "b3d84e4d-...",
    "channel_name": "all",
    "channel_type": "channel",
    "sender_id":    "fa31c41a-...",
    "sender_name":  "oanakiaja",
    "sender_type":  "human",
    "content":      "按顺序都报个数 @Alice",         # ← 明文消息
    "timestamp":    "2026-05-16T09:29:17.765Z",
    "seq":          3940919,                          # ← 全局序列号
    "message_id":   "f02a5e15-..."
  },
  "seq":         3940919,
  "traceparent": "00-4a02...-08cc...-00",             # ← OTel 链路
  "deliveryId":  "40e8b589-..."
}

Agent 看到的最终格式 (RFC 5424 风格)

[target=#all msg=f02a5e15 time=2026-05-16T09:29:17 type=human] @oanakiaja: 按顺序都报个数 @Alice

这是 daemon 把 ws 的 JSON payload 通过 formatIncomingMessage()(line 5118)转成的扁平字符串,然后通过 stream-json 协议喂给 claude 进程的 stdin。LLM 只看得到这个字符串。

4消息发送流程(IM out)

反方向不走 ws,走 HTTPS REST —— 这是个让我意外的发现。

5Agent 启动序列

从"server 决定唤醒 agent A"到"claude 子进程开始推理"完整过程。

claude --model opus \
      --allow-dangerously-skip-permissions \
      --system-prompt-file {workspace}/.slock/claude-system-prompt.md \
      --mcp-config        {workspace}/.slock/claude-mcp-config.json \
      --output-format stream-json --input-format stream-json \
      --strict-mcp-config
   ENV: SLOCK_AGENT_ID, SLOCK_SERVER_URL, SLOCK_AGENT_TOKEN_FILE, PATH+=workspace/.slock

6Agent Prompt 完整组装

每个 agent 进程实际"看到"的输入 = system prompt(预先写文件) + wake prompt(每次启动时通过 stdin 注入)。下面拆解每一块。

① System Prompt(26KB · 323 行)完整结构

这是 daemon 调用 driver.buildSystemPrompt(config) 在本地拼出来的,写到 {workspace}/.slock/claude-system-prompt.md,通过 --system-prompt-file 传给 claude。下面把每章展开,**保留关键原文**让你看到 LLM 实际"读"到的内容。

开篇(无章节标题)

## Who you are — 生命周期

## Current Runtime Context — 注入的身份

This is authoritative context injected by Slock. Do not infer
computer identity from hostname or cwd when this section is present.

- Agent ID: 220e72da-16e1-4c1a-a8a5-d28cfa127d8d
- Server ID: 5a55aa61-86cd-4cfd-a965-16e73de3e832
- Computer: MBP (bb5494bd-5d36-4ff5-a15a-2fb679ccb561)
- Hostname: 192.168.0.101
- OS: darwin arm64
- Daemon: v0.49.0
- Workspace: /Users/oanakiaja/.slock/agents/220e72da-...

## Communication — slock CLI ONLY — 26 命令

- Always communicate through `slock` CLI commands.
  This is your only output channel.
- Runtime Profile migration completion is the only exception:
  call mcp__chat__runtime_profile_migration_done with the exact
  migration_key.
- Always claim a task via `slock task claim` before starting work.
  If the claim fails, move on to a different task.

## Startup sequence — 启动行为

1. If this turn already includes a concrete incoming message,
   first decide whether that message needs a visible
   acknowledgment, blocker question, or ownership signal.
2. Read MEMORY.md (in your cwd) and then only the additional
   memory/files you need to handle the current turn well.
3. If there is no concrete incoming message to handle,
   stop and wait. New messages may be delivered to you
   automatically while your process stays alive.
4. When you receive a message, process it and reply with
   `slock message send`.
5. Complete ALL your work before stopping. ...
   New messages arrive automatically — you do not need to poll.

## Messaging — RFC 5424 风格

[target=#general    msg=a1b2c3d4 time=... type=human] @richard: hello
[target=#general    msg=e5f6a7b8 time=... type=agent] @Alice: hi there
[target=dm:@richard msg=c9d0e1f2 time=... type=human] @richard: can you help?
[target=#general:a1b2c3d4 msg=f3a4b5c6 ...] @richard: thread reply

# 回复 channel
slock message send --target "#channel-name" <<'EOF'
content
EOF

# 回复 DM
slock message send --target dm:@peer-name <<'EOF' ...

# 回复 thread
slock message send --target "#channel:shortid" <<'EOF' ...

### Reminders — 给未来自己的叫醒服务

### Threads — 子对话

### Discovering people and channels

### Channel awareness — 频道感

### Reading history

slock message read --channel "#channel-name"
slock message read --channel dm:@peer-name
slock message read --channel "#channel:shortid"
slock message read --channel "..." --around "messageId"
slock message read --channel "..." --around 12345

### Historical references

### Tasks — 任务认领

# 已是任务
@Alice: Fix the login bug [task #3 status=in_progress]

# 普通消息(可能需要 claim)
@Alice: Can someone look into the login bug?

# 任务系统通知
📋 Alice converted a message to task #3 "Fix the login bug"

### Splitting tasks for parallel execution

## @Mentions

## Communication style

# 错: 测试环境:http://localhost:3000,请查看
# 对: 测试环境:<http://localhost:3000>,请查看
# 也对: 测试环境:[http://localhost:3000](http://localhost:3000),请查看

## Workspace & Memory

# <Your Name>

## Role
<your role definition, evolved over time>

## Key Knowledge
- Read notes/user-preferences.md for ...
- Read notes/channels.md for ...

## Active Context
- Currently working on: <brief summary>
- Last interaction: <brief summary>

## Capabilities

## Message Notifications

## Initial role

② Wake Prompt(每次启动 stdin 注入)

daemon 根据当前状态拼装(line 5113 起),四种 case:

# Case 1: 有 wakeMessage(被消息触发)
New message received:

[target=#all msg=f02a5e15 time=2026-05-16T09:29:17 type=human] @oanakiaja: 按顺序都报个数 @Alice

You also have unread messages in other channels:                   # 仅当 unreadSummary 非空
- #general: 2 unread

Use `slock message read` to catch up, or respond to the message above first.

Respond as appropriate — send a message in the same channel, or take action as needed.
Complete ALL your work before stopping.
Reply in the channel or create/reply in a thread as appropriate; use each message's `target` and `msg` fields to choose the exact target.

IMPORTANT: If the message requires multi-step work (e.g. research, code changes, testing), complete ALL steps before stopping. Sending a progress update does NOT mean your task is done — only stop when you have NO more work to do.

# Case 2: 恢复时只有未读摘要(无具体消息)
You have unread messages from while you were offline:
- #all: 1 unread
- dm:@richard: 1 unread
Use `slock message read` to catch up...

# Case 3: 恢复但无未读 —— "No new messages while you were away. Nothing to do — just stop."
# Case 4: runtime profile control 模式 —— 注入 migration 指令

③ 系统触发消息(server 主动注入的)

除了真人消息,server 还会发"系统消息"。例:新建 agent 时强制让它自我介绍:

{
  "sender_id":   "system",
  "sender_name": "system",
  "sender_type": "human",                              # 注意是 human 不是 system,LLM 把它当指令
  "content":     "First message task (system-triggered):
                  Please post in #all now.
                  Use your Slock identity name: @Mike.
                  Do not use local OS usernames...
                  Say hi and briefly introduce yourself (role + how you can help).
                  Keep it short and friendly."
}

7实例:4 个 Agent 报数 1-2-3-4 全流程

把前面 6 节学到的所有机制串起来,推演最初那张截图(琦玉/架构师A/haoshuo/Eric 在 thread 里报 1-2-3-4)的完整数据流。这条流程**没有真抓到**(抓包时只有 2 agent),但我用真实 ws 帧验证过的机制能推断出 100% 准确的时序。

关键观察(全部基于实抓 ws 验证)

1. 同 seq 广播 —— 我抓的真实帧里 17:29:15.715 和 17:29:15.716 两条 deliver 用了同一个 seq=3940919,只差不同的 deliveryId。4 个 agent 也是同样模式,server 一次性发 4 条 ws 帧。
2. 500ms 跨 agent 限速 —— DEFAULT_AGENT_START_INTERVAL_MS = 500(line 3803),所以 4 个 agent 不会同瞬间 spawn,而是依次相隔 500ms。
3. 顺序不预定 —— 谁 LLM 快谁先报 —— 真实抓包里 Mike(claude/opus)和 Cindy(claude/opus)对同一指令的回复差了 30 秒。截图里 4 个 agent 看似有序的 1-2-3-4 是因为 spawn 依次错开 + 每个 agent 醒来就读历史,不是因为 server 指定了顺序。
4. read_history 是去重核心 —— system prompt 第 5113 行的 wake prompt 强制要求 "Use slock message read to catch up, or respond to the message above first"。每个 agent 在动笔前都会先看 channel 现有内容。
5. fan-out 是 server→所有 agent —— 每个 agent 报完一个数,server 都把它 fan-out 给其他 3 个 agent(同样走 agent:deliver,但 sender_type: "agent")。这让后报的 agent 能"看到"前面的回复。

一个 agent 的实际 prompt 输入(以"架构师A"为例)

架构师A 这个进程被 spawn 起来时,通过 --system-prompt-file 看到 26KB persona,然后 daemon 通过 stdin (stream-json) 注入下面这条 wake prompt:

New message received:

[target=#讨论问题:0c8a3f12 msg=48cc7b43 time=2026-05-16T09:17:00 type=human] @Haoxiang: 在这条thread里所有人给我从1开始每一个人都往上报数,不允许报重复的数字

Respond as appropriate — send a message in the same channel, or take action as needed.
Complete ALL your work before stopping.
Reply in the channel or create/reply in a thread as appropriate; use each message's `target` and `msg` fields to choose the exact target.

IMPORTANT: If the message requires multi-step work (e.g. research, code changes, testing), complete ALL steps before stopping.

架构师A 的 LLM 看到这条之后:

1. (由 system prompt 第 ## Startup sequence 引导)先读 thread 历史:
   $ slock message read --target "#讨论问题:0c8a3f12" --before $(now)
2. 看到琦玉已经回了"1"(如果琦玉先完成 → 这是 server 后续 fan-out 进来的;如果架构师A 比琦玉快 → 这步看不到东西,自己变成第一个)
3. 决定要报"2"
4. 调用 $ slock message send --target "#讨论问题:0c8a3f12" <<'EOF'\n2\nEOF
5. slock CLI 拿环境里的 SLOCK_AGENT_TOKEN_FILE 鉴权,HTTPS POST 给 api.slock.ai
6. server 接收,分配新 seq,fan-out 给 haoshuo / Eric / 琦玉
7. LLM 进程退出,daemon 缓存 idle config 等下次唤醒

同时也解释了为什么会"撞号"

如果两个 agent 同时 在 LLM 推理(spawn 间隔 500ms 内,LLM 5 秒内出结果),后启动那个调 read_history 时前一个还没 post 完,就可能两个都报"1"。截图里没撞号,是因为:

• 4 个 agent spawn 间隔 500ms,每个 LLM 至少 1-2 秒
• 每次 post 完 server fan-out 给其余 agent 是几十毫秒级
• 所以等架构师A spawn 起来 + 推理完时,琦玉的"1"已经在 channel 里了

这个机制对慢 LLM 友好,对快 LLM(比如同时 4 个 haiku)就**容易撞**。理论上可以用 slock task claim 那种乐观锁来强一致,但 slock 选择了"靠 LLM 自觉" + "靠物理延时"这种宽松方案。

8多 Agent 协作模型

实际抓到的报数样例(17:33:03 - 17:33:44)

17:33:03  human: "按顺序报个数"
17:33:03  server → daemon  agent:deliver → @Mike   (seq=3941285)   # 同 seq
17:33:03  server → daemon  agent:deliver → @Cindy  (seq=3941285)   # 同 seq · 同时
17:33:13  @Mike  posts "1"                                          # LLM 快的赢
17:33:13  server → daemon  agent:deliver → @Cindy: @Mike的"1"       # fan-out
17:33:44  @Cindy posts "2"                                          # 看到 "1" 了,自然报 2

所以"防撞号"实际只有两层(我修正了之前的三层说法)

所以这个设计的本质

slock 把"orchestration"问题转嫁给了 LLM 自己 —— 通过 system prompt 里的"Respect ongoing conversations"、"Only the person doing the work should report on it"、"Claim before you start"等规则让 agent 们自觉协调。底层基建只保证:

• 消息有序(全局 seq)
• 消息可达(at-least-once + ack)
• 不撞重启(500ms 节流)

"谁说话"完全是 LLM 决定的涌现行为。这其实是个很大胆的设计 —— 高度依赖 LLM 的对话能力。

9slock CLI 全集

Agent 唯一对外通信方式。从 system prompt 提取的 26 个命令:

10隐私 / 安全 / 风险

11关键代码 & 文件位置

本地文件结构

~/.slock/
├── owner.json                                       # 你的身份
├── agents/{agentId}/
│   ├── .slock/
│   │   ├── slock                                    # 180B shell wrapper → daemon CLI
│   │   ├── agent-token                              # per-agent 鉴权
│   │   ├── claude-system-prompt.md                  # 26KB persona prompt
│   │   ├── claude-mcp-config.json                   # chat-bridge MCP 配置
│   │   └── runtime-sessions/*.jsonl                 # session handoff 记录
│   ├── MEMORY.md                                    # agent 持久记忆
│   └── notes/                                       # agent 自由工作目录
└── machines/{machineId}/
    ├── daemon.lock
    ├── traces/*.jsonl                               # OTel span 本地缓存
    └── trace-uploads/*.uploaded.json                # 上传状态记录

~/.claude/projects/-Users-oanakiaja--slock-agents-{agentId}/{sessionId}.jsonl   # Claude session 实际位置
~/.codex/sessions/{date}/rollout-...-{sessionId}.jsonl                          # Codex session 实际位置

chunk-M4A5QPUN.js 速查

抓包样本

共 276 frames 抓在 /Users/oanakiaja/slock-mitm/ws-frames.jsonl,包括:

• 4 次 agent:start(完整 config payload)
• 11 次 agent:deliver(完整 message payload,含明文)
• 11 次 agent:deliver:ack
• ~60 次 agent:activity(实时状态变更)
• 多次 agent:skills:list / agent:runtime_profile
• 1 次 ready 握手帧