@aiti-ai/aiti-models-import 0.0.0-stage → 0.1.9

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/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.tsx

@@ -0,0 +1,51 @@
+/**
+ * aiti-models-import · client 入口
+ *
+ * register(ctx)：
+ *   1. toolbar 按钮（icons/import.svg，手动打开导入弹窗）
+ *   2. dialogs 插槽常驻条目（ImportDialogSlot，显隐模块内状态）
+ *   3. 首启自动弹：register 时 fetch /status 一次（事件驱动，无轮询）——
+ *      firstRun（无 completedAt/dismissedAt）且存在可用来源 → 打开弹窗（只打扰一次）
+ */
+import { __setCtx } from "./host-shim";
+import { ImportDialogSlot, setDialogOpen } from "./import-app";
+
+export default function register(ctx: Record<string, unknown>) {
+  __setCtx(ctx); // 必须在任何 JSX 渲染前
+
+  function ImportButton() {
+    return (
+      <button type="button" title="从其他 Agent 导入模型配置（codex / zcode / opencode…）"
+        onClick={() => setDialogOpen(true)}
+        style={{ display: "flex", alignItems: "center", justifyContent: "center", width: 36, height: 36, padding: 0, background: "none", borderTop: "none", borderRight: "1px solid var(--border)", color: "var(--text-muted)", cursor: "pointer", fontSize: 15 }}>
+        <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden>
+          <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+          <path d="m7 10 5 5 5-5" />
+          <path d="M12 15V3" />
+        </svg>
+      </button>
+    );
+  }
+
+  ctx.registerItems?.("toolbar", [{ id: "aiti-models-import-open", render: ImportButton, meta: { label: "导入模型配置", icon: "icons/import.svg" } }]);
+  ctx.registerItems?.("dialogs", [{ id: "aiti-models-import-dialog", render: ImportDialogSlot, meta: { label: "模型配置导入" } }]);
+
+  // 跨扩展打开服务（quickstart 引导卡「从 Agent 导入…」消费；ext-services 拍板正路）。
+  // 消费方探测式软依赖：本扩展缺席/旧版无服务 → 对方不渲染入口。
+  try {
+    ctx.registerExtService?.("aiti-models-import.open", { open: () => setDialogOpen(true) });
+  } catch { /* ignore */ }
+
+  // 首启判定：每页面加载至多一次 /status；firstRun 且有可用来源 → 自动弹（关过/导过即不再弹）
+  try {
+    const base = typeof (ctx as any).apiUrl === "function" ? (ctx as any).apiUrl("/api/extensions/aiti-models-import/status") : "/api/extensions/aiti-models-import/status";
+    fetch(base, { cache: "no-store" })
+      .then((r) => r.json())
+      .then((st) => {
+        if (st && st.ok && st.firstRun && Array.isArray(st.sources) && st.sources.some((s: any) => s.available)) {
+          setDialogOpen(true);
+        }
+      })
+      .catch(() => { /* 状态不可得就不弹（手动入口仍在） */ });
+  } catch { /* 极端环境防御 */ }
+}

package/client/src/host-shim.ts

@@ -0,0 +1,88 @@
+/**
+ * host-shim —— JSX client bundle 的宿主桥（共享模板通用版）。
+ *
+ * 为什么需要它：浏览器不认识 JSX，扩展 client 要写 JSX 必须经过 esbuild 预编译
+ * （vite lib mode）。esbuild 的 JSX 自动运行时（jsx: "automatic"）会生成
+ * `jsx(type, props)` 调用，默认指向 React。但 pi-web 的扩展 client 不是 React——
+ * 宿主经 register(ctx) 传入的是自己的渲染原语（h / useState / useEffect / apiUrl…）。
+ *
+ * 所以这里用 vite 的 resolve.alias 把 react / react/jsx-runtime 重定向到本 shim：
+ *   组件里 import react 的 hooks → 本 shim 的 createElement/useState/… → 委托 ctx。
+ * 产物里零 React 引用，宿主保持单渲染实例，npm 生态组件（只要用标准 react hooks）
+ * 也能直接打包进来用。
+ *
+ * 使用：entry.tsx 的 register(ctx) 里第一件事调 `__setCtx(ctx)`（任何 JSX 渲染前）。
+ * 需要的字段（apiUrl/t/useRef/useMemo…）按需在这里加一行委托即可。
+ */
+
+// 模块级 ctx（entry.tsx 的 register 时设置；组件渲染时读取）
+let _ctx: Record<string, unknown> | null = null;
+export function __setCtx(ctx: Record<string, unknown>): void { _ctx = ctx; }
+function c<T = (...args: never[]) => unknown>(name: string): T {
+  return (_ctx?.[name] as T) ?? (() => undefined as never);
+}
+
+// ---------- react 兼容导出（esbuild alias react → 本 shim） ----------
+// React 的 Fragment 类型是 Symbol.for("react.fragment")——传给宿主 h 即生成真 Fragment。
+export const Fragment = (typeof Symbol !== "undefined" && Symbol.for) ? Symbol.for("react.fragment") : 0xacb;
+export function createElement(...args: unknown[]): unknown {
+  return c("h").call(null, ...args);
+}
+// 自动运行时 jsx(type, props, key)——key 是独立第三参；宿主 h() = React.createElement
+// 的第三参是 **children**。直接透传会把 key 当子元素（元素 key 丢失 + key 值覆盖
+// props.children 成为真实内容）。因此必须把 key 合并回 props。
+function mergeKey(args: unknown[]): unknown[] {
+  const [type, props, key, ...rest] = args;
+  if (props && typeof props === "object") {
+    // key 一律合并进 props，createElement 恒收 (type, config) 两参：
+    // 有 key → config.key 由 React 读为元素 key；key 为 undefined/null → 也必须剥掉第三参——
+    // 否则 createElement(type, config, undefined) 按 legacy 语义（第三参=children）用 undefined
+    // 覆盖 props.children，元素内容整体丢失（实证：aiti-editor ⋯ 菜单 key=undefined 的项全部空白）。
+    const merged: Record<string, unknown> = { ...(props as Record<string, unknown>) };
+    if (key !== undefined && key !== null) merged.key = key;
+    return [type, merged, ...rest];
+  }
+  return args;
+}
+export const jsx = (...args: unknown[]) => createElement(...mergeKey(args));
+export const jsxs = (...args: unknown[]) => {
+  // React 自动运行时语义：jsxs（静态多子元素）创建时会对每个子元素调用
+  // validateChildKeys → 标记 _store.validated = 1（"已校验，勿再告警"）。宿主 h()
+  // 是 React.createElement，但它只创建元素、不做这个标记——不补的话，
+  // `<div><A/><B/></div>` 这类“静态兄弟元素”（JSX 里无需写 key，React 自动运行时
+  // 本应抑制该警告）会被 React 误报 “Each child in a list should have a unique key”
+  // （dev-only，按 owner 去重一次）。值必须是 1（2 是另一特殊标记，仍会告警）。
+  const props = (args as [unknown, { children?: unknown } | undefined, ...unknown[]])[1];
+  const children = props?.children;
+  if (Array.isArray(children)) {
+    for (const c of children) {
+      if (c && typeof c === "object" && (c as { _store?: { validated?: number } })._store) {
+        (c as { _store: { validated: number } })._store.validated = 1;
+      }
+    }
+  }
+  return createElement(...mergeKey(args));
+};
+
+// ---------- React hooks 委托（按需增删） ----------
+export const useState = <T>(init: T | (() => T)) => c<(...a: unknown[]) => [T, (v: T | ((prev: T) => T)) => void]>("useState")(init);
+export const useEffect = (fn: () => unknown, deps?: unknown[]) => c("useEffect")(fn, deps);
+export const useRef = <T>(v: T) => c<(...a: unknown[]) => { current: T }>("useRef")(v);
+export const useCallback = <T extends (...args: never[]) => unknown>(fn: T, deps?: unknown[]) => c<(...a: unknown[]) => T>("useCallback")(fn, deps);
+export const useMemo = <T>(fn: () => T, deps?: unknown[]) => c<(...a: unknown[]) => T>("useMemo")(fn, deps);
+
+// ---------- 宿主工具委托（按需增删） ----------
+/** apiUrl(p)：把相对路径拼成当前 basePath 下的完整 API URL（多实例 /dev 前缀安全）。 */
+export function apiUrl(p: string): string {
+  const fn = _ctx?.apiUrl as ((p: string) => string) | undefined;
+  return typeof fn === "function" ? fn(p) : p;
+}
+/** t(key, params?)：扩展 i18n 翻译（index.ts ui.i18n 里的词条）。 */
+export function t(key: string, params?: Record<string, unknown>): string {
+  const fn = _ctx?.t as ((key: string, params?: Record<string, unknown>) => string) | undefined;
+  return typeof fn === "function" ? fn(key, params) : key;
+}
+/** 跨扩展客户端服务读取（ctx.getExtService；提供方懒加载/缺席 → undefined，消费方必须降级）。 */
+export function extSvc<T = unknown>(key: string): T | undefined {
+  return (_ctx as any)?.getExtService?.(key) as T | undefined;
+}