@shgroup/dsh-serenity-hooks 1.45.1 → 1.46.0

package/dsh.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.45.1",
+  "version": "1.46.0",
   "main": "lib/index.js",
   "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——11 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag；后两个按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 轨迹日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.5-rc.2（deepseek-ai/deepseek-harness）。",
   "engines": {

package/lib/index.js

@@ -1915,14 +1915,16 @@ function waitAgentIdle(ctx, agent) {
 /**
 * skills-discovery.ts — CCC 入口 skill 自动发现（纯逻辑，零 DSH 依赖）
 *
-* 发现全部入口技能（原文全量，不截断）：
+* 发现全部入口技能（原文全量，不截断）—— **现行三个来源**（原为四个，**来源 3 已于 2026-09-21 删除**）：
 *   0. **`.serenity` 记号文件内容 = 顶层入口 skill 名**（CCC 记号文件的权威语义，
 *      tiangong-serenity 的 .serenity 内容为 `tg-serenity`）—— 最高优先
 *   1. `.dsh/entry-skill` 指针文件（内容 = skill 名）—— 兼容旧约定
 *   2. `.opencode/skills/*-serenity/SKILL.md` —— 自动扫描该 CCC 的顶层入口
 *      （home-serenity / tg-serenity / pangu-serenity …，命名模式 `*-serenity`）
-*   3. `.dsh/skills/*-serenity/SKILL.md` —— 自动扫描 ACC/harness 入口（acc-serenity 等）
-* 按名去重；顺序 = 记号文件 → 指针 → opencode 入口 → dsh 入口。
+*   ~~3. `.dsh/skills/*-serenity/SKILL.md`（扫 ACC 装进 CCC 的技能副本）~~ —— 🔴 **已删**：
+*      owner 2026-09-21 令「连模板和安装命令一起删」（B 案）。**判据、实测证据与日期逐字记在
+*      `findEntrySkills()` 体内那一段注释里**——本头部只留结论，**不复述判据**（避免两处会漂的真相源）。
+* 按名去重；顺序 = 记号文件 → 指针 → opencode 入口。
 *
 * 任何 CCC 都能自动注入其顶层入口 skill 全文（不硬编码名字）。
 */
@@ -1991,7 +1993,6 @@ function findEntrySkills(root) {
 		}
 	}
 	for (const dir of scanSerenityDirs(resolve(root, ".opencode", "skills"))) add(join(dir, "SKILL.md"), "opencode");
-	for (const dir of scanSerenityDirs(resolve(root, ".dsh", "skills"))) add(join(dir, "SKILL.md"), "dsh");
 	return out;
 }
 function truncateContent(content, maxChars) {
@@ -2153,11 +2154,13 @@ function mergeSkillNames(cccSkills, trajSkills) {
 * @param mdPath 轨迹的 SESSION.md 路径（**来自绑定的 `mdPath`**，不用 label 拼）
 * @param maxChars 总长上限（字符）
 * @param cccSkills CCC 级声明（`readTrajectorySkills`；缺省空 = 只有轨迹级，行为与 v1.43 一致）
+* @param onInjectedNames 观测回调（本次请求实际带上的 skill 名；**纯观测**，供用量统计用——
+*        回调抛错被吞，**不影响注入正文**）
 * @returns 注入正文；两条来源皆无声明 → `''`（空串 = 宿主不产出该 section 块）；
 *          SESSION.md 缺失/读失败 → 响亮提示（若同时有 CCC 级声明，则提示在前、正文随后——
 *          **提示不因"别处有内容"而被吞掉**）
 */
-function buildTrajectorySkillsSection(root, mdPath, maxChars = TRAJECTORY_SKILLS_MAX_CHARS, cccSkills = []) {
+function buildTrajectorySkillsSection(root, mdPath, maxChars = TRAJECTORY_SKILLS_MAX_CHARS, cccSkills = [], onInjectedNames) {
 	const abs = absoluteMdPath(root, mdPath);
 	let trajNames = [];
 	let notice = "";
@@ -2169,6 +2172,9 @@ function buildTrajectorySkillsSection(root, mdPath, maxChars = TRAJECTORY_SKILLS
 	}
 	const names = mergeSkillNames(cccSkills, trajNames);
 	if (names.length === 0) return notice;
+	if (onInjectedNames) try {
+		onInjectedNames(names);
+	} catch {}
 	const blocks = [];
 	for (const name of names) {
 		if (!isSafeSkillName(name)) {
@@ -2189,6 +2195,274 @@ function buildTrajectorySkillsSection(root, mdPath, maxChars = TRAJECTORY_SKILLS
 	const body = blocks.join("\n\n");
 	return truncateContent(notice ? `${notice}\n\n${body}` : body, maxChars);
 }
+//#endregion
+//#region src/usage-stats.ts
+/**
+* usage-stats.ts — ACC 用量统计（**skill 加载次数** ＋ **MSM 执行次数**；落该 CCC 的 `_tmp`）
+*
+* ## 所有者令（本模块的存在理由）
+*
+* 「我需要对 ACC 增加一个统计功能，包括 **skill 加载次数统计，msm 执行次数统计**；
+*  要求这个统计**自动生成在 CCC 的 `_tmp` 内的指定文件**」
+* ＋（对齐时确认）「**skill 加载**两个口径**都记、用字段区分**」「**只记名字、不记参数**」
+* 「**重启后读旧文件续算**」。
+*
+* ## 它解决什么麻烦（白话）
+*
+* 在此之前，「**哪些 skill 真的被加载过、哪些 MSM 真的在跑**」在 ACC 侧**一个数都没有** ——
+* 要判断「这东西还有人用吗」，只能靠翻会话记录**猜**。
+* ⇒ 本模块让每个 CCC 留下一份**纯计数**账本：**用了哪个、多少次、第一次和最近一次是什么时候**。
+* 用途 = 清理/精简的**依据**（没有人用的东西与天天在用的东西，不再靠猜）。
+*
+* ## 🔴 铁律（与 `cro-log.ts` 同族）
+*
+* **本模块每个导出函数都不抛错**：读盘 / 解析 / 写盘失败一律返回结构化失败，
+* 由调用方只记一行日志（或什么都不做）⇒ **统计的问题绝不影响工具执行与既有链路**。
+* 调用点在 `tools/post-execute` 的中途 ⇒ **更不能抛**（否则等于用统计打断会话）。
+*
+* ## 🔴 只记名字（所有者令；也是本模块唯一的"不入盘"约束）
+*
+* **绝不写 `arguments`**：MSM 参数里可能有凭据 / 路径 / 正文。
+* ⇒ 本模块只保留**计数键**（skill 名 / MSM 名），并对其做**长度与数量上限**（见常量），
+* 使文件规模**结构上有界**（不需要轮转，也不会被异常名字撑爆）。
+*
+* ## 🔴 重启后必须续算（所有者令）
+*
+* 宿主会被重启（本容器实测 24h 内 3 次）⇒ 计数**不能只活在内存里**：
+* 每次写盘 = **读旧文件 → 在旧值上自增 → 原子写**（`tmp + rename`，与 `wake-registry.ts` /
+* `cro-log.ts` 同款形态）⇒ **进程重启后计数自然延续**，无需额外的 flush/落盘时机。
+*
+* ## 口径（两个字段，勿合并）
+*
+* | 字段 | 含义 | 喂它的地方 |
+* |---|---|---|
+* | `skill.loads` | 模型**主动**调宿主 `skill` 工具（把某 skill 的 `SKILL.md` 全文载入） | `tools/post-execute`（工具名 = `skill`） |
+* | `skill.injections` | ACC **每请求注入**的 skill 段（`trajectory.skills` / 轨迹 frontmatter 声明） | `seams/system-prompt.ts` 的 trajectory-skills section 求值回调 |
+* | `msm` | `msm` 工具的一次执行，按 **MSM 名**分桶 | `tools/post-execute`（工具名 = `msm`） |
+*
+* 🔴 **两者差好几个数量级**：`loads` 是模型的**动作**（稀疏），`injections` 是**请求的属性**（稠密）。
+* 合并成一个数就**再也读不出**「这个 skill 是被人主动用的，还是只是被配上了」。
+*/
+/** 落点目录（所有者令：CCC 的 `_tmp` 内） */
+const USAGE_STATS_SUBDIR = "_tmp";
+/** 固定文件名（所有者令「指定文件」；对齐时我取的名字，owner 未反对 ⇒ 定为常量） */
+const USAGE_STATS_FILENAME = "acc-usage.json";
+/** 每个桶的键数上限（**结构上界**，见文件头"只记名字"节） */
+const USAGE_MAX_KEYS_PER_BUCKET = 1e3;
+const USAGE_STATS_VERSION = 1;
+/** 统计文件绝对路径（**纯函数**） */
+function usageStatsPath(root) {
+	return join(root, USAGE_STATS_SUBDIR, USAGE_STATS_FILENAME);
+}
+/** 空账本（**纯函数**） */
+function emptyUsageStats() {
+	return {
+		version: USAGE_STATS_VERSION,
+		updatedAt: isoLocal(0),
+		skill: {
+			loads: {},
+			injections: {}
+		},
+		msm: {}
+	};
+}
+/** 单条计数形状校验（容忍手改：字段缺失/类型不符 ⇒ 丢弃该条，不阻断整档） */
+function asCounter(value) {
+	const c = value;
+	if (!c || typeof c !== "object") return null;
+	if (typeof c.count !== "number" || !Number.isFinite(c.count) || c.count < 0) return null;
+	const firstAt = typeof c.firstAt === "string" ? c.firstAt : "";
+	const lastAt = typeof c.lastAt === "string" ? c.lastAt : firstAt;
+	return {
+		count: Math.floor(c.count),
+		firstAt,
+		lastAt
+	};
+}
+/** 桶校验（非对象 ⇒ 空桶；逐键过滤非法条） */
+function asBucket(value) {
+	const out = {};
+	if (!value || typeof value !== "object") return out;
+	for (const [k, v] of Object.entries(value)) {
+		const c = asCounter(v);
+		if (c) out[k] = c;
+	}
+	return out;
+}
+/**
+* 读取账本（**永不抛**；读坏 ⇒ 空账本 + 返回 error 文本，**不静默吞掉**）。
+* 文件不存在 = 正常初态（`error: null` 且空账本）。
+*/
+function loadUsageStats(root) {
+	const path = usageStatsPath(root);
+	if (!existsSync(path)) return {
+		stats: emptyUsageStats(),
+		error: null
+	};
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf-8"));
+		const skill = parsed.skill ?? {};
+		return {
+			stats: {
+				version: USAGE_STATS_VERSION,
+				updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : isoLocal(0),
+				skill: {
+					loads: asBucket(skill.loads),
+					injections: asBucket(skill.injections)
+				},
+				msm: asBucket(parsed.msm)
+			},
+			error: null
+		};
+	} catch (err) {
+		return {
+			stats: emptyUsageStats(),
+			error: `用量统计解析失败（${String(err?.message ?? err)}）`
+		};
+	}
+}
+/** 键是否可记（非空 + 不超长；**不截断**——截断会造出一个不存在的名字） */
+function isRecordableUsageName(name) {
+	return typeof name === "string" && name !== "" && [...name].length <= 120;
+}
+/**
+* 在桶上自增一格（**纯函数**：不改入参，返回新桶）。
+* 新键超桶上限 ⇒ **不新增**（但仍自增已有键）⇒ 键数**结构上有界**。
+*/
+function bumpBucket(bucket, name, at, maxKeys = USAGE_MAX_KEYS_PER_BUCKET) {
+	const prev = bucket[name];
+	if (!prev && Object.keys(bucket).length >= maxKeys) return bucket;
+	const next = prev ? {
+		count: prev.count + 1,
+		firstAt: prev.firstAt || at,
+		lastAt: at
+	} : {
+		count: 1,
+		firstAt: at,
+		lastAt: at
+	};
+	return {
+		...bucket,
+		[name]: next
+	};
+}
+/** 从工具入参里取名字（首个命中的键胜出；取不到 ⇒ `null`） */
+function nameFromArgs(args, keys) {
+	if (args === null || typeof args !== "object") return null;
+	const a = args;
+	for (const k of keys) if (isRecordableUsageName(a[k])) return a[k];
+	return null;
+}
+/** `msm` 工具的名字键（`msm(name, args)` 的第一个参数） */
+const MSM_NAME_KEYS = ["name"];
+/** `skill` 工具的名字键（宿主 `skill` 工具用 `name`；另两个是防御性容错） */
+const SKILL_NAME_KEYS = [
+	"name",
+	"skill",
+	"skillName"
+];
+const NOTHING = {
+	ok: true,
+	error: null,
+	recorded: null,
+	name: null,
+	wrote: false
+};
+/**
+* 读 → 自增 → 原子写（**本模块唯一写盘通道；永不抛**）。
+*
+* @param root CCC 根
+* @param mutate 在已载入的账本上做一次自增（返回值 = 本次记录的结论；返回 `NOTHING` 则不写盘）
+* @param nowMs 当前毫秒（可注入 ⇒ 便于测 firstAt/lastAt）
+*/
+function writeThrough(root, mutate, nowMs = Date.now()) {
+	const path = usageStatsPath(root);
+	try {
+		const at = isoLocal(nowMs);
+		const loaded = loadUsageStats(root);
+		const outcome = mutate(loaded.stats, at);
+		if (outcome.recorded === null) return outcome;
+		loaded.stats.updatedAt = at;
+		mkdirSync(join(root, USAGE_STATS_SUBDIR), { recursive: true });
+		const tmp = `${path}.tmp`;
+		writeFileSync(tmp, `${JSON.stringify(loaded.stats, null, 2)}\n`, "utf-8");
+		renameSync(tmp, path);
+		return {
+			...outcome,
+			ok: true,
+			error: null,
+			wrote: true
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: `用量统计写入失败（${String(err?.message ?? err)}）`,
+			recorded: null,
+			name: null,
+			wrote: false
+		};
+	}
+}
+/**
+* 记录一次工具调用的用量（**`tools/post-execute` 的喂入口**）。
+*
+* 只认两类工具名；其余一律 `NOTHING`（**不产生文件、不产生噪声**）。
+* 🔴 **不看 `arguments` 的其余内容**——只取名字键。
+*/
+function recordToolUsage(root, toolName, args, nowMs = Date.now()) {
+	if (toolName === "msm") {
+		const name = nameFromArgs(args, MSM_NAME_KEYS);
+		if (!name) return NOTHING;
+		return writeThrough(root, (stats, at) => {
+			stats.msm = bumpBucket(stats.msm, name, at);
+			return {
+				ok: true,
+				error: null,
+				recorded: "msm",
+				name,
+				wrote: false
+			};
+		}, nowMs);
+	}
+	if (toolName === "skill") {
+		const name = nameFromArgs(args, SKILL_NAME_KEYS);
+		if (!name) return NOTHING;
+		return writeThrough(root, (stats, at) => {
+			stats.skill.loads = bumpBucket(stats.skill.loads, name, at);
+			return {
+				ok: true,
+				error: null,
+				recorded: "skill.load",
+				name,
+				wrote: false
+			};
+		}, nowMs);
+	}
+	return NOTHING;
+}
+/**
+* 记录一次 **skill 注入**（每个请求的 skill 段装配时调用）。
+*
+* ⚠️ 与 `recordToolUsage` 不同，本函数的调用频度 = **请求频度**（稠密）：
+* 调用方应**只在真的注入了非空内容时**调用（空 section 由宿主丢弃 ⇒ 不产生噪声）。
+* 一次调用只写一次盘（`names` 内的多个 skill 合并在**同一次**读改写里）。
+*/
+function recordSkillInjections(root, names, nowMs = Date.now()) {
+	const usable = names.filter((n) => isRecordableUsageName(n));
+	if (usable.length === 0) return NOTHING;
+	return writeThrough(root, (stats, at) => {
+		let bucket = stats.skill.injections;
+		for (const n of usable) bucket = bumpBucket(bucket, n, at);
+		stats.skill.injections = bucket;
+		return {
+			ok: true,
+			error: null,
+			recorded: "skill.injection",
+			name: usable.join(","),
+			wrote: false
+		};
+	}, nowMs);
+}
 /** 验证窗口：当前时步 ± 1（容忍时钟漂移/生成延迟） */
 const TOTP_WINDOW = 1;
 /** 输出位数（标准 6 位） */
@@ -3159,7 +3433,7 @@ function registerTrajectorySkillSection(agent, root) {
 			text: () => {
 				const current = readLastBound(session);
 				if (!current) return "";
-				return buildTrajectorySkillsSection(root, current.mdPath, TRAJECTORY_SKILLS_MAX_CHARS, readTrajectorySkills(root));
+				return buildTrajectorySkillsSection(root, current.mdPath, TRAJECTORY_SKILLS_MAX_CHARS, readTrajectorySkills(root), (names) => recordSkillInjections(root, names));
 			}
 		});
 		trajectorySkillAgents.add(key);
@@ -6364,6 +6638,9 @@ function registerKeeper(ctx, opts = {}) {
 		const tracker = trackerFor(exec);
 		const shouldRemind = skiffKeeper ? tracker.step(exec.name) : false;
 		const downstream = await next();
+		try {
+			recordToolUsage(root, exec.name, exec.arguments);
+		} catch {}
 		const blocks = [];
 		if (shouldRemind) {
 			const code = tracker.ack();

package/lib/skills-discovery.d.ts

@@ -1,14 +1,16 @@
 /**
  * skills-discovery.ts — CCC 入口 skill 自动发现（纯逻辑，零 DSH 依赖）
  *
- * 发现全部入口技能（原文全量，不截断）：
+ * 发现全部入口技能（原文全量，不截断）—— **现行三个来源**（原为四个，**来源 3 已于 2026-09-21 删除**）：
  *   0. **`.serenity` 记号文件内容 = 顶层入口 skill 名**（CCC 记号文件的权威语义，
  *      tiangong-serenity 的 .serenity 内容为 `tg-serenity`）—— 最高优先
  *   1. `.dsh/entry-skill` 指针文件（内容 = skill 名）—— 兼容旧约定
  *   2. `.opencode/skills/*-serenity/SKILL.md` —— 自动扫描该 CCC 的顶层入口
  *      （home-serenity / tg-serenity / pangu-serenity …，命名模式 `*-serenity`）
- *   3. `.dsh/skills/*-serenity/SKILL.md` —— 自动扫描 ACC/harness 入口（acc-serenity 等）
- * 按名去重；顺序 = 记号文件 → 指针 → opencode 入口 → dsh 入口。
+ *   ~~3. `.dsh/skills/*-serenity/SKILL.md`（扫 ACC 装进 CCC 的技能副本）~~ —— 🔴 **已删**：
+ *      owner 2026-09-21 令「连模板和安装命令一起删」（B 案）。**判据、实测证据与日期逐字记在
+ *      `findEntrySkills()` 体内那一段注释里**——本头部只留结论，**不复述判据**（避免两处会漂的真相源）。
+ * 按名去重；顺序 = 记号文件 → 指针 → opencode 入口。
  *
  * 任何 CCC 都能自动注入其顶层入口 skill 全文（不硬编码名字）。
  */

package/lib/trajectory-skills.d.ts

@@ -81,8 +81,10 @@ export declare function mergeSkillNames(cccSkills: readonly string[], trajSkills
  * @param mdPath 轨迹的 SESSION.md 路径（**来自绑定的 `mdPath`**，不用 label 拼）
  * @param maxChars 总长上限（字符）
  * @param cccSkills CCC 级声明（`readTrajectorySkills`；缺省空 = 只有轨迹级，行为与 v1.43 一致）
+ * @param onInjectedNames 观测回调（本次请求实际带上的 skill 名；**纯观测**，供用量统计用——
+ *        回调抛错被吞，**不影响注入正文**）
  * @returns 注入正文；两条来源皆无声明 → `''`（空串 = 宿主不产出该 section 块）；
  *          SESSION.md 缺失/读失败 → 响亮提示（若同时有 CCC 级声明，则提示在前、正文随后——
  *          **提示不因"别处有内容"而被吞掉**）
  */
-export declare function buildTrajectorySkillsSection(root: string, mdPath: string, maxChars?: number, cccSkills?: readonly string[]): string;
+export declare function buildTrajectorySkillsSection(root: string, mdPath: string, maxChars?: number, cccSkills?: readonly string[], onInjectedNames?: (names: readonly string[]) => void): string;

package/lib/usage-stats.d.ts

@@ -0,0 +1,128 @@
+/**
+ * usage-stats.ts — ACC 用量统计（**skill 加载次数** ＋ **MSM 执行次数**；落该 CCC 的 `_tmp`）
+ *
+ * ## 所有者令（本模块的存在理由）
+ *
+ * 「我需要对 ACC 增加一个统计功能，包括 **skill 加载次数统计，msm 执行次数统计**；
+ *  要求这个统计**自动生成在 CCC 的 `_tmp` 内的指定文件**」
+ * ＋（对齐时确认）「**skill 加载**两个口径**都记、用字段区分**」「**只记名字、不记参数**」
+ * 「**重启后读旧文件续算**」。
+ *
+ * ## 它解决什么麻烦（白话）
+ *
+ * 在此之前，「**哪些 skill 真的被加载过、哪些 MSM 真的在跑**」在 ACC 侧**一个数都没有** ——
+ * 要判断「这东西还有人用吗」，只能靠翻会话记录**猜**。
+ * ⇒ 本模块让每个 CCC 留下一份**纯计数**账本：**用了哪个、多少次、第一次和最近一次是什么时候**。
+ * 用途 = 清理/精简的**依据**（没有人用的东西与天天在用的东西，不再靠猜）。
+ *
+ * ## 🔴 铁律（与 `cro-log.ts` 同族）
+ *
+ * **本模块每个导出函数都不抛错**：读盘 / 解析 / 写盘失败一律返回结构化失败，
+ * 由调用方只记一行日志（或什么都不做）⇒ **统计的问题绝不影响工具执行与既有链路**。
+ * 调用点在 `tools/post-execute` 的中途 ⇒ **更不能抛**（否则等于用统计打断会话）。
+ *
+ * ## 🔴 只记名字（所有者令；也是本模块唯一的"不入盘"约束）
+ *
+ * **绝不写 `arguments`**：MSM 参数里可能有凭据 / 路径 / 正文。
+ * ⇒ 本模块只保留**计数键**（skill 名 / MSM 名），并对其做**长度与数量上限**（见常量），
+ * 使文件规模**结构上有界**（不需要轮转，也不会被异常名字撑爆）。
+ *
+ * ## 🔴 重启后必须续算（所有者令）
+ *
+ * 宿主会被重启（本容器实测 24h 内 3 次）⇒ 计数**不能只活在内存里**：
+ * 每次写盘 = **读旧文件 → 在旧值上自增 → 原子写**（`tmp + rename`，与 `wake-registry.ts` /
+ * `cro-log.ts` 同款形态）⇒ **进程重启后计数自然延续**，无需额外的 flush/落盘时机。
+ *
+ * ## 口径（两个字段，勿合并）
+ *
+ * | 字段 | 含义 | 喂它的地方 |
+ * |---|---|---|
+ * | `skill.loads` | 模型**主动**调宿主 `skill` 工具（把某 skill 的 `SKILL.md` 全文载入） | `tools/post-execute`（工具名 = `skill`） |
+ * | `skill.injections` | ACC **每请求注入**的 skill 段（`trajectory.skills` / 轨迹 frontmatter 声明） | `seams/system-prompt.ts` 的 trajectory-skills section 求值回调 |
+ * | `msm` | `msm` 工具的一次执行，按 **MSM 名**分桶 | `tools/post-execute`（工具名 = `msm`） |
+ *
+ * 🔴 **两者差好几个数量级**：`loads` 是模型的**动作**（稀疏），`injections` 是**请求的属性**（稠密）。
+ * 合并成一个数就**再也读不出**「这个 skill 是被人主动用的，还是只是被配上了」。
+ */
+/** 落点目录（所有者令：CCC 的 `_tmp` 内） */
+export declare const USAGE_STATS_SUBDIR = "_tmp";
+/** 固定文件名（所有者令「指定文件」；对齐时我取的名字，owner 未反对 ⇒ 定为常量） */
+export declare const USAGE_STATS_FILENAME = "acc-usage.json";
+/** 单个计数的形态 */
+export interface UsageCounter {
+    /** 累计次数 */
+    count: number;
+    /** 首次计入时刻（当地 RFC3339 带偏移，遵 D67） */
+    firstAt: string;
+    /** 最近一次计入时刻 */
+    lastAt: string;
+}
+/** 文件形态（`{version, updatedAt, skill:{loads,injections}, msm}`） */
+export interface UsageStats {
+    version: number;
+    /** 最近一次写盘时刻 */
+    updatedAt: string;
+    skill: {
+        /** 模型主动调 `skill` 工具（全文载入） */
+        loads: Record<string, UsageCounter>;
+        /** ACC 每请求注入的 skill 段 */
+        injections: Record<string, UsageCounter>;
+    };
+    /** 按 MSM 名分桶的执行次数 */
+    msm: Record<string, UsageCounter>;
+}
+/** 计数键长度上限（防异常名字把文件撑大；超长 ⇒ **不记**，不截断成假名字） */
+export declare const USAGE_NAME_MAX_CHARS = 120;
+/** 每个桶的键数上限（**结构上界**，见文件头"只记名字"节） */
+export declare const USAGE_MAX_KEYS_PER_BUCKET = 1000;
+/** 统计文件绝对路径（**纯函数**） */
+export declare function usageStatsPath(root: string): string;
+/** 空账本（**纯函数**） */
+export declare function emptyUsageStats(): UsageStats;
+/**
+ * 读取账本（**永不抛**；读坏 ⇒ 空账本 + 返回 error 文本，**不静默吞掉**）。
+ * 文件不存在 = 正常初态（`error: null` 且空账本）。
+ */
+export declare function loadUsageStats(root: string): {
+    stats: UsageStats;
+    error: string | null;
+};
+/** 键是否可记（非空 + 不超长；**不截断**——截断会造出一个不存在的名字） */
+export declare function isRecordableUsageName(name: unknown): name is string;
+/**
+ * 在桶上自增一格（**纯函数**：不改入参，返回新桶）。
+ * 新键超桶上限 ⇒ **不新增**（但仍自增已有键）⇒ 键数**结构上有界**。
+ */
+export declare function bumpBucket(bucket: Record<string, UsageCounter>, name: string, at: string, maxKeys?: number): Record<string, UsageCounter>;
+/** 从工具入参里取名字（首个命中的键胜出；取不到 ⇒ `null`） */
+export declare function nameFromArgs(args: unknown, keys: readonly string[]): string | null;
+/** `msm` 工具的名字键（`msm(name, args)` 的第一个参数） */
+export declare const MSM_NAME_KEYS: readonly ["name"];
+/** `skill` 工具的名字键（宿主 `skill` 工具用 `name`；另两个是防御性容错） */
+export declare const SKILL_NAME_KEYS: readonly ["name", "skill", "skillName"];
+/** 一次记录的结论（供调用方决定要不要留痕；**本模块不自己打日志**） */
+export interface UsageRecordResult {
+    ok: boolean;
+    error: string | null;
+    /** 记入的是哪一类；`null` = 本次没有可记的东西（不算失败） */
+    recorded: 'skill.load' | 'skill.injection' | 'msm' | null;
+    /** 记入的键（`recorded` 为 `null` 时也为 `null`） */
+    name: string | null;
+    /** 本次是否真的落盘（`recorded` 非空即 true；失败时 false） */
+    wrote: boolean;
+}
+/**
+ * 记录一次工具调用的用量（**`tools/post-execute` 的喂入口**）。
+ *
+ * 只认两类工具名；其余一律 `NOTHING`（**不产生文件、不产生噪声**）。
+ * 🔴 **不看 `arguments` 的其余内容**——只取名字键。
+ */
+export declare function recordToolUsage(root: string, toolName: string, args: unknown, nowMs?: number): UsageRecordResult;
+/**
+ * 记录一次 **skill 注入**（每个请求的 skill 段装配时调用）。
+ *
+ * ⚠️ 与 `recordToolUsage` 不同，本函数的调用频度 = **请求频度**（稠密）：
+ * 调用方应**只在真的注入了非空内容时**调用（空 section 由宿主丢弃 ⇒ 不产生噪声）。
+ * 一次调用只写一次盘（`names` 内的多个 skill 合并在**同一次**读改写里）。
+ */
+export declare function recordSkillInjections(root: string, names: readonly string[], nowMs?: number): UsageRecordResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.45.1",
+  "version": "1.46.0",
   "description": "宁静号 ACC harness（Native Cordis 插件）——给 DeepSeek Harness 装一个「AI 工作区」：11 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag）+ 机械约束（安全模式/工作区围墙/密钥守卫/对外输出守卫）+ 工作日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.5-rc.2。",
   "license": "MIT",
   "repository": {