dsh-harmonyos-hiboard 0.7.1 → 0.8.0

package/README.md

@@ -223,8 +223,34 @@ L2 抢救"承诺了却没调用"、L3 按错误类别重试并自动补 `schedul
    - `retry-ok`：工具真的调用了但失败，按错误类别重试后成功
    - `rescue-ok`：根本没调用工具（写成纯文本 / 只承诺没做），兜底代为补推
 
+   **关掉兜底后面板不会消失**，而是改显示「**漏掉未推送 N 次**」——
+   兜底关闭期间它不再补推，但**继续记账**（记成 `missed`）：本该补推的（写成纯文本 /
+   只承诺没调用）以及调用失败却没重试的，都会被记下来。
+   关掉它的代价应该看得见，而不是等你发现卡片少了几张。
+
    这个面板的意义是：以前"保险丝到底有没有干活"只能靠猜，现在直接列给你看。
 
+4. **常驻推送规则**（默认开启）—— **保存授权码时，会把「每轮回答都要推送」自动写进
+   全局指令文件 `$DSH_HOME/AGENTS.md`**，这样「一键安装 + 粘一次授权码」之后就不必再
+   手改任何文件，新会话立刻按规则推送。
+
+   > ⚠️ **这是本插件唯一会改动你已有文件的行为，且明确声明在此。** 具体约束：
+   > - 规则被 **BEGIN/END 标记**包裹，插件**只改标记之间那一段**，标记之外一个字节都不动；
+   > - **幂等**：重复保存不会产生第二份规则；
+   > - **首次改动前自动备份** `AGENTS.md.bak-hiboard-<时间戳>`（只备份一次）；
+   > - **检测到你已手写过推送规则就完全跳过**，并如实提示，而不是硬塞第二份；
+   > - 卡片上那颗开关可以**一键移除**该段（其余内容原样保留），关掉后再保存授权码也不会重新写入。
+
+   **为什么必须写这个文件**：dsh 的 `dsh-agent-instructions` 每个会话都加载
+   `$DSH_HOME/AGENTS.md`，而且**只认这一个全局文件** —— `.local` 叠加（`AGENTS.local.md`）
+   只在**项目目录**的祖先链里生效，全局那段代码写死了只探测 `AGENTS.md`。
+   （`agent/pre-step` 注入要拼宿主内部消息形状，在预览版上太脆，所以没有采用。）
+
+   > **授权码仍然必须手动粘一次**，这一点无法自动化：它是你在手机上
+   > 「负一屏 → 我的 → 动态管理 → 关联账号 → Claw 智能体」取到的**个人凭据**，
+   > 任何插件都不可能凭空得到它。所以准确说法是：安装后规则自动就位，
+   > 你只需**在卡片里粘一次授权码**。
+
 配置写在 `<用户目录>/.dsh/hiboard-push/config.json`（0600，先写临时文件再原子替换）。
 该文件属于当前系统用户，本机所有 dsh profile 共用一份。
 
@@ -383,7 +409,7 @@ npm test
 |---|---|---|
 | 1 | 装插件：`dsh plugin --profile web add dsh-harmonyos-hiboard` | 没有工具 |
 | 2 | 配授权码（设置卡片，或 profile 补丁层） | 调用时报「未配置授权码」 |
-| 3 | **把推送规则写进 `~/.dsh/AGENTS.md`** | 功能在，但**没人调用它** —— 每轮都不会推 |
+| 3 | 保存授权码 —— 插件会把推送规则**自动**写进 `~/.dsh/AGENTS.md`（默认开启、可一键关掉） | 功能在，但**没人调用它** —— 每轮都不会推 |
 | 4 | 重启 dsh | 新装/升级的插件不生效（升级不会热替换已挂载插件） |
 
 第 3 步的现成模板见 **[`docs/AGENTS-rule.md`](docs/AGENTS-rule.md)**：dsh 由

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-harmonyos-hiboard",
-  "version": "0.7.1",
-  "description": "把DSH的任务结果，以服务卡片形式推送到华为鸿蒙负一屏\nPush DSH task results to the Huawei HarmonyOS assistant-today screen as service cards.",
+  "version": "0.8.0",
+  "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/agents-rule.js

@@ -0,0 +1,145 @@
+/**
+ * 常驻推送规则：把「每轮回答都要推送」写进 dsh 的全局指令文件。
+ *
+ * ## 为什么必须动这个文件
+ *
+ * dsh 的 `dsh-agent-instructions` 在每个会话自动加载 `$DSH_HOME/AGENTS.md`。
+ * 它**只认这一个全局文件** —— `.local` 叠加（`AGENTS.local.md`）只在**项目目录**的
+ * 祖先链里生效，全局那段代码写死了只探测 `AGENTS.md`（见 dsh-agent-instructions
+ * 的 `discoverInstructionFiles`）。所以想让规则对所有会话、所有项目生效，
+ * 除了写这个文件没有第二条路（`agent/pre-step` 注入要拼宿主内部消息形状，预览版上太脆）。
+ *
+ * ## 安全约定（每一条都是必须的）
+ *
+ * 1. **只改自己那一段**：规则块由 BEGIN/END 标记包裹，标记之外一个字节都不碰。
+ * 2. **幂等**：标记已存在就原地替换；重复调用不会产生第二份规则。
+ * 3. **不覆盖用户手写的规则**：文件里已有等价规则（非标记块）时**直接跳过**，
+ *    并如实报告，而不是硬塞一份重复的。
+ * 4. **首次改动前备份**：`AGENTS.md.bak-hiboard-<时间戳>`，且只备份一次，不刷屏。
+ * 5. **可一键移除**：`removeRule()` 把标记块整段删掉，其余内容原样保留。
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, readdirSync } from "node:fs";
+import { basename, dirname } from "node:path";
+
+/** 规则块的起止标记。改这里等于改契约，不要动。 */
+export const RULE_BEGIN = "<!-- BEGIN dsh-harmonyos-hiboard (managed block; the plugin rewrites this region) -->";
+export const RULE_END = "<!-- END dsh-harmonyos-hiboard -->";
+
+/** 规则块正文。中英并列：dsh 的全局文件对所有会话生效，读者可能是任意语言。 */
+export function buildRuleBlock() {
+	return [
+		RULE_BEGIN,
+		"## 强制要求：每轮回答都要推送到手机负一屏",
+		"",
+		"1. 给出最终回答时，调用 `hiboard_push` 推送本轮的详细结论。",
+		"2. **必须传 `schedule_id`**（例如 `dsh_worklog`）—— 它为空时卡片只有一行标题、正文不渲染、也点不开。",
+		"3. `content` 用 Markdown，**上限 5000 字符**；超长就推精简版，并在开头注明被截断，完整内容留在对话里。",
+		"4. `result` 是状态标签，默认「任务已完成」。",
+		"5. 本轮确实没有实质输出时，也推一张简短卡片，不要跳过。",
+		"6. 推送失败要写明原因（未配置授权码 / 接口不通），不要静默略过。",
+		"",
+		"> Every turn must push: call `hiboard_push` with a non-empty `schedule_id`; Markdown body is",
+		"> capped at 5000 characters; push a short card even on a thin turn; never fail silently.",
+		"",
+		"（本段由 dsh-harmonyos-hiboard 维护，可在插件的设置卡片里一键关闭与移除。）",
+		RULE_END
+	].join("\n");
+}
+
+/** 判定文件里是否已存在「等价规则」（非本插件标记块）。 */
+export function looksLikePushRule(text) {
+	if (!/hiboard_push/.test(text)) return false;
+	return /(每轮|每一轮|每次|每一条|必须)[^\n]{0,24}(推|发送|推送)/.test(text) || /every\s+(turn|reply|response)/i.test(text);
+}
+
+function readText(file) {
+	try {
+		return readFileSync(file, "utf8");
+	} catch {
+		return "";
+	}
+}
+
+function hasBackup(file) {
+	try {
+		return readdirSync(dirname(file)).some((name) => name.startsWith(`${basename(file)}.bak-hiboard-`));
+	} catch {
+		return false;
+	}
+}
+
+/** 原子写入；`backup` 为真且尚无备份时，先留一份原件。 */
+function writeText(file, text, { backup = false } = {}) {
+	mkdirSync(dirname(file), { recursive: true });
+	if (backup && existsSync(file) && !hasBackup(file)) {
+		try {
+			copyFileSync(file, `${file}.bak-hiboard-${new Date().toISOString().replace(/[-:T]/g, "").slice(0, 15)}`);
+		} catch {
+			/* 备份失败不阻止写入：用户要的是规则生效，不是备份成功 */
+		}
+	}
+	const tmp = `${file}.${process.pid}.tmp`;
+	writeFileSync(tmp, text, "utf8");
+	renameSync(tmp, file);
+}
+
+/** 用新块替换旧块（保留前后一切内容）。 */
+function replaceBlock(text, block) {
+	const start = text.indexOf(RULE_BEGIN);
+	const end = text.indexOf(RULE_END);
+	if (start < 0 || end < 0 || end < start) return text;
+	return `${text.slice(0, start)}${block}${text.slice(end + RULE_END.length)}`;
+}
+
+/** 状态：文件在哪、有没有我们的块、有没有用户自己写的等价规则。 */
+export function ruleStatus(file) {
+	const text = readText(file);
+	const hasBlock = text.includes(RULE_BEGIN) && text.includes(RULE_END);
+	return {
+		file,
+		exists: existsSync(file),
+		block: hasBlock,
+		customRule: !hasBlock && looksLikePushRule(text)
+	};
+}
+
+/**
+ * 确保规则就位（幂等）。
+ * @returns {{action: 'added'|'updated'|'unchanged'|'skipped-custom', status: object}}
+ */
+export function ensureRule(file) {
+	const block = buildRuleBlock();
+	const before = readText(file);
+	const hasBlock = before.includes(RULE_BEGIN) && before.includes(RULE_END);
+
+	if (hasBlock) {
+		const next = replaceBlock(before, block);
+		if (next === before) return { action: "unchanged", status: ruleStatus(file) };
+		writeText(file, next);
+		return { action: "updated", status: ruleStatus(file) };
+	}
+
+	// 用户自己已经写过等价规则 → 不硬塞第二份
+	if (looksLikePushRule(before)) return { action: "skipped-custom", status: ruleStatus(file) };
+
+	const body = before.replace(/\s*$/, "");
+	const next = body ? `${body}\n\n${block}\n` : `${block}\n`;
+	writeText(file, next, { backup: true });
+	return { action: "added", status: ruleStatus(file) };
+}
+
+/**
+ * 移除规则块（只删标记之间那一段）。
+ * @returns {{action: 'removed'|'absent', status: object}}
+ */
+export function removeRule(file) {
+	const before = readText(file);
+	if (!before.includes(RULE_BEGIN)) return { action: "absent", status: ruleStatus(file) };
+	const start = before.indexOf(RULE_BEGIN);
+	const end = before.indexOf(RULE_END);
+	let next = `${before.slice(0, start)}${before.slice(end + RULE_END.length)}`;
+	// 清掉移除后留下的空行堆，但不动其它内容
+	next = next.replace(/\n{3,}/g, "\n\n").replace(/^\s*\n/, "");
+	writeText(file, next);
+	return { action: "removed", status: ruleStatus(file) };
+}

package/src/lib/client.js

@@ -95,14 +95,25 @@ window.__ModuleLoader__.load({
         guardBudget: function (g) {
           return '重试预算：确定未送达 ' + g.retryCount + ' 次 / 可能已送达 ' + g.ambiguousRetryCount + ' 次　·　schedule_id 兜底：' + g.defaultScheduleId;
         },
+        ruleTitle: '常驻推送规则',
+        ruleOn: '已启用',
+        ruleOff: '未启用',
+        ruleHint: '保存授权码时，会自动把「每轮都要推送」写进全局指令文件 AGENTS.md（带标记、可随时移除），新会话即生效。',
+        ruleCustom: '检测到你已手写过推送规则 —— 插件不会改动你的 AGENTS.md。',
+        ruleBlockPresent: 'AGENTS.md 里已有本插件维护的规则段（带标记；关掉即可移除）。',
         debugTitle: '兜底战绩',
         debugSummary: function (c) {
           return '已救回 ' + (c.retryOk + c.rescueOk) + ' 次（重试 ' + c.retryOk + ' · 补推 ' + c.rescueOk + '）';
         },
         debugEmpty: '还没有需要兜底的记录 —— 每次推送都成功调用了工具。',
         debugNone: '兜底还没有运行记录。',
+        debugMissedSummary: function (c) {
+          return '兜底已关闭 —— 期间漏掉未推送 ' + c.missed + ' 次';
+        },
+        debugMissedEmpty: '兜底关闭期间还没有漏推记录。',
         kindRetry: '重试',
         kindRescue: '补推',
+        kindMissed: '漏推',
         loadFailed: '读取配置失败',
         saveFailed: '保存失败',
         unavailable: '设置路由不可用（宿主未提供）。'
@@ -133,14 +144,25 @@ window.__ModuleLoader__.load({
         guardBudget: function (g) {
           return 'Retry budget: definitely-undelivered ' + g.retryCount + ' / possibly-delivered ' + g.ambiguousRetryCount + '　·　schedule_id fallback: ' + g.defaultScheduleId;
         },
+        ruleTitle: 'Always-push rule',
+        ruleOn: 'enabled',
+        ruleOff: 'disabled',
+        ruleHint: 'Saving the authCode also writes an "every turn must push" rule into your global instruction file AGENTS.md (marker-delimited, removable); new sessions pick it up.',
+        ruleCustom: 'You already wrote a push rule by hand, so this plugin leaves AGENTS.md untouched.',
+        ruleBlockPresent: "AGENTS.md already carries this plugin's rule block (marker-delimited; switch this off to remove it).",
         debugTitle: 'Rescues so far',
         debugSummary: function (c) {
           return 'Saved ' + (c.retryOk + c.rescueOk) + ' (retries ' + c.retryOk + ', pushes ' + c.rescueOk + ')';
         },
         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).'
@@ -254,6 +276,7 @@ window.__ModuleLoader__.load({
         var info = summary.data && summary.data.authCode;
         var guard = summary.data && summary.data.guard;
         var audit = summary.data && summary.data.audit;
+        var rule = summary.data && summary.data.rule;
 
         var onSave = function () {
           if (!draft.trim()) { setNote(t.emptyErr); return; }
@@ -277,6 +300,14 @@ window.__ModuleLoader__.load({
             setNote((data.notes && data.notes[0]) || '');
           });
         };
+        var onToggleRule = function (next) {
+          setBusy('rule');
+          setNote('');
+          post({ ruleEnabled: next }).then(function (data) {
+            setBusy('');
+            if (data && data.notes && data.notes[0]) setNote(data.notes[0]);
+          });
+        };
         var onToggleGuard = function (next) {
           setBusy('guard');
           setNote('');
@@ -323,26 +354,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(
@@ -429,6 +482,26 @@ window.__ModuleLoader__.load({
               ),
               showDebug ? h('div', { style: { marginTop: '4px' } }, debugBody) : null
             )
+          ),
+
+          // ---- 常驻推送规则：保存授权码时自动写进全局指令文件 ----
+          h(
+            'div',
+            { style: { marginTop: '14px', paddingTop: '12px', borderTop: '1px solid ' + V.border } },
+            row([
+              h('span', { style: { fontWeight: 600 } }, t.ruleTitle),
+              h('span', { style: { color: V.sub } }, rule && rule.enabled ? t.ruleOn : t.ruleOff),
+              h(Switch, {
+                checked: Boolean(rule && rule.enabled),
+                onChange: onToggleRule,
+                label: t.ruleTitle,
+                disabled: busy === 'rule' || !rule
+              })
+            ]),
+            muted(
+              rule && rule.customRule ? t.ruleCustom : rule && rule.block ? t.ruleBlockPresent : t.ruleHint,
+              { marginTop: '6px' }
+            )
           )
         );
       };

package/src/lib/index.js

@@ -34,6 +34,7 @@ import { join } from "node:path";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import z from "@deepseek-ai/schemastery";
 import { maskAuthCode, parseAuthCodeInput } from "./authcode.js";
+import { ensureRule, removeRule, ruleStatus } from "./agents-rule.js";
 import { configPath, readStore, writeStore } from "./config-store.js";
 import { apply as applyPushGuard } from "./push-guard.js";
 
@@ -74,6 +75,22 @@ const GUARD_STATE_DIR = join(homedir(), ".dsh", "lan", "push-guard");
 /** 调试图最多回溯多少条审计（文件本身有大小上限，读全量没必要）。 */
 const AUDIT_MAX_LINES = 4000;
 
+/**
+ * dsh 的全局指令文件。`dsh-agent-instructions` 每个会话都加载它 ——
+ * 而且**只认这一个全局文件**：`.local` 叠加（`AGENTS.local.md`）只在**项目目录**的
+ * 祖先链里生效，全局那段代码写死了只探测 `AGENTS.md`。所以「每轮都推」这条规则
+ * 想对所有会话、所有项目生效，只能写在这里。
+ */
+const AGENTS_FILE = join(process.env.DSH_HOME || join(homedir(), ".dsh"), "AGENTS.md");
+
+/** 规则写入的结果 → 卡片上的提示语。 */
+const RULE_NOTE = {
+	added: "已把「每轮都要推送」写进全局指令文件 AGENTS.md，新会话即生效。",
+	updated: "已更新 AGENTS.md 里的推送规则。",
+	unchanged: "AGENTS.md 里的推送规则已是最新。",
+	"skipped-custom": "检测到你已手写过推送规则，未改动 AGENTS.md。"
+};
+
 /** Success codes accepted by the official client (string or numeric zero). */
 const SUCCESS_CODES = new Set(["0000000000", "0"]);
 
@@ -118,7 +135,14 @@ const Config = z.object({
 	/** hiboard_push 没带有效 schedule_id 时自动补的值（为空则卡片点不开）。 */
 	defaultScheduleId: z.string().default("dsh_worklog"),
 	/** 设置页路由开关；关掉后 `/hiboard-push/config` 不注册，浏览器半边也停手。 */
-	settingsCard: z.boolean().default(true)
+	settingsCard: z.boolean().default(true),
+	/**
+	 * 保存授权码时，是否顺带把「每轮都要推送」的规则写进全局指令文件
+	 * （`$DSH_HOME/AGENTS.md` 里的一个标记块）。**默认开启** —— 这样一键安装后
+	 * 只要粘一次授权码，规则就自动就位，不必再手改 AGENTS.md。
+	 * 关掉它（卡片上的按钮）会把已写入的那一段一起移除。
+	 */
+	autoRule: z.boolean().default(true)
 });
 
 const entryDefaults = {
@@ -136,7 +160,8 @@ const entryDefaults = {
 	guardAmbiguousRetryCount: 1,
 	guardRetryDelayMs: 3000,
 	defaultScheduleId: "dsh_worklog",
-	settingsCard: true
+	settingsCard: true,
+	autoRule: true
 };
 
 // ---------------------------------------------------------------- payload
@@ -446,7 +471,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 +480,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 +517,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 = () => {
@@ -515,7 +559,9 @@ function buildConfigRoute({ authCodeInfo, settings, storeFile }) {
 			endpoint: s.pushServiceUrl,
 			storeFile,
 			// 调试图：兜底到底把多少次「原本失败的推送」救了回来
-			audit: auditSummary()
+			audit: auditSummary(),
+			// 常驻规则：是否开启、有没有已写入的块、有没有用户自己写的等价规则
+			rule: Object.assign(ruleStatus(AGENTS_FILE), { enabled: s.autoRule })
 		};
 	};
 
@@ -555,6 +601,10 @@ function buildConfigRoute({ authCodeInfo, settings, storeFile }) {
 				const body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
 				const patch = {};
 				const notes = [];
+				/** 本次请求是否真的写入了授权码（清除不算）——用它触发"顺带写规则"。 */
+				let authCodeTouched = false;
+				/** 卡片上的规则开关：true 写入 / false 移除 / undefined 不表态。 */
+				let ruleRequest;
 
 				// ---- 授权码：完整指令或裸码都行；空串表示"清除覆盖" ----
 				if (Object.prototype.hasOwnProperty.call(body, "authCode")) {
@@ -570,10 +620,17 @@ function buildConfigRoute({ authCodeInfo, settings, storeFile }) {
 							return;
 						}
 						patch.authCode = parsed.code;
+						authCodeTouched = true;
 						notes.push(`${parsed.note}（${maskAuthCode(parsed.code)}）`);
 					}
 				}
 
+				// ---- 常驻规则开关 ----
+				if (Object.prototype.hasOwnProperty.call(body, "ruleEnabled")) {
+					patch.autoRule = body.ruleEnabled === true;
+					ruleRequest = body.ruleEnabled === true;
+				}
+
 				// ---- 兜底开关：布尔直接落盘，立即生效 ----
 				for (const key of ["guardEnabled", "guardRescueEnabled", "guardPromiseRescueEnabled", "guardRetryEnabled"]) {
 					if (Object.prototype.hasOwnProperty.call(body, key)) patch[key] = body[key] === true;
@@ -588,6 +645,27 @@ function buildConfigRoute({ authCodeInfo, settings, storeFile }) {
 					return;
 				}
 				writeStore(patch, storeFile);
+
+				// ---- 常规规则动作：放在落盘之后，读到的才是"最终"的 autoRule ----
+				// 保存授权码时**顺带**把「每轮都要推送」写进全局指令文件：用户此刻的意图
+				// 就是"让它开始工作"，不该再要求他手改 AGENTS.md。默认开启，卡片可关。
+				try {
+					if (ruleRequest === false) {
+						const r = removeRule(AGENTS_FILE);
+						notes.push(r.action === "removed" ? "已移除全局指令文件里的推送规则。" : "全局推送规则本来就不存在，未改动。");
+					} else if (ruleRequest === true) {
+						const r = ensureRule(AGENTS_FILE);
+						notes.push(RULE_NOTE[r.action] ?? "已同步全局推送规则。");
+					} else if (authCodeTouched && settings().autoRule) {
+						const r = ensureRule(AGENTS_FILE);
+						// unchanged 不提示：每次保存都重复一句"已是最新"只是噪音
+						if (r.action !== "unchanged") notes.push(RULE_NOTE[r.action] ?? "已同步全局推送规则。");
+					}
+				} catch (error) {
+					// 规则写不进去不该让"授权码已保存"这件事看起来失败
+					notes.push(`授权码已保存，但写入全局规则失败：${String(error?.message ?? error)}`);
+				}
+
 				send(200, { ...summary(), notes });
 			} catch (error) {
 				send(400, { error: String(error?.message ?? error) });
@@ -626,7 +704,8 @@ function apply(ctx, rawConfig) {
 			guardAmbiguousRetryCount: Number(resolved.guardAmbiguousRetryCount) >= 0 ? Number(resolved.guardAmbiguousRetryCount) : 1,
 			guardRetryDelayMs: Number(resolved.guardRetryDelayMs) > 0 ? Number(resolved.guardRetryDelayMs) : 3000,
 			defaultScheduleId: String(resolved.defaultScheduleId ?? "").trim() || "dsh_worklog",
-			settingsCard: resolved.settingsCard !== false
+			settingsCard: resolved.settingsCard !== false,
+			autoRule: resolved.autoRule !== false
 		};
 	};
 

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 用户实际遇到）。