dsh-harmonyos-hiboard 0.7.0 → 0.7.2

package/README.md

@@ -142,7 +142,8 @@ dsh plugin --profile web add "file:<不含空格的路径>"
 
 **2) 填授权码** —— 两种方式，任选其一。
 
-**方式 A（推荐）：图形界面。** 重启 dsh 后打开 **设置 → 插件 → `dsh-harmonyos-hiboard`**，
+**方式 A（推荐）：图形界面。** 重启 dsh 后打开 **主界面左侧栏的「插件」面板 →
+`dsh-harmonyos-hiboard` → 点进它的页面**（**不在「设置」里**，见下方「设置卡片」一节），
 在「推送设置」卡片里填写。输入框**两种写法都认**：
 
 ```text
@@ -199,14 +200,35 @@ L2 抢救"承诺了却没调用"、L3 按错误类别重试并自动补 `schedul
 
 ---
 
-## 设置页（插件卡片）
+## 设置卡片（在「插件」面板里）
 
-打开 **设置 → 插件 → `dsh-harmonyos-hiboard`**，卡片提供两件事：
+打开 **主界面左侧栏的「插件」面板 → `dsh-harmonyos-hiboard` → 点进它的页面**，
+「推送设置」卡片就在简介与条目行之间。
+
+> **注意不是「设置」里。** dsh 的设置导航里那个「内置插件」页只提供只读清单与市场页签，
+> 它**不声明** `plugins.bundle.config` 插槽 —— 这条卡片永远不可能出现在那里。
+> 承载配置卡片的是 `dsh-client-ui-plugin-manager`（侧栏面板 id `plugins`，文案「插件」），
+> 本插件与 modsearch 的卡片都在同一个位置。
+> 新装或升级后如果没看到卡片，**先刷新页面**；**版本升级还需重启 dsh**（已挂载的插件不会被热替换）。
+
+卡片提供三件事：
 
 1. **授权码输入框** —— 裸授权码与整条关联指令都认（自动取末尾的码），保存前显示打码预览，
    保存后**立即生效**；卡片还显示**当前生效来源**（设置页 / 补丁层 / 环境变量），
    避免"改了一处却不生效"。点「清除」删掉设置页那份，回退到下一层。
 2. **推送兜底开关** —— **默认开启**，关掉**立即生效**（不必重启）。
+   文案里也直说了：建议保持开启。
+3. **兜底战绩** —— 列出**「原本没推出去、但兜底救回来了」**的次数与最近几次，
+   数据来自兜底自己的审计流水（`<状态目录>/audit.jsonl`）：
+   - `retry-ok`：工具真的调用了但失败，按错误类别重试后成功
+   - `rescue-ok`：根本没调用工具（写成纯文本 / 只承诺没做），兜底代为补推
+
+   **关掉兜底后面板不会消失**，而是改显示「**漏掉未推送 N 次**」——
+   兜底关闭期间它不再补推，但**继续记账**（记成 `missed`）：本该补推的（写成纯文本 /
+   只承诺没调用）以及调用失败却没重试的，都会被记下来。
+   关掉它的代价应该看得见，而不是等你发现卡片少了几张。
+
+   这个面板的意义是：以前"保险丝到底有没有干活"只能靠猜，现在直接列给你看。
 
 配置写在 `<用户目录>/.dsh/hiboard-push/config.json`（0600，先写临时文件再原子替换）。
 该文件属于当前系统用户，本机所有 dsh profile 共用一份。
@@ -358,6 +380,35 @@ npm test
 
 ---
 
+## 新环境部署清单（怎么对齐到「每轮都推送」）
+
+换一台电脑、或让别人从零装一遍，**装完插件只是一半**。完整清单：
+
+| # | 做什么 | 不做会怎样 |
+|---|---|---|
+| 1 | 装插件：`dsh plugin --profile web add dsh-harmonyos-hiboard` | 没有工具 |
+| 2 | 配授权码（设置卡片，或 profile 补丁层） | 调用时报「未配置授权码」 |
+| 3 | **把推送规则写进 `~/.dsh/AGENTS.md`** | 功能在，但**没人调用它** —— 每轮都不会推 |
+| 4 | 重启 dsh | 新装/升级的插件不生效（升级不会热替换已挂载插件） |
+
+第 3 步的现成模板见 **[`docs/AGENTS-rule.md`](docs/AGENTS-rule.md)**：dsh 由
+`dsh-agent-instructions` 在**每个会话**自动加载 `$DSH_HOME/AGENTS.md`，写在那里就是全局生效。
+
+> ⚠️ **「每轮必定推送」不是插件能保证的事，要如实理解。**
+> `hiboard_push` 是一个**工具**，工具不会自己调用 —— 调不调用由模型按指令决定。
+> 内置兜底把「漏推」的概率压得很低，但它是**启发式**，不是硬保证：
+> - L1/L2 需要正文里**看得出推送意图**才会补推（保守优先，宁可少推也不乱推）；
+> - L3 只对**可重试**的失败生效（授权码无效、内容超长这类永久错误不重试）；
+> - 授权码未配置、或端点处于坏窗口且重试预算用尽时，仍然推不出去。
+>
+> 准确的表述是：**规则 + 兜底让「每轮都推」在实践上基本成立**，而不是被保证。
+
+**不必迁移、与本插件无关的东西**：本机网络入口（局域网 3081 / tailnet 8443 / 公网 18443）、
+token 广播、Steam++ 之类的 hosts 加速器 —— 那些属于本机环境。
+本插件只需要：Node 18+、pnpm、一台能取到授权码的华为手机。
+
+---
+
 ## 兼容性
 
 | 组件 | 版本 |

package/docs/DEPLOY.md

@@ -51,7 +51,8 @@ dsh plugin --profile web add "file:E:/dsh-vendor/dsh-harmonyos-hiboard"
 
 ## 第 3 步：写入授权码
 
-**推荐做法（图形界面）**：不用命令行 —— 打开 **设置 → 插件 → `dsh-harmonyos-hiboard`**，
+**推荐做法（图形界面）**：不用命令行 —— 打开 **主界面侧栏的「插件」面板 →
+`dsh-harmonyos-hiboard` → 点进它的页面**（**不在「设置」里**，见 README「设置卡片」一节），
 在「推送设置」卡片里填。输入框**裸授权码**和**整条关联指令**
 （`openclaw config set skills.entries.today-task.config.authCode <AUTH_CODE>`）都认，
 保存后立即生效，并显示当前生效来源。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-harmonyos-hiboard",
-  "version": "0.7.0",
-  "description": "把 dsh 的任务结果推送到华为鸿蒙负一屏服务卡片；设置页可直接粘贴关联指令；内置推送兜底，默认开启。 ｜ Push dsh task results to Huawei HarmonyOS assistant-today cards, with a settings card and a push safety net that is on by default.",
+  "version": "0.7.2",
+  "description": "把DSH的任务结果，以服务卡片形式推送到华为鸿蒙负一屏 ｜ Push DSH task results to the Huawei HarmonyOS assistant-today screen as service cards.",
   "author": "Jim Chen",
   "license": "MIT",
   "repository": {

package/src/lib/client.js

@@ -101,8 +101,13 @@ window.__ModuleLoader__.load({
         },
         debugEmpty: '还没有需要兜底的记录 —— 每次推送都成功调用了工具。',
         debugNone: '兜底还没有运行记录。',
+        debugMissedSummary: function (c) {
+          return '兜底已关闭 —— 期间漏掉未推送 ' + c.missed + ' 次';
+        },
+        debugMissedEmpty: '兜底关闭期间还没有漏推记录。',
         kindRetry: '重试',
         kindRescue: '补推',
+        kindMissed: '漏推',
         loadFailed: '读取配置失败',
         saveFailed: '保存失败',
         unavailable: '设置路由不可用（宿主未提供）。'
@@ -139,8 +144,13 @@ window.__ModuleLoader__.load({
         },
         debugEmpty: 'Nothing needed rescuing yet — every push called the tool successfully.',
         debugNone: 'The safety net has no run records yet.',
+        debugMissedSummary: function (c) {
+          return 'Safety net is off — ' + c.missed + ' pushes have gone missing since';
+        },
+        debugMissedEmpty: 'Nothing has gone missing while the net was off.',
         kindRetry: 'retry',
         kindRescue: 'rescue',
+        kindMissed: 'missed',
         loadFailed: 'Could not load the configuration',
         saveFailed: 'Could not save',
         unavailable: 'The settings route is unavailable (host did not provide it).'
@@ -323,26 +333,48 @@ window.__ModuleLoader__.load({
           preview = h('div', { style: { marginTop: '6px', fontSize: '12px', color: V.danger } }, t.invalid);
         }
 
-        // ---- 兜底战绩：把「原本没推出去、但兜底救回来了」摆出来 ----
+        // ---- 战绩面板 ----
+        // 兜底**开着**：显示「救回了几次」。
+        // 兜底**关掉**：面板不消失，改显示「漏掉了几张」—— 关掉它的代价要看得见，
+        // 否则用户只会觉得"关了就关了"，直到发现卡片少了几张。
+        var guardOn = Boolean(guard && guard.enabled);
+        var itemRows = function (items, kindOf) {
+          return (items || []).map(function (item, index) {
+            return h(
+              'div',
+              { key: String(index), style: { fontSize: '12px', lineHeight: '1.7', color: V.sub } },
+              '· ' + shortTime(item.at) + '　[' + kindOf(item) + '] ' + (item.label || '-') + ' — ' + item.detail
+            );
+          });
+        };
+        var boldLine = function (text) {
+          return h('div', { style: { fontSize: '12px', fontWeight: 600, marginBottom: '4px' } }, text);
+        };
         var debugBody;
         if (!audit) {
           debugBody = muted(t.debugNone);
-        } else if (!audit.exists || audit.counts.retryOk + audit.counts.rescueOk === 0) {
-          debugBody = muted(t.debugEmpty);
+        } else if (guardOn) {
+          debugBody =
+            !audit.exists || audit.counts.retryOk + audit.counts.rescueOk === 0
+              ? muted(t.debugEmpty)
+              : h(
+                  'div',
+                  null,
+                  boldLine(t.debugSummary(audit.counts)),
+                  itemRows(audit.recent, function (item) {
+                    return item.kind === 'retry-ok' ? t.kindRetry : t.kindRescue;
+                  })
+                );
         } else {
-          debugBody = h(
-            'div',
-            null,
-            h('div', { style: { fontSize: '12px', fontWeight: 600, marginBottom: '4px' } }, t.debugSummary(audit.counts)),
-            (audit.recent || []).map(function (item, index) {
-              return h(
-                'div',
-                { key: String(index), style: { fontSize: '12px', lineHeight: '1.7', color: V.sub } },
-                '· ' + shortTime(item.at) + '　[' + (item.kind === 'retry-ok' ? t.kindRetry : t.kindRescue) + '] ' +
-                  (item.label || '-') + ' — ' + item.detail
-              );
-            })
-          );
+          debugBody =
+            !audit.exists || audit.counts.missed === 0
+              ? muted(t.debugMissedEmpty)
+              : h(
+                  'div',
+                  null,
+                  boldLine(t.debugMissedSummary(audit.counts)),
+                  itemRows(audit.missedRecent, function () { return t.kindMissed; })
+                );
         }
 
         return h(

package/src/lib/index.js

@@ -348,7 +348,7 @@ function hiboardPushTool({ resolveAuthCode, settings }) {
 			const authCode = resolveAuthCode();
 			if (!authCode) {
 				throw new Error(
-					"hiboard_push: 未配置授权码（authCode）。请在 dsh 的「插件」页打开本插件的设置卡片填写" +
+					"hiboard_push: 未配置授权码（authCode）。请打开 dsh 侧栏的「插件」面板 → 本插件 → 在「推送设置」卡片里填写" +
 					"（支持整条关联指令或裸授权码），或写进 profile 补丁层 hiboard-push.config.authCode，" +
 					`或设置环境变量 ${AUTH_CODE_ENV}。授权码获取：负一屏 → 我的 → 动态管理 → 关联账号 → Claw 智能体。`
 				);
@@ -388,7 +388,7 @@ function hiboardVerifyTool({ resolveAuthCode, settings }) {
 			const authCode = resolveAuthCode();
 			if (!authCode) {
 				throw new Error(
-					"hiboard_verify: 未配置授权码（authCode）。请在 dsh 的「插件」页打开本插件的设置卡片填写" +
+					"hiboard_verify: 未配置授权码（authCode）。请打开 dsh 侧栏的「插件」面板 → 本插件 → 在「推送设置」卡片里填写" +
 					"（支持整条关联指令或裸授权码），或写进 profile 补丁层 hiboard-push.config.authCode，" +
 					`或设置环境变量 ${AUTH_CODE_ENV}。授权码获取：负一屏 → 我的 → 动态管理 → 关联账号 → Claw 智能体。`
 				);
@@ -446,7 +446,7 @@ function buildConfigRoute({ authCodeInfo, settings, storeFile }) {
 	 */
 	const auditSummary = () => {
 		const file = join(GUARD_STATE_DIR, "audit.jsonl");
-		const empty = { file, exists: false, counts: { retryOk: 0, rescueOk: 0, failed: 0 }, recent: [] };
+		const empty = { file, exists: false, counts: { retryOk: 0, rescueOk: 0, failed: 0, missed: 0 }, recent: [], missedRecent: [] };
 		let text;
 		try {
 			text = readFileSync(file, "utf8");
@@ -455,8 +455,16 @@ function buildConfigRoute({ authCodeInfo, settings, storeFile }) {
 			return empty;
 		}
 		const lines = text.split("\n").filter(Boolean).slice(-AUDIT_MAX_LINES);
-		const counts = { retryOk: 0, rescueOk: 0, failed: 0 };
+		const counts = { retryOk: 0, rescueOk: 0, failed: 0, missed: 0 };
 		const recent = [];
+		const missedRecent = [];
+		/** missed 的原因码 → 面板上的说法。 */
+		const MISSED_REASON = {
+			"literal-text-unrescued": "模型把调用写成了纯文本（兜底已关闭，未补推）",
+			"broken-promise-unrescued": "模型承诺了推送却没调用工具（兜底已关闭，未补推）",
+			"failed-retryable-unretried": "调用失败，本可重试（兜底已关闭，未重试）",
+			"failed-permanent": "调用永久失败（兜底不会重试这类错误）"
+		};
 		for (const line of lines) {
 			let row;
 			try {
@@ -484,13 +492,24 @@ function buildConfigRoute({ authCodeInfo, settings, storeFile }) {
 					label: row.name ?? "",
 					detail: row.level === "L1" ? "模型把调用写成了纯文本" : "模型承诺了推送却没调用工具"
 				});
+			} else if (row?.kind === "missed") {
+				// 兜底关闭期间"本该补推 / 本该重试"的记录：这是关掉它的代价，要看得到
+				counts.missed += 1;
+				missedRecent.push({
+					kind: "missed",
+					at: row.at ?? "",
+					level: row.level ?? "",
+					label: row.name ?? "",
+					detail: MISSED_REASON[row.reason] ?? String(row.reason ?? "未推送")
+				});
 			} else if (row?.kind === "push-failed" || row?.kind === "rescue-failed" || row?.kind === "rescue-error") {
 				counts.failed += 1;
 			}
 		}
 		// 文件是追加写的，末尾最新；面板要「最近几次」，所以倒序后取前几条
 		recent.reverse();
-		return { file, exists: true, counts, recent: recent.slice(0, 5) };
+		missedRecent.reverse();
+		return { file, exists: true, counts, recent: recent.slice(0, 5), missedRecent: missedRecent.slice(0, 5) };
 	};
 
 	const summary = () => {

package/src/lib/push-guard.js

@@ -546,8 +546,9 @@ export function apply(ctx, config) {
 		ctx.effect(() => {
 			const onEvent = (session, event) => {
 				try {
-					// 设置页关掉后，兜底立即停止（不必重启）
-					if (guardOff()) return;
+					// 注意：**关掉兜底后这个处理器仍要继续跑**。它不再补推，但仍要记账
+					// （见下面的 missed）——「关掉期间漏掉多少张卡片」只有继续观察才数得出来，
+					// 否则设置页那一栏永远是空的。
 					if (!event || typeof event !== "object") return;
 					const sessionId = session?.id ?? "?";
 
@@ -584,6 +585,25 @@ export function apply(ctx, config) {
 						}
 						return;
 					}
+
+					// 兜底被关掉时：**不补推，但照样记账**。
+					// 记成 missed 而不是 rescue-ok —— 设置页据此显示「关掉期间漏掉 N 张」。
+					// 关掉兜底的代价应该是看得见的，而不是悄悄少几张卡片。
+					if (guardOff()) {
+						audit({
+							kind: "missed",
+							level: card.level,
+							name: card.name,
+							sessionId,
+							turn: current.turn,
+							reason: card.level === "L1" ? "literal-text-unrescued" : "broken-promise-unrescued"
+						});
+						ctx.logger?.warn?.(
+							"[push-guard] ⚠️ %s 本该补推（会话 %s 第 %s 轮）：%s —— 但兜底已关闭，仅记账未推送",
+							card.level, sessionId, current.turn ?? "?", card.name
+						);
+						return;
+					}
 					const fingerprint = `${card.name}\n${card.content.length}\n${card.content.slice(0, 80)}`;
 					if (lastRescued.get(sessionId) === fingerprint) return;
 					lastRescued.set(sessionId, fingerprint);
@@ -639,8 +659,31 @@ export function apply(ctx, config) {
 					const ambiguousAttempts = ambiguousBudget;
 					const fallbackScheduleId = String(settings.defaultScheduleId || DEFAULTS.defaultScheduleId).trim() || DEFAULTS.defaultScheduleId;
 					const wrapped = async (args, exec) => {
-						// 设置页关掉后：不补参、不重试，按原样调用（关闭必须真的关闭）
-						if (guardOff()) return original(args, exec);
+						// 设置页关掉后：不补参、不重试，按原样调用（关闭必须真的关闭）。
+						// 但**照样给失败记账**：调用失败了却没重试，就是"漏掉一张"。
+						if (guardOff()) {
+							const outcome = await original(args, exec);
+							try {
+								const verdict = classifyPush(outcome);
+								if (!verdict.ok) {
+									audit({
+										kind: "missed",
+										level: "L3",
+										name: String(args?.name ?? ""),
+										reason: verdict.retryable ? "failed-retryable-unretried" : "failed-permanent",
+										code: verdict.code ?? "",
+										message: String(verdict.message ?? "").slice(0, 160)
+									});
+									ctx.logger?.warn?.(
+										"[push-guard] ⚠️ hiboard_push 失败（%s，%s）—— 兜底已关闭，未重试，仅记账",
+										verdict.code || "-", verdict.retryable ? "本可重试" : "永久错误"
+									);
+								}
+							} catch {
+								/* 记账失败不影响工具本身的返回 */
+							}
+							return outcome;
+						}
 						// ---- 先补 schedule_id，再让工具校验/发送 ----
 						// 为什么必须补：scheduleTaskId 为空时负一屏**只显示一行标题**，
 						// 正文不渲染、详情页点不开（2026-09-27 用户实际遇到）。