@manohub/kit 0.6.0

package/dist/providers/locale-detection.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 语言探测与持久化 —— 替代 i18next 时代的 `i18next-browser-languagedetector`。
+ *
+ * 优先级（高 → 低）：
+ *
+ * 1. 宿主经 micro-app 全局数据下发的 `language`（由 `createSubApp` 直接写入 i18n 实例，
+ *    不参与本模块的探测顺序，只在探测结果之上覆盖）；
+ * 2. localStorage 里上次选定/持久化的语言（key 见 `DEFAULT_LOCALE_STORAGE_KEY`）；
+ * 3. `navigator.language`；
+ * 4. 兜底 `'en'` —— 与迁移前 `fallbackLng: 'en'` 逐字一致。
+ *
+ * 归一化规则与迁移前逐字一致：取 `-` 之前的主语言子标签，`zh` 判为中文，**其余一律 `'en'`**
+ * （`zh-CN` / `zh-Hans` → `zh`，`en-US` / `ja` → `en`）。
+ */
+/** 语言持久化 key。与 i18next 时代的 `i18nextLng` **不同**（属有意行为，老偏好不再生效） */
+export declare const DEFAULT_LOCALE_STORAGE_KEY = "manohub:locale";
+/** 兜底语言（迁移前 `fallbackLng: 'en'` 的等价物） */
+export declare const DEFAULT_FALLBACK_LOCALE = "en";
+/** 本包支持的语言（其余一律归一化到 `en`） */
+export type AppLocale = 'zh' | 'en';
+/**
+ * 归一化任意语言标识为 `'zh' | 'en'`。
+ *
+ * 与迁移前 `String(data.language).split('-')[0] === 'zh' ? 'zh' : 'en'` 行为一致：
+ * 未知语言（含 `undefined` / 空串）都归到 `'en'`。
+ */
+export declare function normalizeLocale(input: unknown): AppLocale;
+/** 读取持久化语言；无值或不可用（隐私模式抛错）时返回 null */
+export declare function readStoredLocale(storageKey?: string): AppLocale | null;
+/** 写入持久化语言；失败静默（不影响当前会话的语言切换） */
+export declare function persistLocale(locale: AppLocale, storageKey?: string): void;
+/** 读取浏览器语言；无 `navigator`（非浏览器环境）时返回 null */
+export declare function detectNavigatorLocale(): AppLocale | null;
+/** 初始语言：localStorage → navigator → `'en'` */
+export declare function detectInitialLocale(storageKey?: string): AppLocale;

package/dist/providers/locale-detection.js

@@ -0,0 +1,44 @@
+const DEFAULT_LOCALE_STORAGE_KEY = "manohub:locale";
+const DEFAULT_FALLBACK_LOCALE = "en";
+function normalizeLocale(input) {
+  return String(input ?? "").split("-")[0]?.toLowerCase() === "zh" ? "zh" : "en";
+}
+function readStoredLocale(storageKey = DEFAULT_LOCALE_STORAGE_KEY) {
+  if (typeof localStorage === "undefined") {
+    return null;
+  }
+  try {
+    const raw = localStorage.getItem(storageKey);
+    return raw ? normalizeLocale(raw) : null;
+  } catch {
+    return null;
+  }
+}
+function persistLocale(locale, storageKey = DEFAULT_LOCALE_STORAGE_KEY) {
+  if (typeof localStorage === "undefined") {
+    return;
+  }
+  try {
+    localStorage.setItem(storageKey, locale);
+  } catch {
+  }
+}
+function detectNavigatorLocale() {
+  if (typeof navigator === "undefined") {
+    return null;
+  }
+  const language = navigator.language;
+  return language ? normalizeLocale(language) : null;
+}
+function detectInitialLocale(storageKey = DEFAULT_LOCALE_STORAGE_KEY) {
+  return readStoredLocale(storageKey) ?? detectNavigatorLocale() ?? DEFAULT_FALLBACK_LOCALE;
+}
+export {
+  DEFAULT_FALLBACK_LOCALE,
+  DEFAULT_LOCALE_STORAGE_KEY,
+  detectInitialLocale,
+  detectNavigatorLocale,
+  normalizeLocale,
+  persistLocale,
+  readStoredLocale
+};

package/dist/providers/setup-i18n.d.ts

@@ -0,0 +1,50 @@
+import type { App } from 'vue';
+import { type AppLocale } from './locale-detection';
+export interface SetupI18nOptions {
+    /**
+     * vue-i18n 消息形态：`{ en: { ... }, zh: { ... } }`。
+     *
+     * ⚠️ 与 i18next 的 `{ en: { translation: {...} } }` 不同，**没有 `translation` 包装层**
+     * （迁移时为破坏性变更）。
+     */
+    messages: Record<string, Record<string, unknown>>;
+    /** 缺省 `'en'`（等价于迁移前的 `fallbackLng: 'en'`） */
+    fallbackLocale?: string;
+    /** 语言持久化 key，缺省 `manohub:locale` */
+    storageKey?: string;
+}
+/**
+ * 全应用唯一的 i18n 实例（vue-i18n Composer 语义：`i18n.global.t` / `.te` / `.locale`）。
+ *
+ * ## 单实例（本包是唯一的创建者）
+ *
+ * 由本包创建并 `app.use`，消费方**不得自行 `createI18n`** —— 全应用只有一个实例，因此：
+ *
+ * - 业务组件与组件树外的服务拿到的是同一份词条与同一个当前语言；
+ * - 不存在「谁后注册谁生效」的覆盖不确定性，也不会两个实例重复注册同名全局组件；
+ * - 语言只需切换一处（本实例的 `locale`）。
+ *
+ * 模块顶层即创建（而不是等 `setupI18n` 才创建），换来两个确定性：
+ *
+ * 1. `i18n` 出口永远是同一个非空实例，消费方无需处理 `null`；
+ * 2. 宿主反复 mount / unmount（micro-app 重挂）时实例不漂移、消息不丢。
+ */
+declare const i18n: import("vue-i18n").I18n<{}, {}, {}, AppLocale, false>;
+export type AppI18n = typeof i18n;
+export { i18n };
+/**
+ * 应用挂载时装配 i18n（幂等）。
+ *
+ * 重复调用**只补消息、不重建实例**：宿主重挂子应用时会再次走到这里，重建会导致
+ * 前一次持有的引用（组件树外的服务、已注入的组件）指向旧实例。
+ */
+export declare function setupI18n(app: App, options: SetupI18nOptions): AppI18n;
+/** 读取当前语言 */
+export declare function getLocale(): string;
+/**
+ * 切换语言：写实例 + 持久化。
+ *
+ * 这是**唯一的语言切换入口**（宿主下发经 `createSubApp` 调用）。因为全应用共用一个
+ * vue-i18n 实例，切换一处即全局生效，不需要额外同步任何一侧。
+ */
+export declare function applyLocale(input: unknown, storageKey?: string): AppLocale;

package/dist/providers/setup-i18n.js

@@ -0,0 +1,42 @@
+import { createI18n } from "vue-i18n";
+import { normalizeLocale, DEFAULT_FALLBACK_LOCALE, detectInitialLocale, persistLocale, DEFAULT_LOCALE_STORAGE_KEY } from "./locale-detection.js";
+const i18n = createI18n({
+  legacy: false,
+  globalInjection: false,
+  locale: detectInitialLocale(),
+  fallbackLocale: DEFAULT_FALLBACK_LOCALE,
+  messages: {},
+  // 迁移前 i18next 缺 key 是静默返回 key；vue-i18n 默认会刷控制台警告，须显式关掉
+  missingWarn: false,
+  fallbackWarn: false,
+  // 缺 key 时回退 key 本身：与迁移前 i18next 的静默行为一致（不抛错、不刷警告）。
+  // 显式写出来是为了表明「这里没有别的兜底来源」—— 词条要么由应用传全，要么就是没翻。
+  missing: (_locale, key) => String(key)
+});
+function setupI18n(app, options) {
+  const { messages, fallbackLocale = DEFAULT_FALLBACK_LOCALE, storageKey } = options;
+  for (const [locale, message] of Object.entries(messages)) {
+    i18n.global.mergeLocaleMessage(locale, message);
+  }
+  i18n.global.fallbackLocale.value = fallbackLocale;
+  setLocale(detectInitialLocale(storageKey), storageKey);
+  app.use(i18n);
+  return i18n;
+}
+function getLocale() {
+  return i18n.global.locale.value;
+}
+function applyLocale(input, storageKey) {
+  return setLocale(normalizeLocale(input), storageKey);
+}
+function setLocale(locale, storageKey) {
+  i18n.global.locale.value = locale;
+  persistLocale(locale, storageKey ?? DEFAULT_LOCALE_STORAGE_KEY);
+  return locale;
+}
+export {
+  applyLocale,
+  getLocale,
+  i18n,
+  setupI18n
+};

package/dist/services/app-container.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 子应用**锚容器**解析 —— `createSubApp` 统一包裹的**作用域锚点**。
+ *
+ * 容器在运行期有两个名字：类名 `app-container`（本包自己的命名前缀，仅供调试自查）与属性
+ * `data-manohub-ui`（**跨包唯一作用域锚**）。后者才是契约：`@manohub/theme` 的主题令牌、
+ * `@manohub/ui` 的组件令牌、以及 ui 服务层的宿主解析，
+ * 全认这一个属性。取「库品牌属性」而不是本包的 `app-` 私有类名，是为了让主题包不欠本包
+ * 一个命名空间 —— 几个包并列安装，谁也不该去锚别人前缀下的名字。
+ *
+ * 因此**任何要落出组件树的内容都必须落在锚容器里**：落到 `body` 上的节点既拿不到令牌
+ * （`var(--ui-*)` 全部失效 ⇒ 组件「样式全丢」），也匹配不到被 `scopecss` 前缀化的应用侧样式。
+ *
+ * 取值优先级：**当前应用挂载时记录的容器**（精确，门户里多应用并存时不会串到别的应用）
+ * → 文档里第一个 `[data-manohub-ui]`（未经 `createSubApp` 的裸挂载场景）
+ * → `document.body`（兜底，行为与「没有本函数」时一致，不会更差）。
+ *
+ * 与 `@manohub/ui` 服务层的关系：本包**不依赖** ui（几个包并列），
+ * 入口编排只在容器上写一个 `data-manohub-ui` 属性；ui 的服务层据此解析宿主。
+ * 应用若要自绘浮层，用本函数取容器（比 `document.querySelector('[data-manohub-ui]')` 精确）。
+ */
+export declare function resolveAppContainer(): Element;
+/**
+ * 同 `resolveAppContainer`，但返回**选择器字符串** —— 给「只吃字符串宿主」的场景用。
+ *
+ * 为什么不能直接给 Element：有的上游件把宿主当选择器解析（`document.querySelector(host)`），
+ * 传 Element 会落到「非法选择器」那条路（实测会抛 `SyntaxError` 并中断整页渲染）。
+ * 给字符串又要避免「门户里多应用并存时串到第一个 `[data-manohub-ui]`」，故给容器补一个
+ * **进程内唯一 id** 再用 `#id` 定位；容器已有 id 时直接用它的。
+ * 兜底到 `document.body` 时返回 `"body"`（有些上游对该值有专门分支，不查 DOM）。
+ */
+export declare function resolveAppContainerSelector(): string;

package/dist/services/app-container.js

@@ -0,0 +1,22 @@
+import { getCurrentAppContainer } from "./app-context.js";
+function resolveAppContainer() {
+  return getCurrentAppContainer() ?? document.querySelector("[data-manohub-ui]") ?? document.body;
+}
+const containerIds = /* @__PURE__ */ new WeakMap();
+let containerSeq = 0;
+function resolveAppContainerSelector() {
+  const container = resolveAppContainer();
+  if (container === document.body) return "body";
+  if (container.id) return `#${container.id}`;
+  let id = containerIds.get(container);
+  if (!id) {
+    id = `ak-app-container-${containerSeq += 1}`;
+    containerIds.set(container, id);
+    container.id = id;
+  }
+  return `#${id}`;
+}
+export {
+  resolveAppContainer,
+  resolveAppContainerSelector
+};

package/dist/services/app-context.d.ts

@@ -0,0 +1,4 @@
+import type { App } from 'vue';
+export declare function setCurrentApp(app: App | null, container?: Element | null): void;
+export declare function getCurrentApp(): App | null;
+export declare function getCurrentAppContainer(): Element | null;

package/dist/services/app-context.js

@@ -0,0 +1,11 @@
+let currentContainer = null;
+function setCurrentApp(app, container = null) {
+  currentContainer = container;
+}
+function getCurrentAppContainer() {
+  return currentContainer;
+}
+export {
+  getCurrentAppContainer,
+  setCurrentApp
+};

package/dist/services/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 本包内部的容器记账（**不是**对外服务层）。
+ *
+ * 命令式反馈服务（消息提示 / 确认框 / 加载遮罩）自 0.6.0 起归 `@manohub/ui` 的服务层；
+ * 本目录只剩「本应用容器是哪一个」这一件事 —— 入口编排创建容器时记下它，浮层与诊断按需取用。
+ */
+export { resolveAppContainer, resolveAppContainerSelector } from './app-container';

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@manohub/kit",
+  "version": "0.6.0",
+  "private": false,
+  "type": "module",
+  "description": "子应用入口编排层：createSubApp（作用域容器与宿主锚点、pinia/路由/vue-query 装配、宿主挂载协议）、i18n 单实例与语言探测，外加随包分发的接入契约（CONTRACT.md，五层闭集条款 + 自检清单）与三个 AI 技能包。本包**零样式产物**：设计令牌（值）在 @manohub/theme，组件（类与行为）在 @manohub/ui，两者由消费方直接引入。",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.iec.io/gsp-cloud-ds/dip/ibp/aihub/frontend-infra.git",
+    "directory": "packages/kit"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "bin",
+    "CONTRACT.md",
+    "README.md"
+  ],
+  "bin": {
+    "kit": "bin/kit.mjs"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./entry": {
+      "types": "./dist/entry/index.d.ts",
+      "import": "./dist/entry/index.js"
+    },
+    "./CONTRACT.md": "./CONTRACT.md"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && vue-tsc -p tsconfig.build.json && vite build",
+    "type-check": "vue-tsc --noEmit -p tsconfig.json",
+    "test:unit": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "@tanstack/vue-query": "^5.0.0",
+    "pinia": "^4.0.0",
+    "vue": "^3.5.0",
+    "vue-i18n": "^11.0.0",
+    "vue-router": "^4.6.0"
+  },
+  "devDependencies": {
+    "@tanstack/vue-query": "catalog:",
+    "@vitejs/plugin-vue-jsx": "catalog:",
+    "jsdom": "^25.0.1",
+    "pinia": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vitest": "^3.2.7",
+    "vue": "catalog:",
+    "vue-i18n": "catalog:",
+    "vue-router": "catalog:",
+    "vue-tsc": "catalog:"
+  }
+}

package/skills/README.md

@@ -0,0 +1,78 @@
+# @manohub/kit 技能包（随包分发）
+
+本目录是随 npm 包一起发布的 AI 代理技能包，供**消费方**（接入了本包的子应用工程）使用。
+
+契约条款的唯一事实源是包内 `CONTRACT.md`。技能只负责**按场景把代理导到正确的流程与查表入口**。
+
+## 技能里为什么不写条款
+
+`CONTRACT.md` 是唯一的合规判据，它有两条性质：
+
+1. **每条条款都是闭集** —— 白名单（如 L1-5 的属性白名单）或逐字清单（如 L3-1 的允许 import 源），
+   看一眼就能判定「符合 / 不符合」，不需要解释。
+2. **§7 配了一份自检清单** —— 全是能直接回答的问句，收工前逐条过一遍即可。
+
+所以技能里的**条款式描述一律算缺陷**：它必然与契约漂移，而契约才是唯一裁判。技能只写两件事 ——
+**「读契约第 X 节」** 与 **「过 §7 自检清单」**。
+
+## 三个技能
+
+| 技能 | 职责 | 可独立调用 |
+|---|---|---|
+| `kit` | 入口编排：识别意图 → 调 `kit-migrate` 或 `kit-dev`（另有「从零建新应用」导到接入 SOP）；承载跨场景硬约束 | 是（子技能也可直接调） |
+| `kit-migrate` | 存量应用改造到「`@manohub/ui` 组件 + `@manohub/kit` 骨架」（清理 `App*` 旧组件名、`.ak-*` 样式、直连底层组件库的写法）：按契约逐层盘点 → 划批次 → 逐文件替换 → 逐层收口 → 验收；支持**只迁一部分**（典型是「只迁页面骨架」） | 是 |
+| `kit-dev` | 按骨架层规范做日常页面开发：选模板 / 选组件与 prop / 守样式纪律 / 缺件处置 / 自检 | 是 |
+
+## 安装到消费方技能目录
+
+在消费方**工程根**执行（缺省落 `.codebuddy/skills/`）；`kit` 是本包的命令入口（`bin`），
+npm 消费方把 `pnpm exec` 换成 `npx`：
+
+```bash
+pnpm exec kit install
+
+pnpm exec kit install --also-claude   # 同时落 .claude/skills/
+pnpm exec kit install --target .x/skills
+pnpm exec kit install --dry-run       # 只预览不落盘
+```
+
+输出示例（每个技能都会报告内容有没有变）：
+
+```text
+[kit 技能安装]
+  源：…/node_modules/@manohub/kit/skills
+  目标：…/.codebuddy/skills
+    ….codebuddy/skills/kit —— 更新 2（共 3 个文件）
+    ….codebuddy/skills/kit-migrate —— 已是包内最新（内容无变化，共 3 个文件）
+  完成：技能目录已与包内内容对齐（包升级后重跑本命令即刷新）
+```
+
+安装器是幂等的：每次执行**先清理同名技能目录再整体复制**，所以包升级后重跑一次即刷新到新版内容。
+等价写法（老脚本/钩子里可用）：`node node_modules/@manohub/kit/skills/install.mjs`。
+它只管理 `kit` / `kit-migrate` / `kit-dev` 这三个目录，不触碰目标目录下的其它内容。
+每次执行都会报告**技能内容有没有变**（「更新 N / 新增 N」＝本次升级改了技能、已生效；
+「已是包内最新」＝本次升级没动技能包），这样消费方不必靠猜「我的技能是不是旧的」。
+
+## 维护约定（改本目录时遵守）
+
+- 引用规范一律写**消费方视角**路径：`node_modules/@manohub/kit/CONTRACT.md` §x.y。
+  禁止出现本机绝对路径、worktree 路径、仓库内相对路径（技能落盘后与包目录分离，这些路径会失效）。
+- **不复述条款**：不抄白名单、不抄件名清单、不抄 prop 词表、不抄值。
+  需要时写「读契约 §x.y」或指向读取路径（见契约 §0 权威源表）。凡本目录内出现判据式描述，视为缺陷。
+- `SKILL.md` 只放流程与硬约束（控制在 5k 词内）；查表内容（替换映射、场景配方）放各自的 `references/`，按需加载。
+- 三个技能的 `description` 触发条件互不重叠，否则代理会命中错的那个
+  （`kit` 只在「意图还没落到具体任务」时命中，具体任务交给两个子技能）。
+- 技能引用的 `references/` 文件必须真实存在，文件名改动要同步 `SKILL.md`
+  （已由 `verify-pack` 的 `checkSkillPack` 机械校验，跨技能引用 `../<skill>/references/…` 同样校验）。
+- 技能目录下的每个文件都必须真进 tarball（`references/` 漏发时「查表」会整体失效，也已机械校验）。
+- 技能引用的契约章节必须真实存在（改契约标题即需同步本目录，`verify-pack` 会校验章节号可解析）。
+- 技能与文档里的命令一律写**消费方命令** `pnpm exec kit install`（npm 注一句 `npx`）。
+- 本包**只有 `install` 一个子命令**（0.6.0 起 `kit lint` 及其四个校验子命令已下线）。
+  `bin/` 是工具脚本、没有自测，改后手工跑一次确认参数透传（如 `--dry-run`），
+  `verify-pack` 校验 `bin/kit.mjs` 随包分发。
+- 改动后跑门禁与打包校验（在仓库根）：
+
+```bash
+pnpm --filter @manohub/kit test:unit   # 入口编排契约单测
+pnpm release:check                         # build + verify-pack（含技能包结构/引用校验）
+```