@shgroup/dsh-serenity-hooks 1.50.0 → 1.51.0

package/README.md

@@ -65,7 +65,7 @@ dsh plugin --profile web add link:$(pwd)/hooks/dsh-serenity-hooks
 
 ## 3. 装完之后你多了什么
 
-### 3.1 十一个工具（其中两个按条件出现）
+### 3.1 十二个工具（其中三个按条件出现）
 
 | 工具 | 干什么 | 什么时候用 |
 |---|---|---|
@@ -80,6 +80,7 @@ dsh plugin --profile web add link:$(pwd)/hooks/dsh-serenity-hooks
 | `container_admin` | 机务舱：管理子角色、管理小工具注册表、查看全部配置 | 定义"子角色"、注册新小工具、改配置时 |
 | `im-bridge` | 给 IM 联系人发消息（目前是微信）：发文本、发文件、查已配置联系人、查通道状态。每次成功发送自动进工作区的消息记录 | 想让 AI 主动给家人/同事发消息（见 §6.6）。**只在工作区配了微信桥时才出现**，且只能发本工作区的消息 |
 | `acc-diag` | ACC 运行态诊断：一次调用出全报告——当前有多少会话活着、各自属于哪个工作区、唤醒时钟的武装态与 tick 次数、唤醒登记表的每一条（含状态 / 投递结果 / 补跑窗口） | **ACC 维护者专用**。**默认对所有工作区隐藏**，只有在工作区配置里点名（`exclusiveTools`）才出现 |
+| `diagram` | 画图：AI 给一段**标签式源码**（`<diagram>` 根 ＋ `<rect>` / `<arrow>` / `<text>` / `<color>` / `<legend>`），插件**在进程内**把它画成 PNG 并贴进对话——**不启浏览器、不截图**。同时落一份 `.svg`（可读可改）与一份 `.png` 在工作区的 `_tmp/diagram/`。自带四项体检（块重叠 / 标签溢出 / 悬空端点 / 线压字），**只告警不拦图**；写错的图元被跳过并逐条报错，其余照画 | 想把关系图/示意图直接放进对话时。**实验性 demo，默认关**：关着的时候这个工具**根本不注册**（AI 看不到它，不占上下文）；开关在设置面板「工具」组。中文能画，是因为字体**随插件内置**（约 3.8 MB） |
 
 > **改过名**（旧名已彻底停用，没有兼容别名）：下面每组的箭头链是**逐个发布版本**的名字，**末项才是今名**——`cc_fs` → `container_fs` · `cc_git` → `container_git` · `session`+`session_rebuild` → `logbook`（v1.30/1.31）→ `trajectory`（v1.32）→ **`container_trajectory`**（v1.34，今名） · `acc_kit` → `dashboard` · `acc_msm` → `msm`（执行）+ `container_admin`（管理）· `eap`/`neat`/`cce` → `praxis` · `skiff_admin` → `container_admin role` · `autopilot-trajectory` → `trajectory`（v1.32）→ **`container_trajectory`**（v1.34，今名）。老会话里看到旧名，**一律取所在那一组的末项**。
 
@@ -379,7 +380,7 @@ pnpm build              # 打包（lib/index.js + client.js）
 | 跑在 | OpenCode | DeepSeek Harness |
 | 实现 | 独立 | **独立**（不复用源码，但遵循同一套标准） |
 | 系统提示词 | `system.transform` | `systemPrompt.section`，平台无关的部分逐字对齐 |
-| 工具 | msm / container_fs / logbook 等 | container_fs / container_trajectory / dashboard / container_git / msm / praxis / handyman / localstore / container_admin ＋ 两个条件出现的（`im-bridge` / `acc-diag`） |
+| 工具 | msm / container_fs / logbook 等 | container_fs / container_trajectory / dashboard / container_git / msm / praxis / handyman / localstore / container_admin ＋ 三个条件出现的（`im-bridge` / `acc-diag` / `diagram`） |
 
 **同一个工作区可以随时换运行时**：`.serenity` 标记、`.opencode/skills/`、配置、`AGENT_SESSIONS/` 的文件格式都一致；
 差别只在平台层（工具名、注入方式），换过去以后 AI 收到的约束是一样的。

package/assets/diagram/LICENSE-Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/assets/diagram/PROVENANCE.md

@@ -0,0 +1,30 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: Droid
+Source: https://android.googlesource.com/platform/frameworks/base/
+
+Files: *
+Copyright: Copyright © 2006, 2007, 2008, 2009, 2010 Google Corp.
+           Droid is a trademark of Google Corp.
+License: Apache-2
+
+Files: debian/*
+Copyright: Copyright © 2010, Simon Ochsenreither <simon@ochsenreither.de>
+           Copyright © 2011-2014 Christian Perrier <bubulle@debian.org>
+           Copyright © 2013-2014  Vasudev Kamath <kamathvasudev@gmail.com>
+License: Apache-2
+
+License: Apache-2
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ .
+       http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ .
+ On Debian systems, the complete text of the Apache License Version 2.0
+ can be found in `/usr/share/common-licenses/Apache-2.0'.

package/dsh.plugin.json

@@ -1,10 +1,10 @@
 {
   "id": "dsh-serenity-hooks",
-  "version": "1.50.0",
+  "version": "1.51.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）。",
+  "description": "宁静号 ACC harness（Native Cordis 插件）：给 DSH 装一个「AI 工作区」——12 个工具（container_fs/container_trajectory/dashboard/container_git/msm/praxis/handyman/localstore/container_admin/im-bridge/acc-diag/diagram；后三个按配置条件出现）+ 机械约束（安全模式/工作区围墙/密钥守卫）+ 轨迹日志与原地重建 + 网页登录入口/微信桥/子角色/对外问答页/trajectory 唤醒注册表。适配 DSH 0.1.7-rc.1（deepseek-ai/deepseek-harness）。",
   "engines": {
-    "dsh": ">=0.1.5-rc.2"
+    "dsh": ">=0.1.7-rc.1"
   },
   "contributes": {
     "tools": [
@@ -18,7 +18,8 @@
       "localstore",
       "container_admin",
       "im-bridge",
-      "acc-diag"
+      "acc-diag",
+      "diagram"
     ],
     "skills": []
   }

package/lib/{ccc-roots-Duk89a-h.js → ccc-roots-DtiMVRPo.js}

@@ -1,4 +1,4 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
 import { a as hostSessions, i as hostService } from "./access-CNccNtgf.js";
 import { a as findSerenityRoot } from "./ccc-DG4Oc7I1.js";
 import { basename } from "node:path";
@@ -150,7 +150,7 @@ async function listCccs(ctx, opts = {}) {
 	if (typeof defaultRoot === "string" && defaultRoot !== "" && !c.roots.includes(defaultRoot)) c.roots.unshift(defaultRoot);
 	let rolesOf = null;
 	if (opts.withRoles === true) {
-		const { readSkiffRoles } = await import("./skiff-role-KqQA6pkr.js").then((n) => n.u);
+		const { readSkiffRoles } = await import("./skiff-role-DQZ6eR51.js").then((n) => n.u);
 		rolesOf = (root) => [...readSkiffRoles(root).keys()];
 	}
 	return c.roots.map((root) => ({

package/lib/client.js

@@ -4812,6 +4812,7 @@ Instruction-following style:
 			const publicAskOn = value?.publicAskEnabled ?? false;
 			const croOn = value?.croEnabled ?? true;
 			const unattendedOn = value?.unattendedEnabled ?? false;
+			const diagramOn = value?.diagramEnabled ?? false;
 			const [openGateway, setOpenGateway] = (0, react.useState)(false);
 			const [openRebuild, setOpenRebuild] = (0, react.useState)(false);
 			const [openSkiff, setOpenSkiff] = (0, react.useState)(false);
@@ -4819,6 +4820,7 @@ Instruction-following style:
 			const [openPublicAsk, setOpenPublicAsk] = (0, react.useState)(false);
 			const [openCro, setOpenCro] = (0, react.useState)(false);
 			const [openUnattended, setOpenUnattended] = (0, react.useState)(false);
+			const [openDiagram, setOpenDiagram] = (0, react.useState)(false);
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: "ss-section",
 				children: [
@@ -5000,6 +5002,27 @@ Instruction-following style:
 							}) })
 						]
 					}),
+					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Group, {
+						title: "工具",
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("li", { children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(RowCard, {
+							title: "图（diagram）",
+							desc: "agent 给一段标签式源码，进程内直接画出 PNG 并贴进对话（不借浏览器；默认关）",
+							expandable: true,
+							open: openDiagram,
+							onToggle: setOpenDiagram,
+							control: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Toggle, {
+								checked: diagramOn,
+								onChange: (on) => toggle("diagramEnabled", on)
+							}),
+							detail: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+								className: "ss-detailStack",
+								children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+									className: "ss-detailIntro",
+									children: "图（diagram 工具）\n· 作用：agent 给一段**标签式源码**（<diagram> 根 ＋ <rect>/<arrow>/<text>/<color>/<legend>），\n  由 ACC **在进程内**画成图并贴进对话 —— 不启浏览器、不截图\n· 产物：图进对话记录（可回看、可被后续轮次引用、可转微信）；同时落两份文件在容器的\n  _tmp/diagram/（.svg 可读可改 ／ .png 是进对话的那份）\n· 自带体检：重叠块 ／ 标签溢出 ／ 悬空端点 ／ 线压字，四条**只告警不拦图**；\n  写错的图元被跳过并逐条报错，其余照画\n· 中文能画：字体**随插件内置**（约 3.8 MB）—— 光栅化引擎看不见系统字体，只能喂内置的\n· 默认关：它是 owner 要的 demo 功能；**关着的时候工具根本不注册**（模型看不到它，不占上下文）\n· 图要贴进对话有个前提：**当前模型路由要声明收图像输入**。没声明时图照样画、照样落盘，\n  回执里写明原因并给路径（同「读图」工具的门）"
+								})
+							})
+						}) })
+					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)(Collapse, {
 						title: "彩蛋模式",
 						desc: "persona 输出风格（默认关闭）",

package/lib/diagram/dsl-render.d.ts

@@ -0,0 +1,8 @@
+import type { DslModel } from './dsl.js';
+export interface DslRender {
+    svg: string;
+    lint: string[];
+    errors: string[];
+    marks: number;
+}
+export declare function renderDsl(model: DslModel): DslRender;

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/rasterize.d.ts

@@ -0,0 +1,28 @@
+/** 字体资产相对包根的路径（**必须同时出现在 package.json 的 files 白名单里**，pack-check 会核对） */
+export declare const DIAGRAM_FONT_ASSET = "assets/diagram/DroidSansFallbackFull.ttf";
+/** 字体绝对路径（导出以便测试与 pack-check 共用同一判据来源） */
+export declare function diagramFontPath(): string;
+/**
+ * 内置字体的族名。SVG 里声明的 `Noto Sans CJK SC` ／ `Source Han Sans SC` ／ `Microsoft YaHei`
+ * 在本机**一个都不存在**（本机 CJK 覆盖只有 AR PL UMing ＋ Droid Sans Fallback）
+ * ⇒ 光栅化时必须由这里兜底，否则中文会退化成缺字方框。
+ */
+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/host/contract.d.ts

@@ -61,8 +61,40 @@ type HostEventName = (typeof HOST_EVENT_NAMES)[number];
  * dsp 订阅的宿主事件清单（与 HOST_EVENT_NAMES 同源；impact/site 供 health 报告与文档）。
  */
 export declare const HOST_EVENTS: readonly HostEventContract[];
-/** dsp 被验证过的宿主版本范围（与 package.json peerDependencies 同源，单一真相源） */
-export declare const REQUIRED_HOST_RANGE = "^0.1.7-rc.1";
+/**
+ * dsp **被验证过的宿主版本档**（单一真相源）—— 每档 = 一个半开区间 `[floor, ceiling)`。
+ *
+ * 🔴 为什么是"档"而不是一条 caret 范围（R↓：2026-09-28 0.2.0-rc.1 适配轮实测得出）：
+ *  - **宿主门的判据是真 semver**（`@deepseek-ai/dsh-app-boot:evaluatePluginCompatibility`
+ *    = `semver.satisfies(runtime, range, { includePrerelease: true })`）⇒ **它支持 `||` 联合范围**；
+ *  - 而 **dsp 这边是手写比较器**（{@link compareSemver}），**不实现 semver 的 range 语义**：
+ *    旧写法"用正则从 `REQUIRED_HOST_RANGE` 剥前缀取 floor"在**联合范围上会取到垃圾**
+ *    （`^0.1.7-rc.1 || ^0.2.0-rc.1` 的预发布捕获组 `(.*)` 会**吞掉 `||` 之后整段**）
+ *    ⇒ 判定**变瞎**（既非"通过"也非"低于下限"，而是不可解释的值）。
+ *  ⇒ 故**档表是唯一被验证的真相**：`REQUIRED_HOST_RANGE`（给宿主门看的串）与
+ *    `checkHostVersion`（给自己的手写比较器）**都从它派生**，两者不可能互相漂移。
+ *
+ * 🔴 两档的由来（**实测，非推断**；判据表见插件仓 `docs/dsh-0.2.0-rc.1-adaptation-plan.md` §7.4）：
+ *  - `^0.1.7-rc.1` 在 `0.2.0-rc.1` 上被宿主**整包拒绝 ＋ 回滚**
+ *    （逐字 `installation rejected: … incompatible with dsh 0.2.0-rc.1` ＋ `restored package.json, …`）；
+ *  - 单档 `^0.2.0-rc.1` 会**同样硬拒本机正在跑的 `0.1.7-rc.2`**
+ *    ⇒ 发布后 deploy 必须先升宿主，**而升级会打断本容器**；
+ *  - ⇒ 双档是**唯一不把本机宿主堵死的写法**（两档在真 semver 下均 PASS）。
+ * 档上界取 `<0.2.0` / `<0.3.0`（即 `^0.2.0-rc.1` 的 caret 上界）：第二档同时覆盖
+ * `0.2.0` 正式版与后续 `0.2.0-rc.N`。
+ */
+export declare const VERIFIED_HOST_BANDS: readonly {
+    floor: string;
+    ceiling: string;
+}[];
+/**
+ * 与 `package.json` 的 `peerDependencies` **逐字同串**的宿主版本范围（由 {@link VERIFIED_HOST_BANDS} 派生）。
+ *
+ * 🔴 这个字符串**就是**宿主门（`evaluatePluginCompatibility`）拿去跑 `semver.satisfies` 的那个串
+ * ⇒ 它与档表**必须一致**（"声明 union、判定单档"是一种自相矛盾）。
+ * 一致性由 `tests/host-contract.test.ts` 的**跨文件对账用例**钉住（读 package.json 逐字比对）。
+ */
+export declare const REQUIRED_HOST_RANGE: string;
 interface HostContractIssue {
     id: string;
     kind: 'service' | 'member' | 'version';
@@ -80,13 +112,14 @@ export interface HostContractReport {
 /** 最小 semver 比较（无依赖）：返回 -1 / 0 / 1；解析失败返回 null */
 export declare function compareSemver(a: string, b: string): number | null;
 /**
- * 宿主版本是否落在 dsp 被验证的范围（`REQUIRED_HOST_RANGE`）。
+ * 宿主版本是否落在 dsp **被验证过的档**（{@link VERIFIED_HOST_BANDS}）之内。
  * 无版本信息 → 视为未知（ok=false，detail 说明），不猜测。
  *
- * floor/ceiling **从 `REQUIRED_HOST_RANGE` 派生**（v1.31.6，0.1.5-rc.1 适配轮）：
- * 此前 floor 是独立硬编码字面量——改 `REQUIRED_HOST_RANGE` 而忘改 floor 会造出
- * "常量说 0.1.5、判定用 0.1.2" 的双真相源。ceiling 无法从 caret 语义机械派生（手写比较器
- * 不实现 semver 的 caret 规则），故保留显式常量并在此声明其含义。
+ * 🔴 **逐档判**（v1.50.x，0.2.0-rc.1 适配轮）：判据 = "∃ 档：`version >= floor ∧ version < ceiling`"。
+ * 曾经的做法是"从 `REQUIRED_HOST_RANGE` 剥前缀取一个 floor ＋ 一个显式 ceiling"——
+ * **单档假设一旦不成立（改联合范围），那个正则就会取到垃圾**（详见 {@link VERIFIED_HOST_BANDS}
+ * 的注释）⇒ 故本函数**只读档表**，不再从范围串反推。
+ * ⚠️ 手写比较器**不实现 semver 的 range 语义**（本条只做"区间内/外"），这也是必须逐档判的原因。
  */
 export declare function checkHostVersion(version: string | null): {
     ok: boolean;