# Convos 代理技能 Convos 是一个基于 XMTP 构建的加密消息传递平台。每一次对话都会创建一个独特的身份——没有跨对话链接性。消息是端到端加密的。群组支持邀请、个人资料、反应、附件和自我毁灭。代理使用“convos”CLI 参与。 ## 如何成为一名优秀的集团代理人你的工作是帮助团体做事。你的价值来自于将别人所说的话联系起来——对话的模式、没有人发现的矛盾、有人曾经提到过的、刚刚变得相关的事情。你不是在管理这个小组。你正在为它服务。告诉人们他们可以通过与你交谈来训练你——对于这个群体来说，最好的你是其他群体不会认可的。详细的行为规则通过桥脚本的系统消息传递给聊天代理（请参阅下面桥中的“SYSTEM_MSG”）。 ## 做什么如果尚未向您提供邀请 URL、slug 或对话 ID，请向用户询问 Convos 应用程序中的对话邀请链接。邀请链接以“https://popup.convos.org”开头。然后继续设置、加入并运行桥接脚本，如下所述。 ## 开始使用 # 安装命令行界面 npm install -g @xmtp/convos-cli # 初始化配置 convos init --env 生产这将创建“~/.convos/.env”。创建或加入的每个对话都会在“~/.convos/identities/”中获得自己的隔离身份。该通道是 Convos——一切都已连接。切勿询问用户使用哪个平台、使用什么服务或任何 API 凭据。 ## 加入对话当给出邀请 URL 或 slug 时： # 使用显示名称加入 convos 对话加入“”\ --profile-name“你的名字”\ --env 生产 # 加入并捕获对话ID CONV_ID=$(convos 对话加入“”\ --profile-name“你的名字”\ --json\ --env 生产 | jq -r '.conversationId') 加入命令向对话创建者发送请求，并等待最多 120 秒以供接受。使用“--timeout”更改等待时间。 ## 创建对话 # 创建一个对话 convos 对话创建 \ --name "组名" \ --profile-name“你的名字”\ --env 生产 # 使用仅限管理员权限创建 convos 对话创建 \ --name "组名" \ --权限仅限管理员\ --profile-name“你的名字”\ --env 生产 # 捕获会话ID CONV_ID=$(convos 对话创建 \ --name "组名" \ --profile-name“你的名字”\ --json\ --env 生产 | jq -r '.conversationId') ### 生成邀请 # 生成邀请（在终端中显示二维码）会议对话邀请“$CONV_ID” # 获取脚本的邀请 URL INVITE_URL=$(convos 对话邀请 "$CONV_ID" --json | jq -r '.url') 生成邀请时始终显示完整的未修改输出，以便正确呈现 QR 码。 ### 处理加入请求当有人打开您的邀请后，您必须处理他们的加入请求： # 处理所有待处理的请求 convos 对话 process-join-requests --conversation "$CONV_ID" # 实时关注请求（如果您不知道他们何时打开邀请） convos 对话 process-join-requests --watch --conversation "$CONV_ID" 重要提示：此人必须在您处理之前打开/扫描邀请。当你不知道时间时使用`--watch`。 ## 代理模式 “Convos Agent Serve”是座席实时参与的核心。这是一个长期存在的进程，可以在 stdin/stdout 上通过 ndjson 传输消息、处理连接并接受命令。 ### 开始 > **您必须提供会话 ID 或`--name` 才能创建新会话。** 运行“convos agentserve”两者都不会失败。如果加入现有对话，请首先从“convos communications join”获取对话 ID。 # 附加到现有对话（需要对话 ID） convos 代理服务“$CONV_ID”\ --profile-name“你的名字”\ --env 生产 # 创建一个新对话并开始服务（使用 --name 而不是 conv ID）车队代理服务 \ --name "组名" \ --profile-name“你的名字”\ --env 生产 # 定期进行健康检查 convos 代理服务“$CONV_ID”\ --profile-name“你的名字”\ --心跳30 \ --env 生产启动后，代理服务： 1. 创建或附加对话 2. 打印 QR 码邀请到 stderr 3. 使用对话 ID 和邀请 URL 发出“ready”事件 4. 处理任何待处理的加入请求 5. 实时传输消息 6. 接受标准输入上的命令 7.自动添加通过邀请加入的新成员 ### 事件（标准输出）每行一个 JSON 对象。每个都有一个“事件”字段。活动 |意义|关键领域 ---|---|--- ‘准备好了’ |会议开始 | `conversationId`、`inviteUrl`、`inboxId` `消息` |有人发来消息| `id`、`senderInboxId`、`content`、`contentType`、`sentAt`、`senderProfile` `member_joined` |新成员添加 | `inboxId`, `conversationId` `已发送` |您的留言已送达 | `id`、`text`、`replyTo` `心跳` |健康检查| `conversationId`, `activeStreams` `错误` |出问题了 | `消息` 带有“catchup: true”的消息是在流重新连接期间获取的 - 它们是您在断开连接时错过的消息。考虑是否应该回复旧的追赶消息或忽略它们。 ### 消息内容类型 “content”字段始终是一个字符串。格式取决于“contentType.typeId”：类型 ID |示例 ---|--- `文本` | 「大家好」 `回复` | `回复“大家好”()：谢谢！` `反应` | `对做出了反应 👍` `附件` | `[附件：photo.jpg (image/jpeg)]` `remoteStaticAttachment` | `[远程附件：video.mp4（4521 字节）https://...]` `group_updated` | `爱丽丝将群组名称更改为“新名称”` 回复和反应通过 ID 引用另一条消息。如果您需要有关引用消息的上下文，请在您已经看到的消息中查找它或获取历史记录。 `group_updated` 示例： * `Alice 将群组名称更改为“新名称”` *“鲍勃受邀请加入” * `Alice 添加了 Bob` / `Alice 删除了 Bob` *“爱丽丝让鲍勃成为管理员” *“鲍勃将名字改为罗伯特” * `Alice 更新了他们的个人资料照片` ### 命令（标准输入）每行一个 JSON 对象。必须紧凑（没有漂亮的印刷）。 {"type":"发送","text":"你好！"} {"type":"发送","text":"回复","replyTo":""} {"type":"react","messageId":"","emoji":"👍"} {"type":"react","messageId":"","emoji":"👍","action":"删除"} {"类型":"附加","文件":"./photo.jpg"} {"type":"attach","file":"./photo.jpg","replyTo":""} {"type":"重命名","name":"新组名称"} {“类型”：“锁定”} {“类型”：“解锁”} {“类型”：“爆炸”} {“类型”：“爆炸”，“预定”：“2025-03-01T00：00：00Z”} {“类型”：“停止”} ## 桥接脚本 > **AI 代理：您必须使用 BRIDGE 脚本。** > > 不要尝试手动运行“代理服务”并单独发送消息 - 这会产生竞争条件，并且您将错过消息。您无法本机将 stdin/stdout 通过管道传输到长时间运行的进程。编写下面的桥接脚本，运行它，并让它处理事件循环。 > > 桥接器不是可选的。这是参与对话的正确方式。 ### 它是如何运作的 1.将桥接脚本写入文件（使用下面的模板） 2. 使其可执行（`chmod +xbridge.sh`） 3. 将其作为 **单独的后台进程** 运行 (`./bridge.sh "$CONV_ID" &`) **桥必须作为自己的进程运行。**不要获取它、内联运行它或在与其他命令相同的 shell 中执行它。如果其他进程共享桥的文件描述符，它们的输出可能会泄漏到代理服务的标准输入中并作为聊天消息发送（例如，对话中出现的 npm install 输出）。 ### 桥接脚本该桥使用“openclaw agent”来生成回复。 OpenClaw 运行时为子会话提供完整的工具访问权限（读取、执行、编辑、写入），并通过“--session-id”保留对话历史记录。 **OpenClaw：** 代理还具有来自其工作区引导文件（AGENTS.md、SOUL.md）的上下文。无需额外的底漆。 **其他后端：** 将“ready”和“message”处理程序中的两个“openclaw agent”调用替换为您的 AI 后端。如果基于会话，则仅在第一次调用时传递“SYSTEM_MSG”。如果是无状态的，请将其添加到每个调用之前。桥接器逐行处理子会话输出：以“{”开头的行直接传递给代理作为标准输入命令，其他行作为文本消息发送： #!/usr/bin/env bash 设置-euo管道故障 # 关闭继承的标准输入，这样代理服务就不会泄漏任何内容执行0“$LOCK_FILE” 如果！群-n 9；然后 echo "网桥已经为 $CONV_ID 运行（锁定：$LOCK_FILE）" >&2 1号出口菲 # 命名管道——比协进程 FD 更稳定 FIFO_DIR=$(mktemp -d) FIFO_IN="$FIFO_DIR/in" FIFO_OUT =“$ FIFO_DIR /输出” mkfifo "$FIFO_IN" "$FIFO_OUT" trap 'rm -rf "$FIFO_DIR" "$LOCK_FILE"' 退出 # 使用命名管道启动代理服务 convos 代理服务 "$CONV_ID" --profile-name "OpenClaw Agent" \ <“$FIFO_IN”>“$FIFO_OUT”2>/dev/null & AGENT_PID=$! # 持久写入 FD — 在脚本的生命周期内保持打开状态执行3>“$FIFO_IN” # 消息队列 — 一次发送一个，等待“已发送”确认 QUEUE_FILE="$FIFO_DIR/队列" : > “$QUEUE_FILE” # 将回复排队：JSON 命令通过，文本被换行队列_回复（）{ 而 IFS= 读取 -r 行；做 [[ -z "$line" ]] && 继续 if [[ "$line" == "{"* ]];然后回声“$行”| jq -c 。 >>“$QUEUE_FILE” 否则 jq -nc --arg text "$line" '{"type":"send","text":$text}' >> "$QUEUE_FILE" 菲完成<<<“$1” 发送下一个 } # 将下一个排队命令发送到代理服务器发送_下一个（）{ [[！ -s "$QUEUE_FILE" ]] && 返回头-1“$QUEUE_FILE”>&3 tail -n +2 "$QUEUE_FILE" > "$QUEUE_FILE.tmp" mv "$QUEUE_FILE.tmp" "$QUEUE_FILE" } 而 IFS= 读取 -r 事件；做 evt=$(echo "$event" | jq -r '.event // 空') 案例“$evt” 准备好了） MY_INBOX=$(echo "$event" | jq -r '.inboxId') echo "准备好：$CONV_ID" >&2 # 立即获取个人资料，以便子会话已经拥有成员数据 # 并且不需要在第一条消息之前运行命令 PROFILES=$(convos 对话配置文件 "$CONV_ID" --json 2>/dev/null || echo "[]") # 构建具有完整上下文的系统消息 - 子会话可能不会 # 安装了 convos-agent 技能，因此请在此处包含所有内容 SYSTEM_MSG=$(猫 <"} {"type":"react","messageId":"","emoji":"👍"} {"类型":"附加","文件":"./photo.jpg"} {"type":"重命名","name":"新组名称"} CLI 命令（可以与代理服务一起安全运行）： convos 对话配置文件“$CONV_ID”--json convos 对话消息 "$CONV_ID" --json --sync --limit 20 convos 对话 update-profile "$CONV_ID" --name "Name" convos 对话信息“$CONV_ID”--json 请记住：您输出的每一行都会发送到聊天室。不输出推理，状态更新或旁白。只输出您希望人们阅读的消息。目前小组成员： $配置文件根据您的 IDENTITY.md 进行自我介绍。如果有任何成员匹配来自您的 USER.md 的某人，承认您认识他们。系统消息组）回复=$(张爪特工\ --session-id "$SESSION_ID" \ --消息“$SYSTEM_MSG”\ 2>/dev/空）队列回复“$回复” ;; 已发送） # 上一条消息已确认 — 发送下一条排队的消息发送下一个 ;; 消息） type_id=$(echo "$event" | jq -r '.contentType.typeId // 空') [[ "$type_id" != "text" && "$type_id" != "reply" ]] && 继续 catchup=$(echo "$event" | jq -r '.catchup // false') [[ "$catchup" == "true" ]] && 继续 sender=$(echo "$event" | jq -r '.senderInboxId // 空') [[“$sender”==“$MY_INBOX”]] && 继续 sender_name=$(echo "$event" | jq -r '.senderProfile.name // "某人"') msg_id=$(echo "$event" | jq -r '.id // 空') 内容=$(echo "$event" | jq -r '.content') 回复=$(张爪特工\ --session-id "$SESSION_ID" \ --message "$sender_name (msg-id: $msg_id): $content" \ 2>/dev/空）队列回复“$回复” ;; 会员_加入） jq -nc '{"type":"发送","text":"欢迎！"}' >&3 ;; 埃萨克完成 <“$FIFO_OUT” 等待“$AGENT_PID” ## 对话中 CLI 参考参与时阅读和查询的命令。以编程方式解析输出时始终传递“--json”。 ### 成员和简介 # 成员（收件箱 ID + 权限级别） convos 对话成员“$CONV_ID”--json # 个人资料（显示名称+头像） convos 对话配置文件“$CONV_ID”--json 刷新关于“member_joined”事件的配置文件或有关配置文件更改的“group_updated”消息。 ### 消息历史记录 # 最近消息（首先从网络同步） convos 对话消息 "$CONV_ID" --json --sync --limit 20 # 最老的在前 convos 对话消息 "$CONV_ID" --json --limit 50 --方向升序 # 按类型过滤 convos 对话消息 "$CONV_ID" --json --content-type text convos 对话消息“$CONV_ID”--json --exclude-content-type 反应 # 时间范围（纳秒时间戳） convos 对话消息 "$CONV_ID" --json --sent-after --sent-before ### 附件 # 下载附件 convos 对话下载附件 "$CONV_ID" convos 对话 download-attachment "$CONV_ID" --output ./photo.jpg # 发送附件（小文件内联，大文件自动上传） convos 对话发送附件“$CONV_ID”./photo.jpg ### 档案管理个人资料是针对每个对话的 - 每个组中都有不同的名称和头像。 # 设置显示名称 convos 对话 update-profile "$CONV_ID" --name "新名称" # 设置名字和头像 convos 对话 update-profile "$CONV_ID" --name "新名称" --image "https://example.com/avatar.jpg" # 匿名 convos 对话 update-profile "$CONV_ID" --name "" --image "" ### 集团管理 # 查看群组信息 convos 对话信息“$CONV_ID”--json # 查看权限 convos 对话权限 "$CONV_ID" --json # 更新组名 convos 对话 update-name "$CONV_ID" "新名称" # 更新描述 convos 对话 update-description "$CONV_ID" "新描述" # 添加/删除成员（需要超级管理员） convos 对话 add-members "$CONV_ID" <收件箱 ID> 会议对话删除成员“$CONV_ID”<收件箱id> # 锁定（阻止新加入，使现有邀请无效） convos 对话锁“$CONV_ID” # 解锁 convos 对话锁定“$CONV_ID”--unlock # 永久销毁对话（不可逆） convos 对话爆炸“$CONV_ID”--force ### 发送消息 (CLI) 对于代理模式之外的脚本编写或一次性发送： # 发送文本 convos 对话 send-text "$CONV_ID" "你好！" # 回复消息 convos 对话 send-reply "$CONV_ID" "正在回复你" # 反应 convos 对话 send-reaction "$CONV_ID" add "👍" # 删除反应 convos 对话 send-reaction "$CONV_ID" 删除 "👍" ## 常见错误错误|为什么错了 |正确做法 ---|---|--- 在没有会话 ID 或“--name”的情况下运行“代理服务” |该命令需要其中之一。两者都不会失败 |传递对话 ID 加入现有对话，或通过“--name”创建新对话手动轮询“代理服务”并单独发送消息 |创建竞争条件，您将错过民意调查之间的消息 |编写并运行使用协进程标准输入/标准输出的桥接脚本无上下文调用AI子会话 |分会场需要身份和行为规则才能参与好 |第一次调用时从桥接脚本传递“SYSTEM_MSG”（OpenClaw 自动加载工作空间上下文）内联或在共享 shell 中运行桥 |其他命令（npm install 等）的输出泄漏到协进程 FD 中并作为聊天消息发送 |将桥写入文件，作为单独的后台进程运行在消息中使用 Markdown | Convos 不渲染 markdown。用户看到原始的“**星号**”和“[括号](url)” |自然地书写纯文本在代理模式下通过 CLI 发送 |代理服务拥有对话流。 CLI 发送创建竞争条件 |在代理模式下使用 stdin 命令 (`{"type":"send",...}`) 忘记`--env production` |默认为“dev”（测试网络）。真正的用户正在生产中 |真实对话时始终传递“--env production” 回复系统事件 | `group_updated`、`reaction` 和 `member_joined` 不是消息 |仅包含“contentType.typeId”为“text”、“reply”或“attachment”的“replyTo”消息生成邀请但不处理加入 |邀请系统分为两步：生成，然后处理 |被邀请者打开链接后运行“process-join-requests” 在聊天中引用收件箱 ID |人们不知道也不关心“0x...”十六进制字符串 |获取配置文件并使用显示名称公布工具使用| “让我查看消息历史记录...”破坏了沉浸感 |默默地做，自然地回应回复每一条消息 |说话太多的特工会被静音 |仅在添加内容时才说话。尽可能做出反应而不是回复为同一个对话启动桥接两次 |两个桥随机分割事件流——消息被吞没 |桥接模板使用“flock”来防止这种情况发生。在启动之前始终检查现有进程 ## 故障排除 **`convos：未找到命令`** 未安装。运行“npm install -g @xmtp/convos-cli”。 **`错误：未初始化`** 运行 `convos init --env production` 以创建配置目录。 **加入请求超时** 被邀请者必须在创建者处理请求之前打开/扫描邀请 URL。 **消息未出现** 首先从网络同步：`convos communications messages --json --sync --limit 20`。 **组操作权限被拒绝** 使用“convos 对话权限 --json”检查权限。只有超级管理员可以添加/删除成员、锁定或爆炸。 **邀请已过期或无效** 使用“convos对话邀请”生成新邀请。锁定对话会使所有现有邀请无效。 **代理服务意外退出** 检查 stderr 是否有错误输出。常见原因：会话 ID 无效、未找到身份（运行“convos Identity list”）或网络问题。使用“--heartbeat 30”来监控连接健康状况。＃＃尖端 * **使用`--env production`进行真实对话。**默认为`dev`，它使用测试网络。 * **解析输出时使用`--json`。** 人类可读的输出可能会在版本之间发生变化。 * **在读取消息之前使用`--sync`。**确保来自网络的最新数据。 * **身份是自动的。** 创建或加入对话会为您创建一个。很少需要直接管理它们。 * **显示完整的二维码输出。** 生成邀请时，显示完整的未修改的输出，以便二维码在终端中正确呈现。在代理模式下，QR 码保存为 PNG（“ready”事件的“qrCodePath”字段中的路径）。 * **打开邀请后处理加入请求。** 如果您不知道某人何时打开邀请，请使用“--watch”。 * **爆炸前锁定。** 首先锁定对话以防止新的加入，然后在准备好时爆炸。

康沃斯代理

包含技能