@aiti-ai/ext-shared 0.0.0-stage → 0.1.8

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.
Files changed (131) hide show
  1. package/LICENSE +21 -0
  2. package/agent-accounts.test.mjs +227 -0
  3. package/agent-accounts.ts +324 -0
  4. package/agent-capability-contract.test.mjs +129 -0
  5. package/agent-interaction.test.mjs +194 -0
  6. package/agent-interaction.ts +340 -0
  7. package/agent-launch.test.mjs +262 -0
  8. package/agent-spawn-env.test.mjs +169 -0
  9. package/agent-spawn-env.ts +548 -0
  10. package/aiti-editor-inject.mjs +49 -0
  11. package/backend-queue.test.mjs +336 -0
  12. package/backend-queue.ts +469 -0
  13. package/blob-save-route.ts +128 -0
  14. package/cbc-model-catalog.ts +86 -0
  15. package/check-client.mjs +273 -0
  16. package/check-ext-globals.mjs +144 -0
  17. package/controlled-login-dialog.mjs +270 -0
  18. package/controlled-login.mjs +398 -0
  19. package/controlled-login.test.mjs +466 -0
  20. package/convert-saveas.test.mjs +39 -0
  21. package/convert-saveas.ts +170 -0
  22. package/copy-client-bundle.mjs +39 -0
  23. package/cursor-cli-store.ts +377 -0
  24. package/dedupe-fetch.test.mjs +71 -0
  25. package/dedupe-fetch.ts +58 -0
  26. package/deploy-commit.mjs +52 -0
  27. package/dev-pack.mjs +246 -0
  28. package/dock-icons.ts +127 -0
  29. package/esbuild-bin.test.mjs +53 -0
  30. package/esbuild-bin.ts +66 -0
  31. package/exec-async.test.mjs +86 -0
  32. package/exec-async.ts +179 -0
  33. package/ext-display-names.ts +91 -0
  34. package/ext-entry-contracts.test.mjs +131 -0
  35. package/ext-float-dock-core.test.mjs +348 -0
  36. package/ext-float-dock-core.ts +783 -0
  37. package/ext-float-dock-lite.ts +52 -0
  38. package/ext-float-dock.test.mjs +286 -0
  39. package/ext-float-dock.ts +740 -0
  40. package/ext-icons-deploy.mjs +24 -0
  41. package/ext-lazy.test.mjs +186 -0
  42. package/ext-lazy.tsx +183 -0
  43. package/ext-model-state.test.mjs +272 -0
  44. package/ext-model-state.ts +324 -0
  45. package/ext-protocol.mjs +113 -0
  46. package/ext-protocol.test.mjs +88 -0
  47. package/ext-session-usage.test.mjs +219 -0
  48. package/ext-session-usage.ts +507 -0
  49. package/external-cli-governance.ts +153 -0
  50. package/git-ops-client/api.mjs +56 -0
  51. package/git-ops-client/branch-panel.tsx +987 -0
  52. package/git-ops-client/i18n.mjs +328 -0
  53. package/host-tools-allow.test.mjs +46 -0
  54. package/host-tools-allow.ts +84 -0
  55. package/icons/alert.svg +1 -0
  56. package/icons/bookmark.svg +1 -0
  57. package/icons/bot.svg +1 -0
  58. package/icons/chart-column.svg +1 -0
  59. package/icons/check-circle.svg +1 -0
  60. package/icons/clipboard-list.svg +1 -0
  61. package/icons/clock.svg +1 -0
  62. package/icons/coffee.svg +1 -0
  63. package/icons/edit.svg +1 -0
  64. package/icons/eye.svg +1 -0
  65. package/icons/git-branch.svg +1 -0
  66. package/icons/git-commit-horizontal.svg +1 -0
  67. package/icons/globe.svg +1 -0
  68. package/icons/history.svg +1 -0
  69. package/icons/import.svg +1 -0
  70. package/icons/inbox.svg +1 -0
  71. package/icons/key-round.svg +1 -0
  72. package/icons/layout-grid.svg +1 -0
  73. package/icons/mail.svg +1 -0
  74. package/icons/message-circle.svg +1 -0
  75. package/icons/message-square.svg +1 -0
  76. package/icons/meter-vertical.svg +1 -0
  77. package/icons/mic.svg +1 -0
  78. package/icons/monitor.svg +1 -0
  79. package/icons/pen-line.svg +1 -0
  80. package/icons/plug.svg +1 -0
  81. package/icons/radio-dot.svg +1 -0
  82. package/icons/radio.svg +1 -0
  83. package/icons/refresh.svg +1 -0
  84. package/icons/rocket.svg +1 -0
  85. package/icons/search.svg +1 -0
  86. package/icons/shield.svg +1 -0
  87. package/icons/sparkles.svg +1 -0
  88. package/icons/square-kanban.svg +1 -0
  89. package/icons/terminal.svg +1 -0
  90. package/icons/users.svg +1 -0
  91. package/icons/volume-2.svg +1 -0
  92. package/icons/wand.svg +1 -0
  93. package/icons/wrench.svg +1 -0
  94. package/icons/x-circle.svg +1 -0
  95. package/icons/x.svg +1 -0
  96. package/ignore-semantics.ts +76 -0
  97. package/lazy-loading-metrics.mjs +61 -0
  98. package/new-session-cwd.test.mjs +389 -0
  99. package/new-session-cwd.ts +253 -0
  100. package/open-viewer-window.ts +65 -0
  101. package/overlay-back-client.test.mjs +123 -0
  102. package/overlay-back-client.ts +87 -0
  103. package/package.json +65 -4
  104. package/pi-fork-rpc/README.md +12 -0
  105. package/pi-fork-rpc/cli-resolve.test.mjs +42 -0
  106. package/pi-fork-rpc/cli-resolve.ts +79 -0
  107. package/pi-fork-rpc/remote-queue.test.mjs +100 -0
  108. package/pi-fork-rpc/remote-queue.ts +140 -0
  109. package/pi-fork-rpc/spec.ts +106 -0
  110. package/pi-fork-rpc/wire.test.mjs +260 -0
  111. package/pi-fork-rpc/wire.ts +367 -0
  112. package/popup-anchor.ts +45 -0
  113. package/provider-priority-contract.test.mjs +55 -0
  114. package/reconcile-deps.mjs +41 -0
  115. package/reload-instances.mjs +60 -0
  116. package/seed-tool.test.mjs +95 -0
  117. package/seed-tool.ts +88 -0
  118. package/session-recycle.ts +109 -0
  119. package/shared-copy-sync.test.mjs +115 -0
  120. package/soffice-locate.ts +171 -0
  121. package/soffice-panel.ts +239 -0
  122. package/sync-dir.mjs +91 -0
  123. package/sync-dir.test.mjs +101 -0
  124. package/sync-gate.test.mjs +93 -0
  125. package/sync-mirror.test.mjs +85 -0
  126. package/task-list.test.mjs +91 -0
  127. package/task-list.ts +118 -0
  128. package/test-rm-rf.mjs +33 -0
  129. package/ui-dialogs.test.mjs +198 -0
  130. package/ui-dialogs.ts +310 -0
  131. package/README.md +0 -3
@@ -0,0 +1,548 @@
1
+ /**
2
+ * agent-spawn-env —— 可 spawn 外部 CLI 的 agent 扩展共享 spawn env 机制
3
+ *
4
+ * 权威源:pi-web-ext/_shared/agent-spawn-env.ts(改动后同步到各扩展目录副本)。
5
+ * 当前副本:aiti-{zcode,claude-code,codex,pi,acp,codebuddy,cursor,qoder}-agent/agent-spawn-env.ts
6
+ * 方案:docs/pi-web-ext-agent-spawn-env-plan.md(2026-09-12)
7
+ *
8
+ * 两件事:
9
+ * 1. 全自动 AITI_BRIDGE_URL——按 pi-web 自身实例推导(systemd 注入 PORT / PI_WEB_BASE_PATH),
10
+ * agent 子进程里的 aiti MCP shim(aiti-mcp-shim.cjs)继承后自协商端点,自动连
11
+ * 「spawn 自己的这个实例」的桥——通知/交互直达 AI 窗所在实例,dev/prod 不再串线。
12
+ * 2. extman `spawn.env`(type: textlist)环境变量列表——用户逐行配 KEY=VALUE,我们自行
13
+ * 解析 $VAR / ${VAR} 引用(工作 env 里已有者优先,回退父进程 env),完全不依赖目标机器
14
+ * shell 的变量展开(Windows cmd/PowerShell 均无 $ 语法),三平台同一套写法。
15
+ *
16
+ * 行语法(两处列表通用):
17
+ * KEY=VALUE 设置(VALUE 支持 $VAR / ${VAR} 引用;未定义 → 空串 + warning)
18
+ * -KEY 从最终 env 移除 KEY(急救口:治理/全量透传漏进来的坏变量,用户配一行即拔掉;
19
+ * 扩展注册侧同样可用,排除未设置的变量是幂等无害操作)
20
+ * # ... / 空行 注释与空白
21
+ *
22
+ * 合并顺序(后行覆盖前行;移除后可再被后续行重新设置):
23
+ * 治理白名单透传(有则)/ processEnv 全量 → 自动 AITI_BRIDGE_URL → extra
24
+ * → 扩展注册侧默认列表(registerSpawnEnvDefaults,含排除项)→ 用户 extman spawn.env(最高优先)。
25
+ *
26
+ * launch 解析(P0 共享层,docs/aiti-custom-agent-plan.md §3.3;2026-09-13):
27
+ * resolveCliLaunch —— 统一 command/argsPrefix/成员 env/bridge 重写($VAR/${cwd} 展开);
28
+ * parseCustomAgents —— agents.json 内部格式校验(aiti-custom-agent UI 读写);
29
+ * spawn.command / spawn.argsPrefix extman feature(spawnCommandFeature/spawnArgsPrefixFeature)。
30
+ */
31
+
32
+ /** extman feature 源(ctx.features,startup 捕获;DI 方案 P1 同款,缺省走 __piWebExt 兜底) */
33
+ type FeaturesLike = { get(extId: string, fid: string): boolean | string | undefined };
34
+
35
+ let capturedFeatures: FeaturesLike | null = null;
36
+
37
+ /** startup 时捕获 ctx.features(可传 null 清除,热重载/测试用) */
38
+ export function captureSpawnEnvFeatures(f: FeaturesLike | null): void {
39
+ capturedFeatures = f;
40
+ }
41
+
42
+ /** 扩展注册侧默认列表(agentSpawnEnv 时按 extId 取用;与用户列表按序合并,用户在后可覆盖) */
43
+ const registeredDefaults = new Map<string, string>();
44
+
45
+ /** 扩展在 startup/注册时声明自己的默认环境变量列表(含 -NAME 排除项;后注册覆盖前注册) */
46
+ export function registerSpawnEnvDefaults(extId: string, list: string): void {
47
+ registeredDefaults.set(extId, String(list ?? ""));
48
+ }
49
+
50
+ /** pi-web 自身实例基地址(同进程推导;127.0.0.1 直连不走 nginx/Authelia)。
51
+ * dev=3001 + /dev、prod=3002 + 空(48);155/23 随各自服务单元的 PORT/PI_WEB_BASE_PATH。 */
52
+ export function piWebSelfBase(processEnv?: Record<string, string | undefined>): string {
53
+ const env = processEnv ?? (process.env as Record<string, string | undefined>);
54
+ const port = env.PORT || "3000";
55
+ const basePath = (env.PI_WEB_BASE_PATH || "").replace(/\/+$/, "");
56
+ return `http://127.0.0.1:${port}${basePath}`;
57
+ }
58
+
59
+ /** 全自动注入项:aiti-devtools MCP 端点线索(带扩展路径签名,aiti-mcp-shim 识别后直连 <extBase>/mcp/mcp) */
60
+ export function bridgeEnv(processEnv?: Record<string, string | undefined>): Record<string, string> {
61
+ return { AITI_BRIDGE_URL: `${piWebSelfBase(processEnv)}/api/extensions/aiti-devtools` };
62
+ }
63
+
64
+ // ---------------- 列表解析(纯语法层,无 shell 参与) ----------------
65
+
66
+ /** 单条操作:value=null 表示移除(-KEY),否则为设置(KEY=VALUE) */
67
+ export interface EnvLineOp {
68
+ key: string;
69
+ value: string | null;
70
+ }
71
+
72
+ const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
73
+ const REF_RE = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
74
+
75
+ /** 解析列表文本为操作序列(非法行记 warning 跳过、不中断;重复 KEY 后行覆盖,移除行原样保留) */
76
+ export function parseEnvList(raw: string): { ops: EnvLineOp[]; warnings: string[] } {
77
+ const ops: EnvLineOp[] = [];
78
+ const warnings: string[] = [];
79
+ for (const rawLine of String(raw || "").split(/\r?\n/)) {
80
+ const line = rawLine.trim();
81
+ if (!line || line.startsWith("#")) continue;
82
+ if (line.startsWith("-")) {
83
+ const key = line.slice(1).trim();
84
+ if (!KEY_RE.test(key)) {
85
+ warnings.push(`跳过非法排除行(须 -NAME):${line.slice(0, 80)}`);
86
+ continue;
87
+ }
88
+ ops.push({ key, value: null });
89
+ continue;
90
+ }
91
+ const eq = line.indexOf("=");
92
+ if (eq <= 0) {
93
+ warnings.push(`跳过非法行(须 KEY=VALUE 或 -NAME):${line.slice(0, 80)}`);
94
+ continue;
95
+ }
96
+ const key = line.slice(0, eq).trim();
97
+ if (!KEY_RE.test(key)) {
98
+ warnings.push(`跳过非法变量名:${key.slice(0, 80)}`);
99
+ continue;
100
+ }
101
+ ops.push({ key, value: line.slice(eq + 1).trim() });
102
+ }
103
+ return { ops, warnings };
104
+ }
105
+
106
+ /**
107
+ * 把操作序列应用到工作 env 上(原地修改并返回;无 shell 参与):
108
+ * - 设置行:VALUE 中 $NAME / ${NAME} 先查工作 env(含治理透传/自动注入/前面行),
109
+ * 再查 base(父进程 env);两处皆无 → 空串 + warning(不保留字面量,避免半解析值进子进程);
110
+ * - 移除行:delete,幂等(排除未设置的变量无害);不做引号剥离 / %VAR% / 命令替换。
111
+ */
112
+ export function applyEnvList(
113
+ ops: EnvLineOp[],
114
+ env: Record<string, string>,
115
+ opts?: { base?: Record<string, string | undefined>; onWarning?: (msg: string) => void },
116
+ ): Record<string, string> {
117
+ const base = opts?.base;
118
+ const onWarning = opts?.onWarning;
119
+ for (const op of ops) {
120
+ if (op.value === null) {
121
+ delete env[op.key];
122
+ continue;
123
+ }
124
+ env[op.key] = op.value.replace(REF_RE, (_m, braced: string, plain: string) => {
125
+ const name = braced || plain;
126
+ if (Object.prototype.hasOwnProperty.call(env, name)) return env[name];
127
+ if (base && Object.prototype.hasOwnProperty.call(base, name)) return base[name] as string;
128
+ onWarning?.(`${op.key}: 引用的 $${name} 未定义(工作 env 与父进程均无),按空串处理`);
129
+ return "";
130
+ });
131
+ }
132
+ return env;
133
+ }
134
+
135
+ /** 便捷口:解析 + 应用到空白 env(独立解析场景用;spawn 链路走 agentSpawnEnv) */
136
+ export function resolveEnvList(
137
+ raw: string,
138
+ base?: Record<string, string | undefined>,
139
+ ): { env: Record<string, string>; warnings: string[] } {
140
+ const { ops, warnings } = parseEnvList(raw);
141
+ const env: Record<string, string> = {};
142
+ applyEnvList(ops, env, { base, onWarning: (w) => warnings.push(w) });
143
+ return { env, warnings };
144
+ }
145
+
146
+ /** 读 extman string/textlist feature 原文(ctx.features 优先,__piWebExt 直调兜底;非字符串一律按空串) */
147
+ function readStringFeature(extId: string, fid: string): string {
148
+ const v = capturedFeatures?.get?.(extId, fid);
149
+ if (typeof v === "string") return v;
150
+ try {
151
+ const reg = (globalThis as { __piWebExt?: { featureValue?: (extId: string, fid: string) => boolean | string } }).__piWebExt;
152
+ const v2 = reg?.featureValue?.(extId, fid);
153
+ if (typeof v2 === "string") return v2;
154
+ } catch { /* ignore */ }
155
+ return "";
156
+ }
157
+
158
+ /** 读 extman spawn.env 列表原文(缺省 "") */
159
+ export function spawnEnvList(extId: string): string {
160
+ return readStringFeature(extId, "spawn.env");
161
+ }
162
+
163
+ /** 读 extman spawn.command(启动命令覆盖;缺省 ""= 用驱动默认 CLI) */
164
+ export function spawnCommand(extId: string): string {
165
+ return readStringFeature(extId, "spawn.command");
166
+ }
167
+
168
+ /** 读 extman spawn.argsPrefix(参数前缀列表原文,每行一个参数;缺省 "") */
169
+ export function spawnArgsPrefix(extId: string): string {
170
+ return readStringFeature(extId, "spawn.argsPrefix");
171
+ }
172
+
173
+ /**
174
+ * spawn env 统一构造。
175
+ * - cli + governance:走治理白名单(external-governance.ts 的 governanceEnv)为基底,
176
+ * 自动 bridgeEnv 进 extra(白名单外仍注入);
177
+ * - 无 governance(cursor/qoder 等全量透传派):processEnv 基底 + bridgeEnv + extra;
178
+ * - 再按序叠加:扩展注册侧默认列表(registerSpawnEnvDefaults)→ 用户 extman spawn.env
179
+ * (可覆盖/可 -NAME 排除一切,含自动注入项——逃生口)。
180
+ */
181
+ export function agentSpawnEnv(opts: {
182
+ cli?: string;
183
+ governance?: (cli: string, extra?: Record<string, string>) => Record<string, string>;
184
+ extra?: Record<string, string>;
185
+ extId?: string;
186
+ envList?: string;
187
+ processEnv?: Record<string, string | undefined>;
188
+ warn?: (msg: string) => void;
189
+ }): Record<string, string> {
190
+ const processEnv = opts.processEnv ?? (process.env as Record<string, string | undefined>);
191
+ const bridge = bridgeEnv(processEnv);
192
+ let out: Record<string, string>;
193
+ if (opts.cli && opts.governance) {
194
+ out = opts.governance(opts.cli, { ...bridge, ...opts.extra });
195
+ } else {
196
+ out = { ...(processEnv as Record<string, string>), ...bridge, ...opts.extra };
197
+ }
198
+ const onWarning = opts.warn ?? ((m: string) => console.warn(`[spawn.env] ${m}`));
199
+ const warnings: string[] = [];
200
+ const defaultsList = opts.extId ? registeredDefaults.get(opts.extId) || "" : "";
201
+ const { ops, warnings: w1 } = parseEnvList(defaultsList);
202
+ const { ops: userOps, warnings: w2 } = parseEnvList(opts.envList || "");
203
+ warnings.push(...w1, ...w2);
204
+ applyEnvList(ops, out, { base: processEnv, onWarning });
205
+ applyEnvList(userOps, out, { base: processEnv, onWarning });
206
+ return out;
207
+ }
208
+
209
+ /** extman feature 声明(各 agent 扩展 features 数组统一追加;type: textlist 见方案文档机制 B) */
210
+ export function spawnEnvFeature(group?: string): {
211
+ id: string; type: "textlist"; label: string; description: string; value: string; placeholder: string; group?: string;
212
+ } {
213
+ return {
214
+ id: "spawn.env",
215
+ ...(group ? { group } : {}),
216
+ type: "textlist",
217
+ label: "spawn 环境变量",
218
+ description:
219
+ "每行一条,启动 agent 子进程时注入(我们自行解析,不依赖 shell,Windows 同样可用):" +
220
+ "KEY=VALUE 设置(支持 $VAR / ${VAR} 引用:先取当前生效值,再回退父进程环境变量;未定义按空串);" +
221
+ "-NAME 移除该变量(急救口:透传漏进来的坏变量配一行即拔掉);# 注释与空行忽略。" +
222
+ "此处可覆盖自动注入的 AITI_BRIDGE_URL,也可 -AITI_BRIDGE_URL 整个去掉。改完下一轮 spawn 生效。",
223
+ value: "",
224
+ placeholder: "FOO=bar\nBAR=$FOO\n-UNWANTED_VAR\n# 注释行与空行忽略",
225
+ };
226
+ }
227
+
228
+ /** extman feature 声明:spawn.command(启动命令覆盖;P1' 启动包装,方案 docs/aiti-custom-agent-plan.md §3.5) */
229
+ export function spawnCommandFeature(group?: string): {
230
+ id: string; type: "string"; label: string; description: string; value: string; placeholder: string; group?: string;
231
+ } {
232
+ return {
233
+ id: "spawn.command",
234
+ ...(group ? { group } : {}),
235
+ type: "string",
236
+ label: "spawn 命令覆盖",
237
+ description:
238
+ "留空 = 使用本扩展默认 CLI。填入后以它替换默认 CLI 启动(docker 化包装:这里填 docker," +
239
+ "再配「spawn 参数前缀」拼 run --rm -i … 镜像 CLI)。支持 $VAR / ${cwd} 引用(spawn 时展开)。改完下一轮 spawn 生效。" +
240
+ "注意:命令可执行任意本机程序,配置者须为本机管理员(与 spawn.env 同级信任)。",
241
+ value: "",
242
+ placeholder: "docker",
243
+ };
244
+ }
245
+
246
+ /** extman feature 声明:spawn.argsPrefix(参数前缀;textlist 每行一个参数,拼在驱动内置参数之前) */
247
+ export function spawnArgsPrefixFeature(group?: string): {
248
+ id: string; type: "textlist"; label: string; description: string; value: string; placeholder: string; group?: string;
249
+ } {
250
+ return {
251
+ id: "spawn.argsPrefix",
252
+ ...(group ? { group } : {}),
253
+ type: "textlist",
254
+ label: "spawn 参数前缀",
255
+ description:
256
+ "每行一个参数,拼在驱动内置参数之前(docker 化:run / --rm / -i / -v 挂载 / 镜像名 / 容器内 CLI 名)。" +
257
+ "支持 $VAR / ${VAR} / ${cwd}(会话工作目录)引用,spawn 时展开;# 注释与空行忽略。改完下一轮 spawn 生效。" +
258
+ "docker 配方要求 -v ${cwd}:${cwd} -w ${cwd} 同路径挂载,否则容器内路径与宿主历史不一致。",
259
+ value: "",
260
+ placeholder: "run\n--rm\n-i\n-v\n${cwd}:${cwd}\n-w\n${cwd}\nmy-image:latest\nclaude",
261
+ };
262
+ }
263
+
264
+ // ---------------- launch 解析(P0:command / argsPrefix / 成员 env / bridge 重写) ----------------
265
+
266
+ /** 通用 $VAR / ${VAR} 展开:resolve(name) 命中 → 值;未命中 → 空串 + warning(不保留字面量)。
267
+ * 与 applyEnvList 同一引用语法;${cwd} 由调用方注入 resolve 实现。 */
268
+ export function expandRefs(
269
+ value: string,
270
+ resolve: (name: string) => string | undefined,
271
+ onWarning?: (msg: string) => void,
272
+ ): string {
273
+ return String(value ?? "").replace(REF_RE, (_m, braced: string, plain: string) => {
274
+ const name = braced || plain;
275
+ const hit = resolve(name);
276
+ if (hit !== undefined) return hit;
277
+ onWarning?.(`引用的 $${name} 未定义,按空串处理`);
278
+ return "";
279
+ });
280
+ }
281
+
282
+ /** 解析多行参数列表:每行一个参数;# 注释与空行忽略;行内容原样保留($VAR/${cwd} 在 spawn 时展开) */
283
+ export function parseArgsLines(raw: string): { args: string[]; warnings: string[] } {
284
+ const args: string[] = [];
285
+ const warnings: string[] = [];
286
+ for (const rawLine of String(raw || "").split(/\r?\n/)) {
287
+ const line = rawLine.trim();
288
+ if (!line || line.startsWith("#")) continue;
289
+ args.push(line);
290
+ }
291
+ return { args, warnings };
292
+ }
293
+
294
+ /** 启动包装覆盖(P2 协议委托:aiti-custom-agent 成员 → 基础扩展 `<extId>.launch` 服务)。
295
+ * 各基础扩展 spawn 点的 resolveCliLaunch 以本覆盖优先于 extman spawn.command/spawn.argsPrefix;
296
+ * target 仅供多成员家族(如 acp)选成员,单成员扩展忽略。 */
297
+ export interface LaunchOverride {
298
+ command?: string;
299
+ argsPrefix?: string[];
300
+ env?: Record<string, string>;
301
+ bridge?: string;
302
+ target?: string;
303
+ }
304
+
305
+ /** launch 解析输入(resolveCliLaunch) */
306
+ export interface CliLaunchInput {
307
+ /** 驱动默认 CLI(成员 command 覆盖之) */
308
+ defaultCommand: string;
309
+ /** 启动命令覆盖(空串/缺省 → defaultCommand;覆盖时 argv 不再附带原 CLI 名) */
310
+ command?: string;
311
+ /** 参数前缀(逐项展开 $VAR/${VAR}/${cwd}) */
312
+ argsPrefix?: string[];
313
+ /** 驱动内置 argv(不含 CLI 名本身) */
314
+ driverArgs?: string[];
315
+ /** 预构建基底 env(协议扩展路径:agentSpawnEnv 产物);缺省 = processEnv 全量透传(generic 路径) */
316
+ env?: Record<string, string>;
317
+ /** 成员级 env(最高优先;值展开 $VAR/${VAR}/${cwd}) */
318
+ memberEnv?: Record<string, string>;
319
+ /** 桥模式:inherit(缺省,保持现状)/ host.docker.internal(替换主机)/ off(移除)/ 显式 http(s):// URL */
320
+ bridge?: string;
321
+ processEnv?: Record<string, string | undefined>;
322
+ /** ${cwd} 解析值;缺省 process.cwd() */
323
+ cwd?: string;
324
+ warn?: (msg: string) => void;
325
+ }
326
+
327
+ /** launch 解析产物:最终 spawn(command, args, { env }) 三元组 + 警告 */
328
+ export interface ResolvedLaunch {
329
+ command: string;
330
+ args: string[];
331
+ env: Record<string, string>;
332
+ warnings: string[];
333
+ /**
334
+ * win32 且 command 以 .cmd/.bat 结尾时为 true(lessons §0.1:Node ≥18.20 直 spawn
335
+ * .cmd shim 即 EINVAL)——调用方 spawn opts 必须带 `shell: launch.shell`。
336
+ * 参数全部为旗标/路径(prompt 走 stdin),无 cmd 特殊字符面。
337
+ */
338
+ shell?: boolean;
339
+ }
340
+
341
+ /**
342
+ * 统一 launch 解析(P0 共享层,方案 docs/aiti-custom-agent-plan.md §3.3)。
343
+ * - command:成员覆盖 → defaultCommand;
344
+ * - env:显式 env 或 processEnv 全量透传为基底 → 自动 AITI_BRIDGE_URL(已有则保持)→
345
+ * 成员 env(最高优先,逐项展开)→ bridge 重写(inherit/host.docker.internal/URL/off);
346
+ * - args:[...argsPrefix(展开), ...driverArgs]——command 覆盖时由调用方保证 driverArgs 不含原 CLI 名。
347
+ * 纯函数:不 spawn、不读文件(feature 读取在扩展侧完成后传入)。
348
+ */
349
+ export function resolveCliLaunch(input: CliLaunchInput): ResolvedLaunch {
350
+ const processEnv = input.processEnv ?? (process.env as Record<string, string | undefined>);
351
+ const warnings: string[] = [];
352
+ const onWarning = (msg: string) => {
353
+ warnings.push(msg);
354
+ input.warn?.(msg);
355
+ };
356
+ const command = String(input.command ?? "").trim() || input.defaultCommand;
357
+ const cwd = input.cwd ?? process.cwd();
358
+
359
+ // env 基底:显式 env(协议扩展路径,agentSpawnEnv 产物)或全量透传(generic 路径)
360
+ const env: Record<string, string> = input.env
361
+ ? { ...input.env }
362
+ : { ...(processEnv as Record<string, string>) };
363
+ // 自动桥线索:显式 env 未带时补注入(agentSpawnEnv 产物已带则原样保持)
364
+ if (!Object.prototype.hasOwnProperty.call(env, "AITI_BRIDGE_URL")) {
365
+ env.AITI_BRIDGE_URL = bridgeEnv(processEnv).AITI_BRIDGE_URL;
366
+ }
367
+
368
+ // 引用展开上下文:${cwd} 特殊名 → 工作 env → 父进程 env;皆无 → undefined(空串 + warning)
369
+ const resolveRef = (name: string): string | undefined => {
370
+ if (name === "cwd") return cwd;
371
+ if (Object.prototype.hasOwnProperty.call(env, name)) return env[name];
372
+ if (Object.prototype.hasOwnProperty.call(processEnv, name)) return processEnv[name] as string;
373
+ return undefined;
374
+ };
375
+
376
+ // 成员 env(最高优先)
377
+ for (const [k, v] of Object.entries(input.memberEnv ?? {})) {
378
+ env[k] = expandRefs(v, resolveRef, (m) => onWarning(`env ${k}: ${m}`));
379
+ }
380
+
381
+ // bridge 重写(作用于最终 env 的 AITI_BRIDGE_URL)
382
+ const mode = String(input.bridge ?? "").trim() || "inherit";
383
+ if (mode !== "inherit") {
384
+ const cur = env.AITI_BRIDGE_URL;
385
+ if (mode === "off") {
386
+ delete env.AITI_BRIDGE_URL;
387
+ } else if (mode === "host.docker.internal") {
388
+ if (cur) {
389
+ try {
390
+ const u = new URL(cur);
391
+ u.hostname = "host.docker.internal";
392
+ env.AITI_BRIDGE_URL = u.toString();
393
+ } catch {
394
+ onWarning(`bridge=host.docker.internal:当前 AITI_BRIDGE_URL 非法(${cur}),保持不变`);
395
+ }
396
+ } else {
397
+ onWarning("bridge=host.docker.internal:当前无 AITI_BRIDGE_URL,忽略");
398
+ }
399
+ } else if (/^https?:\/\//i.test(mode)) {
400
+ env.AITI_BRIDGE_URL = expandRefs(mode, resolveRef, (m) => onWarning(`bridge: ${m}`));
401
+ } else {
402
+ onWarning(`bridge 模式无法识别(${mode}),按 inherit 处理`);
403
+ }
404
+ }
405
+
406
+ // 参数前缀展开 + 拼装
407
+ const prefix = (input.argsPrefix ?? []).map((a) => expandRefs(a, resolveRef, (m) => onWarning(`argsPrefix「${a}」: ${m}`)));
408
+ let launchArgs: string[] = [...prefix, ...(input.driverArgs ?? [])];
409
+ const shell = process.platform === "win32" && /\.(cmd|bat)$/i.test(command.trim());
410
+ if (shell) onWarning(`command 是 .cmd/.bat shim,spawn 需带 shell:true(调用方读取 launch.shell)`);
411
+
412
+ // 脚本入口(.js/.cjs/.mjs):CreateProcess 无法直跑(POSIX 依赖 shebang+chmod,Windows 必挂)
413
+ // → 包装 process.execPath 直跑(lessons §0.1/§5「node 直跑入口」,三平台同构)。
414
+ let launchCommand = command;
415
+ if (/\.(cjs|mjs|js)$/i.test(command.trim())) {
416
+ launchCommand = process.execPath;
417
+ launchArgs = [command, ...launchArgs];
418
+ onWarning(`command 是脚本入口,已包装 process.execPath 直跑`);
419
+ }
420
+ return { command: launchCommand, args: launchArgs, env, warnings, shell };
421
+ }
422
+
423
+ /** 自定义 agent 成员(agents.json 内部格式,UI 读写;parseCustomAgents 产物) */
424
+ export interface CustomAgentSpec {
425
+ /** provider type(唯一;slug:[a-z0-9][a-z0-9_-]*,不含 / 和 .) */
426
+ id: string;
427
+ /** 选择器展示名 */
428
+ label: string;
429
+ /** 驱动类型:generic(通用命令 one-shot)或协议型(claude/codex/…——注册侧映射到
430
+ * 基础扩展 `<extId>.launch` 服务,服务缺席则该成员不注册) */
431
+ driver: string;
432
+ /** 启动命令(generic 必填;协议型空 = 用驱动默认 CLI) */
433
+ command: string;
434
+ /** 参数前缀(逐项展开 $VAR/${cwd}) */
435
+ argsPrefix: string[];
436
+ /** 成员级 env(最高优先) */
437
+ env: Record<string, string>;
438
+ /** 桥模式:""=inherit / host.docker.internal / off / http(s)://… */
439
+ bridge: string;
440
+ /** 委托目标成员(仅多成员家族协议型,如 acp 的 "claude-code";空 = 服务端缺省成员) */
441
+ target: string;
442
+ /** 探活命令(缺省 = command) */
443
+ probe: string;
444
+ /** picker 位次(小者靠前;缺省 1000 与内置一致) */
445
+ order: number;
446
+ /** 启停(false=保留配置但不注册) */
447
+ enabled: boolean;
448
+ }
449
+
450
+ const CUSTOM_AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]*$/i;
451
+
452
+ function safeJsonParse(raw: string): unknown {
453
+ try {
454
+ return JSON.parse(raw);
455
+ } catch (e) {
456
+ return { __parseError: String((e as Error)?.message || e) };
457
+ }
458
+ }
459
+
460
+ /**
461
+ * 校验/规整 agents.json(内部格式,方案 §3.2):非法条目按 warning 跳过、不整体失败;
462
+ * id 去重(先到先得)、driver 白名单(P1 仅 generic)、env 兼容行式写法(KEY=VALUE / -NAME)。
463
+ */
464
+ export function parseCustomAgents(raw: unknown): { agents: CustomAgentSpec[]; warnings: string[] } {
465
+ const warnings: string[] = [];
466
+ const agents: CustomAgentSpec[] = [];
467
+ const obj = typeof raw === "string" ? safeJsonParse(raw) : raw;
468
+ if (obj !== null && typeof obj === "object" && "__parseError" in (obj as Record<string, unknown>)) {
469
+ warnings.push(`agents.json 不是合法 JSON(${(obj as Record<string, unknown>).__parseError}),按空配置处理`);
470
+ return { agents, warnings };
471
+ }
472
+ const list = (obj as { agents?: unknown } | null | undefined)?.agents;
473
+ if (list === undefined) return { agents, warnings };
474
+ if (!Array.isArray(list)) {
475
+ warnings.push("agents.json 的 agents 字段不是数组,按空配置处理");
476
+ return { agents, warnings };
477
+ }
478
+ const seen = new Set<string>();
479
+ list.forEach((item, i) => {
480
+ const at = `agents[${i}]`;
481
+ const it = (item ?? {}) as Record<string, unknown>;
482
+ const id = String(it.id ?? "").trim();
483
+ if (!CUSTOM_AGENT_ID_RE.test(id)) {
484
+ warnings.push(`${at}: 非法 id「${id.slice(0, 40)}」(须 [a-z0-9][a-z0-9_-]*,不含 / .),跳过`);
485
+ return;
486
+ }
487
+ if (seen.has(id)) {
488
+ warnings.push(`${at}: id「${id}」重复,保留先到条目,跳过`);
489
+ return;
490
+ }
491
+ const label = String(it.label ?? "").trim();
492
+ if (!label) {
493
+ warnings.push(`${at}(${id}): 缺显示名 label,跳过`);
494
+ return;
495
+ }
496
+ const driver = String(it.driver ?? "generic").trim() || "generic";
497
+ if (!/^[a-z][a-z0-9-]*$/i.test(driver)) {
498
+ warnings.push(`${at}(${id}): 非法驱动类型「${driver.slice(0, 40)}」,跳过`);
499
+ return;
500
+ }
501
+ const command = String(it.command ?? "").trim();
502
+ if (driver === "generic" && !command) {
503
+ warnings.push(`${at}(${id}): 缺启动命令 command,跳过`);
504
+ return;
505
+ }
506
+ const argsPrefix = Array.isArray(it.argsPrefix)
507
+ ? it.argsPrefix.map((a) => String(a))
508
+ : typeof it.argsPrefix === "string" && it.argsPrefix.trim()
509
+ ? parseArgsLines(it.argsPrefix).args
510
+ : [];
511
+ const env: Record<string, string> = {};
512
+ if (it.env && typeof it.env === "object" && !Array.isArray(it.env)) {
513
+ for (const [k, v] of Object.entries(it.env as Record<string, unknown>)) {
514
+ const key = String(k).trim();
515
+ if (!KEY_RE.test(key)) {
516
+ warnings.push(`${at}(${id}): 非法环境变量名「${key.slice(0, 40)}」,忽略`);
517
+ continue;
518
+ }
519
+ env[key] = String(v ?? "");
520
+ }
521
+ } else if (typeof it.env === "string" && it.env.trim()) {
522
+ // 兼容行式写法(KEY=VALUE / -NAME 排除)
523
+ const { ops, warnings: w } = parseEnvList(it.env);
524
+ warnings.push(...w.map((m) => `${at}(${id}): ${m}`));
525
+ for (const op of ops) {
526
+ if (op.value === null) delete env[op.key];
527
+ else env[op.key] = op.value;
528
+ }
529
+ }
530
+ const orderRaw = String(it.order ?? "").trim();
531
+ const order = orderRaw !== "" && Number.isFinite(Number(orderRaw)) ? Number(orderRaw) : 1000;
532
+ seen.add(id);
533
+ agents.push({
534
+ id,
535
+ label,
536
+ driver,
537
+ command,
538
+ argsPrefix,
539
+ env,
540
+ bridge: String(it.bridge ?? "").trim(),
541
+ target: String(it.target ?? "").trim(),
542
+ probe: String(it.probe ?? "").trim(),
543
+ order,
544
+ enabled: it.enabled !== false,
545
+ });
546
+ });
547
+ return { agents, warnings };
548
+ }
@@ -0,0 +1,49 @@
1
+ /**
2
+ * aiti-editor 注入缓冲 helper(多编辑器机制 §1.5)——实现扩展 client 统一走这里。
3
+ *
4
+ * 背景:aiti-editor 与实现扩展(aiti-sheet-univer / aiti-word-* 等)的 client 加载
5
+ * 时序不定。晚到的注入需要缓冲重放:
6
+ * - aiti-editor 已就绪(window.__aitiEditor 存在)→ 立即注册;
7
+ * - 未就绪 → 注册函数推进 window.__aitiEditorQueue,aiti-editor setupRegistry
8
+ * 挂载后 flush,并广播 `aiti-editor:registry-ready` 事件。
9
+ *
10
+ * 用法(实现扩展 client 入口):
11
+ * import { whenAitiEditorReady } from "../_shared/aiti-editor-inject.mjs";
12
+ * whenAitiEditorReady(() => {
13
+ * window.__aitiEditor.registerEditorProvider({ id: "…", displayName: "…", selector: { extensions: [".xlsx"] },
14
+ * capabilities: ["preview", "edit"], render(host, ctx) { … return { el, dispose() {} }; } });
15
+ * window.__aitiEditor.registerContentProvider({ id: "…", write(filePath, data, baseMtimeMs) { … } });
16
+ * });
17
+ *
18
+ * 本文件按「共享权威源 + 构建期内联」模式消费(同 cursor-cli-store):实现扩展的
19
+ * vite 构建会把本模块打进各自 bundle,运行时零跨目录依赖。
20
+ */
21
+
22
+ /**
23
+ * aiti-editor 就绪后执行 registerNow(幂等安全:已就绪立即同步执行;
24
+ * 未就绪入队,aiti-editor 就绪时重放)。异常只打日志不扩散(注册失败不拖垮宿主页面)。
25
+ * @param {() => void} registerNow
26
+ */
27
+ export function whenAitiEditorReady(registerNow) {
28
+ if (typeof window === "undefined") return;
29
+ if (window.__aitiEditor) {
30
+ try { registerNow(); } catch (e) { console.error("[aiti-editor-inject] 注册失败:", e); }
31
+ return;
32
+ }
33
+ if (!Array.isArray(window.__aitiEditorQueue)) window.__aitiEditorQueue = [];
34
+ window.__aitiEditorQueue.push(() => {
35
+ try { registerNow(); } catch (e) { console.error("[aiti-editor-inject] 注册失败(重放):", e); }
36
+ });
37
+ }
38
+
39
+ /**
40
+ * 监听注册表就绪(含已就绪场景立即触发一次)。用于需要在注册表 ready 后
41
+ * 再做的初始化(如读偏好、拉取候选列表)。
42
+ * @param {() => void} cb
43
+ */
44
+ export function onAitiEditorReady(cb) {
45
+ if (typeof window === "undefined") return;
46
+ if (window.__aitiEditor) { try { cb(); } catch (e) { console.error("[aiti-editor-inject]", e); } return; }
47
+ const h = () => { window.removeEventListener("aiti-editor:registry-ready", h); try { cb(); } catch (e) { console.error("[aiti-editor-inject]", e); } };
48
+ window.addEventListener("aiti-editor:registry-ready", h);
49
+ }