mytglib 2.2.0 → 2.2.1

package/README.md

@@ -1 +1,111 @@
 # mytglib
+
+Telegram 会话创建、转换和登录后 RPC。Node 使用 `@mtcute/node`，Rust 使用仓库内的 `grammers-core`。
+
+## 使用已有会话
+
+```js
+import { CoreClient } from "mytglib";
+
+const core = new CoreClient({
+  sessionSource: { type: "native", sessionFilePath: "/absolute/account.session" },
+  timeout: 30_000,
+  // proxy: { type: "socks5", host: "127.0.0.1", port: 1080 },
+});
+try {
+  const client = await core.init();
+  const users = await client.call({ _: "users.getUsers", id: [{ _: "inputUserSelf" }] });
+  console.log(users);
+  console.log(await core.checkAccountStatus());
+} finally {
+  await core.destroy();
+}
+```
+
+`native` 指 Node 的 mtcute SQLite 运行文件，必须已经保存授权及连接身份。原生会话直接打开，不复制。`destroy()` 关闭连接和存储，保留文件供下次重开。
+
+首次导入外部格式时，将 `sessionSource` 换为以下一种：
+
+```js
+// Telethon / mtcute .session + 配套 JSON
+const sessionSource = {
+  type: "sessionJson",
+  sessionFilePath: "/absolute/source.session",
+  sessionJsonFilePath: "/absolute/source.json",
+  outputSessionPath: "/absolute/new-runtime.session",
+};
+
+// 或 tdata（多账号目录需指定 accountIndex）
+const tdataSource = {
+  type: "tdata",
+  tdataPath: "/absolute/tdata",
+  outputSessionPath: "/absolute/new-runtime.session",
+  passcode: "",
+  // accountIndex: 0,
+};
+```
+
+输出必须是新文件。导入成功后只需保存运行文件路径，后续使用 `native` 打开。连接失败不会丢掉已经完成的导入；同一个 Core 实例重试时也会直接重开运行文件。
+
+已有会话使用保存的 API、设备、版本与语言，不需要设备 token resolver，也不需要重新登录。tdata 使用现有 Desktop 配置规则生成并持久保存连接身份。不要同时传入注册用的 `clientType`、手机号或身份覆盖配置。
+
+## 新建与登录
+
+新建流程继续使用原来的 `CoreClient({ clientType, phone, sessionDirPath, deviceTokenResolver, ... })`。完整示例覆盖初始化、发码、验证码/密码处理、请求与关闭：
+
+```sh
+node examples/login.js --help
+node examples/account-status.js --help
+```
+
+登录示例所需的代理和设备 token 提供方由调用方配置。已有会话不经过该新建流程。
+
+## Rust
+
+使用 `CoreClientConfig::from_session(SessionSource)`，再由 `CoreClient::init()` 返回 `CoreRpcClient`。三种来源为：
+
+- `SessionSource::Grammers`：打开已有 `.grammers`。
+- `SessionSource::SessionJson`：`.session + .json` 导入指定的新 `.grammers`。
+- `SessionSource::Tdata`：选定 tdata 账号导入指定的新 `.grammers`，`profile` 可用 `DesktopProfile::default()`。
+
+普通请求使用 `rpc.invoke()` / `rpc.call()`，测活使用 `rpc.check_account_status()`，最后调用 `core.destroy().await`。两种外部格式会写入真正的原生 SQLite 授权表和连接身份；移除来源文件后仍能重新打开。
+
+```sh
+cargo run --manifest-path vendor/grammers/Cargo.toml -p grammers-core --example account_status -- --help
+```
+
+## 行为与迁移
+
+- 已有授权失效会返回错误，不自动新建授权替代。一次只能有一个所有者使用同一授权；调用方也应协调其他进程。
+- 来源转换是离线操作，转换成功不代表远端授权仍有效。可用 `users.getUsers(inputUserSelf)` 验证登录后请求。
+- `syncSessionJson()` / `sync_session_json()` 显式刷新导出件；关闭客户端不会自动执行导出。
+- 原独立 `checkAccountStatus(options)` / `check_account_status(options)` 已由 Core 方法替代，属于公共 API 变更。桌面客户端接入另行进行，其原固定 revision 不在本次修改范围。
+- 普通 Core 会处理协议控制包和保存运行状态，不再提供旧测活的只读快照、单业务包连接契约。
+
+完整边界和调用方式见 [已有会话](docs/session-reuse.md) 与 [账号测活](docs/account-status.md)。
+
+## 双向限制检测
+
+Node 使用 `core.checkAccountRestriction()`，Rust 使用 `rpc.check_account_restriction()`；两端也提供仅重新解释已留存正文的接口。Core 负责 SpamBot 查询、跨国家缓存匹配、AI 提示词/校验和时间模板。正常检测复用身份查询中的手机号，通过本地 `checkPhone` / `check_phone` 得到国家代码，不再识别回复语言，也不携带 Lingua 模型；业务方负责共享国家目录、首次 TXT 样本及账号状态持久化。
+
+AI 分类使用共享自定义 tone：传入 `aiToneSlug` / `ai_tone_slug`，各账号解析后使用自己的 AI 配额，无需安装。提示词保持已验证的 `spambot-classifier-v1` 原文与四字段输出契约，可继续使用原 tone；本地规则命中或协议冻结时不需要 AI 配置。配置、错误处理与恢复示例见 [双向限制检测](docs/account-restriction.md)。
+
+业务端在写锁内使用 `mergeSpamBotRule()` / `merge_spambot_rule()` 合并最新索引并原子保存；每国家每类别只保存第一份原始 TXT。新规则版本为 `spambot-country-v1`，使用 `countryCode`；旧语言库原样搁置，不读取、迁移或删除。规则加载回调一次返回新库全部国家索引（Rust 为 `Vec<SpamBotRuleIndex>`），空库返回空数组。结果以可空 `countryCode` 替代语言及模型字段，属于需要消费方适配的 API 变更。
+
+## 验证
+
+```sh
+npm test
+cargo test --locked --manifest-path vendor/grammers/Cargo.toml -p grammers-core
+```
+
+Node 需使用与本机 `better-sqlite3` ABI 匹配的版本。本仓库当前依赖支持的 Node 版本见 `package.json`。
+
+Rust 的本地加密协议集成测试需先构建示例，再通过环境变量启用；未指定时 `npm test` 会跳过这部分用例：
+
+```sh
+cargo build --locked --manifest-path vendor/grammers/Cargo.toml -p grammers-core --example account_status
+TG_ACCOUNT_CHECK_RUST_BIN="$PWD/vendor/grammers/target/debug/examples/account_status" node --test tests/account-status-rust.test.js
+```
+
+若设置了 `CARGO_TARGET_DIR`，将示例路径改为实际构建输出目录。协议测试使用本地 peer 和合成授权，不连接 Telegram。