link-to-im

Link-to-IM 桥接技能

你正在管理 Link-to-IM 桥接。 用户数据存储在 ~/.link-to-im/。

前置步骤 — 检查更新

处理任何子命令之前，每个会话静默执行一次此检查：

_UPD=$("SKILL_DIR/node_modules/.bin/update-kit" quick-check --cwd "SKILL_DIR" --json 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true

（将 SKILL_DIR 替换为下文找到的实际技能目录路径。）

• 如果输出包含 "status":"upgrade_available"：告知用户“Link-to-IM v{candidateVersion} 可用（当前 v{currentVersion}）。要现在升级吗？”，并主动提出运行 "SKILL_DIR/node_modules/.bin/update-kit" apply --cwd "SKILL_DIR" --decision update_once。
• 如果输出包含 "status":"just_upgraded"：告知用户“已升级到最新版本！”
• 否则：静默继续。

---

首先，通过查找此 SKILL.md 文件来定位技能目录：

• 使用 Glob 和模式 **/skills/**/link-to-im/SKILL.md 查找其路径，然后据此确定技能根目录。
• 在后续所有文件引用中，将该路径记作 SKILL_DIR。

命令解析

将用户的意图从 $ARGUMENTS 解析为以下子命令之一：

用户说法（示例）	子命令
setup、configure、配置、我想在飞书上用 Link、帮我连接 Telegram、帮我接微信	setup
start、start bridge、启动、启动桥接	start
stop、stop bridge、停止、停止桥接	stop
status、bridge status、状态、运行状态、怎么看桥接的运行状态	status
logs、logs 200、查看日志、查看日志 200	logs
reconfigure、修改配置、帮我改一下 token、换个 bot	reconfigure
doctor、diagnose、诊断、挂了、没反应了、bot 没反应、出问题了	doctor

消歧：status 与 doctor — 用户只是想确认桥接是否正在运行（查询信息）时，使用 status。用户报告问题或怀疑某处故障（诊断）时，使用 doctor。无法确定时，如果用户描述了症状（例如“没反应了”“挂了”），优先使用 doctor。

提取 logs 的可选数字参数（默认值为 50）。

向用户索取任何平台凭据之前，先在内部阅读 SKILL_DIR/references/setup-guides.md，了解每种凭据的获取位置。不要一开始就把完整指南发给用户，只提及他们接下来需要执行的具体步骤（例如：“前往 https://open.feishu.cn → 你的应用 → 凭据，查找 App ID”）。如果用户表示不知道如何操作，再展示指南中的相关部分。

运行环境检测

执行任何子命令之前，先检测当前运行环境：

1. 交互式技能宿主 — AskUserQuestion 工具可用。使用它进行交互式设置向导。
2. 非交互式宿主 — AskUserQuestion 不可用。改为提供非交互式指导：说明操作步骤，展示 SKILL_DIR/config.env.example，并请用户手动创建 ~/.link-to-im/config.env。

可通过检查可用工具列表中是否包含 AskUserQuestion 来进行检测。

配置检查（适用于 start、stop、status、logs、reconfigure、doctor）

运行除 setup 以外的任何子命令之前，检查 ~/.link-to-im/config.env 是否存在：

• 如果不存在：
  • 在交互式宿主中：告知用户“No configuration found”，并使用 AskUserQuestion 自动启动 setup 向导。
  • 在非交互式宿主中：告知用户“No configuration found. Please create ~/.link-to-im/config.env based on the example:”，然后展示 SKILL_DIR/config.env.example 的内容并停止。不要尝试启动守护进程——没有 config.env 时，进程会在启动时崩溃，并留下过期的 PID 文件，导致后续启动受阻。
• **如果存在：**继续执行用户请求的子命令。

子命令

setup

运行交互式设置向导。此子命令需要 AskUserQuestion。如果该工具不可用，则展示 SKILL_DIR/config.env.example 的内容，逐项解释字段，并指导用户手动创建配置文件。 当 AskUserQuestion 可用时，请一次收集一个字段。每次收到回答后，在继续下一个问题之前，先向用户确认该值（密钥仅显示最后 4 个字符，其余部分隐藏）。

步骤 1 — 选择渠道

询问要启用哪些渠道（telegram、discord、feishu、qq、weixin）。接受逗号分隔的输入。简要介绍每个渠道：

• telegram — 最适合个人使用。支持流式预览和内嵌权限按钮。
• discord — 适合团队使用。支持服务器／频道／用户级访问控制。
• feishu（Lark）— 面向 Feishu／Lark 团队。支持流式卡片、工具进度和内嵌权限按钮。
• qq — 仅支持 QQ C2C 私聊。不支持内嵌权限按钮或流式预览。权限通过文本 /perm ... 命令管理。
• weixin — 通过微信二维码登录。仅支持一个已关联账号；新登录会替换之前的账号。不支持内嵌权限按钮或流式预览。权限通过文本 /perm ... 命令或快捷回复 1/2/3 管理。语音消息仅使用微信自身的语音转文字文本；桥接程序不会转录原始语音。

步骤 2 — 收集各渠道的令牌

对每个已启用的渠道，每次收集一项凭据。用一句话告知用户在哪里查找每项值。只有当用户请求帮助或表示不知道如何查找时，才显示完整指南部分（来自 SKILL_DIR/references/setup-guides.md）：

• Telegram：Bot Token → 确认（已遮蔽）→ Chat ID（如何获取请参阅指南）→ 确认 → Allowed User IDs（可选）。**重要：**必须设置 Chat ID 或 Allowed User IDs 中的至少一项，否则机器人会拒绝所有消息。
• Discord：Bot Token → 确认（已遮蔽）→ Allowed User IDs → Allowed Channel IDs（可选）→ Allowed Guild IDs（可选）。**重要：**必须设置 Allowed User IDs 或 Allowed Channel IDs 中的至少一项，否则机器人会拒绝所有消息（默认拒绝）。
• Feishu：App ID → 确认 → App Secret → 确认（已遮蔽）→ Domain（可选）→ Allowed User IDs（可选）。收集完凭据后，说明用户需要完成的两阶段设置：
  • 阶段 1（启动桥接程序前）：(A) 批量添加权限；(B) 启用机器人能力；(C) 发布第一个版本并由管理员审批。完成后，权限和机器人即会生效。
  • 阶段 2（需要运行桥接程序）：(D) 运行 /agent-to-im start；(E) 将事件 (im.message.receive_v1) 和回调 (card.action.trigger) 配置为长连接模式；(F) 发布第二个版本并由管理员审批。
  • **为什么分为两个阶段：**保存事件订阅时，Feishu 会验证 WebSocket 连接。如果桥接程序未运行，保存操作会失败。桥接程序需要已发布的权限才能连接。
  • 简要列出步骤；只有用户提出要求时才展示完整指南。
• QQ：先收集两个必填字段，再收集可选字段：
  1. QQ App ID（必填）→ 确认
  2. QQ App Secret（必填）→ 确认（已遮蔽）
  • 告知用户：这两个值可在 https://q.qq.com/qqbot/openclaw 查找。
  3. Allowed User OpenIDs（可选，按 Enter 跳过）——注意：这是 user_openid，不是 QQ 号码。如果用户还没有 openid，可以留空。
  4. Image Enabled（可选，默认值为 true，按 Enter 跳过）——如果底层服务提供方不支持图像输入，请设为 false。
  5. Max Image Size MB（可选，默认值为 20，按 Enter 跳过）
  • 提醒用户：QQ 首个版本仅支持 C2C 私聊沙箱访问。不支持群聊/频道、行内按钮或流式预览。
• Weixin：不要询问静态令牌，而是：
  1. 告知用户，此频道使用二维码登录，而非手动输入凭据。
  2. 运行 cd SKILL_DIR && npm run weixin:login
  3. 辅助程序会写入 ~/.agent-to-im/runtime/weixin-login.html，并尝试在本地浏览器中自动打开。
  4. 如果自动打开失败，告知用户手动打开该 HTML 文件，并使用 WeChat 扫描二维码。
  5. 等待辅助程序报告成功，然后确认关联账户已保存到本地。
  • 简要说明：关联的 Weixin 账户存储在 ~/.agent-to-im/data/weixin-accounts.json 中。再次运行辅助程序会替换之前关联的账户。
  • 简要说明：CTI_WEIXIN_MEDIA_ENABLED 仅控制传入图像、文件和视频的下载。对于语音消息，桥接程序只接受 WeChat 内置语音转文本功能返回的文本。如果 WeChat 未提供转写文本，桥接程序会返回错误，而不会下载或转写原始音频。

步骤 3 — 常规设置

询问运行时、默认工作目录、模型和模式：

• 运行时：claude、codex、gemini、auto
  • claude — 使用 Claude CLI + Claude Agent SDK
  • codex — 使用 OpenAI Codex SDK
  • gemini — 使用 Gemini CLI
  • auto — 优先尝试 Gemini，然后尝试 Claude；必要时回退到 Codex
• 工作目录：默认值为 $CWD
• 模型（可选）：留空以使用运行时自身的默认模型。如果用户想要覆盖默认值，请让他们输入模型名称。不要硬编码或推荐特定模型名称——可用模型会随时间变化。
• 模式：code（默认）、plan、ask

步骤 4 — 写入配置并验证

1. 显示包含所有设置的最终摘要表（密钥仅显示最后 4 个字符）
2. 写入前询问用户是否确认
3. 使用 Bash 创建目录结构：mkdir -p ~/.link-to-im/{data,logs,runtime,data/messages}
4. 使用 Write 创建 ~/.link-to-im/config.env，包含所有采用 KEY=VALUE 格式的设置
5. 使用 Bash 设置权限：chmod 600 ~/.link-to-im/config.env
6. 验证令牌——读取 SKILL_DIR/references/token-validation.md，查看各平台的准确命令和预期响应。这样可以在用户尝试启动守护进程前发现拼写错误和凭据错误。对于 Weixin，成功扫码登录即视为验证通过。
7. 使用摘要表报告结果。如果任何验证失败，说明可能的问题及修复方法。
8. 成功后，告知用户：“设置完成！运行 /link-to-im start 启动桥接服务。”

start

预检查： 确认 ~/.link-to-im/config.env 存在（参见上文“配置检查”）。如果该文件不存在，守护进程会立即崩溃，并留下过期的 PID 文件。

运行：bash "SKILL_DIR/scripts/daemon.sh" start

向用户展示输出。如果启动失败，告知用户：

• 运行 doctor 进行诊断：/link-to-im doctor
• 查看最近的日志：/link-to-im logs

stop

运行：bash "SKILL_DIR/scripts/daemon.sh" stop

status

运行：bash "SKILL_DIR/scripts/daemon.sh" status

logs

从参数中提取可选的行数 N（默认值为 50）。 运行：bash "SKILL_DIR/scripts/daemon.sh" logs N

reconfigure

1. 从 ~/.link-to-im/config.env 读取当前配置
2. 以清晰的表格格式显示当前设置，所有密钥均需遮蔽（仅显示最后 4 个字符）
3. 使用 AskUserQuestion 询问用户要更改哪些内容
4. 收集新值时，告知用户在哪里可以找到该值；只有在用户寻求帮助时，才显示 SKILL_DIR/references/setup-guides.md 中的完整指南
5. 以原子方式更新配置文件（写入临时文件，然后重命名）
6. 重新验证所有已更改的令牌
7. 提醒用户：“运行 /link-to-im stop，然后运行 /link-to-im start 以应用更改。”

如果用户想在 reconfigure 期间切换 Weixin 账号，请再次运行 cd SKILL_DIR && npm run weixin:login。每次成功扫码都会替换之前关联的本地账号。

doctor

运行：bash "SKILL_DIR/scripts/doctor.sh"

展示结果，并针对任何故障提出修复建议。常见修复方法：

• 缺少 SDK cli.js → cd SKILL_DIR && npm install
• dist/daemon.mjs 已过期 → cd SKILL_DIR && npm run build
• 缺少配置 → 运行 setup
• 缺少 Weixin 账号或账号已过期 → cd SKILL_DIR && npm run weixin:login
• Weixin 语音消息提示缺少语音转文字功能 → 启用微信自带的语音转文字功能并重新发送；桥接服务不会自行转写原始语音音频

对于更复杂的问题（未收到消息、权限超时、内存占用过高、PID 文件过期），请阅读 SKILL_DIR/references/troubleshooting.md，了解详细的诊断步骤。

自我修复协议（UDD）

当 doctor 发现未解决的问题，或桥接运行期间发生错误时，请使用 UDD 自我修复流程。始终在子 Agent 中运行 UDD 命令——切勿在主 Agent 上下文中运行。

1. 检查上游是否已修复：

   cd "SKILL_DIR" && "SKILL_DIR/node_modules/.bin/udd" check --json
   

   如果存在 upstreamFixMatch，且置信度为中或高，请优先建议更新。

2. 分析错误：

   cd "SKILL_DIR" && "SKILL_DIR/node_modules/.bin/udd" analyze --error "<error message>" --json
   

   报告 diagnosis.kind 和建议的策略。

3. 如果用户批准修复：

   cd "SKILL_DIR" && "SKILL_DIR/node_modules/.bin/udd" heal --error "<error message>" --decision repair_once --json
   

   此操作会在隔离的 git worktree 中运行。如果验证通过，修复即可供审核。

4. 如果修复失败，起草 issue：

   cd "SKILL_DIR" && "SKILL_DIR/node_modules/.bin/udd" issue-draft --error "<error message>" --out ./issue-draft.md
   

   提交前先将草稿交由用户审核。

UDD 规则：切勿修改 SKILL_DIR 以外的文件。切勿直接提交到 main。如果缺少 udd.config.json，请告知用户。遵守 .env 和 protectedPaths 中的路径设置。

**飞书升级说明：**如果用户从此技能的旧版本升级后，飞书出现权限错误（例如流式卡片无法使用、输入状态指示器失效、权限按钮无响应），根本原因几乎可以肯定是飞书后端缺少权限或回调。请让用户参阅 SKILL_DIR/references/setup-guides.md 中的“从先前版本升级”部分——他们需要添加新的权限范围（cardkit:card:write、cardkit:card:read、im:message:update、im:message.reactions:read、im:message.reactions:write_only），添加 card.action.trigger 回调，并重新发布应用。升级需要分两轮发布，因为添加回调需要 WebSocket 连接处于活动状态（桥接必须正在运行）。

说明

• 始终在输出中遮蔽机密（仅显示末尾 4 个字符）——用户经常在错误报告中分享终端输出，因此令牌泄露会造成安全事故。
• 启动守护进程前始终检查是否存在 config.env——如果没有该文件，进程会在启动时崩溃，并留下过期的 PID 文件，阻止后续启动（需要手动清理）。
• 守护进程作为后台 Node.js 进程运行，由平台监管程序管理（macOS 上为 launchd，Linux 上为 setsid，Windows 上为 WinSW/NSSM）。
• 配置保存在 ~/.link-to-im/config.env，可跨会话保留。