dsh-markdown-typora 0.3.5 → 0.3.11

package/lib/index.js

@@ -1,1120 +1,1506 @@
-// dsh-markdown-typora 宿主半边（DSH 0.2.1 契约版）：
-//   renderer-cm6 静态路由 + 版本守卫编辑面 API（open/save/stat/edit）+ SSE watch + markdown 模型工具。
-//
-// 插件三件套形状（宿主 cordis loader 读的就是这个）：
-//   export const name / export const inject / export function apply(ctx)
-//
-// 架构（见 README.md）：引擎 0 改动，插件只做 DSH 皮/桥/文件 IO。
-//   · 静态资源来自插件根 renderer-cm6/（core-sync 从 EXE 构建产物逐字节同步）；
-//   · 所有写都走 ctx.fs 的版本守卫（FS_STALE_VERSION 拒绝盲写，冲突不覆盖）；
-//   · save 的 baseVersion 必填 —— 关 tab 的 keepalive flush 也一样，服务端不做"缺版本就无条件写"；
-//   · 写成功后向所有 SSE 连接广播 version（客户端按 path 过滤 + 脏缓冲不覆盖）。
-//
-// 保留的既有不变量：
-//   1. 信任栅栏：ctx.connection.requestRejection 可用就以方法形式调用；否则只放行 loopback。
-//   2. body 上限 64MB：含内联图的 Markdown 十几 MB 在真实用户里常见（8MB 曾把 8.13MB 文档拒之门外）。
-//   3. fs.watch 是 async（返回 close 函数）；不支持时降级为 2s 探测。旧实现把它当同步调用 ⇒
-//      unhandled rejection + watcher 泄漏。这里 await 捕获并幂等 close。
-//   4. 每个 async 分支都有 try/catch，错误以 {ok:false,error:{code,message}} 返回，code 原样透传。
-
-import { readFile, stat as fsStat, writeFile as fsWriteFile } from 'node:fs/promises';
-import { createReadStream } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join, normalize, sep, extname } from 'node:path';
-
-export const name = 'dsh-markdown-typora';
-
-/** 必需服务：webServer（路由挂载点）+ fs（版本守卫读写）。 */
-export const inject = ['webServer', 'fs'];
-
-const ROUTE_PREFIX = '/dsh-markdown-typora';
-const STATIC_PREFIX = ROUTE_PREFIX + '/renderer-cm6/';
-const API_PREFIX = ROUTE_PREFIX + '/api/';
-const IMG_PREFIX = ROUTE_PREFIX + '/img/';
-const CORE_JSON_PATH = ROUTE_PREFIX + '/core.json';
-const KNOWN_ENDPOINTS = new Set(['open', 'save', 'stat', 'edit']);
-const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '::1']);
-
-/** 请求体上限：64MB。含内联图文档常见 10MB+；上限之外明确 413，不静默截断。 */
-export const BODY_MAX_BYTES = 64 * 1024 * 1024;
-/** 本地图片响应上限：与请求体同口径。超过只给 413，不把整块内容读进内存。 */
-export const IMAGE_MAX_BYTES = 64 * 1024 * 1024;
-const WATCH_DEBOUNCE_MS = 120;
-const WATCH_PROBE_MS = 2000;
-const SSE_HEARTBEAT_MS = 15000;
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-export const PLUGIN_ROOT = normalize(join(HERE, '..'));
-
-/** 静态资源 MIME 表（含 CM6 引擎实际用到的 woff/woff2/ttf/wasm/map，以及 mermaid 的 svg/png）。 */
-export const MIME_BY_EXT = {
-  '.html': 'text/html; charset=utf-8',
-  '.htm': 'text/html; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.cjs': 'text/javascript; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.map': 'application/json; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.ttf': 'font/ttf',
-  '.otf': 'font/otf',
-  '.eot': 'application/vnd.ms-fontobject',
-  '.wasm': 'application/wasm',
-  '.txt': 'text/plain; charset=utf-8',
-};
-
-export function mimeFor(filePath) {
-  return MIME_BY_EXT[extname(String(filePath)).toLowerCase()] ?? 'application/octet-stream';
-}
-
-/** ETag 由 size-mtime 组成（要求口径）；mtime 取整毫秒，避免频繁重建时抖动。 */
-export function makeEtag(size, mtimeMs) {
-  const s = Number.isFinite(Number(size)) ? Math.trunc(Number(size)) : 0;
-  const m = Number.isFinite(Number(mtimeMs)) ? Math.trunc(Number(mtimeMs)) : 0;
-  return `"${s}-${m}"`;
-}
-
-/** If-None-Match 匹配（支持 *、逗号列表、弱前缀 W/）。命中返回 304。 */
-export function isNotModified(ifNoneMatch, etag) {
-  if (typeof ifNoneMatch !== 'string' || ifNoneMatch.length === 0) return false;
-  if (ifNoneMatch.trim() === '*') return true;
-  return ifNoneMatch
-    .split(',')
-    .map((part) => part.trim().replace(/^W\//, ''))
-    .some((candidate) => candidate === etag);
-}
-
-/**
- * 缓存策略：
- *   · 入口 HTML、app.js/app.css、dsh-*.js：no-cache（每次带 ETag 校验，拿 304）；
- *   · 字体（woff/woff2/ttf/otf/eot）：public, max-age=604800 —— 内容哈希文件名，长缓存安全；
- *   · 其余（worker/mermaid/图标）：no-cache + ETag。
- */
-export function cacheControlFor(filePath) {
-  const base = String(filePath).split(/[\\/]/).pop() ?? '';
-  const ext = extname(base).toLowerCase();
-  if (ext === '.woff' || ext === '.woff2' || ext === '.ttf' || ext === '.otf' || ext === '.eot') {
-    return 'public, max-age=604800';
-  }
-  if (base === 'index.html' || base === 'app.js' || base === 'app.css' || /^dsh-[^/]*\.js$/i.test(base)) {
-    return 'no-cache';
-  }
-  return 'no-cache';
-}
-
-/**
- * 把一个 URL 相对路径解析成 renderer-cm6 根内的绝对路径；越界/编码异常/盘符/空字节一律 null。
- * 这是路径穿越防护的唯一入口（纯函数，可被测试直接覆盖）。
- */
-export function resolveStaticTarget(rootDir, rawRelative) {
-  if (typeof rawRelative !== 'string') return null;
-  let decoded;
-  try {
-    decoded = decodeURIComponent(rawRelative);
-  } catch {
-    return null;
-  }
-  if (decoded.length === 0) decoded = 'index.html';
-  if (decoded.includes('\0')) return null;
-  const slashed = decoded.replace(/\\/g, '/');
-  if (slashed.startsWith('/')) return null;
-  if (/^[A-Za-z]:/.test(slashed)) return null;
-  const segments = slashed.split('/');
-  if (segments.some((segment) => segment === '..')) return null;
-  const root = normalize(rootDir);
-  const target = normalize(join(root, slashed));
-  if (target !== root && !target.startsWith(root + sep)) return null;
-  return target;
-}
-
-/* ══ 本地图片路由（文档相对路径图的取字节通道）══════════════════════════════════════
- * 为什么需要：CM6 引擎按"当前文档所在目录"解析相对图片路径（`image-path.js` 的
- * resolveImageSource）；桌面壳把它拼成 file:// 并靠 file 页面读盘。DSH 的编辑面是
- * **http 源**：CSP 的 img-src 不含 file:，Chromium 也禁止 http 页面加载 file:// 子资源
- * ⇒ 相对路径图必然"图片加载失败"。所以由插件提供唯一合法的本地图片通道：
- *   GET /dsh-markdown-typora/img/<绝对本地路径（逐段百分号编码，保留 /）>
- * 桥（renderer-cm6/dsh-bridge.js）在 open 时把 <base href> 指到
- *   /dsh-markdown-typora/img/<文档目录>/
- * ⇒ 引擎发出的相对 URL 原样落到本路由。浏览器按 RFC 3986 自己归一化 `../`，
- * 因此这里拿到的永远是规整的绝对路径。
- *
- * 安全边界（三条都必须成立，缺一即拒）：
- *   ① 形态：只接受盘符绝对路径（D:/x/y.png）或 UNC（//server/share/y.png），
- *      拒空段 / 单点 / 双点 / NUL / 坏编码 —— 归一化不靠浏览器，自己逐段验；
- *   ② 扩展名：图片白名单之外一律不服务（本路由不是通用文件服务）；
- *   ③ 只在既有信任栅栏之后（loopback + 宿主鉴权），且只读、只 GET/HEAD。
- * 说明：该读面不强于既有 /api/open（它本来就能读任意路径文本）。 */
-
-/** 图片 MIME（本路由专用；比静态表窄，且不接受 fonts/wasm 之类）。 */
-export const IMAGE_MIME_BY_EXT = {
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.jfif': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.bmp': 'image/bmp',
-  '.avif': 'image/avif',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
-};
-
-export function imageMimeFor(filePath) {
-  return IMAGE_MIME_BY_EXT[extname(String(filePath)).toLowerCase()] ?? null;
-}
-
-/**
- * 把 URL 里 `/img/` 之后的剩余路径还原成**绝对本地路径**；不合规一律 null（纯函数）。
- * 规则见本节注释①。解码逐段进行：`%2e%2e` 解出来是 `..`，同样被拒。
- */
-export function decodeImageRequestPath(rawPath) {
-  if (typeof rawPath !== 'string' || rawPath.length === 0) return null;
-  const slashed = rawPath.replace(/\\/g, '/');
-  let unc = false;
-  let rest = slashed;
-  if (rest.startsWith('//')) { unc = true; rest = rest.slice(2); }
-  else if (rest.startsWith('/')) rest = rest.slice(1);
-  if (rest.length === 0) return null;
-  const segments = rest.split('/');
-  const decoded = [];
-  // Windows 设备名段（CON/NUL/COM1…）会被当成设备打开：读 CON 可能把请求挂住，
-  // 所以连"图片扩展名"都不看，段一级直接拒。
-  const DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
-  for (const segment of segments) {
-    let value;
-    try {
-      value = decodeURIComponent(segment);
-    } catch {
-      return null;
-    }
-    if (value.length === 0) return null;
-    if (value === '.' || value === '..') return null;
-    if (value.includes('\0')) return null;
-    if (/[\\/]/.test(value)) return null;   // %2f/%5c 解出来的分隔符不许再切一层
-    if (DEVICE_NAME.test(value)) return null;
-    if (decoded.length > 0 && value.includes(':')) return null;   // 备用数据流（a.png:b）不收
-    decoded.push(value);
-  }
-  if (decoded.length < 1) return null;
-  let localPath;
-  if (unc) {
-    if (decoded.length < 2) return null;    // //server 后面至少还要有共享名
-    localPath = '//' + decoded.join('/');
-  } else {
-    if (!/^[A-Za-z]:$/.test(decoded[0])) return null;   // 必须是盘符绝对路径
-    if (decoded.length < 2) return null;
-    localPath = decoded[0].toUpperCase() + '/' + decoded.slice(1).join('/');
-  }
-  if (!imageMimeFor(localPath)) return null;
-  return normalize(localPath);
-}
-
-/** 服务一次本地图片请求：ETag/304、HEAD、大小上限、流式输出。返回是否已响应。 */
-export async function serveImageFile(req, res, rawPath) {
-  const method = req?.method === 'HEAD' ? 'HEAD' : 'GET';
-  const target = decodeImageRequestPath(rawPath);
-  if (!target) {
-    sendText(res, 400, 'bad image path');
-    return false;
-  }
-  let info;
-  try {
-    info = await fsStat(target);
-  } catch (error) {
-    sendText(res, error?.code === 'ENOENT' ? 404 : 500, error?.code === 'ENOENT' ? 'not found' : 'stat error');
-    return false;
-  }
-  if (!info.isFile()) {
-    sendText(res, 404, 'not found');
-    return false;
-  }
-  if (info.size > IMAGE_MAX_BYTES) {
-    sendText(res, 413, 'image too large');
-    return false;
-  }
-  const etag = makeEtag(info.size, info.mtimeMs);
-  const headers = {
-    'content-type': imageMimeFor(target),
-    'cache-control': 'no-cache',
-    etag,
-    'x-content-type-options': 'nosniff',
-    // SVG 在 <img> 里不执行脚本，但**直接导航**（地址栏/window.open）时就是同源文档、脚本可跑。
-    // 这条 CSP 对 <img> 渲染零影响，对文档导航把脚本/表单/子资源全部中和。
-    'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox",
-  };
-  if (isNotModified(req.headers['if-none-match'], etag)) {
-    res.writeHead(304, headers);
-    res.end();
-    return true;
-  }
-  // 不写 content-length：stat 与流之间有 TOCTOU（文件被改写会截断/挂住）。
-  // 交给 chunked 传输，浏览器按流读完即可。
-  res.writeHead(200, headers);
-  if (method === 'HEAD') {
-    res.end();
-    return true;
-  }
-  await new Promise((resolve) => {
-    let settled = false;
-    const done = () => { if (settled) return; settled = true; resolve(); };
-    const stream = createReadStream(target);
-    stream.on('error', () => { try { res.destroy(); } catch { /* 已断 */ } done(); });
-    stream.on('end', done);
-    res.on('close', () => { try { stream.destroy(); } catch { /* 已断 */ } done(); });
-    stream.pipe(res);
-  });
-  return true;
-}
-
-/** FsError 等错误的稳定码（分支认码不认文案；不许把 code 吞成 message）。 */
-export function errorCode(error) {
-  const code = error?.code ?? error?.cause?.code;
-  if (typeof code === 'string' && code.length > 0) return code;
-  if (error?.name === 'AbortError') return 'FS_ABORTED';
-  return 'fs-error';
-}
-
-/**
- * DSH 文件策略拒绝这次写入（workspace-write 只允许会话工作区内的路径）。
- * 只在这个明确码/文案上走原生 fs 回退；OS 的 EACCES/EPERM 仍然照常失败。
- */
-export function isSandboxWriteDenied(error) {
-  if (errorCode(error) === 'FS_SANDBOX_DENIED') return true;
-  const message = String(error?.message ?? error ?? '');
-  return /file access denied under (workspace-write|read-only) mode/i.test(message);
-}
-
-function codedError(code, message) {
-  const error = new Error(String(message));
-  error.code = code;
-  return error;
-}
-
-/** ctx.fs 的 target 同时带 displayPath 和 realpath targetKey；原生写用后者。 */
-function nativeTargetPath(target) {
-  const key = target?.targetKey;
-  if (typeof key === 'string' && key.length > 0) return key;
-  const displayPath = target?.displayPath;
-  return typeof displayPath === 'string' ? displayPath : '';
-}
-
-/** 与 dsh-fs-local 的 versionOf 同形：dev:ino:size:mtimeNs:ctimeNs（bigint）。 */
-function versionOfBigInt(info) {
-  return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
-}
-
-/**
- * 沙箱拒绝写入时的原生 fs 回退。保留版本守卫：先读 ctx.fs.stat（读路径在
- * workspace-write 下仍可用），baseVersion 不匹配照样报 FS_STALE_VERSION；
- * 写后优先用 ctx.fs.stat 的新版本，读不到才用同形的 bigint 版本。
- *
- * 注意：这是用户明确要求的“绕过 DSH 文件策略”，只对 Markdown 文档保存生效，
- * 不改变插件其它 fs 能力；OS 权限错误不会被吞掉。
- */
-async function directWriteText(fs, target, text, baseVersion) {
-  const path = nativeTargetPath(target);
-  if (!path) throw codedError('FS_IO_ERROR', 'direct write: target has no native path');
-  let before = null;
-  try { before = await fs.stat(target); } catch { before = null; }
-  if (before) {
-    if (String(before.version) !== String(baseVersion)) {
-      throw codedError('FS_STALE_VERSION', 'file changed since read');
-    }
-  } else {
-    const info = await fsStat(path, { bigint: true }).catch(() => null);
-    if (!info) throw codedError('FS_NOT_FOUND', `not found: ${target.displayPath ?? path}`);
-    if (versionOfBigInt(info) !== String(baseVersion)) {
-      throw codedError('FS_STALE_VERSION', 'file changed since read');
-    }
-  }
-  await fsWriteFile(path, String(text), 'utf8');
-  let after = null;
-  try { after = await fs.stat(target); } catch { after = null; }
-  if (after) return { version: after.version, displayPath: target.displayPath };
-  const info = await fsStat(path, { bigint: true });
-  return { version: versionOfBigInt(info), displayPath: target.displayPath };
-}
-
-
-function textBlock(text) {
-  return [{ type: 'text', text: String(text ?? '') }];
-}
-
-function badRequest(message) {
-  return { ok: false, error: { code: 'bad-request', message } };
-}
-
-function hostnameOf(hostHeader) {
-  if (typeof hostHeader !== 'string' || hostHeader.length === 0) return '';
-  if (hostHeader.startsWith('[')) {
-    const end = hostHeader.indexOf(']');
-    return end > 0 ? hostHeader.slice(1, end).toLowerCase() : '';
-  }
-  return hostHeader.split(':')[0].toLowerCase();
-}
-
-/** loopback 兜底栅栏：Host 必须本机；跨站请求拒绝；有 Origin 时必须与 Host 同源。 */
-export function isTrustedLoopbackRequest(req) {
-  const host = req?.headers?.host;
-  if (!host) return false;
-  const hostname = hostnameOf(host);
-  if (!LOOPBACK_HOSTNAMES.has(hostname)) return false;
-  if (req.headers['sec-fetch-site'] === 'cross-site') return false;
-  const origin = req.headers.origin;
-  if (origin === undefined) return true;
-  try {
-    return new URL(origin).host.toLowerCase() === String(host).toLowerCase();
-  } catch {
-    return false;
-  }
-}
-
-/**
- * 读请求体，超限返回 {ok:false,code:'too-large'}；网络错误返回 {ok:false,code:'request-error'}。
- * 超限后暂停消费剩余数据（不把 64MB 之外的攻击流量继续读进内存）。
- */
-export function readBody(req, limit = BODY_MAX_BYTES) {
-  return new Promise((resolve) => {
-    const chunks = [];
-    let total = 0;
-    let settled = false;
-    const finish = (value) => {
-      if (settled) return;
-      settled = true;
-      resolve(value);
-    };
-    req.on('data', (chunk) => {
-      if (settled) return;
-      total += chunk.length;
-      if (total > limit) {
-        chunks.length = 0;
-        req.pause();
-        finish({ ok: false, code: 'too-large' });
-        return;
-      }
-      chunks.push(chunk);
-    });
-    req.on('end', () => finish({ ok: true, buffer: Buffer.concat(chunks) }));
-    req.on('error', () => finish({ ok: false, code: 'request-error' }));
-    req.on('aborted', () => finish({ ok: false, code: 'request-error' }));
-  });
-}
-
-function sendJson(res, status, value, extraHeaders) {
-  const body = Buffer.from(JSON.stringify(value), 'utf8');
-  if (res.headersSent) {
-    try { res.end(); } catch { /* 已断 */ }
-    return;
-  }
-  res.writeHead(status, {
-    'content-type': 'application/json; charset=utf-8',
-    'cache-control': 'no-store',
-    'content-length': body.length,
-    ...extraHeaders,
-  });
-  res.end(body);
-}
-
-function sendText(res, status, text, extraHeaders) {
-  if (res.headersSent) {
-    try { res.end(); } catch { /* 已断 */ }
-    return;
-  }
-  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8', ...extraHeaders });
-  res.end(text);
-}
-
-/**
- * 宿主核心：把 ctx 依赖收成一个可独立测试的对象。
- * @param {{fs:object, log?:object, rootDir?:string, bodyLimit?:number, watchDebounceMs?:number,
- *          watchProbeMs?:number, heartbeatMs?:number, connectionProvider?:() => any}} [options]
- */
-export function createHost(options = {}) {
-  const fs = options.fs;
-  if (!fs || typeof fs.resolve !== 'function' || typeof fs.writeText !== 'function') {
-    throw new Error('dsh-markdown-typora: a filesystem service (ctx.fs) is required');
-  }
-  const log = options.log ?? console;
-  const rootDir = normalize(options.rootDir ?? PLUGIN_ROOT);
-  const staticRoot = normalize(join(rootDir, 'renderer-cm6'));
-  const coreJsonFile = normalize(join(rootDir, 'core.json'));
-  const bodyLimit = options.bodyLimit ?? BODY_MAX_BYTES;
-  const watchDebounceMs = options.watchDebounceMs ?? WATCH_DEBOUNCE_MS;
-  const watchProbeMs = options.watchProbeMs ?? WATCH_PROBE_MS;
-  const heartbeatMs = options.heartbeatMs ?? SSE_HEARTBEAT_MS;
-  const connectionProvider = typeof options.connectionProvider === 'function'
-    ? options.connectionProvider
-    : () => undefined;
-
-  /** 每个被观察文件一条 entry；refs 计数到 0 才释放（SSE 多 tab 共享）。 */
-  const watchers = new Map();
-  /** 所有活着的 SSE 连接：{ res, targetKey }。广播按"所有连接"发出，客户端按 path 过滤。 */
-  const liveStreams = new Set();
-
-  function watchKeyOf(target) {
-    return String(target?.targetKey ?? target?.displayPath ?? '');
-  }
-
-  function broadcastChange(target, version, delta) {
-    const data = {
-      path: target?.displayPath,
-      targetKey: target?.targetKey,
-      version: String(version ?? ''),
-      ...(delta ? { delta: { oldString: String(delta.oldString ?? '').slice(0, 400), newString: String(delta.newString ?? '').slice(0, 400) } } : {}),
-    };
-    const frame = `event: change\ndata: ${JSON.stringify(data)}\n\n`;
-    for (const stream of liveStreams) {
-      try {
-        stream.res.write(frame);
-      } catch { /* 连接已断，close 事件会清理 */ }
-    }
-  }
-
-  async function tickWatch(entry, baseline = false) {
-    if (entry.disposed) return;
-    let version = '';
-    let missing = false;
-    try {
-      const info = await fs.stat(entry.target);
-      if (info === undefined) missing = true;
-      else version = String(info.version ?? '');
-    } catch {
-      return;
-    }
-    if (entry.disposed) return;
-    const changed = entry.lastVersion !== undefined && (missing || version !== entry.lastVersion);
-    if (changed && !baseline) {
-      if (entry.debounce) clearTimeout(entry.debounce);
-      entry.debounce = setTimeout(() => {
-        entry.debounce = null;
-        if (!entry.disposed) broadcastChange(entry.target, version);
-      }, watchDebounceMs);
-      entry.debounce.unref?.();
-    }
-    if (!missing) entry.lastVersion = version;
-  }
-
-  async function startWatch(entry) {
-    if (entry.started) return;
-    entry.started = true;
-    // FS.watch 是 async：resolve 为 close 函数；不支持时 reject（FS_IO_ERROR）。旧实现把它当
-    // 同步调用且不 catch —— 这里必须 await 并保留 close，否则 watcher 泄漏 / unhandled rejection。
-    try {
-      const close = await fs.watch(entry.target, () => { void tickWatch(entry); }, entry.controller.signal);
-      if (entry.disposed) {
-        try { if (typeof close === 'function') await close(); } catch { /* 已停 */ }
-        return;
-      }
-      entry.close = typeof close === 'function' ? close : null;
-    } catch (error) {
-      if (entry.disposed) return;
-      log.warn?.('%s: fs.watch unavailable (%s) — SSE 退化为 %dms 探测', name, String(error?.message ?? error), watchProbeMs);
-      entry.timer = setInterval(() => { void tickWatch(entry); }, watchProbeMs);
-      entry.timer.unref?.();
-    }
-    await tickWatch(entry, true);
-  }
-
-  function ensureWatch(target) {
-    const key = watchKeyOf(target);
-    let entry = watchers.get(key);
-    if (entry) {
-      entry.refs += 1;
-      return entry;
-    }
-    entry = {
-      refs: 1,
-      target,
-      lastVersion: undefined,
-      controller: new AbortController(),
-      close: null,
-      timer: null,
-      debounce: null,
-      disposed: false,
-      started: false,
-    };
-    watchers.set(key, entry);
-    void startWatch(entry);
-    return entry;
-  }
-
-  function releaseWatch(target) {
-    const key = watchKeyOf(target);
-    const entry = watchers.get(key);
-    if (!entry) return;
-    entry.refs -= 1;
-    if (entry.refs > 0) return;
-    watchers.delete(key);
-    entry.disposed = true;
-    try { entry.controller.abort(); } catch { /* 已停 */ }
-    if (entry.timer) clearInterval(entry.timer);
-    if (entry.debounce) clearTimeout(entry.debounce);
-    const close = entry.close;
-    entry.close = null;
-    if (typeof close === 'function') {
-      Promise.resolve().then(() => close()).catch(() => { /* close 失败不影响进程 */ });
-    }
-  }
-
-  async function serveStatic(req, res, rawRelative) {
-    const target = resolveStaticTarget(staticRoot, rawRelative);
-    if (!target) {
-      sendText(res, 403, 'forbidden');
-      return;
-    }
-    let info;
-    try {
-      info = await fsStat(target);
-    } catch (error) {
-      sendText(res, error?.code === 'ENOENT' ? 404 : 500, error?.code === 'ENOENT' ? 'not found' : 'stat error');
-      return;
-    }
-    let filePath = target;
-    if (info.isDirectory()) {
-      filePath = join(target, 'index.html');
-      try {
-        info = await fsStat(filePath);
-      } catch {
-        sendText(res, 404, 'not found');
-        return;
-      }
-    }
-    if (!info.isFile()) {
-      sendText(res, 404, 'not found');
-      return;
-    }
-    const etag = makeEtag(info.size, info.mtimeMs);
-    const headers = {
-      'content-type': mimeFor(filePath),
-      'cache-control': cacheControlFor(filePath),
-      etag,
-      'x-content-type-options': 'nosniff',
-    };
-    if (isNotModified(req.headers['if-none-match'], etag)) {
-      res.writeHead(304, headers);
-      res.end();
-      return;
-    }
-    let data;
-    try {
-      data = await readFile(filePath);
-    } catch {
-      sendText(res, 500, 'read error');
-      return;
-    }
-    res.writeHead(200, { ...headers, 'content-length': data.length });
-    res.end(req.method === 'HEAD' ? undefined : data);
-  }
-
-  async function serveCoreJson(req, res) {
-    let data;
-    try {
-      data = await readFile(coreJsonFile);
-    } catch (error) {
-      // 不生成 core.json 的旧包也不能让客户端崩：明确 404 + 可诊断文案。
-      sendJson(res, error?.code === 'ENOENT' ? 404 : 500, {
-        ok: false,
-        error: {
-          code: error?.code === 'ENOENT' ? 'not-found' : 'fs-error',
-          message: error?.code === 'ENOENT'
-            ? 'core.json has not been generated yet (run scripts/sync-core.mjs)'
-            : String(error?.message ?? error),
-        },
-      });
-      return;
-    }
-    const headers = { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' };
-    try {
-      const info = await fsStat(coreJsonFile);
-      const etag = makeEtag(info.size, info.mtimeMs);
-      headers.etag = etag;
-      if (isNotModified(req.headers['if-none-match'], etag)) {
-        res.writeHead(304, headers);
-        res.end();
-        return;
-      }
-    } catch { /* 无 stat 也要能返回内容 */ }
-    res.writeHead(200, { ...headers, 'content-length': data.length });
-    res.end(req.method === 'HEAD' ? undefined : data);
-  }
-
-  /** GET /dsh-markdown-typora/api/watch?path=…：SSE 外部变更流；心跳 15s；close 幂等清理。 */
-  async function handleWatch(req, res, url) {
-    const path = url.searchParams.get('path') ?? '';
-    if (!path) {
-      sendJson(res, 400, badRequest('path is required'));
-      return;
-    }
-    let target;
-    try {
-      target = await fs.resolve(path);
-    } catch (error) {
-      sendJson(res, 200, { ok: false, error: { code: errorCode(error), message: String(error?.message ?? error) } });
-      return;
-    }
-    if (res.headersSent) return;
-    res.writeHead(200, {
-      'content-type': 'text/event-stream; charset=utf-8',
-      'cache-control': 'no-store',
-      connection: 'keep-alive',
-      'x-content-type-options': 'nosniff',
-    });
-    res.write('retry: 2000\n\n');
-    const stream = { res, targetKey: watchKeyOf(target) };
-    liveStreams.add(stream);
-    const heartbeat = setInterval(() => {
-      try { res.write(': ping\n\n'); } catch { /* close 清理 */ }
-    }, heartbeatMs);
-    heartbeat.unref?.();
-    const entry = ensureWatch(target);
-    let closed = false;
-    const cleanup = () => {
-      if (closed) return;
-      closed = true;
-      clearInterval(heartbeat);
-      liveStreams.delete(stream);
-      releaseWatch(target);
-    };
-    req.on('close', cleanup);
-    req.on('aborted', cleanup);
-    res.on('close', cleanup);
-    res.on('error', cleanup);
-    try {
-      res.write(`event: ready\ndata: ${JSON.stringify({ path: target.displayPath, version: String(entry.lastVersion ?? '') })}\n\n`);
-    } catch { /* 已断 */ }
-  }
-
-  function resolveOptions(payload) {
-    const cwd = payload?.cwd;
-    return typeof cwd === 'string' && cwd.length > 0 ? { cwd } : undefined;
-  }
-
-  async function apiOpen(payload) {
-    const path = typeof payload?.path === 'string' ? payload.path : '';
-    if (!path) return badRequest('path is required');
-    const target = await fs.resolve(path, resolveOptions(payload));
-    const info = await fs.stat(target);
-    if (!info) return { ok: false, error: { code: 'FS_NOT_FOUND', message: `not found: ${target.displayPath}` } };
-    if (info.type !== 'file') {
-      return { ok: false, error: { code: 'FS_NOT_REGULAR_FILE', message: `not a regular file: ${target.displayPath}` } };
-    }
-    const text = await fs.readText(target);
-    return { ok: true, value: { text, version: info.version, displayPath: target.displayPath, size: info.size, type: info.type } };
-  }
-
-  async function apiSave(payload) {
-    const path = typeof payload?.path === 'string' ? payload.path : '';
-    const text = typeof payload?.text === 'string' ? payload.text : null;
-    const baseVersion = typeof payload?.baseVersion === 'string' ? payload.baseVersion : '';
-    if (!path) return badRequest('path is required');
-    if (text === null) return badRequest('text is required');
-    if (!baseVersion) return badRequest('baseVersion is required — refusing to overwrite without a version guard');
-    const target = await fs.resolve(path, resolveOptions(payload));
-    let result;
-    try {
-      result = await fs.writeText(target, text, { kind: 'replaceIfVersion', version: baseVersion });
-    } catch (error) {
-      if (!isSandboxWriteDenied(error)) throw error;
-      try {
-        log.warn?.('%s: DSH 文件策略拒绝写入 %s；按配置回退原生 fs 写入', name, target?.displayPath ?? path);
-      } catch { /* 日志失败不阻塞保存 */ }
-      result = await directWriteText(fs, target, text, baseVersion);
-    }
-    const version = result?.version;
-    broadcastChange(target, version);
-    return {
-      ok: true,
-      value: { version, displayPath: target.displayPath, size: Buffer.byteLength(text, 'utf8') },
-    };
-  }
-
-  async function apiStat(payload) {
-    const path = typeof payload?.path === 'string' ? payload.path : '';
-    if (!path) return badRequest('path is required');
-    const target = await fs.resolve(path, resolveOptions(payload));
-    const info = await fs.stat(target);
-    if (!info) return { ok: true, value: { missing: true } };
-    return { ok: true, value: { version: info.version, size: info.size, type: info.type, displayPath: target.displayPath } };
-  }
-
-  async function apiEdit(payload) {
-    const path = typeof payload?.path === 'string' ? payload.path : '';
-    const oldString = typeof payload?.oldString === 'string' ? payload.oldString : null;
-    const newString = typeof payload?.newString === 'string' ? payload.newString : null;
-    if (!path) return badRequest('path is required');
-    if (oldString === null || newString === null) return badRequest('oldString and newString are required');
-    const target = await fs.resolve(path, resolveOptions(payload));
-    const expected = typeof payload?.baseVersion === 'string' && payload.baseVersion.length > 0
-      ? { version: payload.baseVersion }
-      : undefined;
-    const result = await fs.editText(target, {
-      oldString,
-      newString,
-      replaceAll: payload?.replaceAll === true,
-    }, expected);
-    const version = result?.version;
-    broadcastChange(target, version, { oldString, newString });
-    return {
-      ok: true,
-      value: {
-        version,
-        displayPath: target.displayPath,
-        changed: result?.before !== result?.after,
-      },
-    };
-  }
-
-  async function dispatch(endpoint, payload) {
-    try {
-      switch (endpoint) {
-        case 'open': return await apiOpen(payload);
-        case 'save': return await apiSave(payload);
-        case 'stat': return await apiStat(payload);
-        case 'edit': return await apiEdit(payload);
-        default: return badRequest(`unknown endpoint: ${String(endpoint)}`);
-      }
-    } catch (error) {
-      const code = errorCode(error);
-      try { log.warn?.('%s: %s failed (%s): %s', name, String(endpoint), code, String(error?.message ?? error)); } catch { /* 日志失败不影响响应 */ }
-      return { ok: false, error: { code, message: String(error?.message ?? error) } };
-    }
-  }
-
-  /** 信任栅栏：requestRejection 以方法调用；不可用时只放行 loopback。 */
-  function fenceStatus(req) {
-    let rejection;
-    try {
-      let connection;
-      try { connection = connectionProvider(); } catch { connection = undefined; }
-      if (typeof connection?.requestRejection === 'function') {
-        try { rejection = connection.requestRejection.call(connection, req); } catch { rejection = 403; }
-      } else if (!isTrustedLoopbackRequest(req)) {
-        rejection = 403;
-      }
-    } catch {
-      rejection = isTrustedLoopbackRequest(req) ? undefined : 403;
-    }
-    if (rejection === undefined) return undefined;
-    return typeof rejection === 'number' ? rejection : 403;
-  }
-
-  async function handleApiPost(req, res, url) {
-    const endpoint = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '');
-    if (!KNOWN_ENDPOINTS.has(endpoint)) {
-      try { req.resume(); } catch { /* 已断 */ }
-      sendJson(res, 404, { ok: false, error: { code: 'not-found', message: `unsupported endpoint: ${String(endpoint)}` } });
-      return;
-    }
-    const mediaType = req.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase();
-    if (mediaType !== 'application/json') {
-      try { req.resume(); } catch { /* 已断 */ }
-      sendJson(res, 415, badRequest('content type must be application/json'));
-      return;
-    }
-    const body = await readBody(req, bodyLimit);
-    if (!body.ok) {
-      const status = body.code === 'too-large' ? 413 : 400;
-      sendJson(res, status, { ok: false, error: { code: body.code, message: body.code === 'too-large' ? `body exceeds ${bodyLimit} bytes` : 'body read failed' } }, { connection: 'close' });
-      return;
-    }
-    let payload;
-    try {
-      payload = JSON.parse(body.buffer.toString('utf8'));
-    } catch {
-      sendJson(res, 400, badRequest('body is not JSON'));
-      return;
-    }
-    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
-      sendJson(res, 400, badRequest('body must be a JSON object'));
-      return;
-    }
-    const result = await dispatch(endpoint, payload);
-    sendJson(res, 200, result);
-  }
-
-  const route = {
-    kind: 'prefix',
-    path: ROUTE_PREFIX,
-    handler: async (req, res) => {
-      try {
-        const rejection = fenceStatus(req);
-        if (rejection !== undefined) {
-          sendText(res, rejection, rejection === 401 ? 'unauthorized' : 'forbidden');
-          return;
-        }
-        let url;
-        try {
-          url = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
-        } catch {
-          sendText(res, 400, 'bad request');
-          return;
-        }
-        const pathname = url.pathname;
-        const isRead = req.method === 'GET' || req.method === 'HEAD';
-
-        if (isRead && pathname === CORE_JSON_PATH) {
-          await serveCoreJson(req, res);
-          return;
-        }
-        // 本地图片通道（文档相对路径图）：见 serveImageFile 上方注释。
-        if (isRead && pathname.startsWith(IMG_PREFIX)) {
-          await serveImageFile(req, res, pathname.slice(IMG_PREFIX.length));
-          return;
-        }
-        if (isRead && pathname === STATIC_PREFIX.slice(0, -1)) {
-          await serveStatic(req, res, 'index.html');
-          return;
-        }
-        if (isRead && pathname.startsWith(STATIC_PREFIX)) {
-          await serveStatic(req, res, pathname.slice(STATIC_PREFIX.length));
-          return;
-        }
-        if (req.method === 'GET' && pathname === API_PREFIX + 'watch') {
-          await handleWatch(req, res, url);
-          return;
-        }
-        if (req.method === 'POST' && pathname.startsWith(API_PREFIX)) {
-          await handleApiPost(req, res, url);
-          return;
-        }
-        sendJson(res, 404, { ok: false, error: { code: 'not-found', message: `not found: ${pathname}` } });
-      } catch (error) {
-        const code = errorCode(error);
-        try { log.warn?.('%s: request failed (%s): %s', name, code, String(error?.message ?? error)); } catch { /* 日志失败不影响响应 */ }
-        if (!res.headersSent) sendJson(res, 200, { ok: false, error: { code, message: String(error?.message ?? error) } });
-        else { try { res.end(); } catch { /* 已断 */ } }
-      }
-    },
-  };
-
-  function close() {
-    for (const stream of liveStreams) {
-      try { stream.res.end(); } catch { /* 已断 */ }
-    }
-    liveStreams.clear();
-    for (const entry of watchers.values()) {
-      entry.disposed = true;
-      try { entry.controller.abort(); } catch { /* 已停 */ }
-      if (entry.timer) clearInterval(entry.timer);
-      if (entry.debounce) clearTimeout(entry.debounce);
-      const closeFn = entry.close;
-      entry.close = null;
-      if (typeof closeFn === 'function') {
-        Promise.resolve().then(() => closeFn()).catch(() => { /* close 失败不影响进程 */ });
-      }
-    }
-    watchers.clear();
-  }
-
-  return { route, dispatch, close, broadcastChange, _internals: { watchers, liveStreams } };
-}
-
-function safeGet(ctx, serviceName) {
-  try {
-    return ctx?.get?.(serviceName);
-  } catch {
-    return undefined;
-  }
-}
-
-function safeLogger(ctx) {
-  try {
-    if (typeof ctx?.logger === 'function') return ctx.logger(name);
-  } catch { /* 用 console */ }
-  return console;
-}
-
-export function apply(ctx) {
-  const log = safeLogger(ctx);
-  let fsService = safeGet(ctx, 'fs');
-  if (!fsService) {
-    try { fsService = ctx.fs; } catch { fsService = undefined; }
-  }
-  if (!fsService) {
-    log.warn?.('%s: ctx.fs unavailable — plugin disabled', name);
-    return;
-  }
-
-  let host;
-  try {
-    host = createHost({
-      fs: fsService,
-      log,
-      rootDir: PLUGIN_ROOT,
-      connectionProvider: () => safeGet(ctx, 'connection'),
-    });
-  } catch (error) {
-    log.warn?.('%s: host init failed: %s', name, String(error?.message ?? error));
-    return;
-  }
-
-  try {
-    if (typeof ctx.effect === 'function') {
-      ctx.effect(() => {
-        const dispose = ctx.webServer.register(host.route);
-        log.info?.('%s: routes mounted on %s', name, ROUTE_PREFIX);
-        return () => {
-          try { if (typeof dispose === 'function') dispose(); } catch { /* 已清理 */ }
-          try { host.close(); } catch { /* 已清理 */ }
-        };
-      }, 'dsh-markdown-typora: routes');
-    } else {
-      ctx.webServer.register(host.route);
-    }
-  } catch (error) {
-    log.warn?.('%s: route registration failed: %s', name, String(error?.message ?? error));
-    try { host.close(); } catch { /* 已清理 */ }
-    return;
-  }
-
-  // markdown 模型工具：Agent 的编辑入口（与编辑面 tab 同一守卫路径）。
-  registerMarkdownTool(ctx, { dispatch: host.dispatch, log });
-}
-
-/**
- * markdown 工具定义（纯数据 + execute，不触达宿主）：便于测试/外部校验 defineTool 形态。
- * DSH 0.2.1 的 defineTool 需要 output.schema + output.render；0.2.0 的旧形态（顶层 render）会抛。
- */
-export function createMarkdownToolDefinition(dispatch) {
-  return {
-    name: 'markdown',
-    description: [
-      '读写 Markdown（及任意文本）文件，与 MarkPilot 编辑面板走同一版本守卫通道。',
-      'read 返回全文与版本；edit 按字面 oldString→newString 原子替换（同 edit 工具语义）。',
-      '冲突纪律：save/edit 报 FS_STALE_VERSION 说明文件在读取后被改过（可能用户正在编辑面板里打字）——',
-      '此时必须重新 read 拿新版本再重试，绝不盲目覆盖；用户编辑永远优先。',
-    ].join(' '),
-    parameters: {
-      action: { type: 'string', required: true, description: 'read = 读文件（text+version）；edit = 字面替换后守卫写回。', enum: ['read', 'edit'] },
-      path: { type: 'string', required: true, description: '文件的绝对路径。' },
-      cwd: { type: 'string', description: '可选：相对路径的解析基准目录。' },
-      oldString: { type: 'string', description: 'action=edit 必填：要替换的原文字面量（须在文件中唯一，除非 replaceAll）。' },
-      newString: { type: 'string', description: 'action=edit 必填：替换后的文字面量。' },
-      replaceAll: { type: 'boolean', description: 'action=edit 可选：替换所有出现（默认 false）。' },
-      baseVersion: { type: 'string', description: '可选：上次 read 拿到的版本；提供后文件已变则拒绝（FS_STALE_VERSION），不盲写。' },
-    },
-    output: {
-      schema: {
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-          ok: { type: 'boolean', required: true },
-          action: { type: 'string', required: true },
-          text: { type: 'string' },
-          version: { type: 'string' },
-          displayPath: { type: 'string' },
-          changed: { type: 'boolean' },
-          error: {
-            type: 'object',
-            additionalProperties: false,
-            properties: {
-              code: { type: 'string', required: true },
-              message: { type: 'string', required: true },
-            },
-          },
-        },
-      },
-      render: (args, value) => {
-        if (value?.ok !== true) {
-          return textBlock(`markdown ${String(args?.action ?? '')} 失败：${value?.error?.code ?? 'error'} — ${value?.error?.message ?? ''}`);
-        }
-        if (value.action === 'read') {
-          const text = String(value.text ?? '');
-          const head = text.length > 8000 ? `${text.slice(0, 8000)}\n…（共 ${text.length} 字符，已截断）` : text;
-          return textBlock(`${value.displayPath ?? ''}（版本 ${String(value.version ?? '').slice(0, 12)}…）:\n${head}`);
-        }
-        return textBlock(`已应用编辑：${value.displayPath ?? ''}${value.changed === false ? '（oldString 与 newString 相同，内容未变）' : ''}，新版本 ${String(value.version ?? '').slice(0, 12)}…`);
-      },
-    },
-    async execute(args) {
-      const action = args?.action === 'edit' ? 'edit' : 'read';
-      try {
-        if (action === 'read') {
-          const result = await dispatch('open', { path: args?.path, cwd: args?.cwd });
-          if (result.ok !== true) return { ok: false, action, error: result.error };
-          return {
-            ok: true,
-            action,
-            text: result.value.text,
-            version: result.value.version,
-            displayPath: result.value.displayPath,
-          };
-        }
-        const result = await dispatch('edit', {
-          path: args?.path,
-          cwd: args?.cwd,
-          oldString: args?.oldString,
-          newString: args?.newString,
-          replaceAll: args?.replaceAll === true,
-          baseVersion: args?.baseVersion,
-        });
-        if (result.ok !== true) return { ok: false, action, error: result.error };
-        return {
-          ok: true,
-          action,
-          version: result.value.version,
-          displayPath: result.value.displayPath,
-          changed: result.value.changed,
-        };
-      } catch (error) {
-        return { ok: false, action, error: { code: errorCode(error), message: String(error?.message ?? error) } };
-      }
-    },
-  };
-}
-
-/**
- * markpilot 模型工具（read/edit）：与编辑面 tab 同一守卫。加载失败只告警，不影响插件其它能力。
- */
-export function registerMarkdownTool(ctx, { dispatch, log } = {}) {
-  const onWarn = (error) => {
-    try { log?.warn?.('dsh-markdown-typora: model tool disabled: %s', String(error?.message ?? error)); } catch { /* 忽略 */ }
-  };
-  try {
-    if (typeof ctx?.inject !== 'function') return;
-    ctx.inject(['tools'], (sctx) => {
-      try {
-        const tools = sctx?.get?.('tools') ?? sctx?.tools;
-        if (!tools || typeof tools.register !== 'function') {
-          onWarn(new Error('Host tools.register is unavailable'));
-          return;
-        }
-        sctx.effect(() => {
-          let stopped = false;
-          let dispose;
-          Promise.resolve()
-            .then(() => import('@deepseek-ai/dsh-tools'))
-            .then((mod) => {
-              if (stopped) return;
-              const defineTool = mod?.defineTool;
-              if (typeof defineTool !== 'function') throw new Error('Host defineTool is unavailable');
-              const tool = defineTool(createMarkdownToolDefinition(dispatch));
-              dispose = tools.register(tool);
-            })
-            .catch((error) => {
-              if (!stopped) onWarn(error);
-            });
-          return () => {
-            stopped = true;
-            try { if (typeof dispose === 'function') dispose(); } catch (error) { onWarn(error); }
-          };
-        }, 'dsh-markdown-typora: markdown tool');
-      } catch (error) {
-        onWarn(error);
-      }
-    });
-  } catch (error) {
-    onWarn(error);
-  }
-}
-
-export default { name, inject, apply };
+// dsh-markdown-typora 宿主半边（DSH 0.2.1 契约版）：
+//   renderer-cm6 静态路由 + 版本守卫编辑面 API（open/save/stat/edit）+ SSE watch + markdown 模型工具。
+//
+// 插件三件套形状（宿主 cordis loader 读的就是这个）：
+//   export const name / export const inject / export function apply(ctx)
+//
+// 架构（见 README.md）：引擎 0 改动，插件只做 DSH 皮/桥/文件 IO。
+//   · 静态资源来自插件根 renderer-cm6/（core-sync 从 EXE 构建产物逐字节同步）；
+//   · 同一文件的写入排队校验 ctx.fs 版本，本地文件使用桌面壳的原子写入与编码处理；
+//   · 每次 save 都要求 baseVersion，版本冲突返回 FS_STALE_VERSION；
+//   · 写成功后向所有 SSE 连接广播 version（客户端按 path 过滤 + 脏缓冲不覆盖）。
+//
+// 保留的既有不变量：
+//   1. 信任栅栏：ctx.connection.requestRejection 可用就以方法形式调用；否则只放行 loopback。
+//   2. body 上限 64MB：含内联图的 Markdown 十几 MB 在真实用户里常见（8MB 曾把 8.13MB 文档拒之门外）。
+//   3. fs.watch 是 async（返回 close 函数）；不支持时降级为 2s 探测。旧实现把它当同步调用 ⇒
+//      unhandled rejection + watcher 泄漏。这里 await 捕获并幂等 close。
+//   4. 每个 async 分支都有 try/catch，错误以 {ok:false,error:{code,message}} 返回，code 原样透传。
+
+import { readFile, stat as fsStat, realpath } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+// 下面三个静态导入**只保留 HMR 依赖边**（host/*.js 变更 ⇒ dsh-hmr 把插件条目一并重启），
+// 实例不直接消费：DSH HMR 的替换计划只驱逐「变更模块 + 其 importer」（planReplacement
+// 只向上闭包，不向下含依赖），协同更新分批到达时 host/ 的 CJS 三件会混代 ——
+// 新 document-store 顶层解构旧 live-documents 的导出 ⇒ “liveCommitDirectory is not a
+// function”（real-manager-enable-r1 实证）。消费实例一律经 loadHostModules() 以
+// 「整组驱逐 + 同代重载」取得：document-store 与 live-documents 永远来自同一代磁盘内容，
+// 不降级、不换目录、共享房间/原子写语义不变。
+import rawDiskStore from '../host/document-store.js';
+import rawLiveStore from '../host/live-documents.js';
+import rawTextCodec from '../host/text-codec.js';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, normalize, sep, extname } from 'node:path';
+
+const requirePlugin = createRequire(import.meta.url);
+const nodeFs = requirePlugin('node:fs');
+const nodeModule = requirePlugin('node:module');
+/** loader 代际（ABI）：图记录若由不带本代「局部 require 所有权」的旧 loader 建立
+ *  （同 digest 的旧 CCB slot 仍在活进程里），一律**不复用**：显式重建一代，
+ *  旧 owner 交由其自己的 close/退休路径排空；重建后的同代码热载才稳定复用。 */
+const HOST_GRAPH_ABI = 2;
+/** 本代 Module → 原始 require（WeakMap：模块可回收，不积累强引用）。 */
+const OWNED_ORIGINALS = new WeakMap();
+/* ── host 运行时图（digest 整组复用/重载；进程级注册表，realpath 归一）────────────
+ * 真实 HMR 实测（real-hmr-worker-count-r2）：每代无条件驱逐 ⇒ 每代一个 file-worker。
+ * 方案（v3，按完整 host 清单而非手维护依赖图）：
+ *   ① digest = host/ 全部源成员（含 native-worker-lease.js、native-worker-path.ps1、
+ *      native/ 子树、package.json）的 rel+字节哈希，目录键走 fs.realpath（junction 拼写归一）；
+ *   ② 相同 digest ⇒ 整组复用（不 require、不碰缓存）——worker、SQLite databases、
+ *      beforeExit 全部延续；未变 native 写逻辑不可能被旧 writer 顶替；
+ *   ③ digest 变 ⇒ 先**预载+验证**新图（拓扑序 require 四入口、导出面形状校验），
+ *      全部成功才原子发布；失败则还原被逐出的缓存键并抛出 —— 旧图不被提前退休、
+ *      不 shutdown、原样可用；缺文件在读清单时即硬错误（无 sentinel、无静默复用）；
+ *   ④ 发布后旧图进 retiredList：其活跃 host 归零时调用**旧代自身**的
+ *      shutdownFileWorker（worker 为该模块实例独占；在途写由其内部 operations 排空），
+ *      然后清空 modules 引用并移除记录 —— exports/连接不再被注册表持有，模块可被
+ *      GC（含其模块级 SQLite databases）；新代冷启不受旧代 closing 影响；
+ *   ⑤ 同代多 host/多 live 窗口共享一张图：单 host.close 只减计数，最后一个才释放。
+ * 不降级、不换目录、共享房间/原子写语义不变。 */
+const HOST_GRAPH_KEY = Symbol.for('dsh-markdown-typora:host-graph');
+const HOST_ENTRY_ORDER = ['text-codec.js', 'safe-file.js', 'live-documents.js', 'document-store.js'];   // 依赖拓扑序
+function hostGraphSlot(hostDir) {
+  const root = (globalThis[HOST_GRAPH_KEY] ??= new Map());
+  let slot = root.get(hostDir);
+  if (!slot) { slot = { current: null, retiredList: [] }; root.set(hostDir, slot); }
+  return slot;
+}
+const HOST_GRAPH_REQUIRED = new Set(['document-store.js', 'live-documents.js', 'text-codec.js', 'safe-file.js',
+  'native-worker-lease.js', 'native-worker-path.ps1', 'native/file-worker.exe', 'native/file-worker.exe.build.json']);
+function readHostGraph(hostDir) {
+  // 真实 sync-host 约定：manifest 在**插件根**（host/ 上一级）的 host.json。
+  // 逐条校验：相对路径、无绝对/..、realpath 后仍在 canonical host 根内（防 symlink 逃逸）、
+  // bytes/sha256 与声明一致；必需成员（4 个 JS + native 脚本/二进制 + build manifest）必须声明。
+  // 任一不满足 ⇒ 硬失败（publish 之前），旧图保活。
+  const manifestPath = join(dirname(hostDir), 'host.json');
+  let manifest;
+  try { manifest = JSON.parse(nodeFs.readFileSync(manifestPath, 'utf8')); }
+  catch (error) { throw Object.assign(new Error('host graph manifest 不可读: ' + manifestPath), { cause: error }); }
+  if (!manifest || !Array.isArray(manifest.files) || manifest.files.length === 0)
+    throw new Error('host graph manifest 形状无效（files 为空）: ' + manifestPath);
+  const seen = new Set();
+  const members = [];
+  for (const entry of manifest.files) {
+    if (!entry || typeof entry.path !== 'string' || !entry.path) throw new Error('host graph manifest 条目无效');
+    const rel = entry.path;
+    if (pathIsAbsoluteShim(rel) || rel.split('/').some((segment) => segment === '..'))
+      throw new Error('host graph manifest 条目必须为 host 内相对路径: ' + rel);
+    if (seen.has(rel)) throw new Error('host graph manifest 重复条目: ' + rel);
+    seen.add(rel);
+    const real = nodeFs.realpathSync(join(hostDir, rel));       // 缺失/坏链 ⇒ throw（硬失败）
+    if (real !== hostDir && !real.startsWith(hostDir + sep))    // canonical 核对：不许 symlink 指到 host 外
+      throw new Error('host graph 成员逃逸 canonical 根: ' + rel + ' → ' + real);
+    const bytes = nodeFs.readFileSync(real);
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    if (bytes.length !== entry.bytes || digest !== entry.sha256)
+      throw new Error(`host graph 成员与 manifest 不匹配: ${rel}（期望 ${entry.bytes}B/${String(entry.sha256).slice(0, 12)}，实际 ${bytes.length}B/${digest.slice(0, 12)}）`);
+    members.push({ rel, real, bytes });
+  }
+  for (const required of HOST_GRAPH_REQUIRED)
+    if (!seen.has(required)) throw new Error('host graph manifest 缺少必需成员: ' + required);
+  members.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+  const graph = createHash('sha256');
+  for (const member of members) {
+    graph.update(member.rel); graph.update('\0');
+    graph.update(createHash('sha256').update(member.bytes).digest());
+  }
+  return { digest: graph.digest('hex'), members };
+}
+function pathIsAbsoluteShim(p) { return p.startsWith('/') || /^[A-Za-z]:/.test(p) || p.startsWith('\\\\'); }
+function evictHostCacheKeys(members) {
+  // 只逐 .js 成员；缓存键 = realpath。还原函数**先清空本次全部成员键**（含装载新产生、
+  // 原先不存在的条目），再放回快照 —— 失败后旧 host 的延迟 require 只见旧实例，不混代。
+  const backup = [];
+  const keys = [];
+  for (const member of members) {
+    if (!member.rel.endsWith('.js')) continue;
+    keys.push(member.real);
+    const existing = requirePlugin.cache[member.real];
+    if (existing !== undefined) backup.push([member.real, existing]);
+    try { delete requirePlugin.cache[member.real]; } catch { /* 原本不在 */ }
+  }
+  return () => {
+    for (const key of keys) { try { delete requirePlugin.cache[key]; } catch { /* 已不在 */ } }
+    for (const [key, mod] of backup) requirePlugin.cache[key] = mod;
+  };
+}
+function finalizeHostRetirement(slot, record) {
+  // 顺序约定（transport）：先旧代 retireLiveStorage()（仍有会话/在途 ⇒ MP_LIVE_ACTIVE，
+  // 此时**不算已清理**——保持 pending，绝不误判 done），再旧代 safeFile.shutdownFileWorker()
+  //（成功后自行移除 beforeExit 监听）。全部完成才清引用、移除记录。
+  if (record.retired === 'done') return;         // 幂等：跨代/跨路径重复触发只收一次
+  const live = record.modules.get('live-documents.js');
+  try {
+    const retired = live?.retireLiveStorage?.();
+    if (retired && retired.ok !== true) return scheduleRetirementRetry(slot, record);
+  } catch (error) {
+    if (error?.code === 'MP_LIVE_ACTIVE') return scheduleRetirementRetry(slot, record);
+    /* 其它错误：存储未收口也要继续收 worker/引用 —— 进程退出兜底仍在 */
+  }
+  const safeFile = record.modules.get('safe-file.js');
+  try { void Promise.resolve(safeFile?.shutdownFileWorker?.()).catch(() => { /* 旧代关停失败不阻塞；退出 hook 兜底 */ }); }
+  catch { /* 旧代关停失败不阻塞 */ }
+  record.retired = 'done';
+  // 解除本代模块的局部 require 所有权：恢复原 mod.require（不碰全局行为），之后其惰性
+  // require 回到普通解析；本代记录随后清引用。
+  unbindOwnedRequires(record);
+  record.modules.clear();                       // 释放引用：旧模块（含模块级 worker/SQLite 状态）可被 GC
+  const at = slot.retiredList.indexOf(record);
+  if (at !== -1) slot.retiredList.splice(at, 1);   // 记录不复留：不持有 exports/连接
+}
+function scheduleRetirementRetry(slot, record) {
+  // MP_LIVE_ACTIVE：仍有在途操作/在场会话 —— 稍后重试一次；仍活跃则留 pending（退出兜底）。
+  if (record.retireRetry) return;
+  record.retireRetry = setTimeout(() => {
+    record.retireRetry = null;
+    if (record.retired === 'pending' && record.hosts.size === 0) finalizeHostRetirement(slot, record);
+  }, 300);
+  record.retireRetry.unref?.();
+}
+function loadHostGraph() {
+  // import.meta.url 可能带 HMR 查询串（?g=…）——取文件本体路径。
+  const here = dirname(fileURLToPath(import.meta.url.split('?')[0]));
+  const hostDir = nodeFs.realpathSync(normalize(join(here, '..', 'host')));   // 缺失 ⇒ 硬错误
+  const slot = hostGraphSlot(hostDir);
+  const graph = readHostGraph(hostDir);           // 任一成员缺/不可读 ⇒ 硬错误（无 sentinel）
+  // 复用条件必须同时满足 digest 与 **loader 代际**：活进程里可能已有同 digest 的旧 CCB slot
+  //（不带本代「局部 require 所有权」）—— 它不能无条件复用，须显式按本代重建一次。
+  if (slot.current && slot.current.digest === graph.digest && slot.current.abi === HOST_GRAPH_ABI) {
+    const current = slot.current;
+    return { live: current.modules.get('live-documents.js'), disk: current.modules.get('document-store.js'),
+      codec: current.modules.get('text-codec.js'), graph: current };
+  }
+  // 预载新图：逐出本图 .js 成员缓存键（含 native-worker-lease 等），拓扑序 require，形状验证。
+  const restore = evictHostCacheKeys(graph.members);
+  const loaded = new Map();
+  const cjsModules = new Map();
+  const cjsByFile = new Map();
+  try {
+    for (const name of HOST_ENTRY_ORDER) {
+      loaded.set(name, requirePlugin('../host/' + name));
+      // 捕获本代模块的 CJS Module 对象（供局部 resolver 用；**不写全局 require.cache**）。
+      try {
+        const resolved = requirePlugin.resolve('../host/' + name);
+        const real = nodeFs.realpathSync(resolved);
+        const mod = requirePlugin.cache[real] || requirePlugin.cache[resolved] || null;
+        cjsModules.set(name, mod);
+        if (mod) {
+          cjsByFile.set(mod.filename, mod);
+          if (real !== mod.filename) cjsByFile.set(real, mod);
+        }
+      } catch { cjsModules.set(name, null); }
+    }
+    const live = loaded.get('live-documents.js'), disk = loaded.get('document-store.js');
+    if (typeof live?.LiveDocuments !== 'function' || typeof live?.withFileCommit !== 'function'
+      || typeof disk?.DocumentStore !== 'function' || typeof disk?.createSession !== 'function'
+      || typeof loaded.get('text-codec.js')?.decodeDocument !== 'function'
+      || typeof loaded.get('safe-file.js')?.prepareFile !== 'function')
+      throw new Error('host graph 新代导出面不完整（digest=' + graph.digest.slice(0, 12) + '）');
+  } catch (error) {
+    restore();                                    // 回滚缓存：旧图成员（含懒 require 路径）原位、不被破坏
+    throw error;
+  }
+  // ① 发布前校验（绑定/导出一致性）——失败 ⇒ 回滚并抛出；**旧图不退休、不 shutdown**。
+  try {
+    validateOwnedGraph(loaded, cjsModules);
+  } catch (error) {
+    restore();
+    throw error;
+  }
+  // ② 在图记录建立后、对外发布前完成逐 Module 实例的 require 绑定；绑定失败同样回滚。
+  const nextGraph = { dir: hostDir, abi: HOST_GRAPH_ABI, digest: graph.digest, modules: loaded, cjs: cjsModules, cjsByFile, hosts: new Set(), retired: 'active', generation: (slot.current?.generation ?? 0) + 1 };
+  try {
+    bindOwnedRequires(nextGraph);
+  } catch (error) {
+    unbindOwnedRequires(nextGraph);
+    restore();
+    throw error;
+  }
+  // ③ 原子发布：旧图记账退休（host 归零才真正释放），新图上桌。
+  const previous = slot.current;
+  if (previous) {
+    previous.retired = previous.hosts.size === 0 ? 'done' : 'pending';
+    slot.retiredList.push(previous);
+    if (previous.retired === 'done') finalizeHostRetirement(slot, previous);
+  }
+  slot.current = nextGraph;
+  return { live: loaded.get('live-documents.js'), disk: loaded.get('document-store.js'),
+    codec: loaded.get('text-codec.js'), graph: slot.current };
+}
+/** 发布前绑定/导出一致性校验：真实 Module 对象缺失或 exports 形状不符 ⇒ 直接失败（不静默放过）。 */
+function validateOwnedGraph(loaded, cjsModules) {
+  for (const name of HOST_ENTRY_ORDER) {
+    const mod = cjsModules.get(name);
+    if (!mod || !mod.exports || mod.exports !== loaded.get(name))
+      throw new Error('host graph 校验失败：成员 Module 缺失或 exports 不匹配（' + name + '）');
+  }
+  const live = loaded.get('live-documents.js'), disk = loaded.get('document-store.js');
+  if (typeof live?.defaultDirectory !== 'function')
+    throw new Error('host graph 校验失败：live-documents.defaultDirectory 非函数（混代绑定）');
+  if (typeof live?.LiveDocuments !== 'function' || typeof live?.withFileCommit !== 'function')
+    throw new Error('host graph 校验失败：live-documents 导出面不完整');
+  if (typeof disk?.DocumentStore !== 'function' || typeof disk?.createSession !== 'function')
+    throw new Error('host graph 校验失败：document-store 导出面不完整');
+  // 只读构造探针：document-store 构造函数仅赋值（无 IO），defaultDirectory 混代时必抛
+  // liveCommitDirectory is not a function —— 这正是发布前要拦下的形态。
+  const probe = new disk.DocumentStore();
+  if (!probe || typeof probe.snapshot !== 'function' || typeof probe.commitDirectory !== 'string' || !probe.commitDirectory)
+    throw new Error('host graph 校验失败：DocumentStore 构造绑定异常');
+  probe.jobs?.clear?.();
+}
+/** 逐 Module 实例安装本代 require（WeakMap 保存原 require；非 prototype、非 _load）。 */
+function bindOwnedRequires(graph) {
+  for (const [name, mod] of graph.cjs) {
+    if (!mod || typeof mod.require !== 'function' || !mod.exports)
+      throw new Error('host graph 绑定失败：成员 Module 不可用（' + name + '）');
+    if (OWNED_ORIGINALS.has(mod)) continue;                     // 已绑定（同代重复发布不应发生）
+    const original = mod.require;
+    const owned = graph.cjsByFile;
+    const wrapped = function ownedRequire(request) {
+      if (typeof request === 'string' && request[0] === '.' && owned) {
+        let filename = null;
+        try { filename = nodeModule._resolveFilename(request, mod, false); } catch { /* 交给原 require 报错 */ }
+        if (filename) {
+          const hit = owned.get(filename);
+          if (hit) return hit.exports;
+        }
+      }
+      return original.call(mod, request);
+    };
+    OWNED_ORIGINALS.set(mod, original);
+    mod.require = wrapped;
+  }
+}
+/** 恢复本代模块的原 require（退役路径）；重复调用安全。 */
+function unbindOwnedRequires(record) {
+  if (!record || !record.cjs) return;
+  for (const [, mod] of record.cjs) {
+    const original = OWNED_ORIGINALS.get(mod);
+    if (original) { try { mod.require = original; } catch { /* 已冻结则忽略 */ } OWNED_ORIGINALS.delete(mod); }
+  }
+}
+// 无兜底：装载失败就让它失败（绝不回落到可能混代的 raw* 实例掩盖问题）。
+const hostModules = loadHostGraph();
+const diskStore = hostModules.disk;
+const liveStore = hostModules.live;
+const textCodec = hostModules.codec;
+const activeHostGraph = hostModules.graph;
+function registerHost(token) { activeHostGraph.hosts.add(token); }
+function scheduleHostRetirement(ownerGraph) {
+  // 已接纳的异步 save 排空后才允许关闭旧代资源（worker/连接）；期间另一 active host
+  // 不受任何影响（owners 已归零才会走到这里，且只作用于被顶代的图）。
+  const here = dirname(fileURLToPath(import.meta.url.split('?')[0]));
+  const hostDir = nodeFs.realpathSync(normalize(join(here, '..', 'host')));
+  void Promise.allSettled([...saveJobs.values()]).then(() => {
+    if (ownerGraph.hosts.size === 0 && ownerGraph.retired === 'pending') finalizeHostRetirement(hostGraphSlot(hostDir), ownerGraph);
+  }).catch(() => { /* 排空失败不阻塞 */ });
+}
+function unregisterHost(token) {
+  const ownerGraph = activeHostGraph;
+  if (ownerGraph.hosts.delete(token) && ownerGraph.hosts.size === 0 && ownerGraph.retired === 'pending') scheduleHostRetirement(ownerGraph);
+}
+void rawDiskStore; void rawLiveStore; void rawTextCodec;
+
+export const name = 'dsh-markdown-typora';
+
+/** 必需服务：webServer（路由挂载点）+ fs（版本守卫读写）。 */
+export const inject = ['webServer', 'fs'];
+
+const ROUTE_PREFIX = '/dsh-markdown-typora';
+const STATIC_PREFIX = ROUTE_PREFIX + '/renderer-cm6/';
+const API_PREFIX = ROUTE_PREFIX + '/api/';
+// Only the editor's explicit local-file actions use its native file capability.
+// The model tool must use the host filesystem's read projection and write policy.
+const MODEL_TOOL = Symbol('markdown model tool');
+const IMG_PREFIX = ROUTE_PREFIX + '/img/';
+const CORE_JSON_PATH = ROUTE_PREFIX + '/core.json';
+const KNOWN_ENDPOINTS = new Set(['open', 'save', 'stat', 'edit', 'live']);
+const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', 'localhost', '::1']);
+
+/** 请求体上限：64MB。含内联图文档常见 10MB+；上限之外明确 413，不静默截断。 */
+export const BODY_MAX_BYTES = 64 * 1024 * 1024;
+/** 本地图片响应上限：与请求体同口径。超过只给 413，不把整块内容读进内存。 */
+export const IMAGE_MAX_BYTES = 64 * 1024 * 1024;
+const WATCH_DEBOUNCE_MS = 120;
+const WATCH_PROBE_MS = 2000;
+const SSE_HEARTBEAT_MS = 15000;
+
+const HERE = dirname(fileURLToPath(import.meta.url.split('?')[0]));
+export const PLUGIN_ROOT = normalize(join(HERE, '..'));
+const localDocuments = new diskStore.DocumentStore();
+// Shared by all createHost instances in this process. Failures do not poison
+// subsequent saves; a queued request must validate its version on admission.
+const saveJobs = new Map();
+const pathKey = p => process.platform === 'win32' ? normalize(p).toLowerCase() : normalize(p);
+async function canonicalTarget(target) {
+  const p=nativeTargetPath(target);
+  try {return await realpath(p);} catch(error) {if(error.code!=='ENOENT')throw error;return p;}
+}
+function queueSave(key, action) {
+  const job=(saveJobs.get(key)||Promise.resolve()).catch(()=>{}).then(action);
+  saveJobs.set(key,job);
+  const done=()=>{if(saveJobs.get(key)===job)saveJobs.delete(key);};job.then(done,done);
+  return job;
+}
+
+/** 静态资源 MIME 表（含 CM6 引擎实际用到的 woff/woff2/ttf/wasm/map，以及 mermaid 的 svg/png）。 */
+export const MIME_BY_EXT = {
+  '.html': 'text/html; charset=utf-8',
+  '.htm': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.cjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.wasm': 'application/wasm',
+  '.txt': 'text/plain; charset=utf-8',
+};
+
+export function mimeFor(filePath) {
+  return MIME_BY_EXT[extname(String(filePath)).toLowerCase()] ?? 'application/octet-stream';
+}
+
+/** ETag 由 size-mtime 组成（要求口径）；mtime 取整毫秒，避免频繁重建时抖动。 */
+export function makeEtag(size, mtimeMs) {
+  const s = Number.isFinite(Number(size)) ? Math.trunc(Number(size)) : 0;
+  const m = Number.isFinite(Number(mtimeMs)) ? Math.trunc(Number(mtimeMs)) : 0;
+  return `"${s}-${m}"`;
+}
+
+/** If-None-Match 匹配（支持 *、逗号列表、弱前缀 W/）。命中返回 304。 */
+export function isNotModified(ifNoneMatch, etag) {
+  if (typeof ifNoneMatch !== 'string' || ifNoneMatch.length === 0) return false;
+  if (ifNoneMatch.trim() === '*') return true;
+  return ifNoneMatch
+    .split(',')
+    .map((part) => part.trim().replace(/^W\//, ''))
+    .some((candidate) => candidate === etag);
+}
+
+/**
+ * 缓存策略：
+ *   · 入口 HTML、app.js/app.css、dsh-*.js：no-cache（每次带 ETag 校验，拿 304）；
+ *   · 字体（woff/woff2/ttf/otf/eot）：public, max-age=604800 —— 内容哈希文件名，长缓存安全；
+ *   · 其余（worker/mermaid/图标）：no-cache + ETag。
+ */
+export function cacheControlFor(filePath) {
+  const base = String(filePath).split(/[\\/]/).pop() ?? '';
+  const ext = extname(base).toLowerCase();
+  if (ext === '.woff' || ext === '.woff2' || ext === '.ttf' || ext === '.otf' || ext === '.eot') {
+    return 'public, max-age=604800';
+  }
+  if (base === 'index.html' || base === 'app.js' || base === 'app.css' || /^dsh-[^/]*\.js$/i.test(base)) {
+    return 'no-cache';
+  }
+  return 'no-cache';
+}
+
+/**
+ * 把一个 URL 相对路径解析成 renderer-cm6 根内的绝对路径；越界/编码异常/盘符/空字节一律 null。
+ * 这是路径穿越防护的唯一入口（纯函数，可被测试直接覆盖）。
+ */
+export function resolveStaticTarget(rootDir, rawRelative) {
+  if (typeof rawRelative !== 'string') return null;
+  let decoded;
+  try {
+    decoded = decodeURIComponent(rawRelative);
+  } catch {
+    return null;
+  }
+  if (decoded.length === 0) decoded = 'index.html';
+  if (decoded.includes('\0')) return null;
+  const slashed = decoded.replace(/\\/g, '/');
+  if (slashed.startsWith('/')) return null;
+  if (/^[A-Za-z]:/.test(slashed)) return null;
+  const segments = slashed.split('/');
+  if (segments.some((segment) => segment === '..')) return null;
+  const root = normalize(rootDir);
+  const target = normalize(join(root, slashed));
+  if (target !== root && !target.startsWith(root + sep)) return null;
+  return target;
+}
+
+/* ══ 本地图片路由（文档相对路径图的取字节通道）══════════════════════════════════════
+ * 为什么需要：CM6 引擎按"当前文档所在目录"解析相对图片路径（`image-path.js` 的
+ * resolveImageSource）；桌面壳把它拼成 file:// 并靠 file 页面读盘。DSH 的编辑面是
+ * **http 源**：CSP 的 img-src 不含 file:，Chromium 也禁止 http 页面加载 file:// 子资源
+ * ⇒ 相对路径图必然"图片加载失败"。所以由插件提供唯一合法的本地图片通道：
+ *   GET /dsh-markdown-typora/img/<绝对本地路径（逐段百分号编码，保留 /）>
+ * 桥（renderer-cm6/dsh-bridge.js）在 open 时把 <base href> 指到
+ *   /dsh-markdown-typora/img/<文档目录>/
+ * ⇒ 引擎发出的相对 URL 原样落到本路由。浏览器按 RFC 3986 自己归一化 `../`，
+ * 因此这里拿到的永远是规整的绝对路径。
+ *
+ * 安全边界（三条都必须成立，缺一即拒）：
+ *   ① 形态：只接受盘符绝对路径（D:/x/y.png）或 UNC（//server/share/y.png），
+ *      拒空段 / 单点 / 双点 / NUL / 坏编码 —— 归一化不靠浏览器，自己逐段验；
+ *   ② 扩展名：图片白名单之外一律不服务（本路由不是通用文件服务）；
+ *   ③ 只在既有信任栅栏之后（loopback + 宿主鉴权），且只读、只 GET/HEAD。
+ * 说明：该读面不强于既有 /api/open（它本来就能读任意路径文本）。 */
+
+/** 图片 MIME（本路由专用；比静态表窄，且不接受 fonts/wasm 之类）。 */
+export const IMAGE_MIME_BY_EXT = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.jfif': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.avif': 'image/avif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+};
+
+export function imageMimeFor(filePath) {
+  return IMAGE_MIME_BY_EXT[extname(String(filePath)).toLowerCase()] ?? null;
+}
+
+/**
+ * 把 URL 里 `/img/` 之后的剩余路径还原成**绝对本地路径**；不合规一律 null（纯函数）。
+ * 规则见本节注释①。解码逐段进行：`%2e%2e` 解出来是 `..`，同样被拒。
+ */
+export function decodeImageRequestPath(rawPath) {
+  if (typeof rawPath !== 'string' || rawPath.length === 0) return null;
+  const slashed = rawPath.replace(/\\/g, '/');
+  let unc = false;
+  let rest = slashed;
+  if (rest.startsWith('//')) { unc = true; rest = rest.slice(2); }
+  else if (rest.startsWith('/')) rest = rest.slice(1);
+  if (rest.length === 0) return null;
+  const segments = rest.split('/');
+  const decoded = [];
+  // Windows 设备名段（CON/NUL/COM1…）会被当成设备打开：读 CON 可能把请求挂住，
+  // 所以连"图片扩展名"都不看，段一级直接拒。
+  const DEVICE_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+  for (const segment of segments) {
+    let value;
+    try {
+      value = decodeURIComponent(segment);
+    } catch {
+      return null;
+    }
+    if (value.length === 0) return null;
+    if (value === '.' || value === '..') return null;
+    if (value.includes('\0')) return null;
+    if (/[\\/]/.test(value)) return null;   // %2f/%5c 解出来的分隔符不许再切一层
+    if (DEVICE_NAME.test(value)) return null;
+    if (decoded.length > 0 && value.includes(':')) return null;   // 备用数据流（a.png:b）不收
+    decoded.push(value);
+  }
+  if (decoded.length < 1) return null;
+  let localPath;
+  if (unc) {
+    if (decoded.length < 2) return null;    // //server 后面至少还要有共享名
+    localPath = '//' + decoded.join('/');
+  } else {
+    if (!/^[A-Za-z]:$/.test(decoded[0])) return null;   // 必须是盘符绝对路径
+    if (decoded.length < 2) return null;
+    localPath = decoded[0].toUpperCase() + '/' + decoded.slice(1).join('/');
+  }
+  if (!imageMimeFor(localPath)) return null;
+  return normalize(localPath);
+}
+
+/** 服务一次本地图片请求：ETag/304、HEAD、大小上限、流式输出。返回是否已响应。 */
+export async function serveImageFile(req, res, rawPath) {
+  const method = req?.method === 'HEAD' ? 'HEAD' : 'GET';
+  const target = decodeImageRequestPath(rawPath);
+  if (!target) {
+    sendText(res, 400, 'bad image path');
+    return false;
+  }
+  let info;
+  try {
+    info = await fsStat(target);
+  } catch (error) {
+    sendText(res, error?.code === 'ENOENT' ? 404 : 500, error?.code === 'ENOENT' ? 'not found' : 'stat error');
+    return false;
+  }
+  if (!info.isFile()) {
+    sendText(res, 404, 'not found');
+    return false;
+  }
+  if (info.size > IMAGE_MAX_BYTES) {
+    sendText(res, 413, 'image too large');
+    return false;
+  }
+  const etag = makeEtag(info.size, info.mtimeMs);
+  const headers = {
+    'content-type': imageMimeFor(target),
+    'cache-control': 'no-cache',
+    etag,
+    'x-content-type-options': 'nosniff',
+    // SVG 在 <img> 里不执行脚本，但**直接导航**（地址栏/window.open）时就是同源文档、脚本可跑。
+    // 这条 CSP 对 <img> 渲染零影响，对文档导航把脚本/表单/子资源全部中和。
+    'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; img-src data:; sandbox",
+  };
+  if (isNotModified(req.headers['if-none-match'], etag)) {
+    res.writeHead(304, headers);
+    res.end();
+    return true;
+  }
+  // 不写 content-length：stat 与流之间有 TOCTOU（文件被改写会截断/挂住）。
+  // 交给 chunked 传输，浏览器按流读完即可。
+  res.writeHead(200, headers);
+  if (method === 'HEAD') {
+    res.end();
+    return true;
+  }
+  await new Promise((resolve) => {
+    let settled = false;
+    const done = () => { if (settled) return; settled = true; resolve(); };
+    const stream = createReadStream(target);
+    stream.on('error', () => { try { res.destroy(); } catch { /* 已断 */ } done(); });
+    stream.on('end', done);
+    res.on('close', () => { try { stream.destroy(); } catch { /* 已断 */ } done(); });
+    stream.pipe(res);
+  });
+  return true;
+}
+
+/** FsError 等错误的稳定码（分支认码不认文案；不许把 code 吞成 message）。 */
+export function errorCode(error) {
+  const code = error?.code ?? error?.cause?.code;
+  if (typeof code === 'string' && code.length > 0) return code;
+  if (error?.name === 'AbortError') return 'FS_ABORTED';
+  return 'fs-error';
+}
+
+/**
+ * DSH 文件策略拒绝这次写入（workspace-write 只允许会话工作区内的路径）。
+ * 只在这个明确码/文案上走原生 fs 回退；OS 的 EACCES/EPERM 仍然照常失败。
+ */
+export function isSandboxWriteDenied(error) {
+  if (errorCode(error) === 'FS_SANDBOX_DENIED') return true;
+  const message = String(error?.message ?? error ?? '');
+  return /file access denied under (workspace-write|read-only) mode/i.test(message);
+}
+
+function codedError(code, message) {
+  const error = new Error(String(message));
+  error.code = code;
+  return error;
+}
+
+/** ctx.fs 的 target 同时带 displayPath 和 realpath targetKey；原生写用后者。 */
+function nativeTargetPath(target) {
+  const key = target?.targetKey;
+  if (typeof key === 'string' && key.length > 0) return key;
+  const displayPath = target?.displayPath;
+  return typeof displayPath === 'string' ? displayPath : '';
+}
+
+/** 与 dsh-fs-local 的 versionOf 同形：dev:ino:size:mtimeNs:ctimeNs（bigint）。 */
+function versionOfBigInt(info) {
+  return `${info.dev}:${info.ino}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`;
+}
+
+/**
+ * Local Markdown saves share the desktop's stable snapshot, encoding and
+ * staged native replacement. Never truncate the destination before commit.
+ * The UI's existing explicit local-file write capability remains scoped here.
+ */
+async function directWriteText(fs, target, text, baseVersion, diskHash) {
+  const file=nativeTargetPath(target),session=diskStore.createSession();
+  if(!file)throw codedError('FS_IO_ERROR','direct write: target has no native path');
+  const version=async()=>{const info=await fs.stat(target);if(!info)throw codedError('FS_NOT_FOUND','file no longer exists');return String(info.version);};
+  try {
+    if(await version()!==baseVersion)throw codedError('FS_STALE_VERSION','file changed since read');
+    await localDocuments.load(session,file);
+    if(diskHash && session.baseline.sha256!==diskHash)throw codedError('FS_STALE_VERSION','file changed since the synchronized revision');
+    if(await version()!==baseVersion)throw codedError('FS_STALE_VERSION','file changed while preparing save');
+    const expected=textCodec.encodeDocument(text,session),expectedHash=createHash('sha256').update(expected).digest('hex');
+    localDocuments.markDirty(session,{documentId:session.documentId,revision:1,dirty:true});
+    await localDocuments.save(session,{filePath:session.filePath,text,documentId:session.documentId,revision:1});
+    const before=await version(),saved=await localDocuments.snapshot(session.filePath),after=await version();
+    if(before!==after||saved.baseline.sha256!==expectedHash)throw codedError('FS_STALE_VERSION','file changed after save; draft retained');
+    return {version:after,displayPath:target.displayPath,size:saved.bytes.length};
+  } catch(error) {
+    if(['MP_FILE_CONFLICT','MP_FILE_MISSING'].includes(error.code))error.code='FS_STALE_VERSION';
+    throw error;
+  }
+}
+
+
+function textBlock(text) {
+  return [{ type: 'text', text: String(text ?? '') }];
+}
+
+function badRequest(message) {
+  return { ok: false, error: { code: 'bad-request', message } };
+}
+
+function hostnameOf(hostHeader) {
+  if (typeof hostHeader !== 'string' || hostHeader.length === 0) return '';
+  if (hostHeader.startsWith('[')) {
+    const end = hostHeader.indexOf(']');
+    return end > 0 ? hostHeader.slice(1, end).toLowerCase() : '';
+  }
+  return hostHeader.split(':')[0].toLowerCase();
+}
+
+/** loopback 兜底栅栏：Host 必须本机；跨站请求拒绝；有 Origin 时必须与 Host 同源。 */
+export function isTrustedLoopbackRequest(req) {
+  const host = req?.headers?.host;
+  if (!host) return false;
+  const hostname = hostnameOf(host);
+  if (!LOOPBACK_HOSTNAMES.has(hostname)) return false;
+  if (req.headers['sec-fetch-site'] === 'cross-site') return false;
+  const origin = req.headers.origin;
+  if (origin === undefined) return true;
+  try {
+    return new URL(origin).host.toLowerCase() === String(host).toLowerCase();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 读请求体，超限返回 {ok:false,code:'too-large'}；网络错误返回 {ok:false,code:'request-error'}。
+ * 超限后暂停消费剩余数据（不把 64MB 之外的攻击流量继续读进内存）。
+ */
+export function readBody(req, limit = BODY_MAX_BYTES) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let total = 0;
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    req.on('data', (chunk) => {
+      if (settled) return;
+      total += chunk.length;
+      if (total > limit) {
+        chunks.length = 0;
+        req.pause();
+        finish({ ok: false, code: 'too-large' });
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => finish({ ok: true, buffer: Buffer.concat(chunks) }));
+    req.on('error', () => finish({ ok: false, code: 'request-error' }));
+    req.on('aborted', () => finish({ ok: false, code: 'request-error' }));
+  });
+}
+
+function sendJson(res, status, value, extraHeaders) {
+  const body = Buffer.from(JSON.stringify(value), 'utf8');
+  if (res.headersSent) {
+    try { res.end(); } catch { /* 已断 */ }
+    return;
+  }
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': body.length,
+    ...extraHeaders,
+  });
+  res.end(body);
+}
+
+function sendText(res, status, text, extraHeaders) {
+  if (res.headersSent) {
+    try { res.end(); } catch { /* 已断 */ }
+    return;
+  }
+  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8', ...extraHeaders });
+  res.end(text);
+}
+
+/**
+ * 宿主核心：把 ctx 依赖收成一个可独立测试的对象。
+ * @param {{fs:object, log?:object, rootDir?:string, bodyLimit?:number, watchDebounceMs?:number,
+ *          watchProbeMs?:number, heartbeatMs?:number, connectionProvider?:() => any}} [options]
+ */
+export function createHost(options = {}) {
+  const fs = options.fs;
+  if (!fs || typeof fs.resolve !== 'function' || typeof fs.writeText !== 'function') {
+    throw new Error('dsh-markdown-typora: a filesystem service (ctx.fs) is required');
+  }
+  const log = options.log ?? console;
+  const rootDir = normalize(options.rootDir ?? PLUGIN_ROOT);
+  const staticRoot = normalize(join(rootDir, 'renderer-cm6'));
+  const coreJsonFile = normalize(join(rootDir, 'core.json'));
+  const bodyLimit = options.bodyLimit ?? BODY_MAX_BYTES;
+  const watchDebounceMs = options.watchDebounceMs ?? WATCH_DEBOUNCE_MS;
+  const watchProbeMs = options.watchProbeMs ?? WATCH_PROBE_MS;
+  const heartbeatMs = options.heartbeatMs ?? SSE_HEARTBEAT_MS;
+  const connectionProvider = typeof options.connectionProvider === 'function'
+    ? options.connectionProvider
+    : () => undefined;
+
+  /** 每个被观察文件一条 entry；refs 计数到 0 才释放（SSE 多 tab 共享）。 */
+  const watchers = new Map();
+  const live = options.liveDocuments ?? new liveStore.LiveDocuments();
+  const leases = new Map();
+  let closed = false;
+
+  function leaseOf(client) {
+    const lease = typeof client === 'string' && leases.get(client);
+    if (!lease) throw codedError('MP_LIVE_LEASE', '编辑同步会话已过期，当前草稿已保留');
+    return lease;
+  }
+  function releaseLive(client) {
+    if (!leases.delete(client)) return;
+    live.leave(client);
+  }
+  function liveEndpoint(payload) {
+    leaseOf(payload.client);
+    if (payload.action === 'leave') {
+      releaseLive(payload.client);
+      return {ok:true,value:null};
+    }
+    if (payload.action !== 'exchange') return badRequest('unknown live action');
+    return Promise.resolve(live.exchange(payload.client,payload.request)).then(value=>({ok:true,value}));
+  }
+  /** Persisted-file notifications are scoped to the watched target. Unsaved edits use independent document leases. */
+  const liveStreams = new Set();
+
+  function watchKeyOf(target) {
+    return String(target?.targetKey ?? target?.displayPath ?? '');
+  }
+
+  function broadcastChange(target, version, delta) {
+    const data = {
+      path: target?.displayPath,
+      targetKey: target?.targetKey,
+      version: String(version ?? ''),
+      ...(delta ? { delta: { oldString: String(delta.oldString ?? '').slice(0, 400), newString: String(delta.newString ?? '').slice(0, 400) } } : {}),
+    };
+    const frame = `event: change\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const stream of liveStreams) {
+      if(stream.targetKey !== watchKeyOf(target))continue;
+      try {
+        stream.res.write(frame);
+      } catch { /* 连接已断，close 事件会清理 */ }
+    }
+  }
+
+  async function tickWatch(entry, baseline = false) {
+    if (entry.disposed) return;
+    let version = '';
+    let missing = false;
+    try {
+      const info = await fs.stat(entry.target);
+      if (info === undefined) missing = true;
+      else version = String(info.version ?? '');
+    } catch {
+      return;
+    }
+    if (entry.disposed) return;
+    const changed = entry.lastVersion !== undefined && (missing || version !== entry.lastVersion);
+    if (changed && !baseline) {
+      if (entry.debounce) clearTimeout(entry.debounce);
+      entry.debounce = setTimeout(() => {
+        entry.debounce = null;
+        if (!entry.disposed) broadcastChange(entry.target, version);
+      }, watchDebounceMs);
+      entry.debounce.unref?.();
+    }
+    if (!missing) entry.lastVersion = version;
+  }
+
+  async function startWatch(entry) {
+    if (entry.started) return;
+    entry.started = true;
+    // FS.watch 是 async：resolve 为 close 函数；不支持时 reject（FS_IO_ERROR）。旧实现把它当
+    // 同步调用且不 catch —— 这里必须 await 并保留 close，否则 watcher 泄漏 / unhandled rejection。
+    try {
+      const close = await fs.watch(entry.target, () => { void tickWatch(entry); }, entry.controller.signal);
+      if (entry.disposed) {
+        try { if (typeof close === 'function') await close(); } catch { /* 已停 */ }
+        return;
+      }
+      entry.close = typeof close === 'function' ? close : null;
+    } catch (error) {
+      if (entry.disposed) return;
+      log.warn?.('%s: fs.watch unavailable (%s) — SSE 退化为 %dms 探测', name, String(error?.message ?? error), watchProbeMs);
+      entry.timer = setInterval(() => { void tickWatch(entry); }, watchProbeMs);
+      entry.timer.unref?.();
+    }
+    await tickWatch(entry, true);
+  }
+
+  function ensureWatch(target) {
+    const key = watchKeyOf(target);
+    let entry = watchers.get(key);
+    if (entry) {
+      entry.refs += 1;
+      return entry;
+    }
+    entry = {
+      refs: 1,
+      target,
+      lastVersion: undefined,
+      controller: new AbortController(),
+      close: null,
+      timer: null,
+      debounce: null,
+      disposed: false,
+      started: false,
+    };
+    watchers.set(key, entry);
+    void startWatch(entry);
+    return entry;
+  }
+
+  function releaseWatch(target) {
+    const key = watchKeyOf(target);
+    const entry = watchers.get(key);
+    if (!entry) return;
+    entry.refs -= 1;
+    if (entry.refs > 0) return;
+    watchers.delete(key);
+    entry.disposed = true;
+    try { entry.controller.abort(); } catch { /* 已停 */ }
+    if (entry.timer) clearInterval(entry.timer);
+    if (entry.debounce) clearTimeout(entry.debounce);
+    const close = entry.close;
+    entry.close = null;
+    if (typeof close === 'function') {
+      Promise.resolve().then(() => close()).catch(() => { /* close 失败不影响进程 */ });
+    }
+  }
+
+  async function serveStatic(req, res, rawRelative) {
+    const target = resolveStaticTarget(staticRoot, rawRelative);
+    if (!target) {
+      sendText(res, 403, 'forbidden');
+      return;
+    }
+    let info;
+    try {
+      info = await fsStat(target);
+    } catch (error) {
+      sendText(res, error?.code === 'ENOENT' ? 404 : 500, error?.code === 'ENOENT' ? 'not found' : 'stat error');
+      return;
+    }
+    let filePath = target;
+    if (info.isDirectory()) {
+      filePath = join(target, 'index.html');
+      try {
+        info = await fsStat(filePath);
+      } catch {
+        sendText(res, 404, 'not found');
+        return;
+      }
+    }
+    if (!info.isFile()) {
+      sendText(res, 404, 'not found');
+      return;
+    }
+    const etag = makeEtag(info.size, info.mtimeMs);
+    const headers = {
+      'content-type': mimeFor(filePath),
+      'cache-control': cacheControlFor(filePath),
+      etag,
+      'x-content-type-options': 'nosniff',
+    };
+    if (isNotModified(req.headers['if-none-match'], etag)) {
+      res.writeHead(304, headers);
+      res.end();
+      return;
+    }
+    let data;
+    try {
+      data = await readFile(filePath);
+    } catch {
+      sendText(res, 500, 'read error');
+      return;
+    }
+    res.writeHead(200, { ...headers, 'content-length': data.length });
+    res.end(req.method === 'HEAD' ? undefined : data);
+  }
+
+  async function serveCoreJson(req, res) {
+    let data;
+    try {
+      data = await readFile(coreJsonFile);
+    } catch (error) {
+      // 不生成 core.json 的旧包也不能让客户端崩：明确 404 + 可诊断文案。
+      sendJson(res, error?.code === 'ENOENT' ? 404 : 500, {
+        ok: false,
+        error: {
+          code: error?.code === 'ENOENT' ? 'not-found' : 'fs-error',
+          message: error?.code === 'ENOENT'
+            ? 'core.json has not been generated yet (run scripts/sync-core.mjs)'
+            : String(error?.message ?? error),
+        },
+      });
+      return;
+    }
+    const headers = { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' };
+    try {
+      const info = await fsStat(coreJsonFile);
+      const etag = makeEtag(info.size, info.mtimeMs);
+      headers.etag = etag;
+      if (isNotModified(req.headers['if-none-match'], etag)) {
+        res.writeHead(304, headers);
+        res.end();
+        return;
+      }
+    } catch { /* 无 stat 也要能返回内容 */ }
+    res.writeHead(200, { ...headers, 'content-length': data.length });
+    res.end(req.method === 'HEAD' ? undefined : data);
+  }
+
+  /** GET /dsh-markdown-typora/api/watch?path=…：SSE 外部变更流；心跳 15s；close 幂等清理。 */
+  async function handleWatch(req, res, url) {
+    const path = url.searchParams.get('path') ?? '';
+    if (!path) {
+      sendJson(res, 400, badRequest('path is required'));
+      return;
+    }
+    let target;
+    try {
+      target = await fs.resolve(path);
+    } catch (error) {
+      sendJson(res, 200, { ok: false, error: { code: errorCode(error), message: String(error?.message ?? error) } });
+      return;
+    }
+    if (res.headersSent) return;
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-store',
+      connection: 'keep-alive',
+      'x-content-type-options': 'nosniff',
+    });
+    res.write('retry: 2000\n\n');
+    const stream = { res, targetKey: watchKeyOf(target) };
+    liveStreams.add(stream);
+    const heartbeat = setInterval(() => {
+      try { res.write(': ping\n\n'); } catch { /* close 清理 */ }
+    }, heartbeatMs);
+    heartbeat.unref?.();
+    const entry = ensureWatch(target);
+    let closed = false;
+    const cleanup = () => {
+      if (closed) return;
+      closed = true;
+      clearInterval(heartbeat);
+      liveStreams.delete(stream);
+      releaseWatch(target);
+    };
+    req.on('close', cleanup);
+    req.on('aborted', cleanup);
+    res.on('close', cleanup);
+    res.on('error', cleanup);
+    try {
+      res.write(`event: ready\ndata: ${JSON.stringify({ path: target.displayPath, version: String(entry.lastVersion ?? '') })}\n\n`);
+    } catch { /* 已断 */ }
+  }
+
+  function resolveOptions(payload, invocation) {
+    const cwd = invocation?.cwd ?? payload?.cwd;
+    return { ...(typeof cwd === 'string' && cwd ? {cwd} : {}), ...(invocation?.signal ? {signal:invocation.signal} : {}) };
+  }
+
+  async function apiOpen(payload, authority, resolvedTarget, invocation) {
+    const path = typeof payload?.path === 'string' ? payload.path : '';
+    if (!path) return badRequest('path is required');
+    const target = resolvedTarget ?? await fs.resolve(path, resolveOptions(payload, invocation));
+    for(let attempt=0;attempt<3;attempt++) {
+      const info=await fs.stat(target, invocation?.signal);
+      if(!info)throw codedError('FS_NOT_FOUND',`not found: ${target.displayPath}`);
+      if(info.type!=='file')throw codedError('FS_NOT_REGULAR_FILE',`not a regular file: ${target.displayPath}`);
+      let text, baseline;
+      // The local provider's version identifies native bytes. Use the same
+      // strict BOM/EOL decoder as its writer; virtual providers keep their API.
+      const native=authority===MODEL_TOOL ? null : await fsStat(nativeTargetPath(target),{bigint:true}).catch(e=>{if(e.code!=='ENOENT')throw e;return null;});
+      if(native&&versionOfBigInt(native)===String(info.version)) {
+        try {const snapshot=await localDocuments.snapshot(nativeTargetPath(target)); baseline=snapshot.baseline.sha256; text=textCodec.decodeDocument(snapshot.bytes,target.displayPath).text;}
+        catch(error){if(error.code==='MP_FILE_CONFLICT')continue;throw error;}
+      } else text=await fs.readText(target, invocation?.signal);
+      const after=await fs.stat(target, invocation?.signal);
+      if(!after||String(after.version)!==String(info.version))continue;
+      const value={text,version:after.version,displayPath:target.displayPath,size:after.size,type:after.type};
+      if (payload.live === true && baseline && authority !== MODEL_TOOL) {
+        const canonical=await canonicalTarget(target);
+        const seed=text.replace(/\r\n?/g,'\n');
+        const joined=await live.join(canonical,seed,baseline);
+        if (closed) { live.leave(joined.client);throw codedError('MP_LIVE_CLOSED','editor host stopped'); }
+        leases.set(joined.client,{canonical:pathKey(canonical)});
+        value.live={client:joined.client,epoch:joined.epoch,version:joined.version,diskHash:joined.diskHash,dirty:joined.text!==seed,savedVersion:joined.savedVersion,
+          ...(Array.isArray(joined.recovered)?{recovered:joined.recovered}:{})};
+        value.text=joined.text;
+      }
+      return {ok:true,value};
+    }
+    throw codedError('FS_STALE_VERSION','file changed during read; retry after the external write finishes');
+  }
+
+  async function apiSave(payload) {
+    const path = typeof payload?.path === 'string' ? payload.path : '';
+    const text = typeof payload?.text === 'string' ? payload.text : null;
+    const baseVersion = typeof payload?.baseVersion === 'string' ? payload.baseVersion : '';
+    if (!path) return badRequest('path is required');
+    if (text === null) return badRequest('text is required');
+    if (!baseVersion) return badRequest('baseVersion is required — refusing to overwrite without a version guard');
+    const target = await fs.resolve(path, resolveOptions(payload)),key=pathKey(await canonicalTarget(target));
+    return queueSave(key,async()=>{
+      const current=await fs.resolve(path,resolveOptions(payload));
+      if(pathKey(await canonicalTarget(current))!==key)throw codedError('FS_STALE_VERSION','save target changed while queued');
+      const before=await fs.stat(current);
+      if(!before)throw codedError('FS_STALE_VERSION','file no longer exists');
+      let result;
+      const native=await fsStat(nativeTargetPath(current),{bigint:true}).catch(e=>{if(e.code!=='ENOENT')throw e;return null;});
+      const local=!!native && versionOfBigInt(native)===String(before.version);
+      if (payload.live) {
+        const ticket=payload.live;
+        if(!local||leaseOf(ticket.client).canonical!==key)throw codedError('MP_LIVE_LEASE','synchronized save target changed');
+        let writerVersion;
+        result=await live.save(ticket.client,{epoch:ticket.epoch,version:ticket.version,text},async({diskHash})=>{
+          const version=await fs.stat(current);
+          const identity=await fsStat(nativeTargetPath(current),{bigint:true});
+          if (!version || versionOfBigInt(identity)!==String(version.version) || pathKey(await canonicalTarget(await fs.resolve(path,resolveOptions(payload))))!==key)
+            throw codedError('FS_STALE_VERSION','file identity changed while waiting to save');
+          const receipt=await directWriteText(fs,current,text,String(version.version),diskHash);
+          writerVersion=receipt.version;
+          return receipt;
+        });
+        // 内核最终契约：写者回执保持权威（provider.version 原样），live 元数据以
+        // liveVersion/savedVersion/diskHash/epoch 另列。此防御兼容过渡期旧形状
+        // （旧内核把 head.version 并进回执盖掉写者版本）—— 两种形状下客户端拿到的
+        // version 都是盘版本、房间版本都在 liveVersion。
+        if(writerVersion!==undefined&&result&&typeof result==='object'&&String(result.version)!==String(writerVersion))
+          result={...result,liveVersion:result.version,version:writerVersion};
+      }else if(String(before.version)!==baseVersion)throw codedError('FS_STALE_VERSION','file changed since read');
+      else if(local)result=await live.external(nativeTargetPath(current),()=>directWriteText(fs,current,text,baseVersion));
+      else try {result=await fs.writeText(current,text,{kind:'replaceIfVersion',version:baseVersion});}
+      catch(error){if(!isSandboxWriteDenied(error))throw error;result=await directWriteText(fs,current,text,baseVersion);}
+      const version=result?.version;broadcastChange(current,version);
+      const value={version,displayPath:current.displayPath,size:result.size??Buffer.byteLength(text,'utf8')};
+      if(payload.live&&result&&typeof result==='object'){
+        // 已授权 live 保存专属：按客户端 applyLiveReceipt 约定透传最小 live 元数据
+        // （savedVersion/liveVersion/epoch/diskHash；provider version 保持权威）。
+        // 普通旧保存与模型写不走此分支 —— live capabilities 不外泄。
+        if(Number.isSafeInteger(result.savedVersion))value.savedVersion=result.savedVersion;
+        if(Number.isSafeInteger(result.liveVersion))value.liveVersion=result.liveVersion;
+        if(typeof result.epoch==='string'&&result.epoch)value.epoch=result.epoch;
+        if(typeof result.diskHash==='string'&&result.diskHash)value.diskHash=result.diskHash;
+      }
+      return {ok:true,value};
+    });
+  }
+
+  async function apiStat(payload) {
+    const path = typeof payload?.path === 'string' ? payload.path : '';
+    if (!path) return badRequest('path is required');
+    const target = await fs.resolve(path, resolveOptions(payload));
+    const info = await fs.stat(target);
+    if (!info) return { ok: true, value: { missing: true } };
+    return { ok: true, value: { version: info.version, size: info.size, type: info.type, displayPath: target.displayPath } };
+  }
+
+  async function apiEdit(payload, invocation) {
+    const path = typeof payload?.path === 'string' ? payload.path : '';
+    const oldString = typeof payload?.oldString === 'string' ? payload.oldString : null;
+    const newString = typeof payload?.newString === 'string' ? payload.newString : null;
+    if (!path) return badRequest('path is required');
+    if (oldString === null || newString === null) return badRequest('oldString and newString are required');
+    if(!oldString)return badRequest('oldString must not be empty');
+    const resolution=resolveOptions(payload, invocation);
+    const target=await fs.resolve(path,resolution),key=pathKey(await canonicalTarget(target));
+    return queueSave(key,async()=>{
+      invocation?.signal?.throwIfAborted();
+      const current=await fs.resolve(path,resolution);
+      if(pathKey(await canonicalTarget(current))!==key)throw codedError('FS_STALE_VERSION','edit target changed while queued');
+      const opened=await apiOpen(payload,MODEL_TOOL,current,invocation),value=opened.value;
+      if(!opened.ok)return opened;
+      if(payload.baseVersion&&payload.baseVersion!==value.version)throw codedError('FS_STALE_VERSION','file changed since read');
+      const first=value.text.indexOf(oldString);
+      if(first<0)throw codedError('FS_EDIT_NOT_FOUND','old_string was not found');
+      if(payload.replaceAll!==true && value.text.includes(oldString,first+oldString.length))throw codedError('FS_AMBIGUOUS_EDIT','ambiguous edit');
+      const write=()=>fs.editText(current,{oldString,newString,replaceAll:payload.replaceAll===true},{version:value.version},invocation?.signal,invocation?.policy);
+      const native=await fsStat(nativeTargetPath(current),{bigint:true}).catch(e=>{if(e.code!=='ENOENT')throw e;return null;});
+      const result=native && versionOfBigInt(native)===String(value.version)
+        ? await live.external(nativeTargetPath(current),write) : await write();
+      broadcastChange(current,result.version,{oldString,newString});
+      return {ok:true,value:{version:result.version,displayPath:current.displayPath,changed:newString!==oldString}};
+    });
+  }
+
+  async function dispatch(endpoint, payload, authority, execution) {
+    try {
+      let invocation;
+      if (authority === MODEL_TOOL) {
+        const session = execution?.agent?.session;
+        let policy;
+        if (endpoint === 'edit' && fs.sandboxMode !== undefined) {
+          policy = await options.sandboxPolicy?.()?.resolve(session ? {session} : {});
+          if (!policy?.mode) throw codedError('FS_SANDBOX_DENIED', 'Cannot resolve filesystem policy for this tool call');
+        }
+        invocation = {signal: execution?.signal, cwd: policy?.workspaceRoot ?? session?.header?.cwd, policy};
+        invocation.signal?.throwIfAborted();
+      }
+      switch (endpoint) {
+        case 'open': return await apiOpen(payload, authority, undefined, invocation);
+        case 'save': return await apiSave(payload);
+        case 'stat': return await apiStat(payload);
+        case 'live': return authority === MODEL_TOOL ? badRequest('editor lease required') : await liveEndpoint(payload);
+        case 'edit': return await apiEdit(payload, invocation);
+        default: return badRequest(`unknown endpoint: ${String(endpoint)}`);
+      }
+    } catch (error) {
+      const code = errorCode(error);
+      try { log.warn?.('%s: %s failed (%s): %s', name, String(endpoint), code, String(error?.message ?? error)); } catch { /* 日志失败不影响响应 */ }
+      return { ok: false, error: { code, message: String(error?.message ?? error) } };
+    }
+  }
+
+  /** 信任栅栏：requestRejection 以方法调用；不可用时只放行 loopback。 */
+  function fenceStatus(req) {
+    let rejection;
+    try {
+      let connection;
+      try { connection = connectionProvider(); } catch { connection = undefined; }
+      if (typeof connection?.requestRejection === 'function') {
+        try { rejection = connection.requestRejection.call(connection, req); } catch { rejection = 403; }
+      } else if (!isTrustedLoopbackRequest(req)) {
+        rejection = 403;
+      }
+    } catch {
+      rejection = isTrustedLoopbackRequest(req) ? undefined : 403;
+    }
+    if (rejection === undefined) return undefined;
+    return typeof rejection === 'number' ? rejection : 403;
+  }
+
+  async function handleApiPost(req, res, url) {
+    const endpoint = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '');
+    if (!KNOWN_ENDPOINTS.has(endpoint)) {
+      try { req.resume(); } catch { /* 已断 */ }
+      sendJson(res, 404, { ok: false, error: { code: 'not-found', message: `unsupported endpoint: ${String(endpoint)}` } });
+      return;
+    }
+    const mediaType = req.headers['content-type']?.split(';', 1)[0]?.trim().toLowerCase();
+    if (mediaType !== 'application/json') {
+      try { req.resume(); } catch { /* 已断 */ }
+      sendJson(res, 415, badRequest('content type must be application/json'));
+      return;
+    }
+    const body = await readBody(req, bodyLimit);
+    if (!body.ok) {
+      const status = body.code === 'too-large' ? 413 : 400;
+      sendJson(res, status, { ok: false, error: { code: body.code, message: body.code === 'too-large' ? `body exceeds ${bodyLimit} bytes` : 'body read failed' } }, { connection: 'close' });
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(body.buffer.toString('utf8'));
+    } catch {
+      sendJson(res, 400, badRequest('body is not JSON'));
+      return;
+    }
+    if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+      sendJson(res, 400, badRequest('body must be a JSON object'));
+      return;
+    }
+    const result = await dispatch(endpoint, payload);
+    sendJson(res, 200, result);
+  }
+
+  const route = {
+    kind: 'prefix',
+    path: ROUTE_PREFIX,
+    handler: async (req, res) => {
+      try {
+        const rejection = fenceStatus(req);
+        if (rejection !== undefined) {
+          sendText(res, rejection, rejection === 401 ? 'unauthorized' : 'forbidden');
+          return;
+        }
+        let url;
+        try {
+          url = new URL(req.url ?? '/', `http://${req.headers.host ?? '127.0.0.1'}`);
+        } catch {
+          sendText(res, 400, 'bad request');
+          return;
+        }
+        const pathname = url.pathname;
+        const isRead = req.method === 'GET' || req.method === 'HEAD';
+
+        if (isRead && pathname === CORE_JSON_PATH) {
+          await serveCoreJson(req, res);
+          return;
+        }
+        // 本地图片通道（文档相对路径图）：见 serveImageFile 上方注释。
+        if (isRead && pathname.startsWith(IMG_PREFIX)) {
+          await serveImageFile(req, res, pathname.slice(IMG_PREFIX.length));
+          return;
+        }
+        if (isRead && pathname === STATIC_PREFIX.slice(0, -1)) {
+          await serveStatic(req, res, 'index.html');
+          return;
+        }
+        if (isRead && pathname.startsWith(STATIC_PREFIX)) {
+          await serveStatic(req, res, pathname.slice(STATIC_PREFIX.length));
+          return;
+        }
+        if (req.method === 'GET' && pathname === API_PREFIX + 'watch') {
+          await handleWatch(req, res, url);
+          return;
+        }
+        if (req.method === 'POST' && pathname.startsWith(API_PREFIX)) {
+          await handleApiPost(req, res, url);
+          return;
+        }
+        sendJson(res, 404, { ok: false, error: { code: 'not-found', message: `not found: ${pathname}` } });
+      } catch (error) {
+        const code = errorCode(error);
+        try { log.warn?.('%s: request failed (%s): %s', name, code, String(error?.message ?? error)); } catch { /* 日志失败不影响响应 */ }
+        if (!res.headersSent) sendJson(res, 200, { ok: false, error: { code, message: String(error?.message ?? error) } });
+        else { try { res.end(); } catch { /* 已断 */ } }
+      }
+    },
+  };
+
+  function close() {
+    closed=true;
+    // 先放本 host 自己的资源（leases → SSE → watchers），再离场代际计数：
+    // 已接纳的异步 save 排空后才可能触发旧代资源关闭（scheduleHostRetirement）。
+    for(const client of leases.keys())releaseLive(client);
+    for (const stream of liveStreams) {
+      try { stream.res.end(); } catch { /* 已断 */ }
+    }
+    liveStreams.clear();
+    for (const entry of watchers.values()) {
+      entry.disposed = true;
+      try { entry.controller.abort(); } catch { /* 已停 */ }
+      if (entry.timer) clearInterval(entry.timer);
+      if (entry.debounce) clearTimeout(entry.debounce);
+      const closeFn = entry.close;
+      entry.close = null;
+      if (typeof closeFn === 'function') {
+        Promise.resolve().then(() => closeFn()).catch(() => { /* close 失败不影响进程 */ });
+      }
+    }
+    watchers.clear();
+    unregisterHost(hostToken);   // 代际生命周期：最后一步离场；同代其它 host 不受影响
+  }
+
+  const hostToken = {};
+  registerHost(hostToken);
+  return { route, dispatch, close, broadcastChange, _internals: { watchers, liveStreams } };
+}
+
+function safeGet(ctx, serviceName) {
+  try {
+    return ctx?.get?.(serviceName);
+  } catch {
+    return undefined;
+  }
+}
+
+function safeLogger(ctx) {
+  try {
+    if (typeof ctx?.logger === 'function') return ctx.logger(name);
+  } catch { /* 用 console */ }
+  return console;
+}
+
+export function apply(ctx) {
+  const log = safeLogger(ctx);
+  let fsService = safeGet(ctx, 'fs');
+  if (!fsService) {
+    try { fsService = ctx.fs; } catch { fsService = undefined; }
+  }
+  if (!fsService) {
+    log.warn?.('%s: ctx.fs unavailable — plugin disabled', name);
+    return;
+  }
+
+  let host;
+  try {
+    host = createHost({
+      fs: fsService,
+      log,
+      rootDir: PLUGIN_ROOT,
+      sandboxPolicy: () => safeGet(ctx, 'sandboxPolicy'),
+      connectionProvider: () => safeGet(ctx, 'connection'),
+    });
+  } catch (error) {
+    log.warn?.('%s: host init failed: %s', name, String(error?.message ?? error));
+    return;
+  }
+
+  try {
+    if (typeof ctx.effect === 'function') {
+      ctx.effect(() => {
+        const dispose = ctx.webServer.register(host.route);
+        log.info?.('%s: routes mounted on %s', name, ROUTE_PREFIX);
+        return () => {
+          try { if (typeof dispose === 'function') dispose(); } catch { /* 已清理 */ }
+          try { host.close(); } catch { /* 已清理 */ }
+        };
+      }, 'dsh-markdown-typora: routes');
+    } else {
+      ctx.webServer.register(host.route);
+    }
+  } catch (error) {
+    log.warn?.('%s: route registration failed: %s', name, String(error?.message ?? error));
+    try { host.close(); } catch { /* 已清理 */ }
+    return;
+  }
+
+  // markdown 模型工具：Agent 的编辑入口（与编辑面 tab 同一守卫路径）。
+  registerMarkdownTool(ctx, { dispatch: host.dispatch, log });
+}
+
+/**
+ * markdown 工具定义（纯数据 + execute，不触达宿主）：便于测试/外部校验 defineTool 形态。
+ * DSH 0.2.1 的 defineTool 需要 output.schema + output.render；0.2.0 的旧形态（顶层 render）会抛。
+ */
+export function createMarkdownToolDefinition(dispatch) {
+  return {
+    name: 'markdown',
+    description: [
+      '读写 Markdown（及任意文本）文件，与 MarkPilot 编辑面板走同一版本守卫通道。',
+      'read 返回全文与版本；edit 按字面 oldString→newString 原子替换（同 edit 工具语义）。',
+      '冲突纪律：save/edit 报 FS_STALE_VERSION 说明文件在读取后被改过（可能用户正在编辑面板里打字）——',
+      '此时必须重新 read 拿新版本再重试，绝不盲目覆盖；用户编辑永远优先。',
+    ].join(' '),
+    parameters: {
+      action: { type: 'string', required: true, description: 'read = 读文件（text+version）；edit = 字面替换后守卫写回。', enum: ['read', 'edit'] },
+      path: { type: 'string', required: true, description: '文件的绝对路径。' },
+      cwd: { type: 'string', description: '可选：相对路径的解析基准目录。' },
+      oldString: { type: 'string', description: 'action=edit 必填：要替换的原文字面量（须在文件中唯一，除非 replaceAll）。' },
+      newString: { type: 'string', description: 'action=edit 必填：替换后的文字面量。' },
+      replaceAll: { type: 'boolean', description: 'action=edit 可选：替换所有出现（默认 false）。' },
+      baseVersion: { type: 'string', description: '可选：上次 read 拿到的版本；提供后文件已变则拒绝（FS_STALE_VERSION），不盲写。' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          action: { type: 'string', required: true },
+          text: { type: 'string' },
+          version: { type: 'string' },
+          displayPath: { type: 'string' },
+          changed: { type: 'boolean' },
+          error: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              code: { type: 'string', required: true },
+              message: { type: 'string', required: true },
+            },
+          },
+        },
+      },
+      render: (args, value) => {
+        if (value?.ok !== true) {
+          return textBlock(`markdown ${String(args?.action ?? '')} 失败：${value?.error?.code ?? 'error'} — ${value?.error?.message ?? ''}`);
+        }
+        if (value.action === 'read') {
+          const text = String(value.text ?? '');
+          const head = text.length > 8000 ? `${text.slice(0, 8000)}\n…（共 ${text.length} 字符，已截断）` : text;
+          return textBlock(`${value.displayPath ?? ''}（版本 ${String(value.version ?? '').slice(0, 12)}…）:\n${head}`);
+        }
+        return textBlock(`已应用编辑：${value.displayPath ?? ''}${value.changed === false ? '（oldString 与 newString 相同，内容未变）' : ''}，新版本 ${String(value.version ?? '').slice(0, 12)}…`);
+      },
+    },
+    async execute(args, execution) {
+      const action = args?.action === 'edit' ? 'edit' : 'read';
+      try {
+        if (action === 'read') {
+          const result = await dispatch('open', { path: args?.path, cwd: args?.cwd }, MODEL_TOOL, execution);
+          if (result.ok !== true) return { ok: false, action, error: result.error };
+          return {
+            ok: true,
+            action,
+            text: result.value.text,
+            version: result.value.version,
+            displayPath: result.value.displayPath,
+          };
+        }
+        const result = await dispatch('edit', {
+          path: args?.path,
+          cwd: args?.cwd,
+          oldString: args?.oldString,
+          newString: args?.newString,
+          replaceAll: args?.replaceAll === true,
+          baseVersion: args?.baseVersion,
+        }, MODEL_TOOL, execution);
+        if (result.ok !== true) return { ok: false, action, error: result.error };
+        return {
+          ok: true,
+          action,
+          version: result.value.version,
+          displayPath: result.value.displayPath,
+          changed: result.value.changed,
+        };
+      } catch (error) {
+        return { ok: false, action, error: { code: errorCode(error), message: String(error?.message ?? error) } };
+      }
+    },
+  };
+}
+
+/**
+ * markpilot 模型工具（read/edit）：与编辑面 tab 同一守卫。加载失败只告警，不影响插件其它能力。
+ */
+export function registerMarkdownTool(ctx, { dispatch, log } = {}) {
+  const onWarn = (error) => {
+    try { log?.warn?.('dsh-markdown-typora: model tool disabled: %s', String(error?.message ?? error)); } catch { /* 忽略 */ }
+  };
+  try {
+    if (typeof ctx?.inject !== 'function') return;
+    ctx.inject(['tools'], (sctx) => {
+      try {
+        const tools = sctx?.get?.('tools') ?? sctx?.tools;
+        if (!tools || typeof tools.register !== 'function') {
+          onWarn(new Error('Host tools.register is unavailable'));
+          return;
+        }
+        sctx.effect(() => {
+          let stopped = false;
+          let dispose;
+          Promise.resolve()
+            .then(() => import('@deepseek-ai/dsh-tools'))
+            .then((mod) => {
+              if (stopped) return;
+              const defineTool = mod?.defineTool;
+              if (typeof defineTool !== 'function') throw new Error('Host defineTool is unavailable');
+              const tool = defineTool(createMarkdownToolDefinition(dispatch));
+              dispose = tools.register(tool);
+            })
+            .catch((error) => {
+              if (!stopped) onWarn(error);
+            });
+          return () => {
+            stopped = true;
+            try { if (typeof dispose === 'function') dispose(); } catch (error) { onWarn(error); }
+          };
+        }, 'dsh-markdown-typora: markdown tool');
+      } catch (error) {
+        onWarn(error);
+      }
+    });
+  } catch (error) {
+    onWarn(error);
+  }
+}
+
+export default { name, inject, apply };