Pyunto Diary

pyunto-agent

让外部 Agent 成为 Pyunto 交换日记的伙伴。这个 Agent 是一名普通成员： 拥有自己的 Pyunto 账户和 X25519 身份密钥，通过常规邀请链接受邀加入。服务器无需改动，也永远看不到明文；解密在此进程中完成。

适用于 iPhone 和 iPad 的 Pyunto · 适用于 Android 的 Pyunto · pyunto-robotics — 同样的理念，只不过对面是一个机器人（观看视频，100 秒）

一次真实运行，使用 Claude Code 作为模型：人设为力量教练，定义在 Markdown 文件中；客户端则用手机记录训练。第二条回复会与前一天进行比较。 观看完整的 90 秒视频。

---

两种 Agent

同一个包、同一个账户、同一套密钥。不同之处在于谁发起对话。

1. Agent — 它会主动向你的用户发送消息

你写下内容；它会在同一个对话线程中主动回复。

     your phone                     your computer
 ┌───────────────┐            ┌──────────────────────┐
 │  Pyunto app   │            │  pyunto-agent run    │
 │               │            │                      │
 │  "tough day   │  ───────▶  │  reads the entry     │
 │   at work"    │  encrypted │  decrypts it HERE    │
 │               │            │        │             │
 │               │            │        ▼             │
 │  "that sounds │  ◀───────  │  Claude API, or      │
 │   exhausting" │  encrypted │  Claude Code, or     │
 └───────────────┘            │  your own HTTP URL   │
                              └──────────────────────┘
        │                                │
        └────────  api.pyunto.com  ──────┘
              (ciphertext only, never plaintext)

**如何邀请它：**运行 pyunto-agent pair，用应用扫描二维码，然后选择一本日记。 你批准后，Agent 就会开始回复。

**适用场景：**运行一项服务，在人们已经常用的地方与他们联系。

通用聊天机器人是一个网站，别人必须记得去访问，而且它在一个不记得用户的标签页中。而这是一个人在手机上的消息应用里的联系人，有名有姓，读过对方之前写的所有内容，并且会按你设定的角色作出回应。

这个角色由一个文件定义。--persona coach.md 就是礼貌的助手与值得付费的服务之间的全部区别：

You are a strength coach. Your client logs every session here.

- Hold them to the programme. If they skipped legs again, say so plainly.
- Always ask for the numbers: weight, sets, reps. A session without numbers is not logged.
- Compare against last week before you praise anything.
- No pep talk. One sentence of encouragement, only when it is earned.

pyunto-agent run --backend claude-api --persona coach.md

它可以用于以下服务：

服务	角色设定能做到聊天机器人做不到的事
🏋️ 力量教练	要求用户提供数据，记住上周的数据，不会夸奖跳过训练
🗣️ 语言导师	纠正每条消息，持续记录学习者自己的错误，并逐步提高难度
🏥 诊所术后随访	每天按顺序询问术后问题，并标记护士应该查看的回答
🥗 营养师	查看餐食照片，持续统计每周总量，关注饮食模式而非单餐
📚 学习监督员	要求学生遵守复习计划，询问实际学了什么，不接受“我学过了”
🔧 物业经理	租户每次都在同一个对话线程中报告问题；Agent 会分诊、索要照片并升级处理
📐 现场检查	工程师拍摄现场照片；Agent 会将照片记录到对应任务中，并询问缺少的信息
📅 戒酒或习惯支持	在关键时刻主动问候，保持连续记录，并按照你的设定回应复发情况

这些服务之所以适合在这里运行，而不是在聊天窗口中运行，原因如下：

• **角色设定始终如一。**它是由你掌控的文件，不是用户可以靠交谈摆脱的提示词。
• 它会记住。--history 会让每条回复都包含近期对话线程，因此“和上周二一样”有了明确含义。
• **它就在用户的手机上。**用户会收到通知，并在自己已经使用的消息应用中回复。无需登录、无需切换标签页，也无需学习使用新应用。
• **你看不到任何内容。**日记采用端到端加密，只有在你运行的进程中才会解密。对于谈论身体、健康或财务状况的客户来说，这是一个实实在在的承诺。
• **一个进程，多个客户。**不指定 --space 时，pyunto-agent run 会回复该账号获邀加入的每本日记中的消息，因此客户只需扫描二维码即可完成引导。使用 --space 可将一个 Agent 固定到一位客户。

2. MCP — 你向 Claude 询问日记内容

没有任何程序在后台运行。Claude Code 或 Claude Desktop 会在你发出请求时访问日记。

     your computer
 ┌────────────────────────┐
 │  Claude Code / Desktop │
 │            │           │        ┌──────────────────┐
 │            ▼           │        │  your phone      │
 │  "what did I write     │        │  Pyunto app      │
 │   about the garden?"   │        │                  │
 │            │           │        │  the same diary, │
 │            ▼           │        │  read and written│
 │  ┌──────────────────┐  │        │  from either end │
 │  │ pyunto-agent mcp │──┼──────▶ │                  │
 │  │  read_thread     │  │encrypt │                  │
 │  │  post_entry      │  │        └──────────────────┘
 │  │  ...12 tools     │  │
 │  └──────────────────┘  │
 └────────────────────────┘

**如何邀请它：**将服务添加到你的 MCP 客户端（见下文），然后让 Claude 配对： pair 工具会显示一个二维码，用 Pyunto 应用扫描即可。无需在终端中执行任何步骤。

claude mcp add pyunto-diary -- uvx pyunto-agent mcp

**适用场景：**将日记用作记忆。搜索数月的记录、总结一周内容、在桌面端撰写日记条目，或让 Claude 在回答前查看你之前记录的内容。每次对话都由你发起；它绝不会在你未询问时主动发言。

选哪一种？

	Agent（run）	MCP（mcp）
谁先发言	Agent	你
是否在后台运行	是，持续运行	否，仅在需要时运行
用户在哪里与它交流	Pyunto 应用，在手机上	Claude Code / Desktop
面向谁	一项服务及其用户	一个人和自己的日记
典型用途	教练、导师、答疑服务	搜索和总结你的记录

两者可以同时配对到同一本日记中——它们使用同一个账户，而且没有任何限制会阻止 run 在你的手机上回复，同时让 mcp 在你的桌面读取相同的记录。

还有第三种，运行在其他地方。 pyunto-robotics 用机器人而非大模型作为另一端：你写下“去找些阳光”，一台模拟或真实的机器就会执行并用照片汇报。它基于这个软件包构建，配对方式也相同。

快速开始：让客户联系你的私人教练

从零开始构建一项真实服务，让客户能在手机上使用。

1. 安装

需要 Python 3.11 或更高版本。请安装到虚拟环境中：Homebrew 的 Python 不允许全局执行 pip install（externally-managed-environment）。

python3.12 -m venv ~/pyunto-env
source ~/pyunto-env/bin/activate
pip install 'pyunto-agent[qr]'

然后选择回复的来源：

export ANTHROPIC_API_KEY=sk-ant-...    # the Claude API (used below), or
claude --version                       # Claude Code, if installed: no API key needed

使用 Claude Code 时，将下面的 --backend claude-api 替换为 --backend command --command 'claude -p --output-format json'。如果两者都未配置，pair 和 run 会说明这一点，并列出选项，然后才显示二维码。

2. 编写教练

这个文件就是服务本身。教练的一切特质——严格还是温和、坚持什么、绝不放任什么——都由此决定，客户无法通过交谈改变这些设定。

cat > trainer.md <<'EOF'
You are a strength coach. Each client logs their sessions in this diary.

- Always ask for the numbers: exercise, weight, sets, reps. "I trained today" is not a log --
  ask what they lifted.
- Compare against their recent sessions before responding. If the weight has not moved in
  three weeks, say so.
- If they skipped a session, ask what happened. Once. Then move on.
- No motivational speeches. One line of encouragement, only when the numbers earn it.
- Never give medical advice. Pain goes to a doctor, and say so plainly.
- Reply in the language they wrote in. Two to four sentences.
EOF

3. 生成二维码并分发

pyunto-agent pair --operator "Sano Fitness" --image trainer-qr.png

Written to trainer-qr.png — send this to whoever should be able to reach the
agent. Each person who scans it lets 🤖 Claude into their own diary; the code
names the account asking and nothing else.

将这张图片放在预约页面、欢迎邮件中，或打印在前台的卡片上。它不是机密，也不会过期：同一张图片适用于所有客户。扫描二维码只允许他们发起请求——每位客户都要在自己的手机上批准将其加入自己的日记，并在批准前查看由谁运营。

打印时，或未安装 Pillow 时，请使用 .svg 而不是 .png。

4. 开始回复

pyunto-agent run --backend claude-api --persona trainer.md

启动时，它会列出自己会回复的所有日记，让你知道它已获准进入哪些日记：

Answering in 2 diaries:
  Sano Fitness - Aiko  [2 members, answers every entry]  1552f3dc
  Sano Fitness - Ken   [2 members, answers every entry]  3124f1b8  (cannot read it yet: open this space in the Pyunto app once)

一个进程即可服务所有扫描过二维码的客户。客户写下：

卧推 80kg，5x5，最后一组感觉很吃力

教练会在客户的日记中回复，并参考他们上周举起的重量——通过手机通知，在他们已经使用的应用中送达。

每位客户的日记都彼此独立且采用端到端加密。只有你运行的进程会进行解密；Pyunto 的服务器永远无法看到其中的任何内容。

只是想自己试试？

跳过角色设定，不生成图片直接配对——二维码会显示在终端中，扫描后 Agent 就会开始回复：

pyunto-agent pair --operator "your name"                       # with ANTHROPIC_API_KEY set
pyunto-agent pair --operator "your name" \
  --backend command --command 'claude -p --output-format json'  # or with Claude Code

然后在应用中打开这个空间一次（这会将密钥交给 Agent），并写下一条记录。

它会回复谁，成员会看到什么

• 在只有一个人和 Agent的日记中，它会回复每条记录。
• 在有三名或更多成员（包括 Agent）的日记中，只有在有人提及它的名字，或将记录发送给所有人时，它才会回复。发给其他人的记录不会唤醒它。
• 其他 Agent 或机器人写下的记录，只有提及这个 Agent（@Claude）时它才会回复。它不会回复机器人的报告或其他 Agent 的签到，因此同一本日记中的两个程序绝不会越过其中的人彼此交谈，也不会陷入循环。
• 机器人（pyunto-robotics）的限制更严格：它只会处理人写下的记录，而且只有在记录中提及它的名字时才会执行操作。
• 在应用的参与者列表中，每位成员都能看到谁在运行 Agent（--operator），以及日记在哪里解密（--runtime，默认值为 self_hosted）。

详情

如果 Agent 已经加入某本日记，pair 会告知你并等待：扫描代码，将其添加到另一本日记；或按 Enter 保留当前日记。

添加 --no-run 可生成二维码后退出，方便你稍后自行使用 pyunto-agent run 启动。二维码不包含秘密信息：它会标明发起请求的账号，而是否同意由持有手机的人决定。

如果未设置 PYUNTO_EMAIL，Agent 会使用名为 PYUNTO_AGENT_NAME 的匿名账号（默认为 "Claude"）；设备 ID 和身份密钥存放在 ~/.pyunto-agent/ 中。

不克隆即可安装

如果你只想运行 Agent，而不是参与开发——一行命令，无需克隆：

pip install 'pyunto-agent[qr]'
pyunto-agent pair --operator "your name"

要运行最新的未发布代码：

pip install 'pyunto-agent[qr] @ git+https://github.com/utagoeinc/pyunto-agent'

更详细的指南

• GUIDE.md — 为不常使用终端的人提供完整的分步设置指南。使用 Claude Code（claude -p），而非 API 密钥。
• DEPLOY.md — 在容器中运行 pyunto-agent serve，并让它与服务端一起运行。

从应用中配对

如果 Agent 是由其他人替你设置的，请反向操作：

1. 在 Pyunto 应用中创建或打开共享空间，并生成邀请链接。
2. pyunto-agent join 'pyunto://invite/…'
3. 在应用中打开一次该空间，以便将空间密钥共享给 Agent 的身份密钥。
4. 此时，pyunto-agent whoami 应会针对该空间显示 key=yes。

照片、视频和文档

Agent 会读取人们附上的内容，而不仅仅是他们输入的文字。每张照片、每段视频或每份文档都会下载到你的设备上，解密后存入 ~/.pyunto-agent/attachments/，再展示给模型：

附件	Claude API（claude-api）	Claude Code（command）	http
照片	图片本身	文件路径；Claude Code 会打开图片	路径 + data_base64
视频	4 个间隔均匀的帧（需要 ffmpeg）	文件及其帧	路径 + data_base64
PDF	PDF 本身	文件路径	路径 + data_base64
文本、Markdown、CSV	文本内容	文件路径	路径 + data_base64
Word、Excel、PowerPoint	文本内容（pip install 'pyunto-agent[docs]'）	文件路径	路径 + data_base64

因此，附上文档并询问“你能帮我检查一下语法吗？”，或附上三张照片并询问“你觉得这个花园怎么样？”，都能得到预期的结果。还有一些细节：

• 图片说明会作为紧跟在照片后面的独立条目发送。Agent 会在收到照片后等待几秒，然后将照片和说明一并处理并回复一次。
• 每次回复时，模型只会看到对话串中最新的 4 个附件。
• 使用 Claude Code 时，附件文件夹会自动通过 --add-dir 传入，因此它可以打开这些文件。
• 模型看到的所有内容都会发送给该模型的提供方，与文本的处理方式相同。请告知日记中的参与者。

Agent：使用 Claude API 回复

pyunto-agent run --backend claude-api --persona persona.md   # replies, phone notification
pyunto-agent run --backend claude-api --silent               # replies, no notification
pyunto-agent run --backend claude-api --dry-run                     # log replies, do not post

Agent：让 Claude Code 担任搭档

pyunto-agent run --backend command --command 'claude -p --output-format json'

命令会通过 stdin 接收提示词（包含 persona、对话串及 prompt 的 JSON），并将 stdout 作为回复（{"result": …}、{"reply": …} 或纯文本）。也可以在命令中添加 {prompt}，将提示词作为参数传入。

MCP：将 Pyunto 用作 Claude 的工具

在 官方 MCP Registry 中列为 com.pyunto/diary（Pyunto Diary）。它通过 uv 运行；无需安装 其他内容。

Claude Code

claude mcp add pyunto-diary -- uvx pyunto-agent mcp

Claude Desktop（claude_desktop_config.json）和 Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "pyunto-diary": { "command": "uvx", "args": ["pyunto-agent", "mcp"] }
  }
}

VS Code（.vscode/mcp.json）

{
  "servers": {
    "pyunto-diary": { "type": "stdio", "command": "uvx", "args": ["pyunto-agent", "mcp"] }
  }
}

然后说 “与我的 Pyunto 日记配对”。Claude 会调用 pair 并显示二维码；在应用中扫描二维码，选择一本日记，批准，然后在应用中打开这本日记一次，以便共享密钥。

工具	功能
pair	生成二维码，让用户将此账号添加到自己的某本日记中
whoami、list_spaces、list_members	查看账号、其日记，以及每本日记中的成员（以及任何 Agent 的运行者）
list_threads、read_thread	查看条目，内容在此设备上解密
read_attachment	查看照片（作为图像）、视频（作为帧）或文档（作为文本）
wait_for_message	阻塞等待，直到有人写入内容
post_entry、react、post_sticker、post_list_item	在日记中写入内容
quick_list_stats	统计一段时间内每个快速清单项目的记录次数
join_space	通过应用中生成的邀请链接或代码加入

在 Claude Code 中运行的极简自主循环：

> Use wait_for_message, then reply with post_entry in the same thread. Repeat.

其中两个工具能让日记伙伴说出聊天模型无法说的话。

quick_list_stats 会统计日记在一段时间内追踪的重复事项——服用的药物、读给孩子听的书、餐食、散步。借助它，Agent 可以说“这是本周第三次了”，而不是开口询问。统计结果由你的设备根据解密后的条目汇总：服务端存储的是这些帖子的密文，因此没有任何端点能回答这个问题。

list_members 会列出空间中的其他成员，并说明每个 Agent 由谁运行、运行在哪里。写入任何敏感内容前都应调用它——它会告诉你谁能看到你发布的内容。

搭配 @pyunto/tm-mcp 使用后，伙伴还可以读取并预订用户的日程。

参考

命令	功能	选项
pair	显示二维码；扫描二维码的人会允许 Agent 进入日记。随后回答条目	--operator NAME（向每位成员显示），--runtime self_hosted|hosted|endpoint，--image FILE.png|.svg（将二维码写入文件并退出），--big（显示更大的终端二维码），--no-run（配对后退出），以及 run 选项
run	回答 Agent 所在的每本日记中的条目	--backend claude-api|command|http，--command CMD，--url URL，--model ID，--persona FILE.md，--space ID（可重复；仅限这些日记），--history N（上下文条目数，默认 12），--silent（发布时不发送通知），--dry-run（记录回复，但不发布）
mcp	通过 stdio 为 Claude Code / Claude Desktop 提供 MCP 服务
whoami	显示 Agent 的账户，以及每个空间的 key=yes/no 状态
join LINK	通过应用中生成的邀请链接加入
send SPACE_ID TEXT	发布一条条目	--thread ID，--silent
serve	代表他人运行 Agent 的 HTTP 服务（参见 DEPLOY.md）	--listen HOST:PORT（默认 127.0.0.1:8788），以及 run 选项

后端：claude-api 需要 ANTHROPIC_API_KEY。command 会运行任意程序，将提示词作为 JSON 通过 stdin 传入，并将其 stdout 作为回复（claude -p --output-format json 是 Claude Code）。 http 会将相同的 JSON 通过 POST 发送到 --url。

配置可从环境变量或工作目录中的 .env 文件读取：

变量	含义
ANTHROPIC_API_KEY	用于 --backend claude-api
PYUNTO_EMAIL，PYUNTO_PASSWORD	以注册账户而非匿名账户运行
PYUNTO_AGENT_NAME	匿名账户的显示名称（默认 Claude）
PYUNTO_AGENT_DIR	设备 ID、身份密钥和空间密钥的存放位置（默认 ~/.pyunto-agent）
PYUNTO_BACKEND，PYUNTO_COMMAND，PYUNTO_BACKEND_URL，PYUNTO_MODEL	--backend、--command、--url、--model 的默认值
PYUNTO_PERSONA	--persona 的默认值
PYUNTO_HISTORY	仅用于 serve：上下文条目数（默认 8）
PYUNTO_AGENT_LISTEN，PYUNTO_AGENT_SECRET	仅用于 serve
PYUNTO_BASE_URL	API 服务（默认 https://api.pyunto.com）

各版本的变更记录见 Releases。

说明

• 日记文本会发送到你选择的后端。使用 claude-api 时，文本会发送到 Anthropic 的 API；请告知日记中的成员。
• 默认速率限制：每小时 60 条回复（Bridge(max_replies_per_hour=…)）。
• 只有成员将空间密钥分享给 Agent 后，Agent 才能读取日记；成员打开空间时，应用会执行此操作。如果 whoami 显示 key=no，请在应用中打开该空间。
• 加密方式（包括测试向量）：https://pyunto.com/encryption.html。
• 测试：运行 pip install -e '.[dev]'，然后运行 pytest（包含密封盒测试向量）。

许可证

Apache-2.0。参见 LICENSE。