Fix the HarmonyOS symbol-upload instructions

en/rum/error-tracking/source-mapping.mdx

@@ -210,11 +210,18 @@ In **Application Management → Source Code Management → HarmonyOS**, the uplo
 
 <Steps>
   <Step title="Install the hvigor plugin">
-    Install the upload plugin in your HarmonyOS project:
+    Declare the plugin in the project's `hvigor/hvigor-config.json5` and let hvigor fetch it from npm:
 
-    ```bash
-    npm install -D @flashcatcloud/hvigor-plugin@^0.1.3
+    ```json5 hvigor/hvigor-config.json5
+    {
+      "modelVersion": "5.0.0",
+      "dependencies": {
+        "@flashcatcloud/hvigor-plugin": "0.1.4"
+      }
+    }
     ```
+
+    You can also run `npm install -D @flashcatcloud/hvigor-plugin`, but a HarmonyOS project root has no `package.json`, so run `npm init -y` first or npm installs into an unrelated project in a parent directory. See [HarmonyOS SDK advanced configuration](/en/rum/sdk/harmony/advanced-config).
   </Step>
   <Step title="Register the plugin in hvigorfile.ts">
     Write the panel-generated `service`, `version`, and `apiKey` settings into `hvigorfile.ts`:
@@ -229,24 +236,25 @@ In **Application Management → Source Code Management → HarmonyOS**, the uplo
         flashcatSymbolUploadPlugin({
           apiKey: process.env.FLASHCAT_API_KEY ?? '',
           service: 'my-app',
-          version: '1.0.0',
-          enabled: process.env.FLASHCAT_UPLOAD === '1'
+          version: '1.0.0'
         })
       ]
     };
     ```
   </Step>
   <Step title="Run the upload after the build">
-    After the build artifacts are ready, run the upload task:
+    Once the build artifacts are ready, run the upload task. **`--no-daemon` is required when you configure the plugin from environment variables**, otherwise a reused hvigor daemon hands the plugin a stale environment, the API key reads as unset, and the upload is silently skipped:
 
     ```bash
-    FLASHCAT_UPLOAD=1 FLASHCAT_API_KEY=your-api-key \
-      hvigorw uploadFlashcatSymbols --mode module -p module=entry@default -p product=default
+    FLASHCAT_API_KEY=your-api-key \
+      hvigorw uploadFlashcatSymbols --no-daemon \
+      --mode module -p module=entry@default -p product=default
     ```
   </Step>
 </Steps>
 
 <Warning>
+- Use **0.1.4 or later**: 0.1.3 registered the task with a dependency on `assembleHar`, which does not exist in a HAP module, and the build fails outright
 - On SaaS, omit `endpoint` — **hvigor-plugin ≥ 0.1.3** defaults to `https://ci.flashcat.cloud`. Do not use the RUM ingest host `browser.flashcat.cloud` (it 404s). For a private deployment set `FLASHCAT_SOURCEMAP_INTAKE_URL` (requires ≥ 0.1.3) or pass `endpoint` explicitly
 - Native `.so` symbolication depends on the GNU build-id. The HarmonyOS NDK enables it by default; if your build pipeline disables it, add `-Wl,--build-id` explicitly
 - For the full HarmonyOS integration, symbol-upload, and compatibility details, continue with [HarmonyOS SDK advanced configuration](/en/rum/sdk/harmony/advanced-config)

en/rum/sdk/harmony/advanced-config.mdx

@@ -431,12 +431,28 @@ The plugin uploads two artifact types:
 | ArkTS Sourcemap | `sourceMaps.map`, optional `nameCache.json` | Restores ArkTS / TS files, functions, lines, and columns |
 | Native symbols | Unstripped `.so` files | Resolves C/C++ frames by GNU build-id |
 
-The plugin ships as an npm package (on **npm**, not ohpm); install it as a build-time dev dependency in your project's root `package.json`, not in `oh-package.json5`:
+The plugin ships as an npm package (on **npm**, not ohpm). Declare it in `hvigor/hvigor-config.json5` and let hvigor fetch it from npm:
+
+```json5 hvigor/hvigor-config.json5
+{
+  "modelVersion": "5.0.0",
+  "dependencies": {
+    "@flashcatcloud/hvigor-plugin": "0.1.4"
+  }
+}
+```
+
+You can install it with npm instead. But a HarmonyOS project root has no `package.json`, and `npm install` walks *up* the directory tree looking for one — so it ends up installing into whatever unrelated project it finds in a parent directory (often your home directory). Create one first:
 
 ```bash
-npm install -D @flashcatcloud/hvigor-plugin@^0.1.3
+npm init -y                                  # only if the project root has no package.json
+npm install -D @flashcatcloud/hvigor-plugin
 ```
 
+<Warning>
+Use **0.1.4 or later**. 0.1.3 registered the upload task with dependencies on both `assembleHap` and `assembleHar`; a module has at most one of them, so the build fails outright with `Cannot find hvigor task 'assembleHar' in module 'entry'`.
+</Warning>
+
 Then register the plugin in the module's `hvigorfile.ts`:
 
 ```ts hvigorfile.ts
@@ -449,24 +465,30 @@ export default {
     flashcatSymbolUploadPlugin({
       apiKey: process.env.FLASHCAT_API_KEY ?? '',
       service: 'shopping-app',
-      version: '1.0.0',
-      enabled: process.env.FLASHCAT_UPLOAD === '1'
+      version: '1.0.0'
     })
   ]
 };
 ```
 
 <Note>
-On SaaS, omit `endpoint` — **hvigor-plugin ≥ 0.1.3** defaults to `https://ci.flashcat.cloud` (**not** the RUM ingest host `browser.flashcat.cloud`). For a private deployment set `FLASHCAT_SOURCEMAP_INTAKE_URL` (scheme + host, no path; also requires ≥ 0.1.3), or pass `endpoint: 'https://rum.example.com'`. Plugin 0.1.2 does not honour `FLASHCAT_SOURCEMAP_INTAKE_URL` — set `endpoint` explicitly, or use the legacy `FLASHCAT_ENDPOINT` env var (deprecated in 0.1.3 but still honoured). `flashcatSymbolUploadPlugin()` also accepts two optional fields: `buildDir` (build output directory, default `build/default`) and `pluginVersion` (the version sent in the `DD-EVP-ORIGIN-VERSION` upload header, which defaults to the plugin's own version). Neither is normally required.
+On SaaS, omit `endpoint` — **hvigor-plugin ≥ 0.1.3** defaults to `https://ci.flashcat.cloud` (**not** the RUM ingest host `browser.flashcat.cloud`). For a private deployment set `FLASHCAT_SOURCEMAP_INTAKE_URL` (scheme + host, no path; also requires ≥ 0.1.3), or pass `endpoint: 'https://rum.example.com'`. Plugin 0.1.2 does not honour `FLASHCAT_SOURCEMAP_INTAKE_URL` — set `endpoint` explicitly, or use the legacy `FLASHCAT_ENDPOINT` env var (deprecated in 0.1.3 but still honoured). `flashcatSymbolUploadPlugin()` also accepts two optional fields: `buildDir` and `pluginVersion` (the version sent in the `DD-EVP-ORIGIN-VERSION` upload header, which defaults to the plugin's own version). **From 0.1.4 the build directory follows the product being built** (`-p product=beta` → `build/beta`), so pass `buildDir` only when the artifacts are somewhere else; 0.1.3 and earlier always used `build/default` and silently scanned the wrong directory for any other product.
 </Note>
 
-Run the upload task after a release build:
+After a release build, run the upload task as its own hvigor invocation:
 
 ```bash
-FLASHCAT_UPLOAD=1 FLASHCAT_API_KEY=*** \
-  hvigorw uploadFlashcatSymbols --mode module -p module=entry@default -p product=default
+FLASHCAT_API_KEY=*** \
+  hvigorw uploadFlashcatSymbols --no-daemon \
+  --mode module -p module=entry@default -p product=beta
 ```
 
+<Warning>
+`--no-daemon` is not optional when you configure the plugin from environment variables. hvigor builds through a long-lived daemon process, which **copies the environment once, when it is created**, and afterwards refreshes only a fixed allowlist (`DEVECO_SDK_HOME`, `OHOS_BASE_SDK_HOME`, and two incremental-build flags). A reused daemon therefore hands the plugin the environment of whoever started it — an IDE build, or an earlier command — not the one you just typed.
+
+The failure is silent: `FLASHCAT_API_KEY` reads as unset and the upload is skipped with a single log line, or a stale key ends in a 401 — either way the build still succeeds. Values written directly into `hvigorfile.ts` are not affected.
+</Warning>
+
 The plugin sends `multipart/form-data` to `{endpoint}/sourcemap/upload`:
 
 | Header | Value |

zh/rum/error-tracking/source-mapping.mdx

@@ -211,11 +211,18 @@ HarmonyOS 崩溃栈可能同时包含 **ArkTS / JS 帧** 和 **Native `.so` 帧*
 
 <Steps>
   <Step title="安装 hvigor 插件">
-    在 HarmonyOS 工程中安装上传插件：
+    在工程的 `hvigor/hvigor-config.json5` 中声明依赖，由 hvigor 自行从 npm 拉取：
 
-    ```bash
-    npm install -D @flashcatcloud/hvigor-plugin@^0.1.3
+    ```json5 hvigor/hvigor-config.json5
+    {
+      "modelVersion": "5.0.0",
+      "dependencies": {
+        "@flashcatcloud/hvigor-plugin": "0.1.4"
+      }
+    }
     ```
+
+    也可以用 `npm install -D @flashcatcloud/hvigor-plugin` 安装，但鸿蒙工程根目录默认没有 `package.json`，需先执行 `npm init -y`，否则会装到父目录的无关工程里。详见 [HarmonyOS SDK 高级配置](/zh/rum/sdk/harmony/advanced-config)。
   </Step>
   <Step title="在 hvigorfile.ts 中注册上传插件">
     把控制台面板生成的 `service`、`version` 与 `apiKey` 配置写入 `hvigorfile.ts`：
@@ -230,24 +237,25 @@ HarmonyOS 崩溃栈可能同时包含 **ArkTS / JS 帧** 和 **Native `.so` 帧*
         flashcatSymbolUploadPlugin({
           apiKey: process.env.FLASHCAT_API_KEY ?? '',
           service: 'my-app',
-          version: '1.0.0',
-          enabled: process.env.FLASHCAT_UPLOAD === '1'
+          version: '1.0.0'
         })
       ]
     };
     ```
   </Step>
   <Step title="构建后执行上传">
-    在构建产物生成后执行上传任务：
+    在构建产物生成后执行上传任务。**用环境变量配置时必须加 `--no-daemon`**，否则 hvigor 复用的守护进程会拿到陈旧的环境变量，导致 API Key 读不到、上传被静默跳过：
 
     ```bash
-    FLASHCAT_UPLOAD=1 FLASHCAT_API_KEY=your-api-key \
-      hvigorw uploadFlashcatSymbols --mode module -p module=entry@default -p product=default
+    FLASHCAT_API_KEY=your-api-key \
+      hvigorw uploadFlashcatSymbols --no-daemon \
+      --mode module -p module=entry@default -p product=default
     ```
   </Step>
 </Steps>
 
 <Warning>
+- 请使用 **0.1.4 及以上**版本：0.1.3 注册任务时会声明不存在的 `assembleHar` 依赖，导致构建直接失败
 - 公有云省略 `endpoint` 时，**hvigor-plugin ≥ 0.1.3** 默认上传到 `https://ci.flashcat.cloud`。不要用 RUM 上报域名 `browser.flashcat.cloud`（会 404）。私有化设置 `FLASHCAT_SOURCEMAP_INTAKE_URL`（需 ≥ 0.1.3）或显式传 `endpoint`
 - Native `.so` 需要保留 GNU build-id；HarmonyOS NDK 默认开启，如你的构建链路关闭了它，请显式添加 `-Wl,--build-id`
 - 更完整的 HarmonyOS 接入、符号上传和兼容性说明，请继续阅读 [HarmonyOS SDK 高级配置](/zh/rum/sdk/harmony/advanced-config)

zh/rum/sdk/harmony/advanced-config.mdx

@@ -431,12 +431,28 @@ async onWorkStart(workInfo: workScheduler.WorkInfo): Promise<void> {
 | ArkTS Sourcemap | `sourceMaps.map`，可选 `nameCache.json` | 还原 ArkTS / TS 文件、函数、行列号 |
 | Native 符号 | 未 strip 的 `.so` 文件 | 根据 GNU build-id 解析 C/C++ 栈帧 |
 
-该插件以 npm 包发布（在 **npm**，不在 ohpm），作为构建期开发依赖安装到工程根目录的 `package.json`，而不是 `oh-package.json5`：
+该插件以 npm 包发布（在 **npm**，不在 ohpm）。推荐在 `hvigor/hvigor-config.json5` 中声明，由 hvigor 自行从 npm 拉取：
+
+```json5 hvigor/hvigor-config.json5
+{
+  "modelVersion": "5.0.0",
+  "dependencies": {
+    "@flashcatcloud/hvigor-plugin": "0.1.4"
+  }
+}
+```
+
+也可以用 npm 安装。但鸿蒙工程根目录默认**没有** `package.json`，而 `npm install` 会逐级向上查找，最终把依赖装进父目录里某个无关工程（常见是用户主目录），所以要先创建一个：
 
 ```bash
-npm install -D @flashcatcloud/hvigor-plugin@^0.1.3
+npm init -y                                  # 仅在工程根目录没有 package.json 时执行
+npm install -D @flashcatcloud/hvigor-plugin
 ```
 
+<Warning>
+请使用 **0.1.4 及以上**版本。0.1.3 在注册上传任务时同时声明了 `assembleHap` 和 `assembleHar` 两个依赖，而一个模块最多只有其中一个，会导致构建直接失败：`Cannot find hvigor task 'assembleHar' in module 'entry'`。
+</Warning>
+
 然后在模块的 `hvigorfile.ts` 中注册插件：
 
 ```ts hvigorfile.ts
@@ -449,24 +465,30 @@ export default {
     flashcatSymbolUploadPlugin({
       apiKey: process.env.FLASHCAT_API_KEY ?? '',
       service: 'shopping-app',
-      version: '1.0.0',
-      enabled: process.env.FLASHCAT_UPLOAD === '1'
+      version: '1.0.0'
     })
   ]
 };
 ```
 
 <Note>
-公有云省略 `endpoint` 时，**hvigor-plugin ≥ 0.1.3** 默认上传到 `https://ci.flashcat.cloud`（**不是** RUM 上报用的 `browser.flashcat.cloud`）。私有化部署请设置环境变量 `FLASHCAT_SOURCEMAP_INTAKE_URL`（协议 + 域名，不带路径；同样需要 ≥ 0.1.3），或传 `endpoint: 'https://rum.example.com'`。旧版 0.1.2 不认 `FLASHCAT_SOURCEMAP_INTAKE_URL`，可显式写 `endpoint`，或设置旧环境变量 `FLASHCAT_ENDPOINT`（0.1.3 起弃用，但仍生效）。`flashcatSymbolUploadPlugin()` 还接受两个可选参数：`buildDir`（构建产物目录，默认 `build/default`）和 `pluginVersion`（写入上传请求头 `DD-EVP-ORIGIN-VERSION` 的版本号，默认与插件版本一致）。一般无需设置。
+公有云省略 `endpoint` 时，**hvigor-plugin ≥ 0.1.3** 默认上传到 `https://ci.flashcat.cloud`（**不是** RUM 上报用的 `browser.flashcat.cloud`）。私有化部署请设置环境变量 `FLASHCAT_SOURCEMAP_INTAKE_URL`（协议 + 域名，不带路径；同样需要 ≥ 0.1.3），或传 `endpoint: 'https://rum.example.com'`。旧版 0.1.2 不认 `FLASHCAT_SOURCEMAP_INTAKE_URL`，可显式写 `endpoint`，或设置旧环境变量 `FLASHCAT_ENDPOINT`（0.1.3 起弃用，但仍生效）。`flashcatSymbolUploadPlugin()` 还接受两个可选参数：`buildDir` 和 `pluginVersion`（写入上传请求头 `DD-EVP-ORIGIN-VERSION` 的版本号，默认与插件版本一致）。**0.1.4 起产物目录会自动跟随构建的 product**（`-p product=beta` → `build/beta`），只有产物不在该位置时才需要传 `buildDir`；0.1.3 及更早固定使用 `build/default`，构建非 default product 时会静默扫描到错误的目录。
 </Note>
 
-发布构建后执行上传任务：
+发布构建完成后，把上传任务作为一次独立的 hvigor 调用执行：
 
 ```bash
-FLASHCAT_UPLOAD=1 FLASHCAT_API_KEY=*** \
-  hvigorw uploadFlashcatSymbols --mode module -p module=entry@default -p product=default
+FLASHCAT_API_KEY=*** \
+  hvigorw uploadFlashcatSymbols --no-daemon \
+  --mode module -p module=entry@default -p product=beta
 ```
 
+<Warning>
+用环境变量配置插件时，`--no-daemon` 不是可选项。hvigor 默认通过常驻的守护进程构建，该进程**只在创建时拷贝一次环境变量**，之后仅刷新固定白名单（`DEVECO_SDK_HOME`、`OHOS_BASE_SDK_HOME` 及两个增量构建开关）。因此复用守护进程时，插件读到的是**启动那个守护进程的人**的环境变量——可能来自 IDE 构建，也可能来自你上一条命令——而不是你刚敲进去的这份。
+
+失败是静默的：`FLASHCAT_API_KEY` 读不到就跳过上传（只打一行日志），旧的 Key 则会以 401 结束——两种情况构建都照样成功。直接写在 `hvigorfile.ts` 里的值不受影响。
+</Warning>
+
 插件会向 `{endpoint}/sourcemap/upload` 发送 `multipart/form-data`：
 
 | Header | 值 |