wfh86421/dsh-telegram-bridge

dsh-telegram-bridge

Telegram ↔ DeepSeek Harness (DSH)：在手机上派工给本机的 AI agent，答案回到 Telegram。
两种实现：A＝独立程序（headless 一次性任务）；B＝DSH host 插件（真的 Session、GUI 看得到、可多轮接续）。

Send tasks to a local DeepSeek Harness agent from Telegram, and get the answer back. Two implementations: a standalone headless runner (A) and a host plugin that creates a real, GUI-visible, multi-turn session (B).

这个套件包含什么

| 目录 | 内容 |
|---|---|
| docs/ | 教学手册（10 份）：总览／快速开始／开发 SOP／契约清单／功能与权限／疑难排解／测试计划／二次开发 |
| src/host-plugin/ | 机制 B：dsh-tg-session 插件（零外部依赖，含 25 项测试） |
| src/headless-bridge/ | 机制 A：tg-bridge.mjs＋PowerShell 包装＋启动器（含 9 项自我测试） |
| examples/ | 设定范例（cordis.patch.yml、状态档） |

没有包含：任何 token／chat id／日志（凭证一律留在 ~/.dsh/notify-secrets.json，在 profile 之外）。

30 秒选机制

| | B（建议） | A（备援） |
|---|---|---|
| 你的 TG 讯息 | 变成真的 Session（GUI 看得到、可接手、可多轮） | 一次性 headless 任务（GUI 看不到） |
| 需要核准时 | ⏳ 逾时回报，可在 GUI 按核准后继续 | ❌ 没有核准管道 → 失败 |
| 安装 | 中（装 bundle＋改设定＋重启 DSH） | 低（复制 3 个档） |

⚠️ 两者不可同时跑：都靠 getUpdates 轮询同一支 bot，会互抢讯息。

快速开始

A：headless 桥接器（10 分钟）

copy src\headless-bridge\tg-bridge.mjs     \tools\
copy src\headless-bridge\run-tg-bridge.ps1 \tools\
node \tools\tg-bridge.mjs --selftest --dry-run --state-dir .\tempselftest   # 应 9/9
powershell -File \tools\run-tg-bridge.ps1 -Test "用一行回我 OK"              # 真的发一则
powershell -File \tools\run-tg-bridge.ps1                                   # 常驻

B：host 插件（30 分钟）

xcopy /E /I src\host-plugin \packages\dsh-tg-session
cmd /c mklink /J "\node_modules\dsh-tg-session" "\packages\dsh-tg-session"
在 \package.json 的 dsh.profile.bundles 追加 "dsh-tg-session"
在 \cordis.patch.yml 设定 tg-session 那一列（见 docs/01）
dsh --profile  --dump-config | Select-String 'tg-session'   # 必须出现
重启 DSH

完整步骤与设定键：docs/01-overview-and-quickstart.md

它能做到什么程度（重点）

| | 范围 |
|---|---|
| 看 | 整台电脑都能读（不受限） |
| 改 | 只限你设定的工作区（workspacePath）＋允许的暂存区 |
| 要核准 | 写到工作区外、对外网络、传讯息 → 无人时会卡住并通知你 |
| 直接拒绝 | 删除／凭证／远端硬体／系统／大量操作（关键字与类别白名单） |
| 做不到 | 图片档案、历史讯息、看中间过程、DSH 关机时 |
| 费用 | 每则 ≈¥0.03 起（固定前缀 ~1 万 token）；内建每日上限 |

细节与实测数字：docs/07-capability-and-permissions.md

文件地图

| 想做的事 | 看这份 |
|---|---|
| 搞清楚要学什么 | docs/00-index.md |
| 快速上手 | docs/01-overview-and-quickstart.md |
| 从零开发一个插件 | docs/05-development-sop.md |
| 要改／延伸（API 契约） | docs/06-contracts.md |
| 功能与权限的界线 | docs/07-capability-and-permissions.md |
| 坏了 | docs/08-troubleshooting.md |
| 上线前测试 | docs/09-telegram-test-plan.md |
| 换 IM／加功能／多人用 | docs/10-second-development.md |

需求

| 项目 | 版本（本套件实测） |
|---|---|
| DeepSeek Harness | @deepseek-ai/dsh 0.1.5-rc.1 |
| Node | v22.23.2 |
| PowerShell | 5.1（Windows）／含 PowerShell 7 亦可 |
| Telegram bot | 任意（用 getUpdates 轮询，不需要公开 IP） |

DSH 是 preview 软件，API 会变。升级后请照 docs/06-contracts.md §11 重跑检查。

安全（请务必读）

- 这个功能＝让远程消息在你电脑上执行 agent。只认一个 chat id、密钥放在 profile 之外、沙箱只允许工作区、危险类别硬拒、有每日成本上限。
- 不要把 token 贴进任何文件或消息；~/.dsh/notify-secrets.json 不要进版控。
- 要给他人用 → 另开一支 bot ＋ 另一个 profile，不要共用。

授权

MIT（见 LICENSE）。DSH 本体为 DeepSeek 所有，本套件只使用其公开接口。