dsh-harmonyos-hiboard 0.7.2 → 0.8.0

package/README.md

@@ -230,6 +230,27 @@ L2 抢救"承诺了却没调用"、L3 按错误类别重试并自动补 `schedul
 
    这个面板的意义是：以前"保险丝到底有没有干活"只能靠猜，现在直接列给你看。
 
+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 共用一份。
 
@@ -388,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,6 +1,6 @@
 {
   "name": "dsh-harmonyos-hiboard",
-  "version": "0.7.2",
+  "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",

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,6 +95,12 @@ 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 + '）';
@@ -138,6 +144,12 @@ 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 + ')';
@@ -264,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; }
@@ -287,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('');
@@ -461,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
@@ -534,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 })
 		};
 	};
 
@@ -574,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")) {
@@ -589,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;
@@ -607,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) });
@@ -645,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
 		};
 	};