@shgroup/dsh-serenity-hooks 1.50.1 → 1.51.1

package/lib/diagram/dsl.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 标签式图表 DSL —— 解析器（只收集，不做几何）。
+ *
+ * 为什么是标签形式（owner 2026-09-29 裁决）：图是正文的附加层，一段
+ * <diagram>…</diagram> 嵌在文档里就能出图，作者不必为画一张图切到另一种文档结构去维护坐标；
+ * 属性 / 文本双形态（<rect .../> 声明几何，<text ...>正文</text> 承载文案）覆盖两类信息，
+ * 与 HTML/SVG 直觉一致，人写机器读都省事；自闭合 + 未知标签只报错不崩 = 前向兼容。
+ * 本文件只「收集」：不解析锚点（`ID.锚点[±dx,±dy]`）、不做几何——那是渲染侧的事；绝不抛异常。
+ */
+export interface DslRect {
+    id: string;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    label?: string;
+    size: number;
+    fill: string;
+}
+export interface DslSeg {
+    kind: 'line' | 'arrow';
+    from: string;
+    to: string;
+    color?: string;
+    width?: number;
+    dash?: string;
+    free: boolean;
+    ln: number;
+}
+export interface DslText {
+    x: number;
+    y: number;
+    text: string;
+    align: 'left' | 'center' | 'right';
+    size: number;
+    color?: string;
+    ln: number;
+}
+export interface DslLegend {
+    x: number;
+    y: number;
+    size: number;
+}
+export interface DslModel {
+    W: number;
+    H: number;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    pad: number;
+    title: string;
+    subtitle: string;
+    colors: Record<string, string>;
+    rects: DslRect[];
+    segments: DslSeg[];
+    texts: DslText[];
+    legend?: DslLegend;
+}
+export interface DslParse {
+    model: DslModel;
+    errors: string[];
+}
+/** 解析标签格式源码。**绝不抛异常**：看不懂的行记进 errors 并跳过，其余照收。 */
+export declare function parseDsl(source: string): DslParse;

package/lib/diagram/fonts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * diagram 字体事实源（**唯一真相源**：资产路径 ＋ 家族名 ＋ CSS 家族栈）
+ *
+ * 为什么单独成模块（R↓）：两处都要它，而它们的依赖面**必须**保持不同 ——
+ *   · `dsl-render.ts` 只生成 SVG 字符串（**纯函数、零 fs**），它需要在 SVG 里写 `font-family` 栈；
+ *   · `rasterize.ts` 要读字体文件喂给 wasm，并设 `defaultFontFamily`。
+ * ⇒ 谁都不该从对方 import（前者会被拖进 `node:fs`／wasm，后者不该定义 SVG 措辞）。
+ *
+ * ## 为什么是**三个**字型（每一个都由一张实测图证明，不是偏好，也不是"多带点保险"）
+ *
+ * | 字型 | 覆盖 | 它修好了什么（实测） |
+ * |---|---|---|
+ * | `DroidSansFallbackFull.ttf` | 汉字 | 没有它 ⇒ 中文全是方框（docker 实测：wasm 对系统字体**完全不可见**） |
+ * | `NotoSans-Regular.ttf` | 拉丁 | 没有它 ⇒ `diagram` ／ `parseDsl` 全变方框（Droid 是 **CJK 兜底字型**，**不含拉丁**） |
+ * | `DejaVuSans.ttf` | 符号 | 没有它 ⇒ `① ② ③` ／ `⇒ ⇒` ／ `→` 仍是方框（**前两个都没有这些字形**，实测对照图见 `docs/diagram-tool-feasibility.md`） |
+ *
+ * 🔴 **上一版的判据漏洞**（v1.51.1 修的）：那条"有字 vs 无字逐字节不同"只证明**有墨**，
+ * 没证明**墨是那个字** —— 方框也是墨 ⇒ 拉丁全变方框时它**照样绿**。
+ * ⇒ 现在每条覆盖声明都配一条**点名字符集**的差分用例：同长度不同字形 ⇒ 必须出不同墨。
+ *
+ * ## 家族名是**量出来的**，不是猜的
+ * 下表取自各文件 `name` 表 `nameID=1`（平台 3 ／ UTF-16BE）：
+ * `Droid Sans Fallback` ／ `Noto Sans` ／ `DejaVu Sans`。
+ * 写错名字时 resvg 的自动回退仍可能把字画出来（**图上看不出来**）⇒ 名字正确与否只能这样证明。
+ */
+export declare const DIAGRAM_CJK_FONT_ASSET = "assets/diagram/DroidSansFallbackFull.ttf";
+export declare const DIAGRAM_LATIN_FONT_ASSET = "assets/diagram/NotoSans-Regular.ttf";
+export declare const DIAGRAM_SYMBOL_FONT_ASSET = "assets/diagram/DejaVuSans.ttf";
+/** 汉字字型的家族名（**字体文件自报的族名**，写错就取不到） */
+export declare const DIAGRAM_CJK_FONT_FAMILY = "Droid Sans Fallback";
+/** 拉丁字型的家族名 */
+export declare const DIAGRAM_LATIN_FONT_FAMILY = "Noto Sans";
+/** 符号字型的家族名 */
+export declare const DIAGRAM_SYMBOL_FONT_FAMILY = "DejaVu Sans";
+/**
+ * SVG 里写的家族栈（**顺序即回退顺序**）：拉丁优先取 Noto，符号落 DejaVu，其余字形落到 Droid。
+ * ⚠️ 末尾的通用名（`sans-serif`）只是兜底惯例：本部署里 resvg **不带系统字体**
+ * （`loadSystemFonts: false`）⇒ 它取不到任何东西，真正的兜底是上面三个内置字型。
+ */
+export declare const DIAGRAM_FONT_STACK = "'Noto Sans', 'DejaVu Sans', 'Droid Sans Fallback', sans-serif";

package/lib/diagram/rasterize.d.ts

@@ -0,0 +1,35 @@
+/** 汉字字型资产（相对包根的路径）——**必须出现在 package.json 的 files 白名单里**（pack-check 会核对） */
+export declare const DIAGRAM_FONT_ASSET = "assets/diagram/DroidSansFallbackFull.ttf";
+/** 拉丁字型资产（v1.51.1 新增：CJK 字型**不含拉丁** ⇒ 只带一个时英文字母全渲染成方框） */
+export declare const DIAGRAM_FONT_ASSET_LATIN = "assets/diagram/NotoSans-Regular.ttf";
+/** 符号字型资产（v1.51.1 新增：前两个**都没有** `① ② ③` ／ `⇒` ／ `→` 的字形 ⇒ 只带前两个时它们仍是方框） */
+export declare const DIAGRAM_FONT_ASSET_SYMBOL = "assets/diagram/DejaVuSans.ttf";
+/** 汉字字型绝对路径（导出以便测试与 pack-check 共用同一判据来源） */
+export declare function diagramFontPath(): string;
+/** 拉丁字型绝对路径 */
+export declare function diagramLatinFontPath(): string;
+/** 符号字型绝对路径 */
+export declare function diagramSymbolFontPath(): string;
+/**
+ * 兜底字型的族名 = **汉字字型**（本工具的图以中文为主）。
+ * 两个内置字型的家族名与 CSS 家族栈统一定义在 `fonts.ts`（单一真相源），此处只透出兜底那一个。
+ */
+export declare const DIAGRAM_FONT_FAMILY = "Droid Sans Fallback";
+export interface RasterResult {
+    png: Uint8Array;
+    /** 实际输出像素宽（= `fitTo width` 的结果；供工具回执如实报尺寸） */
+    width: number;
+    /** 实际输出像素高（按 SVG 自身比例推出） */
+    height: number;
+    /** 渲染耗时（ms）—— 供工具自述与诊断用 */
+    ms: number;
+}
+/**
+ * SVG → PNG。
+ * @param width 输出像素宽（矢量无损放大；高度按 SVG 自身比例推出）
+ */
+export declare function rasterizeSvg(svg: string, width: number): Promise<RasterResult>;
+/** 测试用：清本模块的缓存（**三个字体缓冲 + 就绪 promise**）。
+ *  ⚠️ **wasm 本身无法"重置"**（`initWasm` 进程级一次性）⇒ 清掉后下一次 `rasterizeSvg`
+ *  会**重新走一遍 init 并命中共用态**（"already initialized" 由 `ensureReady` 吞掉）。 */
+export declare function resetRasterCache(): void;

package/lib/handyman-ops.d.ts

@@ -82,7 +82,7 @@ export declare function buildRoundPrompt(opts: {
  * 使用 handyman 前必须先加载 eap 设计方案；并行策略（jobs 编排）；提示词规范（详尽固定 EAP）；
  * 阅读/文字编写类 handyman 内部也加载 eap。
  */
-export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\n\n## Two modes (v1.31.3; default = foreground)\n| | foreground (default) | background |\n|---|---|---|\n| What | child agent(s) run the task ONCE and return their final text (jobs=[...] \u21D2 parallel, cap 5) | loop-validated worker: hard while-loop + random completion code |\n| Use when | you need result(s) back now (per-case testers, single conversions, parallel fan-out) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |\n| Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (\u2264100) |\n| Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |\n| Parallel jobs | **yes** \u2014 jobs=[{task,label?,model?},...], **cap 5 (fixed)** | yes (jobs=[...], handyman.maxParallel default 10) |\n| Mechanism | host delegation service ctx.subagents.start(\"spawn\") + agentOptions | ctx.agents.create + internal while-loop |\n| Model source | CCC handyman.models whitelist (same for both) | same |\n\n## \u26A0\uFE0F Before using: load eap and design the plan\nBefore calling handyman, load eap (acc-eap skill) and design the \"scale-up handyman plan\" based on the EAP framework.\n\n### 1. Task decomposition (E\u2191 Explicit)\n- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria\n- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (both modes)\n\n### 2. Prompt design (handyman's task parameter)\n- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria\n- foreground mode: the child does NOT share your conversation \u2014 restate everything it needs in task\n- Anti-example \"handle this file\" \u2014 ambiguous; good example \"read <path>, extract all rows of the\u300C\u5173\u952E\u51B3\u7B56\u300Dtable,\n  output a JSON array (fields id/conclusion/evidence), do not modify the original file\"\n- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):\n  the handyman-internal agent is also required to load eap and organize output per the EAP standard\n\n### 3. Model whitelist (CCC-configured, mandatory)\n- handyman only uses models listed in .opencode/serenity.json \"handyman.models\" \u2014 never arbitrary models\n- The CCC is expected to point this whitelist at LOW-COST models: handyman is the bulk-execution channel\n- background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)\n- foreground mode: the child is started through the host delegation service with the resolved model\n\n### 3b. \uD83D\uDD34 Provider availability (per-machine \u2014 the whitelist is NOT enough)\n- The whitelist lives in the **CCC** (\"serenity.json\", it **travels with the repository**), but provider\n  **adapters are registered per machine by the host** (profile config / settings namespace). An entry that\n  works on one machine can fail on another with: \"no adapter registered for provider <p>\".\n- Before spawning, handyman verifies the provider of the resolved model against the adapters registered\n  **on this machine**; if it is missing it reports the requested model, where it is configured, **the\n  providers that ARE available here**, any declared-but-dormant route (with its settings namespace), and the\n  exact fix \u2014 foreground puts this in \"diagnostic\", background throws it.\n- \u21D2 If you see \"has no adapter registered on this machine\": edit \".opencode/serenity.json\" \"handyman.models\"\n  (and \"handyman.defaultModel\") to a provider listed as available, or activate/register the provider on this\n  machine. **Do not retry the same call unchanged** \u2014 it fails identically.\n\n### 4. Parallel strategy (both modes)\n- Independent subtasks can run in parallel:\n  \u00B7 **foreground** \u2014 handyman(jobs=[{task,label?,model?},...]) \u21D2 fan-out of custom-model subagents, **cap 5**,\n    results come back **in the order you passed them** (label is only a display name here; per-job \"model\" allowed)\n  \u00B7 **background** \u2014 handyman(mode=\"background\", jobs=[...]): each job gets its own label + task + stop token + progress file\n- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label\n  (AGENT_SESSIONS/handyman-<label>.json) \u2014 same label resumes, different labels never interfere\n- Parallel cap: **foreground 5 (fixed)** / background handyman.maxParallel (default 10 \u2014 cheap models are cheap)\n- Aggregation: foreground returns all outputs in one result; background: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)\n- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead\n\n## Completion criteria\n- foreground: the child's run settles; done=true only when stopReason=\"completed\" (otherwise read diagnostic)\n- background (osp loop standard): the only completion condition = the worker echoes this round's random verification\n  code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable);\n  automatic restart on abnormal agent stop (\u2264100 restarts, anti-infinite-loop)\n\n## Waiting UI\n- The WebUI session-header Serenity detail card shows running background handymen's progress\n  (label / round / last response), one line per parallel job, ~3s refresh (foreground mode writes no progress)\n";
+export declare const HANDYMAN_GUIDE = "# handyman \u2014 Scale-Up Usage Guide (guide)\n\n## Two modes (v1.31.3; default = foreground)\n| | foreground (default) | background |\n|---|---|---|\n| What | child agent(s) run the task ONCE and return their final text (jobs=[...] \u21D2 parallel, cap 10) | loop-validated worker: hard while-loop + random completion code |\n| Use when | you need result(s) back now (per-case testers, single conversions, parallel fan-out) | long/unattended work needing anti-early-finish, resumability, or parallel jobs |\n| Loop / validation | none | stop-token is the ONLY completion condition; round cap (default 100); auto-restart (\u2264100) |\n| Progress file | none | AGENT_SESSIONS/handyman-<label>.md/.json (same label resumes) |\n| Parallel jobs | **yes** \u2014 jobs=[{task,label?,model?},...], **cap 10 (fixed)** | yes (jobs=[...], handyman.maxParallel default 10) |\n| Mechanism | host delegation service ctx.subagents.start(\"spawn\") + agentOptions | ctx.agents.create + internal while-loop |\n| Model source | CCC handyman.models whitelist (same for both) | same |\n\n## \u26A0\uFE0F Before using: load eap and design the plan\nBefore calling handyman, load eap (acc-eap skill) and design the \"scale-up handyman plan\" based on the EAP framework.\n\n### 1. Task decomposition (E\u2191 Explicit)\n- Split large tasks into explicit subtasks: each subtask defines goal / input / boundaries (what to do, what not to do) / acceptance criteria\n- Make dependencies explicit: dependent tasks run serially, independent ones can run in parallel (both modes)\n\n### 2. Prompt design (handyman's task parameter)\n- task must be detailed, fixed, and EAP-compliant: clear goal, drawn boundaries, decidable acceptance criteria\n- foreground mode: the child does NOT share your conversation \u2014 restate everything it needs in task\n- Anti-example \"handle this file\" \u2014 ambiguous; good example \"read <path>, extract all rows of the\u300C\u5173\u952E\u51B3\u7B56\u300Dtable,\n  output a JSON array (fields id/conclusion/evidence), do not modify the original file\"\n- Reading/curating or text-writing work (extracting from files, summarizing, writing docs, generating text, etc.):\n  the handyman-internal agent is also required to load eap and organize output per the EAP standard\n\n### 3. Model whitelist (CCC-configured, mandatory)\n- handyman only uses models listed in .opencode/serenity.json \"handyman.models\" \u2014 never arbitrary models\n- The CCC is expected to point this whitelist at LOW-COST models: handyman is the bulk-execution channel\n- background mode: recursive subagents inside a worker inherit the worker's model automatically (DSH native)\n- foreground mode: the child is started through the host delegation service with the resolved model\n\n### 3b. \uD83D\uDD34 Provider availability (per-machine \u2014 the whitelist is NOT enough)\n- The whitelist lives in the **CCC** (\"serenity.json\", it **travels with the repository**), but provider\n  **adapters are registered per machine by the host** (profile config / settings namespace). An entry that\n  works on one machine can fail on another with: \"no adapter registered for provider <p>\".\n- Before spawning, handyman verifies the provider of the resolved model against the adapters registered\n  **on this machine**; if it is missing it reports the requested model, where it is configured, **the\n  providers that ARE available here**, any declared-but-dormant route (with its settings namespace), and the\n  exact fix \u2014 foreground puts this in \"diagnostic\", background throws it.\n- \u21D2 If you see \"has no adapter registered on this machine\": edit \".opencode/serenity.json\" \"handyman.models\"\n  (and \"handyman.defaultModel\") to a provider listed as available, or activate/register the provider on this\n  machine. **Do not retry the same call unchanged** \u2014 it fails identically.\n\n### 4. Parallel strategy (both modes)\n- Independent subtasks can run in parallel:\n  \u00B7 **foreground** \u2014 handyman(jobs=[{task,label?,model?},...]) \u21D2 fan-out of custom-model subagents, **cap 10**,\n    results come back **in the order you passed them** (label is only a display name here; per-job \"model\" allowed)\n  \u00B7 **background** \u2014 handyman(mode=\"background\", jobs=[...]): each job gets its own label + task + stop token + progress file\n- Concurrency safety guaranteed: unique sessionId (handyman-<label>-<uuid>), progress files isolated per label\n  (AGENT_SESSIONS/handyman-<label>.json) \u2014 same label resumes, different labels never interfere\n- Parallel cap: **foreground 10 (fixed)** / background handyman.maxParallel (default 10 \u2014 cheap models are cheap)\n- Aggregation: foreground returns all outputs in one result; background: after each parallel job produces progress, the main agent merges (or spawns one aggregation handyman)\n- For programmable pipeline/phase orchestration at scale, use the platform's workflow tool instead\n\n## Completion criteria\n- foreground: the child's run settles; done=true only when stopReason=\"completed\" (otherwise read diagnostic)\n- background (osp loop standard): the only completion condition = the worker echoes this round's random verification\n  code (stop token); dialogue round cap (default 100, osp fail-safe, forced stop beyond the cap, resumable);\n  automatic restart on abnormal agent stop (\u2264100 restarts, anti-infinite-loop)\n\n## Waiting UI\n- The WebUI session-header Serenity detail card shows running background handymen's progress\n  (label / round / last response), one line per parallel job, ~3s refresh (foreground mode writes no progress)\n";
 /** handyman 运行状态（进度文件摘要；WebUI 等待界面数据源） */
 interface HandymanRunInfo {
     label: string;

package/lib/index.d.ts

@@ -156,6 +156,13 @@ export interface Config {
     visionPatch?: {
         enabled?: boolean;
     };
+    /**
+     * diagram 工具（实验性 demo；2026-09-29 owner 具名令 **D104**）：标签格式源码 → 进程内
+     * 光栅化成 PNG（**不借浏览器**）。缺省关；部署层同义键 = 面板层 `diagramEnabled`。
+     */
+    diagram?: {
+        enabled?: boolean;
+    };
     /** human-channel（人机信道；**机器级**；2026-09-26 owner 定案）—— 见 `HumanChannelConfig` */
     humanChannel?: HumanChannelConfig;
     /** F1 双端口网关总开关（面板层；部署层同义键 = `gateway.enabled`） */
@@ -176,6 +183,8 @@ export interface Config {
     croEnabled?: Volatile<boolean | undefined>;
     /** 无人值守代理回复总闸（面板层；无部署层同义键；缺省关） */
     unattendedEnabled?: Volatile<boolean | undefined>;
+    /** **diagram 工具总闸**（面板层；部署层同义键 = `diagram.enabled`；缺省关；D104） */
+    diagramEnabled?: Volatile<boolean | undefined>;
 }
 /** schemastery 的 schema 类型（别名只为可读；**名字取自全局命名空间**，见上方 TS2742 说明） */
 type SchemaOf<S, T = S> = Schemastery<S, T>;
@@ -234,6 +243,11 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, "plain">;
+    diagram: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
     humanChannel: z<Schemastery.ObjectS<NoInfer<{
         accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
         subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
@@ -270,6 +284,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     publicAskEnabled: z<boolean, boolean, "volatile">;
     croEnabled: z<boolean, boolean, "volatile">;
     unattendedEnabled: z<boolean, boolean, "volatile">;
+    diagramEnabled: z<boolean, boolean, "volatile">;
 }>>, Schemastery.ObjectT<NoInfer<{
     serenityConfigPaths: z<string[], string[], "defined">;
     tools: z<boolean, boolean, "defined">;
@@ -321,6 +336,11 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     }>>, Schemastery.ObjectT<NoInfer<{
         enabled: z<boolean, boolean, "defined">;
     }>>, "plain">;
+    diagram: z<Schemastery.ObjectS<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        enabled: z<boolean, boolean, "defined">;
+    }>>, "plain">;
     humanChannel: z<Schemastery.ObjectS<NoInfer<{
         accounts: z<HumanChannelAccountConfig[], HumanChannelAccountConfig[], "defined">;
         subscriptions: z<HumanChannelSubscriptionConfig[], HumanChannelSubscriptionConfig[], "defined">;
@@ -357,6 +377,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     publicAskEnabled: z<boolean, boolean, "volatile">;
     croEnabled: z<boolean, boolean, "volatile">;
     unattendedEnabled: z<boolean, boolean, "volatile">;
+    diagramEnabled: z<boolean, boolean, "volatile">;
 }>>, "plain">;
 export declare function apply(ctx: Context, config: Config): void;
 export {};