claude-to-im

Claude-to-IM Plus Bridge Skill

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

技能目录（SKILL_DIR）位于 ~/.claude/skills/claude-to-im。 在 Codex 安装中，它也可能位于 ~/.codex/skills/claude-to-im。 如果这两个路径都不存在，请使用 Glob，匹配模式 **/skills/**/claude-to-im/SKILL.md 或 **/skills/**/claude-to-im-plus/SKILL.md，并根据结果推导根目录。

命令解析

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

用户表述（示例）	子命令
setup、configure、配置、我想在飞书上用 Claude、帮我连接 Telegram、帮我接微信、帮我接钉钉	setup
start、start bridge、启动、启动桥接	start
stop、stop bridge、停止、停止桥接	stop
status、bridge status、状态、运行状态、怎么看桥接的运行状态	status
logs、logs 200、查看日志、查看日志 200	logs
handoff weixin、handoff dingtalk、把当前会话切到微信、把当前会话切到钉钉、把当前 Codex 会话切到微信、把当前 Claude 会话切到钉钉	handoff
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. Claude Code — 有 AskUserQuestion 工具可用。使用该工具进行交互式设置向导。
2. Codex / 其他环境 — 无法使用 AskUserQuestion。改为提供非交互式指导：说明步骤、展示 SKILL_DIR/config.env.example，并请用户手动创建 ~/.claude-to-im/config.env。

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

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

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

• 如果不存在：
  • 在 Claude Code 中：告知用户“未找到配置”，并自动使用 AskUserQuestion 启动 setup 向导。
  • 在 Codex 中：告知用户“未找到配置。请根据示例创建 ~/.claude-to-im/config.env：”，然后展示 SKILL_DIR/config.env.example 的内容并停止。不要尝试启动守护进程——没有 config.env 时，进程会在启动时崩溃，并留下过时的 PID 文件，阻止后续启动。
• 如果存在： 继续执行所请求的子命令。

子命令

setup

运行交互式设置向导。此子命令需要 AskUserQuestion。如果该工具不可用（Codex 环境），则改为展示 SKILL_DIR/config.env.example 的内容，逐字段解释，并指导用户手动创建配置文件。

如果 AskUserQuestion 可用，则一次只收集一个字段。每次用户回答后，都要先向用户确认该值（密钥仅显示最后 4 个字符），再提出下一个问题。

步骤 1 — 选择渠道 询问要启用哪些频道（telegram、discord、feishu、qq、weixin、dingtalk）。接受逗号分隔的输入。简要介绍各个频道：

• telegram — 最适合个人使用。支持流式预览和内联权限按钮。
• discord — 适合团队使用。支持服务器、频道和用户级访问控制。
• feishu（Lark）— 适用于飞书/Lark 团队。支持流式卡片、工具进度和内联权限按钮。
• qq — 仅支持 QQ C2C 私聊。不支持内联权限按钮和流式预览。权限通过文本命令 /perm ... 管理。
• weixin — 使用微信二维码登录。仅支持关联一个账号；新的登录会替换之前的账号。不支持内联权限按钮和流式预览。权限通过文本命令 /perm ... 或快捷回复 1/2/3 管理。语音消息仅使用微信自带的语音转文字结果；桥接程序不会转录原始语音。
• dingtalk — 钉钉 Stream 模式。支持私聊和群聊；v1 仅处理群聊中的 @bot 消息或回复 bot 的消息。仅支持纯文本回复，但可以将收到的图片转发给 Claude/Codex。

步骤 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) 运行 /claude-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/open 找到
  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. 辅助程序会写入 ~/.claude-to-im/runtime/weixin-login.html，并尝试在本地浏览器中自动打开。
  4. 如果无法自动打开，告知用户手动打开该 HTML 文件，并使用 WeChat 扫描二维码。
  5. 等待辅助程序报告成功，然后确认已关联的账号已保存到本地。
  • 简要说明：已关联的 Weixin 账号存储在 ~/.claude-to-im/data/weixin-accounts.json 中。再次运行辅助程序会替换之前关联的账号。
  • 简要说明：CTI_WEIXIN_MEDIA_ENABLED 仅控制入站图像/文件/视频的下载。对于语音消息，桥接服务只接受 WeChat 内置语音转文本功能返回的文本。如果 WeChat 未提供转录文本，桥接服务会返回错误，而不会下载/转录原始音频。
• DingTalk：
  1. 询问 DingTalk App Key
  2. 询问 DingTalk App Secret
  3. 告知用户在 DingTalk 内部应用中启用 Bot 和 Stream mode
  4. 简要说明：群聊仅处理 @bot 或回复机器人消息；v1 回复仅支持纯文本；入站图像可以转发给 Claude/Codex

步骤 3 — 常规设置 询问运行时、默认工作目录、模型和模式：

• 运行时：claude（默认）、codex、auto
  • claude — 使用 Claude Code CLI + Claude Agent SDK（需要安装 claude CLI）
  • codex — 使用 OpenAI Codex SDK（需要 codex CLI；通过 codex auth login 或 OPENAI_API_KEY 进行身份验证）
  • auto — 优先尝试 Claude；如果找不到 Claude CLI，则回退到 Codex
• 工作目录：默认值为 $CWD
• 模型（可选）：留空以继承运行时自身的默认模型。如果用户想要覆盖默认模型，请让其输入模型名称。不要硬编码或推荐特定模型名称——可用模型会随时间变化。
• 模式：code（默认）、plan、ask

步骤 4 — 写入配置并验证

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

start

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

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

向用户显示输出。如果运行失败，告知用户：

• 运行 doctor 进行诊断：/claude-to-im doctor
• 查看最近的日志：/claude-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

handoff

使用此功能重新绑定微信或钉钉，让后续消息继续发送到当前 Codex 或 Claude Code 会话。

公开的 handoff 命令：

• handoff weixin
• handoff dingtalk

运行：

• bash "SKILL_DIR/scripts/handoff.sh" weixin
• bash "SKILL_DIR/scripts/handoff.sh" dingtalk

行为：

• 如果存在 CODEX_THREAD_ID，则将当前会话视为 Codex 会话，并 handoff 到该线程
• 否则，按 CLAUDE_SESSION_ID → CMUX_CLAUDE_PID → 当前 cwd 下的 Claude 活跃会话的顺序检测当前 Claude Code 会话，并优先选择最近活跃的同 cwd 会话
• 成功后，自动将全局 CTI_RUNTIME 切换为检测到的运行时（codex 或 claude）
• 如果目标频道尚无绑定，告知用户先从目标聊天至少发送一条消息
• 如果目标频道存在多个绑定，不要猜测；告知用户目前此简化版 handoff 仅支持每个频道对应一个目标聊天
• 此辅助程序会创建一个全新的本地桥接会话，并保留旧会话和消息文件
• 写入绑定后，handoff 始终会启动桥接，以便新目标聊天立即可用
• 重启桥接会丢弃待处理的权限请求
• Handoff 仅影响该频道的后续消息；不会迁移已在流式传输中的回复
• 在 Codex 运行时中，桥接子进程默认禁用 Codex 响应 WebSocket，以提高代理环境下的可靠性。只有在需要 Codex 的默认 WebSocket 传输方式时，才设置 CTI_CODEX_DISABLE_WEBSOCKETS=false。
• 对于代理环境，告知用户直接在 ~/.claude-to-im/config.env 中填写 export HTTPS_PROXY=...、export HTTP_PROXY=...、export ALL_PROXY=...，以及可选的 export NO_PROXY=...。桥接会将大写和小写的代理变量转发给守护进程以及 Claude/Codex 子进程；不要依赖 ~/.zshrc 等交互式 shell 启动文件来配置后台守护进程。

已移除的命令：

• handoff projects
• handoff threads ...
• handoff claude ...

如果用户询问这些命令，告知他们这些命令已移除，请在当前对话中使用 handoff weixin 或 handoff dingtalk。

⚠️ Claude 恢复会话的限制（v1）： 桥接中恢复的 Claude 会话不会继承原 Claude Code 窗口中的 --settings、--permission-mode、沙盒标记或额外允许的目录（--add-dir）。桥接仅使用自身 config.env 中提供的设置（CTI_DEFAULT_MODE、CTI_ENV_ISOLATION、CTI_AUTO_APPROVE 等）。请明确告知用户：“恢复的会话的工具权限和允许访问的目录可能与原 Claude Code 窗口不同。”

reconfigure

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

如果用户想在 reconfigure 期间切换微信账号，请再次运行 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 语音消息提示缺少语音转文字功能 → 启用 WeChat 自带的语音转文字功能并重新发送；桥接程序不会自行转录原始语音音频

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

Feishu 升级说明： 如果用户从旧版此技能升级后，Feishu 返回权限错误（例如，流式卡片无法使用、输入状态指示器失效、权限按钮无响应），根本原因几乎肯定是 Feishu 后端缺少权限或回调。请用户参考 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）。
• 配置保存在 ~/.claude-to-im/config.env，并会跨会话保留。