重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
ton-bug-triage by ton-blockchain/ton-triage-skill
npx skills add https://github.com/ton-blockchain/ton-triage-skill --skill ton-bug-triage当任务是在本地 tontester 网络上复现问题,而不仅仅是启动验证器时,使用此技能。
典型触发场景:
标准是:选择能回答问题的最小拓扑结构,在运行前定义成功条件,并收集足够的证据以使结果可解释。
请区分以下路径:
scripts/run_basic_network.py--repo-root 传入的真实 TON 代码库validator-engine、create-state、tonlibjson 和 tolk广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
不要假设技能目录和代码库是同一个东西。脚本位于技能目录中。它们对您传入的代码库和构建目录进行操作。
wallet-env.txt 是启动器和后续辅助工具之间的主要交接产物。
这些辅助工具依赖于 tontester 的内部实现和私有 API。如果 tontester 发生变化,需要相应调整辅助工具的行为、生成的绑定或命令假设。
在运行任何操作之前,请选择一个工作流:
工作流 A — 通过交易触发 当 bug 需要通过部署合约、发送内部消息或将畸形/自定义负载传递到合约账户来触发时,使用此工作流。工作流 B — 通过验证器行为触发 当 bug 需要打补丁的验证器代码、混合构建版本、共识干扰、畸形协议数据包、流量重排序或故意无效的区块行为时,使用此工作流。如果一个复现同时涉及两者,请先问一个问题:您能否在正常部署/发送路径后,在未修改的网络上触发它?如果可以,从工作流 A 开始。如果不可以,则将其视为工作流 B。
vanilla-build/ 是基准构建,build/ 或 build-probing/ 是修改后的构建。mc_seqno、明确的崩溃标记、进程终止、活跃的合约账户、检查过的交易,或诚实节点对畸形数据包的拒绝。优先使用捆绑的脚本,而不是一次性的 shell 命令序列。
scripts/run_basic_network.py 从单个构建版本启动一个或多个验证器。支持 --emit-wallet-env、--base-port、--validators 和 --keep-alive。scripts/run_mixed_network.py 从不同的构建目录启动基准和探测验证器。用于恶意与诚实节点实验、基于日志的崩溃检测和探测节点存活检查。scripts/compile_tolk.py 将 .tolk 源代码编译为 .fif 并生成合约代码 BoC。如果 tolk 二进制文件相对于代码库 HEAD 已过时,则会硬性失败。scripts/build_stateinit.py 从代码加上可选的数据和库字典 BoC 构建可部署的 StateInit BoC。scripts/run_fift_script.py 使用正确的包含路径运行 .fif 脚本。scripts/wallet_send.py 构建并可选地发送钱包签名的消息。使用 --init-boc 进行部署,使用 --body-boc 发送任意的内部负载。scripts/send_boc.py 通过 tonlib 发送预构建的序列化外部消息 BoC,而无需通过 wallet_send.py 重新构建。scripts/address_info.py 当辅助工具输入需要交叉检查时,对原始和友好的 TON 地址形式进行规范化和检查。scripts/account_state.py 获取原始账户状态并转储代码/数据 BoC 以供检查。scripts/get_method.py 通过 tonlib 运行 get-method 并打印 JSON。scripts/inspect_latest_transaction.py 获取最新的账户交易,导出原始交易数据,并在 tonlib 将其作为 msg.dataRaw 返回时保存消息体/初始状态 BoC。scripts/run_liteclient.py 使用 wallet-env.txt 或显式的代码库/构建/配置输入运行 lite-client 命令。scripts/dump_boc.py 通过 Fift 打印 BoC 单元树。用于负载、StateInit、导出的交易数据以及转储的账户代码/数据。scripts/summarize_run.py 为已完成或正在运行的运行目录总结节点活性和崩溃标记。scripts/demo_wallet_flow.py 简单钱包路径的已知良好端到端验证器。当触发条件是“部署合约,然后发送消息”时,使用工作流 A。
--emit-wallet-env 启动一个小型网络。scripts/compile_tolk.py 编译您的合约,或者如果您不使用 Tolk,则提供从 Fift 汇编手动构建的代码 BoC。scripts/build_stateinit.py 构建可部署的 StateInit。仅在合约实际需要时传递 --data-boc 和 --library-boc。scripts/wallet_send.py --init-boc 从已注资的内置 main-wallet 进行部署。使用 --init-boc 的部署消息也可能调用合约的内部消息处理程序。在发送单独的触发消息之前,请检查部署交易本身是否更改了合约状态。account_state.py 加上合约特定的 get-method,而不是假设一次主链推进就足够了。run_fift_script.py 是生成一次性 body.boc 的最简单方法。scripts/wallet_send.py --body-boc 发送触发消息。--body-boc 是权威的负载路径,会覆盖 --comment。如果您已经有一个签名的外部消息 BoC,请使用 scripts/send_boc.py --boc,而不是用 wallet_send.py 重新构建。--wait-mc-advance 证明网络是存活的。它不证明交易成功、部署激活或合约状态改变。始终直接检查目标账户。inspect_latest_transaction.py --out-dir 和 dump_boc.py 进行观察。导出的 transaction-data.boc 和 in-msg-body.boc 是进行单元级调试的起点。如果基于 tonlib 的辅助工具崩溃(常见症状:KeyError: '@extra'),请使用 run_liteclient.py 作为所有观察步骤的后备方案。参见 references/liteclient_fallback.md。有关完整的工作序列,请阅读 references/contract_deploy_flow.md。
仅针对简单钱包冒烟路径,请阅读 references/wallet_and_deploy_helpers.md。
当触发条件是“修改验证器行为,然后观察诚实节点的反应”时,使用工作流 B。
TON_PROBING_* 环境变量之后。--success-log、--failure-log、--require-node-alive 和 --require-node-dead。scripts/run_mixed_network.py 运行混合网络。scripts/summarize_run.py 总结运行情况,然后仅在总结指向的地方手动检查特定日志。有关常见的补丁模式,请阅读 references/probing_patterns.md。
有关端到端示例,请阅读 references/bug_hunt_example.md。
一个有效的“未复现”结果仍然是有用的证据。仅当以下所有条件都成立时,才将一次运行视为真正的负面结果:
当一次干净的重新运行给出相同结果,并且剩余的更改只是次要的参数调整时,停止迭代并报告负面结果。
compile_tolk.py 因构建过时而失败,请先重新构建 tolk。确切的修复方法通常是 ninja -C <build-dir> tolk。inspect_latest_transaction.py 显示错误的负载,请同时转储原始触发 BoC 和导出的 in-msg-body.boc,并比较它们的单元树。记录足够的信息以支持声明:
对于工作流 A,请记住 --wait-mc-advance 只是一个活性提示;请从目标账户或交易确认成功。
python,请使用 python3。tonapi 绑定,辅助工具通常会从 test/tontester/generate_tl.py 生成它们。--repo-root 传入;包含文件和生成的产物来自代码库,而不是技能文件夹。account_state.py、get_method.py、inspect_latest_transaction.py、wallet_send.py --auto-seqno)因 KeyError: '@extra' 或类似的 tonlib 包装器错误而崩溃,则本地 tonlib 构建存在兼容性问题。对于检查操作,请回退到 lite-client,并使用带有手动 --seqno 的 wallet_send.py 而不是 --auto-seqno。有关共享的后备流程,请参见 references/liteclient_fallback.md。vanilla-build/CMakeCache.txt 指向 build/,则将 vanilla-build 视为无效并重新创建它。不要信任重新配置到错误目录的构建树。lite-client 存在于传入的构建目录中。有些代码库只构建了 create-state、tonlibjson 和 tolk。run-* 目录。references/wallet_and_deploy_helpers.md 阅读此文件了解经过验证的简单钱包冒烟路径。references/contract_deploy_flow.md 阅读此文件了解通用工作流 A 的编译、部署、触发、检查路径。references/liteclient_fallback.md 当基于 tonlib 的辅助工具失败且工作流 A 需要 lite-client 检查或手动钱包 seqno 处理时,阅读此文件。references/probing_patterns.md 在设计工作流 B 代码更改时,阅读此文件。references/diagnostic_checklist.md 当运行完成但结果不明确时,阅读此文件。references/bug_hunt_example.md 阅读此文件了解具体的混合网络负面结果示例。每周安装次数
66
代码库
GitHub 星标数
9
首次出现
2026年3月9日
安全审计
安装于
codex65
opencode63
kimi-cli59
gemini-cli59
amp59
cline59
Use this skill when the job is to prove something on a local tontester network, not just to launch validators.
Typical triggers:
The standard is: choose the smallest topology that answers the question, define the success condition before running, and collect enough evidence that the result is interpretable.
Keep these paths distinct:
scripts/run_basic_network.py--repo-rootvalidator-engine, create-state, tonlibjson, and tolkDo not assume the skill directory and the repo are the same thing. The scripts live in the skill. They operate on the repo and build you pass in.
wallet-env.txt is the main handoff artifact between the launcher and follow-up helpers.
These helpers depend on tontester internals and private APIs. If tontester changes, expect to adjust helper behavior, generated bindings, or command assumptions.
Choose one workflow before running anything:
Workflow A — trigger via transaction Use this when the bug is reached by deploying a contract, sending an internal message, or delivering a malformed/custom payload to a contract account.
Workflow B — trigger via validator behavior Use this when the bug requires patched validator code, mixed builds, consensus interference, malformed protocol packets, reordered traffic, or deliberately invalid block behavior.
If a repro touches both, ask one question first: can you trigger it on an unmodified network after a normal deploy/send path? If yes, start with Workflow A. If no, treat it as Workflow B.
Start with the smallest network that can answer the question. Use one validator unless the path needs peers, consensus, or mixed builds.
Prefer ordinary deploy/send flow over zerostate edits. If the bug only reproduces after zerostate mutation, say that clearly.
Keep baseline and probing builds separate. Usually vanilla-build/ is baseline and build/ or build-probing/ is the modified build.
Decide the success condition before running. Examples: target mc_seqno, explicit crash marker, process death, active contract account, inspected transaction, or honest-node rejection of a malformed packet.
For Workflow B, make the probing node self-immune. Operational meaning: the probing node may emit malformed or adversarial behavior, but it must stay alive until the target effect is observed on the honest nodes. A run is invalid if the probing node dies first and that death could explain the outcome.
Record enough evidence to rerun the exact scenario. Keep the run directory, the build directories, the commands, the relevant addresses, and the exported artifacts.
Before calling something maintainer-ready, rerun it from a clean checkout or detached worktree with only the intended artifacts.
Prefer the bundled scripts over one-off shell sequences.
scripts/run_basic_network.py Launch one or more validators from a single build. Supports --emit-wallet-env, --base-port, --validators, and --keep-alive.
scripts/run_mixed_network.py Launch baseline and probing validators from different build directories. Use this for malicious-vs-honest experiments, log-based crash detection, and probing-node survival checks.
scripts/compile_tolk.py Compile a .tolk source to .fif and materialize the contract code BoC. It hard-fails if the binary is stale relative to repo .
Use Workflow A when the trigger is “deploy contract, then send message”.
--emit-wallet-env.scripts/compile_tolk.py, or provide a hand-built code BoC from Fift assembly if you are not using Tolk.StateInit with scripts/build_stateinit.py. Pass --data-boc and --library-boc only when the contract actually needs them.main-wallet with scripts/wallet_send.py --init-boc. A deploy message that uses --init-boc may also invoke the contract's internal message handler. Check whether the deploy transaction itself changed contract state before sending a separate trigger.For the full worked sequence, read references/contract_deploy_flow.md.
For the simple wallet smoke path only, read references/wallet_and_deploy_helpers.md.
Use Workflow B when the trigger is “modify validator behavior, then observe honest-node reaction”.
TON_PROBING_* environment variables.--success-log, --failure-log, --require-node-alive, and --require-node-dead deliberately.scripts/run_mixed_network.py.scripts/summarize_run.py, then inspect specific logs manually only where the summary points.For common patch shapes, read references/probing_patterns.md.
For an end-to-end example, read references/bug_hunt_example.md.
A valid “did not reproduce” is still useful evidence. Treat a run as a real negative result only if all of the following are true:
Stop iterating and report a negative result when a clean rerun gives the same outcome and the remaining changes are only minor parameter churn.
If compile_tolk.py fails with a stale-build error, rebuild tolk first. The exact fix is usually ninja -C <build-dir> tolk.
If a deploy appears to succeed but the destination still looks empty, check too-early observation first. Wait for activation instead of assuming the deploy path is broken.
If a contract is active but the expected get-method fails, verify the method id and the initial data layout before changing the network topology.
If inspect_latest_transaction.py shows the wrong payload, dump both the original trigger BoC and the exported in-msg-body.boc and compare their cell trees.
If probing markers are missing in Workflow B, the environment variables did not reach the node or the patched code path never executed.
If the probing node dies before the target effect is observed, the run is invalid.
Record enough to support the claim:
For Workflow A, remember that --wait-mc-advance is only a liveness hint; confirm success from the target account or transaction.
python is missing, use python3.tonapi bindings are missing, the helpers usually generate them from test/tontester/generate_tl.py.--repo-root; includes and generated artifacts come from the repo, not the skill folder.account_state.py, get_method.py, inspect_latest_transaction.py, wallet_send.py --auto-seqno) crash with KeyError: '@extra' or similar tonlib wrapper errors, the local tonlib build has a compatibility issue. Fall back to for inspection and use with manual instead of . See for the shared fallback flow.references/wallet_and_deploy_helpers.md Read this for the proven simple-wallet smoke path.
references/contract_deploy_flow.md Read this for the generic Workflow A compile, deploy, trigger, inspect path.
references/liteclient_fallback.md Read this when tonlib-based helpers fail and Workflow A needs lite-client inspection or manual wallet seqno handling.
references/probing_patterns.md Read this when designing Workflow B code changes.
references/diagnostic_checklist.md Read this when a run completed but the outcome is unclear.
references/bug_hunt_example.md Read this for a concrete mixed-network negative-result example.
Weekly Installs
66
Repository
GitHub Stars
9
First Seen
Mar 9, 2026
Security Audits
Gen Agent Trust HubPassSocketWarnSnykWarn
Installed on
codex65
opencode63
kimi-cli59
gemini-cli59
amp59
cline59
Azure 升级评估与自动化工具 - 轻松迁移 Functions 计划、托管层级和 SKU
111,700 周安装
智能体性能优化指南:通过数据驱动和提示工程提升AI智能体可靠性与效率
288 周安装
AgentOps技能转换器 - 一键将技能转换为Codex、Cursor等AI平台格式
288 周安装
goals by boshu2/agentops:自动化健身目标维护与测量CLI工具
289 周安装
opencode-mirror 镜像工具:快速配置与安全使用指南 | Git 镜像管理
296 周安装
heal-skill:自动化技能维护工具,一键检测修复技能规范问题
293 周安装
LobeChat i18n 国际化指南:使用 react-i18next 实现多语言支持与最佳实践
295 周安装
tolkHEADscripts/build_stateinit.py Build a deployable StateInit BoC from code plus optional data and library-dictionary BoCs.
scripts/run_fift_script.py Run a .fif script with the correct include paths.
scripts/wallet_send.py Build and optionally send a wallet-signed message. Use --init-boc for deployment and --body-boc for arbitrary internal payloads.
scripts/send_boc.py Send a prebuilt serialized external message BoC through tonlib without rebuilding it via wallet_send.py.
scripts/address_info.py Normalize and inspect raw and friendly TON address forms when helper inputs need to be cross-checked.
scripts/account_state.py Fetch raw account state and dump code/data BoCs for inspection.
scripts/get_method.py Run a get-method through tonlib and print JSON.
scripts/inspect_latest_transaction.py Fetch the latest account transaction, export raw transaction data, and save message body/init-state BoCs when tonlib returns them as msg.dataRaw.
scripts/run_liteclient.py Run a lite-client command using wallet-env.txt or explicit repo/build/config inputs.
scripts/dump_boc.py Print a BoC cell tree through Fift. Use this for payloads, StateInit, exported transaction data, and dumped account code/data.
scripts/summarize_run.py Summarize node liveness and crash markers for a finished or live run directory.
scripts/demo_wallet_flow.py Known-good end-to-end verifier for the simple wallet path.
account_state.py plus a contract-specific get-method over assuming one masterchain advance is enough.run_fift_script.py is the easiest way to emit a one-off body.boc.scripts/wallet_send.py --body-boc. --body-boc is the authoritative payload path and overrides --comment. If you already have a signed external message BoC, use scripts/send_boc.py --boc instead of rebuilding it with wallet_send.py. --wait-mc-advance proves the network is alive. It does NOT prove the transaction succeeded, the deploy activated, or the contract state changed. Always inspect the target account directly.inspect_latest_transaction.py --out-dir and dump_boc.py. The exported transaction-data.boc and in-msg-body.boc are the starting point for cell-level debugging. If the tonlib-based helpers crash (common symptom: KeyError: '@extra'), use run_liteclient.py as the fallback for all observation steps. See references/liteclient_fallback.md.lite-clientwallet_send.py--seqno--auto-seqnoreferences/liteclient_fallback.mdvanilla-build/CMakeCache.txt points at build/, treat vanilla-build as invalid and recreate it. Do not trust a build tree that reconfigures into the wrong directory.lite-client is present in the passed build directory. Some checkouts only have create-state, tonlibjson, and tolk built.run-* directories before retrying.