fix audio report issue

Author: jizhen181-dot

docs/Agent-Wallet/Developer/CLI-Reference.md

@@ -26,6 +26,10 @@ agent-wallet start -p Abc12345!
 ```
 Password requirements: at least 8 characters, including uppercase, lowercase, numbers, and special characters.
 
+:::caution Shell history risk
+Passing `-p` inline records the password in your terminal's history file. For production wallets, prefer interactive mode (`agent-wallet start` without `-p`) or set `AGENT_WALLET_PASSWORD` as an environment variable — see [Non-Interactive Execution](#non-interactive-execution-for-automation--background-services).
+:::
+
 **Import an existing private key:**
 ```bash
 agent-wallet start -p Abc12345! -k your-private-key-hex
@@ -155,16 +159,18 @@ jobs:
 
 </details>
 
-### Method B: Local Password Cache (True "Set and Forget")
+### Method B: Local Password Cache (Convenience vs. Security Trade-off)
 
-The ultimate convenience solution. After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables:
+After running a command once with the `--save-runtime-secrets` flag, the password is permanently cached in a local file (`~/.agent-wallet/runtime_secrets.json`). The next time you run any signing command, the system automatically reads from the cache. No need for inline passwords or environment variables:
 
 ```bash
 agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets
 ```
 
-:::danger Security Warning
-`runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Only use this feature if you fully trust the runtime environment, and make sure this file is never committed to git or synced to the cloud.
+:::danger This disables the dual-lock protection
+Caching the password next to the wallet file means a single file system compromise grants full access to your funds — defeating Agent-wallet's core "physical file + password separation" security model. **Only use this for throwaway test wallets.**
+
+`runtime_secrets.json` stores your master password in **plaintext**. Any program with access to your file system (malicious plugins, AI agents, automation scripts) can read it directly. Make sure this file is never committed to git or synced to the cloud.
 
 The tool automatically sets restrictive file permissions (`600` — owner-read-only) on creation. If you've manually moved or copied the file, verify the permissions: `chmod 600 ~/.agent-wallet/runtime_secrets.json`.
 :::

docs/Agent-Wallet/Developer/SDK-Cookbook.md

@@ -21,7 +21,11 @@ Before running any example below, make sure you have:
 
 1. Installed the Agent-wallet SDK (see [SDK Guide](./SDK-Guide.md))
 2. Initialized a local wallet via the CLI, or configured static mode environment variables
-3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode) or `AGENT_WALLET_PRIVATE_KEY` (static mode)
+3. Set `AGENT_WALLET_PASSWORD` (local `local_secure` mode — strongly recommended)
+
+:::danger Avoid static mode (`AGENT_WALLET_PRIVATE_KEY`) for real funds
+Static mode stores your private key as plaintext in an environment variable — the exact exposure Agent-wallet's `local_secure` mode is designed to prevent. Only use `AGENT_WALLET_PRIVATE_KEY` in fully isolated, offline test environments with throwaway keys. For mainnet operations, always use `AGENT_WALLET_PASSWORD` with your local encrypted safe.
+:::
 
 ---
 
@@ -112,7 +116,15 @@ async function transferTRX(
   console.log("Unsigned txID:", unsignedTx.txID);
 
   // Step 3: Sign locally with Agent-wallet
-  const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx));
+  let signedTx: Record<string, unknown>;
+  try {
+    signedTx = JSON.parse(await wallet.signTransaction(unsignedTx));
+  } catch (e) {
+    throw new Error(`signTransaction returned invalid JSON: ${e}`);
+  }
+  if (!signedTx.signature) {
+    throw new Error("Signed transaction is missing the signature field");
+  }
   console.log("Signed, signature:", signedTx.signature);
 
   // Step 4: Broadcast via TronGrid
@@ -177,7 +189,13 @@ async def transfer_trx(
         print("Unsigned txID:", unsigned_tx["txID"])
 
         # Step 3: Sign locally with Agent-wallet
-        signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx))
+        raw_signed = await wallet.sign_transaction(unsigned_tx)
+        try:
+            signed_tx = json.loads(raw_signed)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"signTransaction returned invalid JSON: {e}") from e
+        if "signature" not in signed_tx:
+            raise ValueError("Signed transaction is missing the signature field")
         print("Signed, signature:", signed_tx["signature"])
 
         # Step 4: Broadcast via TronGrid
@@ -306,6 +324,7 @@ async function transferBNB(
   console.log("Signed");
 
   // Step 5: Broadcast
+  // signTransaction returns hex without '0x' prefix; ethers requires it
   const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex);
   console.log("Broadcast successful! txHash:", txResponse.hash);
 

docs/Agent-Wallet/FAQ.md

@@ -76,7 +76,9 @@ No limit. You can create separate wallets for different AI agents, different cha
 | **If an agent reads the file** | ✅ Key is inaccessible | ❌ Stolen instantly |
 | **Use case** | ✅ All scenarios | ⚠️ Fully isolated dev environments only |
 
-**Always use `local_secure`** unless you're 100% certain no other agent is running on that machine.
+:::danger `raw_secret` exposes your private key as plaintext
+`raw_secret` stores your key unencrypted — the exact exposure `local_secure` mode is designed to prevent. If any other process on your machine can read files, your key can be stolen instantly. **Always use `local_secure`** unless you're 100% certain no other agent is running on that machine and it's a fully isolated, offline test environment.
+:::
 
 ### What values does the `network` parameter accept?
 

docs/Agent-Wallet/QuickStart.md

@@ -123,7 +123,7 @@ source ~/.zshrc
 ```
 
 </TabItem>
-<TabItem value="win-linux" label="Windows / Linux Users (Bash)">
+<TabItem value="win-linux" label="Linux / WSL Users (Bash)">
 
 **Step 1:** Open `~/.bashrc` in an editor. Add the following line at the end of the file (replace the content inside the single quotes with your actual password):
 

docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md

@@ -135,7 +135,7 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$'
 
 1. **Verify password**: Run `echo $AGENT_WALLET_PASSWORD` to confirm the variable is set correctly.
 2. **Check wallet directory**: Verify `~/.agent-wallet/` exists and contains wallet files. If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path.
-3. **If password is lost**: You'll need to re-initialize the wallet. See the [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details.
+3. **If password is lost**: You'll need to re-initialize the wallet. Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details.
 
 
 ### "Conflicting Wallet Modes"
@@ -271,7 +271,7 @@ sun-mcp-server
    - Check Permit2 request structured data
    - Confirm chain ID, token address, deadline correct
 
-3. **Reinitialize Wallet** — see [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) for re-initialization instructions.
+3. **Reinitialize Wallet** — run `agent-wallet reset` to wipe and start over. See [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) for details.
 
 4. **Use Alternate Authorization Method**
    ```

docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md

@@ -93,7 +93,7 @@ If the server reports an invalid private key at startup, it's usually a format i
 
 `AGENT_WALLET_PASSWORD` must exactly match the master password set during wallet initialization. Verify that the wallet directory exists (`ls ~/.agent-wallet/`) and that `AGENT_WALLET_DIR` points to the correct path if you used a custom directory.
 
-If the password is lost, you'll need to re-initialize — see the [Agent-Wallet Quick Start](../../../Agent-Wallet/QuickStart) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details.
+If the password is lost, you'll need to re-initialize. Run `agent-wallet reset` to wipe and start over — see [CLI Reference → Reset](../../../Agent-Wallet/Developer/CLI-Reference#agent-wallet-reset-reset-all-data) and [Agent-Wallet FAQ](../../../Agent-Wallet/FAQ) for details.
 
 ### TronGrid API Key not working
 

i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/CLI-Reference.md

@@ -26,6 +26,10 @@ agent-wallet start -p Abc12345!
 ```
 密码要求：至少 8 位，包含大写、小写、数字和特殊字符。
 
+:::caution Shell 历史记录风险
+使用 `-p` 内联传递密码会将密码记录在终端的历史文件中。生产钱包建议使用交互式模式（不带 `-p` 的 `agent-wallet start`）或通过环境变量设置 `AGENT_WALLET_PASSWORD`——详见[非交互式执行](#非交互式执行专为自动化与后台设计)。
+:::
+
 **导入已有私钥：**
 ```bash
 agent-wallet start -p Abc12345! -k 你的私钥十六进制
@@ -155,16 +159,18 @@ jobs:
 
 </details>
 
-### 方式 B：密码本地缓存（真正的"一劳永逸"）
+### 方式 B：密码本地缓存（便利性与安全性的取舍）
 
-这是最省事的终极方案。执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量：
+执行一次带 `--save-runtime-secrets` 参数的命令后，密码会被永久缓存在本地文件（`~/.agent-wallet/runtime_secrets.json`）中。下次再运行任何签名命令时，系统会自动读取该缓存。你既不需要在命令行写密码，也不需要配环境变量：
 
 ```bash
 agent-wallet sign msg "Hello" -n tron -p "Abc12345!" --save-runtime-secrets
 ```
 
-:::danger 安全提示
-`runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。请仅在你完全信任运行环境的前提下使用此功能，且务必确保该文件不会被提交到 git 或同步到云端。
+:::danger 此操作会使双重锁保护失效
+将密码缓存在钱包文件旁边，意味着一次文件系统入侵就能获取全部资金——彻底击溃 Agent-wallet 的核心"物理文件 + 密码分离"安全模型。**请仅对一次性测试钱包使用此功能。**
+
+`runtime_secrets.json` 以**明文**存储你的主密码。任何能访问你文件系统的程序（恶意插件、AI 代理、自动化脚本）都可以直接读取。务必确保该文件不会被提交到 git 或同步到云端。
 
 工具在创建该文件时会自动设置严格的文件权限（`600`——仅所有者可读）。如果你手动移动或复制过该文件，请验证权限：`chmod 600 ~/.agent-wallet/runtime_secrets.json`。
 :::
@@ -240,6 +246,7 @@ echo "提取到的签名内容是: $SIGNATURE"
 
 # 接下来，你可以拿这个 $SIGNATURE 去发请求、拼 JSON，或者传给其他流水线任务...
 ```
+
 ---
 
 ## 下一步

i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/Developer/SDK-Cookbook.md

@@ -21,7 +21,11 @@ Agent-wallet 专注做好最核心的安全签名步骤（第 2 步）。本页
 
 1. 安装 Agent-wallet SDK（详见 [SDK 接入指南](./SDK-Guide.md)）
 2. 通过 CLI 初始化本地钱包，或配置静态模式的环境变量
-3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式）或 `AGENT_WALLET_PRIVATE_KEY`（静态模式）
+3. 设置 `AGENT_WALLET_PASSWORD`（本地 `local_secure` 模式——强烈推荐）
+
+:::danger 真金白银操作请勿使用静态模式（`AGENT_WALLET_PRIVATE_KEY`）
+静态模式将你的私钥以明文存储在环境变量中——这恰恰是 Agent-wallet `local_secure` 模式旨在防范的风险。请仅在完全隔离的离线测试环境中使用一次性测试私钥。主网操作请永远使用 `AGENT_WALLET_PASSWORD` 配合本地加密保险箱。
+:::
 
 ---
 
@@ -112,7 +116,15 @@ async function transferTRX(
   console.log("未签名 txID：", unsignedTx.txID);
 
   // 第三步：用 Agent-wallet 本地签名
-  const signedTx = JSON.parse(await wallet.signTransaction(unsignedTx));
+  let signedTx: Record<string, unknown>;
+  try {
+    signedTx = JSON.parse(await wallet.signTransaction(unsignedTx));
+  } catch (e) {
+    throw new Error(`signTransaction 返回了无效的 JSON: ${e}`);
+  }
+  if (!signedTx.signature) {
+    throw new Error("签名后的交易缺少 signature 字段");
+  }
   console.log("已签名，signature：", signedTx.signature);
 
   // 第四步：通过 TronGrid 广播
@@ -177,7 +189,13 @@ async def transfer_trx(
         print("未签名 txID：", unsigned_tx["txID"])
 
         # 第三步：用 Agent-wallet 本地签名
-        signed_tx = json.loads(await wallet.sign_transaction(unsigned_tx))
+        raw_signed = await wallet.sign_transaction(unsigned_tx)
+        try:
+            signed_tx = json.loads(raw_signed)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"signTransaction 返回了无效的 JSON: {e}") from e
+        if "signature" not in signed_tx:
+            raise ValueError("签名后的交易缺少 signature 字段")
         print("已签名，signature：", signed_tx["signature"])
 
         # 第四步：通过 TronGrid 广播
@@ -306,6 +324,7 @@ async function transferBNB(
   console.log("已签名");
 
   // 第五步：广播
+  // signTransaction 返回的十六进制不带 '0x' 前缀；ethers 需要加上
   const txResponse = await rpcProvider.broadcastTransaction("0x" + signedTxHex);
   console.log("广播成功！txHash：", txResponse.hash);
 

i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/FAQ.md

@@ -76,7 +76,9 @@ MetaMask 是给人用的浏览器钱包，有图形界面，每次签名需要
 | **代理读了文件** | ✅ 拿不到密钥 | ❌ 直接被盗 |
 | **适合场景** | ✅ 所有场景 | ⚠️ 完全隔离的开发环境 |
 
-**永远用 `local_secure`**，除非你 100% 确定那台机器上没有任何其他代理。
+:::danger `raw_secret` 会以明文存储你的私钥
+`raw_secret` 不加密私钥——这恰恰是 `local_secure` 模式旨在防范的风险。如果你的机器上有任何其他进程能读取文件，你的私钥就会被直接盗走。**永远用 `local_secure`**，除非你 100% 确定那台机器上没有任何其他代理，且处于完全隔离的离线测试环境中。
+:::
 
 ### `network` 参数怎么填？
 

i18n/zh-Hans/docusaurus-plugin-content-docs/current/Agent-Wallet/QuickStart.md

@@ -123,7 +123,7 @@ source ~/.zshrc
 ```
 
 </TabItem>
-<TabItem value="win-linux" label="Windows / Linux 用户 (Bash)">
+<TabItem value="win-linux" label="Linux / WSL 用户 (Bash)">
 
 **第 1 步：** 用编辑器打开 `~/.bashrc` 文件，在末尾添加以下内容（把单引号里的内容换成你的真实密码）：