# Gram 群发助手 · 完整说明

文档更新：2026-11-15。正式安装发行暂缓。

<a id="introduction"></a>

## 把名单变成有记录的发送

Gram 群发助手是一款在本机运行的桌面工具：输入指定 Telegram 用户名，查询其 Gram 收款地址，使用 Keeper 钱包批量发送小额 Gram，并附上统一推广文案。

从名单、查询到发送和回执，都在同一个工作区完成。常用金额为每人 0.1 Gram，也可以按实际需要修改。

### 一条清楚的工作流程

1. 准备账号与钱包：登录 Telegram 查询账号，导入自己的 Keeper 付款钱包。
2. 输入用户名：粘贴名单或导入文件，选择参与查询的账号。
3. 查询收款地址：查看结果，需要时导出地址；发送时由软件自动检查查询来源。
4. 设置并核对：填写每人金额与附言，检查收款明细、本金和费用预算。
5. 确认并发送：本人确认后建立任务，在任务记录查看逐笔状态。

### 核心能力

| 能力 | 能做什么 |
| --- | --- |
| 用户名查询 | 支持 @用户名、用户名和 t.me 链接；保留错误与去重信息 |
| 多账号参与 | 导入或登录协议账号，选择本次参与查询的账号 |
| Keeper 批量发送 | 设置统一金额与附言，选择一个或多个已导入的钱包 |
| 发送前核对 | 展示收款人、地址、本金、费用、批次与排除原因 |
| 任务记录 | 汇总全部任务的逐笔用户名、昵称、地址、附言、金额及状态 |
| 防重与恢复 | 默认排除已付款历史；中断后先核对，仅重新预览确实未发送的部分 |
| 文件与导出 | 查询名单支持六种文件格式；地址可按所选字段导出 TXT |
| 本机工作区 | 保存配置、任务与历史，支持工作区备份和合并恢复 |

### Telegram 通知如何理解

符合 Telegram 钱包服务条件的收款可能在 Telegram 官方服务通知中展示，因此可以承载带附言的小额推广。软件负责转账及任务追踪；通知的生成、展示和延迟由 Telegram 服务决定。

> 已确认链上到账不等于 Telegram 官方通知已经送达。请分别评估资金结果和通知展示效果，不以重复转账代替核对。

### 当前使用范围

付款端仅支持 Keeper 对应的钱包，资产为 Gram。地址虽然可能显示为 UQ 等友好编码，不能因此按 TON 主网转账。

当前本机 macOS 开发构建已有实际使用验证。Windows 与 macOS 独立桌面软件是交付形式，正式安装包、签名与跨平台安装验收暂缓，本网站暂不提供安装下载。

### 从这里开始

第一次使用请阅读[快速开始](#quick-start)。需要逐项操作时看[使用教程](#tutorial)，查页面用途时看[功能说明](#features)，遇到问题时看[常见问题](#faq)。


---

<a id="quick-start"></a>

## 第一次使用，从这里开始

按下面的顺序完成一次发送。已有账号和钱包可以直接复用，无须每次重新导入。

### 01 · 准备本机工作区

打开软件，点击右上角 **解锁本机凭据**。成功后显示 **锁定凭据**，表示本机材料可供当前操作使用。

在 **设置 → 本机环境** 可以检查数据库、加密和锁定状态。本网站仅提供说明，不接收登录信息、会话或钱包材料。

### 02 · 添加查询账号

1. 打开 **查询账号 → API配置**，填写自己的 API ID 和 API hash，点击 **保存 API 配置**。
2. 切到 **增加账号**，选择已保存的配置，点击 **开始手机号登录** 或 **开始二维码登录**。
3. 按软件提示完成登录，然后在 **本机账号** 确认账号已出现。

已有支持格式的协议账号，可使用 **导入账号** 预检并导入。API 配置不是 Telegram 用户名，也不是付款钱包。

### 03 · 导入 Keeper 付款钱包

进入 **付款钱包 → 导入钱包**，填写钱包名称、付款钱包已知地址和付款钱包助记词，点击 **验证并保存钱包**。

软件会核对地址与助记词是否一致。成功后可在 **钱包列表** 看到钱包。请在钱包中留足发送本金和网络费用；启用钱包不会自动发起转账。

> 助记词只在本机软件中输入。不要粘贴到本网站、聊天、截图或导出文件。

### 04 · 输入用户名并查找

进入 **用户名查询 → 参与账号** 勾选本次查询账号，再切到 **用户名输入**，每行输入一个用户名或链接，点击 **查找**。

```text
@example_user_a
https://t.me/example_user_b
example_user_c
```

以上仅为格式示例，不是测试收款人。请替换为自己的指定名单。

在 **查找结果** 查看地址与状态。没有取得地址的行不会因此自动变成可付款名单。

### 05 · 设置金额与附言

1. 进入 **批量发送 → 收款名单 → 查询结果**，等待软件载入最近批次并完成来源检查。
2. 在 **发送设置** 填写每人金额，例如 **0.1 Gram**，以及本次统一附言。
3. 在 **参与钱包** 勾选付款钱包；按需在 **更多设置** 调整批次人数、范围、费用上限和历史处理。
4. 回到 **发送设置**，点击 **生成付款预览**。

### 06 · 核对后再确认

生成成功后自动进入 **发送核对**。检查 **发送概览、收款明细、批次费用、排除明细**，确认收款地址、付款钱包、金额和附言。

例如 10 位收款人、每人 0.1 Gram，本金为 1 Gram，另需网络费用。最终以软件核对页显示的本次有效人数和预算为准。

确认无误后回到需要提交的核对页，勾选核对框，再点击 **确认并发送**。切换核对菜单会清除勾选；修改参数后需要重新生成预览。

### 07 · 查看结果

进入 **任务记录 → 发送记录**，查看全部任务的逐笔状态。**已提交** 需要继续观察，**已确认到账** 才表示软件已有对应到账证据。

需要停止后续发送时，打开 **任务管理 → 查看任务 → 任务状态**，按任务状态使用 **停止新发送**。已提交交易不能撤回。

遇到 **待核或未知** 时先查看[异常与恢复教程](#recovery)，不要直接新建重复付款。


---

<a id="features"></a>

## 每个栏目，各司其职

左侧栏目是独立功能，顶部横向菜单切换该功能的细项。**开始使用** 提供静态步骤说明；日常主要使用用户名查询、批量发送和任务记录。

### 用户名查询

| 菜单 | 用途 |
| --- | --- |
| 用户名输入 | 粘贴名单、导入名单，展开查询选项调整间隔与并发 |
| 查找结果 | 查看当前批次的用户名、UID／姓名、会员／上线、地址和结果 |
| 参与账号 | 选择本次新查询使用的 Telegram 账号 |

查询前检查参与账号的可用性。明确不可用的账号不参与本次分配，冷却和其他错误按实际结果处理。参与账号用于查询，不负责从 Keeper 扣款。

停止、继续和重试按钮仅在有对应任务时显示。修改参与账号不会把既有任务重新分配；历史任务继续时使用原配置。

### 批量发送

| 菜单 | 用途 |
| --- | --- |
| 收款名单 | 在粘贴地址、导入文件、查询结果三种来源中选择 |
| 发送设置 | 统一设置每人金额与转账附言，生成付款预览 |
| 参与钱包 | 勾选已导入且可用的 Keeper 付款钱包 |
| 更多设置 | 调整批次人数、发送范围、费用上限、钱包并发及历史处理 |
| 发送核对 | 按发送概览、收款明细、批次费用、排除明细核对后确认 |

查询结果作为来源时自动检查，仅通过的结果进入名单。直接粘贴地址时，由使用者自行核对收款地址；软件不会把人工地址声明为已验证的 Telegram 身份。

默认历史处理用于避免重复付款。仅在明确需要新一轮发送时选择新轮次，已在途、待核和已占用记录仍会排除。

### 任务记录

| 菜单 | 用途 |
| --- | --- |
| 发送记录 | 按页查看全部任务的逐笔发送历史 |
| 任务管理 | 查看任务，进入任务状态、逐笔明细或导出记录 |
| 待核处理 | 处理需要进一步证据的签名或发送状态 |

默认记录显示用户名、昵称、地址、附言、金额和发送状态。旧记录缺少可信昵称时显示 **—**。停止、只读核对、恢复未发等操作按任务实际状态显示。

### 查询账号

顶部菜单为 **本机账号、增加账号、导入账号、代理、API配置、钱包检测**。

支持在本机登录或导入支持格式的账号、管理可用状态、配置网络线路。钱包检测读取查询账号自身的钱包信息；它与 Keeper 付款钱包导入是两个功能。

代理按需配置，没有代理时无需填写。钱包检测下分 **检测操作、检测结果、筛选导出**，不需要每次发送前重复执行。

### 付款钱包

通过 **钱包列表、导入钱包** 管理自己的 Keeper 钱包。支持验证保存、编辑、启用、停用和删除本机记录。实际参与本次付款的钱包在 **批量发送 → 参与钱包** 勾选。

多个钱包按配置分配整批任务；本次本金和费用预算在核对页按钱包分别展示。

### 设置与运行日志

设置菜单为 **默认参数、节点访问、导出目录、备份恢复、本机环境**。用于保存常用配置、管理节点访问、选择输出目录以及创建或恢复工作区备份。

运行日志用于查看本次运行和错误线索。求助时优先提供错误文字与所在栏目，避免发送完整配置或敏感材料。

### 进度与状态

| 显示 | 如何理解 |
| --- | --- |
| 查询进度达到 100% | 全部行处理结束，可能仍包含失败或跳过 |
| 不定进度等待条 | 正在导入、估费或读取信息，暂时没有可计算总量 |
| 绿色成功标识 | 当前操作或该行达到其对应成功条件 |
| 黄色待核／警示 | 需要等待、检查或进一步证据 |
| 红色失败 | 查看该行或页面错误后处理 |
| 已提交 | 已提交发送，尚不能当作已确认到账 |
| 已确认到账 | 已有相应链上到账证据，不代表官方通知送达 |


---

<a id="tutorial"></a>

## 常用操作，一次讲清

首次配置请先看[快速开始](#quick-start)。这里按实际任务说明名单、发送、导出与恢复的操作位置。

### 准备与导入用户名

进入 **用户名查询 → 用户名输入**，每行一个用户名、@用户名或单段 t.me 链接。不要混入群邀请链接、手机号或付款地址。

大量名单可点击 **导入名单**，支持 TXT、CSV、TSV、JSON、JSONL、XLSX。先在 **参与账号** 选择可用账号；本机锁定时按软件提示解锁。

最简单的 TXT 示例：

```text
@example_user_a
@example_user_b
@example_user_c
```

JSON 示例：

```json
[
  { "username": "example_user_a" },
  { "username": "example_user_b" }
]
```

文件预检会保留来源行、错误和重复信息。持续读取 JSONL 只处理完整的新行，不会扩大已经确认的付款任务。示例名称仅展示格式，请替换为实际指定名单。

### 查看与导出收款地址

进入 **查找结果** 查看当前批次。地址以常见 UQ 友好编码显示，双击地址可复制。

点击 **导出收款地址**，勾选需要的字段，再点击 **导出 TXT**，按系统窗口保存：

| 勾选 | 输出方式 |
| --- | --- |
| 只勾选地址 | 每行一个纯地址 |
| 只勾选用户名 | 每行一个用户名 |
| 两项都勾选 | 每行 用户名----地址 |

导出包含当前批次全部页中有地址的结果，不附加表头、引号或逗号。没有地址的行跳过。页面显示 **已提交导出** 表示已启动下载；系统取消后不会保存文件。

### 从查询结果准备发送

打开 **批量发送 → 收款名单 → 查询结果**。软件载入最近完成或暂停的查询批次，自动核对来源，仅将通过的结果带入。

等待页面显示已选择的收款人数后，再设置金额。来源检查失败时先处理错误；切换来源、取消、锁定或离开操作期间，不会接受迟到的旧检查结果。

也可以选 **粘贴地址** 或 **导入文件**。人工地址须自行核对，支持的付款名单包括逐行地址、地址数组或含 address 字段的对象。文件中的金额和附言不会直接成为付款授权，需要明确采用页面统一设置。

### 设置并检查一批发送

1. **发送设置**：输入每人金额和统一附言，发送前检查文字、标点、链接与图标字符。
2. **参与钱包**：选择本次 Keeper 付款钱包。
3. **更多设置**：按需调整批次人数、范围和费用上限；首次发送可保留默认历史排除策略。
4. 回 **发送设置** 点击 **生成付款预览**，等待读取链状态和估费。
5. 在 **发送核对** 查看有效人数、排除原因、每笔地址、各钱包本金与费用预算。
6. 核对完成后勾选确认框，点击 **确认并发送**；看到 **付款任务已建立** 后前往任务记录。

附言是转账中的文本，可使用软件接受的字符。Telegram 如何展示字符、链接和图标由其客户端及服务决定，不是上传图片广告的入口。

费用上限用于签名前预算检查，不能封顶已签交易的实际网络费用。余额不足时补充余额或调整金额、名单、批次和参与钱包，再重新生成。

### 查看历史与导出记录

打开 **任务记录 → 发送记录**，直接查看所有任务的逐笔历史，底部可分页，无须先选择任务。

如需操作某一任务，进入 **任务管理**，点击该任务的 **查看任务**：

| 任务内菜单 | 使用方式 |
| --- | --- |
| 任务状态 | 按实际状态停止新发送、只读核对、重新预览确实未发送名单 |
| 逐笔明细 | 查看该任务每位收款人的处理结果 |
| 导出记录 | 按界面选择格式与列，保存该任务结果 |

请以对应行的状态判断结果。任务建立成功、进度条或钱包余额变化都不能替代逐笔到账状态。

<a id="recovery"></a>

### 停止、中断与恢复

发送过程中需要停止，进入 **任务管理 → 查看任务 → 任务状态**，在有该操作时点击 **停止新发送**。它阻止后续发送，不能撤回已提交交易。

意外退出后，软件不会自动续发。先打开原任务，读取逐笔状态并按界面进行只读核对。已提交、待核或未知状态保留占用，不应通过新任务强行重付。

仅在软件确认存在确实未发送的部分时，使用 **重新预览确实未发送名单**。软件保留相应金额与附言，重新估费，仍由本人核对并确认付款。

> 没查到交易、等待超时、序号变化或余额变化，单独都不能证明未发送。状态不明时保留原任务并核对。

### 备份与恢复工作区

进入 **设置 → 备份恢复**，点击 **创建工作区备份**，选择专用保存目录。将备份作为私有文件妥善保管。

恢复时点击 **预检备份** 并选择备份目录，阅读预检结果后使用 **确认合并恢复工作区**。恢复会保留较新的付款记录，撤销旧付款授权；历史未核对前发送保持锁定。

恢复不会自动付款。系统绑定的凭据在其他机器上可能无法解密，需要在软件内重新导入；工作区备份不等于可随意分享的普通导出文件。


---

<a id="faq"></a>

## 遇到问题，先看这里

### 已到账，但没有 Telegram 官方通知？

链上到账与官方通知是两个结果。通知可能受 Telegram 服务处理、钱包状态及展示时机影响；软件无法保证每笔通知生成或即时送达。

先在 **任务记录 → 发送记录** 查看该笔到账状态。有条件时由收款人查看其钱包流水。不要仅因没有通知就再次付款。

### UQ 地址是 TON 地址吗？为什么有时看到 0:？

UQ 等友好编码和 0: 开头的原始格式可以表示同一个底层账户。编码形式本身不能判断资产和网络。

本软件付款使用 **Keeper 所在 Gram 网络与原生 Gram**。不要因为地址外观相似就在 TON 主网转账。软件查询结果优先展示完整 UQ 地址。

### 只知道用户名就一定能转账吗？

软件先查询可取得的收款地址，再在用于付款时检查来源。用户名不存在、账号接口不可用、目标钱包状态或网络错误，都可能导致没有取得可用结果。

查询到候选地址不等于已完成付款来源检查，也不等于收款人本人独立确认。没有地址时可以向对方取得公开地址，在 **批量发送** 人工填写并核对。

### 查询账号和付款钱包有什么区别？

查询账号用于登录 Telegram、查询用户名和地址；参与账号控制本次查询使用哪些账号。付款钱包保存自己的 Keeper 付款材料，由它支付 Gram 和网络费用。两者分别在不同栏目管理。

### 查询失败，是否代表对方没有钱包？

不能这样判断。先看失败原因。**查询账号不可用** 指参与查询的账号接口不可用，不直接说明收款目标的状态。

会话失效时通过失败行 **重新登录查询账号**，完成后回原任务 **重试失败项**。代理错误可用 **检查查询代理** 修复原账号线路。服务端冷却应等到页面显示的可重试时间。

### 导入名单或确认按钮点不了？

查询时检查数据库是否正常、是否有参与账号，以及本机凭据是否需要解锁。导入名单点击后可按提示解锁并选择文件。

付款时先生成有效预览，确保本机已解锁、已选择可用 Keeper 钱包，并勾选核对框。修改参数、切换核对菜单或锁定后，旧确认会失效；按提示重新核对，不要连续点击。

### 为什么默认排除了曾经付款的地址？

默认历史策略用于避免误重付。需要明确发起下一轮时，在 **更多设置 → 历史付款处理** 选择新轮次，再仔细核对排除明细和本次名单。

新轮次仍排除在途、待核和已占用记录，不会解除状态不明的资金保护。

### 每人金额和总费用怎么算？

本金等于本次有效收款人数乘以每人金额，另加网络费用预算。比如 10 人每人 0.1 Gram，本金是 1 Gram。

最终以 **发送核对** 的人数、本金、各钱包预算和批次费用为准。费用上限是后续签名前的检查条件，不是已签交易的最终费用保证。

### 显示节点访问受限或余额不足？

节点受限时，按付款页 **修复当前节点访问** 保存当前节点的访问配置，再手动重新生成预览。也可在 **设置 → 节点访问** 管理。

余额不足时检查各参与钱包的实际可用余额，补充余额或调整名单、金额与批次设置，然后重新预览。不要把节点问题当成已付款失败并立即重发。

### 可以暂停后自动续发吗？

查询停止会保留结果，有未完成部分时可手动继续。付款停止或软件重开后不会自动续发；需先核对原任务，再为确实未发送的部分重新预览并由本人确认。

### 导出只有地址，或者没有文件？

**导出收款地址** 默认只勾选地址，因此输出逐行纯地址。需要用户名时同时勾选用户名，输出格式为 **用户名----地址**。

导出跳过没有地址的结果。页面显示已提交导出仅代表下载已启动，仍需在系统窗口保存；取消或被系统拒绝时不会有新文件。

### 现在能下载 Windows 或 macOS 安装包吗？

正式安装包、签名与跨平台安装验收仍暂缓，本站不提供未验收的安装下载。当前使用状态以已交付的本机版本为准。

### 需要向别人提供哪些信息来排查？

记录出错栏目、操作步骤、错误代码与发生时间即可；必要时提供不含敏感内容的截图。助记词、私钥、API hash、验证码、会话和代理密码只在本机处理，不发到文档站或聊天中。