@aiti-ai/aiti-app-center 0.2.10 → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,39 +1,35 @@
1
1
  # @aiti-ai/aiti-app-center
2
2
 
3
- > 左栏区块栈全部折叠后空白态的应用抽屉(开始菜单)——应用视图(动作/面板/管理入口卡,hover 快捷钉 + 信息页)与开关视图(feature 开关按扩展分组)双视图单行切换,tag 式分类(内部固定分类多语 + 自定义分类 + 默认 other)、按视图搜索、编辑模式排序/隐藏/恢复
3
+ > The app drawer (start menu) shown in the blank state after every left-column dock block is collapsed — a single-row switch between the Apps view (action/panel/manage entry cards, hover quick-pin + info page) and the Toggles view (feature toggles grouped by extension), tag-style categories (8 fixed internal categories with i18n + custom categories + default other), search scoped per view, and edit-mode reorder/hide/restore
4
4
 
5
- ## 来源 · Origin
5
+ English · [简体中文](./README.zh-CN.md)
6
6
 
7
- 本包是 **aiti** 生态的组成部分——以 [pi](https://pi.dev) 为引擎的个人 AI 开发工作台与本地调试注入生态:**aiti-agent**(自托管 Web 工作台,基于开源项目 [pi-web](https://github.com/aiti-ai/pi-web) 构建,浏览器为主操作面)+ 各开发工具内的调试注入(aiti-devtools)+ 丰富的扩展体系。
7
+ ## About aiti
8
8
 
9
9
  This package is part of the **aiti** ecosystem — a personal AI development workbench powered by [pi](https://pi.dev): **aiti-agent** (a self-hosted web workbench built on the open-source [pi-web](https://github.com/aiti-ai/pi-web)) plus debug injection into mainstream dev tools (aiti-devtools) and a rich extension system.
10
10
 
11
- - 工作台 / workbench: <https://github.com/aiti-ai/pi-web>
12
- - 生态仓库 / monorepo: <https://github.com/aiti-ai/aiti-ai>
13
- - 官网 / site: <https://aiti.pw>
11
+ - Workbench (aiti-agent, built on pi-web): <https://github.com/aiti-ai/pi-web>
12
+ - Ecosystem monorepo: <https://github.com/aiti-ai/aiti-ai>
13
+ - Site: <https://aiti.pw>
14
14
 
15
- ## 功能定位(中文)
15
+ Category: System & admin · Tags: `app-center` · `launcher` · `start-menu` · `dock` · `spacer` · `category` · `apps`
16
16
 
17
- 左栏区块栈全部折叠后空白态的应用抽屉(开始菜单)——应用视图(动作/面板/管理入口卡,hover 快捷钉 + 信息页)与开关视图(feature 开关按扩展分组)双视图单行切换,tag 式分类(内部固定分类多语 + 自定义分类 + 默认 other)、按视图搜索、编辑模式排序/隐藏/恢复
17
+ ## Extension authors
18
18
 
19
- 系统与管理 · tags: `app-center` · `launcher` · `start-menu` · `dock` · `spacer` · `category` · `apps`
19
+ - **Commands are entries**: an item registered in the `commands` slot (with `meta.onClick` + `icon`) shows up in the App Center **and** in the composer's command suggestions — e.g. "Select model" / "Compact context" (registered by `aiti-ai-input`) let users finish work without leaving the input box.
20
+ - **Keywords are self-declared**: put search vocabulary on the item (`meta.keywords`) or on the extension (`keywords` in `index.ts`, passed through the manifest). The app center only falls back to its legacy override table — new extensions must never be added there. Extension-level keywords apply to every card, so command aliases belong on the item.
20
21
 
21
- ## Positioning (English)
22
+ ## Install
22
23
 
23
- The app drawer (start menu) shown in the blank state after every left-column dock block is collapsed — a single-row switch between the Apps view (action/panel/manage entry cards, hover quick-pin + info page) and the Toggles view (feature toggles grouped by extension), tag-style categories (8 fixed internal categories with i18n + custom categories + default other), search scoped per view, and edit-mode reorder/hide/restore
24
+ Bundled with **aiti-agent** (`@aiti-ai/pi-web`) — enable it from the in-app extension manager (ExtMan / App Center).
24
25
 
25
- ## 安装 / 部署
26
+ Manual install: place this package at `~/.pi/web/extensions/aiti-app-center/` and reload pi-web.
26
27
 
27
- ```bash
28
- node pi-web-ext/aiti-app-center/tools/deploy.mjs # 双实例部署 + reload;
29
- # 消费方 session-manager(optionalDependsOn 软依赖)经 aiti-app-center.api 服务渲染进 DockStack filler
30
- ```
28
+ ## Documentation
31
29
 
32
- ## 文档 · Documentation
33
-
34
- - 中文完整文档(aiti-docs): <https://aiti.pw/extensions/aiti-app-center.html>
35
- - English docs: <https://aiti.pw/en/extensions/aiti-app-center.html>
36
- - 扩展注册表 / registry: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>
30
+ - Documentation (English): <https://aiti.pw/en/extensions/aiti-app-center.html>
31
+ - 文档(中文): <https://aiti.pw/extensions/aiti-app-center.html>
32
+ - Extension registry: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>
37
33
 
38
34
  ## License
39
35
 
@@ -0,0 +1,36 @@
1
+ # @aiti-ai/aiti-app-center
2
+
3
+ > 左栏区块栈全部折叠后空白态的应用抽屉(开始菜单)——应用视图(动作/面板/管理入口卡,hover 快捷钉 + 信息页)与开关视图(feature 开关按扩展分组)双视图单行切换,tag 式分类(内部固定分类多语 + 自定义分类 + 默认 other)、按视图搜索、编辑模式排序/隐藏/恢复
4
+
5
+ [English](./README.md) · 简体中文
6
+
7
+ ## 关于 aiti
8
+
9
+ 本包是 **aiti** 生态的组成部分——以 [pi](https://pi.dev) 为引擎的个人 AI 开发工作台与本地调试注入生态:**aiti-agent**(自托管 Web 工作台,基于开源项目 [pi-web](https://github.com/aiti-ai/pi-web) 构建,浏览器为主操作面)+ 各开发工具内的调试注入(aiti-devtools)+ 丰富的扩展体系。
10
+
11
+ - 工作台(aiti-agent,基于 pi-web): <https://github.com/aiti-ai/pi-web>
12
+ - 生态仓库: <https://github.com/aiti-ai/aiti-ai>
13
+ - 官网: <https://aiti.pw>
14
+
15
+ 分类: 系统与管理 · tags: `app-center` · `launcher` · `start-menu` · `dock` · `spacer` · `category` · `apps`
16
+
17
+ ## 扩展作者须知
18
+
19
+ - **命令即条目**:注册在 `commands` 命令目录槽的条目(带 `meta.onClick` + `icon`)会同时出现在应用中心**和**输入框的命令联想里——例如「选择模型」「压缩上下文」(由 `aiti-ai-input` 注册),用户不离开输入框就能完成操作。
20
+ - **关键词自声明**:搜索词写在条目 `meta.keywords` 或扩展顶层 `keywords`(`index.ts`,经 manifest 透传)。应用中心只对存量扩展兜底覆盖表——新扩展严禁再加表。扩展级关键词对该扩展所有卡片生效,命令别名请放条目级。
21
+
22
+ ## 安装
23
+
24
+ 随 **aiti-agent**(`@aiti-ai/pi-web`)捆绑发行——在工作台内的扩展管理器(ExtMan / 应用中心)启用即可。
25
+
26
+ 手动安装:把本包放到 `~/.pi/web/extensions/aiti-app-center/` 后 reload。
27
+
28
+ ## 文档
29
+
30
+ - 中文文档: <https://aiti.pw/extensions/aiti-app-center.html>
31
+ - Documentation (English): <https://aiti.pw/en/extensions/aiti-app-center.html>
32
+ - 扩展注册表: <https://aiti.pw/extensions.html> · machine-readable <https://aiti.pw/extensions.json>
33
+
34
+ ## 许可证
35
+
36
+ MIT
@@ -5,23 +5,25 @@
5
5
  * DockStack 的 spacer(全部区块折叠时才存在——任一展开自动让位,零显隐状态)。
6
6
  * React 原语 = 宿主单实例(host-shim 委托 ctx;跨 bundle 组件工厂与 DockStack 服务同模式)。
7
7
  *
8
- * 布局(v2 视图分置,不占行):
9
- * 搜索行 = 搜索框(flex:1)+ ✏️ 编辑 / + 扩展管理 / ⇄ 视图切换(28px 方形图标按钮)
8
+ * 布局(v2 视图分置,不占行;v3.1 单滚动体):
9
+ * header 插槽 = 快速上手卡(session-manager 传入,随内容滚动)
10
+ * 搜索行(sticky 顶吸)= 搜索框(flex:1)+ ✏️ 编辑 / + 扩展管理 / ⇄ 视图切换(28px 方形图标按钮)
10
11
  * · 应用视图(默认):可执行入口(action/panel/manage)
11
12
  * flat(可见应用 ≤ FLAT_MODE_THRESHOLD)按分类平铺;否则「常用(钉住序)+ 更多(分类 chips + 网格)」
12
13
  * 开关视图:toggle 按来源扩展分组的行式开关(不钉不隐藏)
13
14
  * 卡片操作:非编辑态 hover(触屏常显)= ☆ 快捷钉拔 + ? 信息页;编辑态追加 ✕ 隐藏、钉住区 ▲▼
14
15
  * 信息页:来源扩展(名/id/版本/描述)+ 功能说明 + 钉住/隐藏 + 该扩展开关直切 + 一键禁用(状态机)+ 打开扩展管理
15
16
  */
16
- import { useState, useEffect, useMemo, useRef, apiUrl, t } from "./host-shim";
17
+ import { useState, useEffect, useLayoutEffect, useCallback, useMemo, useRef, apiUrl, t } from "./host-shim";
17
18
  import {
18
- buildApps, matchApp, viewMode, moreExpandedDefault, categoryLabel, categorySortKey,
19
+ buildApps, matchApp, viewMode, categoryLabel, categorySortKey,
19
20
  splitByKind, extensionToggleGroups, hardDependents, disableExtension, isToggleId,
20
21
  readPinned, readHidden, togglePinned, toggleHidden, hideApp, movePinned, pruneToggleIds,
21
- setBooleanFeature, APP_STORE_EVENT,
22
+ setBooleanFeature, APP_STORE_EVENT, currentUiLocale,
23
+ MORE_COLLAPSE_PINNED_ROWS, PINNED_CARD_MIN, PINNED_COL_GAP, pinnedRowsNeeded,
22
24
  type AppDescriptor, type ToggleGroup,
23
25
  } from "./app-registry";
24
- import { present, presentState, dockPref } from "../../../_shared/ext-float-dock-core";
26
+ import { openPanel } from "./commands";
25
27
 
26
28
  /** 触屏(无 hover):卡片右上角 ☆/? 常显(方案 §5.2)。 */
27
29
  const IS_TOUCH = typeof matchMedia === "function" && matchMedia("(hover: none)").matches;
@@ -32,19 +34,7 @@ const DISABLE_PROTECT: Record<string, string> = {
32
34
  "aiti-extman": "info.disableManager",
33
35
  };
34
36
 
35
- /** 面板打开原语:已停靠 → 原位激活(ACTIVATE 置前);有偏好 → 落偏好位;否则右栏 tab(dock 面板的宿命位)。 */
36
- function openPanel(key: string): void {
37
- try {
38
- const cur = presentState(key);
39
- if (cur.startsWith("docked:")) {
40
- const zone = cur.slice("docked:".length);
41
- if (zone) { present(key, `dock:${zone}`); return; }
42
- }
43
- const pref = dockPref(key);
44
- if (pref && pref !== "float") { present(key, `dock:${pref}`); return; }
45
- present(key, "dock:right-panel");
46
- } catch { /* ignore */ }
47
- }
37
+ /** 面板打开原语 openPanel 上提至 ./commands(应用命令提示服务同源消费;本组件改 import)。 */
48
38
 
49
39
  /** manifest 一次拉取(304 缓存同宿主);refresh = 禁用后重拉(nonce 变更触发 effect,非轮询)。 */
50
40
  function useManifestExts(): { exts: Array<Record<string, any>>; refresh: () => void } {
@@ -61,6 +51,32 @@ function useManifestExts(): { exts: Array<Record<string, any>>; refresh: () => v
61
51
  return { exts, refresh: () => setNonce((n) => n + 1) };
62
52
  }
63
53
 
54
+ /** Pinyin index (extman server /status enrichment: "full-pinyin concatenated + initials") — used as
55
+ * search hay; silent degradation on fetch failure (no pinyin search).
56
+ * Cross-extension dependency: same precedent as extman's ops API (the toggle switch uses it too);
57
+ * without extman only pinyin capability is lost. */
58
+ function usePinyinMap(): Record<string, string> {
59
+ const [map, setMap] = useState<Record<string, string>>({});
60
+ useEffect(() => {
61
+ let alive = true;
62
+ fetch(apiUrl("/api/extensions/aiti-extman/status"))
63
+ .then((r) => r.json())
64
+ .then((d) => {
65
+ if (!alive) return;
66
+ const next: Record<string, string> = {};
67
+ const exts = d?.extensions ?? {};
68
+ for (const id of Object.keys(exts)) {
69
+ const p = exts[id]?.pinyin;
70
+ if (typeof p === "string" && p) next[id] = p;
71
+ }
72
+ setMap(next);
73
+ })
74
+ .catch(() => { /* extman absent/failed → no pinyin, silent */ });
75
+ return () => { alive = false; };
76
+ }, []);
77
+ return map;
78
+ }
79
+
64
80
  /** feature 态本地覆盖层:extman 广播(含本扩展自己 set-feature 后补发的同款事件)→ 原地 patch,不重拉 manifest。 */
65
81
  function useFeatureOverlay(): { overlay: Record<string, boolean>; dropExt: (extId: string) => void } {
66
82
  const [overlay, setOverlay] = useState<Record<string, boolean>>({});
@@ -154,6 +170,20 @@ const miniBtn = (active?: boolean, danger?: boolean) => ({
154
170
  color: danger ? "var(--text-dim, #888)" : active ? "var(--accent, #2563eb)" : "var(--text-muted, #888)",
155
171
  } as const);
156
172
 
173
+ /** Bare corner badge (no chip background) — small glyph buttons on one line. */
174
+ const cardOpsBtn = (active?: boolean, danger?: boolean) => ({
175
+ width: 16, height: 16, display: "inline-flex", alignItems: "center", justifyContent: "center",
176
+ border: "none", borderRadius: 4, padding: 0, cursor: "pointer",
177
+ fontFamily: "inherit", fontSize: 10, lineHeight: 1, background: "transparent",
178
+ color: danger ? "var(--text-dim, #888)" : active ? "var(--accent, #2563eb)" : "var(--text-muted, #999)",
179
+ } as const);
180
+ const badgeHover = {
181
+ onMouseEnter: (e: any) => { e.currentTarget.style.color = "var(--accent, #2563eb)"; },
182
+ onMouseLeave: (e: any) => { e.currentTarget.style.color = ""; },
183
+ };
184
+ /* Offset from cell edge to the centered 52px icon tile corner (+2px inset). */
185
+ const iconCornerInset = "calc((100% - 52px) / 2 + 2px)";
186
+
157
187
  /** 搜索行右侧紧凑图标按钮(28px 方形,不占额外行)。 */
158
188
  function HeaderButton(props: { title: string; onClick: () => void; active?: boolean; children: any }) {
159
189
  const { title, onClick, active, children } = props;
@@ -207,22 +237,31 @@ function AppCard(props: {
207
237
  {app.label}
208
238
  </span>
209
239
  {showOps ? (
210
- <span style={{ position: "absolute", top: -6, right: -2, display: "flex", gap: 2, zIndex: 2 }}>
240
+ <span style={{ position: "absolute", top: 2, left: iconCornerInset, display: "flex", alignItems: "center", gap: 2, zIndex: 2 }}>
211
241
  <button type="button" title={pinned ? t("app.unpin") : t("app.pin")} aria-label={pinned ? t("app.unpin") : t("app.pin")}
212
- style={miniBtn(pinned)}
213
- onClick={() => togglePinned(app.id)}>{pinned ? "★" : "☆"}</button>
242
+ style={cardOpsBtn(pinned)} {...badgeHover}
243
+ onClick={() => togglePinned(app.id)}>
244
+ <svg width={10} height={10} viewBox="0 0 24 24" fill={pinned ? "currentColor" : "none"} stroke="currentColor"
245
+ strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
246
+ <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2" />
247
+ </svg>
248
+ </button>
214
249
  {edit ? (
215
- <button type="button" title={t("app.hide")} aria-label={t("app.hide")} style={miniBtn(false, true)}
250
+ <button type="button" title={t("app.hide")} aria-label={t("app.hide")} style={cardOpsBtn(false, true)} {...badgeHover}
216
251
  onClick={() => hideApp(app.id)}>✕</button>
217
252
  ) : null}
218
- <button type="button" title={t("info.title")} aria-label={t("info.title")} style={miniBtn(infoActive)}
253
+ </span>
254
+ ) : null}
255
+ {showOps ? (
256
+ <span style={{ position: "absolute", top: 2, right: iconCornerInset, display: "flex", alignItems: "center", zIndex: 2 }}>
257
+ <button type="button" title={t("info.title")} aria-label={t("info.title")} style={cardOpsBtn(infoActive)} {...badgeHover}
219
258
  onClick={() => onInfo(app)}>?</button>
220
259
  </span>
221
260
  ) : null}
222
261
  {edit && pinned && onMove ? (
223
- <span style={{ position: "absolute", top: -6, left: -2, display: "flex", gap: 2, zIndex: 2 }}>
224
- <button type="button" title={t("app.up")} aria-label={t("app.up")} style={miniBtn()} onClick={() => onMove(app.id, -1)}>▲</button>
225
- <button type="button" title={t("app.down")} aria-label={t("app.down")} style={miniBtn()} onClick={() => onMove(app.id, 1)}>▼</button>
262
+ <span style={{ position: "absolute", top: 32, right: iconCornerInset, display: "flex", gap: 2, zIndex: 2 }}>
263
+ <button type="button" title={t("app.up")} aria-label={t("app.up")} style={cardOpsBtn()} {...badgeHover} onClick={() => onMove(app.id, -1)}>▲</button>
264
+ <button type="button" title={t("app.down")} aria-label={t("app.down")} style={cardOpsBtn()} {...badgeHover} onClick={() => onMove(app.id, 1)}>▼</button>
226
265
  </span>
227
266
  ) : null}
228
267
  </div>
@@ -230,7 +269,8 @@ function AppCard(props: {
230
269
  }
231
270
 
232
271
  const sectionHead = { fontSize: 10, fontWeight: 600, color: "var(--text-dim, #888)", letterSpacing: "0.05em", textTransform: "uppercase" as const, padding: "2px 2px 0", userSelect: "none" as const };
233
- const gridStyle = { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(64px, 1fr))", gap: "10px 6px", width: "100%" } as const;
272
+ /* 卡片网格:列数推导(pinnedGridColumns/pinnedRowsNeeded)与本表 minmax/列距同源(PINNED_CARD_MIN/PINNED_COL_GAP),勿单边改 */
273
+ const gridStyle = { display: "grid", gridTemplateColumns: `repeat(auto-fill, minmax(${PINNED_CARD_MIN}px, 1fr))`, gap: `10px ${PINNED_COL_GAP}px`, width: "100%" } as const;
234
274
  const chipBtn = {
235
275
  display: "inline-flex", alignItems: "center", gap: 4, alignSelf: "flex-start",
236
276
  background: "none", border: "1px solid var(--border, #3a3a3a)", borderRadius: 7,
@@ -414,13 +454,25 @@ function InfoSheet(props: {
414
454
  );
415
455
  }
416
456
 
417
- /** 应用中心主组件(ctx = 宿主扩展 ctx;useSlotItems 为宿主真 hook,须在渲染体内调用)。 */
418
- export function AppCenter(props: { ctx: Record<string, any> }) {
419
- const { ctx } = props;
457
+ /** 应用中心主组件(ctx = 宿主扩展 ctx;useSlotItems 为宿主真 hook,须在渲染体内调用)。
458
+ * header(v3.1):可选顶部插槽(session-manager filler 传入快速上手卡)——随内容滚动,
459
+ * 搜索行 sticky 顶吸:快速上手滚出视口后搜索行钉在滚动体顶部。 */
460
+ export function AppCenter(props: { ctx: Record<string, any>; header?: any }) {
461
+ const { ctx, header } = props;
420
462
  // 插槽枚举(三槽均非交互槽——宿主 AppShell 启动即读,懒扩展以静态条目+转发器出现,零额外拉取)
421
463
  const toolbarItems = (ctx.useSlotItems as (s: string) => any[])?.("toolbar") ?? [];
464
+ const commandItems = (ctx.useSlotItems as (s: string) => any[])?.("commands") ?? []; // 命令目录槽(无渲染点纯命令,方案 §9)
422
465
  const footerItems = (ctx.useSlotItems as (s: string) => any[])?.("sidebarFooter") ?? [];
423
466
  const rightDockItems = (ctx.useSlotItems as (s: string) => any[])?.("rightFileDock") ?? [];
467
+ // UI locale:静态条目的 "i18n:" 标签解析在 buildApps 内按 locale 出成品文案;宿主
468
+ // useSlotItems 在 locale 切换时数组身份不变(store version 不 bump),须自行订阅
469
+ // locale 变更事件重算(宿主 ExtSlots.LOCALE_CHANGED_EVENT,跨边界字符串约定)。
470
+ const [locale, setLocale] = useState(currentUiLocale);
471
+ useEffect(() => {
472
+ const on = () => setLocale(currentUiLocale());
473
+ window.addEventListener("pi-web:locale-changed", on);
474
+ return () => window.removeEventListener("pi-web:locale-changed", on);
475
+ }, []);
424
476
  const { exts, refresh: refreshManifest } = useManifestExts();
425
477
  const { overlay: featureOverlay, dropExt: dropFeatureOverlay } = useFeatureOverlay();
426
478
  // 一次性本地迁移(P0-2):prune 必须先于两个数组的读取——useState 初始化器按声明序在首帧执行。
@@ -435,13 +487,33 @@ export function AppCenter(props: { ctx: Record<string, any> }) {
435
487
  const [query, setQuery] = useState("");
436
488
  const [edit, setEdit] = useState(false);
437
489
  const [view, setView] = useState<"apps" | "toggles">("apps");
438
- const [moreOpen, setMoreOpen] = useState<boolean>(() => moreExpandedDefault(readPinned().length));
490
+ const [moreOpen, setMoreOpen] = useState(true); // 首帧先展开;收起由下方 layout effect 按实测宽度在 paint 前决定
439
491
  const [selectedCat, setSelectedCat] = useState<string>("__all");
440
492
  const [infoId, setInfoId] = useState<string | null>(null);
441
493
  const [disable, setDisable] = useState<{ confirm: boolean; busy: boolean; error: string | null }>({ confirm: false, busy: false, error: null });
442
494
  const [removedExts, setRemovedExts] = useState<string[]>([]);
443
495
  const [notice, setNotice] = useState<string | null>(null);
496
+ const pinyinMap = usePinyinMap();
444
497
  const scrollRef = useRef<HTMLDivElement | null>(null);
498
+ // 滚动体内容宽(v3.2):ResizeObserver 事件驱动测量(非轮询),供「更多」行数自适应。
499
+ // clientWidth 含 padding——扣除实测左右 padding 得内容盒宽(= 卡片网格实际可用宽度)。
500
+ const [contentWidth, setContentWidth] = useState(0);
501
+ const bodyRoRef = useRef<ResizeObserver | null>(null);
502
+ const attachBody = useCallback((el: HTMLDivElement | null) => {
503
+ scrollRef.current = el;
504
+ bodyRoRef.current?.disconnect();
505
+ bodyRoRef.current = null;
506
+ if (el && typeof ResizeObserver !== "undefined") {
507
+ const measure = () => {
508
+ const cs = getComputedStyle(el);
509
+ setContentWidth(el.clientWidth - parseFloat(cs.paddingLeft || "0") - parseFloat(cs.paddingRight || "0"));
510
+ };
511
+ const ro = new ResizeObserver(measure);
512
+ ro.observe(el); // observe 即触发首次回调(异步);下方同步先测一次供首帧 layout effect 用
513
+ bodyRoRef.current = ro;
514
+ measure();
515
+ }
516
+ }, []);
445
517
 
446
518
  const featureState = useMemo(() => {
447
519
  const m: Record<string, boolean> = {};
@@ -453,12 +525,15 @@ export function AppCenter(props: { ctx: Record<string, any> }) {
453
525
  exts: exts as any,
454
526
  slotItems: [
455
527
  ...toolbarItems.map((it: any) => ({ ...it, slot: "toolbar" as const })),
528
+ ...commandItems.map((it: any) => ({ ...it, slot: "commands" as const })),
456
529
  ...footerItems.map((it: any) => ({ ...it, slot: "sidebarFooter" as const })),
457
530
  ...rightDockItems.map((it: any) => ({ ...it, slot: "rightFileDock" as const })),
458
531
  ],
459
532
  featureState,
460
533
  openPanel,
461
- }), [toolbarItems, footerItems, rightDockItems, exts, featureState]);
534
+ locale,
535
+ pinyinMap,
536
+ }), [toolbarItems, commandItems, footerItems, rightDockItems, exts, featureState, locale, pinyinMap]);
462
537
 
463
538
  // 禁用成功 = 乐观移除该扩展全部四类卡(不依赖宿主 store 更新时序;reload 后插槽卡自然消失)
464
539
  const apps = useMemo(() => (removedExts.length === 0 ? builtApps : builtApps.filter((a) => !removedExts.includes(a.extId))), [builtApps, removedExts]);
@@ -474,17 +549,18 @@ export function AppCenter(props: { ctx: Record<string, any> }) {
474
549
  const infoToggles = useMemo(() => (infoApp ? toggles.filter((a) => a.extId === infoApp.extId) : []), [infoApp, toggles]);
475
550
  const infoDependents = useMemo(() => (infoApp ? hardDependents(exts as any, infoApp.extId) : []), [infoApp, exts]);
476
551
 
477
- // 形态判断用「实际可见钉住数」(P0-2 双保险):钉住数组可能含已隐藏/已消失的 id。
478
- // 只在此处「展开」修正(数据迟到后才发现无可见钉住)——收起只发生在下次打开,
479
- // 用户当场 hover 钉住不打断「更多」浏览(§2)。
480
- const pinnedSeenRef = useRef(pinnedApps.length > 0);
481
- useEffect(() => {
482
- if (apps.length === 0) return;
483
- const has = pinnedApps.length > 0;
484
- if (has === pinnedSeenRef.current) return;
485
- pinnedSeenRef.current = has;
486
- if (!has) setMoreOpen(true);
487
- }, [pinnedApps.length, apps.length]);
552
+ // 「更多」默认形态(v3.2 宽度自适应):钉住区已占满的整行数(按容器内容宽推导列数,末行未占满不计)不足
553
+ // MORE_COLLAPSE_PINNED_ROWS → 自动展开全部;占满 ≥ 阈值整行才默认收起。
554
+ // 收起只发生在挂载首帧(layout effect,paint 前生效无跳动)与下次打开(重挂载重算);
555
+ // 打开态变窄不打断浏览,仅在变宽腾出空间(行数降到阈值下)时即时展开。
556
+ const autoMoreRef = useRef<boolean | null>(null);
557
+ useLayoutEffect(() => {
558
+ if (apps.length === 0 && !header) return; // 数据未到不判定(钉住可能指向未建出的应用)
559
+ const auto = pinnedRowsNeeded(pinnedApps.length, contentWidth) < MORE_COLLAPSE_PINNED_ROWS;
560
+ const prev = autoMoreRef.current;
561
+ autoMoreRef.current = auto;
562
+ if (prev === null || (auto && prev === false)) setMoreOpen(auto);
563
+ }, [contentWidth, pinnedApps.length, apps.length, header]);
488
564
 
489
565
  const searching = query.trim().length > 0;
490
566
  const entryResults = useMemo(() => (searching ? visibleEntries.filter((a) => matchApp(a, query)) : []), [searching, visibleEntries, query]);
@@ -502,7 +578,7 @@ export function AppCenter(props: { ctx: Record<string, any> }) {
502
578
  }, [visibleEntries, pinnedApps, searching]);
503
579
 
504
580
  const mode = viewMode(visibleEntries.length);
505
- if (apps.length === 0) return null; // 无可收录入口 → spacer 保持空白(行为同未装)
581
+ if (apps.length === 0 && !header) return null; // 无可收录入口且无 header → spacer 保持空白(行为同未装)
506
582
 
507
583
  const onToggleFeature = (app: AppDescriptor) => {
508
584
  const featureId = app.id.slice(`toggle:${app.extId}:`.length);
@@ -559,42 +635,47 @@ export function AppCenter(props: { ctx: Record<string, any> }) {
559
635
 
560
636
  return (
561
637
  <div data-aiti-app-center="1" style={{ flex: 1, minHeight: 0, position: "relative", display: "flex", flexDirection: "column" }}>
562
- {/* 搜索行:搜索框吸收挤压 + 三枚方形图标按钮(不额外占行) */}
563
- <div style={{ display: "flex", alignItems: "center", gap: 5, flexShrink: 0, padding: "10px 12px 0" }}>
564
- <div style={{ flex: 1, minWidth: 0, display: "flex", alignItems: "center", gap: 6, background: "var(--bg-hover, #232323)", border: "1px solid var(--border, #3a3a3a)", borderRadius: 8, padding: "5px 9px" }}>
565
- <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" aria-hidden="true" style={{ color: "var(--text-dim, #888)", flexShrink: 0 }}>
566
- <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
567
- </svg>
568
- <input
569
- type="text"
570
- value={query}
571
- onChange={(e: any) => setQuery(e.target.value)}
572
- placeholder={t(view === "apps" ? "app.search" : "app.searchToggles")}
573
- aria-label={t(view === "apps" ? "app.search" : "app.searchToggles")}
574
- style={{ flex: 1, minWidth: 0, background: "none", border: "none", outline: "none", color: "var(--text, #ddd)", fontSize: 12, fontFamily: "inherit" }}
575
- />
576
- </div>
577
- {view === "apps" ? (
578
- <HeaderButton title={edit ? t("app.done") : t("app.edit")} active={edit} onClick={() => setEdit((v) => !v)}>
579
- <EditIcon />
638
+ {/* 单滚动体(v3.1):快速上手(header 插槽,session-manager filler 传入)随内容滚出视口,
639
+ 搜索行 sticky 顶吸——负 margin 全幅 + bg-panel 不透明背景盖住滚过内容;
640
+ InfoSheet top:48 与吸顶搜索行下沿对齐。
641
+ Render header directly: a dismissed guide returns null, so no empty flex item (and no
642
+ flex gap) is left above the sticky search row. */}
643
+ <div ref={attachBody} data-app-center-body="1" style={{ flex: 1, minHeight: 0, overflowY: "auto", overflowX: "hidden", padding: "0 12px 12px", display: "flex", flexDirection: "column", gap: 12 }}>
644
+ {header}
645
+ {/* 搜索行:搜索框吸收挤压 + 三枚方形图标按钮(不额外占行) */}
646
+ <div data-app-center-search="1" style={{ position: "sticky", top: 0, zIndex: 3, flexShrink: 0, display: "flex", alignItems: "center", gap: 5, margin: "0 -12px", padding: "10px 12px 8px", background: "var(--bg-panel, #1b1b1b)" }}>
647
+ <div style={{ flex: 1, minWidth: 0, display: "flex", alignItems: "center", gap: 6, background: "var(--bg-hover, #232323)", border: "1px solid var(--border, #3a3a3a)", borderRadius: 8, padding: "5px 9px" }}>
648
+ <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" aria-hidden="true" style={{ color: "var(--text-dim, #888)", flexShrink: 0 }}>
649
+ <circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" />
650
+ </svg>
651
+ <input
652
+ type="text"
653
+ value={query}
654
+ onChange={(e: any) => setQuery(e.target.value)}
655
+ placeholder={t(view === "apps" ? "app.search" : "app.searchToggles")}
656
+ aria-label={t(view === "apps" ? "app.search" : "app.searchToggles")}
657
+ style={{ flex: 1, minWidth: 0, background: "none", border: "none", outline: "none", color: "var(--text, #ddd)", fontSize: 12, fontFamily: "inherit" }}
658
+ />
659
+ </div>
660
+ {view === "apps" ? (
661
+ <HeaderButton title={edit ? t("app.done") : t("app.edit")} active={edit} onClick={() => setEdit((v) => !v)}>
662
+ <EditIcon />
663
+ </HeaderButton>
664
+ ) : null}
665
+ {extmanApp ? (
666
+ <HeaderButton title={t("view.extman")} onClick={openExtman}><PlusIcon /></HeaderButton>
667
+ ) : null}
668
+ <HeaderButton title={t(view === "apps" ? "view.toToggles" : "view.toApps")} onClick={switchView}>
669
+ {view === "apps" ? <SlidersIcon /> : <GridIcon />}
580
670
  </HeaderButton>
581
- ) : null}
582
- {extmanApp ? (
583
- <HeaderButton title={t("view.extman")} onClick={openExtman}><PlusIcon /></HeaderButton>
584
- ) : null}
585
- <HeaderButton title={t(view === "apps" ? "view.toToggles" : "view.toApps")} onClick={switchView}>
586
- {view === "apps" ? <SlidersIcon /> : <GridIcon />}
587
- </HeaderButton>
588
- </div>
589
-
590
- {notice ? (
591
- <div style={{ display: "flex", alignItems: "center", gap: 6, margin: "8px 12px 0", padding: "5px 8px", border: "1px solid var(--border, #3a3a3a)", borderRadius: 8, fontSize: 11, color: "var(--text-muted, #999)" }}>
592
- <span style={{ flex: 1, minWidth: 0 }}>{notice}</span>
593
- <button type="button" style={miniBtn()} title={t("info.close")} aria-label={t("info.close")} onClick={() => setNotice(null)}>✕</button>
594
671
  </div>
595
- ) : null}
596
672
 
597
- <div ref={scrollRef} data-app-center-body="1" style={{ flex: 1, minHeight: 0, overflowY: "auto", overflowX: "hidden", padding: "10px 12px 12px", display: "flex", flexDirection: "column", gap: 12 }}>
673
+ {notice ? (
674
+ <div style={{ display: "flex", alignItems: "center", gap: 6, padding: "5px 8px", border: "1px solid var(--border, #3a3a3a)", borderRadius: 8, fontSize: 11, color: "var(--text-muted, #999)" }}>
675
+ <span style={{ flex: 1, minWidth: 0 }}>{notice}</span>
676
+ <button type="button" style={miniBtn()} title={t("info.close")} aria-label={t("info.close")} onClick={() => setNotice(null)}>✕</button>
677
+ </div>
678
+ ) : null}
598
679
  {view === "toggles" ? (
599
680
  toggleGroups.length === 0 ? (
600
681
  <div style={{ fontSize: 12, color: "var(--text-dim, #888)", textAlign: "center", padding: "12px 0" }}>{t("app.noResults")}</div>
@@ -619,7 +700,7 @@ export function AppCenter(props: { ctx: Record<string, any> }) {
619
700
  ) : (
620
701
  <div style={{ fontSize: 11, color: "var(--text-dim, #888)", padding: "2px 2px" }}>{t("app.pinHint")}</div>
621
702
  )}
622
- {/* 更多(首次态默认展开;钉过默认收起;编辑态强制展开——hover 快捷钉不打断展开) */}
703
+ {/* 更多(钉住区占满 ≥ 2 行才默认收起——列数随宽度自适应;不足两行展开全部;编辑态强制展开——hover 快捷钉不打断展开) */}
623
704
  {moreOpen || edit ? (
624
705
  <div style={{ display: "flex", flexDirection: "column", gap: 10 }}>
625
706
  <div role="tablist" aria-label={t("app.more")} style={{ display: "flex", flexWrap: "wrap", gap: "5px 6px", flexShrink: 0 }}>
@@ -701,9 +782,10 @@ export function AppCenter(props: { ctx: Record<string, any> }) {
701
782
  );
702
783
  }
703
784
 
704
- /** 服务 API(aiti-app-center.api):跨 bundle 组件工厂,session-manager 编排器作 DockStack filler 消费。 */
785
+ /** 服务 API(aiti-app-center.api):跨 bundle 组件工厂,session-manager 编排器作 DockStack filler 消费。
786
+ * opts.header(v3.1):可选顶部插槽元素(如快速上手卡)——进滚动体随内容滚走,搜索行 sticky 顶吸。 */
705
787
  export function createAppCenterApi(ctx: Record<string, any>) {
706
788
  return {
707
- renderAppCenter: () => <AppCenter ctx={ctx} />,
789
+ renderAppCenter: (opts?: { header?: any }) => <AppCenter ctx={ctx} header={opts?.header} />,
708
790
  };
709
791
  }
@@ -29,8 +29,11 @@ const {
29
29
  categoryLabel,
30
30
  categorySortKey,
31
31
  viewMode,
32
- moreExpandedDefault,
32
+ MORE_COLLAPSE_PINNED_ROWS, PINNED_CARD_MIN, PINNED_COL_GAP, pinnedGridColumns, pinnedRowsNeeded,
33
33
  matchApp,
34
+ currentUiLocale,
35
+ i18nTableFor,
36
+ translateExtItemText,
34
37
  readPinned,
35
38
  writePinned,
36
39
  togglePinned,
@@ -71,11 +74,24 @@ test("categoryLabel / categorySortKey:内部 i18n、自定义原文、内部
71
74
  assert.ok(categorySortKey("other") < categorySortKey("我的工具"));
72
75
  });
73
76
 
74
- test("viewMode / moreExpandedDefault:形态自适应(v3)", () => {
77
+ test("viewMode / pinned rows:形态自适应(v3.2 宽度自适应收起)", () => {
75
78
  assert.equal(viewMode(FLAT_MODE_THRESHOLD), "flat");
76
79
  assert.equal(viewMode(FLAT_MODE_THRESHOLD + 1), "two-segment");
77
- assert.equal(moreExpandedDefault(0), true); // 首次态:更多展开
78
- assert.equal(moreExpandedDefault(3), false); // 已钉住:收起
80
+ // 列数 = auto-fill minmax(64,1fr)+6 列距推导:floor((W+6)/70);未测得宽度保守 1 列
81
+ assert.equal(PINNED_CARD_MIN, 64);
82
+ assert.equal(PINNED_COL_GAP, 6);
83
+ assert.equal(pinnedGridColumns(0), 1);
84
+ assert.equal(pinnedGridColumns(70), 1);
85
+ assert.equal(pinnedGridColumns(140), 2);
86
+ assert.equal(pinnedGridColumns(306), 4);
87
+ // 行数 = floor(count/cols)(整行占满口径,末行未占满不计);不足 MORE_COLLAPSE_PINNED_ROWS(2)整行 → 展开,≥ 2 整行 → 收起
88
+ assert.equal(pinnedRowsNeeded(0, 306), 0);
89
+ assert.equal(pinnedRowsNeeded(4, 306), 1); // 1 整行 → 展开(rows < 2)
90
+ assert.equal(pinnedRowsNeeded(5, 306), 1); // 第 2 行仅 1 个(未占满)→ 仍算 1 整行 → 展开
91
+ assert.equal(pinnedRowsNeeded(7, 306), 1); // 第 2 行 3/4 → 展开
92
+ assert.equal(pinnedRowsNeeded(8, 306), 2); // 两行全满 → 收起
93
+ assert.equal(pinnedRowsNeeded(9, 306), 2); // 2 整行 + 末行 1 个(不计)→ 收起
94
+ assert.ok(pinnedRowsNeeded(8, 306) >= MORE_COLLAPSE_PINNED_ROWS);
79
95
  });
80
96
 
81
97
  test("matchApp:多词 AND、大小写不敏感、覆盖 keywords", () => {
@@ -325,6 +341,89 @@ test("静态面板条目不进卡(声明标记打不中 dock key = 死卡)",
325
341
  assert.ok(apps.some((a) => a.label === "图片预览"), "动态面板卡保留");
326
342
  });
327
343
 
344
+ test("translateExtItemText:i18n: 前缀级联(当前 locale → 短码 → en → 首表)/缺键回退裸 key/无前缀透传", () => {
345
+ const ui18n = {
346
+ "zh-CN": { "ext.shortLabel": "扩展", "only.zh": "仅中文" },
347
+ en: { "ext.shortLabel": "Exts", "only.en": "EN only" },
348
+ };
349
+ assert.equal(translateExtItemText("aiti-extman", "i18n:ext.shortLabel", ui18n, "zh-CN"), "扩展");
350
+ assert.equal(translateExtItemText("aiti-extman", "i18n:ext.shortLabel", ui18n, "en"), "Exts");
351
+ // zh-TW:无 zh-TW 表 → zh-CN 兜底(同为 zh 语族;扩展只发 en + zh-CN)
352
+ assert.equal(translateExtItemText("aiti-extman", "i18n:ext.shortLabel", ui18n, "zh-TW"), "扩展");
353
+ // 命中表里缺键 → 裸 key(en 表命中但无 only.zh)
354
+ assert.equal(translateExtItemText("aiti-extman", "i18n:only.zh", ui18n, "en"), "only.zh");
355
+ // en 无表时末位兜底 = 首表(zh-CN)
356
+ const zhOnly = { "zh-CN": { "k": "只有中文" } };
357
+ assert.equal(translateExtItemText("x", "i18n:k", zhOnly, "en"), "只有中文");
358
+ // 短码表直接命中
359
+ const withZh = { ...ui18n, zh: { "zh.only": "短码命中" } };
360
+ assert.equal(translateExtItemText("x", "i18n:zh.only", withZh, "zh-TW"), "短码命中");
361
+ assert.deepEqual(i18nTableFor(withZh, "zh"), withZh.zh);
362
+ // 缺键 → 裸 key;缺表 → 裸 key
363
+ assert.equal(translateExtItemText("aiti-extman", "i18n:nope", ui18n, "zh-CN"), "nope");
364
+ assert.equal(translateExtItemText("aiti-extman", "i18n:ext.shortLabel", undefined, "zh-CN"), "ext.shortLabel");
365
+ // 无前缀 / 无 extId / 空文案
366
+ assert.equal(translateExtItemText("x", "普通文案", ui18n, "zh-CN"), "普通文案");
367
+ assert.equal(translateExtItemText(undefined, "i18n:ext.shortLabel", ui18n, "zh-CN"), "i18n:ext.shortLabel");
368
+ assert.equal(translateExtItemText("x", "", ui18n, "zh-CN"), "");
369
+ assert.equal(translateExtItemText("x", undefined, ui18n, "zh-CN"), "");
370
+ assert.deepEqual(i18nTableFor(undefined, "zh-CN"), {});
371
+ });
372
+
373
+ test("matchApp:拼音索引 + 连写宽松 + 错字容忍(extman 同款,2026-11-15 对齐)", () => {
374
+ const app = { label: "服务隧道", extId: "service-tunnels", extName: "Service Tunnels", keywords: [], pinyin: "fuwusuidao fst" };
375
+ assert.ok(matchApp(app, "fuwusuidao"), "全拼连写命中 pinyin hay");
376
+ assert.ok(matchApp(app, "fuwu suidao"), "拼音分词连写宽松(qNorm 去空格)");
377
+ assert.ok(matchApp(app, "fst"), "首字母命中");
378
+ assert.ok(matchApp(app, "fuwusuida"), "拼音尾字符缺失在错字容忍内(8字允1错)");
379
+ assert.ok(matchApp(app, "服务"), "中文词命中 label");
380
+ assert.ok(!matchApp(app, "helloworld"), "完全无关词不命中(错字容忍不误报)");
381
+ // cards without a pinyin field: concatenation/typo matching still applies to the rest of the hay (safe degradation)
382
+ const noPinyin = { label: "服务隧道", extId: "service-tunnels", extName: "Service Tunnels", keywords: [] };
383
+ assert.ok(matchApp(noPinyin, "servcie"), "错字容忍:英文 label 错字命中(无 pinyin 也可用)");
384
+ assert.ok(matchApp(noPinyin, "tunnels service"), "双语名分词 AND 命中");
385
+ });
386
+
387
+ test("currentUiLocale:pi-locale 读取 + 非法值/缺省回退 en", () => {
388
+ store.set("pi-locale", "zh-CN");
389
+ assert.equal(currentUiLocale(), "zh-CN");
390
+ store.set("pi-locale", "fr");
391
+ assert.equal(currentUiLocale(), "en");
392
+ store.delete("pi-locale");
393
+ assert.equal(currentUiLocale(), "en");
394
+ });
395
+
396
+ test("buildApps:静态条目 i18n: 标签解析(label 优先 title 兜底)+ toggle feature label + locale 参数", () => {
397
+ const exts = [
398
+ {
399
+ id: "extman", name: "ExtMan", category: "system",
400
+ ui: { i18n: { "zh-CN": { "ext.shortLabel": "扩展", "ext.title": "扩展管理" }, en: { "ext.shortLabel": "Exts" } } },
401
+ },
402
+ { id: "plain", features: [{ id: "f.on", label: "i18n:feat.on", enabled: true }] },
403
+ ];
404
+ exts[1].ui = { i18n: { "zh-CN": { "feat.on": "开关甲" }, en: { "feat.on": "Toggle A" } } };
405
+ const slotItems = [
406
+ { slot: "sidebarFooter", id: "extman:open", extId: "extman", meta: { label: "i18n:ext.shortLabel", onClick: () => {} } },
407
+ { slot: "toolbar", id: "extman:notitle", extId: "extman", meta: { title: "i18n:ext.title", onClick: () => {} } }, // 无 label → title 兑底
408
+ { slot: "toolbar", id: "extman:raw", extId: "extman", meta: { label: "原文案", onClick: () => {} } }, // 无前缀透传
409
+ ];
410
+ const zh = buildApps({ exts, slotItems, featureState: { "plain:f.on": true }, openPanel: () => {}, locale: "zh-CN" });
411
+ const byId = new Map(zh.map((a) => [a.id, a]));
412
+ assert.equal(byId.get("manage:extman:open").label, "扩展");
413
+ assert.equal(byId.get("action:extman:notitle").label, "扩展管理"); // label 缺 → title 译后兑底
414
+ assert.equal(byId.get("action:extman:raw").label, "原文案");
415
+ assert.equal(byId.get("toggle:plain:f.on").label, "开关甲");
416
+ const en = buildApps({ exts, slotItems, featureState: {}, openPanel: () => {}, locale: "en" });
417
+ const enById = new Map(en.map((a) => [a.id, a]));
418
+ assert.equal(enById.get("manage:extman:open").label, "Exts");
419
+ assert.equal(enById.get("action:extman:notitle").label, "ext.title"); // en 缺键 → 裸 key(与宿主同)
420
+ // 缺 locale 参数 → 现读 pi-locale(测试桩 localStorage)
421
+ store.set("pi-locale", "zh-CN");
422
+ const auto = buildApps({ exts, slotItems: [slotItems[0]], featureState: {}, openPanel: () => {} });
423
+ assert.equal(auto[0].label, "扩展");
424
+ store.delete("pi-locale");
425
+ });
426
+
328
427
  test("disableExtension:ops 请求形态 + HTTP 200 里的 body.error 也算失败", async () => {
329
428
  const calls = [];
330
429
  let next = { ok: true, status: 200, body: {} };