@aiti-ai/aiti-onlyoffice 0.0.0-stage → 0.1.7

package/AGENTS.md

@@ -0,0 +1,28 @@
+# aiti-onlyoffice 扩展（部署目录直改指南）
+
+## 结构
+- 运行时文件平铺在本目录根（index.ts / core.cjs …，宿主 loader 按相对路径加载——**禁手改运行时平铺文件**，改 src/ 再 build）
+- `src/` 源码（client/src + 服务端 ts/cjs）· `dist/` 构建产物（禁手改）· `tools/` 构建/部署脚本
+- npm 包形态的扩展：本目录 package.json 含 version 与 aitiConfigs 声明
+
+## 小改现场流程（改文案/样式/小逻辑）
+1. 改 `src/` 下对应源码
+2. `node tools/build.mjs`（client 有构建产物的扩展；纯服务端改动跳过）
+3. `curl -X POST http://127.0.0.1:3001/api/extensions/reload`（dev；prod 3002；外部经 nginx 带 basePath：/dev、/mac、/mdev、/win、/wdev → `/xxx/api/extensions/reload`）
+4. 浏览器刷新页面验证
+
+## 大改回源码仓
+- 源码仓：`extensions/aiti-onlyoffice/`（git 管理，deploy 同步回本目录）
+- 改完在源码仓跑 `node tools/deploy.mjs`（或仓库根 `node scripts/deploy-all.mjs --only aiti-onlyoffice`）
+
+## 数据目录（数据分层：config / cache）
+- `ctx.configDir` 根级 = 配置与关键小状态（aiti-configs 备份范围；小、珍贵、人可读）
+- `ctx.cacheDir`（= `<configDir>/cache/`）= 可删缓存：db/venv/日志/大文件；rm -rf 后扩展下次访问自动重建
+- `ctx.dataDir` 已移除（访问即抛）——新代码禁用
+- 本扩展白名单（永不为 cache 的配置文件）见 package.json `aitiConfigs.configFiles`
+
+## 红线
+- 禁轮询（setInterval 拉取）；需要等待用事件/回调/SSE（桥的 SSE、aiti-event-bus topics）
+- 禁重启生产服务（pi-web 3002 等 restart 须用户明确同意）
+- 禁手改 dist/ 与运行时平铺文件；跨扩展通信走 ctx.services（禁 globalThis.__ext 直穿）
+- 服务端：SQLite 一律 WAL + 分批小事务（批间 setImmediate 让步）；禁 execFileSync 调 >1s 外部程序；>8MB 文件禁同步读

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aiti-ai contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/blob-save-route.ts

@@ -0,0 +1,128 @@
+/**
+ * blob-save-route —— 二进制文件保存 route 工厂（共享权威源，部署时拷进扩展目录）。
+ *
+ * 消费方：aiti-sheet-univer / aiti-word-superdoc 等带 edit 能力的实现扩展
+ * （docs/aiti-editor-office-plan.md §2.0 共享层）。
+ *
+ * 端点语义（POST，body JSON）：
+ *   { filePath: string, dataBase64: string, baseMtimeMs?: number, cwd?: string }
+ *   → 200 { ok: true, mtimeMs, size }
+ *   → 400 路径不在白名单 / 扩展名不在白名单 / dataBase64 非法
+ *   → 409 { ok:false, conflict:true, diskMtimeMs } 磁盘已被外部修改（乐观锁）
+ *   → 413 超过 maxBytes
+ * 写盘原子（tmp + rename），目标目录自动创建（同名文件保存必然已存在，目录防御性兜底）。
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, normalize, sep } from "node:path";
+
+/** ~ 展开（浏览器无 homedir；对齐 core /api/files filePathFromSegments） */
+function expandTildePath(p: string): string {
+  const home = homedir();
+  if (p === "~") return home;
+  if (p.startsWith("~/") || p.startsWith("~\\")) return join(home, p.slice(2));
+  return p;
+}
+
+/** 保存白名单（对标 aiti-editor M1 宽松版：workspace + 用户根） */
+export function resolveAllowedWriteRoot(filePath: string, cwd?: string): string | null {
+  if (!filePath) return null;
+  const expanded = expandTildePath(filePath);
+  if (!isAbsolute(expanded)) return null;
+  const home = homedir();
+  const roots: string[] = [];
+  if (cwd && isAbsolute(cwd)) roots.push(normalize(cwd));
+  roots.push(join(home, "workspace"));
+  roots.push(home);
+  const fp = normalize(expanded);
+  return roots.some((r) => fp === r || fp.startsWith(r + sep)) ? fp : null;
+}
+
+export interface BlobSaveRouteOptions {
+  /** 扩展 id（tmp 文件命名/日志前缀） */
+  extId: string;
+  /** 允许保存的扩展名白名单（小写含点，如 [".xlsx", ".xlsm"]） */
+  allowedExts: string[];
+  /** 单文件字节上限（默认 30MB，方案 §2.1 maxBytes feature 档） */
+  maxBytes?: number;
+}
+
+export interface BlobSaveBody {
+  filePath?: unknown;
+  dataBase64?: unknown;
+  baseMtimeMs?: unknown;
+  cwd?: unknown;
+}
+
+/**
+ * 生成 route handler：`if (p[p.length-1] === "save-blob") return await handle(req);`
+ */
+export function createBlobSaveRoute(opts: BlobSaveRouteOptions) {
+  const maxBytes = opts.maxBytes ?? 30 * 1024 * 1024;
+  const allowed = new Set(opts.allowedExts.map((e) => e.toLowerCase()));
+  const log = (m: string) => console.log("[" + opts.extId + "][save-blob] " + m);
+
+  return async function handleSaveBlob(req: Request): Promise<Response> {
+    const json = (body: unknown, status = 200) => new Response(JSON.stringify(body), {
+      status,
+      headers: { "content-type": "application/json", "cache-control": "no-store" },
+    });
+    let body: BlobSaveBody;
+    try {
+      body = await req.json();
+    } catch {
+      return json({ ok: false, error: "body 需为 JSON" }, 400);
+    }
+    const filePath = typeof body.filePath === "string" ? body.filePath : "";
+    const dataBase64 = typeof body.dataBase64 === "string" ? body.dataBase64 : "";
+    const cwd = typeof body.cwd === "string" ? body.cwd : undefined;
+    if (!filePath || !dataBase64) return json({ ok: false, error: "需要 filePath 与 dataBase64" }, 400);
+
+    const lower = filePath.toLowerCase();
+    if (![...allowed].some((ext) => lower.endsWith(ext))) {
+      return json({ ok: false, error: "扩展名不在白名单内（" + [...allowed].join(" ") + "）" }, 400);
+    }
+    const target = resolveAllowedWriteRoot(filePath, cwd);
+    if (!target) return json({ ok: false, error: "路径不在可写白名单内" }, 400);
+
+    let buf: Buffer;
+    try {
+      buf = Buffer.from(dataBase64, "base64");
+    } catch {
+      return json({ ok: false, error: "dataBase64 非法" }, 400);
+    }
+    if (buf.length === 0) return json({ ok: false, error: "空内容拒绝保存" }, 400);
+    if (buf.length > maxBytes) return json({ ok: false, error: "文件超过 " + Math.round(maxBytes / 1024 / 1024) + "MB 上限" }, 413);
+
+    // 乐观锁：baseMtimeMs 与磁盘不一致 → 409（沿用 aiti-editor 冲突 UI 范式）
+    let st;
+    try { st = statSync(target); } catch { /* 新文件（理论上保存目标必已存在；防御） */ }
+    if (st) {
+      if (!st.isFile()) return json({ ok: false, error: "目标不是文件" }, 400);
+      if (typeof body.baseMtimeMs === "number" && Math.abs(st.mtimeMs - (body.baseMtimeMs as number)) > 1) {
+        return json({ ok: false, conflict: true, diskMtimeMs: st.mtimeMs }, 409);
+      }
+    }
+
+    // 原子写：tmp 必须与目标同目录（同文件系统，rename 才不跨设备 EXDEV）
+    const tmp = join(dirname(target), "." + opts.extId + "-save-tmp-" + process.pid + "-" + Date.now());
+    try {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(tmp, buf);
+      renameSync(tmp, target);
+    } catch (e) {
+      try { require("node:fs").rmSync(tmp, { force: true }); } catch { /* 忽略 */ }
+      log("写盘失败: " + String((e as Error).message || e));
+      return json({ ok: false, error: "写盘失败: " + String((e as Error).message || e) }, 500);
+    }
+    const after = statSync(target);
+    log("已保存 " + target + " (" + after.size + " bytes)");
+    return json({ ok: true, mtimeMs: after.mtimeMs, size: after.size });
+  };
+}
+
+/** 内容哈希（调试/日志用） */
+export function blobHash(buf: Buffer): string {
+  return createHash("md5").update(buf).digest("hex").slice(0, 8);
+}

package/check-client.mjs

@@ -0,0 +1,273 @@
+/**
+ * check-client —— 扩展 client .mjs/.js 的 TS 残留 tripwire（零依赖，纯 node）。
+ *
+ * 背景：aiti-plan-review 事故（docs/aiti-ext-client-hardening-plan.md §1）——
+ * `useState<any>(null)` 解析为合法 JS 比较表达式 `useState < any > (null)`，
+ * node --check / TS 解析器 / babel 全不报错，只有运行时才炸。纯语法检查
+ * 原理性无效，只能启发式规则 + 渲染期错误边界兜底。
+ *
+ * 用法：
+ *   CLI    node check-client.mjs <file|dir>...        FAIL → exit 1
+ *   自测   node check-client.mjs --selftest           fixtures 全过 → exit 0
+ *   API    lintClientSource(src) → violations[]       { line, level, rule, text }
+ *          lintPath(path)        → { files, violations }（文件或目录，递归）
+ *          checkClientDir(dir,{log})                 FAIL → throw（deploy 脚本用）
+ *
+ * 词法：规则匹配前先剥离注释/字符串/模板字面量（${} 插值内代码保留检查）——
+ * aiti-editor 的 Monaco TS stub 模板串、JSDoc @return 都是合法内容，不剥全误报。
+ * 已知极限：regex 字面量含引号等 lexer 歧义允许漏报（tripwire 定位非编译器）。
+ *
+ * 豁免：目标行或其上一行含 `check-client:allow` 即跳过该行。
+ * 权威源：本文件；aiti-extman 部署副本由其 tools/deploy.mjs 拷贝（改动两处同步）。
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ── 规则（分级）──────────────────────────────────────────────────────────────
+
+const RULES = [
+  // FAIL：合法 JS 但运行时必炸 / 纯 TS 语法
+  { level: "FAIL", re: /\b(useState|useRef|useMemo|useCallback|useReducer|useImperativeHandle)\s*</, why: "React hook 泛型（运行时必炸）" },
+  // 注：含「any/unknown/string」字样的规则用字符串构 RegExp——本文件自身也
+  // 会被扫，正则字面量里的 (?:any 会被自己命中（词法器不处理 regex 字面量），
+  // 字符串字面量则会被词法遮蔽。
+  { level: "FAIL", re: new RegExp("\\bas\\s+(?:" + "any|unknown|const)\\b"), why: "as 断言" },
+  { level: "FAIL", re: new RegExp(":\\s*(?:" + "any|unknown)\\b"), why: ": any/: unknown 注解" },
+  { level: "FAIL", re: /\b(?:import|export)\s+type\s/, why: "import/export type" },
+  { level: "FAIL", re: /\b(?:interface|enum)\s+[A-Za-z_$]/, why: "interface/enum 声明" },
+  // warn：疑似残留，人工确认，不阻断
+  { level: "warn", re: new RegExp(":\\s*(?:" + "string|number|boolean|void)\\b(?!\\s*[._\\w])"), why: "疑似类型注解" },
+  { level: "warn", re: /\bsatisfies\s/, why: "satisfies" },
+  { level: "warn", re: /\b(?:Record|Partial|Readonly|Omit|Pick)\s*</, why: "TS 工具类型" },
+];
+
+// ── 词法剥离：注释/字符串/模板字面量 → 空格（保留换行，行号不漂移）─────────
+export function stripLiterals(src) {
+  const out = src.split("");
+  const n = src.length;
+  const mask = (from, to) => {
+    for (let k = from; k < to && k < n; k++) if (out[k] !== "\n") out[k] = " ";
+  };
+  let mode = "code";
+  let depth = 0;
+  const stack = []; // 模板 ${ 插值进入时的 brace 深度（支持嵌套模板）
+  let i = 0;
+  while (i < n) {
+    const c = src[i];
+    const d = i + 1 < n ? src[i + 1] : "";
+    if (mode === "code") {
+      if (c === "/" && d === "/") {
+        const j = src.indexOf("\n", i);
+        const end = j === -1 ? n : j;
+        mask(i, end);
+        i = end;
+      } else if (c === "/" && d === "*") {
+        const j = src.indexOf("*/", i + 2);
+        const end = j === -1 ? n : j + 2;
+        mask(i, end);
+        i = end;
+      } else if (c === "'" || c === '"') {
+        let j = i + 1;
+        while (j < n && src[j] !== c && src[j] !== "\n") j += src[j] === "\\" ? 2 : 1;
+        if (j < n && src[j] === c) {
+          mask(i, j + 1);
+          i = j + 1;
+        } else {
+          // 未闭合到行尾 → 可能是 regex 字面量歧义，只遮开引号，按代码继续
+          out[i] = " ";
+          i++;
+        }
+      } else if (c === "`") {
+        mode = "tpl";
+        out[i] = " ";
+        i++;
+      } else if (c === "{") {
+        depth++;
+        i++;
+      } else if (c === "}") {
+        if (stack.length && depth === stack[stack.length - 1]) {
+          stack.pop();
+          mode = "tpl"; // 插值结束回模板
+          out[i] = " ";
+        } else {
+          depth = Math.max(0, depth - 1);
+        }
+        i++;
+      } else i++;
+    } else if (mode === "tpl") {
+      if (c === "\\") {
+        mask(i, Math.min(i + 2, n));
+        i += 2;
+      } else if (c === "`") {
+        mode = "code";
+        out[i] = " ";
+        i++;
+      } else if (c === "$" && d === "{") {
+        stack.push(depth);
+        mode = "code";
+        mask(i, i + 2);
+        i += 2;
+      } else {
+        if (c !== "\n") out[i] = " ";
+        i++;
+      }
+    } else {
+      // 不可达：line/block/字符串均在 code 分支内联处理
+      i++;
+    }
+  }
+  return out.join("");
+}
+
+// ── 单源检查 ────────────────────────────────────────────────────────────────
+export function lintClientSource(src) {
+  const masked = stripLiterals(src);
+  const origLines = src.split("\n");
+  const maskedLines = masked.split("\n");
+  const violations = [];
+  for (let i = 0; i < maskedLines.length; i++) {
+    const prev = i > 0 ? origLines[i - 1] : "";
+    if (origLines[i].includes("check-client:allow") || prev.includes("check-client:allow")) continue;
+    for (const { level, re, why } of RULES) {
+      if (re.test(maskedLines[i])) {
+        violations.push({ line: i + 1, level, rule: why, text: origLines[i].trim().slice(0, 90) });
+      }
+    }
+  }
+  return violations;
+}
+
+// ── 文件/目录检查 ───────────────────────────────────────────────────────────
+const SKIP_DIR = new Set(["node_modules", ".git"]);
+/** 超过此体积视为 vendored bundle（如 Monaco ts.worker，合法含 interface 字样），不查。 */
+const MAX_BYTES = 512 * 1024;
+const isClientFile = (name) => /\.(mjs|js|cjs)$/.test(name) && !/\.min\./.test(name) && !/\.test\./.test(name);
+
+export function lintPath(p, out = { files: 0, violations: [] }) {
+  const st = statSync(p);
+  if (st.isDirectory()) {
+    for (const name of readdirSync(p)) {
+      if (SKIP_DIR.has(name)) continue;
+      lintPath(join(p, name), out);
+    }
+    return out;
+  }
+  const base = p.split("/").pop();
+  if (!isClientFile(base)) return out;
+  if (st.size > MAX_BYTES) return out; // vendored bundle 豁免
+  out.files++;
+  for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  return out;
+}
+
+export function formatViolations(violations) {
+  return violations
+    .map((v) => `  ${v.level} ${v.file}:${v.line} [${v.rule}] ${v.text}`)
+    .join("\n");
+}
+
+/** deploy 脚本用：检查目录，FAIL 抛错（消息含违规清单），warn 只打日志不阻断。 */
+export function checkClientDir(dir, { log = console.log } = {}) {
+  const { files, violations } = lintPath(resolve(dir));
+  const fails = violations.filter((v) => v.level === "FAIL");
+  const warns = violations.filter((v) => v.level === "warn");
+  if (warns.length) log(`[check-client] ${warns.length} 处疑似 TS 残留（不阻断，建议人工确认）：\n${formatViolations(warns)}`);
+  if (fails.length) {
+    throw new Error(
+      `client 检查未通过：${files} 个文件中 ${fails.length} 处 TS 残留（.mjs 里是合法 JS，语法检查不报，运行时必炸）。\n` +
+        formatViolations(fails) +
+        `\n修复或在该行加注释 // check-client:allow 豁免。详见 docs/aiti-ext-client-hardening-plan.md`,
+    );
+  }
+  if (files) log(`[check-client] ${files} 个 client 文件检查通过`);
+  return { files, fails: fails.length, warns: warns.length };
+}
+
+/**
+ * extman 安装用：扫整个扩展目录（含第三方，不遵循 client/ 约定）。
+ * 在 SKIP_DIR 之上额外跳过构建产物/vendored 目录（Monaco ts.worker、语言包等
+ * 合法包含 TS 字样，词法器对 minified 代码不提供保证）；体积上限同上。
+ */
+export function lintExtensionDir(dir) {
+  const out = { files: 0, violations: [] };
+  const walk = (p) => {
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p)) {
+        if (SKIP_DIR.has(name) || VENDORED_DIRS.has(name)) continue;
+        walk(join(p, name));
+      }
+      return;
+    }
+    const base = p.split("/").pop();
+    if (!isClientFile(base) || st.size > MAX_BYTES) return;
+    out.files++;
+    for (const v of lintClientSource(readFileSync(p, "utf8"))) out.violations.push({ file: p, ...v });
+  };
+  walk(resolve(dir));
+  return out;
+}
+const VENDORED_DIRS = new Set(["vendor", "monaco", "dist", "build", "assets", "static", "bundles", "chunks"]);
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+function selftest() {
+  const MUST_FAIL = [
+    "const [st, setSt] = useState<any>(null);",
+    "const r = useRef<number>(null);",
+    "const x = v as any;",
+    "function f(a: unknown) {}",
+    'import type { Foo } from "./x";',
+    "interface Foo { a: string }",
+    "enum Color { Red }",
+    "const y = v as const;",
+  ];
+  const MUST_WARN = [
+    "const opts = { mode: string };",
+    "x satisfies Y;",
+    "const m: Record<string, any> = {};",
+  ];
+  const MUST_PASS = [
+    'const REACT_TYPE_STUB = `\ndeclare module "react" {\n  export function useState<T>(init: T): [T];\n  export const Fragment: any;\n}\n`;',
+    "/** @return {{chars1: string, chars2: string}} */",
+    "const [s] = useState(null);",
+    "useState<any>(null); // check-client:allow",
+    "// check-client:allow\nuseState<never>(0);",
+    "const cmp = a < b && c > (d);",
+    "if (a // 注释里 as any 不算\n  ) run();",
+  ];
+  let bad = 0;
+  const check = (src, expect, desc) => {
+    const v = lintClientSource(src);
+    const fails = v.filter((x) => x.level === "FAIL");
+    const ok = expect === "FAIL" ? fails.length > 0 : expect === "PASS" ? v.length === 0 : v.length > 0 && fails.length === 0;
+    if (!ok) {
+      bad++;
+      console.log(`SELFTEST FAIL [${desc}] 期望 ${expect}，实际 ${JSON.stringify(v)}`);
+    }
+  };
+  MUST_FAIL.forEach((s) => check(s, "FAIL", s.slice(0, 40)));
+  MUST_WARN.forEach((s) => check(s, "WARN", s.slice(0, 40)));
+  MUST_PASS.forEach((s) => check(s, "PASS", s.replace(/\n/g, "⏎").slice(0, 40)));
+  if (bad) {
+    console.log(`selftest: ${bad} 处未过`);
+    process.exit(1);
+  }
+  console.log("selftest: 全部通过（8 FAIL / 3 WARN / 7 PASS）");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.filename)) {
+  if (process.argv.includes("--selftest")) {
+    selftest();
+  } else if (process.argv.length > 2) {
+    const all = { files: 0, violations: [] };
+    for (const p of process.argv.slice(2)) lintPath(resolve(p), all);
+    const fails = all.violations.filter((v) => v.level === "FAIL");
+    const warns = all.violations.filter((v) => v.level === "warn");
+    if (all.violations.length) console.log(formatViolations(all.violations));
+    console.log(`\n${all.files} 个文件：FAIL=${fails.length} warn=${warns.length}`);
+    process.exit(fails.length ? 1 : 0);
+  } else {
+    console.log("用法：node check-client.mjs <file|dir>... ｜ --selftest");
+    process.exit(2);
+  }
+}

package/client/src/entry.ts

@@ -0,0 +1,98 @@
+/**
+ * aiti-onlyoffice · client 入口（M2，docs/aiti-editor-office-plan.md §2.4）。
+ *
+ * 注册判据（server /status）：feature onlyoffice.enabled 开 + DocumentServer healthcheck 通过
+ * → 注册 word/sheet/slide 三 provider（分开注册让用户能分别设默认）。失败 → 不注册（菜单自然无此项）。
+ * 保存不经 ContentProvider（DS 内部经 callback 直写服务端），仅本次注册 editor provider。
+ */
+import { whenAitiEditorReady } from "../../../_shared/aiti-editor-inject.mjs";
+import { renderOnlyofficeView } from "./oo-view";
+
+interface ProviderSpec {
+  id: string;
+  displayName: string;
+  extensions: string[];
+  about: { summary: string; capabilities: string[]; limits: string[]; vendor: string };
+}
+
+const PROVIDERS: ProviderSpec[] = [
+  {
+    id: "aiti-onlyoffice.docx",
+    displayName: "Word（OnlyOffice）",
+    extensions: [".docx", ".doc", ".odt"],
+    about: {
+      summary: "OnlyOffice DocumentServer 深度保真 Word 编辑（完整排版还原；.doc/.odt 老格式原生编辑）",
+      capabilities: ["完整保真渲染与编辑（与桌面 Word 同引擎）", "DS 侧保存（forcesave/自动保存经 callback 直写服务端）", "批注 / 修订 / 目录 / 文本框等复杂排版", "文件变化实时跟随（mtime → key 变 → DS 重拉）"],
+      limits: ["需要本机 Docker 运行 OnlyOffice DocumentServer（scripts/onlyoffice-up.sh）", "容器不可达时 provider 自动消失（菜单无此项）", "AGPL 社区版（隔离于本扩展，不装即无）"],
+      vendor: "OnlyOffice DocumentServer (AGPL-3.0 社区版，Docker)",
+    },
+  },
+  {
+    id: "aiti-onlyoffice.sheet",
+    displayName: "Excel（OnlyOffice）",
+    extensions: [".xlsx", ".xlsm", ".xls", ".ods"],
+    about: {
+      summary: "OnlyOffice DocumentServer 深度保真 Excel 编辑（.xls/.ods 老格式原生编辑）",
+      capabilities: ["完整保真渲染与编辑（公式 / 图表 / 透视表 / 条件格式）", "DS 侧保存（forcesave/自动保存经 callback 直写服务端）", "文件变化实时跟随"],
+      limits: ["需要本机 Docker 运行 OnlyOffice DocumentServer", "容器不可达时 provider 自动消失", "AGPL 社区版（隔离于本扩展）"],
+      vendor: "OnlyOffice DocumentServer (AGPL-3.0 社区版，Docker)",
+    },
+  },
+  {
+    id: "aiti-onlyoffice.slide",
+    displayName: "PowerPoint（OnlyOffice）",
+    extensions: [".pptx", ".ppt", ".odp"],
+    about: {
+      summary: "OnlyOffice DocumentServer 深度保真 PPT 编辑（.ppt/.odp 老格式原生编辑）",
+      capabilities: ["完整保真渲染与编辑（母版 / 动画占位 / 形状）", "DS 侧保存（forcesave/自动保存经 callback 直写服务端）"],
+      limits: ["需要本机 Docker 运行 OnlyOffice DocumentServer", "容器不可达时 provider 自动消失", "AGPL 社区版（隔离于本扩展）"],
+      vendor: "OnlyOffice DocumentServer (AGPL-3.0 社区版，Docker)",
+    },
+  },
+];
+
+async function tryRegister(ctx: Record<string, any>): Promise<void> {
+  const apiUrl = (p: string) => (typeof ctx.apiUrl === "function" ? ctx.apiUrl(p) : p);
+  let status: any = null;
+  try {
+    status = await fetch(apiUrl("/api/extensions/aiti-onlyoffice/status"), { cache: "no-store" }).then((r) => r.json());
+  } catch { return; }
+  if (!status?.ok || !status.enabled || !status.available) {
+    console.log("[aiti-onlyoffice] 不注册 provider：" + (status?.message || "status 不可达"));
+    return;
+  }
+  // dsPublicUrl 传给视图（api.js 加载地址）
+  (window as any).__aitiOnlyofficeDsPublicUrl = status.publicUrl || "";
+
+  whenAitiEditorReady(() => {
+    const we = (window as any).__aitiEditor;
+    const disposables: Array<() => void> = (window as any).__aitiOnlyofficeDisposables || [];
+    for (const off of disposables) { try { off(); } catch { /* 忽略 */ } }
+    disposables.length = 0;
+
+    for (const spec of PROVIDERS) {
+      disposables.push(we.registerEditorProvider({
+        id: spec.id,
+        displayName: spec.displayName,
+        sourceExt: "aiti-onlyoffice",
+        selector: { extensions: spec.extensions },
+        capabilities: ["preview", "edit"],
+        defaultCapability: "edit",
+        about: spec.about,
+        render: (host: any, c: any) => renderOnlyofficeView(host, c),
+      }));
+    }
+    (window as any).__aitiOnlyofficeDisposables = disposables;
+  });
+}
+
+function register(ctx: Record<string, any>): void {
+  // apiUrl（多实例 /dev 前缀安全）→ oo-view 的 config fetch 用
+  (window as any).__aitiOnlyofficeApiUrl = (p: string) => (typeof ctx.apiUrl === "function" ? ctx.apiUrl(p) : p);
+  // 状态探测（/status）推到「编辑器首次就绪」——即用户第一次打开文件/用编辑器时，
+  // 开页不再打这个请求。provider 晚到注册由编辑器仲裁层重新仲裁当前文件
+  // （registry.registerEditorProvider → fireActiveChange）。
+  whenAitiEditorReady(() => { void tryRegister(ctx); });
+}
+
+export default register;

package/client/src/oo-view.ts

@@ -0,0 +1,119 @@
+/**
+ * aiti-onlyoffice · 视图（provider.render 挂载回调，纯 DOM 无 JSX）。
+ *
+ * 数据流（§2.4）：GET /config（JWT 签名）→ 动态加载 DS api.js → DocsAPI.DocEditor iframe。
+ * 保存由 DS 内部经 callbackUrl 直写服务端（不碰 host.save / ContentProvider 管线）。
+ */
+
+const apiUrl = (p: string) => ((window as any).__aitiOnlyofficeApiUrl as (p: string) => string)?.(p) || p;
+
+/** 加载占位 */
+function loadingPane(text: string): HTMLElement {
+  const el = document.createElement("div");
+  el.setAttribute("data-oo-loading", "1");
+  el.style.cssText = "position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:8px;color:var(--text-muted,#888);font-size:13px;background:var(--bg,#fff);z-index:5;";
+  const spinner = document.createElement("div");
+  spinner.style.cssText = "width:22px;height:22px;border-radius:50%;border:2.5px solid var(--border,#e0e0e0);border-top-color:var(--primary,#6366f1);animation:aiti-oo-spin 0.8s linear infinite;";
+  const label = document.createElement("div");
+  label.textContent = text;
+  el.append(spinner, label);
+  if (!document.getElementById("aiti-oo-spin-style")) {
+    const style = document.createElement("style");
+    style.id = "aiti-oo-spin-style";
+    style.textContent = "@keyframes aiti-oo-spin{to{transform:rotate(360deg)}}";
+    document.head.appendChild(style);
+  }
+  return el;
+}
+
+function clearLoading(container: HTMLElement): void {
+  container.querySelectorAll("[data-oo-loading]").forEach((n) => n.remove());
+}
+
+/** 错误态（含「尝试其他编辑器」提示位——打开方式菜单在宿主工具条 ▦） */
+function errorPane(title: string, detail: string): HTMLElement {
+  const el = document.createElement("div");
+  el.style.cssText = "flex:1;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:10px;color:var(--danger, #f87171);font-size:13px;padding:16px;text-align:center;";
+  const t = document.createElement("div"); t.textContent = title;
+  const d = document.createElement("div"); d.style.cssText = "color:var(--text-dim,#888);font-size:12px;word-break:break-all;max-width:80%;"; d.textContent = detail;
+  const hint = document.createElement("div"); hint.style.cssText = "color:var(--text-dim,#888);font-size:12px;";
+  hint.textContent = "可用工具条「▦ 打开方式」切换其他编辑器";
+  el.append(t, d, hint);
+  return el;
+}
+
+/**
+ * DS api.js（<dsPublicUrl>/web-apps/apps/api/documents/api.js → 全局 DocsAPI）。
+ * 必须走 <script src> 真实全局执行：api.js 顶层声明依赖全局作用域（loadVendorGlobal
+ * 的 new Function 包装会把顶层声明困在函数作用域内，window.DocsAPI 永不挂载）。
+ * api.js 非 UMD（无 define 检测），不受页面 Monaco AMD loader 影响。
+ */
+function loadDocsApi(dsPublicUrl: string): Promise<any> {
+  const w = window as any;
+  if (w.DocsAPI) return Promise.resolve(w.DocsAPI);
+  return new Promise((resolve, reject) => {
+    const el = document.createElement("script");
+    el.src = dsPublicUrl.replace(/\/$/, "") + "/web-apps/apps/api/documents/api.js";
+    el.async = true;
+    el.onload = () => {
+      if (w.DocsAPI) resolve(w.DocsAPI);
+      else reject(new Error("api.js 已加载但 DocsAPI 未挂载（DS 版本异常？）"));
+    };
+    el.onerror = () => reject(new Error("api.js 加载失败: " + el.src));
+    document.head.appendChild(el);
+  });
+}
+
+/**
+ * OnlyOffice DocEditor 视图。
+ * 返回 { el, dispose }（provider.render 契约）。
+ */
+export function renderOnlyofficeView(host: any, ctx: { filePath: string; cwd?: string }): { el: HTMLElement; dispose(): void } {
+  const el = document.createElement("div");
+  el.style.cssText = "display:flex;flex-direction:column;height:100%;overflow:hidden;background:var(--bg,#fff);position:relative;";
+  const viewport = document.createElement("div");
+  viewport.style.cssText = "flex:1;min-height:0;position:relative;overflow:hidden;";
+  // DS DocEditor 需要一个占位 div（按 id 替换内容为 iframe）
+  const placeholder = document.createElement("div");
+  placeholder.id = "aiti-oo-editor-" + Math.random().toString(36).slice(2, 8);
+  placeholder.style.cssText = "position:absolute;inset:0;";
+  viewport.appendChild(placeholder);
+  el.appendChild(viewport);
+  viewport.appendChild(loadingPane("连接 OnlyOffice DocumentServer…"));
+
+  let dead = false;
+  let editor: any = null;
+
+  (async () => {
+    const q = new URLSearchParams({ filePath: ctx.filePath, ...(ctx.cwd ? { cwd: ctx.cwd } : {}) });
+    const d = await fetch(apiUrl("/api/extensions/aiti-onlyoffice/config?" + q.toString()), { cache: "no-store" }).then((r) => r.json());
+    if (dead) return;
+    if (!d?.ok) throw new Error(d?.error || "config 获取失败");
+    const DocsAPI = await loadDocsApi((window as any).__aitiOnlyofficeDsPublicUrl || new URL(apiUrl("/"), location.href).origin || "");
+    if (dead) return;
+    clearLoading(viewport);
+    editor = new DocsAPI.DocEditor(placeholder.id, {
+      ...d.config,
+      width: "100%",
+      height: "100%",
+      events: {
+        onDocumentReady: () => { /* DS 内部管理保存与脏态 */ },
+        onError: (e: any) => console.warn("[aiti-onlyoffice] DS 事件:", e),
+      },
+    });
+  })().catch((e) => {
+    if (dead) return;
+    clearLoading(viewport);
+    viewport.querySelectorAll("iframe").forEach((f) => f.remove());
+    viewport.appendChild(errorPane("OnlyOffice 打开失败", String((e && e.message) || e)));
+  });
+
+  return {
+    el,
+    dispose() {
+      dead = true;
+      try { editor?.destroyEditor?.(); } catch { /* 忽略 */ }
+      editor = null;
+    },
+  };
+}

package/client/src/package.json

@@ -0,0 +1 @@
+{ "type": "module" }