acton

Acton TON CLI 工作流

权威信息来源

• 命令拼写和行为应以实际安装的二进制文件为准：
  • acton --version
  • acton --help
  • acton help <command>
  • acton <command> --help
• 当前概念、教程和完整参考请使用官方托管文档：
  • https://ton-blockchain.github.io/acton/docs/welcome/
  • https://ton-blockchain.github.io/acton/docs/commands/
  • https://ton-blockchain.github.io/acton/llms-full.txt
• 实际项目模式和参考合约请使用官方示例仓库：
  • https://github.com/ton-blockchain/acton-contracts
• 仅在需要时阅读随附参考资料：
  • references/command-map.md，用于快速选择命令
  • references/troubleshooting.md，用于了解常见故障模式
• 不要假设本地路径、私有检出目录或特定开发机器。
• 仅当用户明确要求检查上游实现时，才使用 GitHub 源码。将 acton-contracts 视为项目结构和合约模式的示例，而非 CLI 标志的权威来源。
• 如果文档与已安装的 CLI 不一致，请说明 Acton 版本，并在该本地工作流中以已安装的 CLI 为准。如果用户想了解最新行为，建议先运行 acton up 或使用安装／更新流程。

首个版本不包含的功能

• 不要推荐使用 acton localnet 或 --net localnet。该功能可能仍会显示在源码或 trunk 帮助信息中，但首个版本不包含此功能，应视为公共工作流中不可用。

安装或更新 Acton

如果缺少 acton 且任务需要运行它，请安装公开二进制文件：

curl -LsSf https://github.com/ton-blockchain/acton/releases/latest/download/acton-installer.sh | sh

然后打开新的 shell，或根据需要重新加载已更新的 shell 配置文件，并验证：

acton --version
acton --help

更新和版本管理：

• acton up 安装最新稳定版本。
• acton up --list 列出可用版本。
• acton up <version> 安装指定版本。
• 在已安装的 CLI 支持时，acton up --trunk 安装最新的 trunk 构建。
• 在 CI 中，优先使用 ton-blockchain/setup-acton@master 或已发布的 ghcr.io/ton-blockchain/acton:<version> 镜像。

在任何项目中进行的首批检查

1. 确认工具和项目上下文：
   • acton --version
   • acton doctor
   • pwd
2. 如果从项目目录外运行，请显式选择上下文：
   • acton --project-root <PATH> ...
   • acton --manifest-path <PATH>/Acton.toml ...
3. 在依赖记忆操作前，先检查相关命令的帮助信息：
   • acton help build
   • acton help test
   • acton help script
4. 检查 Acton.toml 中相关的部分：
   • [package]
   • [contracts]
   • [build]
   • [wrappers.tolk]
   • [wrappers.typescript]
   • [fmt]
   • [test]
   • [lint]
   • [networks]
   • [scripts]
   • [import-mappings]

项目根目录规则：相对于配置文件的路径以项目根目录为基准解析。相对 CLI 路径标志以当前工作目录为基准解析，除非传入绝对路径。

项目初始化

• 使用 acton new [path] --template empty|counter|jetton|nft 创建新项目。
• 实用的 acton new 标志：
  • --name、--description、--license
  • 当模板支持时，使用 --app 创建 TypeScript/Vite 应用脚手架
  • 使用 --hooks 添加默认项目 Git 钩子
  • 使用 --agents 生成编码 Agent 指南
• 使用 acton init 为现有目录添加 Acton 支持。
• 实用的 acton init 模式：
  • acton init --create-app [path] 仅创建 TypeScript 应用脚手架
  • acton init --stdlib-only 仅刷新随附的标准库
• acton init 可以将默认的 [import-mappings] 写入现有清单，但重写可能会删除 TOML 注释和未知键。

构建、编译和包装器

• acton build [contract-name]
  • 构建所有合约，或构建一个合约及其传递依赖。
  • 常用标志：--clear-cache、--graph <path>、--out-dir <dir>、--gen-dir <dir>、--output-fift <dir>、--info。
• acton compile <file.tolk>
  • 单文件编译器入口。
  • 常用标志：--json、--base64-only、--boc <file>、--fift <file>、--source-map <file>、--abi <file>、--allow-no-entrypoint、--clear-cache。
• acton wrapper <contract-name>
  • 根据合约 ABI 生成 Tolk 包装器。
  • 使用 --test、--test-output 或 --test-output-dir 生成测试桩。
  • 使用 --ts 通过 gen-typescript-from-tolk 生成 TypeScript 包装器。
  • 不要将 --ts 与测试桩生成选项结合使用。
• 如果 ABI、存储或消息类型发生变化，请重新生成包装器，不要手动编辑生成的文件。
• 包装器输出的默认值来自 [wrappers.tolk]、[wrappers.typescript] 和 @wrappers 导入映射。

测试和质量门禁

• 核心入口：acton test [path]。
• 常用测试标志：
  • --filter <regex>、--include <glob>、--exclude <glob>
  • --fail-fast
  • --fuzz-seed <seed>
  • --verbose，用于查看底层执行器日志
  • --debug --debug-port <port>
  • --backtrace full
  • --reporter console|dot|teamcity|junit 或以逗号分隔的组合
  • --junit-path <dir>、--junit-merge
  • --show-bodies
  • --clear-cache
• 覆盖率：
  • acton test --coverage --coverage-format lcov
  • acton test --coverage --coverage-format text
  • --coverage-file <path>
  • --coverage-minimum-percent <percent>
  • --coverage-include-wrappers
  • --coverage-include-tests
• Gas 性能分析：
  • acton test --snapshot build/gas-baseline.json
  • acton test --baseline-snapshot build/gas-baseline.json
  • acton test --baseline-snapshot build/gas-baseline.json --fail-on-diff
• 变异测试：
  • acton test --mutate --mutate-contract <contract-name>
  • --mutation-diff worktree|ref|branch
  • --mutation-diff-ref <ref>
  • --mutation-levels critical,major,minor
  • --mutation-disable-rules <rule>
  • --mutation-rules-file <path>
  • --mutation-session-id <id>
  • --mutation-id <id>
  • --mutation-workers <n>
  • --mutation-minimum-percent <percent>
• Fork 测试：
  • acton test --fork-net testnet|mainnet|custom:<name>
  • acton test --fork-net testnet --fork-block-number <seqno>
• 测试 UI 和跟踪记录：
  • acton test --ui
  • acton test --ui --ui-port <port>
  • acton test --save-test-trace
  • acton test --save-test-trace <dir>
• 默认值位于 [test]、[test.coverage]、[test.fuzz] 和 [test.mutation] 中。CLI 标志会覆盖当前运行的配置。

Lint、格式化和钩子

• acton check [target]
  • 检查项目、合约名称或 .tolk 文件。
  • 常用标志：--fix、--output-format plain|json|sarif|github|gitlab、--output-file <path>、--enable-only <code[,code...]>、--explain <rule>。
• Lint 配置位于 [lint]、[lint.rules] 和 [lint.rules.<contract-name>] 中。
• 行内忽略规则使用 // check-disable-next-line ...。
• acton fmt [paths...]
  • 格式化源文件。
  • 在 CI 中使用 acton fmt --check。
  • 默认值位于 [fmt] 中。
• acton hooks new|install|status|uninstall
  • 管理 .githooks 下的项目本地 Git 钩子。
• 典型的 CI 门禁：
  • acton build
  • acton test --reporter console,junit
  • acton check --output-format github
  • acton fmt --check

脚本、部署和网络读取

• acton script <path> [args...] 运行独立的 Tolk 脚本。
• 没有 acton deploy 命令。部署由脚本驱动。
• 对于会更改状态的脚本，安全的执行顺序如下：
  1. acton build
  2. acton test
  3. 使用 acton script <path> 在本地模拟
  4. acton script <path> --net testnet
  5. 仅在 testnet 验证通过后，才运行 acton script <path> --net mainnet
• --net <network> 会将真实交易广播到 testnet、mainnet 或 custom:<name>。如果省略 --net，则仅在本地执行。
• --fork-net <network> 会在本地执行时读取远程状态。如果设置了 --net，省略 --fork-net 时，读取操作默认使用所选网络。
• 常用脚本标志：--debug、--debug-port、--backtrace full、--verbose、--clear-cache、--fork-net、--fork-block-number、--net、--explorer tonscan|toncx|dton|tonviewer、--show-bodies。
• acton run <script-name> [args...] 运行 Acton.toml 中 [scripts] 的条目。
• 脚本参数会根据 main() ABI 解析。对于看起来像 Acton 标志的转发参数，请在前面使用 --。
• 内置网络 API 密钥通过环境变量设置，通常从 .env 加载：
  • TONCENTER_TESTNET_API_KEY
  • TONCENTER_MAINNET_API_KEY
  • custom:<name> 对应的 <NORMALIZED_NAME>_API_KEY

钱包、验证和检查

• 钱包：
  • acton wallet new
  • acton wallet import
  • acton wallet list
  • acton wallet export-mnemonic
  • acton wallet sign
  • acton wallet remove
  • acton wallet airdrop
• 如可用，请优先使用安全的密钥环存储。对于 CI，请使用 mnemonic-env，切勿提交明文钱包文件或助记词。
• 验证：
  • acton verify [contract-name] --address <addr> --net testnet|mainnet
  • 实用标志：--wallet <name>、--compiler-version <version>、--dry-run。
• RPC 检查：
  • acton rpc info <address>
  • acton rpc block
  • acton rpc block-number
  • acton rpc trace <hash>
• 链上库：
  • acton library publish
  • acton library fetch
  • acton library info
  • acton library topup
• 底层工具：
  • acton disasm [boc-file]
  • acton retrace <tx-hash>
  • acton doc tvm <query...>
  • acton func2tolk <path>
  • acton ls --stdio 或 acton ls --port <port>
  • acton completions bash|elvish|fish|powershell|zsh|nushell

安全和正确性规则

• 在运行 acton script --net mainnet、acton verify、acton library publish 或 acton library topup 前，只警告一次。
• 如果钱包、网络、项目根目录和 Acton 版本的假设会影响结果，请明确说明。
• 不要编造命令或标志。不确定时，请使用 acton help <command> 核实。
• 除非用户安装的二进制文件明确支持，否则不要使用包含 acton litenode、[mappings]、--broadcast、--api-key 或 acton up --canary 的旧示例。
• 对于 Acton 文档未涵盖的区块链概念，请参考 TON 文档；对于 CLI 行为，请参考 Acton 文档。