Skip to content

docs(cases): bind Telegram to existing node — claude-code-cli walkthrough (refs #14)#24

Open
s2agi wants to merge 1 commit into
mainfrom
feat/telegram-cli-bind-impl
Open

docs(cases): bind Telegram to existing node — claude-code-cli walkthrough (refs #14)#24
s2agi wants to merge 1 commit into
mainfrom
feat/telegram-cli-bind-impl

Conversation

@s2agi
Copy link
Copy Markdown
Contributor

@s2agi s2agi commented May 12, 2026

Why

Refs #14

issue #14 要求"对已经存在的节点用 anet 命令绑定 Telegram,优先 claude-code-cli"。本 PR 只处理 claude-code-cli runtime 路径(issue #14 的 P0 子集),不涉及 SDK 两个 runtime(那部分在 PR #20 RFC-002 Phase 1 设计中,targeting v0.9+)。

调研发现命令路径已实现

  • anet channel add telegram <node-id> --bot-token <tok> --allow <user-id> (agent-network/bin/cli.ts:2570)
  • spawn 注入 --channels plugin:telegram@claude-plugins-official + TELEGRAM_STATE_DIR env (cli.ts:1636-1648)
  • 落盘 ~/.anet/nodes/<id>/channels/telegram/{access.json, .env, inbox/} (cli.ts:989)

缺的是用户教程。本 PR 仅补文档,不动代码。

What

新增详细操作手册(ZH + EN,~640 行 each):

  • docs-site/docs/cases/telegram-bind-claude-code-cli.md
  • docs-site/docs/en/cases/telegram-bind-claude-code-cli.md

覆盖 6 大步骤,每步给:

  • 预期命令输出
  • 落盘文件内容(.env / access.json / config.json 改动 / spawn args)
  • 错误诊断表(每种 error message → 解决)

加章节:

  • 步骤 0:Claude Code Telegram plugin 安装(claude plugin install telegram@claude-plugins-official,user-scope 一次装)
  • 步骤 1-2:拿 bot token + user id + 确认 runtime
  • 步骤 3-4:anet channel add telegram + 验证落盘
  • 步骤 5-6:重启节点 + Telegram DM 实测
  • 高级用法:多人白名单 / 群聊 / token rotate / unbind / 工具限制
  • 安全考虑:dangerouslySkipPermissions 取舍 + allowFrom 强制 + 一次性 workdir 建议
  • demos/codex-telegram-squad 区别表
  • 其他 runtime 状态(SDK 两个引 RFC-002)
  • 故障排查速查表

docs-site/docs/.vitepress/config.ts ZH + EN sidebar 案例 分类下加新链接。

How to verify

cd docs-site && npm run build
# 应该 "build complete in Xs",无 dead link

浏览器打开 anet.sh /cases/telegram-bind-claude-code-cli,6 步走全部可读。

用户视角端到端实测这步留给 Vincent 自测,PR 没等到 token 不阻塞 doc review):

  1. 跟着 step 0 装 plugin
  2. 跟着 step 1 拿 bot token + 自己 user id(私下,不进 PR)
  3. step 3 anet channel add telegram <你的-node> --bot-token <tok> --allow <id>
  4. step 5 重启节点
  5. step 6 DM bot 看是否回复

Vincent 自测 / 通信牛 跟着文档跑一遍发现偏差 → 直接在 PR comment 反馈,我 amend 修文档。

Test evidence

build complete in 54.53s.

无 dead link。EN 镜像跟 ZH 内容对齐(6 步 + 高级用法 + 安全 + cheat sheet 全镜像)。

未做端到端实测:跟 N站马 要 telegram bot token 被她合理拒绝(credential 不走 commhub channel 链式转述 — 这是 OSS 安全红线,她做得对)。文档基于 cli.ts 源码 review + 本机已装 plugin 的实际行为推导,但真 Telegram bot 发消息那一环节没真跑过 → 标 "Vincent 自测" 验收门。

Checklist

  • Relevant tests pass locally (docs build green)
  • docs-site/docs/changelog.md updated (n/a — 不是 user-visible behavior 改动,只是新教程)
  • Docs synced (这就是 doc 本身)
  • No secrets / tokens / private IPs / /home/<user> paths in the diff(所有 path 都是 <user> placeholder + 文档内 example bot token 123456789:AAEhBP_XYZxyz... 是 telegram docs 标准 placeholder)
  • Conventional Commits (docs:)
  • No Co-Authored-By: Claude* footer
  • Issue linked via Refs #14(不 Closes,因为 issue [feature] 节点接入 Telegram 的命令 #14 还含 SDK runtime 部分由 RFC-002 PR docs(rfc): RFC-002 node Telegram bind cli plan (closes #14) #20 跟踪)

关联 PR / Issue

…d walkthrough (refs #14)

Refs #14

issue #14 仅 claude-code-cli 路径 — 命令 `anet channel add telegram <node>` 实际已经
在 cli.ts:2570 实现,spawn 注入在 cli.ts:1636-1648,但没有用户教程。

新增详细操作手册 docs-site/docs/cases/telegram-bind-claude-code-cli.md (ZH+EN):
- 6 大步骤 + 每步预期输出 + 落盘文件内容
- step 0 plugin 安装(claude plugin install telegram@claude-plugins-official)
- 错误诊断表(每种 error message → 解决)
- 高级用法(多人 / 群聊 / token rotate / unbind / 工具限制)
- 安全考虑(dangerouslySkipPermissions + allowFrom 强制 + 一次性 workdir 建议)
- 跟 codex-telegram-squad demo 区别
- 故障排查速查表

sidebar 加链接(ZH + EN cases 列表)。

未端到端实测 — 命令路径基于 cli.ts 源码 review + 本机 claude plugin 已装确认。
Vincent 自测后如有偏差 amend。SDK 两个 runtime 状态文档明确,引到 RFC-002 P1/P2。
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants