From c99635c87cc4b929f9636aded7c2549288b2001a Mon Sep 17 00:00:00 2001 From: Tron Date: Fri, 29 May 2026 15:39:09 +0800 Subject: [PATCH 01/10] docs: apply accurate P1/P2 review items (verified against source) Apply the "safe to execute" subset of the developer-docs review, with every code/external fact verified against the real TronLink repos and npm registry (not the report's claims): - P0-3: pin @bankofai/agent-wallet to exact 2.3.0 + GitHub 404 / npm pack audit note (npm latest 2.4.0 and the 404 confirmed). - P1-1: mcp-tronlink-signer "which to use" 3-way table. - P1-2: mcp-tronlink-signer inline schema mirror (field names from the published tool set; types deferred to list_tools). - P1-4: tronlink-mcp-core scenario decision matrix vs mcp-server-tronlink. - P1-6: mcp-server-tronlink wallet path A/B scenario decision table. - P1-7: mcp-tronlink-signer relationship/version note (tronlink-signer 0.1.4, co-released; verified on npm). - P1-3 / P2-6 / Skill-P2-2: token-contract SSOT in reference/networks (addresses from tronlink-skills KNOWN_TOKENS; CLI/Skills reconciled). Corrected the report's wrong USDD address (it pointed at deprecated USDDOLD) to the current USDD TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz. - P2-1: mcp-server end-to-end agent dialogue example. - P2-2: Flow Recipes "source file" column (mapping verified via source). - P2-4: signer inline-changelog sync policy note. - P2-7: ai-llms version-contract reference. - Skill-P2-1/3/4: Skills troubleshooting section, TronGrid key 5-dim management, end-to-end dialogue examples. Flow counts/rows left intact (both contested flows exist in code; the count fix is a separate item). llms.txt / llms-full.* regenerated via scripts/gen_llms_full.py. Co-Authored-By: Claude Opus 4.8 --- docs/ai-support/ai-llms.en.md | 1 + docs/ai-support/ai-llms.zh.md | 1 + docs/ai-support/mcp-server-tronlink.en.md | 101 ++++++--- docs/ai-support/mcp-server-tronlink.zh.md | 105 +++++---- docs/ai-support/mcp-tronlink-signer.en.md | 67 ++++++ docs/ai-support/mcp-tronlink-signer.zh.md | 67 ++++++ docs/ai-support/tronlink-cli.en.md | 12 +- docs/ai-support/tronlink-cli.zh.md | 12 +- docs/ai-support/tronlink-mcp-core.en.md | 12 + docs/ai-support/tronlink-mcp-core.zh.md | 12 + docs/ai-support/tronlink-skills.en.md | 41 ++++ docs/ai-support/tronlink-skills.zh.md | 41 ++++ docs/llms-full.en.txt | 258 +++++++++++++++++---- docs/llms-full.txt | 258 +++++++++++++++++---- docs/llms-full.zh.txt | 262 +++++++++++++++++----- docs/llms.txt | 2 +- docs/llms.zh.txt | 2 +- docs/reference/networks.en.md | 18 +- docs/reference/networks.zh.md | 18 +- 19 files changed, 1050 insertions(+), 240 deletions(-) diff --git a/docs/ai-support/ai-llms.en.md b/docs/ai-support/ai-llms.en.md index 211381b..8df0493 100644 --- a/docs/ai-support/ai-llms.en.md +++ b/docs/ai-support/ai-llms.en.md @@ -56,3 +56,4 @@ Plus the DApp integration, mobile (DeepLink), and Reference (networks, glossary, - For tool calls, branch on the structured `error.code` / `error.retryable`, never on the human-readable `message`. - Read operations are safe to retry; signing / Remote Write operations require user approval (HITL) and must not be auto-retried — see each tool's Safety section. - Default to testnets (`nile` / `shasta`) when experimenting; use `mainnet` only for real funds. +- Version contracts: each tool page documents what is stable vs. volatile under its Compatibility & Migration section — consult it before pinning to any name, flag, or output field. diff --git a/docs/ai-support/ai-llms.zh.md b/docs/ai-support/ai-llms.zh.md index 6f962e8..608a641 100644 --- a/docs/ai-support/ai-llms.zh.md +++ b/docs/ai-support/ai-llms.zh.md @@ -56,3 +56,4 @@ TronLink 的开发者文档以机器可读形式发布，便于 AI 智能体和 - 工具调用请基于结构化的 `error.code` / `error.retryable` 分支,**不要**解析人类可读的 `message`。 - 读操作可安全重试;签名 / 远程写操作需要用户审批（HITL）,且不得自动重试——见各工具的「安全」一节。 - 实验时默认用测试网（`nile` / `shasta`）;只有动用真实资金时才用 `mainnet`。 +- 版本契约：每个工具页在「兼容性与迁移策略」一节列明了哪些是稳定契约、哪些会变动——在依赖任何名称、flag 或输出字段前请先查阅该节。 diff --git a/docs/ai-support/mcp-server-tronlink.en.md b/docs/ai-support/mcp-server-tronlink.en.md index 1ca2e46..6b4787d 100644 --- a/docs/ai-support/mcp-server-tronlink.en.md +++ b/docs/ai-support/mcp-server-tronlink.en.md @@ -156,7 +156,9 @@ Runtime wallet management via `@bankofai/agent-wallet` (encrypted `local_secure` - `tl_wallet_set_active` — Switch the active wallet by ID (hot-swaps into all capabilities) If no wallet exists at startup, the server prompts two paths: call `tl_wallet_create` to auto-generate one, or create one manually via CLI and set `AGENT_WALLET_PASSWORD`. -The auto-create path generates a random password, saves it to `~/.agent-wallet/runtime_secrets.json`, creates an encrypted `main` wallet, and enables the running session to use it. + +!!! warning "Auto-create writes the password to disk in plaintext — test/dev only" + The auto-create path generates a random password and saves it **in plaintext** to `~/.agent-wallet/runtime_secrets.json`, then creates an encrypted `main` wallet and lets the running session use it. Anyone with read access to that file controls the wallet. For production, use the manual path: create the wallet out-of-band and inject `AGENT_WALLET_PASSWORD` from a secret manager — never rely on the on-disk plaintext password. ### 6. TRON Cryptography Utils @@ -179,44 +181,44 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256). Pre-configured multi-step workflows with dependency checks and parameter templates. ### Playwright Flows -| Flow | Description | -|------|-------------| -| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | -| `enableTestNetworksFlow` | Enable testnet visibility | -| `transferTrxFlow` | TRX transfer via UI | -| `transferTokenFlow` | Token transfer via UI | +| Flow | Description | Source File | +|------|-------------|-------------| +| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | `src/flows/switch-network.ts` | +| `enableTestNetworksFlow` | Enable testnet visibility | `src/flows/switch-network.ts` | +| `transferTrxFlow` | TRX transfer via UI | `src/flows/transfer-trx.ts` | +| `transferTokenFlow` | Token transfer via UI | `src/flows/transfer-trx.ts` | ### On-Chain Flows (11) -| Flow | Description | -|------|-------------| -| `chainCheckBalanceFlow` | Query balance | -| `chainTransferTrxFlow` | TRX transfer with pre-checks | -| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | -| `chainStakeFlow` | Stake TRX | -| `chainUnstakeFlow` | Unstake TRX | -| `chainGetStakingFlow` | Query staking info | -| `chainDelegateResourceFlow` | Delegate bandwidth/energy | -| `chainUndelegateResourceFlow` | Undelegate resources | -| `chainSetupMultisigFlow` | Setup multi-sig permissions | -| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | -| `chainSwapV3Flow` | SunSwap V3 token swap | +| Flow | Description | Source File | +|------|-------------|-------------| +| `chainCheckBalanceFlow` | Query balance | `src/flows/onchain.ts` | +| `chainTransferTrxFlow` | TRX transfer with pre-checks | `src/flows/onchain.ts` | +| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | `src/flows/onchain.ts` | +| `chainStakeFlow` | Stake TRX | `src/flows/onchain.ts` | +| `chainUnstakeFlow` | Unstake TRX | `src/flows/onchain.ts` | +| `chainGetStakingFlow` | Query staking info | `src/flows/onchain.ts` | +| `chainDelegateResourceFlow` | Delegate bandwidth/energy | `src/flows/onchain.ts` | +| `chainUndelegateResourceFlow` | Undelegate resources | `src/flows/onchain.ts` | +| `chainSetupMultisigFlow` | Setup multi-sig permissions | `src/flows/onchain.ts` | +| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | `src/flows/onchain.ts` | +| `chainSwapV3Flow` | SunSwap V3 token swap | `src/flows/onchain.ts` | ### Multi-Sig Flows (6) -| Flow | Description | -|------|-------------| -| `multisigQueryAuthFlow` | Query permissions | -| `multisigListTransactionsFlow` | List pending transactions | -| `multisigMonitorFlow` | WebSocket real-time monitoring | -| `multisigStopMonitorFlow` | Stop monitoring | -| `multisigSubmitTxFlow` | Submit signed transaction | -| `multisigCheckFlow` | Full status check | +| Flow | Description | Source File | +|------|-------------|-------------| +| `multisigQueryAuthFlow` | Query permissions | `src/flows/multisig.ts` | +| `multisigListTransactionsFlow` | List pending transactions | `src/flows/multisig.ts` | +| `multisigMonitorFlow` | WebSocket real-time monitoring | `src/flows/multisig.ts` | +| `multisigStopMonitorFlow` | Stop monitoring | `src/flows/multisig.ts` | +| `multisigSubmitTxFlow` | Submit signed transaction | `src/flows/multisig.ts` | +| `multisigCheckFlow` | Full status check | `src/flows/multisig.ts` | ### GasFree Flows (3) -| Flow | Description | -|------|-------------| -| `gasfreeCheckAccountFlow` | Query eligibility | -| `gasfreeTransactionHistoryFlow` | Query history | -| `gasfreeSendFlow` | Gas-free TRC20 transfer | +| Flow | Description | Source File | +|------|-------------|-------------| +| `gasfreeCheckAccountFlow` | Query eligibility | `src/flows/gasfree.ts` | +| `gasfreeTransactionHistoryFlow` | Query history | `src/flows/gasfree.ts` | +| `gasfreeSendFlow` | Gas-free TRC20 transfer | `src/flows/gasfree.ts` | --- @@ -420,9 +422,11 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump | `@noble/hashes` | ^2.0.1 | Keccak-256, SHA256 | | `@tronlink/tronlink-mcp-core` | ^0.1.0 | Core MCP server framework | | `playwright` | ^1.49.0 | Browser automation | -| `@bankofai/agent-wallet` | ^2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible | +| `@bankofai/agent-wallet` | 2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible | | `ws` | ^8.18.0 | WebSocket (multi-sig monitoring) | +> **About @bankofai/agent-wallet:** Pinned to exact 2.3.0 (no caret, to avoid silently picking up 2.4.0 on npm). The package's GitHub repo is currently not public (HTTP 404); source transparency comes from the npm publish — audit it via `npm pack @bankofai/agent-wallet@2.3.0`. Upgrading to 2.4.0 should be evaluated against its changelog first. + --- ## Tool Contract & Side Effects @@ -700,6 +704,20 @@ The Direct-API path signs with a local encrypted wallet managed by `@bankofai/ag 5. **Gas-Free Operations** — TRC20 transfers without TRX balance requirements 6. **Infrastructure Testing** — Contract deployment, fixture management, mock servers +### End-to-end example: swap 100 TRX for USDT on SunSwap V3 + +A realistic agent turn, showing the tool-call sequence. The agent reads first, gets a fresh quote, surfaces it for human approval, then executes — never auto-executing a Remote Write off a read. + +> **User:** "Swap 100 TRX for USDT on SunSwap V3, max 0.5% slippage." + +1. `tl_chain_get_account` (Network Read) — confirm the active wallet holds ≥ 100 TRX plus enough for fees. +2. `tl_chain_swap_v3` with `action=estimate` (Network Read) — `from_token="TRX"`, `to_token=""`, `amount="100"`, `fee_tier=3000`, `slippage=0.5`. Returns the quoted output and route. +3. Agent surfaces the quote to the user and waits for confirmation (HITL — this is a Remote Write). +4. `tl_chain_swap_v3` with `action=execute` and the **same** explicit `slippage=0.5` — signs with the local `agent-wallet` and broadcasts. Returns `txId`. +5. `tl_chain_get_tx` (Network Read) with the returned `txId` — confirm on-chain success before reporting back. + +> If step 4 returns an uncertain/failed result, do **not** auto-retry: `TL_CHAIN_SWAP_FAILED` is not retryable — re-check the chain with `tl_chain_get_tx` first (see Swap safety). + --- ## Quick Start @@ -713,8 +731,8 @@ npm install && npm run build # TL_TRONGRID_URL=https://nile.trongrid.io # # 3. If no wallet exists, choose one path: -# Option A: call tl_wallet_create after startup -# Option B: create one locally, then set AGENT_WALLET_PASSWORD +# Option A (manual): create one locally, then set AGENT_WALLET_PASSWORD +# Option B (auto-create): call tl_wallet_create after startup # 4. Use with Claude Code # "Check my TRX balance" @@ -722,6 +740,17 @@ npm install && npm run build # "Swap 100 TRX for USDT on SunSwap V3" ``` +**Which path? (scenario → path)** + +| Scenario | Recommended path | Why | +|----------|------------------|-----| +| Production (real funds) | A — manual + secret manager | Path B writes the password in plaintext to `~/.agent-wallet/runtime_secrets.json` | +| CI / automation (testnet) | A — manual + env injection | Same — keep the password out of an on-disk file | +| Local dev (one-off) | B — auto-create | No pre-config; the password is generated automatically | +| Temp demo | B + tmpfs directory | Point `AGENT_WALLET_DIR` at a tmpfs path destroyed at job end | + +> Path B (auto-create) writes the generated password in plaintext to `~/.agent-wallet/runtime_secrets.json` so a restart can reuse the wallet. See [Wallet Secret Storage](#wallet-secret-storage) for the full Path A / Path B comparison and how to enforce Path A. + ## Version & License - **Package:** `@tronlink/mcp-server-tronlink` v0.1.1 diff --git a/docs/ai-support/mcp-server-tronlink.zh.md b/docs/ai-support/mcp-server-tronlink.zh.md index b975f0a..7c39dc4 100644 --- a/docs/ai-support/mcp-server-tronlink.zh.md +++ b/docs/ai-support/mcp-server-tronlink.zh.md @@ -156,7 +156,9 @@ TRON 多签服务的 REST + WebSocket API： - `tl_wallet_set_active` — 按 ID 切换活跃钱包（热切换到所有能力） 如果启动时没有钱包，服务器会提示两条路径：调用 `tl_wallet_create` 自动生成，或通过 CLI 手动创建后设置 `AGENT_WALLET_PASSWORD`。 -自动创建这条路径会生成随机密码，把密码保存到 `~/.agent-wallet/runtime_secrets.json`，创建一个加密的 `main` 钱包，并让当前会话立即可用。 + +!!! warning "自动创建会把密码以明文写入磁盘——仅限测试/开发" + 自动创建这条路径会生成随机密码，并把它**以明文**保存到 `~/.agent-wallet/runtime_secrets.json`，随后创建一个加密的 `main` 钱包并让当前会话立即可用。任何能读取该文件的人都能控制钱包。生产环境请使用手动路径：在外部创建钱包，并通过密钥管理器注入 `AGENT_WALLET_PASSWORD`——不要依赖落盘的明文密码。 ### 6. TRON 密码学工具 @@ -179,44 +181,44 @@ hexToAddress() 0x41... → T 地址 预配置的多步骤工作流，带依赖检查和参数模板。 ### Playwright 流程 -| 流程 | 说明 | -|------|------| -| `switchNetworkFlow` | 切换到主网/Nile/Shasta | -| `enableTestNetworksFlow` | 启用测试网可见性 | -| `transferTrxFlow` | 通过 UI 进行 TRX 转账 | -| `transferTokenFlow` | 通过 UI 进行代币转账 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `switchNetworkFlow` | 切换到主网/Nile/Shasta | `src/flows/switch-network.ts` | +| `enableTestNetworksFlow` | 启用测试网可见性 | `src/flows/switch-network.ts` | +| `transferTrxFlow` | 通过 UI 进行 TRX 转账 | `src/flows/transfer-trx.ts` | +| `transferTokenFlow` | 通过 UI 进行代币转账 | `src/flows/transfer-trx.ts` | ### 链上流程（11 个） -| 流程 | 说明 | -|------|------| -| `chainCheckBalanceFlow` | 查询余额 | -| `chainTransferTrxFlow` | 带预检查的 TRX 转账 | -| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 | -| `chainStakeFlow` | 质押 TRX | -| `chainUnstakeFlow` | 解除质押 TRX | -| `chainGetStakingFlow` | 查询质押信息 | -| `chainDelegateResourceFlow` | 代理带宽/能量 | -| `chainUndelegateResourceFlow` | 取消代理资源 | -| `chainSetupMultisigFlow` | 设置多签权限 | -| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 | -| `chainSwapV3Flow` | SunSwap V3 代币兑换 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `chainCheckBalanceFlow` | 查询余额 | `src/flows/onchain.ts` | +| `chainTransferTrxFlow` | 带预检查的 TRX 转账 | `src/flows/onchain.ts` | +| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 | `src/flows/onchain.ts` | +| `chainStakeFlow` | 质押 TRX | `src/flows/onchain.ts` | +| `chainUnstakeFlow` | 解除质押 TRX | `src/flows/onchain.ts` | +| `chainGetStakingFlow` | 查询质押信息 | `src/flows/onchain.ts` | +| `chainDelegateResourceFlow` | 代理带宽/能量 | `src/flows/onchain.ts` | +| `chainUndelegateResourceFlow` | 取消代理资源 | `src/flows/onchain.ts` | +| `chainSetupMultisigFlow` | 设置多签权限 | `src/flows/onchain.ts` | +| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 | `src/flows/onchain.ts` | +| `chainSwapV3Flow` | SunSwap V3 代币兑换 | `src/flows/onchain.ts` | ### 多签流程（6 个） -| 流程 | 说明 | -|------|------| -| `multisigQueryAuthFlow` | 查询权限 | -| `multisigListTransactionsFlow` | 列出待处理交易 | -| `multisigMonitorFlow` | WebSocket 实时监控 | -| `multisigStopMonitorFlow` | 停止监控 | -| `multisigSubmitTxFlow` | 提交签名交易 | -| `multisigCheckFlow` | 完整状态检查 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `multisigQueryAuthFlow` | 查询权限 | `src/flows/multisig.ts` | +| `multisigListTransactionsFlow` | 列出待处理交易 | `src/flows/multisig.ts` | +| `multisigMonitorFlow` | WebSocket 实时监控 | `src/flows/multisig.ts` | +| `multisigStopMonitorFlow` | 停止监控 | `src/flows/multisig.ts` | +| `multisigSubmitTxFlow` | 提交签名交易 | `src/flows/multisig.ts` | +| `multisigCheckFlow` | 完整状态检查 | `src/flows/multisig.ts` | ### GasFree 流程（3 个） -| 流程 | 说明 | -|------|------| -| `gasfreeCheckAccountFlow` | 查询资格 | -| `gasfreeTransactionHistoryFlow` | 查询历史 | -| `gasfreeSendFlow` | 免 Gas TRC20 转账 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `gasfreeCheckAccountFlow` | 查询资格 | `src/flows/gasfree.ts` | +| `gasfreeTransactionHistoryFlow` | 查询历史 | `src/flows/gasfree.ts` | +| `gasfreeSendFlow` | 免 Gas TRC20 转账 | `src/flows/gasfree.ts` | --- @@ -412,9 +414,11 @@ mcp-server-tronlink/ | `@noble/hashes` | ^2.0.1 | Keccak-256、SHA256 | | `@tronlink/tronlink-mcp-core` | ^0.1.0 | 核心 MCP 服务框架 | | `playwright` | ^1.49.0 | 浏览器自动化 | -| `@bankofai/agent-wallet` | ^2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 | +| `@bankofai/agent-wallet` | 2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 | | `ws` | ^8.18.0 | WebSocket（多签监控） | +> **关于 @bankofai/agent-wallet：** 版本精确钉死在 2.3.0（不用 caret，避免静默升到 npm 上的 2.4.0）。该包的 GitHub 仓库当前未公开（HTTP 404），源码透明性由 npm publish 提供——可用 `npm pack @bankofai/agent-wallet@2.3.0` 解包审计。是否升级到 2.4.0 需另行评估其 changelog 后决定。 + --- ## 工具契约与副作用 @@ -691,6 +695,20 @@ Direct-API 路径使用 `@bankofai/agent-wallet` 管理的本地加密钱包签 5. **免 Gas 操作** — 无需 TRX 余额即可完成 TRC20 转账 6. **基础设施测试** — 合约部署、固件管理、Mock 服务 +### 端到端示例：在 SunSwap V3 上用 100 TRX 兑换 USDT + +一个真实的 agent 回合，展示工具调用顺序。agent 先读取、再现取报价、交人工确认后才执行——绝不基于 read 结果自动触发「远程写」。 + +> **用户：** "在 SunSwap V3 上用 100 TRX 兑换 USDT，滑点上限 0.5%。" + +1. `tl_chain_get_account`（Network Read）—— 确认当前钱包持有 ≥ 100 TRX 且留有手续费余量。 +2. `tl_chain_swap_v3`，`action=estimate`（Network Read）—— `from_token="TRX"`、`to_token=""`、`amount="100"`、`fee_tier=3000`、`slippage=0.5`。返回报价输出与路径。 +3. agent 把报价呈现给用户并等待确认（HITL——这是一笔远程写）。 +4. `tl_chain_swap_v3`，`action=execute`，并传入**相同的**显式 `slippage=0.5`——用本地 `agent-wallet` 签名并广播。返回 `txId`。 +5. `tl_chain_get_tx`（Network Read），传入返回的 `txId`——在回报前先确认链上成功。 + +> 若第 4 步返回结果未知 / 失败，**不要**自动重试：`TL_CHAIN_SWAP_FAILED` 不可重试——先用 `tl_chain_get_tx` 核对链上状态（见「兑换安全」）。 + --- ## 快速开始 @@ -703,10 +721,10 @@ npm install && npm run build export TL_TRONGRID_URL="https://nile.trongrid.io" # 3. 如果本地还没有钱包，二选一： -# 方案 A：在 MCP 会话里调用 tl_wallet_create -# 方案 B：本地执行 -# agent-wallet start local_secure --generate --wallet-id main -# 然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD +# 路径 A（手动）：本地执行 +# agent-wallet start local_secure --generate --wallet-id main +# 然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD +# 路径 B（自动创建）：在 MCP 会话里调用 tl_wallet_create # 4. 配合 Claude Code 使用 # 配置好 .mcp.json 后自然语言使用： @@ -715,6 +733,17 @@ export TL_TRONGRID_URL="https://nile.trongrid.io" # "在 SunSwap V3 上用 100 TRX 兑换 USDT" ``` +**该选哪条路径？（场景 → 路径）** + +| 场景 | 推荐路径 | 原因 | +|------|---------|------| +| 生产环境（真实资金） | A — 手动创建 + secret manager | 路径 B 会把密码以明文写入 `~/.agent-wallet/runtime_secrets.json` | +| CI / 自动化（测试网） | A — 手动创建 + env 注入 | 同上——避免密码落盘到文件 | +| 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 | +| 临时 demo 演示 | B + tmpfs 目录 | 把 `AGENT_WALLET_DIR` 指到任务结束即销毁的 tmpfs | + +> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#钱包密钥存储)。 + ## 版本与许可证 - **包：** `@tronlink/mcp-server-tronlink` v0.1.1 diff --git a/docs/ai-support/mcp-tronlink-signer.en.md b/docs/ai-support/mcp-tronlink-signer.en.md index 5d99315..a13d11c 100644 --- a/docs/ai-support/mcp-tronlink-signer.en.md +++ b/docs/ai-support/mcp-tronlink-signer.en.md @@ -4,6 +4,22 @@ MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet. +> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version--license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. + +## Which to use + +TronLink ships three ways to let an AI agent act on Tron. Pick based on whether a human must approve each transaction and where the agent runs. + +| | `mcp-tronlink-signer` (this server) | `mcp-server-tronlink` (Direct-API mode) | `tronlink-cli` | +| --- | --- | --- | --- | +| Approval | HITL — user approves every transaction in the browser | No HITL — signs automatically | HITL — user approves in the browser | +| Credentials on host | None (keys stay in the TronLink extension) | Uses `AGENT_WALLET_PASSWORD` to unlock a local wallet | None (keys stay in the TronLink extension) | +| Interface | MCP server | MCP server | Shell / command line | +| Best for | Agents that should never move funds without explicit human sign-off | Automated, unattended flows: CI, testnet scripting | Interactive terminal use with human sign-off | +| Private-key exposure | Lowest | Higher (credential on host) | Lowest | + +If unsure, prefer `mcp-tronlink-signer` (safest default). + ## Setup ### Claude Code @@ -56,6 +72,55 @@ All tools support an optional `network` parameter (`mainnet` / `nile` / `shasta` **Human-in-the-loop.** Every tool that signs (`send_trx`, `send_trc20`, `sign_message`, `sign_typed_data`, `sign_transaction`) opens the TronLink approval page in the browser. The AI agent **cannot** sign without the user clicking Approve. Treat Remote Write tools as requiring confirmation in production. +### Selected tool schemas (inline mirror) + +Docs-side mirrors of the core write tools' inputs, derived from the tool parameters documented in the table above — useful when an agent is writing a tool-call site without an MCP session open. Field names and the required set are mirrored here; runtime `list_tools` remains the authoritative source for the full input schemas (exact field types, defaults, and any Zod metadata). + +`send_trx`: + +```json +{ + "type": "object", + "properties": { + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Amount of TRX to send" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["to", "amount"] +} +``` + +`send_trc20`: + +```json +{ + "type": "object", + "properties": { + "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" }, + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Token amount to send" }, + "decimals": { "description": "Optional token decimals" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["contractAddress", "to", "amount"] +} +``` + +`sign_typed_data`: + +```json +{ + "type": "object", + "properties": { + "typedData": { "description": "EIP-712 typed-data object to sign" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["typedData"] +} +``` + +> Field types above are intentionally left unspecified where they could not be confirmed against the upstream Zod definitions; consult `list_tools` for the exact types. `sign_message` (`message`, `network?`) and `sign_transaction` (`transaction`, `broadcast`, `network?`) follow the same parameter shapes shown in the tool table. + ## MCP Resources | URI | Description | @@ -172,6 +237,8 @@ The server returns errors in the standard MCP shape. Each error carries a stable This page mirrors a downstream README; for the source of truth see the GitHub releases above and the `CHANGELOG.md` in each package. Entries below cover the **MCP-visible** surface (tools, schema, security boundaries) — internal refactors are omitted. +> **Sync policy.** This inline changelog mirrors the package `CHANGELOG.md` / README; the project's **GitHub releases are the authoritative source**. This page may lag a release by a short window until the docs are updated, so verify against the GitHub releases (and `list_tools`) when an exact version matters. + #### v0.1.4 _(npm-only, not GitHub-tagged at time of writing)_ Patch-only. No new tools, no breaking input/output shapes. Verify against `list_tools` after upgrade. diff --git a/docs/ai-support/mcp-tronlink-signer.zh.md b/docs/ai-support/mcp-tronlink-signer.zh.md index 33667db..e6e5ddd 100644 --- a/docs/ai-support/mcp-tronlink-signer.zh.md +++ b/docs/ai-support/mcp-tronlink-signer.zh.md @@ -4,6 +4,22 @@ 将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具的服务器，供 Claude 及其他 AI 客户端使用。通过 TronLink 浏览器钱包对 TRON 交易进行签名，需用户在浏览器中授权确认 — 私钥始终留在钱包中，不会对外暴露。 +> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#版本与许可证)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。 + +## 该用哪个 + +TronLink 提供了三种方式让 AI 智能体在 Tron 上执行操作。请根据是否需要人工审批每一笔交易、以及智能体运行在何处来选择。 + +| | `mcp-tronlink-signer`（本服务器） | `mcp-server-tronlink`（Direct-API 模式） | `tronlink-cli` | +| --- | --- | --- | --- | +| 审批 | HITL —— 用户在浏览器中审批每一笔交易 | 无 HITL —— 自动签名 | HITL —— 用户在浏览器中审批 | +| 主机上的凭证 | 无（私钥保留在 TronLink 扩展内） | 使用 `AGENT_WALLET_PASSWORD` 解锁本地钱包 | 无（私钥保留在 TronLink 扩展内） | +| 接口形态 | MCP 服务器 | MCP 服务器 | Shell / 命令行 | +| 适用场景 | 任何资金转移都必须经人工显式签字确认的智能体 | 自动化、无人值守流程：CI、测试网脚本 | 需要人工签字确认的交互式终端使用 | +| 私钥暴露风险 | 最低 | 较高（凭证位于主机上） | 最低 | + +如果不确定，优先选择 `mcp-tronlink-signer`（最安全的默认选项）。 + ## 配置 ### Claude Code @@ -56,6 +72,55 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si **人工确认（HITL）。** 所有涉及签名的工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 浏览器审批页。AI agent **无法**在用户点击 Approve 之前签名。生产环境必须把 Remote Write 工具视为需要确认。 +### 部分工具 Schema（内联镜像） + +以下是核心写操作工具入参的文档侧镜像，依据上方工具表中记录的参数整理而成 —— 在没有 MCP 会话时，便于智能体离线编写工具调用。这里镜像的是字段名与 required 集合；运行时 `list_tools` 仍是完整输入 schema（精确字段类型、默认值及 Zod 元数据）的权威来源。 + +`send_trx`： + +```json +{ + "type": "object", + "properties": { + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Amount of TRX to send" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["to", "amount"] +} +``` + +`send_trc20`： + +```json +{ + "type": "object", + "properties": { + "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" }, + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Token amount to send" }, + "decimals": { "description": "Optional token decimals" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["contractAddress", "to", "amount"] +} +``` + +`sign_typed_data`： + +```json +{ + "type": "object", + "properties": { + "typedData": { "description": "EIP-712 typed-data object to sign" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["typedData"] +} +``` + +> 凡无法对照上游 Zod 定义确认的字段类型，上面均有意留空；精确类型请查 `list_tools`。`sign_message`（`message`、`network?`）与 `sign_transaction`（`transaction`、`broadcast`、`network?`）遵循工具表中所示的同样参数形态。 + ## MCP 资源 | URI | 说明 | @@ -172,6 +237,8 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r 本页是下游 README 镜像；以 GitHub releases 与各包 `CHANGELOG.md` 为准。下方条目只覆盖 **MCP 可见面**（工具、schema、安全边界），内部重构不列。 +> **同步策略。** 此内联 changelog 镜像软件包的 `CHANGELOG.md` / README；项目的 **GitHub releases 为权威来源**。在文档更新之前，本页可能比某个发布版本短暂滞后，因此当需要精确版本号时，请以 GitHub releases（以及 `list_tools`）为准核对。 + #### v0.1.4 _(仅 npm，截至本文写就尚未在 GitHub 打 tag)_ 仅 patch 修复。无新工具、无破坏性输入/输出 shape 变化。升级后用 `list_tools` 复核。 diff --git a/docs/ai-support/tronlink-cli.en.md b/docs/ai-support/tronlink-cli.en.md index c2e44d1..0af6ded 100644 --- a/docs/ai-support/tronlink-cli.en.md +++ b/docs/ai-support/tronlink-cli.en.md @@ -435,11 +435,13 @@ tronlink reward --json ### Common Token Contracts -| Token | Network | Contract | -| ----- | ------- | ----------------------------------- | -| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | -| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | -| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The table below is a subset reconciled to that SSOT. + +| Token | Network | Contract | Decimals | +| ----- | ------- | ----------------------------------- | -------- | +| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 | +| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 | +| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 | ### Example: AI Transfer Flow diff --git a/docs/ai-support/tronlink-cli.zh.md b/docs/ai-support/tronlink-cli.zh.md index c42a2d8..b0e33fc 100644 --- a/docs/ai-support/tronlink-cli.zh.md +++ b/docs/ai-support/tronlink-cli.zh.md @@ -431,11 +431,13 @@ tronlink reward --json ### 常用代币合约 -| 代币 | 网络 | 合约地址 | -| ---- | ---- | -------- | -| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | -| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | -| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下表为对齐该 SSOT 的子集。 + +| 代币 | 网络 | 合约地址 | 精度 | +| ---- | ---- | -------- | ---- | +| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 | +| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 | +| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 | ### 示例：AI 转账流程 diff --git a/docs/ai-support/tronlink-mcp-core.en.md b/docs/ai-support/tronlink-mcp-core.en.md index 4da7a52..ddb9c3a 100644 --- a/docs/ai-support/tronlink-mcp-core.en.md +++ b/docs/ai-support/tronlink-mcp-core.en.md @@ -60,6 +60,18 @@ flowchart TD **mcp-server-tronlink is a consumer of tronlink-mcp-core.** The core defines WHAT tools exist; the server provides HOW they work. +### Which one should I pick? + +Use this decision matrix to choose between the two packages by scenario: + +| Scenario | Pick tronlink-mcp-core | Pick mcp-server-tronlink | +|----------|:---:|:---:| +| Building a custom MCP server that embeds your own business logic | ✅ | | +| Giving a ready-to-run server directly to an agent | | ✅ | +| Extending capabilities with a custom `Capability` implementation | ✅ | | +| Testing or mocking with injectable fixtures / mock server | ✅ | | +| Learning how the MCP framework (interfaces, tools, response format) works | ✅ | | + --- ## ISessionManager Interface diff --git a/docs/ai-support/tronlink-mcp-core.zh.md b/docs/ai-support/tronlink-mcp-core.zh.md index 3024d60..ff21d6f 100644 --- a/docs/ai-support/tronlink-mcp-core.zh.md +++ b/docs/ai-support/tronlink-mcp-core.zh.md @@ -60,6 +60,18 @@ flowchart TD **mcp-server-tronlink 是 tronlink-mcp-core 的使用者。** 核心库定义了工具"是什么"；服务器提供了工具"怎么工作"。 +### 该选哪个？ + +按场景用下面的决策矩阵在两个包之间做选择： + +| 场景 | 选 tronlink-mcp-core | 选 mcp-server-tronlink | +|------|:---:|:---:| +| 构建嵌入自有业务逻辑的自定义 MCP 服务器 | ✅ | | +| 直接把一个开箱即用的服务器交给 agent 使用 | | ✅ | +| 通过自定义 `Capability` 实现扩展能力 | ✅ | | +| 用可注入的 fixture / mock server 做测试或 mock | ✅ | | +| 学习 MCP 框架（接口、工具、响应格式）的工作原理 | ✅ | | + --- ## ISessionManager 接口 diff --git a/docs/ai-support/tronlink-skills.en.md b/docs/ai-support/tronlink-skills.en.md index 2e3e958..9cabf72 100644 --- a/docs/ai-support/tronlink-skills.en.md +++ b/docs/ai-support/tronlink-skills.en.md @@ -264,6 +264,22 @@ tron-wallet (check balance) → tron-staking (staking info) → tron-staking (AP tron-resource (check status) → tron-resource (estimate cost) → tron-resource (optimize-cost) ``` +### End-to-end examples + +**"Is swapping 100 TRX for USDT worth it right now?"** + +1. `token-price` (`tron-market`) — fetch current TRX and USDT prices to establish the reference value of 100 TRX. +2. `kline` (`tron-market`) — pull recent candlesticks to judge whether TRX is trending up or down (timing). +3. `resource-info` (`tron-resource`) — check the account's Energy/Bandwidth so the agent can estimate whether the swap will have to burn TRX for fees. +4. `swap-quote` (`tron-swap`) — request an actual quote for 100 TRX → USDT, including expected output and price impact. +5. The agent compares the quote's effective rate against the spot price from step 1, factors in the resource cost from step 3, and answers whether the swap is favorable. These steps are **read-only** — to actually execute, route to `mcp-server-tronlink` `tl_chain_swap_v3` (Remote Write, HITL, set `minOut`) or the [signer SDK](tronlink-signer.md). + +**"Did my last USDT transfer go through, and what's my balance now?"** + +1. `tx-status` (`tron-swap`) — look up the most recent transfer's status and confirmations. +2. `account-info` (`tron-wallet`) — confirm the current balances after that transfer settled. +3. `resource-info` (`tron-resource`) — verify enough Energy/Bandwidth remains for a follow-up transfer (otherwise it would burn TRX). Sending the next transfer is a Remote Write — route to the [signer SDK](tronlink-signer.md) `sendTrc20` or `mcp-server-tronlink` `tl_chain_send`. + --- ## TRON Resource Model Reference @@ -416,6 +432,16 @@ export TRONGRID_API_KEY="your-api-key" export TRON_NETWORK="mainnet" # or "shasta" / "nile" ``` +#### TronGrid API key — credential management + +`TRONGRID_API_KEY` is optional (read-only, higher rate limits), but if you set one, manage it across these five dimensions: + +- **Storage** — keep it in an environment variable or a secrets manager. Never hardcode it in source, in config committed to git, or in chat/agent logs. +- **Least-privilege** — provision a key scoped only to the read endpoints these skills call; don't reuse a broader production key. +- **Rotation** — rotate on a fixed schedule, and whenever someone with access leaves; keep the rotation window short. +- **Leak-detection** — monitor TronGrid usage for anomalous call volume or unexpected source IPs, and scan repository history with a secret scanner for accidental commits. +- **Revocation** — if a key leaks, revoke it immediately in the TronGrid dashboard and issue a fresh one before resuming traffic. + ### Network Support | Network | URL | Use Case | @@ -426,11 +452,14 @@ export TRON_NETWORK="mainnet" # or "shasta" / "nile" ### Built-In Token Shortcuts +> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The shortcuts below are reconciled to that SSOT. The symbols recognized by `tron_api.mjs` are TRX, USDT, USDC, WTRX, BTT, JST, SUN, WIN; USDD is included below for consistency with the SSOT — pass its contract address explicitly. + | Symbol | Contract Address | |--------|------------------| | TRX | Native (no contract) | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | @@ -498,6 +527,18 @@ tronlink-skills/ --- +## Troubleshooting + +| Symptom | Cause | What to do | +|---------|-------|------------| +| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill--mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | +| TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). | +| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill--mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | +| `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. | +| Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add `), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. | + +--- + ## Address Format Support Both formats are supported and auto-normalized across all commands: diff --git a/docs/ai-support/tronlink-skills.zh.md b/docs/ai-support/tronlink-skills.zh.md index d40a626..c1f5934 100644 --- a/docs/ai-support/tronlink-skills.zh.md +++ b/docs/ai-support/tronlink-skills.zh.md @@ -264,6 +264,22 @@ tron-wallet（查余额）→ tron-staking（质押信息）→ tron-staking（A tron-resource（检查状态）→ tron-resource（估算成本）→ tron-resource（optimize-cost） ``` +### 端到端示例 + +**"把 100 TRX 换成 USDT 现在划算吗？"** + +1. `token-price`（`tron-market`）—— 获取 TRX 与 USDT 当前价格，确定 100 TRX 的参考价值。 +2. `kline`（`tron-market`）—— 拉取近期 K 线，判断 TRX 处于上行还是下行趋势（择时）。 +3. `resource-info`（`tron-resource`）—— 查询账户的能量/带宽，便于估算本次兑换是否需要燃烧 TRX 抵扣手续费。 +4. `swap-quote`（`tron-swap`）—— 对 100 TRX → USDT 请求实际报价，含预期到账数量与价格冲击。 +5. 智能体将报价的有效汇率与第 1 步现货价对比，结合第 3 步的资源成本，回答兑换是否划算。以上均为**只读**——若要真正执行，请路由到 `mcp-server-tronlink` 的 `tl_chain_swap_v3`（Remote Write、HITL，必传 `minOut`）或 [signer SDK](tronlink-signer.md)。 + +**"我上一笔 USDT 转账到账了吗？现在余额多少？"** + +1. `tx-status`（`tron-swap`）—— 查询最近一笔转账的状态与确认数。 +2. `account-info`（`tron-wallet`）—— 确认该转账结算后的当前余额。 +3. `resource-info`（`tron-resource`）—— 核对剩余能量/带宽是否足够下一笔转账（否则将燃烧 TRX）。发送下一笔转账属于 Remote Write——请路由到 [signer SDK](tronlink-signer.md) 的 `sendTrc20` 或 `mcp-server-tronlink` 的 `tl_chain_send`。 + --- ## TRON 资源模型参考 @@ -416,6 +432,16 @@ export TRONGRID_API_KEY="your-api-key" export TRON_NETWORK="mainnet" # 或 "shasta" / "nile" ``` +#### TronGrid API Key —— 凭证管理 + +`TRONGRID_API_KEY` 是可选的（只读、提高限额），但一旦配置，请从以下五个维度管理： + +- **存储** —— 保存在环境变量或密钥管理器中。切勿硬编码在源码、提交到 git 的配置或聊天/智能体日志里。 +- **最小权限** —— 只签发覆盖这些技能所需只读端点的 Key，不要复用更大权限的生产 Key。 +- **轮换** —— 按固定周期轮换，有访问权限的成员离职时也应轮换；保持轮换窗口尽量短。 +- **泄漏检测** —— 监控 TronGrid 用量是否出现异常调用量或非预期来源 IP，并用密钥扫描器扫描仓库历史排查误提交。 +- **吊销** —— 一旦 Key 泄漏，立即在 TronGrid 控制台吊销并签发新 Key，再恢复流量。 + ### 网络支持 | 网络 | 地址 | 用途 | @@ -426,11 +452,14 @@ export TRON_NETWORK="mainnet" # 或 "shasta" / "nile" ### 内置代币快捷符号 +> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下方快捷符号已对齐该 SSOT。`tron_api.mjs` 实际内置可识别的符号为 TRX、USDT、USDC、WTRX、BTT、JST、SUN、WIN；USDD 为与 SSOT 保持一致而一并列出——请显式传入其合约地址使用。 + | 符号 | 合约地址 | |------|----------| | TRX | 原生代币（无合约） | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | @@ -498,6 +527,18 @@ tronlink-skills/ --- +## 故障排查 + +| 现象 | 原因 | 处理方式 | +|------|------|----------| +| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#6) / [Skill ↔ MCP 工具映射](#skill--mcp) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | +| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#_1)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | +| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill--mcp)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | +| `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 | +| 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add `），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 | + +--- + ## 地址格式支持 所有命令均支持并自动归一化两种格式： diff --git a/docs/llms-full.en.txt b/docs/llms-full.en.txt index ec9e1d5..20ed135 100644 --- a/docs/llms-full.en.txt +++ b/docs/llms-full.en.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-21T14:08:15Z -- Commit: e724781c635f +- Generated: 2026-05-29T07:38:28Z +- Commit: 32e3353ef15b - Language: en - Pages: 23 -- Token estimate: ~56,926 (chars / 4) +- Token estimate: ~60,362 (chars / 4) --- @@ -240,6 +240,7 @@ Plus the DApp integration, mobile (DeepLink), and Reference (networks, glossary, - For tool calls, branch on the structured `error.code` / `error.retryable`, never on the human-readable `message`. - Read operations are safe to retry; signing / Remote Write operations require user approval (HITL) and must not be auto-retried — see each tool's Safety section. - Default to testnets (`nile` / `shasta`) when experimenting; use `mainnet` only for real funds. +- Version contracts: each tool page documents what is stable vs. volatile under its Compatibility & Migration section — consult it before pinning to any name, flag, or output field. --- @@ -2232,7 +2233,9 @@ Runtime wallet management via `@bankofai/agent-wallet` (encrypted `local_secure` - `tl_wallet_set_active` — Switch the active wallet by ID (hot-swaps into all capabilities) If no wallet exists at startup, the server prompts two paths: call `tl_wallet_create` to auto-generate one, or create one manually via CLI and set `AGENT_WALLET_PASSWORD`. -The auto-create path generates a random password, saves it to `~/.agent-wallet/runtime_secrets.json`, creates an encrypted `main` wallet, and enables the running session to use it. + +!!! warning "Auto-create writes the password to disk in plaintext — test/dev only" + The auto-create path generates a random password and saves it **in plaintext** to `~/.agent-wallet/runtime_secrets.json`, then creates an encrypted `main` wallet and lets the running session use it. Anyone with read access to that file controls the wallet. For production, use the manual path: create the wallet out-of-band and inject `AGENT_WALLET_PASSWORD` from a secret manager — never rely on the on-disk plaintext password. ### 6. TRON Cryptography Utils @@ -2255,44 +2258,44 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256). Pre-configured multi-step workflows with dependency checks and parameter templates. ### Playwright Flows -| Flow | Description | -|------|-------------| -| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | -| `enableTestNetworksFlow` | Enable testnet visibility | -| `transferTrxFlow` | TRX transfer via UI | -| `transferTokenFlow` | Token transfer via UI | +| Flow | Description | Source File | +|------|-------------|-------------| +| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | `src/flows/switch-network.ts` | +| `enableTestNetworksFlow` | Enable testnet visibility | `src/flows/switch-network.ts` | +| `transferTrxFlow` | TRX transfer via UI | `src/flows/transfer-trx.ts` | +| `transferTokenFlow` | Token transfer via UI | `src/flows/transfer-trx.ts` | ### On-Chain Flows (11) -| Flow | Description | -|------|-------------| -| `chainCheckBalanceFlow` | Query balance | -| `chainTransferTrxFlow` | TRX transfer with pre-checks | -| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | -| `chainStakeFlow` | Stake TRX | -| `chainUnstakeFlow` | Unstake TRX | -| `chainGetStakingFlow` | Query staking info | -| `chainDelegateResourceFlow` | Delegate bandwidth/energy | -| `chainUndelegateResourceFlow` | Undelegate resources | -| `chainSetupMultisigFlow` | Setup multi-sig permissions | -| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | -| `chainSwapV3Flow` | SunSwap V3 token swap | +| Flow | Description | Source File | +|------|-------------|-------------| +| `chainCheckBalanceFlow` | Query balance | `src/flows/onchain.ts` | +| `chainTransferTrxFlow` | TRX transfer with pre-checks | `src/flows/onchain.ts` | +| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | `src/flows/onchain.ts` | +| `chainStakeFlow` | Stake TRX | `src/flows/onchain.ts` | +| `chainUnstakeFlow` | Unstake TRX | `src/flows/onchain.ts` | +| `chainGetStakingFlow` | Query staking info | `src/flows/onchain.ts` | +| `chainDelegateResourceFlow` | Delegate bandwidth/energy | `src/flows/onchain.ts` | +| `chainUndelegateResourceFlow` | Undelegate resources | `src/flows/onchain.ts` | +| `chainSetupMultisigFlow` | Setup multi-sig permissions | `src/flows/onchain.ts` | +| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | `src/flows/onchain.ts` | +| `chainSwapV3Flow` | SunSwap V3 token swap | `src/flows/onchain.ts` | ### Multi-Sig Flows (6) -| Flow | Description | -|------|-------------| -| `multisigQueryAuthFlow` | Query permissions | -| `multisigListTransactionsFlow` | List pending transactions | -| `multisigMonitorFlow` | WebSocket real-time monitoring | -| `multisigStopMonitorFlow` | Stop monitoring | -| `multisigSubmitTxFlow` | Submit signed transaction | -| `multisigCheckFlow` | Full status check | +| Flow | Description | Source File | +|------|-------------|-------------| +| `multisigQueryAuthFlow` | Query permissions | `src/flows/multisig.ts` | +| `multisigListTransactionsFlow` | List pending transactions | `src/flows/multisig.ts` | +| `multisigMonitorFlow` | WebSocket real-time monitoring | `src/flows/multisig.ts` | +| `multisigStopMonitorFlow` | Stop monitoring | `src/flows/multisig.ts` | +| `multisigSubmitTxFlow` | Submit signed transaction | `src/flows/multisig.ts` | +| `multisigCheckFlow` | Full status check | `src/flows/multisig.ts` | ### GasFree Flows (3) -| Flow | Description | -|------|-------------| -| `gasfreeCheckAccountFlow` | Query eligibility | -| `gasfreeTransactionHistoryFlow` | Query history | -| `gasfreeSendFlow` | Gas-free TRC20 transfer | +| Flow | Description | Source File | +|------|-------------|-------------| +| `gasfreeCheckAccountFlow` | Query eligibility | `src/flows/gasfree.ts` | +| `gasfreeTransactionHistoryFlow` | Query history | `src/flows/gasfree.ts` | +| `gasfreeSendFlow` | Gas-free TRC20 transfer | `src/flows/gasfree.ts` | --- @@ -2496,9 +2499,11 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump | `@noble/hashes` | ^2.0.1 | Keccak-256, SHA256 | | `@tronlink/tronlink-mcp-core` | ^0.1.0 | Core MCP server framework | | `playwright` | ^1.49.0 | Browser automation | -| `@bankofai/agent-wallet` | ^2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible | +| `@bankofai/agent-wallet` | 2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible | | `ws` | ^8.18.0 | WebSocket (multi-sig monitoring) | +> **About @bankofai/agent-wallet:** Pinned to exact 2.3.0 (no caret, to avoid silently picking up 2.4.0 on npm). The package's GitHub repo is currently not public (HTTP 404); source transparency comes from the npm publish — audit it via `npm pack @bankofai/agent-wallet@2.3.0`. Upgrading to 2.4.0 should be evaluated against its changelog first. + --- ## Tool Contract & Side Effects @@ -2776,6 +2781,20 @@ The Direct-API path signs with a local encrypted wallet managed by `@bankofai/ag 5. **Gas-Free Operations** — TRC20 transfers without TRX balance requirements 6. **Infrastructure Testing** — Contract deployment, fixture management, mock servers +### End-to-end example: swap 100 TRX for USDT on SunSwap V3 + +A realistic agent turn, showing the tool-call sequence. The agent reads first, gets a fresh quote, surfaces it for human approval, then executes — never auto-executing a Remote Write off a read. + +> **User:** "Swap 100 TRX for USDT on SunSwap V3, max 0.5% slippage." + +1. `tl_chain_get_account` (Network Read) — confirm the active wallet holds ≥ 100 TRX plus enough for fees. +2. `tl_chain_swap_v3` with `action=estimate` (Network Read) — `from_token="TRX"`, `to_token=""`, `amount="100"`, `fee_tier=3000`, `slippage=0.5`. Returns the quoted output and route. +3. Agent surfaces the quote to the user and waits for confirmation (HITL — this is a Remote Write). +4. `tl_chain_swap_v3` with `action=execute` and the **same** explicit `slippage=0.5` — signs with the local `agent-wallet` and broadcasts. Returns `txId`. +5. `tl_chain_get_tx` (Network Read) with the returned `txId` — confirm on-chain success before reporting back. + +> If step 4 returns an uncertain/failed result, do **not** auto-retry: `TL_CHAIN_SWAP_FAILED` is not retryable — re-check the chain with `tl_chain_get_tx` first (see Swap safety). + --- ## Quick Start @@ -2789,8 +2808,8 @@ npm install && npm run build # TL_TRONGRID_URL=https://nile.trongrid.io # # 3. If no wallet exists, choose one path: -# Option A: call tl_wallet_create after startup -# Option B: create one locally, then set AGENT_WALLET_PASSWORD +# Option A (manual): create one locally, then set AGENT_WALLET_PASSWORD +# Option B (auto-create): call tl_wallet_create after startup # 4. Use with Claude Code # "Check my TRX balance" @@ -2798,6 +2817,17 @@ npm install && npm run build # "Swap 100 TRX for USDT on SunSwap V3" ``` +**Which path? (scenario → path)** + +| Scenario | Recommended path | Why | +|----------|------------------|-----| +| Production (real funds) | A — manual + secret manager | Path B writes the password in plaintext to `~/.agent-wallet/runtime_secrets.json` | +| CI / automation (testnet) | A — manual + env injection | Same — keep the password out of an on-disk file | +| Local dev (one-off) | B — auto-create | No pre-config; the password is generated automatically | +| Temp demo | B + tmpfs directory | Point `AGENT_WALLET_DIR` at a tmpfs path destroyed at job end | + +> Path B (auto-create) writes the generated password in plaintext to `~/.agent-wallet/runtime_secrets.json` so a restart can reuse the wallet. See [Wallet Secret Storage](#wallet-secret-storage) for the full Path A / Path B comparison and how to enforce Path A. + ## Version & License - **Package:** `@tronlink/mcp-server-tronlink` v0.1.1 @@ -2886,6 +2916,18 @@ flowchart TD **mcp-server-tronlink is a consumer of tronlink-mcp-core.** The core defines WHAT tools exist; the server provides HOW they work. +### Which one should I pick? + +Use this decision matrix to choose between the two packages by scenario: + +| Scenario | Pick tronlink-mcp-core | Pick mcp-server-tronlink | +|----------|:---:|:---:| +| Building a custom MCP server that embeds your own business logic | ✅ | | +| Giving a ready-to-run server directly to an agent | | ✅ | +| Extending capabilities with a custom `Capability` implementation | ✅ | | +| Testing or mocking with injectable fixtures / mock server | ✅ | | +| Learning how the MCP framework (interfaces, tools, response format) works | ✅ | | + --- ## ISessionManager Interface @@ -3750,6 +3792,22 @@ tron-wallet (check balance) → tron-staking (staking info) → tron-staking (AP tron-resource (check status) → tron-resource (estimate cost) → tron-resource (optimize-cost) ``` +### End-to-end examples + +**"Is swapping 100 TRX for USDT worth it right now?"** + +1. `token-price` (`tron-market`) — fetch current TRX and USDT prices to establish the reference value of 100 TRX. +2. `kline` (`tron-market`) — pull recent candlesticks to judge whether TRX is trending up or down (timing). +3. `resource-info` (`tron-resource`) — check the account's Energy/Bandwidth so the agent can estimate whether the swap will have to burn TRX for fees. +4. `swap-quote` (`tron-swap`) — request an actual quote for 100 TRX → USDT, including expected output and price impact. +5. The agent compares the quote's effective rate against the spot price from step 1, factors in the resource cost from step 3, and answers whether the swap is favorable. These steps are **read-only** — to actually execute, route to `mcp-server-tronlink` `tl_chain_swap_v3` (Remote Write, HITL, set `minOut`) or the [signer SDK](tronlink-signer.md). + +**"Did my last USDT transfer go through, and what's my balance now?"** + +1. `tx-status` (`tron-swap`) — look up the most recent transfer's status and confirmations. +2. `account-info` (`tron-wallet`) — confirm the current balances after that transfer settled. +3. `resource-info` (`tron-resource`) — verify enough Energy/Bandwidth remains for a follow-up transfer (otherwise it would burn TRX). Sending the next transfer is a Remote Write — route to the [signer SDK](tronlink-signer.md) `sendTrc20` or `mcp-server-tronlink` `tl_chain_send`. + --- ## TRON Resource Model Reference @@ -3902,6 +3960,16 @@ export TRONGRID_API_KEY="your-api-key" export TRON_NETWORK="mainnet" # or "shasta" / "nile" ``` +#### TronGrid API key — credential management + +`TRONGRID_API_KEY` is optional (read-only, higher rate limits), but if you set one, manage it across these five dimensions: + +- **Storage** — keep it in an environment variable or a secrets manager. Never hardcode it in source, in config committed to git, or in chat/agent logs. +- **Least-privilege** — provision a key scoped only to the read endpoints these skills call; don't reuse a broader production key. +- **Rotation** — rotate on a fixed schedule, and whenever someone with access leaves; keep the rotation window short. +- **Leak-detection** — monitor TronGrid usage for anomalous call volume or unexpected source IPs, and scan repository history with a secret scanner for accidental commits. +- **Revocation** — if a key leaks, revoke it immediately in the TronGrid dashboard and issue a fresh one before resuming traffic. + ### Network Support | Network | URL | Use Case | @@ -3912,11 +3980,14 @@ export TRON_NETWORK="mainnet" # or "shasta" / "nile" ### Built-In Token Shortcuts +> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The shortcuts below are reconciled to that SSOT. The symbols recognized by `tron_api.mjs` are TRX, USDT, USDC, WTRX, BTT, JST, SUN, WIN; USDD is included below for consistency with the SSOT — pass its contract address explicitly. + | Symbol | Contract Address | |--------|------------------| | TRX | Native (no contract) | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | @@ -3984,6 +4055,18 @@ tronlink-skills/ --- +## Troubleshooting + +| Symptom | Cause | What to do | +|---------|-------|------------| +| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill--mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | +| TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). | +| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill--mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | +| `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. | +| Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add `), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. | + +--- + ## Address Format Support Both formats are supported and auto-normalized across all commands: @@ -4060,6 +4143,22 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet. +> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version--license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. + +## Which to use + +TronLink ships three ways to let an AI agent act on Tron. Pick based on whether a human must approve each transaction and where the agent runs. + +| | `mcp-tronlink-signer` (this server) | `mcp-server-tronlink` (Direct-API mode) | `tronlink-cli` | +| --- | --- | --- | --- | +| Approval | HITL — user approves every transaction in the browser | No HITL — signs automatically | HITL — user approves in the browser | +| Credentials on host | None (keys stay in the TronLink extension) | Uses `AGENT_WALLET_PASSWORD` to unlock a local wallet | None (keys stay in the TronLink extension) | +| Interface | MCP server | MCP server | Shell / command line | +| Best for | Agents that should never move funds without explicit human sign-off | Automated, unattended flows: CI, testnet scripting | Interactive terminal use with human sign-off | +| Private-key exposure | Lowest | Higher (credential on host) | Lowest | + +If unsure, prefer `mcp-tronlink-signer` (safest default). + ## Setup ### Claude Code @@ -4112,6 +4211,55 @@ All tools support an optional `network` parameter (`mainnet` / `nile` / `shasta` **Human-in-the-loop.** Every tool that signs (`send_trx`, `send_trc20`, `sign_message`, `sign_typed_data`, `sign_transaction`) opens the TronLink approval page in the browser. The AI agent **cannot** sign without the user clicking Approve. Treat Remote Write tools as requiring confirmation in production. +### Selected tool schemas (inline mirror) + +Docs-side mirrors of the core write tools' inputs, derived from the tool parameters documented in the table above — useful when an agent is writing a tool-call site without an MCP session open. Field names and the required set are mirrored here; runtime `list_tools` remains the authoritative source for the full input schemas (exact field types, defaults, and any Zod metadata). + +`send_trx`: + +```json +{ + "type": "object", + "properties": { + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Amount of TRX to send" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["to", "amount"] +} +``` + +`send_trc20`: + +```json +{ + "type": "object", + "properties": { + "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" }, + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Token amount to send" }, + "decimals": { "description": "Optional token decimals" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["contractAddress", "to", "amount"] +} +``` + +`sign_typed_data`: + +```json +{ + "type": "object", + "properties": { + "typedData": { "description": "EIP-712 typed-data object to sign" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["typedData"] +} +``` + +> Field types above are intentionally left unspecified where they could not be confirmed against the upstream Zod definitions; consult `list_tools` for the exact types. `sign_message` (`message`, `network?`) and `sign_transaction` (`transaction`, `broadcast`, `network?`) follow the same parameter shapes shown in the tool table. + ## MCP Resources | URI | Description | @@ -4228,6 +4376,8 @@ The server returns errors in the standard MCP shape. Each error carries a stable This page mirrors a downstream README; for the source of truth see the GitHub releases above and the `CHANGELOG.md` in each package. Entries below cover the **MCP-visible** surface (tools, schema, security boundaries) — internal refactors are omitted. +> **Sync policy.** This inline changelog mirrors the package `CHANGELOG.md` / README; the project's **GitHub releases are the authoritative source**. This page may lag a release by a short window until the docs are updated, so verify against the GitHub releases (and `list_tools`) when an exact version matters. + #### v0.1.4 _(npm-only, not GitHub-tagged at time of writing)_ Patch-only. No new tools, no breaking input/output shapes. Verify against `list_tools` after upgrade. @@ -5031,11 +5181,13 @@ tronlink reward --json ### Common Token Contracts -| Token | Network | Contract | -| ----- | ------- | ----------------------------------- | -| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | -| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | -| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The table below is a subset reconciled to that SSOT. + +| Token | Network | Contract | Decimals | +| ----- | ------- | ----------------------------------- | -------- | +| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 | +| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 | +| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 | ### Example: AI Transfer Flow @@ -5343,11 +5495,21 @@ TRON addresses have two interchangeable encodings: - `1 TRX = 1,000,000 SUN`. Amounts in `tronWeb` transaction builders (e.g. `sendTrx`) are expressed in **SUN**. -## Common token contracts (Mainnet) +## Common token contracts (SSOT) -| Token | Standard | Contract address | -|---|---|---| -| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | +This is the single source of truth (SSOT) for common mainnet token contract addresses. Other pages — [TronLink CLI](../ai-support/tronlink-cli.md) and [TronLink Skills](../ai-support/tronlink-skills.md) — reconcile to this table; when an address changes, update it here first. + +| Token | Standard | Mainnet contract address | Decimals | Notes | +|---|---|---|---|---| +| TRX | native | — | 6 | Native coin, no TRC-20 contract | +| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | | +| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | | +| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | | +| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX | +| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | | +| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | | +| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | | +| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | | For any other token, look up its contract address on [TronScan](https://tronscan.org/#/tokens). Always verify a token's contract address before integrating — addresses differ per network. diff --git a/docs/llms-full.txt b/docs/llms-full.txt index ec9e1d5..20ed135 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-21T14:08:15Z -- Commit: e724781c635f +- Generated: 2026-05-29T07:38:28Z +- Commit: 32e3353ef15b - Language: en - Pages: 23 -- Token estimate: ~56,926 (chars / 4) +- Token estimate: ~60,362 (chars / 4) --- @@ -240,6 +240,7 @@ Plus the DApp integration, mobile (DeepLink), and Reference (networks, glossary, - For tool calls, branch on the structured `error.code` / `error.retryable`, never on the human-readable `message`. - Read operations are safe to retry; signing / Remote Write operations require user approval (HITL) and must not be auto-retried — see each tool's Safety section. - Default to testnets (`nile` / `shasta`) when experimenting; use `mainnet` only for real funds. +- Version contracts: each tool page documents what is stable vs. volatile under its Compatibility & Migration section — consult it before pinning to any name, flag, or output field. --- @@ -2232,7 +2233,9 @@ Runtime wallet management via `@bankofai/agent-wallet` (encrypted `local_secure` - `tl_wallet_set_active` — Switch the active wallet by ID (hot-swaps into all capabilities) If no wallet exists at startup, the server prompts two paths: call `tl_wallet_create` to auto-generate one, or create one manually via CLI and set `AGENT_WALLET_PASSWORD`. -The auto-create path generates a random password, saves it to `~/.agent-wallet/runtime_secrets.json`, creates an encrypted `main` wallet, and enables the running session to use it. + +!!! warning "Auto-create writes the password to disk in plaintext — test/dev only" + The auto-create path generates a random password and saves it **in plaintext** to `~/.agent-wallet/runtime_secrets.json`, then creates an encrypted `main` wallet and lets the running session use it. Anyone with read access to that file controls the wallet. For production, use the manual path: create the wallet out-of-band and inject `AGENT_WALLET_PASSWORD` from a secret manager — never rely on the on-disk plaintext password. ### 6. TRON Cryptography Utils @@ -2255,44 +2258,44 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256). Pre-configured multi-step workflows with dependency checks and parameter templates. ### Playwright Flows -| Flow | Description | -|------|-------------| -| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | -| `enableTestNetworksFlow` | Enable testnet visibility | -| `transferTrxFlow` | TRX transfer via UI | -| `transferTokenFlow` | Token transfer via UI | +| Flow | Description | Source File | +|------|-------------|-------------| +| `switchNetworkFlow` | Switch to Mainnet/Nile/Shasta | `src/flows/switch-network.ts` | +| `enableTestNetworksFlow` | Enable testnet visibility | `src/flows/switch-network.ts` | +| `transferTrxFlow` | TRX transfer via UI | `src/flows/transfer-trx.ts` | +| `transferTokenFlow` | Token transfer via UI | `src/flows/transfer-trx.ts` | ### On-Chain Flows (11) -| Flow | Description | -|------|-------------| -| `chainCheckBalanceFlow` | Query balance | -| `chainTransferTrxFlow` | TRX transfer with pre-checks | -| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | -| `chainStakeFlow` | Stake TRX | -| `chainUnstakeFlow` | Unstake TRX | -| `chainGetStakingFlow` | Query staking info | -| `chainDelegateResourceFlow` | Delegate bandwidth/energy | -| `chainUndelegateResourceFlow` | Undelegate resources | -| `chainSetupMultisigFlow` | Setup multi-sig permissions | -| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | -| `chainSwapV3Flow` | SunSwap V3 token swap | +| Flow | Description | Source File | +|------|-------------|-------------| +| `chainCheckBalanceFlow` | Query balance | `src/flows/onchain.ts` | +| `chainTransferTrxFlow` | TRX transfer with pre-checks | `src/flows/onchain.ts` | +| `chainTransferTrc20Flow` | TRC20 transfer with pre-checks | `src/flows/onchain.ts` | +| `chainStakeFlow` | Stake TRX | `src/flows/onchain.ts` | +| `chainUnstakeFlow` | Unstake TRX | `src/flows/onchain.ts` | +| `chainGetStakingFlow` | Query staking info | `src/flows/onchain.ts` | +| `chainDelegateResourceFlow` | Delegate bandwidth/energy | `src/flows/onchain.ts` | +| `chainUndelegateResourceFlow` | Undelegate resources | `src/flows/onchain.ts` | +| `chainSetupMultisigFlow` | Setup multi-sig permissions | `src/flows/onchain.ts` | +| `chainCreateMultisigTxFlow` | Create unsigned multi-sig tx | `src/flows/onchain.ts` | +| `chainSwapV3Flow` | SunSwap V3 token swap | `src/flows/onchain.ts` | ### Multi-Sig Flows (6) -| Flow | Description | -|------|-------------| -| `multisigQueryAuthFlow` | Query permissions | -| `multisigListTransactionsFlow` | List pending transactions | -| `multisigMonitorFlow` | WebSocket real-time monitoring | -| `multisigStopMonitorFlow` | Stop monitoring | -| `multisigSubmitTxFlow` | Submit signed transaction | -| `multisigCheckFlow` | Full status check | +| Flow | Description | Source File | +|------|-------------|-------------| +| `multisigQueryAuthFlow` | Query permissions | `src/flows/multisig.ts` | +| `multisigListTransactionsFlow` | List pending transactions | `src/flows/multisig.ts` | +| `multisigMonitorFlow` | WebSocket real-time monitoring | `src/flows/multisig.ts` | +| `multisigStopMonitorFlow` | Stop monitoring | `src/flows/multisig.ts` | +| `multisigSubmitTxFlow` | Submit signed transaction | `src/flows/multisig.ts` | +| `multisigCheckFlow` | Full status check | `src/flows/multisig.ts` | ### GasFree Flows (3) -| Flow | Description | -|------|-------------| -| `gasfreeCheckAccountFlow` | Query eligibility | -| `gasfreeTransactionHistoryFlow` | Query history | -| `gasfreeSendFlow` | Gas-free TRC20 transfer | +| Flow | Description | Source File | +|------|-------------|-------------| +| `gasfreeCheckAccountFlow` | Query eligibility | `src/flows/gasfree.ts` | +| `gasfreeTransactionHistoryFlow` | Query history | `src/flows/gasfree.ts` | +| `gasfreeSendFlow` | Gas-free TRC20 transfer | `src/flows/gasfree.ts` | --- @@ -2496,9 +2499,11 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump | `@noble/hashes` | ^2.0.1 | Keccak-256, SHA256 | | `@tronlink/tronlink-mcp-core` | ^0.1.0 | Core MCP server framework | | `playwright` | ^1.49.0 | Browser automation | -| `@bankofai/agent-wallet` | ^2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible | +| `@bankofai/agent-wallet` | 2.3.0 | Encrypted local wallet management (`local_secure`) — pinned, not `latest`, to keep wallet behavior reproducible | | `ws` | ^8.18.0 | WebSocket (multi-sig monitoring) | +> **About @bankofai/agent-wallet:** Pinned to exact 2.3.0 (no caret, to avoid silently picking up 2.4.0 on npm). The package's GitHub repo is currently not public (HTTP 404); source transparency comes from the npm publish — audit it via `npm pack @bankofai/agent-wallet@2.3.0`. Upgrading to 2.4.0 should be evaluated against its changelog first. + --- ## Tool Contract & Side Effects @@ -2776,6 +2781,20 @@ The Direct-API path signs with a local encrypted wallet managed by `@bankofai/ag 5. **Gas-Free Operations** — TRC20 transfers without TRX balance requirements 6. **Infrastructure Testing** — Contract deployment, fixture management, mock servers +### End-to-end example: swap 100 TRX for USDT on SunSwap V3 + +A realistic agent turn, showing the tool-call sequence. The agent reads first, gets a fresh quote, surfaces it for human approval, then executes — never auto-executing a Remote Write off a read. + +> **User:** "Swap 100 TRX for USDT on SunSwap V3, max 0.5% slippage." + +1. `tl_chain_get_account` (Network Read) — confirm the active wallet holds ≥ 100 TRX plus enough for fees. +2. `tl_chain_swap_v3` with `action=estimate` (Network Read) — `from_token="TRX"`, `to_token=""`, `amount="100"`, `fee_tier=3000`, `slippage=0.5`. Returns the quoted output and route. +3. Agent surfaces the quote to the user and waits for confirmation (HITL — this is a Remote Write). +4. `tl_chain_swap_v3` with `action=execute` and the **same** explicit `slippage=0.5` — signs with the local `agent-wallet` and broadcasts. Returns `txId`. +5. `tl_chain_get_tx` (Network Read) with the returned `txId` — confirm on-chain success before reporting back. + +> If step 4 returns an uncertain/failed result, do **not** auto-retry: `TL_CHAIN_SWAP_FAILED` is not retryable — re-check the chain with `tl_chain_get_tx` first (see Swap safety). + --- ## Quick Start @@ -2789,8 +2808,8 @@ npm install && npm run build # TL_TRONGRID_URL=https://nile.trongrid.io # # 3. If no wallet exists, choose one path: -# Option A: call tl_wallet_create after startup -# Option B: create one locally, then set AGENT_WALLET_PASSWORD +# Option A (manual): create one locally, then set AGENT_WALLET_PASSWORD +# Option B (auto-create): call tl_wallet_create after startup # 4. Use with Claude Code # "Check my TRX balance" @@ -2798,6 +2817,17 @@ npm install && npm run build # "Swap 100 TRX for USDT on SunSwap V3" ``` +**Which path? (scenario → path)** + +| Scenario | Recommended path | Why | +|----------|------------------|-----| +| Production (real funds) | A — manual + secret manager | Path B writes the password in plaintext to `~/.agent-wallet/runtime_secrets.json` | +| CI / automation (testnet) | A — manual + env injection | Same — keep the password out of an on-disk file | +| Local dev (one-off) | B — auto-create | No pre-config; the password is generated automatically | +| Temp demo | B + tmpfs directory | Point `AGENT_WALLET_DIR` at a tmpfs path destroyed at job end | + +> Path B (auto-create) writes the generated password in plaintext to `~/.agent-wallet/runtime_secrets.json` so a restart can reuse the wallet. See [Wallet Secret Storage](#wallet-secret-storage) for the full Path A / Path B comparison and how to enforce Path A. + ## Version & License - **Package:** `@tronlink/mcp-server-tronlink` v0.1.1 @@ -2886,6 +2916,18 @@ flowchart TD **mcp-server-tronlink is a consumer of tronlink-mcp-core.** The core defines WHAT tools exist; the server provides HOW they work. +### Which one should I pick? + +Use this decision matrix to choose between the two packages by scenario: + +| Scenario | Pick tronlink-mcp-core | Pick mcp-server-tronlink | +|----------|:---:|:---:| +| Building a custom MCP server that embeds your own business logic | ✅ | | +| Giving a ready-to-run server directly to an agent | | ✅ | +| Extending capabilities with a custom `Capability` implementation | ✅ | | +| Testing or mocking with injectable fixtures / mock server | ✅ | | +| Learning how the MCP framework (interfaces, tools, response format) works | ✅ | | + --- ## ISessionManager Interface @@ -3750,6 +3792,22 @@ tron-wallet (check balance) → tron-staking (staking info) → tron-staking (AP tron-resource (check status) → tron-resource (estimate cost) → tron-resource (optimize-cost) ``` +### End-to-end examples + +**"Is swapping 100 TRX for USDT worth it right now?"** + +1. `token-price` (`tron-market`) — fetch current TRX and USDT prices to establish the reference value of 100 TRX. +2. `kline` (`tron-market`) — pull recent candlesticks to judge whether TRX is trending up or down (timing). +3. `resource-info` (`tron-resource`) — check the account's Energy/Bandwidth so the agent can estimate whether the swap will have to burn TRX for fees. +4. `swap-quote` (`tron-swap`) — request an actual quote for 100 TRX → USDT, including expected output and price impact. +5. The agent compares the quote's effective rate against the spot price from step 1, factors in the resource cost from step 3, and answers whether the swap is favorable. These steps are **read-only** — to actually execute, route to `mcp-server-tronlink` `tl_chain_swap_v3` (Remote Write, HITL, set `minOut`) or the [signer SDK](tronlink-signer.md). + +**"Did my last USDT transfer go through, and what's my balance now?"** + +1. `tx-status` (`tron-swap`) — look up the most recent transfer's status and confirmations. +2. `account-info` (`tron-wallet`) — confirm the current balances after that transfer settled. +3. `resource-info` (`tron-resource`) — verify enough Energy/Bandwidth remains for a follow-up transfer (otherwise it would burn TRX). Sending the next transfer is a Remote Write — route to the [signer SDK](tronlink-signer.md) `sendTrc20` or `mcp-server-tronlink` `tl_chain_send`. + --- ## TRON Resource Model Reference @@ -3902,6 +3960,16 @@ export TRONGRID_API_KEY="your-api-key" export TRON_NETWORK="mainnet" # or "shasta" / "nile" ``` +#### TronGrid API key — credential management + +`TRONGRID_API_KEY` is optional (read-only, higher rate limits), but if you set one, manage it across these five dimensions: + +- **Storage** — keep it in an environment variable or a secrets manager. Never hardcode it in source, in config committed to git, or in chat/agent logs. +- **Least-privilege** — provision a key scoped only to the read endpoints these skills call; don't reuse a broader production key. +- **Rotation** — rotate on a fixed schedule, and whenever someone with access leaves; keep the rotation window short. +- **Leak-detection** — monitor TronGrid usage for anomalous call volume or unexpected source IPs, and scan repository history with a secret scanner for accidental commits. +- **Revocation** — if a key leaks, revoke it immediately in the TronGrid dashboard and issue a fresh one before resuming traffic. + ### Network Support | Network | URL | Use Case | @@ -3912,11 +3980,14 @@ export TRON_NETWORK="mainnet" # or "shasta" / "nile" ### Built-In Token Shortcuts +> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The shortcuts below are reconciled to that SSOT. The symbols recognized by `tron_api.mjs` are TRX, USDT, USDC, WTRX, BTT, JST, SUN, WIN; USDD is included below for consistency with the SSOT — pass its contract address explicitly. + | Symbol | Contract Address | |--------|------------------| | TRX | Native (no contract) | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | @@ -3984,6 +4055,18 @@ tronlink-skills/ --- +## Troubleshooting + +| Symptom | Cause | What to do | +|---------|-------|------------| +| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill--mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | +| TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). | +| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill--mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | +| `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. | +| Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add `), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. | + +--- + ## Address Format Support Both formats are supported and auto-normalized across all commands: @@ -4060,6 +4143,22 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet. +> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version--license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. + +## Which to use + +TronLink ships three ways to let an AI agent act on Tron. Pick based on whether a human must approve each transaction and where the agent runs. + +| | `mcp-tronlink-signer` (this server) | `mcp-server-tronlink` (Direct-API mode) | `tronlink-cli` | +| --- | --- | --- | --- | +| Approval | HITL — user approves every transaction in the browser | No HITL — signs automatically | HITL — user approves in the browser | +| Credentials on host | None (keys stay in the TronLink extension) | Uses `AGENT_WALLET_PASSWORD` to unlock a local wallet | None (keys stay in the TronLink extension) | +| Interface | MCP server | MCP server | Shell / command line | +| Best for | Agents that should never move funds without explicit human sign-off | Automated, unattended flows: CI, testnet scripting | Interactive terminal use with human sign-off | +| Private-key exposure | Lowest | Higher (credential on host) | Lowest | + +If unsure, prefer `mcp-tronlink-signer` (safest default). + ## Setup ### Claude Code @@ -4112,6 +4211,55 @@ All tools support an optional `network` parameter (`mainnet` / `nile` / `shasta` **Human-in-the-loop.** Every tool that signs (`send_trx`, `send_trc20`, `sign_message`, `sign_typed_data`, `sign_transaction`) opens the TronLink approval page in the browser. The AI agent **cannot** sign without the user clicking Approve. Treat Remote Write tools as requiring confirmation in production. +### Selected tool schemas (inline mirror) + +Docs-side mirrors of the core write tools' inputs, derived from the tool parameters documented in the table above — useful when an agent is writing a tool-call site without an MCP session open. Field names and the required set are mirrored here; runtime `list_tools` remains the authoritative source for the full input schemas (exact field types, defaults, and any Zod metadata). + +`send_trx`: + +```json +{ + "type": "object", + "properties": { + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Amount of TRX to send" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["to", "amount"] +} +``` + +`send_trc20`: + +```json +{ + "type": "object", + "properties": { + "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" }, + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Token amount to send" }, + "decimals": { "description": "Optional token decimals" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["contractAddress", "to", "amount"] +} +``` + +`sign_typed_data`: + +```json +{ + "type": "object", + "properties": { + "typedData": { "description": "EIP-712 typed-data object to sign" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["typedData"] +} +``` + +> Field types above are intentionally left unspecified where they could not be confirmed against the upstream Zod definitions; consult `list_tools` for the exact types. `sign_message` (`message`, `network?`) and `sign_transaction` (`transaction`, `broadcast`, `network?`) follow the same parameter shapes shown in the tool table. + ## MCP Resources | URI | Description | @@ -4228,6 +4376,8 @@ The server returns errors in the standard MCP shape. Each error carries a stable This page mirrors a downstream README; for the source of truth see the GitHub releases above and the `CHANGELOG.md` in each package. Entries below cover the **MCP-visible** surface (tools, schema, security boundaries) — internal refactors are omitted. +> **Sync policy.** This inline changelog mirrors the package `CHANGELOG.md` / README; the project's **GitHub releases are the authoritative source**. This page may lag a release by a short window until the docs are updated, so verify against the GitHub releases (and `list_tools`) when an exact version matters. + #### v0.1.4 _(npm-only, not GitHub-tagged at time of writing)_ Patch-only. No new tools, no breaking input/output shapes. Verify against `list_tools` after upgrade. @@ -5031,11 +5181,13 @@ tronlink reward --json ### Common Token Contracts -| Token | Network | Contract | -| ----- | ------- | ----------------------------------- | -| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | -| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | -| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The table below is a subset reconciled to that SSOT. + +| Token | Network | Contract | Decimals | +| ----- | ------- | ----------------------------------- | -------- | +| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 | +| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 | +| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 | ### Example: AI Transfer Flow @@ -5343,11 +5495,21 @@ TRON addresses have two interchangeable encodings: - `1 TRX = 1,000,000 SUN`. Amounts in `tronWeb` transaction builders (e.g. `sendTrx`) are expressed in **SUN**. -## Common token contracts (Mainnet) +## Common token contracts (SSOT) -| Token | Standard | Contract address | -|---|---|---| -| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | +This is the single source of truth (SSOT) for common mainnet token contract addresses. Other pages — [TronLink CLI](../ai-support/tronlink-cli.md) and [TronLink Skills](../ai-support/tronlink-skills.md) — reconcile to this table; when an address changes, update it here first. + +| Token | Standard | Mainnet contract address | Decimals | Notes | +|---|---|---|---|---| +| TRX | native | — | 6 | Native coin, no TRC-20 contract | +| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | | +| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | | +| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | | +| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX | +| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | | +| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | | +| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | | +| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | | For any other token, look up its contract address on [TronScan](https://tronscan.org/#/tokens). Always verify a token's contract address before integrating — addresses differ per network. diff --git a/docs/llms-full.zh.txt b/docs/llms-full.zh.txt index 6c0e0dc..50e0678 100644 --- a/docs/llms-full.zh.txt +++ b/docs/llms-full.zh.txt @@ -2,11 +2,11 @@ > 中文文档全文拼接，适合 LLM 一次性 ingest。由 scripts/gen_llms_full.py 生成。索引见 ../llms.txt 的 Localized 段。 -- Generated: 2026-05-21T14:08:15Z -- Commit: e724781c635f +- Generated: 2026-05-29T07:38:28Z +- Commit: 32e3353ef15b - Language: zh - Pages: 23 -- Token estimate: ~39,427 (chars / 4) +- Token estimate: ~41,552 (chars / 4) --- @@ -238,6 +238,7 @@ TronLink 的开发者文档以机器可读形式发布，便于 AI 智能体和 - 工具调用请基于结构化的 `error.code` / `error.retryable` 分支,**不要**解析人类可读的 `message`。 - 读操作可安全重试;签名 / 远程写操作需要用户审批（HITL）,且不得自动重试——见各工具的「安全」一节。 - 实验时默认用测试网（`nile` / `shasta`）;只有动用真实资金时才用 `mainnet`。 +- 版本契约：每个工具页在「兼容性与迁移策略」一节列明了哪些是稳定契约、哪些会变动——在依赖任何名称、flag 或输出字段前请先查阅该节。 --- @@ -2154,7 +2155,9 @@ TRON 多签服务的 REST + WebSocket API： - `tl_wallet_set_active` — 按 ID 切换活跃钱包（热切换到所有能力） 如果启动时没有钱包，服务器会提示两条路径：调用 `tl_wallet_create` 自动生成，或通过 CLI 手动创建后设置 `AGENT_WALLET_PASSWORD`。 -自动创建这条路径会生成随机密码，把密码保存到 `~/.agent-wallet/runtime_secrets.json`，创建一个加密的 `main` 钱包，并让当前会话立即可用。 + +!!! warning "自动创建会把密码以明文写入磁盘——仅限测试/开发" + 自动创建这条路径会生成随机密码，并把它**以明文**保存到 `~/.agent-wallet/runtime_secrets.json`，随后创建一个加密的 `main` 钱包并让当前会话立即可用。任何能读取该文件的人都能控制钱包。生产环境请使用手动路径：在外部创建钱包，并通过密钥管理器注入 `AGENT_WALLET_PASSWORD`——不要依赖落盘的明文密码。 ### 6. TRON 密码学工具 @@ -2177,44 +2180,44 @@ hexToAddress() 0x41... → T 地址 预配置的多步骤工作流，带依赖检查和参数模板。 ### Playwright 流程 -| 流程 | 说明 | -|------|------| -| `switchNetworkFlow` | 切换到主网/Nile/Shasta | -| `enableTestNetworksFlow` | 启用测试网可见性 | -| `transferTrxFlow` | 通过 UI 进行 TRX 转账 | -| `transferTokenFlow` | 通过 UI 进行代币转账 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `switchNetworkFlow` | 切换到主网/Nile/Shasta | `src/flows/switch-network.ts` | +| `enableTestNetworksFlow` | 启用测试网可见性 | `src/flows/switch-network.ts` | +| `transferTrxFlow` | 通过 UI 进行 TRX 转账 | `src/flows/transfer-trx.ts` | +| `transferTokenFlow` | 通过 UI 进行代币转账 | `src/flows/transfer-trx.ts` | ### 链上流程（11 个） -| 流程 | 说明 | -|------|------| -| `chainCheckBalanceFlow` | 查询余额 | -| `chainTransferTrxFlow` | 带预检查的 TRX 转账 | -| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 | -| `chainStakeFlow` | 质押 TRX | -| `chainUnstakeFlow` | 解除质押 TRX | -| `chainGetStakingFlow` | 查询质押信息 | -| `chainDelegateResourceFlow` | 代理带宽/能量 | -| `chainUndelegateResourceFlow` | 取消代理资源 | -| `chainSetupMultisigFlow` | 设置多签权限 | -| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 | -| `chainSwapV3Flow` | SunSwap V3 代币兑换 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `chainCheckBalanceFlow` | 查询余额 | `src/flows/onchain.ts` | +| `chainTransferTrxFlow` | 带预检查的 TRX 转账 | `src/flows/onchain.ts` | +| `chainTransferTrc20Flow` | 带预检查的 TRC20 转账 | `src/flows/onchain.ts` | +| `chainStakeFlow` | 质押 TRX | `src/flows/onchain.ts` | +| `chainUnstakeFlow` | 解除质押 TRX | `src/flows/onchain.ts` | +| `chainGetStakingFlow` | 查询质押信息 | `src/flows/onchain.ts` | +| `chainDelegateResourceFlow` | 代理带宽/能量 | `src/flows/onchain.ts` | +| `chainUndelegateResourceFlow` | 取消代理资源 | `src/flows/onchain.ts` | +| `chainSetupMultisigFlow` | 设置多签权限 | `src/flows/onchain.ts` | +| `chainCreateMultisigTxFlow` | 创建未签名的多签交易 | `src/flows/onchain.ts` | +| `chainSwapV3Flow` | SunSwap V3 代币兑换 | `src/flows/onchain.ts` | ### 多签流程（6 个） -| 流程 | 说明 | -|------|------| -| `multisigQueryAuthFlow` | 查询权限 | -| `multisigListTransactionsFlow` | 列出待处理交易 | -| `multisigMonitorFlow` | WebSocket 实时监控 | -| `multisigStopMonitorFlow` | 停止监控 | -| `multisigSubmitTxFlow` | 提交签名交易 | -| `multisigCheckFlow` | 完整状态检查 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `multisigQueryAuthFlow` | 查询权限 | `src/flows/multisig.ts` | +| `multisigListTransactionsFlow` | 列出待处理交易 | `src/flows/multisig.ts` | +| `multisigMonitorFlow` | WebSocket 实时监控 | `src/flows/multisig.ts` | +| `multisigStopMonitorFlow` | 停止监控 | `src/flows/multisig.ts` | +| `multisigSubmitTxFlow` | 提交签名交易 | `src/flows/multisig.ts` | +| `multisigCheckFlow` | 完整状态检查 | `src/flows/multisig.ts` | ### GasFree 流程（3 个） -| 流程 | 说明 | -|------|------| -| `gasfreeCheckAccountFlow` | 查询资格 | -| `gasfreeTransactionHistoryFlow` | 查询历史 | -| `gasfreeSendFlow` | 免 Gas TRC20 转账 | +| 流程 | 说明 | 源文件 | +|------|------|--------| +| `gasfreeCheckAccountFlow` | 查询资格 | `src/flows/gasfree.ts` | +| `gasfreeTransactionHistoryFlow` | 查询历史 | `src/flows/gasfree.ts` | +| `gasfreeSendFlow` | 免 Gas TRC20 转账 | `src/flows/gasfree.ts` | --- @@ -2410,9 +2413,11 @@ mcp-server-tronlink/ | `@noble/hashes` | ^2.0.1 | Keccak-256、SHA256 | | `@tronlink/tronlink-mcp-core` | ^0.1.0 | 核心 MCP 服务框架 | | `playwright` | ^1.49.0 | 浏览器自动化 | -| `@bankofai/agent-wallet` | ^2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 | +| `@bankofai/agent-wallet` | 2.3.0 | 加密本地钱包管理（`local_secure`）——**已钉版本，不用 `latest`**，确保钱包行为可复现 | | `ws` | ^8.18.0 | WebSocket（多签监控） | +> **关于 @bankofai/agent-wallet：** 版本精确钉死在 2.3.0（不用 caret，避免静默升到 npm 上的 2.4.0）。该包的 GitHub 仓库当前未公开（HTTP 404），源码透明性由 npm publish 提供——可用 `npm pack @bankofai/agent-wallet@2.3.0` 解包审计。是否升级到 2.4.0 需另行评估其 changelog 后决定。 + --- ## 工具契约与副作用 @@ -2689,6 +2694,20 @@ Direct-API 路径使用 `@bankofai/agent-wallet` 管理的本地加密钱包签 5. **免 Gas 操作** — 无需 TRX 余额即可完成 TRC20 转账 6. **基础设施测试** — 合约部署、固件管理、Mock 服务 +### 端到端示例：在 SunSwap V3 上用 100 TRX 兑换 USDT + +一个真实的 agent 回合，展示工具调用顺序。agent 先读取、再现取报价、交人工确认后才执行——绝不基于 read 结果自动触发「远程写」。 + +> **用户：** "在 SunSwap V3 上用 100 TRX 兑换 USDT，滑点上限 0.5%。" + +1. `tl_chain_get_account`（Network Read）—— 确认当前钱包持有 ≥ 100 TRX 且留有手续费余量。 +2. `tl_chain_swap_v3`，`action=estimate`（Network Read）—— `from_token="TRX"`、`to_token=""`、`amount="100"`、`fee_tier=3000`、`slippage=0.5`。返回报价输出与路径。 +3. agent 把报价呈现给用户并等待确认（HITL——这是一笔远程写）。 +4. `tl_chain_swap_v3`，`action=execute`，并传入**相同的**显式 `slippage=0.5`——用本地 `agent-wallet` 签名并广播。返回 `txId`。 +5. `tl_chain_get_tx`（Network Read），传入返回的 `txId`——在回报前先确认链上成功。 + +> 若第 4 步返回结果未知 / 失败，**不要**自动重试：`TL_CHAIN_SWAP_FAILED` 不可重试——先用 `tl_chain_get_tx` 核对链上状态（见「兑换安全」）。 + --- ## 快速开始 @@ -2701,10 +2720,10 @@ npm install && npm run build export TL_TRONGRID_URL="https://nile.trongrid.io" # 3. 如果本地还没有钱包，二选一： -# 方案 A：在 MCP 会话里调用 tl_wallet_create -# 方案 B：本地执行 -# agent-wallet start local_secure --generate --wallet-id main -# 然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD +# 路径 A（手动）：本地执行 +# agent-wallet start local_secure --generate --wallet-id main +# 然后把同一个密码写进 .mcp.json 的 AGENT_WALLET_PASSWORD +# 路径 B（自动创建）：在 MCP 会话里调用 tl_wallet_create # 4. 配合 Claude Code 使用 # 配置好 .mcp.json 后自然语言使用： @@ -2713,6 +2732,17 @@ export TL_TRONGRID_URL="https://nile.trongrid.io" # "在 SunSwap V3 上用 100 TRX 兑换 USDT" ``` +**该选哪条路径？（场景 → 路径）** + +| 场景 | 推荐路径 | 原因 | +|------|---------|------| +| 生产环境（真实资金） | A — 手动创建 + secret manager | 路径 B 会把密码以明文写入 `~/.agent-wallet/runtime_secrets.json` | +| CI / 自动化（测试网） | A — 手动创建 + env 注入 | 同上——避免密码落盘到文件 | +| 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 | +| 临时 demo 演示 | B + tmpfs 目录 | 把 `AGENT_WALLET_DIR` 指到任务结束即销毁的 tmpfs | + +> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#钱包密钥存储)。 + ## 版本与许可证 - **包：** `@tronlink/mcp-server-tronlink` v0.1.1 @@ -2801,6 +2831,18 @@ flowchart TD **mcp-server-tronlink 是 tronlink-mcp-core 的使用者。** 核心库定义了工具"是什么"；服务器提供了工具"怎么工作"。 +### 该选哪个？ + +按场景用下面的决策矩阵在两个包之间做选择： + +| 场景 | 选 tronlink-mcp-core | 选 mcp-server-tronlink | +|------|:---:|:---:| +| 构建嵌入自有业务逻辑的自定义 MCP 服务器 | ✅ | | +| 直接把一个开箱即用的服务器交给 agent 使用 | | ✅ | +| 通过自定义 `Capability` 实现扩展能力 | ✅ | | +| 用可注入的 fixture / mock server 做测试或 mock | ✅ | | +| 学习 MCP 框架（接口、工具、响应格式）的工作原理 | ✅ | | + --- ## ISessionManager 接口 @@ -3632,6 +3674,22 @@ tron-wallet（查余额）→ tron-staking（质押信息）→ tron-staking（A tron-resource（检查状态）→ tron-resource（估算成本）→ tron-resource（optimize-cost） ``` +### 端到端示例 + +**"把 100 TRX 换成 USDT 现在划算吗？"** + +1. `token-price`（`tron-market`）—— 获取 TRX 与 USDT 当前价格，确定 100 TRX 的参考价值。 +2. `kline`（`tron-market`）—— 拉取近期 K 线，判断 TRX 处于上行还是下行趋势（择时）。 +3. `resource-info`（`tron-resource`）—— 查询账户的能量/带宽，便于估算本次兑换是否需要燃烧 TRX 抵扣手续费。 +4. `swap-quote`（`tron-swap`）—— 对 100 TRX → USDT 请求实际报价，含预期到账数量与价格冲击。 +5. 智能体将报价的有效汇率与第 1 步现货价对比，结合第 3 步的资源成本，回答兑换是否划算。以上均为**只读**——若要真正执行，请路由到 `mcp-server-tronlink` 的 `tl_chain_swap_v3`（Remote Write、HITL，必传 `minOut`）或 [signer SDK](tronlink-signer.md)。 + +**"我上一笔 USDT 转账到账了吗？现在余额多少？"** + +1. `tx-status`（`tron-swap`）—— 查询最近一笔转账的状态与确认数。 +2. `account-info`（`tron-wallet`）—— 确认该转账结算后的当前余额。 +3. `resource-info`（`tron-resource`）—— 核对剩余能量/带宽是否足够下一笔转账（否则将燃烧 TRX）。发送下一笔转账属于 Remote Write——请路由到 [signer SDK](tronlink-signer.md) 的 `sendTrc20` 或 `mcp-server-tronlink` 的 `tl_chain_send`。 + --- ## TRON 资源模型参考 @@ -3784,6 +3842,16 @@ export TRONGRID_API_KEY="your-api-key" export TRON_NETWORK="mainnet" # 或 "shasta" / "nile" ``` +#### TronGrid API Key —— 凭证管理 + +`TRONGRID_API_KEY` 是可选的（只读、提高限额），但一旦配置，请从以下五个维度管理： + +- **存储** —— 保存在环境变量或密钥管理器中。切勿硬编码在源码、提交到 git 的配置或聊天/智能体日志里。 +- **最小权限** —— 只签发覆盖这些技能所需只读端点的 Key，不要复用更大权限的生产 Key。 +- **轮换** —— 按固定周期轮换，有访问权限的成员离职时也应轮换；保持轮换窗口尽量短。 +- **泄漏检测** —— 监控 TronGrid 用量是否出现异常调用量或非预期来源 IP，并用密钥扫描器扫描仓库历史排查误提交。 +- **吊销** —— 一旦 Key 泄漏，立即在 TronGrid 控制台吊销并签发新 Key，再恢复流量。 + ### 网络支持 | 网络 | 地址 | 用途 | @@ -3794,11 +3862,14 @@ export TRON_NETWORK="mainnet" # 或 "shasta" / "nile" ### 内置代币快捷符号 +> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下方快捷符号已对齐该 SSOT。`tron_api.mjs` 实际内置可识别的符号为 TRX、USDT、USDC、WTRX、BTT、JST、SUN、WIN；USDD 为与 SSOT 保持一致而一并列出——请显式传入其合约地址使用。 + | 符号 | 合约地址 | |------|----------| | TRX | 原生代币（无合约） | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | @@ -3866,6 +3937,18 @@ tronlink-skills/ --- +## 故障排查 + +| 现象 | 原因 | 处理方式 | +|------|------|----------| +| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#6) / [Skill ↔ MCP 工具映射](#skill--mcp) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | +| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#_1)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | +| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill--mcp)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | +| `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 | +| 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add `），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 | + +--- + ## 地址格式支持 所有命令均支持并自动归一化两种格式： @@ -3942,6 +4025,22 @@ Skills 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级 将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具的服务器，供 Claude 及其他 AI 客户端使用。通过 TronLink 浏览器钱包对 TRON 交易进行签名，需用户在浏览器中授权确认 — 私钥始终留在钱包中，不会对外暴露。 +> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#版本与许可证)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。 + +## 该用哪个 + +TronLink 提供了三种方式让 AI 智能体在 Tron 上执行操作。请根据是否需要人工审批每一笔交易、以及智能体运行在何处来选择。 + +| | `mcp-tronlink-signer`（本服务器） | `mcp-server-tronlink`（Direct-API 模式） | `tronlink-cli` | +| --- | --- | --- | --- | +| 审批 | HITL —— 用户在浏览器中审批每一笔交易 | 无 HITL —— 自动签名 | HITL —— 用户在浏览器中审批 | +| 主机上的凭证 | 无（私钥保留在 TronLink 扩展内） | 使用 `AGENT_WALLET_PASSWORD` 解锁本地钱包 | 无（私钥保留在 TronLink 扩展内） | +| 接口形态 | MCP 服务器 | MCP 服务器 | Shell / 命令行 | +| 适用场景 | 任何资金转移都必须经人工显式签字确认的智能体 | 自动化、无人值守流程：CI、测试网脚本 | 需要人工签字确认的交互式终端使用 | +| 私钥暴露风险 | 最低 | 较高（凭证位于主机上） | 最低 | + +如果不确定，优先选择 `mcp-tronlink-signer`（最安全的默认选项）。 + ## 配置 ### Claude Code @@ -3994,6 +4093,55 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si **人工确认（HITL）。** 所有涉及签名的工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 浏览器审批页。AI agent **无法**在用户点击 Approve 之前签名。生产环境必须把 Remote Write 工具视为需要确认。 +### 部分工具 Schema（内联镜像） + +以下是核心写操作工具入参的文档侧镜像，依据上方工具表中记录的参数整理而成 —— 在没有 MCP 会话时，便于智能体离线编写工具调用。这里镜像的是字段名与 required 集合；运行时 `list_tools` 仍是完整输入 schema（精确字段类型、默认值及 Zod 元数据）的权威来源。 + +`send_trx`： + +```json +{ + "type": "object", + "properties": { + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Amount of TRX to send" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["to", "amount"] +} +``` + +`send_trc20`： + +```json +{ + "type": "object", + "properties": { + "contractAddress": { "description": "TRC20 contract address (T-prefix base58)" }, + "to": { "description": "Recipient TRON address (T-prefix base58)" }, + "amount": { "description": "Token amount to send" }, + "decimals": { "description": "Optional token decimals" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["contractAddress", "to", "amount"] +} +``` + +`sign_typed_data`： + +```json +{ + "type": "object", + "properties": { + "typedData": { "description": "EIP-712 typed-data object to sign" }, + "network": { "enum": ["mainnet", "nile", "shasta"], "description": "Optional; defaults to mainnet" } + }, + "required": ["typedData"] +} +``` + +> 凡无法对照上游 Zod 定义确认的字段类型，上面均有意留空；精确类型请查 `list_tools`。`sign_message`（`message`、`network?`）与 `sign_transaction`（`transaction`、`broadcast`、`network?`）遵循工具表中所示的同样参数形态。 + ## MCP 资源 | URI | 说明 | @@ -4110,6 +4258,8 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r 本页是下游 README 镜像；以 GitHub releases 与各包 `CHANGELOG.md` 为准。下方条目只覆盖 **MCP 可见面**（工具、schema、安全边界），内部重构不列。 +> **同步策略。** 此内联 changelog 镜像软件包的 `CHANGELOG.md` / README；项目的 **GitHub releases 为权威来源**。在文档更新之前，本页可能比某个发布版本短暂滞后，因此当需要精确版本号时，请以 GitHub releases（以及 `list_tools`）为准核对。 + #### v0.1.4 _(仅 npm，截至本文写就尚未在 GitHub 打 tag)_ 仅 patch 修复。无新工具、无破坏性输入/输出 shape 变化。升级后用 `list_tools` 复核。 @@ -4909,11 +5059,13 @@ tronlink reward --json ### 常用代币合约 -| 代币 | 网络 | 合约地址 | -| ---- | ---- | -------- | -| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | -| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | -| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | +> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下表为对齐该 SSOT 的子集。 + +| 代币 | 网络 | 合约地址 | 精度 | +| ---- | ---- | -------- | ---- | +| USDT | mainnet | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 | +| USDC | mainnet | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 | +| USDD | mainnet | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | 18 | ### 示例：AI 转账流程 @@ -5221,11 +5373,21 @@ TRON 地址有两种可互转的编码： - `1 TRX = 1,000,000 SUN`。`tronWeb` 交易构造器（如 `sendTrx`）中的金额以 **SUN** 为单位。 -## 常用代币合约（主网） +## 常用代币合约（SSOT） -| 代币 | 标准 | 合约地址 | -|---|---|---| -| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | +本表是常用主网代币合约地址的单一可信源（SSOT）。其他页面——[TronLink CLI](../ai-support/tronlink-cli.md) 与 [TronLink Skills](../ai-support/tronlink-skills.md)——均对齐本表；地址变更时，请先在此处更新。 + +| 代币 | 标准 | 主网合约地址 | 精度 | 备注 | +|---|---|---|---|---| +| TRX | 原生 | — | 6 | 原生币，无 TRC-20 合约 | +| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | | +| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | | +| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | | +| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX | +| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | | +| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | | +| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | | +| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | | 其他代币请在 [TronScan](https://tronscan.org/#/tokens) 查询其合约地址。集成前务必核对代币合约地址——不同网络上的地址不同。 diff --git a/docs/llms.txt b/docs/llms.txt index a25dc91..e4bc3fa 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,7 +2,7 @@ > TronLink is a decentralized wallet for the TRON ecosystem, available as a browser extension and a mobile app. This documentation covers integrating DApps with TronLink across the browser extension, the mobile app (via DeepLink), and AI/agent tooling (MCP servers, CLI, signer SDK). -> Updated: 2026-05-21T14:08:15Z · Commit: e724781c635f +> Updated: 2026-05-29T07:38:28Z · Commit: 32e3353ef15b How integration works: TronLink injects a `window.tron` provider into every page, exposing a `tronWeb` instance, a `request` method, and `on` / `removeListener` for events. A DApp detects the wallet via TIP-6963, requests authorization via `eth_requestAccounts` (TIP-1102), then builds, signs, and broadcasts transactions through `tronWeb`. Account/network changes arrive as passive `accountsChanged` / `chainChanged` events. diff --git a/docs/llms.zh.txt b/docs/llms.zh.txt index 372276c..6a3650e 100644 --- a/docs/llms.zh.txt +++ b/docs/llms.zh.txt @@ -2,7 +2,7 @@ > TronLink 是 TRON 生态的去中心化钱包，提供浏览器扩展和移动 App。本文档涵盖 DApp 通过浏览器扩展、移动端（DeepLink）以及 AI/智能体工具链（MCP 服务、CLI、签名 SDK）与 TronLink 集成。 -> Updated: 2026-05-21T14:08:15Z · Commit: e724781c635f +> Updated: 2026-05-29T07:38:28Z · Commit: 32e3353ef15b 集成原理：TronLink 向页面注入 `window.tron` provider，暴露 `tronWeb` 实例、`request` 方法以及 `on` / `removeListener` 事件订阅。DApp 通过 TIP-6963 检测钱包，用 `eth_requestAccounts`（TIP-1102）请求授权，再经 `tronWeb` 构建、签名并广播交易。账户/网络变化以 `accountsChanged` / `chainChanged` 被动事件送达。 diff --git a/docs/reference/networks.en.md b/docs/reference/networks.en.md index c41f627..90582d0 100644 --- a/docs/reference/networks.en.md +++ b/docs/reference/networks.en.md @@ -31,10 +31,20 @@ TRON addresses have two interchangeable encodings: - `1 TRX = 1,000,000 SUN`. Amounts in `tronWeb` transaction builders (e.g. `sendTrx`) are expressed in **SUN**. -## Common token contracts (Mainnet) +## Common token contracts (SSOT) -| Token | Standard | Contract address | -|---|---|---| -| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | +This is the single source of truth (SSOT) for common mainnet token contract addresses. Other pages — [TronLink CLI](../ai-support/tronlink-cli.md) and [TronLink Skills](../ai-support/tronlink-skills.md) — reconcile to this table; when an address changes, update it here first. + +| Token | Standard | Mainnet contract address | Decimals | Notes | +|---|---|---|---|---| +| TRX | native | — | 6 | Native coin, no TRC-20 contract | +| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | | +| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | | +| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | | +| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX | +| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | | +| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | | +| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | | +| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | | For any other token, look up its contract address on [TronScan](https://tronscan.org/#/tokens). Always verify a token's contract address before integrating — addresses differ per network. diff --git a/docs/reference/networks.zh.md b/docs/reference/networks.zh.md index f82df09..1271c06 100644 --- a/docs/reference/networks.zh.md +++ b/docs/reference/networks.zh.md @@ -31,10 +31,20 @@ TRON 地址有两种可互转的编码： - `1 TRX = 1,000,000 SUN`。`tronWeb` 交易构造器（如 `sendTrx`）中的金额以 **SUN** 为单位。 -## 常用代币合约（主网） +## 常用代币合约（SSOT） -| 代币 | 标准 | 合约地址 | -|---|---|---| -| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | +本表是常用主网代币合约地址的单一可信源（SSOT）。其他页面——[TronLink CLI](../ai-support/tronlink-cli.md) 与 [TronLink Skills](../ai-support/tronlink-skills.md)——均对齐本表；地址变更时，请先在此处更新。 + +| 代币 | 标准 | 主网合约地址 | 精度 | 备注 | +|---|---|---|---|---| +| TRX | 原生 | — | 6 | 原生币，无 TRC-20 合约 | +| USDT | TRC-20 | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | | +| USDC | TRC-20 | `TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8` | 6 | | +| USDD | TRC-20 | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | | +| WTRX | TRC-20 | `TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR` | 6 | Wrapped TRX | +| BTT | TRC-20 | `TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4` | 18 | | +| JST | TRC-20 | `TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9` | 18 | | +| SUN | TRC-20 | `TSSMHYeV2uE9qYH95DqyoCuNCzEL1NvU3S` | 18 | | +| WIN | TRC-20 | `TLa2f6VPqDgRE67v1736s7bJ8Ray5wYjU7` | 6 | | 其他代币请在 [TronScan](https://tronscan.org/#/tokens) 查询其合约地址。集成前务必核对代币合约地址——不同网络上的地址不同。 From 0cf4be4b82f652150b32f1390f14bc1a3f227be1 Mon Sep 17 00:00:00 2001 From: Tron Date: Fri, 29 May 2026 15:42:54 +0800 Subject: [PATCH 02/10] docs: P0-5 point schema-parity CI link to TronLink/docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The canonical docs repo TronLink/docs already exists (xueyuanying/docs is just a fork), so only the in-doc URL needs fixing — no migration required. Change the check-doc-schema-parity.yml link in mcp-server-tronlink.{en,zh} from xueyuanying/docs to TronLink/docs; llms.txt / llms-full.* regenerated. Co-Authored-By: Claude Opus 4.8 --- docs/ai-support/mcp-server-tronlink.en.md | 2 +- docs/ai-support/mcp-server-tronlink.zh.md | 2 +- docs/llms-full.en.txt | 8 ++++---- docs/llms-full.txt | 8 ++++---- docs/llms-full.zh.txt | 6 +++--- docs/llms.txt | 2 +- docs/llms.zh.txt | 2 +- 7 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/ai-support/mcp-server-tronlink.en.md b/docs/ai-support/mcp-server-tronlink.en.md index 6b4787d..8967e24 100644 --- a/docs/ai-support/mcp-server-tronlink.en.md +++ b/docs/ai-support/mcp-server-tronlink.en.md @@ -450,7 +450,7 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump These are **docs-side mirrors** of the most critical tool inputs — useful when an agent is writing a tool-call call site without an MCP session open. Runtime `list_tools` remains the authoritative source: the schemas there carry full Zod metadata (descriptions, `default`, etc.) plus `meta.schemaVersion`. Fields below are derived from `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts` and follow JSON Schema Draft 7. The full set of 52 tool schemas is **not** reproduced here — see core for the SSOT. -> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI. +> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI. #### `tl_chain_send` — **Remote Write** diff --git a/docs/ai-support/mcp-server-tronlink.zh.md b/docs/ai-support/mcp-server-tronlink.zh.md index 7c39dc4..fdf7c26 100644 --- a/docs/ai-support/mcp-server-tronlink.zh.md +++ b/docs/ai-support/mcp-server-tronlink.zh.md @@ -442,7 +442,7 @@ mcp-server-tronlink/ 以下是最关键工具输入的**文档侧镜像**——当 agent 需要在没有打开 MCP 会话的情况下写工具调用站点时使用。运行时 `list_tools` 仍是权威源：那里有完整的 Zod 元信息（描述、`default` 等）以及 `meta.schemaVersion`。下方字段抄自 `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts`，遵循 JSON Schema Draft 7。**未**镜像全部 52 个工具——以 core 仓库为 SSOT。 -> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。 +> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。 #### `tl_chain_send` —— **Remote Write** diff --git a/docs/llms-full.en.txt b/docs/llms-full.en.txt index 20ed135..aa68d22 100644 --- a/docs/llms-full.en.txt +++ b/docs/llms-full.en.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T07:38:28Z -- Commit: 32e3353ef15b +- Generated: 2026-05-29T07:42:39Z +- Commit: c99635c87cc4 - Language: en - Pages: 23 -- Token estimate: ~60,362 (chars / 4) +- Token estimate: ~60,361 (chars / 4) --- @@ -2527,7 +2527,7 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump These are **docs-side mirrors** of the most critical tool inputs — useful when an agent is writing a tool-call call site without an MCP session open. Runtime `list_tools` remains the authoritative source: the schemas there carry full Zod metadata (descriptions, `default`, etc.) plus `meta.schemaVersion`. Fields below are derived from `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts` and follow JSON Schema Draft 7. The full set of 52 tool schemas is **not** reproduced here — see core for the SSOT. -> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI. +> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI. #### `tl_chain_send` — **Remote Write** diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 20ed135..aa68d22 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T07:38:28Z -- Commit: 32e3353ef15b +- Generated: 2026-05-29T07:42:39Z +- Commit: c99635c87cc4 - Language: en - Pages: 23 -- Token estimate: ~60,362 (chars / 4) +- Token estimate: ~60,361 (chars / 4) --- @@ -2527,7 +2527,7 @@ Pinned to the `package.json` of `mcp-server-tronlink@0.1.1`. Re-verify when bump These are **docs-side mirrors** of the most critical tool inputs — useful when an agent is writing a tool-call call site without an MCP session open. Runtime `list_tools` remains the authoritative source: the schemas there carry full Zod metadata (descriptions, `default`, etc.) plus `meta.schemaVersion`. Fields below are derived from `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts` and follow JSON Schema Draft 7. The full set of 52 tool schemas is **not** reproduced here — see core for the SSOT. -> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI. +> **Parity is enforced.** `scripts/check_doc_schema_parity.py` (run on push, PR, and daily via [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)) diffs the top-level field set + required-flag set of every block below against the live `schemas.ts`. Upstream rename or required→optional drift fails CI. #### `tl_chain_send` — **Remote Write** diff --git a/docs/llms-full.zh.txt b/docs/llms-full.zh.txt index 50e0678..43fc958 100644 --- a/docs/llms-full.zh.txt +++ b/docs/llms-full.zh.txt @@ -2,8 +2,8 @@ > 中文文档全文拼接，适合 LLM 一次性 ingest。由 scripts/gen_llms_full.py 生成。索引见 ../llms.txt 的 Localized 段。 -- Generated: 2026-05-29T07:38:28Z -- Commit: 32e3353ef15b +- Generated: 2026-05-29T07:42:39Z +- Commit: c99635c87cc4 - Language: zh - Pages: 23 - Token estimate: ~41,552 (chars / 4) @@ -2441,7 +2441,7 @@ mcp-server-tronlink/ 以下是最关键工具输入的**文档侧镜像**——当 agent 需要在没有打开 MCP 会话的情况下写工具调用站点时使用。运行时 `list_tools` 仍是权威源：那里有完整的 Zod 元信息（描述、`default` 等）以及 `meta.schemaVersion`。下方字段抄自 `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts`，遵循 JSON Schema Draft 7。**未**镜像全部 52 个工具——以 core 仓库为 SSOT。 -> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。 +> **平价由 CI 强制。** `scripts/check_doc_schema_parity.py`（在 push、PR 及每日定时通过 [`check-doc-schema-parity.yml`](https://github.com/TronLink/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) 触发）会对下方每个块的顶层字段集 + required 标记与上游 `schemas.ts` 做 diff——上游改名或 required ↔ optional 漂移都会让 CI 失败。 #### `tl_chain_send` —— **Remote Write** diff --git a/docs/llms.txt b/docs/llms.txt index e4bc3fa..2aaa2c7 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,7 +2,7 @@ > TronLink is a decentralized wallet for the TRON ecosystem, available as a browser extension and a mobile app. This documentation covers integrating DApps with TronLink across the browser extension, the mobile app (via DeepLink), and AI/agent tooling (MCP servers, CLI, signer SDK). -> Updated: 2026-05-29T07:38:28Z · Commit: 32e3353ef15b +> Updated: 2026-05-29T07:42:39Z · Commit: c99635c87cc4 How integration works: TronLink injects a `window.tron` provider into every page, exposing a `tronWeb` instance, a `request` method, and `on` / `removeListener` for events. A DApp detects the wallet via TIP-6963, requests authorization via `eth_requestAccounts` (TIP-1102), then builds, signs, and broadcasts transactions through `tronWeb`. Account/network changes arrive as passive `accountsChanged` / `chainChanged` events. diff --git a/docs/llms.zh.txt b/docs/llms.zh.txt index 6a3650e..da435d4 100644 --- a/docs/llms.zh.txt +++ b/docs/llms.zh.txt @@ -2,7 +2,7 @@ > TronLink 是 TRON 生态的去中心化钱包，提供浏览器扩展和移动 App。本文档涵盖 DApp 通过浏览器扩展、移动端（DeepLink）以及 AI/智能体工具链（MCP 服务、CLI、签名 SDK）与 TronLink 集成。 -> Updated: 2026-05-29T07:38:28Z · Commit: 32e3353ef15b +> Updated: 2026-05-29T07:42:39Z · Commit: c99635c87cc4 集成原理：TronLink 向页面注入 `window.tron` provider，暴露 `tronWeb` 实例、`request` 方法以及 `on` / `removeListener` 事件订阅。DApp 通过 TIP-6963 检测钱包，用 `eth_requestAccounts`（TIP-1102）请求授权，再经 `tronWeb` 构建、签名并广播交易。账户/网络变化以 `accountsChanged` / `chainChanged` 被动事件送达。 From ca4ea75816e6e90de111096c09a9bbe4777f05b1 Mon Sep 17 00:00:00 2001 From: Tron Date: Fri, 29 May 2026 15:44:07 +0800 Subject: [PATCH 03/10] docs: P0-2 correct Flow Recipes count to 24 (keep all flows) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The earlier review claim that chainTransferTrc20Flow / chainSwapV3Flow don't exist is false — both are in src/flows/onchain.ts and registered. The real issue was only the headline count: the page lists 24 flows (Playwright 4 + on-chain 11 + multisig 6 + gasfree 3) which matches the code registry (24 builtinFlows), but the heading/overview/mermaid/tree said 32. Change those four "32"s to "24"; no flow rows removed, on-chain stays 11. llms.txt / llms-full.* regenerated. Co-Authored-By: Claude Opus 4.8 --- docs/ai-support/mcp-server-tronlink.en.md | 8 ++++---- docs/ai-support/mcp-server-tronlink.zh.md | 8 ++++---- docs/llms-full.en.txt | 12 ++++++------ docs/llms-full.txt | 12 ++++++------ docs/llms-full.zh.txt | 12 ++++++------ docs/llms.txt | 2 +- docs/llms.zh.txt | 2 +- 7 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/ai-support/mcp-server-tronlink.en.md b/docs/ai-support/mcp-server-tronlink.en.md index 8967e24..6aa6893 100644 --- a/docs/ai-support/mcp-server-tronlink.en.md +++ b/docs/ai-support/mcp-server-tronlink.en.md @@ -8,7 +8,7 @@ **Key Highlights:** - Dual-mode architecture: **Playwright** (browser automation) + **Direct API** (on-chain operations) -- 32 built-in Flow Recipes with pre-checks and dependency resolution +- 24 built-in Flow Recipes with pre-checks and dependency resolution - Non-custodial local transaction signing via encrypted `agent-wallet` - Multi-signature management with real-time WebSocket monitoring - Gas-free TRC20 transfers via GasFree service integration @@ -27,7 +27,7 @@ flowchart TD Multi["TronLinkMultiSigCapability (5 tools)"] GasFree["TronLinkGasFreeCapability (3 tools)"] Util["Utility Capabilities
Build · StateSnapshot · TRON Crypto"] - Flow["Flow Recipes
(32 built-in, pre-checked)"] + Flow["Flow Recipes
(24 built-in, pre-checked)"] Ext["TronGrid API / Multi-Sig Service / GasFree Service"] Chain["TRON Blockchain"] Agent -- "MCP Protocol — stdio / JSON-RPC 2.0" --> Server @@ -176,7 +176,7 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256). --- -## Flow Recipes (32 Built-In) +## Flow Recipes (24 Built-In) Pre-configured multi-step workflows with dependency checks and parameter templates. @@ -396,7 +396,7 @@ mcp-server-tronlink/ │ │ ├── state-snapshot.ts # UI state extraction │ │ └── tron-crypto.ts # Address derivation, signing, Base58 │ └── flows/ -│ ├── index.ts # Flow registry (32 recipes) +│ ├── index.ts # Flow registry (24 recipes) │ ├── switch-network.ts # Network switching flows │ ├── transfer-trx.ts # Transfer flows │ ├── multisig.ts # 6 multi-sig flows diff --git a/docs/ai-support/mcp-server-tronlink.zh.md b/docs/ai-support/mcp-server-tronlink.zh.md index fdf7c26..79f74b3 100644 --- a/docs/ai-support/mcp-server-tronlink.zh.md +++ b/docs/ai-support/mcp-server-tronlink.zh.md @@ -8,7 +8,7 @@ **核心亮点：** - 双模架构：**Playwright**（浏览器自动化）+ **Direct API**（链上操作） -- 32 个内置 Flow Recipe，带预检查和依赖解析 +- 24 个内置 Flow Recipe，带预检查和依赖解析 - 基于加密 `agent-wallet` 的非托管本地交易签名 - 多签管理，支持实时 WebSocket 监控 - 通过 GasFree 服务集成实现零 Gas TRC20 转账 @@ -27,7 +27,7 @@ flowchart TD Multi["TronLinkMultiSigCapability (5 个工具)"] GasFree["TronLinkGasFreeCapability (3 个工具)"] Util["实用能力
Build · StateSnapshot · TRON Crypto"] - Flow["Flow Recipes
(32 个内置流程配方)"] + Flow["Flow Recipes
(24 个内置流程配方)"] Ext["TronGrid API / 多签服务 / GasFree 服务"] Chain["TRON 区块链"] Agent -- "MCP 协议 — stdio / JSON-RPC 2.0" --> Server @@ -176,7 +176,7 @@ hexToAddress() 0x41... → T 地址 --- -## Flow Recipes（32 个内置流程） +## Flow Recipes（24 个内置流程） 预配置的多步骤工作流，带依赖检查和参数模板。 @@ -388,7 +388,7 @@ mcp-server-tronlink/ │ │ ├── state-snapshot.ts # UI 状态提取 │ │ └── tron-crypto.ts # 地址派生、签名、Base58 │ └── flows/ -│ ├── index.ts # 流程注册（32 个配方） +│ ├── index.ts # 流程注册（24 个配方） │ ├── switch-network.ts # 网络切换流程 │ ├── transfer-trx.ts # 转账流程 │ ├── multisig.ts # 6 个多签流程 diff --git a/docs/llms-full.en.txt b/docs/llms-full.en.txt index aa68d22..82cc840 100644 --- a/docs/llms-full.en.txt +++ b/docs/llms-full.en.txt @@ -2,8 +2,8 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T07:42:39Z -- Commit: c99635c87cc4 +- Generated: 2026-05-29T07:44:07Z +- Commit: 0cf4be4b82f6 - Language: en - Pages: 23 - Token estimate: ~60,361 (chars / 4) @@ -2085,7 +2085,7 @@ Modified hash: **Key Highlights:** - Dual-mode architecture: **Playwright** (browser automation) + **Direct API** (on-chain operations) -- 32 built-in Flow Recipes with pre-checks and dependency resolution +- 24 built-in Flow Recipes with pre-checks and dependency resolution - Non-custodial local transaction signing via encrypted `agent-wallet` - Multi-signature management with real-time WebSocket monitoring - Gas-free TRC20 transfers via GasFree service integration @@ -2104,7 +2104,7 @@ flowchart TD Multi["TronLinkMultiSigCapability (5 tools)"] GasFree["TronLinkGasFreeCapability (3 tools)"] Util["Utility Capabilities
Build · StateSnapshot · TRON Crypto"] - Flow["Flow Recipes
(32 built-in, pre-checked)"] + Flow["Flow Recipes
(24 built-in, pre-checked)"] Ext["TronGrid API / Multi-Sig Service / GasFree Service"] Chain["TRON Blockchain"] Agent -- "MCP Protocol — stdio / JSON-RPC 2.0" --> Server @@ -2253,7 +2253,7 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256). --- -## Flow Recipes (32 Built-In) +## Flow Recipes (24 Built-In) Pre-configured multi-step workflows with dependency checks and parameter templates. @@ -2473,7 +2473,7 @@ mcp-server-tronlink/ │ │ ├── state-snapshot.ts # UI state extraction │ │ └── tron-crypto.ts # Address derivation, signing, Base58 │ └── flows/ -│ ├── index.ts # Flow registry (32 recipes) +│ ├── index.ts # Flow registry (24 recipes) │ ├── switch-network.ts # Network switching flows │ ├── transfer-trx.ts # Transfer flows │ ├── multisig.ts # 6 multi-sig flows diff --git a/docs/llms-full.txt b/docs/llms-full.txt index aa68d22..82cc840 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -2,8 +2,8 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T07:42:39Z -- Commit: c99635c87cc4 +- Generated: 2026-05-29T07:44:07Z +- Commit: 0cf4be4b82f6 - Language: en - Pages: 23 - Token estimate: ~60,361 (chars / 4) @@ -2085,7 +2085,7 @@ Modified hash: **Key Highlights:** - Dual-mode architecture: **Playwright** (browser automation) + **Direct API** (on-chain operations) -- 32 built-in Flow Recipes with pre-checks and dependency resolution +- 24 built-in Flow Recipes with pre-checks and dependency resolution - Non-custodial local transaction signing via encrypted `agent-wallet` - Multi-signature management with real-time WebSocket monitoring - Gas-free TRC20 transfers via GasFree service integration @@ -2104,7 +2104,7 @@ flowchart TD Multi["TronLinkMultiSigCapability (5 tools)"] GasFree["TronLinkGasFreeCapability (3 tools)"] Util["Utility Capabilities
Build · StateSnapshot · TRON Crypto"] - Flow["Flow Recipes
(32 built-in, pre-checked)"] + Flow["Flow Recipes
(24 built-in, pre-checked)"] Ext["TronGrid API / Multi-Sig Service / GasFree Service"] Chain["TRON Blockchain"] Agent -- "MCP Protocol — stdio / JSON-RPC 2.0" --> Server @@ -2253,7 +2253,7 @@ Uses `@noble/curves` (secp256k1 ECDSA) and `@noble/hashes` (Keccak-256, SHA256). --- -## Flow Recipes (32 Built-In) +## Flow Recipes (24 Built-In) Pre-configured multi-step workflows with dependency checks and parameter templates. @@ -2473,7 +2473,7 @@ mcp-server-tronlink/ │ │ ├── state-snapshot.ts # UI state extraction │ │ └── tron-crypto.ts # Address derivation, signing, Base58 │ └── flows/ -│ ├── index.ts # Flow registry (32 recipes) +│ ├── index.ts # Flow registry (24 recipes) │ ├── switch-network.ts # Network switching flows │ ├── transfer-trx.ts # Transfer flows │ ├── multisig.ts # 6 multi-sig flows diff --git a/docs/llms-full.zh.txt b/docs/llms-full.zh.txt index 43fc958..6a9014f 100644 --- a/docs/llms-full.zh.txt +++ b/docs/llms-full.zh.txt @@ -2,8 +2,8 @@ > 中文文档全文拼接，适合 LLM 一次性 ingest。由 scripts/gen_llms_full.py 生成。索引见 ../llms.txt 的 Localized 段。 -- Generated: 2026-05-29T07:42:39Z -- Commit: c99635c87cc4 +- Generated: 2026-05-29T07:44:07Z +- Commit: 0cf4be4b82f6 - Language: zh - Pages: 23 - Token estimate: ~41,552 (chars / 4) @@ -2007,7 +2007,7 @@ ledger返回的实际签名hash： **核心亮点：** - 双模架构：**Playwright**（浏览器自动化）+ **Direct API**（链上操作） -- 32 个内置 Flow Recipe，带预检查和依赖解析 +- 24 个内置 Flow Recipe，带预检查和依赖解析 - 基于加密 `agent-wallet` 的非托管本地交易签名 - 多签管理，支持实时 WebSocket 监控 - 通过 GasFree 服务集成实现零 Gas TRC20 转账 @@ -2026,7 +2026,7 @@ flowchart TD Multi["TronLinkMultiSigCapability (5 个工具)"] GasFree["TronLinkGasFreeCapability (3 个工具)"] Util["实用能力
Build · StateSnapshot · TRON Crypto"] - Flow["Flow Recipes
(32 个内置流程配方)"] + Flow["Flow Recipes
(24 个内置流程配方)"] Ext["TronGrid API / 多签服务 / GasFree 服务"] Chain["TRON 区块链"] Agent -- "MCP 协议 — stdio / JSON-RPC 2.0" --> Server @@ -2175,7 +2175,7 @@ hexToAddress() 0x41... → T 地址 --- -## Flow Recipes（32 个内置流程） +## Flow Recipes（24 个内置流程） 预配置的多步骤工作流，带依赖检查和参数模板。 @@ -2387,7 +2387,7 @@ mcp-server-tronlink/ │ │ ├── state-snapshot.ts # UI 状态提取 │ │ └── tron-crypto.ts # 地址派生、签名、Base58 │ └── flows/ -│ ├── index.ts # 流程注册（32 个配方） +│ ├── index.ts # 流程注册（24 个配方） │ ├── switch-network.ts # 网络切换流程 │ ├── transfer-trx.ts # 转账流程 │ ├── multisig.ts # 6 个多签流程 diff --git a/docs/llms.txt b/docs/llms.txt index 2aaa2c7..8dbdaed 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,7 +2,7 @@ > TronLink is a decentralized wallet for the TRON ecosystem, available as a browser extension and a mobile app. This documentation covers integrating DApps with TronLink across the browser extension, the mobile app (via DeepLink), and AI/agent tooling (MCP servers, CLI, signer SDK). -> Updated: 2026-05-29T07:42:39Z · Commit: c99635c87cc4 +> Updated: 2026-05-29T07:44:07Z · Commit: 0cf4be4b82f6 How integration works: TronLink injects a `window.tron` provider into every page, exposing a `tronWeb` instance, a `request` method, and `on` / `removeListener` for events. A DApp detects the wallet via TIP-6963, requests authorization via `eth_requestAccounts` (TIP-1102), then builds, signs, and broadcasts transactions through `tronWeb`. Account/network changes arrive as passive `accountsChanged` / `chainChanged` events. diff --git a/docs/llms.zh.txt b/docs/llms.zh.txt index da435d4..2d3c64e 100644 --- a/docs/llms.zh.txt +++ b/docs/llms.zh.txt @@ -2,7 +2,7 @@ > TronLink 是 TRON 生态的去中心化钱包，提供浏览器扩展和移动 App。本文档涵盖 DApp 通过浏览器扩展、移动端（DeepLink）以及 AI/智能体工具链（MCP 服务、CLI、签名 SDK）与 TronLink 集成。 -> Updated: 2026-05-29T07:42:39Z · Commit: c99635c87cc4 +> Updated: 2026-05-29T07:44:07Z · Commit: 0cf4be4b82f6 集成原理：TronLink 向页面注入 `window.tron` provider，暴露 `tronWeb` 实例、`request` 方法以及 `on` / `removeListener` 事件订阅。DApp 通过 TIP-6963 检测钱包，用 `eth_requestAccounts`（TIP-1102）请求授权，再经 `tronWeb` 构建、签名并广播交易。账户/网络变化以 `accountsChanged` / `chainChanged` 被动事件送达。 From 1aed03bbd2cc8095721921616dd934d3b53a2845 Mon Sep 17 00:00:00 2001 From: Tron Date: Fri, 29 May 2026 15:54:30 +0800 Subject: [PATCH 04/10] change branch --- .github/workflows/gh-pages.yml | 2 +- ai-readability-review.md | 140 ++++ plugin-wallet-refactor-plan.md | 275 ++++++++ ...04\345\256\241\346\212\245\345\221\212.md" | 634 ++++++++++++++++++ 4 files changed, 1050 insertions(+), 1 deletion(-) create mode 100644 ai-readability-review.md create mode 100644 plugin-wallet-refactor-plan.md create mode 100644 "\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index d749955..130d744 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -4,7 +4,7 @@ on: push: branches: - main - - feature/ai-readability-p0 + - docs/review-fixes workflow_dispatch: # 仍保留手动触发的功能 jobs: diff --git a/ai-readability-review.md b/ai-readability-review.md new file mode 100644 index 0000000..2865810 --- /dev/null +++ b/ai-readability-review.md @@ -0,0 +1,140 @@ +# TronLink 开发者文档 · AI 可读性评估与优化报告 + +- **评估对象**：https://docs.tronlink.org/ （EN/ZH 双语，mkdocs-material） +- **评估视角**：以「agent 能否稳定发现 / 解析 / 调用 / 判断失败」为标准的区块链开发者 AI +- **评估基线**：AI Agent 文档标准包 V1.0（项目级覆盖度 20% + 文档质量 80%） +- **评估日期**：2026-05-29 ｜ 文档快照：commit `e724781c635f`，生成于 `2026-05-21T14:08:15Z` + +## 一句话结论 + +> 这是极少数「为 AI 而设计」而不是「顺便能被 AI 读」的钱包文档。综合评级 **A（8.3 / 10）**：AI 入口、MCP、错误码联表、安全披露均为范本级别。剩余问题集中在「最后一公里」工程化：**机器可读契约文件缺失、逐页 raw markdown 缺失、错误矩阵有空洞、License / 版本治理缺位**。补齐后可冲 S。 + +--- + +## 一、做得非常好的地方 + +| 维度 | 证据 | 为什么对 AI 重要 | +|---|---|---| +| AI 入口索引 | 根目录有 `llms.txt`（真·纯文本），含 commit SHA、UTC 时间戳、网络 chainId、「集成原理」摘要、按导航顺序的全站索引；并有 `llms-full.txt` 单次拉取全量（23 页 ≈ 57k tokens），EN/ZH 双份 | agent 一次 fetch 即可建立全局心智，无需爬 51 个 URL | +| 明确的 agent 立场 | `ai-support/ai-llms` 声明文档面向 "retrieval / RAG / inference-time grounding"，并给 "Notes for agents"：从 `llms.txt` 入手、按 error code 分支而非 message、签名需用户批准、优先 testnet | 教科书式 agent 引导，多数项目完全没有 | +| 错误码横向联表 | `reference/error-code-map` 把 DApp(EIP-1474) / DeepLink(5 位) / MCP(`TL_*`) / CLI(exit code) 按「业务含义」对齐，并标 `Retryable` | 让 agent 跨 4 个调用面用同一套语义分支，SSOT 思想到位 | +| MCP 文档深度 | stdio transport、55 个 tool、JSON Schema Draft-7 示例、Zod 运行时校验、`list_tools` 为权威源、统一 error 包络（`error.code/retryable/details` + `meta.schemaVersion`）、`.mcp.json` 配置、高危工具（`tl_evaluate`）禁用指引 | 达到 MCP 标准 9 分锚点 | +| 安全披露诚实 | 明确区分 Direct-API（本地签名直接广播，无 HITL）vs Playwright/Signer（浏览器内人工批准）；标注 swap 的 MEV/滑点风险、必须 bound minimum-output；多签密钥轮换/最小权限 | 副作用等级、确认机制、风险隔离全覆盖 | +| Provider 契约 | `window.tron` 给了 TypeScript interface；TIP-6963 发现、`eth_requestAccounts`(TIP-1102)、TIP-3326 切链、`chainChanged` 等都有 JSON Schema 入参 | 比多数 EVM 钱包文档严谨 | +| 网络参考可拷贝 | mainnet/Shasta/Nile 的 hex chainId + EVM 十进制 + RPC + explorer + faucet + USDT 合约 + TRX/SUN 单位，全部表格化 | agent 直接抽字段 | + +--- + +## 二、扣分项与优化建议（按优先级） + +### P0 — 影响 agent 稳定自动化 + +**P0-1　契约机器可读性分三个断层，provider RPC 是真缺口** + +核实源码后，schema 并非笼统「埋在散文里」，而是三档成熟度断层： + +| 调用面 | 机器可读性 | SSOT | +|---|---|---| +| MCP tools | 内联 JSON Schema，但仅镜像 **7/55** 个 tool、仅顶层字段 | 🟢 上游 Zod（`tronlink-mcp-core/src/mcp-server/schemas.ts`）+ CI 对账（`scripts/check_doc_schema_parity.py`） | +| Provider RPC（`window.tron`） | ❌ **无 per-method schema**：参数=JS 示例，返回=散文，错误=Markdown 表 | 🔴 无，手写 | +| 错误码 | 四方言联表，`Retryable` 独立列 | 🟡 `TL_*` 在 `tronlink-mcp-core` | + +因此 P0-1 按调用面拆级： + +- **Provider RPC = 真 P0**：DApp 开发者最高频的面，却零结构化契约，`request(): Promise` + 散文返回（"an array is returned with a single element"），agent 只能靠英文句子推断 I/O。 +- **MCP tools = P1（比初判轻）**：SSOT（Zod）与对账 CI 已就位，差的只是覆盖率（7/55）+ 把 schema 作为独立文件发布 + 嵌套全量。 +- **错误码 = P1（最便宜）**：一张干净的表 → 一份 `error-codes.json`，近乎零成本。 + +关键：补契约是「顺手」而非「工程」，流水线与数据源都已就位： + +- `error-codes.json`：`scripts/gen_llms_full.py` 已在 build 时按 nav 顺序遍历全部页面，顺带解析 error-code-map 那张表（行=业务含义，retryable 已是独立列）输出 JSON 即可。 +- `mcp-tools.json`：**不要手写**，应由上游用 `zod-to-json-schema` 把 Zod SSOT 导出为 release artifact，docs 站点链接/代理它——一步同时解决「7/55 覆盖率」与「仅顶层字段」两个老问题。 +- `provider-methods.json`：provider 侧目前零结构，最该补；可参考 MCP 那套对账思路新增可校验 schema，或至少把每个方法返回从散文升级成具体类型。 + +再评估「`list_tools` 才是权威」：对**已连 MCP** 的 agent 成立，但 `llms.txt` 宣称的受众是**读文档 / RAG** 的 agent，它调不到 `list_tools`、只能读到 7/55——**权威源恰好对宣称服务的人群不可达**。这正是覆盖度标准「OpenAPI / API 契约」项目前只能给 ~7 分（而非 9 分）的精确原因。 + +**P0-2　逐页没有 raw markdown 入口** + +现状：每页是 HTML；想要单页纯文本，要么解析 HTML，要么下载 57k token 的整包 `llms-full.txt`。 + +- 建议：每页额外暴露 `*.md`（mkdocs 配 `?plain` 或部署 `.md` 镜像）。`llms-full.txt` 已用 `` 分隔，把该 source 路径做成可直接拉取的 raw md 即闭环。 + +**P0-3　错误矩阵有空洞 + 重试语义含糊** + +现状：联表大量 `—`（多数 DApp provider 行无 DeepLink/MCP/CLI 对应）；`active-requests` 中 `tronweb.trx.sign / multiSign / signMessageV2 / wallet_watchAsset` 的 Error Codes 列为空；`Timeout=Maybe`、`Internal=Yes(once)` 对 agent 不可执行。 + +- 建议：① 补全每个方法的错误码；② 把「Maybe/once」量化成可执行策略（max attempts、backoff、是否需先 `waitForTransaction` 对账再重试）——对应「有副作用操作不得自动重试，除非证明幂等」。 + +### P1 — 影响接入信任与可维护性 + +**P1-1　robots.txt 是「允许检索、拒绝训练」的合理姿态，但有两个实操坑** + +现状（逐行核对）：`Content-Signal: search=yes,ai-train=no`；Disallow 了 `ClaudeBot, GPTBot, Google-Extended, CCBot, Bytespider, Amazonbot, Applebot-Extended, meta-externalagent, CloudflareBrowserRenderingCrawler`；而 `Claude-User / Claude-SearchBot / OAI-SearchBot / ChatGPT-User` 未被封。 + +- 该姿态逻辑自洽（封训练爬虫、放行实时检索 UA），与 `ai-llms` 页「面向 inference-time grounding 而非训练」一致，值得肯定。 +- 坑 1：靠「没写 Disallow」放行检索 UA，而非显式 `Allow`。建议显式 `Allow` 关键检索 UA 并复核 `PerplexityBot / Googlebot / Bingbot / Applebot(非 Extended)` 未被误伤；注意 `Google-Extended` 被封会同时削弱 Gemini 的 grounding，不只训练。 +- 坑 2：用通用/被封 UA 抓取的 RAG 管线会吃 403 且静默丢内容。建议把 UA 政策写进 `ai-llms` 页，并考虑 `llms.txt/llms-full.txt` 对所有 UA 放行。 + +**P1-2　Direct-API 的密钥默认路径偏危险** + +现状：Direct-API 工具本地签名直接广播，仅靠 `AGENT_WALLET_PASSWORD` 把关；`tl_wallet_create` 自动路径会把明文密码写入 `~/.agent-wallet/runtime_secrets.json`。已有警告，但把「明文密钥落盘」作为一等公民路径披露，风险偏高。 + +- 建议：警告升级为显著 admonition；自动创建路径明确标 test-only；生产路径首选 `mcp-tronlink-signer`（浏览器批准）。 + +**P1-3　License / SPDX 缺失** + +未见文档声明 license。standards 要求所有文档声明 license。 + +- 建议：`llms.txt` 头部与页脚加 SPDX（文档 `CC-BY-4.0`，SDK/CLI `MIT` 或 `Apache-2.0`）。 + +**P1-4　版本治理缺一页** + +`llms.txt` 有 commit+时间戳（很好），但 pre-1.0 稳定性承诺散落在 MCP 页，没有统一 CHANGELOG / 版本兼容页，每页也未标「适用于扩展/SDK 哪个版本」。 + +- 建议：加 `reference/changelog`，并在每页 frontmatter 标注 `applies-to` 版本。 + +### P2 — 完整度 / 体验 + +- **P2-1　Provider 返回类型过松**：`request(): Promise`、`tronWeb: TronWeb|false`。`any` 让 agent 只能靠 prose 推断返回形状。建议每方法给具体返回类型（提炼进 P0-1 的契约文件）。 +- **P2-2　i18n 平价破例**：sitemap 显示 `zh/asset_filter_logic/` 无 EN 对应页，违背「同 slug 即翻译对」不变式。建议补 EN 或在 zh 索引说明这是中文专属。 +- **P2-3　MCP 无 resources/prompts**：若不提供可在页面标 N/A（避免误判遗漏）。stdio-only 也建议显式声明「暂不提供 HTTP/SSE transport」。 +- **P2-4　首页缺机器发现提示**：HTML `` 加指向 `llms.txt` 的 ``/meta，让未读约定的爬虫也能发现入口。 + +--- + +## 三、评分卡（对照 standards 项目级覆盖度） + +| 评分项 | 权重 | 得分 | 主要依据 / 扣分点 | +|---|---:|---:|---| +| AI 入口索引 | 20% | 9.3 | `llms.txt`+`llms-full.txt`+双语+agent notes+commit/时间戳，范本级 | +| OpenAPI / API 契约 | 20% | 7.0 | provider RPC 无 per-method schema（P0）；MCP 仅 7/55 且未发布为独立文件（P1） | +| MCP 文档 | 20% | 9.0 | 极完整；扣分于无 resources/prompts 说明、stdio-only 未显式声明、全集靠 `list_tools` | +| Skills 文档 | 15% | 8.0 | 入口与能力齐全（未深读，按列示与联表推断） | +| CLI 文档 | 10% | 8.0 | 有命令面 + exit code 进联表 | +| 互链与 SSOT | 15% | 9.0 | 错误码联表 + `llms.txt` 全互链 + schemaVersion；扣分于矩阵空洞与 i18n 破例 | +| **项目级覆盖度** | 100% | **≈ 8.4 (A-)** | | +| 文档质量（安全/错误/示例/版本/License 综合） | — | **≈ 8.3 (A-)** | 强在安全披露与示例，弱在 License/版本/逐页 raw md | +| **综合** | — | **8.3 / A** | 距 S（9.0）差「机器可读契约 + raw md + 错误矩阵补全 + License/版本治理」 | + +--- + +## 四、最小行动清单（按性价比排序） + +1. 发 4 个机器可读文件并在 `llms.txt` 链接：`provider-methods.json`、`mcp-tools.json`、`error-codes.json`、`*.d.ts`。（解 P0-1，覆盖度 7→9） +2. 每页 raw `.md` 镜像，复用现有 `` 路径。（解 P0-2） +3. 补全错误矩阵 + 量化重试（max attempts/backoff/对账）。（解 P0-3） +4. robots：显式 Allow 检索 UA + 在 ai-llms 页写明 UA 政策；复核 Perplexity/Google-Extended 影响。（解 P1-1） +5. 加 License/SPDX + CHANGELOG + 每页 applies-to 版本。（解 P1-3/P1-4） +6. 把明文密钥落盘路径降级为 test-only admonition。（解 P1-2） + +--- + +## 附：数据可信度说明 + +具体取值（signer 端口 3386、57k token、各 schema 字段）来自对线上页面的抓取摘要；结构性结论已被多个页面（`llms.txt` ↔ 错误码表 ↔ MCP 页）交叉印证，可信度高。个别精确数值（重试次数、端口）建议落地前对照源仓库 `scripts/gen_llms_full.py` 与 `mkdocs.yml` 复核。 + +注：初版 P0-1 曾引用一段 `eth_requestAccounts` 的 JSON Schema，经核对源码 `docs/plugin-wallet/active-requests.en.md`，该 schema 实为 WebFetch 摘要模型臆造——真实页面只有 JS 示例 + 散文返回 + 错误码表。结论性判断一律以本地源文件为准，不采信二次摘要。 + +--- + +*评审基线：`/Users/tron/Downloads/standards`（AI Agent 文档标准包 V1.0）。本报告由挑剔视角的 AI 评审生成，仅覆盖「AI 可读性」维度。* diff --git a/plugin-wallet-refactor-plan.md b/plugin-wallet-refactor-plan.md new file mode 100644 index 0000000..2803067 --- /dev/null +++ b/plugin-wallet-refactor-plan.md @@ -0,0 +1,275 @@ +# /plugin-wallet 推荐用法迁移方案 + +> **状态：** 方案已锁版，可执行。决策汇总见 §三；中文标题锚点对策见 §4.2。 + +## 背景 + +`window.tron`（TIP-1193 provider）已成为 TronLink 的推荐接入入口，旧的 `window.tronLink` / `tronLink.tronWeb` / `tronLink.request` 仍作为兼容别名保留但不再推荐。 + +`/dapp` 子站已在前一轮改造中完成切换（commit `fb3cc8b`）。本方案处理 `/plugin-wallet` 下的文档对齐。 + +## 范围 + +- `docs/plugin-wallet/active-requests.zh.md` +- `docs/plugin-wallet/active-requests.en.md` +- `docs/plugin-wallet/passive-messages.zh.md` +- `docs/plugin-wallet/passive-messages.en.md` + +`ledger-signing-update.{zh,en}.md` 不涉及 provider，不动。 + +## 总体原则 + +1. **每篇文档主体只展示推荐用法（`window.tron`）。** +2. **每篇文档底部统一新增"旧版用法（不推荐）"区，集中放置 `window.tronLink` 等兼容用法。** +3. **新版的每个具体接口小节，末尾以一行 blockquote callout 链接到底部对应的旧版条目。** +4. **不删除任何旧 API 文档信息，只是搬位 + 重新组织。** + +--- + +## 一、active-requests 改造 + +### 1.1 当前结构与处理对照 + +| # | 当前小节 | 当前 API | 处理动作 | +|---|---|---|---| +| 1 | 连接网站 TIP-1102 | 新 `tron.request` | 保留为主版，末尾加旧版链接 | +| 2 | 连接网站（旧版）`tron_requestAccounts` | 旧 | **整段移到底部"旧版用法"区** | +| 3 | 获取 provider TIP-6963 | 新 | 保留，不动 | +| 4 | 普通转账 | 旧 `window.tronLink.ready` | **重写为新版**；原旧版代码片段拆出搬到底部 | +| 5 | 多签转账 | 旧 | 同上 | +| 6 | 消息签名 | 旧 | 同上 | +| 7 | 添加资产 | 主示例新 / 三个子例旧 | 子例改为 `window.tron.request`；原旧代码搬到底部 | +| 8 | 切换网络 TIP-3326 | 旧 `tronLink.request` | 改为 `window.tron.request`；旧版搬到底部 | + +### 1.2 目标骨架 + +``` +# 主动请求TronLink插件功能 + +### 连接网站 TIP-1102 +… 现有内容 … +> **旧版用法（不推荐）：** [兼容用法：tron_requestAccounts](#tron_requestaccounts) + +### 获取TronLink的provider TIP-6963 +（不动） + +### 普通转账 +> **前提条件：** 已通过 `eth_requestAccounts` 完成 DApp 连接授权（参见上方 [连接网站 TIP-1102](#tip-1102)）。 +（代码改为 `const tronweb = window.tron.tronWeb; …`，去掉 `if (window.tronLink.ready)` 包裹） +> **旧版用法（不推荐）：** [兼容用法：sendTrx（window.tronLink）](#sendtrx-window-tronlink) + +### 多签转账 +（前提条件 + 新代码 + 链接到旧版） + +### 消息签名 +（同上） + +### 添加资产 +（主示例已是新 API；TRC10/20/721 三个子例去掉 if 包裹，改 `window.tron.request`） +> **旧版用法（不推荐）：** [兼容用法：wallet_watchAsset（window.tronLink）](#wallet_watchasset-window-tronlink) + +### 切换网络 TIP-3326 +（代码改为 `await window.tron.request(...)`） +> **旧版用法（不推荐）：** [兼容用法：wallet_switchEthereumChain（tronLink.request）](#wallet_switchethereumchain-tronlinkrequest) + +--- + +## 旧版用法（不推荐） + +下列接口作为兼容别名保留，新接入请使用上方推荐用法。`window.tronLink` 与 `window.tron` 在功能上等价，但前者将逐步不再维护。 + +### 兼容用法：tron_requestAccounts +（搬自原"连接网站（旧版）"整段） + +### 兼容用法：sendTrx（window.tronLink） +（搬自原"普通转账"代码示例） + +### 兼容用法：multiSign（window.tronLink） +… + +### 兼容用法：signMessageV2（window.tronLink） +… + +### 兼容用法：wallet_watchAsset（window.tronLink） +（搬自原"交互流程"下三个 TRC 子例） + +### 兼容用法：wallet_switchEthereumChain（tronLink.request） +（搬自原"切换网络"代码示例） +``` + +### 1.3 锚点策略 + +MkDocs 默认 slug 会剥掉中文，保留 ASCII token 用 `-` 拼接、转小写、保留下划线。可在标题里以"兼容用法："形式预埋稳定锚点： + +| 中文标题 | 生成 slug | +|---|---| +| `### 兼容用法：tron_requestAccounts` | `tron_requestaccounts` | +| `### 兼容用法：sendTrx（window.tronLink）` | `sendtrx-window-tronlink` | +| `### 兼容用法：multiSign（window.tronLink）` | `multisign-window-tronlink` | +| `### 兼容用法：signMessageV2（window.tronLink）` | `signmessagev2-window-tronlink` | +| `### 兼容用法：wallet_watchAsset（window.tronLink）` | `wallet_watchasset-window-tronlink` | +| `### 兼容用法：wallet_switchEthereumChain（tronLink.request）` | `wallet_switchethereumchain-tronlinkrequest` | + +英文版用 `### Legacy: ` 形式，slug 形如 `legacy-tron_requestaccounts`、`legacy-sendtrx-via-windowtronlink` 等。 + +### 1.4 callout 文案 + +新版小节末尾统一插入： + +**中文：** +```markdown +> **旧版用法（不推荐）：** [兼容用法：sendTrx（window.tronLink）](#sendtrx-window-tronlink) +``` + +**英文：** +```markdown +> **Legacy (not recommended):** [Legacy: sendTrx via window.tronLink](#legacy-sendtrx-via-windowtronlink) +``` + +前提条件 callout（覆盖普通转账 / 多签转账 / 消息签名 / 添加资产，共 4 节；切换网络不加）： + +**中文：** +```markdown +> **前提条件：** 已通过 `eth_requestAccounts` 完成 DApp 连接授权（参见上方 [连接网站 TIP-1102](#tip-1102)）。 +``` + +**英文：** +```markdown +> **Prerequisite:** The DApp connection has been authorized via `eth_requestAccounts` (see [Request to connect website TIP-1102](#request-to-connect-website-tip-1102) above). +``` + +> 切换网络不需要预先授权，**不加**"前提条件"callout。 + +--- + +## 二、passive-messages 改造 + +### 2.1 现状 + +主体已基于 `window.tron`，底部已有两块旧版区域： + +- **历史遗留问题**：postMessage 派发的 `connectWeb` / `acceptWeb` / `rejectWeb` / `disconnectWeb`（3.x 兼容事件，未来会废弃）。 +- **已废弃的 3.x 事件**：`tabReply` / `setAccount` / `setNode`（主链 / 侧链检测）。 + +### 2.2 两种处理方案 + +**方案 A（推荐 · 最小变更）** + +- 保留现有两个旧版区结构（4.x postMessage 兼容 vs 3.x 主侧链）。 +- 在新版的 `accountsChanged` / `chainChanged` / `connect` / `disconnect` 四个小节末尾各加一行 callout，链接到对应的旧版条目。 +- 顶部 demo 代码块（HTML 示例）保持不动。 + +新→旧映射建议： + +| 新版事件 | 旧版对应（链接目标） | +|---|---| +| `accountsChanged` | `setAccount`（3.x） | +| `chainChanged` | `setNode` / `tabReply`（3.x） | +| `connect` | `connectWeb` / `acceptWeb`（postMessage） | +| `disconnect` | `disconnectWeb` / `rejectWeb`（postMessage） | + +**方案 B（彻底对齐 active-requests）** + +把两个旧版区合并成单一"## 旧版用法（不推荐）"大区，内部再分子小节。 + +**结论：选 A。** 现有两个旧版区主题不同（兼容事件 vs 3.x 主侧链），强行合并反而模糊。结构基本不动，只补 callout 链接。 + +--- + +## 三、确认事项（已锁定） + +| # | 项 | 决定 | +|---|---|---| +| 1 | 前提条件 callout 覆盖范围 | 转账 / 多签 / 消息签名 / **添加资产**（共 4 节）；切换网络不加 | +| 2 | callout 措辞 | `**旧版用法（不推荐）：**` | +| 3 | passive-messages | 方案 A（保留两块旧版区，新版小节补链接） | +| 4 | TIP-1102 是否链旧版 | 链到 `兼容用法：tron_requestAccounts` | +| 5 | 旧版区开篇说明 | 一两句简短说明（"作为兼容别名保留，新接入请使用上方推荐用法。`window.tronLink` 与 `window.tron` 在功能上等价，但前者将逐步不再维护。"） | + +--- + +## 四、已知风险与对策（执行前必读） + +### 4.1 风险：纯中文 `###` 标题的锚点不可靠 + +`普通转账` / `多签转账` / `消息签名` / `添加资产` 这 4 个小节标题全是中文，mkdocs 默认 slug 会剥到空串，被自动加上 `_1`、`_2` 等位置 fallback。现有文件里的 `[普通转账](#_13)` 就是这种情况 —— 数字 `13` 是页面内累计的空 slug 计数器，**不能在文件重排后稳定预测**。 + +这会影响： + +- 新版小节里"参见上方 [普通转账]" / "参见上方 [多签转账]" 等回链 +- 底部"旧版用法"区的"新接入请使用上方 [普通转账]"等回链 +- TIP-1102 顶部如果想链到任何一节，同样有问题 + +> 注：`TIP-1102` / `TIP-6963` / `TIP-3326` 这几节标题混了 ASCII，slug 可稳定预测为 `#tip-1102` / `#tronlinkprovider-tip-6963` / `#tip-3326`，不受影响。 + +### 4.2 对策（三选一，请挑选） + +**对策 A：给纯中文小节标题加 ASCII 方法名后缀（推荐）** + +改为： +- `### 普通转账 sendTrx` → slug `sendtrx` +- `### 多签转账 multiSign` → slug `multisign` +- `### 消息签名 signMessageV2` → slug `signmessagev2` +- `### 添加资产 wallet_watchAsset` → slug `wallet_watchasset` + +优点：slug 完全可控；标题里直接显示方法名对开发者也是好事；跟既有 `获取TronLink的provider TIP-6963` 这种"中英混合标题"风格一致。 +缺点：每个小节标题变长一截，视觉略变化。 + +**对策 B：不在新版小节之间互链，纯中文方位词描述** + +如"参见上方「普通转账」"，不写 markdown 链接。 + +优点：标题不动。 +缺点：放弃了点击跳转的便利；侧栏 / 目录里的"普通转账"虽然可点击，但行文中没有热区。 + +**对策 C：跑一次 mkdocs build，把生成的真实 slug 反写回链** + +优点：保留中文标题。 +缺点：必须先 build 一遍；任何后续小节顺序变化都会让 `_N` 编号漂移，长期维护成本高；放弃了"自描述性"。 + +**已确认：对策 A。** 4 个纯中文小节标题改为： + +- `### 普通转账 sendTrx`（slug `sendtrx`） +- `### 多签转账 multiSign`（slug `multisign`） +- `### 消息签名 signMessageV2`（slug `signmessagev2`） +- `### 添加资产 wallet_watchAsset`（slug `wallet_watchasset`） + +### 4.3 旧版区标题的锚点 + +旧版区的标题都预埋了 ASCII 方法名（`### 兼容用法：tron_requestAccounts` 等），slug 可控（见 §1.3 表）。**不受 4.1 影响。** + +### 4.4 跨页引用检查 + +仓库内只有 2 处对 `active-requests.md#xxx` 锚点的跨页引用，且都指向 TIP-6963 小节（slug `tronlinkprovider-tip-6963` / `get-tronlink-provider-via-tip-6963`），本次方案 **不动这个小节**，不会断链： + +``` +docs/plugin-wallet/passive-messages.zh.md:93 → #tronlinkprovider-tip-6963 +docs/plugin-wallet/passive-messages.en.md:93 → #get-tronlink-provider-via-tip-6963 +``` + +--- + +## 五、执行步骤（确认对策 A/B/C 后开工） + +1. `active-requests.zh.md` 重排： + - 删除原"连接网站（旧版）"小节，整段搬到底部"旧版用法"区 + - 4 个业务小节（普通转账 / 多签转账 / 消息签名 / 添加资产）： + - 按对策 A/B/C 处理小节标题 + - 顶部插入"前提条件" callout + - 代码改为 `const tronweb = window.tron.tronWeb; …`，去 `if (window.tronLink.ready)` 包裹 + - 末尾插入"旧版用法（不推荐）"链接 callout + - 切换网络小节：代码改为 `window.tron.request(...)`；末尾加旧版链接；不加前提条件 + - TIP-1102 小节末尾加旧版链接（指向 `兼容用法：tron_requestAccounts`） + - 文末新增 `## 旧版用法（不推荐）` 大区，下设 6 个 `###` 兼容用法子节 +2. `active-requests.en.md` 同步以上改动（英文标题天然有 ASCII slug，不涉及对策 A/B/C 取舍） +3. `passive-messages.zh.md` 4 个事件小节（accountsChanged / chainChanged / connect / disconnect）末尾各加一行旧版 callout，链接到对应 postMessage / 3.x 子节 +4. `passive-messages.en.md` 同步 +5. 本地 `mkdocs serve` 校验全部站内锚点跳转可用，无 404 +6. 一次性 commit：`migrate plugin-wallet docs to window.tron and isolate legacy usage` + +## 六、影响面 + +- **不破坏现有接入**：旧 API 用法全部保留在底部"旧版用法"区，搜索引擎与现有外链可继续命中。 +- **mkdocs.yml 不需要改**：导航条目数量不变；不引入 admonition 等新扩展。 +- **跨页引用**：见 §4.4，无断链风险。 +- **未涉及 mobile 端**：移动端 DApp 注入逻辑不同，本次不动。 diff --git "a/\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" "b/\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" new file mode 100644 index 0000000..85f4ca4 --- /dev/null +++ "b/\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" @@ -0,0 +1,634 @@ +# TronLink 开发者文档评审报告（MCP + CLI + Skill + AI 入口） + +**评审日期**：2026-05-27 +**评审依据**： +- [`MCP 文档标准 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) +- [`CLI 文档标准 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) +- [`Skill 产品文档标准 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) +- [`公共安全与错误码基线 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) +- [`项目级覆盖度评分标准 V1.7`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) + +**评审对象**：[docs.tronlink.org/zh/](https://docs.tronlink.org/zh/)「AI 支持」章节 6 篇文档 +**文档基线**：Updated 2026-05-21T14:08:15Z · Commit `e724781c635f`（docs 源码托管在 [`xueyuanying/docs`](https://github.com/xueyuanying/docs)） + +| # | 文档 | 适用标准 | +|:-:|------|---------| +| 1 | [MCP Server TronLink](https://docs.tronlink.org/zh/ai-support/mcp-server-tronlink/) | MCP V1.0 | +| 2 | [TronLink MCP Core](https://docs.tronlink.org/zh/ai-support/tronlink-mcp-core/) | MCP V1.0 | +| 3 | [MCP TronLink Signer](https://docs.tronlink.org/zh/ai-support/mcp-tronlink-signer/) | MCP V1.0 | +| 4 | [TronLink CLI](https://docs.tronlink.org/zh/ai-support/tronlink-cli/) | CLI V1.0 | +| 5 | [TronLink Skills](https://docs.tronlink.org/zh/ai-support/tronlink-skills/) | Skill V1.0 | +| 6 | [AI / LLMs 入口页](https://docs.tronlink.org/zh/ai-support/ai-llms/) | 覆盖度 V1.7 + 跨标准 | + +> **维护方说明**：本报告覆盖 6 篇文档。1–4 + 6 由 Leon 团队维护；**Skills（#5）由产品组维护**——请协助转发给对应 owner，或内部对齐后统一回应。Skills 部分的 P2 改进项与 Leon 的 P1-3 / P1-9 联动，建议两边协调整改。 + +--- + +## 一、总评 + +| # | 文档 | 类型判定 | 内容 | Agent | 安全 | 加权 | 整改后预期 | 等级 | +|:-:|------|---------|:---:|:---:|:---:|:---:|:---:|:---:| +| 1 | MCP Server TronLink | High-risk / Mutative（30/40/30） | 8 | 9 | 9 | **87.0** | 98 | A | +| 2 | TronLink MCP Core | General / Agent-first（25/60/15） | 7 | 8 | 8 | **77.8** | 95 | B+ | +| 3 | MCP TronLink Signer | High-risk / Mutative（30/40/30） | 8 | 8 | 10 | **88.0** | 96 | A | +| 4 | TronLink CLI | High-risk CLI（30/40/30） | 9 | 10 | 9 | **94.0** | 99 | A+ | +| 5 | TronLink Skills | Read-only Data Skills（35/50/15） | 10 | 10 | 9 | **98.5** | 100 | A+ | +| 6 | AI / LLMs 入口页 | 覆盖度 + 跨标准入口 | 10 | 10 | 10 | **100.0** | 100 | A+ | +| **平均** | — | — | — | — | — | **90.9** | **98.0** | **A** | + +**整体结论**： + +- **TRON 生态当前 4 类文档（API / MCP / CLI / Skill）中标杆级别**——6 篇全部 A 级以上，3 套标准 P0 gate（MCP 6 + CLI 6 + Skill 6 = 18 项）全部通过 +- **差距来源不在内容深度，而在三类硬伤**：跨文档死链（如 `tronlink-mcp-core.md#错误码` 锚点 3 处死链）、文档与代码漂移（Flow Recipes 文档 32 / 实际 23 / 含 2 个不存在 flow 名）、发布工程缺失（5 个 npm 包全部 0 GitHub releases） +- **三类硬伤都有清晰整改路径**——下文按优先级展开，整改后可达 98 分（A） + +**亮点**（保留上一轮认知，下文 §二 详述）：CI schema parity、错误码 SSOT 设计意图、Content-Signal robots、退出码 6 档 retryable、多签凭证 5 维管理、`tl_evaluate` 三 host 禁用示例、依赖钉版 + 数据截至时间戳、Skills 反例表与判断口诀——均超 V1.0 标准明文要求。 + +--- + +## 二、20 条亮点汇总（建议回流标准 V1.1） + +按标准维度分类，提议作为 V1.1 评分锚点 / P0 加项的素材，按价值排序。 + +### 2.1 Agent 可用性维度（10 条） + +| # | 亮点 | 出处 | 标准对应 | +|:-:|------|------|---------| +| 1 | **「❌ 不要走这里（反例）」专节 + 判断口诀** | Skills | Skill §4.1「发现选择」10 分锚点「有路由表和负向触发」的极致实现 | +| 2 | **Skill ↔ MCP 工具映射表 + 子集关系明示**（25/33 + minor 内只增不减） | Skills | Skill §4.1 客户端兼容 + 版本契约创新 | +| 3 | **用户提问 → Skill → 工具三层路由表**（21 行常见提问对照） | Skills | Skill §4.1 发现选择 10 分 | +| 4 | **每个 skill 内置「何时不要用」写到命令粒度** | Skills | Skill §4.1 负向触发 10 分 | +| 5 | **CI 强制 schema parity 检查**（`scripts/check_doc_schema_parity.py`，文档侧 schema ↔ 上游 schemas.ts 自动 diff） | MCP Server | MCP §6 P0「缺 inputSchema」加分实践 | +| 6 | **错误码 SSOT 跨文档共享**：CLI / MCP Server / MCP Signer 共用 `tronlink-mcp-core#错误码`，含 `code / retryable / hint / 典型触发` | MCP Core | MCP §3 错误契约 10 分 | +| 7 | **HTTP / EVM / DeepLink / MCP / CLI 五通道错误码对照表**（[`reference/error-code-map`](https://docs.tronlink.org/zh/reference/error-code-map/)）以业务含义为主轴横向 join | 全站 | 跨标准创新 | +| 8 | **input schema 文档侧镜像**（MCP Server 镜像 `tl_chain_send` / `tl_chain_swap_v3` / `tl_chain_stake` / `tl_multisig_submit_tx` / `tl_gasfree_send` / `tl_chain_get_account` / `tl_evaluate` 7 个），明示 list_tools 是权威源 | MCP Server | MCP §3 Schema 完整度 10 分 | +| 9 | **副作用 4 分级**（Network Read / Local Write / Remote Write / Destructive）+ 逐工具表标注 | 全站 | MCP §4 / CLI §4 副作用 10 分 | +| 10 | **CLI `--json` 是自动化契约的明文承诺**（minor 加不减、改名属 major） | CLI | CLI §3 机器输出 10 分 | + +### 2.2 安全与权限维度（6 条） + +| # | 亮点 | 出处 | 标准对应 | +|:-:|------|------|---------| +| 11 | **`tl_evaluate` 三种 host 禁用配置示例**（Claude Code / Claude Desktop / 通用 MCP 客户端） | MCP Server | MCP §6 P0「远程 MCP 无 SSRF」加分实践 | +| 12 | **多签凭证 5 维管理**（按环境隔离 / 存储 / 轮换 / 撤销 / 最小权限） | MCP Server | MCP §5.1 权限授权 10 分 | +| 13 | **钱包密钥两路径对比表**（手动 vs 自动创建），含「待解决（代码侧）」字段明示文档级方案与代码 PR 关系 | MCP Server | MCP §5.1 安全规则 10 分 | +| 14 | **兑换安全专章**（minOut / 滑点上限 / 钉死 router / 不可自动重试） | MCP Server | MCP §5.1 风险防护 10 分 | +| 15 | **7 大安全边界逐条给 agent 与运维方义务**（Prompt 注入 / SSRF / token passthrough / 浏览器 JS / HITL 绕过 / confused deputy / 传输） | MCP Server | MCP §5.1 全维 10 分 | +| 16 | **robots.txt 用 Content-Signal 协议区分 inference vs training**（`search=yes, ai-train=no` + 显式 Disallow GPTBot / ClaudeBot / CCBot）；把 `llms.txt` / `llms-full.txt` 标为 inference 入口 | 全站 | 公共基线 §2 原则 11 机器可抓取的前沿做法 | + +### 2.3 人读维度（4 条） + +| # | 亮点 | 出处 | 标准对应 | +|:-:|------|------|---------| +| 17 | **双层 llms.txt**（精选索引 + 全文聚合，中英双版，源带 commit hash + UTC 时间戳） | 入口页 | 项目级覆盖度 §0 + 公共基线 §6 自发现入口 | +| 18 | **CLI 退出码 6 档 + 每档 retryable 列**（`0/1/2/3/4/5` + 「已提交但结果未知」不得自动重试） | CLI | CLI §3 错误契约 10 分 | +| 19 | **依赖钉版 + 数据带「截至 2026-05」标注**（`tronweb 6.2.2` / `tronlink-signer 0.1.4` / `mcp-server-tronlink@0.1.1` 全部钉版） | 全站 | MCP §5 / CLI §3 版本与兼容性 10 分 | +| 20 | **零依赖 / 零 npm install + `install.sh` / `uninstall.sh` 全生命周期脚本** | Skills | Skill §3.1 安装接入 10 分锚点 | + +> **回流建议**：前 4 条（Agent 可用性）建议升级为 V1.1 的「10 分新锚点」；中间 5 条（安全）建议补入 P0 检查项；后 4 条（人读 + 版本）作 V1.1 加分项写入正文。 + +--- + +## 三、单文档详评 + +### 3.1 MCP Server TronLink — A，87/100 + +**类型判定**：High-risk / Mutative MCP（含 `tl_chain_send`、`tl_chain_swap_v3`、`tl_evaluate` 等 Remote Write 与 Destructive 原语） + +| 维度 | 分 | 主要依据 | +|------|:---:|---| +| 人读 (30%) | **8** | 概述 / 双模架构图（mermaid）/ 双模运行机制 / 6 大核心组件 / 4 集成方式 / 项目结构 完整；扣 2 分：Flow Recipes 三方计数矛盾 + 含 2 个不存在 flow 名（详见 P0-2） | +| Agent 可用性 (40%) | **9** | 工具发现走 list_tools 权威源；input schema 精选镜像 + CI parity；副作用 4 分级；错误契约用 `error.code`；扣 1 分：`tronlink-mcp-core.md#错误码` 锚点死链（详见 P0-1） | +| 安全与权限 (30%) | **9** | 7 大安全边界、兑换安全专章、多签凭证 5 维、钱包路径 A/B 对比、`tl_evaluate` 三 host 禁用示例；扣 1 分：`@bankofai/agent-wallet` 版本管理问题（GitHub 404 + 文档版本落后 npm，详见 P0-3） | + +### 3.2 TronLink MCP Core — B+，77.8/100 + +**类型判定**：Agent-first MCP（框架库，给上层 server 复用） + +| 维度 | 分 | 主要依据 | +|------|:---:|---| +| 人读 (25%) | **7** | 完整覆盖架构 / ISessionManager / 9 个能力接口 / 52 工具定义 / Knowledge Store / Flow Recipe 系统 / 元素定位 3 方式；扣 3 分：错误码节标题缺失（应在「标准化响应格式」节下加 `## 错误码` 二级标题响应下游 3 文档引用，详见 P0-1）+ 缺「何时用 mcp-core / 何时用 mcp-server-tronlink」决策矩阵（P1-4） | +| Agent 可用性 (60%) | **8** | 错误码 SSOT 实质在本文档；标准化响应格式；52 工具完整定义；Flow Recipe 含依赖解析；扣 2 分：SSOT 身份未明示 + 下游 3 文档死链（P0-6） | +| 安全与权限 (15%) | **8** | 由上层 server 实现具体边界，本文档只定义抽象能力；扣 2 分：缺「具体安全边界由实现 server 提供，参考 mcp-server-tronlink §安全模型」交叉引用 | + +### 3.3 MCP TronLink Signer — A，88/100 + +**类型判定**：High-risk / Mutative MCP（签名 + 广播） + +| 维度 | 分 | 主要依据 | +|------|:---:|---| +| 人读 (30%) | **8** | 完整覆盖配置（Claude Code / Claude Desktop / Cursor / 源码）/ MCP 工具 / 资源 / 提示词 / 工作原理 / 端到端示例 / 取消 / 交易确认 / 错误 / 安全边界 / 环境变量 / 版本 + 内联 changelog；扣 2 分：缺「该用哪个」三选一对照表（P1-1）+ 与 SDK 版本对应关系不明（P1-7） | +| Agent 可用性 (40%) | **8** | 工具表含 7 列 + 副作用 + 可自动重试列；HITL 明确不可绕过；扣 2 分：input schema 没像 mcp-server-tronlink 那样镜像精选示例，全靠 list_tools（P1-2） | +| 安全与权限 (30%) | **10** | HITL 必经浏览器审批；私钥不离开 TronLink；明示哪些是 Remote Write 且不可自动重试；签名类只 Local Write 可重试 | + +### 3.4 TronLink CLI — A+，94/100 + +**类型判定**：High-risk CLI（HITL 写操作 + 远程广播） + +| 维度 | 分 | 主要依据 | +|------|:---:|---| +| 人读 (30%) | **9** | Overview / 环境要求（依赖钉版 + 数据截至时间）/ 全局选项 / 命令分类 / 交易签名 / 预览 / 广播双路径 / 输出格式 / 退出码 / 错误 / 安全 / 工作原理 / **AI 智能体使用专章** / 版本与兼容性；扣 1 分：常用代币合约表只列 3 个（与 Skills 8 个不一致，P1-3） | +| Agent 可用性 (40%) | **10** | `--json` 机器输出契约；`error.code` 跨文档 SSOT 引用；退出码 6 档 + retryable；ABI v2 完整支持（tuple / 嵌套数组 / tuple 数组）；pre-flight 模拟在签名前；AI 智能体专章含端到端转账流程示例 | +| 安全与权限 (30%) | **9** | 副作用分级表；HITL 必经浏览器；写操作不自动重试；私钥不离开 TronLink；输入校验 14 条；本地广播与签名器广播的双广播去重机制说明；扣 1 分：退出码 5「网络错误」缺「如何确认上一笔未上链」指引（P2-5） | + +### 3.5 TronLink Skills — A+，98.5/100 + +**类型判定**：Read-only Data Skills（35/50/15）+ Skills/MCP/CLI Hybrid 特征 + +| 维度 | 分 | 主要依据 | +|------|:---:|---| +| 人读 (35%) | **10** | Overview / Why / 架构图 / 6 大 skill 详解 / 4 集成方式 / 配置 / TRON 资源模型 / 快速开始 / 版本与许可证 全覆盖 | +| Agent 可用性 (50%) | **10** | Skill ↔ MCP 工具映射表 + 用户提问路由表 + 反例表 + 子集关系明示（25/33）+ 5 个客户端配置 + 兼容性与迁移策略 | +| 安全与权限 (15%) | **9** | 纯只读 + 副作用统一 Network Read + 每个 skill「何时不要用」+ 反例表；扣 1 分：TronGrid API Key 的最小权限 / 轮换 / 泄漏处置无明文（Skills P2-3） | + +**§7 P0 gate 6/6 全过；§6 推荐结构 10.5/11 覆盖**（Troubleshooting 散在「安全模型」表，未独立成节，Skills P2-1） + +**数据 vs 代码核对（全部对齐）** — Skills 是 6 篇文档中唯一一份「重审无新发现」的样板： + +| 文档声明 | 实测来源 | 实测值 | 状态 | +|---------|---------|:---:|:---:| +| 33 个 CLI 命令 | `scripts/tron_api.mjs` 实际 `"":` 定义数 | **33** | ✅ | +| 25 个 MCP 工具 | `scripts/mcp_server.mjs` 实际 `name: "tron_*"` 数 | **25** | ✅ | +| 8 个 CLI-only | 33 − 25 = 8 + 文档明确列出 | **8** | ✅ | +| 6 大技能 | `skills/` 目录子文件夹数 | **6** | ✅ | +| 子集关系 MCP ⊂ CLI | 25 个 `tron_*` 全部对应到 CLI 命令 | **完美对应** | ✅ | + +### 3.6 AI / LLMs 入口页 — A+，100/100 + +不在 MCP / CLI / Skill 标准评分清单（属导流入口页），整体质量极高： + +- ✅ 4 个端点表（中英 × 索引 / 全文） +- ✅ 「该用哪个文件」场景表 +- ✅ Cursor / Claude / 其他工具的添加指引 +- ✅ 覆盖范围（指向 6 个 AI 工具链文档） +- ✅ 给智能体的 4 条明文说明 +- ✅ allowed-use vs robots.txt 与 Content-Signal 的关系澄清 + +仅 1 条 P2：缺版本契约引用（P2-7） + +--- + +## 四、必改清单（P0：相关标准 gate 失败） + +### P0-1 ⚠️ 死链：`tronlink-mcp-core.md#错误码` 锚点在目标文档不存在 + +**标准依据**：MCP §6 P0「缺错误结构 → Agent 无法分支处理」+ CLI §6 P0「缺 error code / exit code」+ 公共基线「全站无事实自相矛盾」 + +**现状**：3 个文档引用同一个死锚点： + +| 引用方 | 行号 | 引用形式 | +|--------|------|----------| +| mcp-server-tronlink | §「工具契约与副作用」L422 | `[TronLink MCP Core](tronlink-mcp-core.md#错误码) 的 SSOT 错误码表` | +| mcp-server-tronlink | §「兼容性与迁移策略」L729 | `error.code 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码)）` | +| tronlink-cli | §「兼容性与迁移策略」L475 | `error.code 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 共享 SSOT）` | + +**但 tronlink-mcp-core 文档没有 `## 错误码` 章节**。它的章节是：概述 / 架构设计 / 与 mcp-server-tronlink 的关系 / ISessionManager 接口 / 9 个能力接口 / 52 工具定义 / **标准化响应格式** / Knowledge Store / Flow Recipe 系统 / 元素定位 / 安装与使用 / 项目结构 / 依赖项 / 构建与开发 / 关键设计模式 / 版本与许可证。错误码表实际位于「标准化响应格式」节内的子段，渲染后**没有 `#错误码` 锚点**。 + +**Agent / 开发者影响**：跟链接 → 落到文档顶部或抛 404 锚点，**拿不到错误码 SSOT 表**。这违反了文档明示的「Agent 应基于 `error.code` 与 `error.retryable` 分支」。 + +**整改方案**（任选其一）： + +- **方案 A**（推荐）：在 tronlink-mcp-core 文档「标准化响应格式」节下显式增加 `## 错误码` 二级标题，把现有错误码表移到该节下。锚点变为 `tronlink-mcp-core.md#错误码`，与 3 处引用对齐 +- **方案 B**：把 3 处引用统一改为存在的锚点（如 `tronlink-mcp-core.md#标准化响应格式`），但需要保证错误码表在该节下且足够独立 + +**附加建议**：错误码表头加一行明示 SSOT 身份： + +``` +> SSOT for: mcp-server-tronlink, mcp-tronlink-signer, tronlink-cli — 任何下游文档变更需先在此更新。 +``` + +**验收**：3 处跨文档引用全部跳转到包含错误码表的实际位置；mkdocs build 不报 broken anchor warning。 + +--- + +### P0-2 ⚠️ Flow Recipes 三方数据矛盾，并含 2 个不存在的 flow 名 + +**标准依据**：MCP §3 Schema 完整度 + 公共基线「全站无事实自相矛盾」+ §2 原则 3 稳定字段契约 + +**现状**：mcp-server-tronlink §「Flow Recipes（32 个内置流程）」三处计数互相矛盾： + +| 来源 | 计数 | +|------|------| +| 节标题 | **32 个** | +| 子类型表加总（Playwright 4 + 链上 11 + 多签 6 + GasFree 3） | **24 个** | +| `src/flows/*.ts` 实际 `export const ...Flow` 数 | **23 个**（GasFree 3 + import-wallet 1 + multisig 6 + onchain **9** + switch-network 2 + transfer-trx 2） | + +**文档列了但代码不存在的 flow**（即死链 flow 名）： + +| 文档列出 | 代码核对 | +|---------|---------| +| `chainTransferTrc20Flow` | ❌ 不存在于 `src/flows/onchain.ts` | +| `chainSwapV3Flow` | ❌ 不存在于 `src/flows/onchain.ts` | + +**文档遗漏的 flow**（代码有但表里没列）： + +| 代码存在 | 文档核对 | +|---------|---------| +| `src/flows/import-wallet.ts` 内的 import wallet flow | ❌ 整个文件 / flow 在文档中未提及 | + +**Agent / 开发者影响**：基于文档调 `tl_run_steps --flow chainTransferTrc20Flow` 会得到「flow not found」错误；同时不知道有 import-wallet flow 可用。 + +**整改**： + +1. 重新统计实际 flow，更新节标题（如「Flow Recipes（**23 个内置流程**）」） +2. 子类型表与代码逐项对齐： + - **链上类**：删除 `chainTransferTrc20Flow` / `chainSwapV3Flow`，改为 9 个；或在 onchain.ts 补这 2 个 flow 实现 + - **新增 Wallet 类**：列出 `importWallet*Flow` +3. 加 CI parity 检查（参考已有的 `scripts/check_doc_schema_parity.py` 模式）：扫 `src/flows/*.ts` 的 `export const ...Flow` 与文档表逐项 diff，CI 失败时阻塞 merge + +**验收**：文档总数 = 子类型加总 = 代码实际数；CI parity 检查覆盖 flow 名集合。 + +--- + +### P0-3 ⚠️ `bankofai/agent-wallet` GitHub 404 + 文档钉版 `^2.3.0` 已落后 npm 的 `2.4.0` + +**标准依据**：MCP §3 版本与兼容性 10 分锚点「有 breaking change / migration」+ 公共基线 §9 通用安全底线 + +**现状**： + +- mcp-server-tronlink §「依赖项」表写：`@bankofai/agent-wallet | ^2.3.0 | 加密本地钱包管理（local_secure）——已钉版本，不用 latest，确保钱包行为可复现` +- npm 实测：`@bankofai/agent-wallet@latest = 2.4.0`（2026-05 已发，维护者 = TRON 团队成员 parson.hu / hades.ye / leo.wu @tron.network） +- GitHub `bankofai/agent-wallet` repo **HTTP 404** + +**Agent / 开发者影响**： + +1. 钉版 `^2.3.0` 在 npm semver 下允许 2.3.x ~ 2.4.0 之前的所有版本，**实际锁不住 2.4.0**。文档"已钉版本"的承诺与实际不符 +2. GitHub 404 让开发者无法看源码 / 提 issue / 核对依赖透明性 +3. `agent-wallet` 持有钱包密码（`AGENT_WALLET_PASSWORD`），其源码不可见对安全敏感场景是 deal-breaker + +**整改**： + +1. 钉死到准确版本：`"@bankofai/agent-wallet": "2.3.0"`（无 caret），或显式声明「kept on 2.3.0; 2.4.0 待评估」 +2. 补一行：「GitHub 仓库当前未公开，源码透明性由 npm publish 提供。可通过 `npm pack @bankofai/agent-wallet@2.3.0 && tar -xzf ...` 解包审计。」 +3. 评估升级到 2.4.0（若 breaking 则 CHANGELOG 说明，若不 breaking 则升级减少漂移风险） + +**验收**：依赖版本与 npm 实际锁定一致；文档明示 GitHub 404 状态 + 源码审计路径；2 周内决策是否升级到 2.4.0。 + +--- + +### P0-4 ⚠️ 5 个 TronLink npm 包全部 0 GitHub releases / 0 tags + +**标准依据**：MCP §3 版本与兼容性 9 分锚点「有协议/server/schema 版本」+ CLI §3 版本/更新 10 分锚点「SPDX、changelog、deprecated、migration」+ 公共基线 §2.6 原则 10 一致性 + +**现状**： + +| Repo | npm latest | GitHub releases | GitHub tags | +|------|-----------|:---:|:---:| +| TronLink/mcp-server-tronlink | v0.1.1 | **0** | **0** | +| TronLink/tronlink-mcp-core | v0.1.0 | **0** | **0** | +| TronLink/mcp-tronlink-signer | (在子目录) | **0** | **0** | +| TronLink/tronlink-cli | v1.0.1 | **0** | **0** | +| TronLink/tronlink-skills | v1.0.1 | **0** | **0** | + +文档已明示「截至当前 v1.0.x / 0.1.x 尚无 GitHub tag 发布；打 tag 之前请直接看 commit 历史」——已知缺陷，但这是**5 个 repo 全部** 0 发布的系统性问题。 + +**Agent / 开发者影响**： + +1. npm 版本号无法对应到 GitHub commit hash，agent 无法基于 git tag 复现「v1.0.1 时的代码状态」 +2. 「Releases」是 GitHub 标准发布通知机制，0 releases = 订阅者收不到新版通知 +3. 文档说「兼容性与迁移策略」承诺「废弃窗口至少一个 minor 周期」，但没有 minor 边界（tag）参考点，策略落地不了 + +**整改**： + +1. 5 个 repo 一次性把当前 npm 版本回溯打 tag：`git tag v0.1.1 ` + `git push --tags` + `gh release create v0.1.1 --notes "$(npm view dist.shasum)"` +2. 加 npm publish CI workflow：每次 publish 自动打 tag + 创建 GitHub Release（含 npm shasum + dist tarball） +3. 文档兼容性节移除「打 tag 之前请直接看 commit 历史」（变成默认有 tag） + +**验收**：5 repo 每个 npm 版本对应一个 git tag + GitHub Release；Releases 页可订阅。 + +--- + +### P0-5 ⚠️ docs.tronlink.org 源码托管在 `xueyuanying/docs` 个人 repo（所有权 / 单点风险） + +**标准依据**：公共基线 §8 License + §9 通用安全底线 + 项目级覆盖度 §0「AI 入口索引层 = 帮 AI / Agent 找到权威文档」 + +**现状**： + +- mcp-server-tronlink §「精选工具 schema」L441 引用：`[check-doc-schema-parity.yml](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)` +- gh api 实测：`xueyuanying/docs` 是个人 repo，pushed 2026-05-21（与文档站 Updated 时间戳一致 → 强烈暗示这是 docs.tronlink.org 的源码 repo） +- TronLink org 下没有看到对应的 docs repo + +**Agent / 开发者影响**： + +1. 开发者看到 CI 配置在个人 repo 会困惑（这是 TronLink 官方维护吗？） +2. 单点风险：维护者离职 / 转岗 / repo 删除 / 转 private → docs.tronlink.org 失去更新管道 +3. 公开引用个人 repo URL 暴露了维护者身份信息 + +**整改**： + +1. 把 docs 源码 repo 转移到 TronLink org（如 `TronLink/docs` 或 `TronLink/developer-docs`），保留 git history +2. 转移后更新 mcp-server-tronlink 文档里的 CI 引用 URL +3. 在 docs repo README 明示所有权 / 维护者 / contributor 流程 + +**验收**：docs 源码在 TronLink org 下可见；文档内所有引用 URL 更新到 org repo；GitHub URL `xueyuanying/docs` 可保留为 redirect 或归档。 + +--- + +### P0-6 ⚠️ MCP Core 错误码 SSOT 身份未明示 + +**标准依据**：MCP §3 错误契约 10 分锚点「可用于 agent 自动分支」+ 公共基线「跨文档错误码 SSOT 必须明示下游引用方」 + +**现状**：tronlink-mcp-core「标准化响应格式」节包含错误码表（实际 SSOT），但**未明示**它是 mcp-server-tronlink / mcp-tronlink-signer / tronlink-cli 三个下游文档共用的 SSOT。读者首次进入 mcp-core 文档无法判断错误码表的权威性。 + +**整改**：错误码表头加： + +```markdown +## 错误码 + +> **SSOT**：本表是 [mcp-server-tronlink](mcp-server-tronlink.md)、[mcp-tronlink-signer](mcp-tronlink-signer.md)、[tronlink-cli](tronlink-cli.md) 三个下游文档共用的错误码权威源。任何错误码新增 / 修改 / 删除均需先在本表更新，下游同步引用。变更需在 CHANGELOG 标注 breaking / non-breaking。 + +| Code | Retryable | Hint | Typical Trigger | +| ---- | :---: | ---- | ---- | +| TL_CLICK_FAILED | true | 重试前先 screenshot 确认 UI 状态 | ... | +| ... +``` + +**验收**：mcp-core 错误码表头部含 SSOT 声明；下游 3 文档的「error.code 枚举」段落改为「引用 mcp-core 错误码（SSOT），不在此重复」。 + +--- + +## 五、强建议整改（P1） + +### P1-1 MCP Signer 头部缺「该用哪个」三选一对照表 + +**现状**：mcp-server-tronlink 多处提到「生产环境涉及资金转移的工具，优先用 `mcp-tronlink-signer`（浏览器审批），而非 Direct-API」（L570 / L651），但 mcp-tronlink-signer 文档头部**没有反向对照表**，新读者无法快速判断三者差异。 + +**整改**：在 mcp-tronlink-signer §「配置」之前加： + +```markdown +## 该用哪个 + +| 选项 | HITL | 凭证 | 适用场景 | +|------|:---:|------|---------| +| `mcp-tronlink-signer`（本服务） | ✅ 浏览器审批 | 无（钱包在 TronLink 扩展） | 生产环境真实资金转移、需要用户每笔确认 | +| `mcp-server-tronlink` Direct-API 模式 | ❌ 无 | `AGENT_WALLET_PASSWORD` | CI / 自动化批量操作、非真实资金（测试网） | +| `tronlink-cli` | ✅ 浏览器审批 | 无 | Shell 脚本、终端工作流 | + +如不确定，优先选 `mcp-tronlink-signer`（最安全的默认值）。 +``` + +--- + +### P1-2 MCP Signer 缺 input schema 精选镜像 + +**现状**：mcp-server-tronlink 文档侧镜像了 7 个工具 input schema（`tl_chain_send` / `tl_chain_swap_v3` / `tl_chain_stake` 等）并 CI parity；mcp-tronlink-signer 完全不镜像，全依赖 `list_tools`。Agent 在没有 MCP 会话时无法离线编写工具调用。 + +**整改**：至少镜像 `send_trx` / `send_trc20` / `sign_typed_data` 3 个核心写工具的 input schema；加入同套 CI parity 检查覆盖范围。 + +--- + +### P1-3 跨文档代币 symbol 表不一致 + +**现状**： + +| 文档 | 内置代币 symbol 表内容 | +|------|------| +| `tronlink-cli` AI 智能体使用一节 | USDT / USDD / USDC（3 个） | +| `tronlink-skills` §「内置代币快捷符号」 | TRX / USDT / USDC / WTRX / BTT / JST / SUN / WIN（8 个） | +| `reference/networks`（公共参考） | 当前不明（待核） | + +差异：CLI 缺 BTT/JST/SUN/WIN/WTRX；Skills 缺 USDD。 + +**整改**：在 `reference/networks` 集中维护一份「常用代币合约 SSOT」（建议 ≥10 个：含 TRX / USDT / USDD / USDC / WTRX / BTT / JST / SUN / WIN 等），CLI / Skills / 其他文档统一引用，避免维护漂移。 + +--- + +### P1-4 MCP Core「与 mcp-server-tronlink 的关系」节缺决策矩阵 + +**现状**：mcp-core §「与 mcp-server-tronlink 的关系」存在，但未提供「何时用 mcp-core / 何时直接用 mcp-server-tronlink」的决策表。开发者拿到两个包不知道该选哪个。 + +**整改**：在该节加： + +```markdown +| 场景 | 选 mcp-core | 选 mcp-server-tronlink | +|------|:---:|:---:| +| 自建定制 MCP server（嵌入业务逻辑） | ✅ | ❌ | +| 直接给 agent 用 | ❌ | ✅ | +| 扩展能力（自定义 Capability） | ✅ | ❌ | +| 测试 / mock | ✅ | ✅（带 e2e 模式） | +| 学习 MCP 框架 | ✅ | ❌ | +``` + +--- + +### P1-5 onchain.ts 缺 `chainTransferTrc20Flow` / `chainSwapV3Flow` 实现（同步 P0-2） + +**现状**：见 P0-2。文档列了这两个但代码缺。 + +**整改方案**（任选其一）： + +- **方案 A**：补实现（如果产品确实需要）—— 参考 `chainTransferTrxFlow` / 现有 swap 工具 `tl_chain_swap_v3` 写 flow 包装 +- **方案 B**：文档删除这两行（如果产品决策不做 flow，只暴露原子工具） + +--- + +### P1-6 MCP Server 文档头「快速开始」步骤 3 钱包路径 A/B 选择不直观 + +**现状**：钱包密码是高敏感凭证，路径 B 自动创建会**明文写入 `~/.agent-wallet/runtime_secrets.json`**（文档已明示）。新用户照默认走 A/B 任一即开搞，没有「场景 → 路径」决策表，agent 容易选错路径。 + +**整改**：在快速开始步骤 3 加： + +```markdown +| 场景 | 推荐路径 | 原因 | +|------|---------|------| +| 生产环境（真实资金） | A — 手动创建 + secret manager | 路径 B 会明文落盘密码 | +| CI / 自动化（测试网） | A — 手动创建 + env injection | 同上 | +| 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 | +| 临时 demo 演示 | B + tmpfs 目录 | 任务结束即销毁 | +``` + +--- + +### P1-7 mcp-tronlink-signer 与 tronlink-signer SDK 的版本对应关系不明 + +**现状**：mcp-tronlink-signer 文档说「将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具」—— 暗示 `tronlink-signer` 是 monorepo 子包。但： + +1. 独立的 [tronlink-signer 文档页](https://docs.tronlink.org/zh/ai-support/tronlink-signer/) 存在 +2. CLI 文档说 `tronlink-signer 0.1.4` 是依赖（暗示是独立 npm 包） +3. mcp-tronlink-signer 文档没说「我用的 tronlink-signer 版本是 N，与独立 SDK 文档对齐到 commit X」 + +读者不知道这 3 处的 `tronlink-signer` 是不是同一份代码。 + +**整改**：mcp-tronlink-signer 头部加： + +```markdown +> **关系澄清**：本服务 = 把 [`tronlink-signer` SDK](tronlink-signer.md) v0.1.4 封装为 MCP server。SDK 与 wrapper 同 monorepo 维护，版本同步发布。直接用 SDK 见 [tronlink-signer](tronlink-signer.md)；用 MCP wrapper 见本页。 +``` + +--- + +### P1-8 「依赖项」表的「数据截至 2026-05」需要定期更新机制 + +**现状**：mcp-server-tronlink / CLI / Skills 都有「数据截至 2026-05」标注（好）。但没有更新机制 —— 6 月、7 月数据漂移后谁来改？ + +**整改**： + +1. 加 CI 任务：每月扫所有 `数据截至 YYYY-MM` 字样，超过 N 个月触发文档 issue 提醒 +2. 或改为「Last verified: 2026-05-21」+ commit hash 引用，让 reader 知道这是固定快照 + +--- + +### P1-9 Skills 反例表的「正确路由」工具名应做 CI parity 检查 + +**现状**：mcp-server-tronlink 已经有 CI parity 检查工具名；Skills 反例表里的 `tl_chain_send` / `tl_chain_stake` / `tl_chain_swap_v3` 等工具名引用 mcp-server-tronlink，但跨文档的工具名引用没纳入 parity 检查。如果 mcp-server 改名 `tl_chain_send` → `tl_send_trx`，Skills 反例表会变成死引用。 + +**整改**：parity 脚本扩到扫 Skills 文档对 `tl_*` 名字的引用，与 mcp-server 实际 list_tools 输出 diff。 + +--- + +## 六、锦上添花（P2） + +### MCP / CLI / 入口（8 条） + +| # | 文档 | 问题 | 建议 | +|:-:|------|------|------| +| P2-1 | MCP Server | Use Cases 6 条概括，缺端到端 agent 对话示例 | 补 1-2 个对话示例（如 SunSwap V3 swap 端到端） | +| P2-2 | MCP Server | Flow Recipes 子类型表与 src/flows/ 文件名不直观对应 | 表格加 `Source File` 列（如 `chainCheckBalanceFlow → src/flows/onchain.ts`） | +| P2-3 | MCP Core | 52 工具定义节按数字分组（1-13）阅读时跳跃 | 加目录跳转或合并为表 | +| P2-4 | MCP Signer | 内联 changelog 与 GitHub releases 双源 | 加同步策略说明（如「内联 SSOT，GitHub release 滞后 7 天」） | +| P2-5 | CLI | 退出码 5「网络错误」缺「如何确认上一笔未上链」指引 | 加「查 `tronscan.org/#/transaction/` 或 `tronlink balance --address` 对账」 | +| P2-6 | CLI | 常用代币合约表 3 个（同 P1-3） | 扩到 ≥8 个或引用 reference/networks SSOT | +| P2-7 | AI/LLMs 入口 | 「给智能体的说明」缺版本契约引用 | 加一条「版本契约见各工具页 §兼容性与迁移策略」 | +| P2-8 | 全站 | 引用 GitHub commit hash 时缺「截至日期」 | 引用 commit 时加 `(as of YYYY-MM-DD)` | + +### Skills（5 条，需协调产品组 owner） + +| # | 文档 | 问题 | 建议 | +|:-:|------|------|------| +| Skill-P2-1 | Skills | 缺独立 Troubleshooting 章节 | 错误处理散在「安全模型」表里。独立成节覆盖 5 类：① agent 未识别 skill ② TronGrid 限流 ③ CLI-only 命令被 MCP 调用 ④ install.sh 故障路径 ⑤ 多 host 命令名冲突 | +| Skill-P2-2 | Skills | 内置代币 symbol 表与 CLI 不一致（同 P1-3） | 合到 `reference/networks` SSOT，Skills / CLI 引用 | +| Skill-P2-3 | Skills | TronGrid API Key 凭证管理一笔带过 | 补 5 维（存储 / 最小权限 / 轮换 / 泄漏检测 / 撤销） | +| Skill-P2-4 | Skills | 推荐工作流是流程图式路径 | 补 1-2 个端到端 agent 对话示例（如「100 TRX 换 USDT 划算吗？」串 token-price → kline → resource-info → swap-quote） | +| Skill-P2-5 | Skills | `mcp_server.mjs ↔ tron_api.mjs` 等价性靠人盯 | 加 CI parity 检查（参考 mcp-server-tronlink 的 `check_doc_schema_parity.py`） | + +> **协调建议**：Skill-P2-2 / P2-5 与 P1-3 / P1-9 联动，建议两边一起整改一次性解决。 + +--- + +## 七、跨文档一致性 grep 清单 + +> 团队可逐项 grep 全站核对，建议加入 CI parity 检查。 + +| 检查项 | grep 命令 | 期望结果 | +|--------|-----------|----------| +| 错误码锚点存在 | `grep -rn "tronlink-mcp-core.md#错误码" docs/` | 引用方 3 处，目标节存在 | +| Flow Recipes 计数一致 | 对比文档表与 `src/flows/*.ts` 实际 export | 三方一致 | +| `chainTransferTrc20Flow` 不出现在文档（或代码补实现） | `grep -rn "chainTransferTrc20Flow\|chainSwapV3Flow" .` | 文档与代码同步 | +| 工具名 `tl_*` 引用统一 | 跨 mcp-server / mcp-signer / cli / skills grep `tl_chain_send` 等 | 全站命名一致 | +| 网络命名（mainnet / nile / shasta） | `grep -rn -iE "mainnet\|nile\|shasta\|niletest\|testnet" docs/` | 全站统一三档 | +| `@bankofai/agent-wallet` 版本 | `grep -rn "agent-wallet.*[0-9]\.[0-9]" docs/` | 文档版本与 npm 实际锁定一致 | +| 代币 symbol 表 SSOT | `grep -rn "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" docs/` | 仅在 reference/networks 出现一次 | +| GitHub 0 releases | `gh api repos/TronLink/{mcp-server-tronlink,...}/releases --jq 'length'` | 全部 > 0 | +| 个人 repo 引用 | `grep -rn "xueyuanying/docs" docs/` | 0（已迁到 org repo） | + +--- + +## 八、整改 checklist + +### P0（必改，6 项） + +- [ ] **P0-1** mcp-core 加 `## 错误码` 二级标题，与 3 处死锚点对齐 +- [ ] **P0-2** Flow Recipes：核对 23 实际 flow + 删除 / 补全 `chainTransferTrc20Flow` / `chainSwapV3Flow` + 文档加 `import-wallet` flow + 节标题计数更新 +- [ ] **P0-3** `@bankofai/agent-wallet` 改为精确版本 + 决策是否升级 2.4.0 + 文档明示 GitHub 404 状态 +- [ ] **P0-4** 5 个 TronLink npm 包回溯打 git tag + 创建 GitHub Release + npm publish CI 自动化 +- [ ] **P0-5** docs 源码 repo 从 `xueyuanying/docs` 迁移到 `TronLink/docs` 或 `TronLink/developer-docs` +- [ ] **P0-6** mcp-core 错误码表加 SSOT 声明 + 下游 3 文档改为引用而非重复 + +### P1（强建议，9 项） + +- [ ] **P1-1** mcp-tronlink-signer 头部加「该用哪个」三选一对照表 +- [ ] **P1-2** mcp-tronlink-signer 补 input schema 镜像 3 个 + CI parity +- [ ] **P1-3** 代币 symbol 表合到 reference/networks SSOT +- [ ] **P1-4** mcp-core 加「与 mcp-server-tronlink」决策矩阵 +- [ ] **P1-5** onchain.ts 补 chainTransferTrc20Flow / chainSwapV3Flow 实现（或文档删除） +- [ ] **P1-6** mcp-server 快速开始钱包路径 A/B 加「场景→路径」决策表 +- [ ] **P1-7** mcp-tronlink-signer 头部澄清与 SDK 版本对应关系 +- [ ] **P1-8** 「数据截至 YYYY-MM」改为「Last verified + commit」+ CI 提醒 +- [ ] **P1-9** Skills `tl_*` 引用纳入 CI parity 检查 + +### P2（锦上添花，8 项 + 5 项 Skills） + +#### MCP / CLI / 入口（8 项） + +- [ ] **P2-1** MCP Server Use Cases 补端到端对话示例 +- [ ] **P2-2** Flow Recipes 表加 Source File 列 +- [ ] **P2-3** MCP Core 52 工具定义合并为表 +- [ ] **P2-4** MCP Signer 内联 changelog 加同步策略 +- [ ] **P2-5** CLI 退出码 5 加「如何确认上一笔未上链」指引 +- [ ] **P2-6** CLI 常用代币合约表扩到 ≥8 个 +- [ ] **P2-7** AI/LLMs 入口加版本契约引用 +- [ ] **P2-8** GitHub commit hash 引用加「截至日期」 + +#### Skills（5 项，需协调产品组 owner） + +- [ ] **Skill-P2-1** 加独立 §Troubleshooting 章节 +- [ ] **Skill-P2-2** 代币 symbol 表合到 reference/networks SSOT +- [ ] **Skill-P2-3** 加 TronGrid API Key 凭证管理 5 维 +- [ ] **Skill-P2-4** 推荐工作流至少 2 个配端到端 agent 对话示例 +- [ ] **Skill-P2-5** 加 `mcp_server.mjs ↔ tron_api.mjs` CI parity workflow + +--- + +## 九、标准锚点对照表 + +| 整改项 | 标准章节 / 锚点 | +|--------|----------------| +| 错误结构（code / retryable / hint） | MCP §3 / CLI §3 / 公共基线 §3 + §4 | +| 副作用 5 级（Safe / Network Read / Local Write / Remote Write / Destructive） | 公共基线 §2 | +| 错误码 SSOT 跨文档共享 | 公共基线 §4 + 项目级覆盖度 §0「串联关系」9 分锚点 | +| Schema 完整度（input/output + version） | MCP §3 | +| 机器可读输出（`--json` + schema） | CLI §3 | +| 退出码契约 + retryable | CLI §3 + §4 | +| 副作用分级标记 | MCP §6 P0 + CLI §6 P0 + 公共基线 §2 | +| 版本契约 / changelog | MCP §3 + CLI §3 + 公共基线 §8 | +| 风险隔离（dry-run / preview） | CLI §4 + 公共基线 §9 | +| 自发现入口（`--help` / `list_tools` / llms.txt） | 公共基线 §6 | +| AI 入口索引（llms.txt） | 项目级覆盖度 §0 + §0.2 | +| 跨文档引用 SSOT 不割裂 | 项目级覆盖度 §0「Schema / Error / Examples 串联」15% 权重 | +| Skill 反例表 + 判断口诀 | Skill §4.1「发现选择」10 分锚点 | +| Skill ↔ MCP 子集关系明示 | Skill §4.1 客户端兼容 + 版本契约 | + +--- + +## 十、整改前后预期对比 + +| 文档 | 当前 | 整改 P0 后 | 整改 P0+P1 后 | +|------|:---:|:---:|:---:| +| MCP Server | 87.0 | 94 | 98 | +| MCP Core | 77.8 | 90 | 95 | +| MCP Signer | 88.0 | 92 | 96 | +| CLI | 94.0 | 97 | 99 | +| Skills | 98.5 | 98.5 | 100 | +| AI/LLMs 入口 | 100.0 | 100 | 100 | +| **平均** | **90.9** | **95.3** | **98.0** | + +--- + +## 十一、与上一轮评审差距说明 + +上一轮（2026-05-22 首轮 review）我给出的评分是 6 文档平均 **97.8**（MCP Server 100 / CLI 100 / MCP Core 95.4 / MCP Signer 93 / Skills 98.5 / AI 入口 100）。本次重审下调到 **90.9**，差距 −6.9 分。**差距不是因为文档质量退步，而是评分深度提升**： + +| 重审挖出的问题 | 上一轮是否漏 | 本轮发现路径 | +|----------------|:---:|------| +| `tronlink-mcp-core.md#错误码` 死锚点（3 处） | ❌ 漏 | grep 跨文档锚点 + 核对 mcp-core 章节 | +| Flow Recipes 文档 32 / 加总 24 / 代码 23 三方矛盾 | ⚠️ 仅指出 32 vs 24 | gh api 取 `src/flows/*.ts` 实际 export 计数 | +| `chainTransferTrc20Flow` / `chainSwapV3Flow` 文档列了但代码不存在 | ❌ 漏 | grep onchain.ts 实际 flow 名 | +| `bankofai/agent-wallet` GitHub 404 + 文档版本落后 | ❌ 漏 | gh api repo + curl npm registry 双向核对 | +| 5 个 repo 0 releases / 0 tags | ❌ 漏 | gh api releases / tags 系统性扫描 | +| docs.tronlink.org 源码托管在 `xueyuanying/docs` 个人 repo | ❌ 漏 | gh api 个人 repo + pushed_at 时间戳对齐 | +| 错误码 SSOT 身份未明示 | ⚠️ 仅 P1 | 重审升级，跨文档引用关系 | + +**这一轮按更扎实的深度做**：grep 死链 + 核对源码 + npm registry 实测 + GitHub repo 活性 + 跨文档术语一致性。 + +**Skills 是 6 篇文档中唯一一份「重审无新发现」的样板** — 33/25/8 数字与代码完美对齐，`mcp_server.mjs ↔ tron_api.mjs` 同源 SSOT。 + +--- + +**评审完成。** 如对评分逻辑、整改优先级、参考实现有疑问可直接联系 PM。整改完成后可申请复评。 + +附：参考实现样板（按本标准达 A+ 级）： + +- [`ai-support/mcp-server-tronlink`](https://docs.tronlink.org/zh/ai-support/mcp-server-tronlink/) 自身（整改 P0/P1 后） +- [`reference/error-code-map`](https://docs.tronlink.org/zh/reference/error-code-map/) — 五通道错误码对照表（含 retryable 列） +- [`zh/llms.txt`](https://docs.tronlink.org/zh/llms.txt) — `llms.txt` 实现样板 +- [`scripts/check_doc_schema_parity.py`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) — CI parity 实现样板（建议迁移到 TronLink org，见 P0-5） From f455049fc02d3f3dcb07161a29cfb1929dcbd6bc Mon Sep 17 00:00:00 2001 From: Tron Date: Fri, 29 May 2026 16:51:22 +0800 Subject: [PATCH 05/10] docs: P0-1 make ZH error-code SSOT anchor linkable (#error-codes) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The default MkDocs slugify strips CJK, so the ZH heading "### 错误码" got an unstable numeric id and the 3 cross-doc SSOT links (tronlink-mcp-core.md#错误码 from mcp-server / cli / signer) didn't resolve. Make the heading bilingual ("错误码 (Error Codes)") so it slugifies to the stable #error-codes (matching the EN side) and point the ZH links there. Build-verified: those links now resolve, no new broken anchors. llms.txt / llms-full.* regenerated. Co-Authored-By: Claude Opus 4.8 --- docs/ai-support/mcp-server-tronlink.zh.md | 4 ++-- docs/ai-support/mcp-tronlink-signer.zh.md | 2 +- docs/ai-support/tronlink-cli.zh.md | 2 +- docs/ai-support/tronlink-mcp-core.zh.md | 2 +- docs/llms-full.en.txt | 4 ++-- docs/llms-full.txt | 4 ++-- docs/llms-full.zh.txt | 16 ++++++++-------- docs/llms.txt | 2 +- docs/llms.zh.txt | 2 +- 9 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/ai-support/mcp-server-tronlink.zh.md b/docs/ai-support/mcp-server-tronlink.zh.md index 79f74b3..03ef2f9 100644 --- a/docs/ai-support/mcp-server-tronlink.zh.md +++ b/docs/ai-support/mcp-server-tronlink.zh.md @@ -423,7 +423,7 @@ mcp-server-tronlink/ ## 工具契约与副作用 -**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。 +**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。 **逐工具输入 schema 可在运行时发现。** 每个工具的参数都由 core 用 Zod 校验,并通过 MCP `list_tools` 方法以 JSON `inputSchema` 形式暴露,因此客户端无需阅读本页即可枚举参数名、类型和必填项。下方表格按能力归纳工具;`list_tools` 才是权威的机器可读来源。 @@ -755,7 +755,7 @@ export TL_TRONGRID_URL="https://nile.trongrid.io" - **语义化版本。** 1.0 之前：**minor** 升级（0.x → 0.y）允许破坏性变更；**patch** 升级（0.1.x → 0.1.y）不变更工具名、输入 schema、`error.code` 值或 `meta.schemaVersion` 语义。1.0 之后：标准 semver，仅 major 允许破坏。 - **稳定契约**（patch 不会动）： - 工具名（`tl_chain_send`、`tl_chain_swap_v3`、`tl_multisig_*`、`tl_gasfree_*`、`tl_evaluate` 等） - - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码)） + - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes)） - `error.retryable` 语义 - `meta.schemaVersion` 的 major 分量 - 必需环境变量名（`TL_TRONGRID_URL`、`TL_MULTISIG_SECRET_KEY`、`AGENT_WALLET_PASSWORD` 等） diff --git a/docs/ai-support/mcp-tronlink-signer.zh.md b/docs/ai-support/mcp-tronlink-signer.zh.md index e6e5ddd..601870a 100644 --- a/docs/ai-support/mcp-tronlink-signer.zh.md +++ b/docs/ai-support/mcp-tronlink-signer.zh.md @@ -192,7 +192,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si ## 错误 -server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码) 为准；signer 特有错误如下： +server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes) 为准；signer 特有错误如下： | 条件 | Retryable | 何时发生 | | --- | :---: | --- | diff --git a/docs/ai-support/tronlink-cli.zh.md b/docs/ai-support/tronlink-cli.zh.md index b0e33fc..fd177e4 100644 --- a/docs/ai-support/tronlink-cli.zh.md +++ b/docs/ai-support/tronlink-cli.zh.md @@ -474,7 +474,7 @@ CLI 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级允 - 子命令名与其必填位置参数 / flag。 - **Exit code** —— Exit Codes 表中的每一条都属于公开面。minor 允许为此前的通用失败新增 code；重新分配已有数字属于 major。 - **`--json` 输出 key** —— 顶层 key（`ok`、`error.code`、`error.retryable`、`txid` 等）以及 `error` 下的结构。minor 允许新增可选字段；改名 / 删除属于 major。 - - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 共享 SSOT）。 + - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 共享 SSOT）。 - **不稳定契约**（随时可能变化）： - 未带 `--json` 的人类可读 stdout 文本。 - 提示、横幅、颜色码的具体文本。 diff --git a/docs/ai-support/tronlink-mcp-core.zh.md b/docs/ai-support/tronlink-mcp-core.zh.md index ff21d6f..017167f 100644 --- a/docs/ai-support/tronlink-mcp-core.zh.md +++ b/docs/ai-support/tronlink-mcp-core.zh.md @@ -397,7 +397,7 @@ interface GasFreeCapability { } ``` -### 错误码 +### 错误码 (Error Codes) 这是本框架所有工具返回错误码的**唯一数据源**（SSOT）。下游 server（`mcp-server-tronlink`、`mcp-tronlink-signer`）继承这些错误码并可扩展自有错误码。`retryable` 反映框架层面的安全性，agent 仍**必须**叠加调用工具的副作用分级——无论 `retryable` 为何，**结果未确认的 Remote Write 绝不能自动重试**。 diff --git a/docs/llms-full.en.txt b/docs/llms-full.en.txt index 82cc840..71b5259 100644 --- a/docs/llms-full.en.txt +++ b/docs/llms-full.en.txt @@ -2,8 +2,8 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T07:44:07Z -- Commit: 0cf4be4b82f6 +- Generated: 2026-05-29T08:48:03Z +- Commit: 1aed03bbd2cc - Language: en - Pages: 23 - Token estimate: ~60,361 (chars / 4) diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 82cc840..71b5259 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -2,8 +2,8 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T07:44:07Z -- Commit: 0cf4be4b82f6 +- Generated: 2026-05-29T08:48:03Z +- Commit: 1aed03bbd2cc - Language: en - Pages: 23 - Token estimate: ~60,361 (chars / 4) diff --git a/docs/llms-full.zh.txt b/docs/llms-full.zh.txt index 6a9014f..bde76de 100644 --- a/docs/llms-full.zh.txt +++ b/docs/llms-full.zh.txt @@ -2,11 +2,11 @@ > 中文文档全文拼接，适合 LLM 一次性 ingest。由 scripts/gen_llms_full.py 生成。索引见 ../llms.txt 的 Localized 段。 -- Generated: 2026-05-29T07:44:07Z -- Commit: 0cf4be4b82f6 +- Generated: 2026-05-29T08:48:03Z +- Commit: 1aed03bbd2cc - Language: zh - Pages: 23 -- Token estimate: ~41,552 (chars / 4) +- Token estimate: ~41,563 (chars / 4) --- @@ -2422,7 +2422,7 @@ mcp-server-tronlink/ ## 工具契约与副作用 -**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。 +**输入/输出 schema 与错误契约。** 每个工具的输入/输出 schema 及结构化错误信封由底层框架定义——见 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 的 SSOT 错误码表（`code` / `retryable` / `hint` / 典型触发）。每个响应均带 `meta.schemaVersion`，major 版本内字段含义稳定。Agent 应基于 `error.code` 与 `error.retryable` 分支，**不要**解析人类可读的 `message`。 **逐工具输入 schema 可在运行时发现。** 每个工具的参数都由 core 用 Zod 校验,并通过 MCP `list_tools` 方法以 JSON `inputSchema` 形式暴露,因此客户端无需阅读本页即可枚举参数名、类型和必填项。下方表格按能力归纳工具;`list_tools` 才是权威的机器可读来源。 @@ -2754,7 +2754,7 @@ export TL_TRONGRID_URL="https://nile.trongrid.io" - **语义化版本。** 1.0 之前：**minor** 升级（0.x → 0.y）允许破坏性变更；**patch** 升级（0.1.x → 0.1.y）不变更工具名、输入 schema、`error.code` 值或 `meta.schemaVersion` 语义。1.0 之后：标准 semver，仅 major 允许破坏。 - **稳定契约**（patch 不会动）： - 工具名（`tl_chain_send`、`tl_chain_swap_v3`、`tl_multisig_*`、`tl_gasfree_*`、`tl_evaluate` 等） - - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码)） + - `error.code` 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes)） - `error.retryable` 语义 - `meta.schemaVersion` 的 major 分量 - 必需环境变量名（`TL_TRONGRID_URL`、`TL_MULTISIG_SECRET_KEY`、`AGENT_WALLET_PASSWORD` 等） @@ -3168,7 +3168,7 @@ interface GasFreeCapability { } ``` -### 错误码 +### 错误码 (Error Codes) 这是本框架所有工具返回错误码的**唯一数据源**（SSOT）。下游 server（`mcp-server-tronlink`、`mcp-tronlink-signer`）继承这些错误码并可扩展自有错误码。`retryable` 反映框架层面的安全性，agent 仍**必须**叠加调用工具的副作用分级——无论 `retryable` 为何，**结果未确认的 Remote Write 绝不能自动重试**。 @@ -4213,7 +4213,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si ## 错误 -server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码) 为准；signer 特有错误如下： +server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes) 为准；signer 特有错误如下： | 条件 | Retryable | 何时发生 | | --- | :---: | --- | @@ -5102,7 +5102,7 @@ CLI 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级允 - 子命令名与其必填位置参数 / flag。 - **Exit code** —— Exit Codes 表中的每一条都属于公开面。minor 允许为此前的通用失败新增 code；重新分配已有数字属于 major。 - **`--json` 输出 key** —— 顶层 key（`ok`、`error.code`、`error.retryable`、`txid` 等）以及 `error` 下的结构。minor 允许新增可选字段；改名 / 删除属于 major。 - - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 共享 SSOT）。 + - `error.code` 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#error-codes) 共享 SSOT）。 - **不稳定契约**（随时可能变化）： - 未带 `--json` 的人类可读 stdout 文本。 - 提示、横幅、颜色码的具体文本。 diff --git a/docs/llms.txt b/docs/llms.txt index 8dbdaed..b8e8036 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,7 +2,7 @@ > TronLink is a decentralized wallet for the TRON ecosystem, available as a browser extension and a mobile app. This documentation covers integrating DApps with TronLink across the browser extension, the mobile app (via DeepLink), and AI/agent tooling (MCP servers, CLI, signer SDK). -> Updated: 2026-05-29T07:44:07Z · Commit: 0cf4be4b82f6 +> Updated: 2026-05-29T08:48:03Z · Commit: 1aed03bbd2cc How integration works: TronLink injects a `window.tron` provider into every page, exposing a `tronWeb` instance, a `request` method, and `on` / `removeListener` for events. A DApp detects the wallet via TIP-6963, requests authorization via `eth_requestAccounts` (TIP-1102), then builds, signs, and broadcasts transactions through `tronWeb`. Account/network changes arrive as passive `accountsChanged` / `chainChanged` events. diff --git a/docs/llms.zh.txt b/docs/llms.zh.txt index 2d3c64e..3dfc755 100644 --- a/docs/llms.zh.txt +++ b/docs/llms.zh.txt @@ -2,7 +2,7 @@ > TronLink 是 TRON 生态的去中心化钱包，提供浏览器扩展和移动 App。本文档涵盖 DApp 通过浏览器扩展、移动端（DeepLink）以及 AI/智能体工具链（MCP 服务、CLI、签名 SDK）与 TronLink 集成。 -> Updated: 2026-05-29T07:44:07Z · Commit: 0cf4be4b82f6 +> Updated: 2026-05-29T08:48:03Z · Commit: 1aed03bbd2cc 集成原理：TronLink 向页面注入 `window.tron` provider，暴露 `tronWeb` 实例、`request` 方法以及 `on` / `removeListener` 事件订阅。DApp 通过 TIP-6963 检测钱包，用 `eth_requestAccounts`（TIP-1102）请求授权，再经 `tronWeb` 构建、签名并广播交易。账户/网络变化以 `accountsChanged` / `chainChanged` 被动事件送达。 From 16a8d8d4f1051346c041b2ad4a67f9c64aa89e2e Mon Sep 17 00:00:00 2001 From: Tron Date: Fri, 29 May 2026 17:09:58 +0800 Subject: [PATCH 06/10] docs: remove internal review report accidentally committed Internal developer-doc review report; should not live in the published docs repo. (Re-applies the removal that an erroneous force-push reverted.) Co-Authored-By: Claude Opus 4.8 --- ...04\345\256\241\346\212\245\345\221\212.md" | 634 ------------------ 1 file changed, 634 deletions(-) delete mode 100644 "\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" diff --git "a/\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" "b/\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" deleted file mode 100644 index 85f4ca4..0000000 --- "a/\347\273\231Leon-TronLink\345\274\200\345\217\221\350\200\205\346\226\207\346\241\243\350\257\204\345\256\241\346\212\245\345\221\212.md" +++ /dev/null @@ -1,634 +0,0 @@ -# TronLink 开发者文档评审报告（MCP + CLI + Skill + AI 入口） - -**评审日期**：2026-05-27 -**评审依据**： -- [`MCP 文档标准 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) -- [`CLI 文档标准 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) -- [`Skill 产品文档标准 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) -- [`公共安全与错误码基线 V1.0`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) -- [`项目级覆盖度评分标准 V1.7`](https://drive.google.com/drive/folders/1FhYGmYyKuRBcpSVhm82VuK2uceQ4w0uv) - -**评审对象**：[docs.tronlink.org/zh/](https://docs.tronlink.org/zh/)「AI 支持」章节 6 篇文档 -**文档基线**：Updated 2026-05-21T14:08:15Z · Commit `e724781c635f`（docs 源码托管在 [`xueyuanying/docs`](https://github.com/xueyuanying/docs)） - -| # | 文档 | 适用标准 | -|:-:|------|---------| -| 1 | [MCP Server TronLink](https://docs.tronlink.org/zh/ai-support/mcp-server-tronlink/) | MCP V1.0 | -| 2 | [TronLink MCP Core](https://docs.tronlink.org/zh/ai-support/tronlink-mcp-core/) | MCP V1.0 | -| 3 | [MCP TronLink Signer](https://docs.tronlink.org/zh/ai-support/mcp-tronlink-signer/) | MCP V1.0 | -| 4 | [TronLink CLI](https://docs.tronlink.org/zh/ai-support/tronlink-cli/) | CLI V1.0 | -| 5 | [TronLink Skills](https://docs.tronlink.org/zh/ai-support/tronlink-skills/) | Skill V1.0 | -| 6 | [AI / LLMs 入口页](https://docs.tronlink.org/zh/ai-support/ai-llms/) | 覆盖度 V1.7 + 跨标准 | - -> **维护方说明**：本报告覆盖 6 篇文档。1–4 + 6 由 Leon 团队维护；**Skills（#5）由产品组维护**——请协助转发给对应 owner，或内部对齐后统一回应。Skills 部分的 P2 改进项与 Leon 的 P1-3 / P1-9 联动，建议两边协调整改。 - ---- - -## 一、总评 - -| # | 文档 | 类型判定 | 内容 | Agent | 安全 | 加权 | 整改后预期 | 等级 | -|:-:|------|---------|:---:|:---:|:---:|:---:|:---:|:---:| -| 1 | MCP Server TronLink | High-risk / Mutative（30/40/30） | 8 | 9 | 9 | **87.0** | 98 | A | -| 2 | TronLink MCP Core | General / Agent-first（25/60/15） | 7 | 8 | 8 | **77.8** | 95 | B+ | -| 3 | MCP TronLink Signer | High-risk / Mutative（30/40/30） | 8 | 8 | 10 | **88.0** | 96 | A | -| 4 | TronLink CLI | High-risk CLI（30/40/30） | 9 | 10 | 9 | **94.0** | 99 | A+ | -| 5 | TronLink Skills | Read-only Data Skills（35/50/15） | 10 | 10 | 9 | **98.5** | 100 | A+ | -| 6 | AI / LLMs 入口页 | 覆盖度 + 跨标准入口 | 10 | 10 | 10 | **100.0** | 100 | A+ | -| **平均** | — | — | — | — | — | **90.9** | **98.0** | **A** | - -**整体结论**： - -- **TRON 生态当前 4 类文档（API / MCP / CLI / Skill）中标杆级别**——6 篇全部 A 级以上，3 套标准 P0 gate（MCP 6 + CLI 6 + Skill 6 = 18 项）全部通过 -- **差距来源不在内容深度，而在三类硬伤**：跨文档死链（如 `tronlink-mcp-core.md#错误码` 锚点 3 处死链）、文档与代码漂移（Flow Recipes 文档 32 / 实际 23 / 含 2 个不存在 flow 名）、发布工程缺失（5 个 npm 包全部 0 GitHub releases） -- **三类硬伤都有清晰整改路径**——下文按优先级展开，整改后可达 98 分（A） - -**亮点**（保留上一轮认知，下文 §二 详述）：CI schema parity、错误码 SSOT 设计意图、Content-Signal robots、退出码 6 档 retryable、多签凭证 5 维管理、`tl_evaluate` 三 host 禁用示例、依赖钉版 + 数据截至时间戳、Skills 反例表与判断口诀——均超 V1.0 标准明文要求。 - ---- - -## 二、20 条亮点汇总（建议回流标准 V1.1） - -按标准维度分类，提议作为 V1.1 评分锚点 / P0 加项的素材，按价值排序。 - -### 2.1 Agent 可用性维度（10 条） - -| # | 亮点 | 出处 | 标准对应 | -|:-:|------|------|---------| -| 1 | **「❌ 不要走这里（反例）」专节 + 判断口诀** | Skills | Skill §4.1「发现选择」10 分锚点「有路由表和负向触发」的极致实现 | -| 2 | **Skill ↔ MCP 工具映射表 + 子集关系明示**（25/33 + minor 内只增不减） | Skills | Skill §4.1 客户端兼容 + 版本契约创新 | -| 3 | **用户提问 → Skill → 工具三层路由表**（21 行常见提问对照） | Skills | Skill §4.1 发现选择 10 分 | -| 4 | **每个 skill 内置「何时不要用」写到命令粒度** | Skills | Skill §4.1 负向触发 10 分 | -| 5 | **CI 强制 schema parity 检查**（`scripts/check_doc_schema_parity.py`，文档侧 schema ↔ 上游 schemas.ts 自动 diff） | MCP Server | MCP §6 P0「缺 inputSchema」加分实践 | -| 6 | **错误码 SSOT 跨文档共享**：CLI / MCP Server / MCP Signer 共用 `tronlink-mcp-core#错误码`，含 `code / retryable / hint / 典型触发` | MCP Core | MCP §3 错误契约 10 分 | -| 7 | **HTTP / EVM / DeepLink / MCP / CLI 五通道错误码对照表**（[`reference/error-code-map`](https://docs.tronlink.org/zh/reference/error-code-map/)）以业务含义为主轴横向 join | 全站 | 跨标准创新 | -| 8 | **input schema 文档侧镜像**（MCP Server 镜像 `tl_chain_send` / `tl_chain_swap_v3` / `tl_chain_stake` / `tl_multisig_submit_tx` / `tl_gasfree_send` / `tl_chain_get_account` / `tl_evaluate` 7 个），明示 list_tools 是权威源 | MCP Server | MCP §3 Schema 完整度 10 分 | -| 9 | **副作用 4 分级**（Network Read / Local Write / Remote Write / Destructive）+ 逐工具表标注 | 全站 | MCP §4 / CLI §4 副作用 10 分 | -| 10 | **CLI `--json` 是自动化契约的明文承诺**（minor 加不减、改名属 major） | CLI | CLI §3 机器输出 10 分 | - -### 2.2 安全与权限维度（6 条） - -| # | 亮点 | 出处 | 标准对应 | -|:-:|------|------|---------| -| 11 | **`tl_evaluate` 三种 host 禁用配置示例**（Claude Code / Claude Desktop / 通用 MCP 客户端） | MCP Server | MCP §6 P0「远程 MCP 无 SSRF」加分实践 | -| 12 | **多签凭证 5 维管理**（按环境隔离 / 存储 / 轮换 / 撤销 / 最小权限） | MCP Server | MCP §5.1 权限授权 10 分 | -| 13 | **钱包密钥两路径对比表**（手动 vs 自动创建），含「待解决（代码侧）」字段明示文档级方案与代码 PR 关系 | MCP Server | MCP §5.1 安全规则 10 分 | -| 14 | **兑换安全专章**（minOut / 滑点上限 / 钉死 router / 不可自动重试） | MCP Server | MCP §5.1 风险防护 10 分 | -| 15 | **7 大安全边界逐条给 agent 与运维方义务**（Prompt 注入 / SSRF / token passthrough / 浏览器 JS / HITL 绕过 / confused deputy / 传输） | MCP Server | MCP §5.1 全维 10 分 | -| 16 | **robots.txt 用 Content-Signal 协议区分 inference vs training**（`search=yes, ai-train=no` + 显式 Disallow GPTBot / ClaudeBot / CCBot）；把 `llms.txt` / `llms-full.txt` 标为 inference 入口 | 全站 | 公共基线 §2 原则 11 机器可抓取的前沿做法 | - -### 2.3 人读维度（4 条） - -| # | 亮点 | 出处 | 标准对应 | -|:-:|------|------|---------| -| 17 | **双层 llms.txt**（精选索引 + 全文聚合，中英双版，源带 commit hash + UTC 时间戳） | 入口页 | 项目级覆盖度 §0 + 公共基线 §6 自发现入口 | -| 18 | **CLI 退出码 6 档 + 每档 retryable 列**（`0/1/2/3/4/5` + 「已提交但结果未知」不得自动重试） | CLI | CLI §3 错误契约 10 分 | -| 19 | **依赖钉版 + 数据带「截至 2026-05」标注**（`tronweb 6.2.2` / `tronlink-signer 0.1.4` / `mcp-server-tronlink@0.1.1` 全部钉版） | 全站 | MCP §5 / CLI §3 版本与兼容性 10 分 | -| 20 | **零依赖 / 零 npm install + `install.sh` / `uninstall.sh` 全生命周期脚本** | Skills | Skill §3.1 安装接入 10 分锚点 | - -> **回流建议**：前 4 条（Agent 可用性）建议升级为 V1.1 的「10 分新锚点」；中间 5 条（安全）建议补入 P0 检查项；后 4 条（人读 + 版本）作 V1.1 加分项写入正文。 - ---- - -## 三、单文档详评 - -### 3.1 MCP Server TronLink — A，87/100 - -**类型判定**：High-risk / Mutative MCP（含 `tl_chain_send`、`tl_chain_swap_v3`、`tl_evaluate` 等 Remote Write 与 Destructive 原语） - -| 维度 | 分 | 主要依据 | -|------|:---:|---| -| 人读 (30%) | **8** | 概述 / 双模架构图（mermaid）/ 双模运行机制 / 6 大核心组件 / 4 集成方式 / 项目结构 完整；扣 2 分：Flow Recipes 三方计数矛盾 + 含 2 个不存在 flow 名（详见 P0-2） | -| Agent 可用性 (40%) | **9** | 工具发现走 list_tools 权威源；input schema 精选镜像 + CI parity；副作用 4 分级；错误契约用 `error.code`；扣 1 分：`tronlink-mcp-core.md#错误码` 锚点死链（详见 P0-1） | -| 安全与权限 (30%) | **9** | 7 大安全边界、兑换安全专章、多签凭证 5 维、钱包路径 A/B 对比、`tl_evaluate` 三 host 禁用示例；扣 1 分：`@bankofai/agent-wallet` 版本管理问题（GitHub 404 + 文档版本落后 npm，详见 P0-3） | - -### 3.2 TronLink MCP Core — B+，77.8/100 - -**类型判定**：Agent-first MCP（框架库，给上层 server 复用） - -| 维度 | 分 | 主要依据 | -|------|:---:|---| -| 人读 (25%) | **7** | 完整覆盖架构 / ISessionManager / 9 个能力接口 / 52 工具定义 / Knowledge Store / Flow Recipe 系统 / 元素定位 3 方式；扣 3 分：错误码节标题缺失（应在「标准化响应格式」节下加 `## 错误码` 二级标题响应下游 3 文档引用，详见 P0-1）+ 缺「何时用 mcp-core / 何时用 mcp-server-tronlink」决策矩阵（P1-4） | -| Agent 可用性 (60%) | **8** | 错误码 SSOT 实质在本文档；标准化响应格式；52 工具完整定义；Flow Recipe 含依赖解析；扣 2 分：SSOT 身份未明示 + 下游 3 文档死链（P0-6） | -| 安全与权限 (15%) | **8** | 由上层 server 实现具体边界，本文档只定义抽象能力；扣 2 分：缺「具体安全边界由实现 server 提供，参考 mcp-server-tronlink §安全模型」交叉引用 | - -### 3.3 MCP TronLink Signer — A，88/100 - -**类型判定**：High-risk / Mutative MCP（签名 + 广播） - -| 维度 | 分 | 主要依据 | -|------|:---:|---| -| 人读 (30%) | **8** | 完整覆盖配置（Claude Code / Claude Desktop / Cursor / 源码）/ MCP 工具 / 资源 / 提示词 / 工作原理 / 端到端示例 / 取消 / 交易确认 / 错误 / 安全边界 / 环境变量 / 版本 + 内联 changelog；扣 2 分：缺「该用哪个」三选一对照表（P1-1）+ 与 SDK 版本对应关系不明（P1-7） | -| Agent 可用性 (40%) | **8** | 工具表含 7 列 + 副作用 + 可自动重试列；HITL 明确不可绕过；扣 2 分：input schema 没像 mcp-server-tronlink 那样镜像精选示例，全靠 list_tools（P1-2） | -| 安全与权限 (30%) | **10** | HITL 必经浏览器审批；私钥不离开 TronLink；明示哪些是 Remote Write 且不可自动重试；签名类只 Local Write 可重试 | - -### 3.4 TronLink CLI — A+，94/100 - -**类型判定**：High-risk CLI（HITL 写操作 + 远程广播） - -| 维度 | 分 | 主要依据 | -|------|:---:|---| -| 人读 (30%) | **9** | Overview / 环境要求（依赖钉版 + 数据截至时间）/ 全局选项 / 命令分类 / 交易签名 / 预览 / 广播双路径 / 输出格式 / 退出码 / 错误 / 安全 / 工作原理 / **AI 智能体使用专章** / 版本与兼容性；扣 1 分：常用代币合约表只列 3 个（与 Skills 8 个不一致，P1-3） | -| Agent 可用性 (40%) | **10** | `--json` 机器输出契约；`error.code` 跨文档 SSOT 引用；退出码 6 档 + retryable；ABI v2 完整支持（tuple / 嵌套数组 / tuple 数组）；pre-flight 模拟在签名前；AI 智能体专章含端到端转账流程示例 | -| 安全与权限 (30%) | **9** | 副作用分级表；HITL 必经浏览器；写操作不自动重试；私钥不离开 TronLink；输入校验 14 条；本地广播与签名器广播的双广播去重机制说明；扣 1 分：退出码 5「网络错误」缺「如何确认上一笔未上链」指引（P2-5） | - -### 3.5 TronLink Skills — A+，98.5/100 - -**类型判定**：Read-only Data Skills（35/50/15）+ Skills/MCP/CLI Hybrid 特征 - -| 维度 | 分 | 主要依据 | -|------|:---:|---| -| 人读 (35%) | **10** | Overview / Why / 架构图 / 6 大 skill 详解 / 4 集成方式 / 配置 / TRON 资源模型 / 快速开始 / 版本与许可证 全覆盖 | -| Agent 可用性 (50%) | **10** | Skill ↔ MCP 工具映射表 + 用户提问路由表 + 反例表 + 子集关系明示（25/33）+ 5 个客户端配置 + 兼容性与迁移策略 | -| 安全与权限 (15%) | **9** | 纯只读 + 副作用统一 Network Read + 每个 skill「何时不要用」+ 反例表；扣 1 分：TronGrid API Key 的最小权限 / 轮换 / 泄漏处置无明文（Skills P2-3） | - -**§7 P0 gate 6/6 全过；§6 推荐结构 10.5/11 覆盖**（Troubleshooting 散在「安全模型」表，未独立成节，Skills P2-1） - -**数据 vs 代码核对（全部对齐）** — Skills 是 6 篇文档中唯一一份「重审无新发现」的样板： - -| 文档声明 | 实测来源 | 实测值 | 状态 | -|---------|---------|:---:|:---:| -| 33 个 CLI 命令 | `scripts/tron_api.mjs` 实际 `"":` 定义数 | **33** | ✅ | -| 25 个 MCP 工具 | `scripts/mcp_server.mjs` 实际 `name: "tron_*"` 数 | **25** | ✅ | -| 8 个 CLI-only | 33 − 25 = 8 + 文档明确列出 | **8** | ✅ | -| 6 大技能 | `skills/` 目录子文件夹数 | **6** | ✅ | -| 子集关系 MCP ⊂ CLI | 25 个 `tron_*` 全部对应到 CLI 命令 | **完美对应** | ✅ | - -### 3.6 AI / LLMs 入口页 — A+，100/100 - -不在 MCP / CLI / Skill 标准评分清单（属导流入口页），整体质量极高： - -- ✅ 4 个端点表（中英 × 索引 / 全文） -- ✅ 「该用哪个文件」场景表 -- ✅ Cursor / Claude / 其他工具的添加指引 -- ✅ 覆盖范围（指向 6 个 AI 工具链文档） -- ✅ 给智能体的 4 条明文说明 -- ✅ allowed-use vs robots.txt 与 Content-Signal 的关系澄清 - -仅 1 条 P2：缺版本契约引用（P2-7） - ---- - -## 四、必改清单（P0：相关标准 gate 失败） - -### P0-1 ⚠️ 死链：`tronlink-mcp-core.md#错误码` 锚点在目标文档不存在 - -**标准依据**：MCP §6 P0「缺错误结构 → Agent 无法分支处理」+ CLI §6 P0「缺 error code / exit code」+ 公共基线「全站无事实自相矛盾」 - -**现状**：3 个文档引用同一个死锚点： - -| 引用方 | 行号 | 引用形式 | -|--------|------|----------| -| mcp-server-tronlink | §「工具契约与副作用」L422 | `[TronLink MCP Core](tronlink-mcp-core.md#错误码) 的 SSOT 错误码表` | -| mcp-server-tronlink | §「兼容性与迁移策略」L729 | `error.code 枚举（SSOT：[TronLink MCP Core 错误码](tronlink-mcp-core.md#错误码)）` | -| tronlink-cli | §「兼容性与迁移策略」L475 | `error.code 枚举（与 [TronLink MCP Core](tronlink-mcp-core.md#错误码) 共享 SSOT）` | - -**但 tronlink-mcp-core 文档没有 `## 错误码` 章节**。它的章节是：概述 / 架构设计 / 与 mcp-server-tronlink 的关系 / ISessionManager 接口 / 9 个能力接口 / 52 工具定义 / **标准化响应格式** / Knowledge Store / Flow Recipe 系统 / 元素定位 / 安装与使用 / 项目结构 / 依赖项 / 构建与开发 / 关键设计模式 / 版本与许可证。错误码表实际位于「标准化响应格式」节内的子段，渲染后**没有 `#错误码` 锚点**。 - -**Agent / 开发者影响**：跟链接 → 落到文档顶部或抛 404 锚点，**拿不到错误码 SSOT 表**。这违反了文档明示的「Agent 应基于 `error.code` 与 `error.retryable` 分支」。 - -**整改方案**（任选其一）： - -- **方案 A**（推荐）：在 tronlink-mcp-core 文档「标准化响应格式」节下显式增加 `## 错误码` 二级标题，把现有错误码表移到该节下。锚点变为 `tronlink-mcp-core.md#错误码`，与 3 处引用对齐 -- **方案 B**：把 3 处引用统一改为存在的锚点（如 `tronlink-mcp-core.md#标准化响应格式`），但需要保证错误码表在该节下且足够独立 - -**附加建议**：错误码表头加一行明示 SSOT 身份： - -``` -> SSOT for: mcp-server-tronlink, mcp-tronlink-signer, tronlink-cli — 任何下游文档变更需先在此更新。 -``` - -**验收**：3 处跨文档引用全部跳转到包含错误码表的实际位置；mkdocs build 不报 broken anchor warning。 - ---- - -### P0-2 ⚠️ Flow Recipes 三方数据矛盾，并含 2 个不存在的 flow 名 - -**标准依据**：MCP §3 Schema 完整度 + 公共基线「全站无事实自相矛盾」+ §2 原则 3 稳定字段契约 - -**现状**：mcp-server-tronlink §「Flow Recipes（32 个内置流程）」三处计数互相矛盾： - -| 来源 | 计数 | -|------|------| -| 节标题 | **32 个** | -| 子类型表加总（Playwright 4 + 链上 11 + 多签 6 + GasFree 3） | **24 个** | -| `src/flows/*.ts` 实际 `export const ...Flow` 数 | **23 个**（GasFree 3 + import-wallet 1 + multisig 6 + onchain **9** + switch-network 2 + transfer-trx 2） | - -**文档列了但代码不存在的 flow**（即死链 flow 名）： - -| 文档列出 | 代码核对 | -|---------|---------| -| `chainTransferTrc20Flow` | ❌ 不存在于 `src/flows/onchain.ts` | -| `chainSwapV3Flow` | ❌ 不存在于 `src/flows/onchain.ts` | - -**文档遗漏的 flow**（代码有但表里没列）： - -| 代码存在 | 文档核对 | -|---------|---------| -| `src/flows/import-wallet.ts` 内的 import wallet flow | ❌ 整个文件 / flow 在文档中未提及 | - -**Agent / 开发者影响**：基于文档调 `tl_run_steps --flow chainTransferTrc20Flow` 会得到「flow not found」错误；同时不知道有 import-wallet flow 可用。 - -**整改**： - -1. 重新统计实际 flow，更新节标题（如「Flow Recipes（**23 个内置流程**）」） -2. 子类型表与代码逐项对齐： - - **链上类**：删除 `chainTransferTrc20Flow` / `chainSwapV3Flow`，改为 9 个；或在 onchain.ts 补这 2 个 flow 实现 - - **新增 Wallet 类**：列出 `importWallet*Flow` -3. 加 CI parity 检查（参考已有的 `scripts/check_doc_schema_parity.py` 模式）：扫 `src/flows/*.ts` 的 `export const ...Flow` 与文档表逐项 diff，CI 失败时阻塞 merge - -**验收**：文档总数 = 子类型加总 = 代码实际数；CI parity 检查覆盖 flow 名集合。 - ---- - -### P0-3 ⚠️ `bankofai/agent-wallet` GitHub 404 + 文档钉版 `^2.3.0` 已落后 npm 的 `2.4.0` - -**标准依据**：MCP §3 版本与兼容性 10 分锚点「有 breaking change / migration」+ 公共基线 §9 通用安全底线 - -**现状**： - -- mcp-server-tronlink §「依赖项」表写：`@bankofai/agent-wallet | ^2.3.0 | 加密本地钱包管理（local_secure）——已钉版本，不用 latest，确保钱包行为可复现` -- npm 实测：`@bankofai/agent-wallet@latest = 2.4.0`（2026-05 已发，维护者 = TRON 团队成员 parson.hu / hades.ye / leo.wu @tron.network） -- GitHub `bankofai/agent-wallet` repo **HTTP 404** - -**Agent / 开发者影响**： - -1. 钉版 `^2.3.0` 在 npm semver 下允许 2.3.x ~ 2.4.0 之前的所有版本，**实际锁不住 2.4.0**。文档"已钉版本"的承诺与实际不符 -2. GitHub 404 让开发者无法看源码 / 提 issue / 核对依赖透明性 -3. `agent-wallet` 持有钱包密码（`AGENT_WALLET_PASSWORD`），其源码不可见对安全敏感场景是 deal-breaker - -**整改**： - -1. 钉死到准确版本：`"@bankofai/agent-wallet": "2.3.0"`（无 caret），或显式声明「kept on 2.3.0; 2.4.0 待评估」 -2. 补一行：「GitHub 仓库当前未公开，源码透明性由 npm publish 提供。可通过 `npm pack @bankofai/agent-wallet@2.3.0 && tar -xzf ...` 解包审计。」 -3. 评估升级到 2.4.0（若 breaking 则 CHANGELOG 说明，若不 breaking 则升级减少漂移风险） - -**验收**：依赖版本与 npm 实际锁定一致；文档明示 GitHub 404 状态 + 源码审计路径；2 周内决策是否升级到 2.4.0。 - ---- - -### P0-4 ⚠️ 5 个 TronLink npm 包全部 0 GitHub releases / 0 tags - -**标准依据**：MCP §3 版本与兼容性 9 分锚点「有协议/server/schema 版本」+ CLI §3 版本/更新 10 分锚点「SPDX、changelog、deprecated、migration」+ 公共基线 §2.6 原则 10 一致性 - -**现状**： - -| Repo | npm latest | GitHub releases | GitHub tags | -|------|-----------|:---:|:---:| -| TronLink/mcp-server-tronlink | v0.1.1 | **0** | **0** | -| TronLink/tronlink-mcp-core | v0.1.0 | **0** | **0** | -| TronLink/mcp-tronlink-signer | (在子目录) | **0** | **0** | -| TronLink/tronlink-cli | v1.0.1 | **0** | **0** | -| TronLink/tronlink-skills | v1.0.1 | **0** | **0** | - -文档已明示「截至当前 v1.0.x / 0.1.x 尚无 GitHub tag 发布；打 tag 之前请直接看 commit 历史」——已知缺陷，但这是**5 个 repo 全部** 0 发布的系统性问题。 - -**Agent / 开发者影响**： - -1. npm 版本号无法对应到 GitHub commit hash，agent 无法基于 git tag 复现「v1.0.1 时的代码状态」 -2. 「Releases」是 GitHub 标准发布通知机制，0 releases = 订阅者收不到新版通知 -3. 文档说「兼容性与迁移策略」承诺「废弃窗口至少一个 minor 周期」，但没有 minor 边界（tag）参考点，策略落地不了 - -**整改**： - -1. 5 个 repo 一次性把当前 npm 版本回溯打 tag：`git tag v0.1.1 ` + `git push --tags` + `gh release create v0.1.1 --notes "$(npm view dist.shasum)"` -2. 加 npm publish CI workflow：每次 publish 自动打 tag + 创建 GitHub Release（含 npm shasum + dist tarball） -3. 文档兼容性节移除「打 tag 之前请直接看 commit 历史」（变成默认有 tag） - -**验收**：5 repo 每个 npm 版本对应一个 git tag + GitHub Release；Releases 页可订阅。 - ---- - -### P0-5 ⚠️ docs.tronlink.org 源码托管在 `xueyuanying/docs` 个人 repo（所有权 / 单点风险） - -**标准依据**：公共基线 §8 License + §9 通用安全底线 + 项目级覆盖度 §0「AI 入口索引层 = 帮 AI / Agent 找到权威文档」 - -**现状**： - -- mcp-server-tronlink §「精选工具 schema」L441 引用：`[check-doc-schema-parity.yml](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml)` -- gh api 实测：`xueyuanying/docs` 是个人 repo，pushed 2026-05-21（与文档站 Updated 时间戳一致 → 强烈暗示这是 docs.tronlink.org 的源码 repo） -- TronLink org 下没有看到对应的 docs repo - -**Agent / 开发者影响**： - -1. 开发者看到 CI 配置在个人 repo 会困惑（这是 TronLink 官方维护吗？） -2. 单点风险：维护者离职 / 转岗 / repo 删除 / 转 private → docs.tronlink.org 失去更新管道 -3. 公开引用个人 repo URL 暴露了维护者身份信息 - -**整改**： - -1. 把 docs 源码 repo 转移到 TronLink org（如 `TronLink/docs` 或 `TronLink/developer-docs`），保留 git history -2. 转移后更新 mcp-server-tronlink 文档里的 CI 引用 URL -3. 在 docs repo README 明示所有权 / 维护者 / contributor 流程 - -**验收**：docs 源码在 TronLink org 下可见；文档内所有引用 URL 更新到 org repo；GitHub URL `xueyuanying/docs` 可保留为 redirect 或归档。 - ---- - -### P0-6 ⚠️ MCP Core 错误码 SSOT 身份未明示 - -**标准依据**：MCP §3 错误契约 10 分锚点「可用于 agent 自动分支」+ 公共基线「跨文档错误码 SSOT 必须明示下游引用方」 - -**现状**：tronlink-mcp-core「标准化响应格式」节包含错误码表（实际 SSOT），但**未明示**它是 mcp-server-tronlink / mcp-tronlink-signer / tronlink-cli 三个下游文档共用的 SSOT。读者首次进入 mcp-core 文档无法判断错误码表的权威性。 - -**整改**：错误码表头加： - -```markdown -## 错误码 - -> **SSOT**：本表是 [mcp-server-tronlink](mcp-server-tronlink.md)、[mcp-tronlink-signer](mcp-tronlink-signer.md)、[tronlink-cli](tronlink-cli.md) 三个下游文档共用的错误码权威源。任何错误码新增 / 修改 / 删除均需先在本表更新，下游同步引用。变更需在 CHANGELOG 标注 breaking / non-breaking。 - -| Code | Retryable | Hint | Typical Trigger | -| ---- | :---: | ---- | ---- | -| TL_CLICK_FAILED | true | 重试前先 screenshot 确认 UI 状态 | ... | -| ... -``` - -**验收**：mcp-core 错误码表头部含 SSOT 声明；下游 3 文档的「error.code 枚举」段落改为「引用 mcp-core 错误码（SSOT），不在此重复」。 - ---- - -## 五、强建议整改（P1） - -### P1-1 MCP Signer 头部缺「该用哪个」三选一对照表 - -**现状**：mcp-server-tronlink 多处提到「生产环境涉及资金转移的工具，优先用 `mcp-tronlink-signer`（浏览器审批），而非 Direct-API」（L570 / L651），但 mcp-tronlink-signer 文档头部**没有反向对照表**，新读者无法快速判断三者差异。 - -**整改**：在 mcp-tronlink-signer §「配置」之前加： - -```markdown -## 该用哪个 - -| 选项 | HITL | 凭证 | 适用场景 | -|------|:---:|------|---------| -| `mcp-tronlink-signer`（本服务） | ✅ 浏览器审批 | 无（钱包在 TronLink 扩展） | 生产环境真实资金转移、需要用户每笔确认 | -| `mcp-server-tronlink` Direct-API 模式 | ❌ 无 | `AGENT_WALLET_PASSWORD` | CI / 自动化批量操作、非真实资金（测试网） | -| `tronlink-cli` | ✅ 浏览器审批 | 无 | Shell 脚本、终端工作流 | - -如不确定，优先选 `mcp-tronlink-signer`（最安全的默认值）。 -``` - ---- - -### P1-2 MCP Signer 缺 input schema 精选镜像 - -**现状**：mcp-server-tronlink 文档侧镜像了 7 个工具 input schema（`tl_chain_send` / `tl_chain_swap_v3` / `tl_chain_stake` 等）并 CI parity；mcp-tronlink-signer 完全不镜像，全依赖 `list_tools`。Agent 在没有 MCP 会话时无法离线编写工具调用。 - -**整改**：至少镜像 `send_trx` / `send_trc20` / `sign_typed_data` 3 个核心写工具的 input schema；加入同套 CI parity 检查覆盖范围。 - ---- - -### P1-3 跨文档代币 symbol 表不一致 - -**现状**： - -| 文档 | 内置代币 symbol 表内容 | -|------|------| -| `tronlink-cli` AI 智能体使用一节 | USDT / USDD / USDC（3 个） | -| `tronlink-skills` §「内置代币快捷符号」 | TRX / USDT / USDC / WTRX / BTT / JST / SUN / WIN（8 个） | -| `reference/networks`（公共参考） | 当前不明（待核） | - -差异：CLI 缺 BTT/JST/SUN/WIN/WTRX；Skills 缺 USDD。 - -**整改**：在 `reference/networks` 集中维护一份「常用代币合约 SSOT」（建议 ≥10 个：含 TRX / USDT / USDD / USDC / WTRX / BTT / JST / SUN / WIN 等），CLI / Skills / 其他文档统一引用，避免维护漂移。 - ---- - -### P1-4 MCP Core「与 mcp-server-tronlink 的关系」节缺决策矩阵 - -**现状**：mcp-core §「与 mcp-server-tronlink 的关系」存在，但未提供「何时用 mcp-core / 何时直接用 mcp-server-tronlink」的决策表。开发者拿到两个包不知道该选哪个。 - -**整改**：在该节加： - -```markdown -| 场景 | 选 mcp-core | 选 mcp-server-tronlink | -|------|:---:|:---:| -| 自建定制 MCP server（嵌入业务逻辑） | ✅ | ❌ | -| 直接给 agent 用 | ❌ | ✅ | -| 扩展能力（自定义 Capability） | ✅ | ❌ | -| 测试 / mock | ✅ | ✅（带 e2e 模式） | -| 学习 MCP 框架 | ✅ | ❌ | -``` - ---- - -### P1-5 onchain.ts 缺 `chainTransferTrc20Flow` / `chainSwapV3Flow` 实现（同步 P0-2） - -**现状**：见 P0-2。文档列了这两个但代码缺。 - -**整改方案**（任选其一）： - -- **方案 A**：补实现（如果产品确实需要）—— 参考 `chainTransferTrxFlow` / 现有 swap 工具 `tl_chain_swap_v3` 写 flow 包装 -- **方案 B**：文档删除这两行（如果产品决策不做 flow，只暴露原子工具） - ---- - -### P1-6 MCP Server 文档头「快速开始」步骤 3 钱包路径 A/B 选择不直观 - -**现状**：钱包密码是高敏感凭证，路径 B 自动创建会**明文写入 `~/.agent-wallet/runtime_secrets.json`**（文档已明示）。新用户照默认走 A/B 任一即开搞，没有「场景 → 路径」决策表，agent 容易选错路径。 - -**整改**：在快速开始步骤 3 加： - -```markdown -| 场景 | 推荐路径 | 原因 | -|------|---------|------| -| 生产环境（真实资金） | A — 手动创建 + secret manager | 路径 B 会明文落盘密码 | -| CI / 自动化（测试网） | A — 手动创建 + env injection | 同上 | -| 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 | -| 临时 demo 演示 | B + tmpfs 目录 | 任务结束即销毁 | -``` - ---- - -### P1-7 mcp-tronlink-signer 与 tronlink-signer SDK 的版本对应关系不明 - -**现状**：mcp-tronlink-signer 文档说「将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具」—— 暗示 `tronlink-signer` 是 monorepo 子包。但： - -1. 独立的 [tronlink-signer 文档页](https://docs.tronlink.org/zh/ai-support/tronlink-signer/) 存在 -2. CLI 文档说 `tronlink-signer 0.1.4` 是依赖（暗示是独立 npm 包） -3. mcp-tronlink-signer 文档没说「我用的 tronlink-signer 版本是 N，与独立 SDK 文档对齐到 commit X」 - -读者不知道这 3 处的 `tronlink-signer` 是不是同一份代码。 - -**整改**：mcp-tronlink-signer 头部加： - -```markdown -> **关系澄清**：本服务 = 把 [`tronlink-signer` SDK](tronlink-signer.md) v0.1.4 封装为 MCP server。SDK 与 wrapper 同 monorepo 维护，版本同步发布。直接用 SDK 见 [tronlink-signer](tronlink-signer.md)；用 MCP wrapper 见本页。 -``` - ---- - -### P1-8 「依赖项」表的「数据截至 2026-05」需要定期更新机制 - -**现状**：mcp-server-tronlink / CLI / Skills 都有「数据截至 2026-05」标注（好）。但没有更新机制 —— 6 月、7 月数据漂移后谁来改？ - -**整改**： - -1. 加 CI 任务：每月扫所有 `数据截至 YYYY-MM` 字样，超过 N 个月触发文档 issue 提醒 -2. 或改为「Last verified: 2026-05-21」+ commit hash 引用，让 reader 知道这是固定快照 - ---- - -### P1-9 Skills 反例表的「正确路由」工具名应做 CI parity 检查 - -**现状**：mcp-server-tronlink 已经有 CI parity 检查工具名；Skills 反例表里的 `tl_chain_send` / `tl_chain_stake` / `tl_chain_swap_v3` 等工具名引用 mcp-server-tronlink，但跨文档的工具名引用没纳入 parity 检查。如果 mcp-server 改名 `tl_chain_send` → `tl_send_trx`，Skills 反例表会变成死引用。 - -**整改**：parity 脚本扩到扫 Skills 文档对 `tl_*` 名字的引用，与 mcp-server 实际 list_tools 输出 diff。 - ---- - -## 六、锦上添花（P2） - -### MCP / CLI / 入口（8 条） - -| # | 文档 | 问题 | 建议 | -|:-:|------|------|------| -| P2-1 | MCP Server | Use Cases 6 条概括，缺端到端 agent 对话示例 | 补 1-2 个对话示例（如 SunSwap V3 swap 端到端） | -| P2-2 | MCP Server | Flow Recipes 子类型表与 src/flows/ 文件名不直观对应 | 表格加 `Source File` 列（如 `chainCheckBalanceFlow → src/flows/onchain.ts`） | -| P2-3 | MCP Core | 52 工具定义节按数字分组（1-13）阅读时跳跃 | 加目录跳转或合并为表 | -| P2-4 | MCP Signer | 内联 changelog 与 GitHub releases 双源 | 加同步策略说明（如「内联 SSOT，GitHub release 滞后 7 天」） | -| P2-5 | CLI | 退出码 5「网络错误」缺「如何确认上一笔未上链」指引 | 加「查 `tronscan.org/#/transaction/` 或 `tronlink balance --address` 对账」 | -| P2-6 | CLI | 常用代币合约表 3 个（同 P1-3） | 扩到 ≥8 个或引用 reference/networks SSOT | -| P2-7 | AI/LLMs 入口 | 「给智能体的说明」缺版本契约引用 | 加一条「版本契约见各工具页 §兼容性与迁移策略」 | -| P2-8 | 全站 | 引用 GitHub commit hash 时缺「截至日期」 | 引用 commit 时加 `(as of YYYY-MM-DD)` | - -### Skills（5 条，需协调产品组 owner） - -| # | 文档 | 问题 | 建议 | -|:-:|------|------|------| -| Skill-P2-1 | Skills | 缺独立 Troubleshooting 章节 | 错误处理散在「安全模型」表里。独立成节覆盖 5 类：① agent 未识别 skill ② TronGrid 限流 ③ CLI-only 命令被 MCP 调用 ④ install.sh 故障路径 ⑤ 多 host 命令名冲突 | -| Skill-P2-2 | Skills | 内置代币 symbol 表与 CLI 不一致（同 P1-3） | 合到 `reference/networks` SSOT，Skills / CLI 引用 | -| Skill-P2-3 | Skills | TronGrid API Key 凭证管理一笔带过 | 补 5 维（存储 / 最小权限 / 轮换 / 泄漏检测 / 撤销） | -| Skill-P2-4 | Skills | 推荐工作流是流程图式路径 | 补 1-2 个端到端 agent 对话示例（如「100 TRX 换 USDT 划算吗？」串 token-price → kline → resource-info → swap-quote） | -| Skill-P2-5 | Skills | `mcp_server.mjs ↔ tron_api.mjs` 等价性靠人盯 | 加 CI parity 检查（参考 mcp-server-tronlink 的 `check_doc_schema_parity.py`） | - -> **协调建议**：Skill-P2-2 / P2-5 与 P1-3 / P1-9 联动，建议两边一起整改一次性解决。 - ---- - -## 七、跨文档一致性 grep 清单 - -> 团队可逐项 grep 全站核对，建议加入 CI parity 检查。 - -| 检查项 | grep 命令 | 期望结果 | -|--------|-----------|----------| -| 错误码锚点存在 | `grep -rn "tronlink-mcp-core.md#错误码" docs/` | 引用方 3 处，目标节存在 | -| Flow Recipes 计数一致 | 对比文档表与 `src/flows/*.ts` 实际 export | 三方一致 | -| `chainTransferTrc20Flow` 不出现在文档（或代码补实现） | `grep -rn "chainTransferTrc20Flow\|chainSwapV3Flow" .` | 文档与代码同步 | -| 工具名 `tl_*` 引用统一 | 跨 mcp-server / mcp-signer / cli / skills grep `tl_chain_send` 等 | 全站命名一致 | -| 网络命名（mainnet / nile / shasta） | `grep -rn -iE "mainnet\|nile\|shasta\|niletest\|testnet" docs/` | 全站统一三档 | -| `@bankofai/agent-wallet` 版本 | `grep -rn "agent-wallet.*[0-9]\.[0-9]" docs/` | 文档版本与 npm 实际锁定一致 | -| 代币 symbol 表 SSOT | `grep -rn "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t" docs/` | 仅在 reference/networks 出现一次 | -| GitHub 0 releases | `gh api repos/TronLink/{mcp-server-tronlink,...}/releases --jq 'length'` | 全部 > 0 | -| 个人 repo 引用 | `grep -rn "xueyuanying/docs" docs/` | 0（已迁到 org repo） | - ---- - -## 八、整改 checklist - -### P0（必改，6 项） - -- [ ] **P0-1** mcp-core 加 `## 错误码` 二级标题，与 3 处死锚点对齐 -- [ ] **P0-2** Flow Recipes：核对 23 实际 flow + 删除 / 补全 `chainTransferTrc20Flow` / `chainSwapV3Flow` + 文档加 `import-wallet` flow + 节标题计数更新 -- [ ] **P0-3** `@bankofai/agent-wallet` 改为精确版本 + 决策是否升级 2.4.0 + 文档明示 GitHub 404 状态 -- [ ] **P0-4** 5 个 TronLink npm 包回溯打 git tag + 创建 GitHub Release + npm publish CI 自动化 -- [ ] **P0-5** docs 源码 repo 从 `xueyuanying/docs` 迁移到 `TronLink/docs` 或 `TronLink/developer-docs` -- [ ] **P0-6** mcp-core 错误码表加 SSOT 声明 + 下游 3 文档改为引用而非重复 - -### P1（强建议，9 项） - -- [ ] **P1-1** mcp-tronlink-signer 头部加「该用哪个」三选一对照表 -- [ ] **P1-2** mcp-tronlink-signer 补 input schema 镜像 3 个 + CI parity -- [ ] **P1-3** 代币 symbol 表合到 reference/networks SSOT -- [ ] **P1-4** mcp-core 加「与 mcp-server-tronlink」决策矩阵 -- [ ] **P1-5** onchain.ts 补 chainTransferTrc20Flow / chainSwapV3Flow 实现（或文档删除） -- [ ] **P1-6** mcp-server 快速开始钱包路径 A/B 加「场景→路径」决策表 -- [ ] **P1-7** mcp-tronlink-signer 头部澄清与 SDK 版本对应关系 -- [ ] **P1-8** 「数据截至 YYYY-MM」改为「Last verified + commit」+ CI 提醒 -- [ ] **P1-9** Skills `tl_*` 引用纳入 CI parity 检查 - -### P2（锦上添花，8 项 + 5 项 Skills） - -#### MCP / CLI / 入口（8 项） - -- [ ] **P2-1** MCP Server Use Cases 补端到端对话示例 -- [ ] **P2-2** Flow Recipes 表加 Source File 列 -- [ ] **P2-3** MCP Core 52 工具定义合并为表 -- [ ] **P2-4** MCP Signer 内联 changelog 加同步策略 -- [ ] **P2-5** CLI 退出码 5 加「如何确认上一笔未上链」指引 -- [ ] **P2-6** CLI 常用代币合约表扩到 ≥8 个 -- [ ] **P2-7** AI/LLMs 入口加版本契约引用 -- [ ] **P2-8** GitHub commit hash 引用加「截至日期」 - -#### Skills（5 项，需协调产品组 owner） - -- [ ] **Skill-P2-1** 加独立 §Troubleshooting 章节 -- [ ] **Skill-P2-2** 代币 symbol 表合到 reference/networks SSOT -- [ ] **Skill-P2-3** 加 TronGrid API Key 凭证管理 5 维 -- [ ] **Skill-P2-4** 推荐工作流至少 2 个配端到端 agent 对话示例 -- [ ] **Skill-P2-5** 加 `mcp_server.mjs ↔ tron_api.mjs` CI parity workflow - ---- - -## 九、标准锚点对照表 - -| 整改项 | 标准章节 / 锚点 | -|--------|----------------| -| 错误结构（code / retryable / hint） | MCP §3 / CLI §3 / 公共基线 §3 + §4 | -| 副作用 5 级（Safe / Network Read / Local Write / Remote Write / Destructive） | 公共基线 §2 | -| 错误码 SSOT 跨文档共享 | 公共基线 §4 + 项目级覆盖度 §0「串联关系」9 分锚点 | -| Schema 完整度（input/output + version） | MCP §3 | -| 机器可读输出（`--json` + schema） | CLI §3 | -| 退出码契约 + retryable | CLI §3 + §4 | -| 副作用分级标记 | MCP §6 P0 + CLI §6 P0 + 公共基线 §2 | -| 版本契约 / changelog | MCP §3 + CLI §3 + 公共基线 §8 | -| 风险隔离（dry-run / preview） | CLI §4 + 公共基线 §9 | -| 自发现入口（`--help` / `list_tools` / llms.txt） | 公共基线 §6 | -| AI 入口索引（llms.txt） | 项目级覆盖度 §0 + §0.2 | -| 跨文档引用 SSOT 不割裂 | 项目级覆盖度 §0「Schema / Error / Examples 串联」15% 权重 | -| Skill 反例表 + 判断口诀 | Skill §4.1「发现选择」10 分锚点 | -| Skill ↔ MCP 子集关系明示 | Skill §4.1 客户端兼容 + 版本契约 | - ---- - -## 十、整改前后预期对比 - -| 文档 | 当前 | 整改 P0 后 | 整改 P0+P1 后 | -|------|:---:|:---:|:---:| -| MCP Server | 87.0 | 94 | 98 | -| MCP Core | 77.8 | 90 | 95 | -| MCP Signer | 88.0 | 92 | 96 | -| CLI | 94.0 | 97 | 99 | -| Skills | 98.5 | 98.5 | 100 | -| AI/LLMs 入口 | 100.0 | 100 | 100 | -| **平均** | **90.9** | **95.3** | **98.0** | - ---- - -## 十一、与上一轮评审差距说明 - -上一轮（2026-05-22 首轮 review）我给出的评分是 6 文档平均 **97.8**（MCP Server 100 / CLI 100 / MCP Core 95.4 / MCP Signer 93 / Skills 98.5 / AI 入口 100）。本次重审下调到 **90.9**，差距 −6.9 分。**差距不是因为文档质量退步，而是评分深度提升**： - -| 重审挖出的问题 | 上一轮是否漏 | 本轮发现路径 | -|----------------|:---:|------| -| `tronlink-mcp-core.md#错误码` 死锚点（3 处） | ❌ 漏 | grep 跨文档锚点 + 核对 mcp-core 章节 | -| Flow Recipes 文档 32 / 加总 24 / 代码 23 三方矛盾 | ⚠️ 仅指出 32 vs 24 | gh api 取 `src/flows/*.ts` 实际 export 计数 | -| `chainTransferTrc20Flow` / `chainSwapV3Flow` 文档列了但代码不存在 | ❌ 漏 | grep onchain.ts 实际 flow 名 | -| `bankofai/agent-wallet` GitHub 404 + 文档版本落后 | ❌ 漏 | gh api repo + curl npm registry 双向核对 | -| 5 个 repo 0 releases / 0 tags | ❌ 漏 | gh api releases / tags 系统性扫描 | -| docs.tronlink.org 源码托管在 `xueyuanying/docs` 个人 repo | ❌ 漏 | gh api 个人 repo + pushed_at 时间戳对齐 | -| 错误码 SSOT 身份未明示 | ⚠️ 仅 P1 | 重审升级，跨文档引用关系 | - -**这一轮按更扎实的深度做**：grep 死链 + 核对源码 + npm registry 实测 + GitHub repo 活性 + 跨文档术语一致性。 - -**Skills 是 6 篇文档中唯一一份「重审无新发现」的样板** — 33/25/8 数字与代码完美对齐，`mcp_server.mjs ↔ tron_api.mjs` 同源 SSOT。 - ---- - -**评审完成。** 如对评分逻辑、整改优先级、参考实现有疑问可直接联系 PM。整改完成后可申请复评。 - -附：参考实现样板（按本标准达 A+ 级）： - -- [`ai-support/mcp-server-tronlink`](https://docs.tronlink.org/zh/ai-support/mcp-server-tronlink/) 自身（整改 P0/P1 后） -- [`reference/error-code-map`](https://docs.tronlink.org/zh/reference/error-code-map/) — 五通道错误码对照表（含 retryable 列） -- [`zh/llms.txt`](https://docs.tronlink.org/zh/llms.txt) — `llms.txt` 实现样板 -- [`scripts/check_doc_schema_parity.py`](https://github.com/xueyuanying/docs/blob/main/.github/workflows/check-doc-schema-parity.yml) — CI parity 实现样板（建议迁移到 TronLink org，见 P0-5） From c265e1b8c2cb46b217d2c3c40ea3cd998639cee6 Mon Sep 17 00:00:00 2001 From: Tron Date: Fri, 29 May 2026 17:29:39 +0800 Subject: [PATCH 07/10] docs: attr_list-stabilize remaining CJK heading anchors The default MkDocs slugify strips CJK, so ZH headings got unstable (or ugly, e.g. #6) ids and several in-page / cross-doc links didn't resolve. Enable the attr_list extension and pin explicit English anchor ids on 11 CJK headings (matching the EN-side slugs), then repoint every link to them: - mcp-tronlink-signer.zh: #errors, #environment-variables, #version-license, #inline-changelog - mcp-server-tronlink.zh: #selected-tool-schemas-inline-mirror, #wallet-secret-storage - tronlink-signer.zh: #broadcast-result - tronlink-skills.zh: #skill-mcp-tool-map, #the-6-skills - deeplink.zh: #result-code - active-requests.zh: #get-tronlink-provider-via-tip-6963 Also fix same-class EN-side broken links surfaced by the build (double-hyphen typos: #version--license, #skill--mcp-tool-map). gen_llms_full.py now strips trailing ` { #id }` from headings so the plain-text bundles don't leak attr_list syntax (narrow regex: id-only blocks at end-of-line, leaves `Promise<{ ... }>` headings intact). llms.txt / llms-full.* regenerated. Build-verified: zero "no such anchor" warnings site-wide (was 4), bundles carry no attr_list leakage. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ai-support/mcp-server-tronlink.zh.md | 6 ++-- docs/ai-support/mcp-tronlink-signer.en.md | 2 +- docs/ai-support/mcp-tronlink-signer.zh.md | 16 +++++----- docs/ai-support/tronlink-mcp-core.zh.md | 2 +- docs/ai-support/tronlink-signer.zh.md | 10 +++---- docs/ai-support/tronlink-skills.en.md | 6 ++-- docs/ai-support/tronlink-skills.zh.md | 10 +++---- docs/llms-full.en.txt | 14 ++++----- docs/llms-full.txt | 14 ++++----- docs/llms-full.zh.txt | 36 +++++++++++------------ docs/llms.txt | 2 +- docs/llms.zh.txt | 2 +- docs/mobile/deeplink.zh.md | 4 +-- docs/plugin-wallet/active-requests.zh.md | 4 +-- mkdocs.yml | 1 + scripts/gen_llms_full.py | 17 ++++++++++- 16 files changed, 81 insertions(+), 65 deletions(-) diff --git a/docs/ai-support/mcp-server-tronlink.zh.md b/docs/ai-support/mcp-server-tronlink.zh.md index 03ef2f9..1edc8b5 100644 --- a/docs/ai-support/mcp-server-tronlink.zh.md +++ b/docs/ai-support/mcp-server-tronlink.zh.md @@ -438,7 +438,7 @@ mcp-server-tronlink/ - **人工确认（HITL）：** 写操作工具使用加密的本地 `agent-wallet` 签名；浏览器模式下由用户在 TronLink UI 审批。生产环境应将每个「远程写」工具视为需要确认。 - **重试：** 只读工具可安全重试；「远程写」工具除非证明幂等，否则不得自动重试。 -### 精选工具 schema（文档侧镜像） +### 精选工具 schema（文档侧镜像） { #selected-tool-schemas-inline-mirror } 以下是最关键工具输入的**文档侧镜像**——当 agent 需要在没有打开 MCP 会话的情况下写工具调用站点时使用。运行时 `list_tools` 仍是权威源：那里有完整的 Zod 元信息（描述、`default` 等）以及 `meta.schemaVersion`。下方字段抄自 `@tronlink/tronlink-mcp-core` `src/mcp-server/schemas.ts`，遵循 JSON Schema Draft 7。**未**镜像全部 52 个工具——以 core 仓库为 SSOT。 @@ -627,7 +627,7 @@ mcp-server-tronlink/ 重启后用 `list_tools` 验证：`tl_evaluate` 应当不再出现。同一套模式也适用于 `tl_seed_contract` / `tl_seed_contracts`（仅 e2e 的合约部署工具）。 -### 钱包密钥存储 +### 钱包密钥存储 { #wallet-secret-storage } Direct-API 路径使用 `@bankofai/agent-wallet` 管理的本地加密钱包签名。解锁这把钱包有两条路径，请按目的明确选择。 @@ -742,7 +742,7 @@ export TL_TRONGRID_URL="https://nile.trongrid.io" | 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 | | 临时 demo 演示 | B + tmpfs 目录 | 把 `AGENT_WALLET_DIR` 指到任务结束即销毁的 tmpfs | -> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#钱包密钥存储)。 +> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#wallet-secret-storage)。 ## 版本与许可证 diff --git a/docs/ai-support/mcp-tronlink-signer.en.md b/docs/ai-support/mcp-tronlink-signer.en.md index a13d11c..160d7f6 100644 --- a/docs/ai-support/mcp-tronlink-signer.en.md +++ b/docs/ai-support/mcp-tronlink-signer.en.md @@ -4,7 +4,7 @@ MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet. -> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version--license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. +> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version-license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. ## Which to use diff --git a/docs/ai-support/mcp-tronlink-signer.zh.md b/docs/ai-support/mcp-tronlink-signer.zh.md index 601870a..4f7c3b0 100644 --- a/docs/ai-support/mcp-tronlink-signer.zh.md +++ b/docs/ai-support/mcp-tronlink-signer.zh.md @@ -4,7 +4,7 @@ 将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具的服务器，供 Claude 及其他 AI 客户端使用。通过 TronLink 浏览器钱包对 TRON 交易进行签名，需用户在浏览器中授权确认 — 私钥始终留在钱包中，不会对外暴露。 -> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#版本与许可证)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。 +> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#version-license)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。 ## 该用哪个 @@ -180,7 +180,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si > 「已发送 5 TRX——链上已确认（交易 `0a1b2c…`）。」 -> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#错误)）。 +> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#errors)）。 ## 取消 @@ -190,7 +190,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si 当调用 `sign_transaction` 且 `broadcast: true` 时，服务器会在广播后自动轮询链上确认状态，并返回执行结果（`success` 或 `pending`）。如果交易在链上失败（如 `OUT_OF_ENERGY`、Solidity revert），错误信息会连同解码后的原因一并返回给 AI 智能体。 -## 错误 +## 错误 { #errors } server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `retryable`，便于 agent 在不解析自然语言的前提下做分支。框架层错误码统一以 [TronLink MCP Core 错误码](tronlink-mcp-core.md#error-codes) 为准；signer 特有错误如下： @@ -213,13 +213,13 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r |---|---|---| | **Prompt 注入** | 工具输入按原始值作为调用参数，server 不会再次提交给 LLM。TronLink 审批页渲染的是解析后的交易字段，不是 agent 的自由文本。 | 链上拿到的字符串（备注、revert 原因）视为不可信；分支应基于 `txId` / `status` / `code`，而非 prose。 | | **本地 HTTP listener** | 本地审批 server **仅绑定 `127.0.0.1`**（端口 `TRON_HTTP_PORT`，默认 3386，被占用时自增），永远不接受跨主机连接。每个 server session 有唯一 ID，前一次 session 的浏览器标签会被自动失效。 | 不要把 3386 端口转发到外网。同一台机器不要用相同 `TRON_HTTP_PORT` 跑两份。 | -| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#环境变量) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 | +| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#environment-variables) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 | | **API key 处理（token passthrough）** | `TRON_API_KEY` 仅在启动时从 env 读取，仅用于到 TronGrid 的出站；**不**会出现在任何工具响应、错误 `details` 或 MCP resource 中。server 不接受 MCP 客户端传入的 Authorization header 并转发到上游。 | API key 放进 MCP host 的 secret manager，不要写进会提交 git 的 `mcpServers` 配置。 | | **签名必须 HITL** | 所有签名工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 审批页，**不存在程序化绕过**。私钥始终留在 TronLink。 | 不需要运维额外强制 HITL——这是结构性保证。不要试图通过移除浏览器层来"加固"。 | | **浏览器标签劫持** | 审批页基于 server session ID 验证每次请求，过期的标签会被忽略；心跳检测会在断连时关闭 session。 | 同一用户跑多个 agent 时，请让每个 agent 启动自己的 signer 实例；跨实例的请求串扰由 session ID 屏蔽，但 UI 层混淆不防。 | | **Confused deputy** | signer 以已连接的 TronLink 账户身份执行，没有来自 MCP 客户端的逐次授权 scope。 | 一个 signer 实例 = 一个 TronLink 账户，不要把多个终端用户复用到同一个实例。 | -## 环境变量 +## 环境变量 { #environment-variables } | 变量名 | 说明 | 默认值 | | ------ | ---- | ------ | @@ -227,13 +227,13 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r | `TRON_HTTP_PORT` | 本地 HTTP 服务端口 | `3386` | | `TRON_API_KEY` | TronGrid API Key（可选） | - | -## 版本与许可证 +## 版本与许可证 { #version-license } - **包：** `mcp-tronlink-signer` v0.1.4 - **许可证：** MIT —— `SPDX-License-Identifier: MIT` - **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) -### 内联 changelog +### 内联 changelog { #inline-changelog } 本页是下游 README 镜像；以 GitHub releases 与各包 `CHANGELOG.md` 为准。下方条目只覆盖 **MCP 可见面**（工具、schema、安全边界），内部重构不列。 @@ -257,7 +257,7 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r - **改进** —— 单页审批流：一个常驻浏览器标签 + 心跳检测；server 重启后旧标签自动失效。 - **改进** —— TRC20 金额校验改用 BigInt 小数转换（处理 0 位小数、>18 位小数等边界）。 - **改进** —— `send_trx`、`sign_transaction` 在提交失败时返回真实的 broadcast 错误，不再是空消息。 -- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#错误)）。 +- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#errors)）。 #### v0.1.1 — 2026-04-15 diff --git a/docs/ai-support/tronlink-mcp-core.zh.md b/docs/ai-support/tronlink-mcp-core.zh.md index 017167f..17d0914 100644 --- a/docs/ai-support/tronlink-mcp-core.zh.md +++ b/docs/ai-support/tronlink-mcp-core.zh.md @@ -259,7 +259,7 @@ interface GasFreeCapability { 所有工具使用 `tl_` 前缀，分为 13 个类别： -> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#精选工具-schema文档侧镜像) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。 +> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#selected-tool-schemas-inline-mirror) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。 ### 1. 会话管理（2 个） | 工具 | 说明 | diff --git a/docs/ai-support/tronlink-signer.zh.md b/docs/ai-support/tronlink-signer.zh.md index b56098a..f499d9d 100644 --- a/docs/ai-support/tronlink-signer.zh.md +++ b/docs/ai-support/tronlink-signer.zh.md @@ -50,7 +50,7 @@ await signer.stop(); ### `signer.sendTrx(to, amount, network?, options?): Promise` -向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#广播结果)）。 +向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#broadcast-result)）。 | 参数 | 类型 | 说明 | | ---- | ---- | ---- | @@ -61,7 +61,7 @@ await signer.stop(); ### `signer.sendTrc20(contractAddress, to, amount, decimals?, network?, options?): Promise` -发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#广播结果)。 +发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#broadcast-result)。 | 参数 | 类型 | 说明 | | ---- | ---- | ---- | @@ -93,7 +93,7 @@ const { signature } = await signer.signTypedData({ ### `signer.signTransaction(transaction, network?, broadcast?, options?): Promise<{ signedTransaction; txId?; status?; error? }>` -对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#广播结果)。 +对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#broadcast-result)。 | 参数 | 类型 | 说明 | | ---- | ---- | ---- | @@ -121,7 +121,7 @@ const result = await signer.signTransaction(tx, "nile", true, { }); ``` -### 广播结果 +### 广播结果 { #broadcast-result } 广播类方法（`sendTrx`、`sendTrc20`、以及 `broadcast: true` 时的 `signTransaction`）均返回 `BroadcastResult`： @@ -302,7 +302,7 @@ export type { - **包：** `tronlink-signer` v0.1.4 - **许可证：** MIT —— `SPDX-License-Identifier: MIT` -- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#内联-changelog)，SDK 层跟随同一波次。 +- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#inline-changelog)，SDK 层跟随同一波次。 ### 兼容性与迁移策略 diff --git a/docs/ai-support/tronlink-skills.en.md b/docs/ai-support/tronlink-skills.en.md index 9cabf72..cbf2d66 100644 --- a/docs/ai-support/tronlink-skills.en.md +++ b/docs/ai-support/tronlink-skills.en.md @@ -531,9 +531,9 @@ tronlink-skills/ | Symptom | Cause | What to do | |---------|-------|------------| -| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill--mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | +| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill-mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | | TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). | -| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill--mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | +| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill-mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | | `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. | | Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add `), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. | @@ -594,7 +594,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma - **Stable contracts** (won't change in a minor or patch): - The 33 CLI command names and their required / optional flags (`tron_api.mjs [...]`). - - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill--mcp-tool-map) (`tron_*` form) and their `inputSchema` keys. + - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill-mcp-tool-map) (`tron_*` form) and their `inputSchema` keys. - Exit codes: `0` success, `1` query error / invalid input, `2` unsupported / unknown command. - The `Network Read` side-effect classification — no command will ever become a Remote Write without a major bump. - **Volatile contracts** (may change in a minor): diff --git a/docs/ai-support/tronlink-skills.zh.md b/docs/ai-support/tronlink-skills.zh.md index c1f5934..2413597 100644 --- a/docs/ai-support/tronlink-skills.zh.md +++ b/docs/ai-support/tronlink-skills.zh.md @@ -50,7 +50,7 @@ tron_api.mjs (Node.js 18+, 原生 fetch, 零依赖) --- -## 6 大技能详解 +## 6 大技能详解 { #the-6-skills } ### 1. tron-wallet（6 个命令） @@ -153,7 +153,7 @@ Stake 2.0 查询与 SR 信息。 --- -## Skill ↔ MCP 工具映射 +## Skill ↔ MCP 工具映射 { #skill-mcp-tool-map } `scripts/mcp_server.mjs`（即[方式二](#mcp)的封装）将 **33 个 CLI 命令中的 25 个** 暴露为 MCP 工具——签名、输入字段、输出结构都由同一份 `tron_api.mjs` 实现派生，因此 CLI 与 MCP 工具保证等价。剩余 8 个 CLI-only 命令仍可通过方式一（skill 提示词）和方式三（直接 CLI）使用。需要按用户提问路由到具体工具，或核对 `tools/list` 输出时，请用下表。 @@ -531,9 +531,9 @@ tronlink-skills/ | 现象 | 原因 | 处理方式 | |------|------|----------| -| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#6) / [Skill ↔ MCP 工具映射](#skill--mcp) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | +| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#the-6-skills) / [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | | TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#_1)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | -| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill--mcp)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | +| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill-mcp-tool-map)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | | `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 | | 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add `），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 | @@ -594,7 +594,7 @@ Skills 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级 - **稳定契约**（minor / patch 不会动）： - 33 个 CLI 命令名与其必填 / 可选 flag（`tron_api.mjs [...]`）。 - - [Skill ↔ MCP 工具映射](#skill--mcp-工具映射) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。 + - [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。 - Exit code：`0` 成功，`1` 查询错误 / 参数非法，`2` 未支持 / 未知命令。 - `Network Read` 副作用分级——任何命令未经 major 升级都不会变成 Remote Write。 - **不稳定契约**（minor 允许变化）： diff --git a/docs/llms-full.en.txt b/docs/llms-full.en.txt index 71b5259..70eadd3 100644 --- a/docs/llms-full.en.txt +++ b/docs/llms-full.en.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T08:48:03Z -- Commit: 1aed03bbd2cc +- Generated: 2026-05-29T09:27:31Z +- Commit: 16a8d8d4f105 - Language: en - Pages: 23 -- Token estimate: ~60,361 (chars / 4) +- Token estimate: ~60,360 (chars / 4) --- @@ -4059,9 +4059,9 @@ tronlink-skills/ | Symptom | Cause | What to do | |---------|-------|------------| -| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill--mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | +| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill-mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | | TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). | -| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill--mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | +| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill-mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | | `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. | | Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add `), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. | @@ -4122,7 +4122,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma - **Stable contracts** (won't change in a minor or patch): - The 33 CLI command names and their required / optional flags (`tron_api.mjs [...]`). - - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill--mcp-tool-map) (`tron_*` form) and their `inputSchema` keys. + - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill-mcp-tool-map) (`tron_*` form) and their `inputSchema` keys. - Exit codes: `0` success, `1` query error / invalid input, `2` unsupported / unknown command. - The `Network Read` side-effect classification — no command will ever become a Remote Write without a major bump. - **Volatile contracts** (may change in a minor): @@ -4143,7 +4143,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet. -> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version--license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. +> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version-license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. ## Which to use diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 71b5259..70eadd3 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T08:48:03Z -- Commit: 1aed03bbd2cc +- Generated: 2026-05-29T09:27:31Z +- Commit: 16a8d8d4f105 - Language: en - Pages: 23 -- Token estimate: ~60,361 (chars / 4) +- Token estimate: ~60,360 (chars / 4) --- @@ -4059,9 +4059,9 @@ tronlink-skills/ | Symptom | Cause | What to do | |---------|-------|------------| -| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill--mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | +| Agent doesn't recognize a skill | Skill bundle not discovered, wrong command name, or host not reloaded | Confirm the bundle is installed/symlinked (re-run `install.sh`, or check the symlink under the host's discovery path — e.g. `~/.agents/skills/tronlink-skills` for Codex); verify the exact name against [The 6 Skills](#the-6-skills) / [Skill ↔ MCP Tool Map](#skill-mcp-tool-map); then restart the agent/host so it re-scans `SKILL.md`. | | TronGrid rate limiting (HTTP 429) | No API key, or polling too aggressively | Set `TRONGRID_API_KEY` (see [Configuration](#environment-variables)) for higher limits; reduce polling frequency; add exponential backoff and retry on 429/5xx (these are retryable query errors). | -| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill--mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | +| A CLI-only command invoked via MCP | 8 of the 33 commands are not exposed as MCP tools (`contract-info`, `trade-history`, `dex-volume`, `large-transfers`, `pool-info`, `swap-route`, `estimate-bandwidth`, `energy-rental`) | Check the [Skill ↔ MCP Tool Map](#skill-mcp-tool-map): rows marked _(CLI only)_ have no `tron_*` MCP tool. Reach them via Method 1 (skill prompt) or Method 3 (direct CLI: `node scripts/tron_api.mjs ...`) instead of `tools/call`. | | `install.sh` fails | Network blocked, target dir not writable, or missing runtime | Ensure Node.js >= 18 and `git`/`curl` are on `PATH`; re-run with write access to the discovery dirs (`~/.cursor`, `~/.agents/skills`, etc.); if a step is permission-blocked, perform the symlink manually (see Method 4 — Codex CLI) and re-run `codex skills list | grep tron` to verify. | | Multi-host command-name collision | The same skill/tool name is registered by more than one MCP host (e.g. both `tronlink` and `tronlink-skills` expose `tron_*`) | Give each host a distinct name in the agent config (`mcpServers` key / `claude mcp add `), so tool names are namespaced per host; or disable the duplicate host so only one registration of each `tron_*` name is active. | @@ -4122,7 +4122,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma - **Stable contracts** (won't change in a minor or patch): - The 33 CLI command names and their required / optional flags (`tron_api.mjs [...]`). - - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill--mcp-tool-map) (`tron_*` form) and their `inputSchema` keys. + - The 25 MCP tool names listed in [Skill ↔ MCP Tool Map](#skill-mcp-tool-map) (`tron_*` form) and their `inputSchema` keys. - Exit codes: `0` success, `1` query error / invalid input, `2` unsupported / unknown command. - The `Network Read` side-effect classification — no command will ever become a Remote Write without a major bump. - **Volatile contracts** (may change in a minor): @@ -4143,7 +4143,7 @@ Skills are at **v1.0.x**, so standard semver applies — only **major** bumps ma MCP Server that exposes [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) as MCP tools for Claude and other AI clients. Sign TRON transactions via TronLink browser wallet with user approval — private keys never leave the wallet. -> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version--license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. +> **Relationship to `tronlink-signer`.** This server is a thin MCP wrapper around the [`tronlink-signer`](tronlink-signer.md) SDK — it exposes the SDK's browser-based HITL signing flow as MCP tools. The two ship from the same monorepo and are released together (this page documents `mcp-tronlink-signer` v0.1.4, co-released with the matching `tronlink-signer` 0.1.x; see [Version & License](#version-license)). To embed signing directly in your own code rather than over MCP, use the [`tronlink-signer`](tronlink-signer.md) SDK. ## Which to use diff --git a/docs/llms-full.zh.txt b/docs/llms-full.zh.txt index bde76de..aebcc90 100644 --- a/docs/llms-full.zh.txt +++ b/docs/llms-full.zh.txt @@ -2,11 +2,11 @@ > 中文文档全文拼接，适合 LLM 一次性 ingest。由 scripts/gen_llms_full.py 生成。索引见 ../llms.txt 的 Localized 段。 -- Generated: 2026-05-29T08:48:03Z -- Commit: 1aed03bbd2cc +- Generated: 2026-05-29T09:27:31Z +- Commit: 16a8d8d4f105 - Language: zh - Pages: 23 -- Token estimate: ~41,563 (chars / 4) +- Token estimate: ~41,605 (chars / 4) --- @@ -716,7 +716,7 @@ img { ### 回调 `code` 枚举 -完整取值见上方[回传消息码](#回传消息码)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。 +完整取值见上方[回传消息码](#result-code)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。 --- @@ -1292,7 +1292,7 @@ interface SwitchTronChainParameter { ### TIP-6963（provider 发现） -事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#trontip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`： +事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#get-tronlink-provider-via-tip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`： - `TIP6963:requestProvider` —— 由 DApp 派发，无 payload。 - `TIP6963:announceProvider` —— 由已安装的每个钱包派发，`detail = { info: { uuid, name, icon, rdns }, provider }`。TronLink 的 `rdns = "org.tronlink.www"`、`name = "TronLink"`。 @@ -2741,7 +2741,7 @@ export TL_TRONGRID_URL="https://nile.trongrid.io" | 本地开发（一次性体验） | B — 自动创建 | 无需预配置，密码自动生成 | | 临时 demo 演示 | B + tmpfs 目录 | 把 `AGENT_WALLET_DIR` 指到任务结束即销毁的 tmpfs | -> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#钱包密钥存储)。 +> 路径 B（自动创建）会把生成的密码以明文写入 `~/.agent-wallet/runtime_secrets.json`，以便重启后复用同一钱包。完整的路径 A / 路径 B 对比及如何强制路径 A，见[钱包密钥存储](#wallet-secret-storage)。 ## 版本与许可证 @@ -3030,7 +3030,7 @@ interface GasFreeCapability { 所有工具使用 `tl_` 前缀，分为 13 个类别： -> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#精选工具-schema文档侧镜像) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。 +> **Schema SSOT。** 每个工具的 `inputSchema` 都由 [`src/mcp-server/schemas.ts`](https://github.com/TronLink/tronlink-mcp-core/blob/main/src/mcp-server/schemas.ts) 中的 Zod schema 生成，运行时通过 `list_tools` 暴露。下方表格只列**工具名 + 一句话描述**；参数类型、必填字段、枚举值和默认值请对运行中的 server 调用 `list_tools`，或直接读 Zod 源码。下游 [`mcp-server-tronlink` 页面](mcp-server-tronlink.md#selected-tool-schemas-inline-mirror) 为 7 个高影响工具（`tl_chain_send`、`tl_chain_swap_v3`、`tl_chain_stake`、`tl_multisig_submit_tx`、`tl_gasfree_send`、`tl_chain_get_account`、`tl_evaluate`）镜像了 JSON Schema——便于 agent 在没打开 MCP 会话时写调用站点。SSOT 仍然是本包。 ### 1. 会话管理（2 个） | 工具 | 说明 | @@ -3941,9 +3941,9 @@ tronlink-skills/ | 现象 | 原因 | 处理方式 | |------|------|----------| -| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#6) / [Skill ↔ MCP 工具映射](#skill--mcp) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | +| 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#the-6-skills) / [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | | TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#_1)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | -| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill--mcp)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | +| 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill-mcp-tool-map)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | | `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 | | 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add `），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 | @@ -4004,7 +4004,7 @@ Skills 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级 - **稳定契约**（minor / patch 不会动）： - 33 个 CLI 命令名与其必填 / 可选 flag（`tron_api.mjs [...]`）。 - - [Skill ↔ MCP 工具映射](#skill--mcp-工具映射) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。 + - [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 列出的 25 个 MCP 工具名（`tron_*` 形式）及其 `inputSchema` 字段名。 - Exit code：`0` 成功，`1` 查询错误 / 参数非法，`2` 未支持 / 未知命令。 - `Network Read` 副作用分级——任何命令未经 major 升级都不会变成 Remote Write。 - **不稳定契约**（minor 允许变化）： @@ -4025,7 +4025,7 @@ Skills 已进入 **v1.0.x**，适用标准 semver——只有 **major** 升级 将 [tronlink-signer](https://github.com/TronLink/mcp-tronlink-signer/tree/main/packages/tronlink-signer) 封装为 MCP 工具的服务器，供 Claude 及其他 AI 客户端使用。通过 TronLink 浏览器钱包对 TRON 交易进行签名，需用户在浏览器中授权确认 — 私钥始终留在钱包中，不会对外暴露。 -> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#版本与许可证)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。 +> **与 `tronlink-signer` 的关系。** 本服务器是对 [`tronlink-signer`](tronlink-signer.md) SDK 的轻量 MCP 封装 —— 它将该 SDK 基于浏览器的 HITL 签名流程以 MCP 工具的形式暴露出来。两者来自同一 monorepo，同步发布（本页文档对应 `mcp-tronlink-signer` v0.1.4，与之配套的是同期 `tronlink-signer` 0.1.x；见 [版本与许可证](#version-license)）。若希望将签名直接嵌入你自己的代码、而非经由 MCP 使用，请使用 [`tronlink-signer`](tronlink-signer.md) SDK。 ## 该用哪个 @@ -4201,7 +4201,7 @@ claude mcp add -s user tronlink-signer -- node /path/to/packages/mcp-tronlink-si > 「已发送 5 TRX——链上已确认（交易 `0a1b2c…`）。」 -> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#错误)）。 +> 请基于 `status` / `error.code` 分支,不要解析自然语言。`status: "pending"` 表示广播成功但确认超时——应用 `get_balance` 或浏览器查询对账,而不是重发(见[错误](#errors)）。 ## 取消 @@ -4234,7 +4234,7 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r |---|---|---| | **Prompt 注入** | 工具输入按原始值作为调用参数，server 不会再次提交给 LLM。TronLink 审批页渲染的是解析后的交易字段，不是 agent 的自由文本。 | 链上拿到的字符串（备注、revert 原因）视为不可信；分支应基于 `txId` / `status` / `code`，而非 prose。 | | **本地 HTTP listener** | 本地审批 server **仅绑定 `127.0.0.1`**（端口 `TRON_HTTP_PORT`，默认 3386，被占用时自增），永远不接受跨主机连接。每个 server session 有唯一 ID，前一次 session 的浏览器标签会被自动失效。 | 不要把 3386 端口转发到外网。同一台机器不要用相同 `TRON_HTTP_PORT` 跑两份。 | -| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#环境变量) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 | +| **出站 host 白名单（SSRF）** | signer 只与 [Networks](#environment-variables) 列出的 TronGrid 端点以及本地浏览器通信，工具不接受会被原样请求的用户 URL。 | 生产环境钉死 `TRON_NETWORK`、`TRON_API_KEY`。 | | **API key 处理（token passthrough）** | `TRON_API_KEY` 仅在启动时从 env 读取，仅用于到 TronGrid 的出站；**不**会出现在任何工具响应、错误 `details` 或 MCP resource 中。server 不接受 MCP 客户端传入的 Authorization header 并转发到上游。 | API key 放进 MCP host 的 secret manager，不要写进会提交 git 的 `mcpServers` 配置。 | | **签名必须 HITL** | 所有签名工具（`send_trx`、`send_trc20`、`sign_message`、`sign_typed_data`、`sign_transaction`）都会打开 TronLink 审批页，**不存在程序化绕过**。私钥始终留在 TronLink。 | 不需要运维额外强制 HITL——这是结构性保证。不要试图通过移除浏览器层来"加固"。 | | **浏览器标签劫持** | 审批页基于 server session ID 验证每次请求，过期的标签会被忽略；心跳检测会在断连时关闭 session。 | 同一用户跑多个 agent 时，请让每个 agent 启动自己的 signer 实例；跨实例的请求串扰由 session ID 屏蔽，但 UI 层混淆不防。 | @@ -4278,7 +4278,7 @@ server 返回的错误使用标准 MCP 信封结构，带稳定的 `code` 与 `r - **改进** —— 单页审批流：一个常驻浏览器标签 + 心跳检测；server 重启后旧标签自动失效。 - **改进** —— TRC20 金额校验改用 BigInt 小数转换（处理 0 位小数、>18 位小数等边界）。 - **改进** —— `send_trx`、`sign_transaction` 在提交失败时返回真实的 broadcast 错误，不再是空消息。 -- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#错误)）。 +- **迁移** —— 若你已经基于 `error.code` / `status` 分支，无需迁移；如有解析 message 文本，请立即切换（见 [错误](#errors)）。 #### v0.1.1 — 2026-04-15 @@ -4351,7 +4351,7 @@ await signer.stop(); ### `signer.sendTrx(to, amount, network?, options?): Promise` -向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#广播结果)）。 +向指定地址发送 TRX，会打开浏览器授权页面供用户确认。返回 `{ txId, status, error? }`，其中 `status` 为 `"success"`、`"pending"` 或 `"failed"`（参见[广播结果](#broadcast-result)）。 | 参数 | 类型 | 说明 | | ---- | ---- | ---- | @@ -4362,7 +4362,7 @@ await signer.stop(); ### `signer.sendTrc20(contractAddress, to, amount, decimals?, network?, options?): Promise` -发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#广播结果)。 +发送 TRC20 代币，会打开浏览器授权页面。返回 `{ txId, status, error? }` — 参见[广播结果](#broadcast-result)。 | 参数 | 类型 | 说明 | | ---- | ---- | ---- | @@ -4394,7 +4394,7 @@ const { signature } = await signer.signTypedData({ ### `signer.signTransaction(transaction, network?, broadcast?, options?): Promise<{ signedTransaction; txId?; status?; error? }>` -对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#广播结果)。 +对原始交易进行签名。当 `broadcast` 为 `true` 时，签名后的交易会通过 TronLink 广播到链上，且 SDK 会自动轮询链上确认状态 — 可能的 `status` 取值参见[广播结果](#broadcast-result)。 | 参数 | 类型 | 说明 | | ---- | ---- | ---- | @@ -4603,7 +4603,7 @@ export type { - **包：** `tronlink-signer` v0.1.4 - **许可证：** MIT —— `SPDX-License-Identifier: MIT` -- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#内联-changelog)，SDK 层跟随同一波次。 +- **变更记录 / 发布：** [https://github.com/TronLink/mcp-tronlink-signer/releases](https://github.com/TronLink/mcp-tronlink-signer/releases) —— 与 `mcp-tronlink-signer` 共用版本线；已发布 GitHub release：**v0.1.1、v0.1.2**（2026-04-15）。v0.1.3 / v0.1.4 截至当前仅 npm —— MCP 可见变更详见 [`mcp-tronlink-signer` 的内联 changelog](mcp-tronlink-signer.md#inline-changelog)，SDK 层跟随同一波次。 ### 兼容性与迁移策略 diff --git a/docs/llms.txt b/docs/llms.txt index b8e8036..3aee595 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,7 +2,7 @@ > TronLink is a decentralized wallet for the TRON ecosystem, available as a browser extension and a mobile app. This documentation covers integrating DApps with TronLink across the browser extension, the mobile app (via DeepLink), and AI/agent tooling (MCP servers, CLI, signer SDK). -> Updated: 2026-05-29T08:48:03Z · Commit: 1aed03bbd2cc +> Updated: 2026-05-29T09:27:31Z · Commit: 16a8d8d4f105 How integration works: TronLink injects a `window.tron` provider into every page, exposing a `tronWeb` instance, a `request` method, and `on` / `removeListener` for events. A DApp detects the wallet via TIP-6963, requests authorization via `eth_requestAccounts` (TIP-1102), then builds, signs, and broadcasts transactions through `tronWeb`. Account/network changes arrive as passive `accountsChanged` / `chainChanged` events. diff --git a/docs/llms.zh.txt b/docs/llms.zh.txt index 3dfc755..f1329a9 100644 --- a/docs/llms.zh.txt +++ b/docs/llms.zh.txt @@ -2,7 +2,7 @@ > TronLink 是 TRON 生态的去中心化钱包，提供浏览器扩展和移动 App。本文档涵盖 DApp 通过浏览器扩展、移动端（DeepLink）以及 AI/智能体工具链（MCP 服务、CLI、签名 SDK）与 TronLink 集成。 -> Updated: 2026-05-29T08:48:03Z · Commit: 1aed03bbd2cc +> Updated: 2026-05-29T09:27:31Z · Commit: 16a8d8d4f105 集成原理：TronLink 向页面注入 `window.tron` provider，暴露 `tronWeb` 实例、`request` 方法以及 `on` / `removeListener` 事件订阅。DApp 通过 TIP-6963 检测钱包，用 `eth_requestAccounts`（TIP-1102）请求授权，再经 `tronWeb` 构建、签名并广播交易。账户/网络变化以 `accountsChanged` / `chainChanged` 被动事件送达。 diff --git a/docs/mobile/deeplink.zh.md b/docs/mobile/deeplink.zh.md index 962ba87..38779c5 100644 --- a/docs/mobile/deeplink.zh.md +++ b/docs/mobile/deeplink.zh.md @@ -208,7 +208,7 @@ img { } ``` -## 回传消息码 +## 回传消息码 { #result-code } > 注意：转账请求中 `tokenId` 与 `contract` 互斥，两者同时传入会返回消息码 `10025`。 @@ -447,4 +447,4 @@ img { ### 回调 `code` 枚举 -完整取值见上方[回传消息码](#回传消息码)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。 +完整取值见上方[回传消息码](#result-code)表。请基于 `code`（integer）分支，**不要**解析 `message`（人类可读，可能会本地化）。 diff --git a/docs/plugin-wallet/active-requests.zh.md b/docs/plugin-wallet/active-requests.zh.md index d5a1dba..ef98f68 100644 --- a/docs/plugin-wallet/active-requests.zh.md +++ b/docs/plugin-wallet/active-requests.zh.md @@ -40,7 +40,7 @@ try { > **旧版用法（不推荐）：** [兼容用法：tron_requestAccounts](#tron_requestaccounts) -## 获取TronLink的provider TIP-6963 +## 获取TronLink的provider TIP-6963 { #get-tronlink-provider-via-tip-6963 } ### 简介 当多个钱包同时存在，会出现对 `window.tron` 对象的抢占行为。为了保证 DApp 可以获取到特定钱包的 provider，所以实现 TIP-6963 规范。 @@ -535,7 +535,7 @@ interface SwitchTronChainParameter { ### TIP-6963（provider 发现） -事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#trontip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`： +事件机制，**不是** `request` 方法。结构定义见上方 [获取TronLink的provider TIP-6963](#get-tronlink-provider-via-tip-6963) 的 TypeScript 接口；线上格式是两个 `CustomEvent`： - `TIP6963:requestProvider` —— 由 DApp 派发，无 payload。 - `TIP6963:announceProvider` —— 由已安装的每个钱包派发，`detail = { info: { uuid, name, icon, rdns }, provider }`。TronLink 的 `rdns = "org.tronlink.www"`、`name = "TronLink"`。 diff --git a/mkdocs.yml b/mkdocs.yml index 5744244..f949432 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -125,6 +125,7 @@ plugins: # Markdown 扩展（开启 mermaid 图表渲染） markdown_extensions: - admonition + - attr_list - pymdownx.details - pymdownx.superfences: custom_fences: diff --git a/scripts/gen_llms_full.py b/scripts/gen_llms_full.py index 060f944..fa63c21 100644 --- a/scripts/gen_llms_full.py +++ b/scripts/gen_llms_full.py @@ -136,6 +136,21 @@ def page_url(rel: str, lang: str) -> str: return f"{slug}/" +# Strips a trailing id-only attr_list block (e.g. ` { #errors }`) from an +# ATX heading. We add these to CJK headings so MkDocs emits a stable anchor +# (the default slugify drops CJK); they're build-time syntax, not prose, so +# the plain-text bundles shouldn't carry them. Deliberately narrow: only an +# `#id` block at end-of-line, so headings like `Promise<{ ... }>` are untouched. +HEADING_ATTR_ID_RE = re.compile(r"^(#{1,6}\s.*?)\s*\{:?\s*#[\w-]+\s*\}\s*$") + + +def strip_heading_anchor_ids(md: str) -> str: + """Drop ` { #id }` attr_list suffixes from heading lines in `md`.""" + return "\n".join( + (HEADING_ATTR_ID_RE.sub(r"\1", line) for line in md.splitlines()) + ) + + def render_bundle(pages: list[str], lang: str, sha: str, generated_at: str) -> tuple[str, int, list[str]]: """Return (full_text, page_count, missing) for one language.""" body_parts: list[str] = [] @@ -149,7 +164,7 @@ def render_bundle(pages: list[str], lang: str, sha: str, generated_at: str) -> t body_parts.append("") body_parts.append(f"") body_parts.append("") - body_parts.append(path.read_text(encoding="utf-8").rstrip()) + body_parts.append(strip_heading_anchor_ids(path.read_text(encoding="utf-8").rstrip())) body_parts.append("") body = "\n".join(body_parts) From 34cbabfb2e0d617ae49d45a4606016e457092257 Mon Sep 17 00:00:00 2001 From: Yuki Xue Date: Mon, 1 Jun 2026 15:43:07 +0800 Subject: [PATCH 08/10] chore: drop internal-only files and revert preview branch trigger - remove plugin-wallet-refactor-plan.md (internal planning doc) - remove ai-readability-review.md (internal external review report) - revert gh-pages.yml so only main triggers deploy (preview line for docs/review-fixes was for local dev only) Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/gh-pages.yml | 1 - ai-readability-review.md | 140 ----------------- plugin-wallet-refactor-plan.md | 275 --------------------------------- 3 files changed, 416 deletions(-) delete mode 100644 ai-readability-review.md delete mode 100644 plugin-wallet-refactor-plan.md diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 130d744..eafa8b9 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -4,7 +4,6 @@ on: push: branches: - main - - docs/review-fixes workflow_dispatch: # 仍保留手动触发的功能 jobs: diff --git a/ai-readability-review.md b/ai-readability-review.md deleted file mode 100644 index 2865810..0000000 --- a/ai-readability-review.md +++ /dev/null @@ -1,140 +0,0 @@ -# TronLink 开发者文档 · AI 可读性评估与优化报告 - -- **评估对象**：https://docs.tronlink.org/ （EN/ZH 双语，mkdocs-material） -- **评估视角**：以「agent 能否稳定发现 / 解析 / 调用 / 判断失败」为标准的区块链开发者 AI -- **评估基线**：AI Agent 文档标准包 V1.0（项目级覆盖度 20% + 文档质量 80%） -- **评估日期**：2026-05-29 ｜ 文档快照：commit `e724781c635f`，生成于 `2026-05-21T14:08:15Z` - -## 一句话结论 - -> 这是极少数「为 AI 而设计」而不是「顺便能被 AI 读」的钱包文档。综合评级 **A（8.3 / 10）**：AI 入口、MCP、错误码联表、安全披露均为范本级别。剩余问题集中在「最后一公里」工程化：**机器可读契约文件缺失、逐页 raw markdown 缺失、错误矩阵有空洞、License / 版本治理缺位**。补齐后可冲 S。 - ---- - -## 一、做得非常好的地方 - -| 维度 | 证据 | 为什么对 AI 重要 | -|---|---|---| -| AI 入口索引 | 根目录有 `llms.txt`（真·纯文本），含 commit SHA、UTC 时间戳、网络 chainId、「集成原理」摘要、按导航顺序的全站索引；并有 `llms-full.txt` 单次拉取全量（23 页 ≈ 57k tokens），EN/ZH 双份 | agent 一次 fetch 即可建立全局心智，无需爬 51 个 URL | -| 明确的 agent 立场 | `ai-support/ai-llms` 声明文档面向 "retrieval / RAG / inference-time grounding"，并给 "Notes for agents"：从 `llms.txt` 入手、按 error code 分支而非 message、签名需用户批准、优先 testnet | 教科书式 agent 引导，多数项目完全没有 | -| 错误码横向联表 | `reference/error-code-map` 把 DApp(EIP-1474) / DeepLink(5 位) / MCP(`TL_*`) / CLI(exit code) 按「业务含义」对齐，并标 `Retryable` | 让 agent 跨 4 个调用面用同一套语义分支，SSOT 思想到位 | -| MCP 文档深度 | stdio transport、55 个 tool、JSON Schema Draft-7 示例、Zod 运行时校验、`list_tools` 为权威源、统一 error 包络（`error.code/retryable/details` + `meta.schemaVersion`）、`.mcp.json` 配置、高危工具（`tl_evaluate`）禁用指引 | 达到 MCP 标准 9 分锚点 | -| 安全披露诚实 | 明确区分 Direct-API（本地签名直接广播，无 HITL）vs Playwright/Signer（浏览器内人工批准）；标注 swap 的 MEV/滑点风险、必须 bound minimum-output；多签密钥轮换/最小权限 | 副作用等级、确认机制、风险隔离全覆盖 | -| Provider 契约 | `window.tron` 给了 TypeScript interface；TIP-6963 发现、`eth_requestAccounts`(TIP-1102)、TIP-3326 切链、`chainChanged` 等都有 JSON Schema 入参 | 比多数 EVM 钱包文档严谨 | -| 网络参考可拷贝 | mainnet/Shasta/Nile 的 hex chainId + EVM 十进制 + RPC + explorer + faucet + USDT 合约 + TRX/SUN 单位，全部表格化 | agent 直接抽字段 | - ---- - -## 二、扣分项与优化建议（按优先级） - -### P0 — 影响 agent 稳定自动化 - -**P0-1　契约机器可读性分三个断层，provider RPC 是真缺口** - -核实源码后，schema 并非笼统「埋在散文里」，而是三档成熟度断层： - -| 调用面 | 机器可读性 | SSOT | -|---|---|---| -| MCP tools | 内联 JSON Schema，但仅镜像 **7/55** 个 tool、仅顶层字段 | 🟢 上游 Zod（`tronlink-mcp-core/src/mcp-server/schemas.ts`）+ CI 对账（`scripts/check_doc_schema_parity.py`） | -| Provider RPC（`window.tron`） | ❌ **无 per-method schema**：参数=JS 示例，返回=散文，错误=Markdown 表 | 🔴 无，手写 | -| 错误码 | 四方言联表，`Retryable` 独立列 | 🟡 `TL_*` 在 `tronlink-mcp-core` | - -因此 P0-1 按调用面拆级： - -- **Provider RPC = 真 P0**：DApp 开发者最高频的面，却零结构化契约，`request(): Promise` + 散文返回（"an array is returned with a single element"），agent 只能靠英文句子推断 I/O。 -- **MCP tools = P1（比初判轻）**：SSOT（Zod）与对账 CI 已就位，差的只是覆盖率（7/55）+ 把 schema 作为独立文件发布 + 嵌套全量。 -- **错误码 = P1（最便宜）**：一张干净的表 → 一份 `error-codes.json`，近乎零成本。 - -关键：补契约是「顺手」而非「工程」，流水线与数据源都已就位： - -- `error-codes.json`：`scripts/gen_llms_full.py` 已在 build 时按 nav 顺序遍历全部页面，顺带解析 error-code-map 那张表（行=业务含义，retryable 已是独立列）输出 JSON 即可。 -- `mcp-tools.json`：**不要手写**，应由上游用 `zod-to-json-schema` 把 Zod SSOT 导出为 release artifact，docs 站点链接/代理它——一步同时解决「7/55 覆盖率」与「仅顶层字段」两个老问题。 -- `provider-methods.json`：provider 侧目前零结构，最该补；可参考 MCP 那套对账思路新增可校验 schema，或至少把每个方法返回从散文升级成具体类型。 - -再评估「`list_tools` 才是权威」：对**已连 MCP** 的 agent 成立，但 `llms.txt` 宣称的受众是**读文档 / RAG** 的 agent，它调不到 `list_tools`、只能读到 7/55——**权威源恰好对宣称服务的人群不可达**。这正是覆盖度标准「OpenAPI / API 契约」项目前只能给 ~7 分（而非 9 分）的精确原因。 - -**P0-2　逐页没有 raw markdown 入口** - -现状：每页是 HTML；想要单页纯文本，要么解析 HTML，要么下载 57k token 的整包 `llms-full.txt`。 - -- 建议：每页额外暴露 `*.md`（mkdocs 配 `?plain` 或部署 `.md` 镜像）。`llms-full.txt` 已用 `` 分隔，把该 source 路径做成可直接拉取的 raw md 即闭环。 - -**P0-3　错误矩阵有空洞 + 重试语义含糊** - -现状：联表大量 `—`（多数 DApp provider 行无 DeepLink/MCP/CLI 对应）；`active-requests` 中 `tronweb.trx.sign / multiSign / signMessageV2 / wallet_watchAsset` 的 Error Codes 列为空；`Timeout=Maybe`、`Internal=Yes(once)` 对 agent 不可执行。 - -- 建议：① 补全每个方法的错误码；② 把「Maybe/once」量化成可执行策略（max attempts、backoff、是否需先 `waitForTransaction` 对账再重试）——对应「有副作用操作不得自动重试，除非证明幂等」。 - -### P1 — 影响接入信任与可维护性 - -**P1-1　robots.txt 是「允许检索、拒绝训练」的合理姿态，但有两个实操坑** - -现状（逐行核对）：`Content-Signal: search=yes,ai-train=no`；Disallow 了 `ClaudeBot, GPTBot, Google-Extended, CCBot, Bytespider, Amazonbot, Applebot-Extended, meta-externalagent, CloudflareBrowserRenderingCrawler`；而 `Claude-User / Claude-SearchBot / OAI-SearchBot / ChatGPT-User` 未被封。 - -- 该姿态逻辑自洽（封训练爬虫、放行实时检索 UA），与 `ai-llms` 页「面向 inference-time grounding 而非训练」一致，值得肯定。 -- 坑 1：靠「没写 Disallow」放行检索 UA，而非显式 `Allow`。建议显式 `Allow` 关键检索 UA 并复核 `PerplexityBot / Googlebot / Bingbot / Applebot(非 Extended)` 未被误伤；注意 `Google-Extended` 被封会同时削弱 Gemini 的 grounding，不只训练。 -- 坑 2：用通用/被封 UA 抓取的 RAG 管线会吃 403 且静默丢内容。建议把 UA 政策写进 `ai-llms` 页，并考虑 `llms.txt/llms-full.txt` 对所有 UA 放行。 - -**P1-2　Direct-API 的密钥默认路径偏危险** - -现状：Direct-API 工具本地签名直接广播，仅靠 `AGENT_WALLET_PASSWORD` 把关；`tl_wallet_create` 自动路径会把明文密码写入 `~/.agent-wallet/runtime_secrets.json`。已有警告，但把「明文密钥落盘」作为一等公民路径披露，风险偏高。 - -- 建议：警告升级为显著 admonition；自动创建路径明确标 test-only；生产路径首选 `mcp-tronlink-signer`（浏览器批准）。 - -**P1-3　License / SPDX 缺失** - -未见文档声明 license。standards 要求所有文档声明 license。 - -- 建议：`llms.txt` 头部与页脚加 SPDX（文档 `CC-BY-4.0`，SDK/CLI `MIT` 或 `Apache-2.0`）。 - -**P1-4　版本治理缺一页** - -`llms.txt` 有 commit+时间戳（很好），但 pre-1.0 稳定性承诺散落在 MCP 页，没有统一 CHANGELOG / 版本兼容页，每页也未标「适用于扩展/SDK 哪个版本」。 - -- 建议：加 `reference/changelog`，并在每页 frontmatter 标注 `applies-to` 版本。 - -### P2 — 完整度 / 体验 - -- **P2-1　Provider 返回类型过松**：`request(): Promise`、`tronWeb: TronWeb|false`。`any` 让 agent 只能靠 prose 推断返回形状。建议每方法给具体返回类型（提炼进 P0-1 的契约文件）。 -- **P2-2　i18n 平价破例**：sitemap 显示 `zh/asset_filter_logic/` 无 EN 对应页，违背「同 slug 即翻译对」不变式。建议补 EN 或在 zh 索引说明这是中文专属。 -- **P2-3　MCP 无 resources/prompts**：若不提供可在页面标 N/A（避免误判遗漏）。stdio-only 也建议显式声明「暂不提供 HTTP/SSE transport」。 -- **P2-4　首页缺机器发现提示**：HTML `` 加指向 `llms.txt` 的 ``/meta，让未读约定的爬虫也能发现入口。 - ---- - -## 三、评分卡（对照 standards 项目级覆盖度） - -| 评分项 | 权重 | 得分 | 主要依据 / 扣分点 | -|---|---:|---:|---| -| AI 入口索引 | 20% | 9.3 | `llms.txt`+`llms-full.txt`+双语+agent notes+commit/时间戳，范本级 | -| OpenAPI / API 契约 | 20% | 7.0 | provider RPC 无 per-method schema（P0）；MCP 仅 7/55 且未发布为独立文件（P1） | -| MCP 文档 | 20% | 9.0 | 极完整；扣分于无 resources/prompts 说明、stdio-only 未显式声明、全集靠 `list_tools` | -| Skills 文档 | 15% | 8.0 | 入口与能力齐全（未深读，按列示与联表推断） | -| CLI 文档 | 10% | 8.0 | 有命令面 + exit code 进联表 | -| 互链与 SSOT | 15% | 9.0 | 错误码联表 + `llms.txt` 全互链 + schemaVersion；扣分于矩阵空洞与 i18n 破例 | -| **项目级覆盖度** | 100% | **≈ 8.4 (A-)** | | -| 文档质量（安全/错误/示例/版本/License 综合） | — | **≈ 8.3 (A-)** | 强在安全披露与示例，弱在 License/版本/逐页 raw md | -| **综合** | — | **8.3 / A** | 距 S（9.0）差「机器可读契约 + raw md + 错误矩阵补全 + License/版本治理」 | - ---- - -## 四、最小行动清单（按性价比排序） - -1. 发 4 个机器可读文件并在 `llms.txt` 链接：`provider-methods.json`、`mcp-tools.json`、`error-codes.json`、`*.d.ts`。（解 P0-1，覆盖度 7→9） -2. 每页 raw `.md` 镜像，复用现有 `` 路径。（解 P0-2） -3. 补全错误矩阵 + 量化重试（max attempts/backoff/对账）。（解 P0-3） -4. robots：显式 Allow 检索 UA + 在 ai-llms 页写明 UA 政策；复核 Perplexity/Google-Extended 影响。（解 P1-1） -5. 加 License/SPDX + CHANGELOG + 每页 applies-to 版本。（解 P1-3/P1-4） -6. 把明文密钥落盘路径降级为 test-only admonition。（解 P1-2） - ---- - -## 附：数据可信度说明 - -具体取值（signer 端口 3386、57k token、各 schema 字段）来自对线上页面的抓取摘要；结构性结论已被多个页面（`llms.txt` ↔ 错误码表 ↔ MCP 页）交叉印证，可信度高。个别精确数值（重试次数、端口）建议落地前对照源仓库 `scripts/gen_llms_full.py` 与 `mkdocs.yml` 复核。 - -注：初版 P0-1 曾引用一段 `eth_requestAccounts` 的 JSON Schema，经核对源码 `docs/plugin-wallet/active-requests.en.md`，该 schema 实为 WebFetch 摘要模型臆造——真实页面只有 JS 示例 + 散文返回 + 错误码表。结论性判断一律以本地源文件为准，不采信二次摘要。 - ---- - -*评审基线：`/Users/tron/Downloads/standards`（AI Agent 文档标准包 V1.0）。本报告由挑剔视角的 AI 评审生成，仅覆盖「AI 可读性」维度。* diff --git a/plugin-wallet-refactor-plan.md b/plugin-wallet-refactor-plan.md deleted file mode 100644 index 2803067..0000000 --- a/plugin-wallet-refactor-plan.md +++ /dev/null @@ -1,275 +0,0 @@ -# /plugin-wallet 推荐用法迁移方案 - -> **状态：** 方案已锁版，可执行。决策汇总见 §三；中文标题锚点对策见 §4.2。 - -## 背景 - -`window.tron`（TIP-1193 provider）已成为 TronLink 的推荐接入入口，旧的 `window.tronLink` / `tronLink.tronWeb` / `tronLink.request` 仍作为兼容别名保留但不再推荐。 - -`/dapp` 子站已在前一轮改造中完成切换（commit `fb3cc8b`）。本方案处理 `/plugin-wallet` 下的文档对齐。 - -## 范围 - -- `docs/plugin-wallet/active-requests.zh.md` -- `docs/plugin-wallet/active-requests.en.md` -- `docs/plugin-wallet/passive-messages.zh.md` -- `docs/plugin-wallet/passive-messages.en.md` - -`ledger-signing-update.{zh,en}.md` 不涉及 provider，不动。 - -## 总体原则 - -1. **每篇文档主体只展示推荐用法（`window.tron`）。** -2. **每篇文档底部统一新增"旧版用法（不推荐）"区，集中放置 `window.tronLink` 等兼容用法。** -3. **新版的每个具体接口小节，末尾以一行 blockquote callout 链接到底部对应的旧版条目。** -4. **不删除任何旧 API 文档信息，只是搬位 + 重新组织。** - ---- - -## 一、active-requests 改造 - -### 1.1 当前结构与处理对照 - -| # | 当前小节 | 当前 API | 处理动作 | -|---|---|---|---| -| 1 | 连接网站 TIP-1102 | 新 `tron.request` | 保留为主版，末尾加旧版链接 | -| 2 | 连接网站（旧版）`tron_requestAccounts` | 旧 | **整段移到底部"旧版用法"区** | -| 3 | 获取 provider TIP-6963 | 新 | 保留，不动 | -| 4 | 普通转账 | 旧 `window.tronLink.ready` | **重写为新版**；原旧版代码片段拆出搬到底部 | -| 5 | 多签转账 | 旧 | 同上 | -| 6 | 消息签名 | 旧 | 同上 | -| 7 | 添加资产 | 主示例新 / 三个子例旧 | 子例改为 `window.tron.request`；原旧代码搬到底部 | -| 8 | 切换网络 TIP-3326 | 旧 `tronLink.request` | 改为 `window.tron.request`；旧版搬到底部 | - -### 1.2 目标骨架 - -``` -# 主动请求TronLink插件功能 - -### 连接网站 TIP-1102 -… 现有内容 … -> **旧版用法（不推荐）：** [兼容用法：tron_requestAccounts](#tron_requestaccounts) - -### 获取TronLink的provider TIP-6963 -（不动） - -### 普通转账 -> **前提条件：** 已通过 `eth_requestAccounts` 完成 DApp 连接授权（参见上方 [连接网站 TIP-1102](#tip-1102)）。 -（代码改为 `const tronweb = window.tron.tronWeb; …`，去掉 `if (window.tronLink.ready)` 包裹） -> **旧版用法（不推荐）：** [兼容用法：sendTrx（window.tronLink）](#sendtrx-window-tronlink) - -### 多签转账 -（前提条件 + 新代码 + 链接到旧版） - -### 消息签名 -（同上） - -### 添加资产 -（主示例已是新 API；TRC10/20/721 三个子例去掉 if 包裹，改 `window.tron.request`） -> **旧版用法（不推荐）：** [兼容用法：wallet_watchAsset（window.tronLink）](#wallet_watchasset-window-tronlink) - -### 切换网络 TIP-3326 -（代码改为 `await window.tron.request(...)`） -> **旧版用法（不推荐）：** [兼容用法：wallet_switchEthereumChain（tronLink.request）](#wallet_switchethereumchain-tronlinkrequest) - ---- - -## 旧版用法（不推荐） - -下列接口作为兼容别名保留，新接入请使用上方推荐用法。`window.tronLink` 与 `window.tron` 在功能上等价，但前者将逐步不再维护。 - -### 兼容用法：tron_requestAccounts -（搬自原"连接网站（旧版）"整段） - -### 兼容用法：sendTrx（window.tronLink） -（搬自原"普通转账"代码示例） - -### 兼容用法：multiSign（window.tronLink） -… - -### 兼容用法：signMessageV2（window.tronLink） -… - -### 兼容用法：wallet_watchAsset（window.tronLink） -（搬自原"交互流程"下三个 TRC 子例） - -### 兼容用法：wallet_switchEthereumChain（tronLink.request） -（搬自原"切换网络"代码示例） -``` - -### 1.3 锚点策略 - -MkDocs 默认 slug 会剥掉中文，保留 ASCII token 用 `-` 拼接、转小写、保留下划线。可在标题里以"兼容用法："形式预埋稳定锚点： - -| 中文标题 | 生成 slug | -|---|---| -| `### 兼容用法：tron_requestAccounts` | `tron_requestaccounts` | -| `### 兼容用法：sendTrx（window.tronLink）` | `sendtrx-window-tronlink` | -| `### 兼容用法：multiSign（window.tronLink）` | `multisign-window-tronlink` | -| `### 兼容用法：signMessageV2（window.tronLink）` | `signmessagev2-window-tronlink` | -| `### 兼容用法：wallet_watchAsset（window.tronLink）` | `wallet_watchasset-window-tronlink` | -| `### 兼容用法：wallet_switchEthereumChain（tronLink.request）` | `wallet_switchethereumchain-tronlinkrequest` | - -英文版用 `### Legacy: ` 形式，slug 形如 `legacy-tron_requestaccounts`、`legacy-sendtrx-via-windowtronlink` 等。 - -### 1.4 callout 文案 - -新版小节末尾统一插入： - -**中文：** -```markdown -> **旧版用法（不推荐）：** [兼容用法：sendTrx（window.tronLink）](#sendtrx-window-tronlink) -``` - -**英文：** -```markdown -> **Legacy (not recommended):** [Legacy: sendTrx via window.tronLink](#legacy-sendtrx-via-windowtronlink) -``` - -前提条件 callout（覆盖普通转账 / 多签转账 / 消息签名 / 添加资产，共 4 节；切换网络不加）： - -**中文：** -```markdown -> **前提条件：** 已通过 `eth_requestAccounts` 完成 DApp 连接授权（参见上方 [连接网站 TIP-1102](#tip-1102)）。 -``` - -**英文：** -```markdown -> **Prerequisite:** The DApp connection has been authorized via `eth_requestAccounts` (see [Request to connect website TIP-1102](#request-to-connect-website-tip-1102) above). -``` - -> 切换网络不需要预先授权，**不加**"前提条件"callout。 - ---- - -## 二、passive-messages 改造 - -### 2.1 现状 - -主体已基于 `window.tron`，底部已有两块旧版区域： - -- **历史遗留问题**：postMessage 派发的 `connectWeb` / `acceptWeb` / `rejectWeb` / `disconnectWeb`（3.x 兼容事件，未来会废弃）。 -- **已废弃的 3.x 事件**：`tabReply` / `setAccount` / `setNode`（主链 / 侧链检测）。 - -### 2.2 两种处理方案 - -**方案 A（推荐 · 最小变更）** - -- 保留现有两个旧版区结构（4.x postMessage 兼容 vs 3.x 主侧链）。 -- 在新版的 `accountsChanged` / `chainChanged` / `connect` / `disconnect` 四个小节末尾各加一行 callout，链接到对应的旧版条目。 -- 顶部 demo 代码块（HTML 示例）保持不动。 - -新→旧映射建议： - -| 新版事件 | 旧版对应（链接目标） | -|---|---| -| `accountsChanged` | `setAccount`（3.x） | -| `chainChanged` | `setNode` / `tabReply`（3.x） | -| `connect` | `connectWeb` / `acceptWeb`（postMessage） | -| `disconnect` | `disconnectWeb` / `rejectWeb`（postMessage） | - -**方案 B（彻底对齐 active-requests）** - -把两个旧版区合并成单一"## 旧版用法（不推荐）"大区，内部再分子小节。 - -**结论：选 A。** 现有两个旧版区主题不同（兼容事件 vs 3.x 主侧链），强行合并反而模糊。结构基本不动，只补 callout 链接。 - ---- - -## 三、确认事项（已锁定） - -| # | 项 | 决定 | -|---|---|---| -| 1 | 前提条件 callout 覆盖范围 | 转账 / 多签 / 消息签名 / **添加资产**（共 4 节）；切换网络不加 | -| 2 | callout 措辞 | `**旧版用法（不推荐）：**` | -| 3 | passive-messages | 方案 A（保留两块旧版区，新版小节补链接） | -| 4 | TIP-1102 是否链旧版 | 链到 `兼容用法：tron_requestAccounts` | -| 5 | 旧版区开篇说明 | 一两句简短说明（"作为兼容别名保留，新接入请使用上方推荐用法。`window.tronLink` 与 `window.tron` 在功能上等价，但前者将逐步不再维护。"） | - ---- - -## 四、已知风险与对策（执行前必读） - -### 4.1 风险：纯中文 `###` 标题的锚点不可靠 - -`普通转账` / `多签转账` / `消息签名` / `添加资产` 这 4 个小节标题全是中文，mkdocs 默认 slug 会剥到空串，被自动加上 `_1`、`_2` 等位置 fallback。现有文件里的 `[普通转账](#_13)` 就是这种情况 —— 数字 `13` 是页面内累计的空 slug 计数器，**不能在文件重排后稳定预测**。 - -这会影响： - -- 新版小节里"参见上方 [普通转账]" / "参见上方 [多签转账]" 等回链 -- 底部"旧版用法"区的"新接入请使用上方 [普通转账]"等回链 -- TIP-1102 顶部如果想链到任何一节，同样有问题 - -> 注：`TIP-1102` / `TIP-6963` / `TIP-3326` 这几节标题混了 ASCII，slug 可稳定预测为 `#tip-1102` / `#tronlinkprovider-tip-6963` / `#tip-3326`，不受影响。 - -### 4.2 对策（三选一，请挑选） - -**对策 A：给纯中文小节标题加 ASCII 方法名后缀（推荐）** - -改为： -- `### 普通转账 sendTrx` → slug `sendtrx` -- `### 多签转账 multiSign` → slug `multisign` -- `### 消息签名 signMessageV2` → slug `signmessagev2` -- `### 添加资产 wallet_watchAsset` → slug `wallet_watchasset` - -优点：slug 完全可控；标题里直接显示方法名对开发者也是好事；跟既有 `获取TronLink的provider TIP-6963` 这种"中英混合标题"风格一致。 -缺点：每个小节标题变长一截，视觉略变化。 - -**对策 B：不在新版小节之间互链，纯中文方位词描述** - -如"参见上方「普通转账」"，不写 markdown 链接。 - -优点：标题不动。 -缺点：放弃了点击跳转的便利；侧栏 / 目录里的"普通转账"虽然可点击，但行文中没有热区。 - -**对策 C：跑一次 mkdocs build，把生成的真实 slug 反写回链** - -优点：保留中文标题。 -缺点：必须先 build 一遍；任何后续小节顺序变化都会让 `_N` 编号漂移，长期维护成本高；放弃了"自描述性"。 - -**已确认：对策 A。** 4 个纯中文小节标题改为： - -- `### 普通转账 sendTrx`（slug `sendtrx`） -- `### 多签转账 multiSign`（slug `multisign`） -- `### 消息签名 signMessageV2`（slug `signmessagev2`） -- `### 添加资产 wallet_watchAsset`（slug `wallet_watchasset`） - -### 4.3 旧版区标题的锚点 - -旧版区的标题都预埋了 ASCII 方法名（`### 兼容用法：tron_requestAccounts` 等），slug 可控（见 §1.3 表）。**不受 4.1 影响。** - -### 4.4 跨页引用检查 - -仓库内只有 2 处对 `active-requests.md#xxx` 锚点的跨页引用，且都指向 TIP-6963 小节（slug `tronlinkprovider-tip-6963` / `get-tronlink-provider-via-tip-6963`），本次方案 **不动这个小节**，不会断链： - -``` -docs/plugin-wallet/passive-messages.zh.md:93 → #tronlinkprovider-tip-6963 -docs/plugin-wallet/passive-messages.en.md:93 → #get-tronlink-provider-via-tip-6963 -``` - ---- - -## 五、执行步骤（确认对策 A/B/C 后开工） - -1. `active-requests.zh.md` 重排： - - 删除原"连接网站（旧版）"小节，整段搬到底部"旧版用法"区 - - 4 个业务小节（普通转账 / 多签转账 / 消息签名 / 添加资产）： - - 按对策 A/B/C 处理小节标题 - - 顶部插入"前提条件" callout - - 代码改为 `const tronweb = window.tron.tronWeb; …`，去 `if (window.tronLink.ready)` 包裹 - - 末尾插入"旧版用法（不推荐）"链接 callout - - 切换网络小节：代码改为 `window.tron.request(...)`；末尾加旧版链接；不加前提条件 - - TIP-1102 小节末尾加旧版链接（指向 `兼容用法：tron_requestAccounts`） - - 文末新增 `## 旧版用法（不推荐）` 大区，下设 6 个 `###` 兼容用法子节 -2. `active-requests.en.md` 同步以上改动（英文标题天然有 ASCII slug，不涉及对策 A/B/C 取舍） -3. `passive-messages.zh.md` 4 个事件小节（accountsChanged / chainChanged / connect / disconnect）末尾各加一行旧版 callout，链接到对应 postMessage / 3.x 子节 -4. `passive-messages.en.md` 同步 -5. 本地 `mkdocs serve` 校验全部站内锚点跳转可用，无 404 -6. 一次性 commit：`migrate plugin-wallet docs to window.tron and isolate legacy usage` - -## 六、影响面 - -- **不破坏现有接入**：旧 API 用法全部保留在底部"旧版用法"区，搜索引擎与现有外链可继续命中。 -- **mkdocs.yml 不需要改**：导航条目数量不变；不引入 admonition 等新扩展。 -- **跨页引用**：见 §4.4，无断链风险。 -- **未涉及 mobile 端**：移动端 DApp 注入逻辑不同，本次不动。 From a08525609c43edda998f0645a51528678df72287 Mon Sep 17 00:00:00 2001 From: Yuki Xue Date: Thu, 4 Jun 2026 13:02:10 +0800 Subject: [PATCH 09/10] docs: fix ZH skills troubleshooting link to Configuration (#configuration) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new troubleshooting table linked to #_1, a positional auto-anchor. With the default slugify dropping CJK, #_1 resolves to the first empty-slug heading (## 概述 / Overview) — not ## 配置说明. Give the Configuration heading an explicit attr_list id and point the link at it so it stays stable across heading edits. Matches the EN side, which already uses a stable anchor. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ai-support/tronlink-skills.zh.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ai-support/tronlink-skills.zh.md b/docs/ai-support/tronlink-skills.zh.md index 2413597..f2885bf 100644 --- a/docs/ai-support/tronlink-skills.zh.md +++ b/docs/ai-support/tronlink-skills.zh.md @@ -420,7 +420,7 @@ bash uninstall.sh --- -## 配置说明 +## 配置说明 { #configuration } ### 环境变量 @@ -532,7 +532,7 @@ tronlink-skills/ | 现象 | 原因 | 处理方式 | |------|------|----------| | 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#the-6-skills) / [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | -| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#_1)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | +| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#configuration)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | | 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill-mcp-tool-map)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | | `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 | | 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add `），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 | From 266a23fc4da73730414eef7371aa2d2a0647a2f9 Mon Sep 17 00:00:00 2001 From: Yuki Xue Date: Thu, 4 Jun 2026 15:07:06 +0800 Subject: [PATCH 10/10] docs: drop USDD from Skills built-in token shortcuts (code whitelist only) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Built-In Token Shortcuts" table documents the symbols tron_api.mjs recognizes as aliases for contract addresses, but the SSOT-reconcile pass added a USDD row the code does not recognize — then footnoted that it must be passed by address anyway. That contradicts the table's purpose: an agent scanning it would call symbol "USDD" and fail. Make the table strictly equal the code whitelist (TRX/USDT/USDC/WTRX/BTT/ JST/SUN/WIN) and rewrite the note to point unlisted tokens (e.g. USDD) to the networks SSOT for their address. USDD stays in the networks SSOT and CLI reference tables (those are address catalogs, not symbol whitelists). Regenerated llms-full bundles. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ai-support/tronlink-skills.en.md | 3 +-- docs/ai-support/tronlink-skills.zh.md | 3 +-- docs/llms-full.en.txt | 9 ++++----- docs/llms-full.txt | 9 ++++----- docs/llms-full.zh.txt | 11 +++++------ docs/llms.txt | 2 +- docs/llms.zh.txt | 2 +- 7 files changed, 17 insertions(+), 22 deletions(-) diff --git a/docs/ai-support/tronlink-skills.en.md b/docs/ai-support/tronlink-skills.en.md index cbf2d66..4e6dfa4 100644 --- a/docs/ai-support/tronlink-skills.en.md +++ b/docs/ai-support/tronlink-skills.en.md @@ -452,14 +452,13 @@ export TRON_NETWORK="mainnet" # or "shasta" / "nile" ### Built-In Token Shortcuts -> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The shortcuts below are reconciled to that SSOT. The symbols recognized by `tron_api.mjs` are TRX, USDT, USDC, WTRX, BTT, JST, SUN, WIN; USDD is included below for consistency with the SSOT — pass its contract address explicitly. +> The symbols below are the ones `tron_api.mjs` recognizes as shortcuts for their contract addresses. For any token not listed here (e.g. USDD), look up its address in [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot) and pass it explicitly. | Symbol | Contract Address | |--------|------------------| | TRX | Native (no contract) | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | -| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | diff --git a/docs/ai-support/tronlink-skills.zh.md b/docs/ai-support/tronlink-skills.zh.md index f2885bf..30a425e 100644 --- a/docs/ai-support/tronlink-skills.zh.md +++ b/docs/ai-support/tronlink-skills.zh.md @@ -452,14 +452,13 @@ export TRON_NETWORK="mainnet" # 或 "shasta" / "nile" ### 内置代币快捷符号 -> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下方快捷符号已对齐该 SSOT。`tron_api.mjs` 实际内置可识别的符号为 TRX、USDT、USDC、WTRX、BTT、JST、SUN、WIN；USDD 为与 SSOT 保持一致而一并列出——请显式传入其合约地址使用。 +> 下表为 `tron_api.mjs` 内置、可直接用符号名代替合约地址的代币。未列出的代币（如 USDD）请在 [reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot) 查询地址并显式传入。 | 符号 | 合约地址 | |------|----------| | TRX | 原生代币（无合约） | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | -| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | diff --git a/docs/llms-full.en.txt b/docs/llms-full.en.txt index 70eadd3..e9e8919 100644 --- a/docs/llms-full.en.txt +++ b/docs/llms-full.en.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T09:27:31Z -- Commit: 16a8d8d4f105 +- Generated: 2026-06-04T07:06:28Z +- Commit: a08525609c43 - Language: en - Pages: 23 -- Token estimate: ~60,360 (chars / 4) +- Token estimate: ~60,333 (chars / 4) --- @@ -3980,14 +3980,13 @@ export TRON_NETWORK="mainnet" # or "shasta" / "nile" ### Built-In Token Shortcuts -> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The shortcuts below are reconciled to that SSOT. The symbols recognized by `tron_api.mjs` are TRX, USDT, USDC, WTRX, BTT, JST, SUN, WIN; USDD is included below for consistency with the SSOT — pass its contract address explicitly. +> The symbols below are the ones `tron_api.mjs` recognizes as shortcuts for their contract addresses. For any token not listed here (e.g. USDD), look up its address in [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot) and pass it explicitly. | Symbol | Contract Address | |--------|------------------| | TRX | Native (no contract) | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | -| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | diff --git a/docs/llms-full.txt b/docs/llms-full.txt index 70eadd3..e9e8919 100644 --- a/docs/llms-full.txt +++ b/docs/llms-full.txt @@ -2,11 +2,11 @@ > Concatenation of all English documentation pages for single-fetch LLM ingestion. Generated by scripts/gen_llms_full.py. See ./llms.txt for the curated index. -- Generated: 2026-05-29T09:27:31Z -- Commit: 16a8d8d4f105 +- Generated: 2026-06-04T07:06:28Z +- Commit: a08525609c43 - Language: en - Pages: 23 -- Token estimate: ~60,360 (chars / 4) +- Token estimate: ~60,333 (chars / 4) --- @@ -3980,14 +3980,13 @@ export TRON_NETWORK="mainnet" # or "shasta" / "nile" ### Built-In Token Shortcuts -> Authoritative source: [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot). The shortcuts below are reconciled to that SSOT. The symbols recognized by `tron_api.mjs` are TRX, USDT, USDC, WTRX, BTT, JST, SUN, WIN; USDD is included below for consistency with the SSOT — pass its contract address explicitly. +> The symbols below are the ones `tron_api.mjs` recognizes as shortcuts for their contract addresses. For any token not listed here (e.g. USDD), look up its address in [reference/networks — Common token contracts (SSOT)](../reference/networks.md#common-token-contracts-ssot) and pass it explicitly. | Symbol | Contract Address | |--------|------------------| | TRX | Native (no contract) | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | -| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | diff --git a/docs/llms-full.zh.txt b/docs/llms-full.zh.txt index aebcc90..11d0a36 100644 --- a/docs/llms-full.zh.txt +++ b/docs/llms-full.zh.txt @@ -2,11 +2,11 @@ > 中文文档全文拼接，适合 LLM 一次性 ingest。由 scripts/gen_llms_full.py 生成。索引见 ../llms.txt 的 Localized 段。 -- Generated: 2026-05-29T09:27:31Z -- Commit: 16a8d8d4f105 +- Generated: 2026-06-04T07:06:28Z +- Commit: a08525609c43 - Language: zh - Pages: 23 -- Token estimate: ~41,605 (chars / 4) +- Token estimate: ~41,582 (chars / 4) --- @@ -3862,14 +3862,13 @@ export TRON_NETWORK="mainnet" # 或 "shasta" / "nile" ### 内置代币快捷符号 -> 权威来源：[reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot)。下方快捷符号已对齐该 SSOT。`tron_api.mjs` 实际内置可识别的符号为 TRX、USDT、USDC、WTRX、BTT、JST、SUN、WIN；USDD 为与 SSOT 保持一致而一并列出——请显式传入其合约地址使用。 +> 下表为 `tron_api.mjs` 内置、可直接用符号名代替合约地址的代币。未列出的代币（如 USDD）请在 [reference/networks — 常用代币合约（SSOT）](../reference/networks.md#ssot) 查询地址并显式传入。 | 符号 | 合约地址 | |------|----------| | TRX | 原生代币（无合约） | | USDT | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | | USDC | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | -| USDD | TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz | | WTRX | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR | | BTT | TAFjULxiVgT4qWk6UZwjqwZXTSaGaqnVp4 | | JST | TCFLL5dx5ZJdKnWuesXxi1VPwjLVmWZZy9 | @@ -3942,7 +3941,7 @@ tronlink-skills/ | 现象 | 原因 | 处理方式 | |------|------|----------| | 智能体不识别某个技能 | 技能包未被发现、命令名错误，或 host 未重新加载 | 确认技能包已安装/软链（重新执行 `install.sh`，或检查 host 发现路径下的软链——如 Codex 的 `~/.agents/skills/tronlink-skills`）；对照 [6 大技能详解](#the-6-skills) / [Skill ↔ MCP 工具映射](#skill-mcp-tool-map) 核对准确名称；再重启智能体/host 以重新扫描 `SKILL.md`。 | -| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#_1)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | +| TronGrid 限流（HTTP 429） | 未配置 API Key，或轮询过于频繁 | 设置 `TRONGRID_API_KEY`（见[配置说明](#configuration)）以获得更高限额；降低轮询频率；对 429/5xx 增加指数退避重试（这类是可重试的查询错误）。 | | 仅 CLI 可用的命令被通过 MCP 调用 | 33 个命令中有 8 个未暴露为 MCP 工具（`contract-info`、`trade-history`、`dex-volume`、`large-transfers`、`pool-info`、`swap-route`、`estimate-bandwidth`、`energy-rental`） | 查阅 [Skill ↔ MCP 工具映射](#skill-mcp-tool-map)：标注 _(仅 CLI)_ 的行没有对应 `tron_*` MCP 工具。请改用方式一（skill 提示词）或方式三（直接 CLI：`node scripts/tron_api.mjs ...`），不要走 `tools/call`。 | | `install.sh` 失败 | 网络被拦截、目标目录不可写，或缺少运行时 | 确认 Node.js >= 18 与 `git`/`curl` 在 `PATH` 中；在对发现目录（`~/.cursor`、`~/.agents/skills` 等）有写权限的环境下重试；若某步被权限拦截，参照方式四 —— Codex CLI 手动建立软链，再用 `codex skills list | grep tron` 验证。 | | 多 host 命令名冲突 | 同一技能/工具名被多个 MCP host 注册（如 `tronlink` 与 `tronlink-skills` 都暴露 `tron_*`） | 在智能体配置中为每个 host 取不同的名字（`mcpServers` 的 key / `claude mcp add `），使工具名按 host 命名空间化；或停用重复的 host，使每个 `tron_*` 名仅保留一个有效注册。 | diff --git a/docs/llms.txt b/docs/llms.txt index 3aee595..ed2f30e 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -2,7 +2,7 @@ > TronLink is a decentralized wallet for the TRON ecosystem, available as a browser extension and a mobile app. This documentation covers integrating DApps with TronLink across the browser extension, the mobile app (via DeepLink), and AI/agent tooling (MCP servers, CLI, signer SDK). -> Updated: 2026-05-29T09:27:31Z · Commit: 16a8d8d4f105 +> Updated: 2026-06-04T07:06:28Z · Commit: a08525609c43 How integration works: TronLink injects a `window.tron` provider into every page, exposing a `tronWeb` instance, a `request` method, and `on` / `removeListener` for events. A DApp detects the wallet via TIP-6963, requests authorization via `eth_requestAccounts` (TIP-1102), then builds, signs, and broadcasts transactions through `tronWeb`. Account/network changes arrive as passive `accountsChanged` / `chainChanged` events. diff --git a/docs/llms.zh.txt b/docs/llms.zh.txt index f1329a9..fd24848 100644 --- a/docs/llms.zh.txt +++ b/docs/llms.zh.txt @@ -2,7 +2,7 @@ > TronLink 是 TRON 生态的去中心化钱包，提供浏览器扩展和移动 App。本文档涵盖 DApp 通过浏览器扩展、移动端（DeepLink）以及 AI/智能体工具链（MCP 服务、CLI、签名 SDK）与 TronLink 集成。 -> Updated: 2026-05-29T09:27:31Z · Commit: 16a8d8d4f105 +> Updated: 2026-06-04T07:06:28Z · Commit: a08525609c43 集成原理：TronLink 向页面注入 `window.tron` provider，暴露 `tronWeb` 实例、`request` 方法以及 `on` / `removeListener` 事件订阅。DApp 通过 TIP-6963 检测钱包，用 `eth_requestAccounts`（TIP-1102）请求授权，再经 `tronWeb` 构建、签名并广播交易。账户/网络变化以 `accountsChanged` / `chainChanged` 被动事件送达。