@forgeax/interface 0.4.1 → 0.6.0

package/dist/package/node/lib/action-registry.js

@@ -1,210 +0,0 @@
-/** action-registry —— UI 语义操作层(产品 AI 化 P0)的单一真值源:
- *  「本产品当前暴露哪些可被人 / AI 调用的功能」。
- *
- *  一张注册表服务三个消费者(压缩公理:消掉「AI 能做的和人能做的是不是同一套?」):
- *    1. 按钮 onClick —— 组件经 `dispatchAction(id, args)` 派发(与 AI 同一条路);
- *    2. 命令面板(P2,cmdk 激活时数据源即本表);
- *    3. AI 工具调用 —— `ui_snapshot` 读清单 / `ui_invoke` 派发,经 lib/ui-bridge.ts
- *       的 perception 往返接到编排层(@forgeax/orchestrator)。
- *
- *  契约形态(评审 2.1):`schema` 的 SSOT 是 **JSON Schema 纯对象**(AI 侧 ToolSpec 与
- *  postMessage 结构化克隆都只吃 JSON;函数永不过 wire)。`available` / `run` 只活在
- *  本模块,manifest(`buildManifest`)只导出可序列化子集。
- *
- *  headless 边界(方案 §5):`surface:'both'` 的 action,UI `run()` 必须调 server 的
- *  同一 HTTP API(server 是行为 SSOT),UI 侧只许加视觉反馈——不许长出独立业务逻辑。
- */
-// ─── 注册表本体(模块级 Map,页级单例)────────────────────────────────────────
-const actions = new Map();
-const stateSlices = new Map();
-const changeListeners = new Set();
-function notifyChange() {
-    for (const cb of changeListeners) {
-        try {
-            cb();
-        }
-        catch {
-            /* listener 异常不传染 */
-        }
-    }
-}
-/** 注册一个 action(同 id 重复注册 = 替换,幂等;HMR 安全)。返回注销函数。 */
-export function registerAction(def) {
-    actions.set(def.id, def);
-    notifyChange();
-    return () => {
-        if (actions.get(def.id) === def) {
-            actions.delete(def.id);
-            notifyChange();
-        }
-    };
-}
-/** 注册一片状态摘要(同 id 替换,幂等)。返回注销函数。 */
-export function registerStateSlice(id, selector) {
-    stateSlices.set(id, selector);
-    notifyChange();
-    return () => {
-        if (stateSlices.get(id) === selector) {
-            stateSlices.delete(id);
-            notifyChange();
-        }
-    };
-}
-/** 注册表(action 或 state slice)变更订阅 —— ui-bridge 据此 debounce 重推 manifest。 */
-export function onRegistryChange(cb) {
-    changeListeners.add(cb);
-    return () => changeListeners.delete(cb);
-}
-export function getAction(id) {
-    return actions.get(id);
-}
-// ─── 派发单入口(评审 2.4:data-* 只做发现,执行永远走这里)──────────────────
-/** AI 派发时打的来源标记;window 事件供 ghost 高亮层(P1)与 telemetry / 轨迹追踪衔接。
- *  detail 形:`{ id, source, args }` —— args 让轨迹追踪(lib/ui-trajectory)记得下「做了啥」,
- *  ghost 高亮只用 id/source(向后兼容,多带的字段无害)。 */
-export const UI_ACTION_DISPATCH_EVENT = 'forgeax:ui-action-dispatch';
-/** 极简 JSON Schema 参数校验(P0:required + 顶层 properties 的原始类型)。
- *  不引 ajv——契约漂移由编排层契约测试兜,这里挡住明显错参即可(Fail Fast)。 */
-function validateArgs(schema, args) {
-    if (!schema)
-        return true;
-    const required = Array.isArray(schema.required) ? schema.required : [];
-    for (const k of required) {
-        if (typeof k === 'string' && !(k in args))
-            return `missing required arg "${k}"`;
-    }
-    const props = schema.properties && typeof schema.properties === 'object'
-        ? schema.properties
-        : {};
-    for (const [k, v] of Object.entries(args)) {
-        const p = props[k];
-        if (!p)
-            continue; // 未声明的多余参数放过(向前兼容),由 run 自行忽略
-        const t = p.type;
-        if (typeof t === 'string') {
-            const actual = Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v;
-            const okType = (t === 'string' && actual === 'string') ||
-                (t === 'number' && actual === 'number') ||
-                (t === 'integer' && actual === 'number' && Number.isInteger(v)) ||
-                (t === 'boolean' && actual === 'boolean') ||
-                (t === 'object' && actual === 'object') ||
-                (t === 'array' && actual === 'array');
-            if (!okType)
-                return `arg "${k}" should be ${t}, got ${actual}`;
-        }
-        if (Array.isArray(p.enum) && !p.enum.includes(v)) {
-            return `arg "${k}" must be one of ${JSON.stringify(p.enum)}`;
-        }
-    }
-    return true;
-}
-/** 派发一个 action —— 按钮与 AI 共用的**唯一**执行入口(未注册的 id 拒绝,fail-closed)。 */
-export async function dispatchAction(id, args = {}, opts = {}) {
-    const src = opts.source ?? 'human';
-    // [fx-action-trace] 定位「点了/调了没反应」的最小充分打点:
-    //   ① entry —— 派发是否发生 + args/source(缺此行 = 根本没触发 dispatch)。
-    //   ② terminal —— 唯一终态行:completed/accepted 带 stateDigest(判「到底改了啥」),
-    //      rejected 带 reason(未注册/不可用/参数错/run 抛错 已统一收敛进 reason)。
-    // 两行即可定位:有 entry 无 terminal = 卡在 run();rejected+reason = 为何被拒;
-    // completed 但 stateDigest 没变 = action 效果与 UI 脱节。故只留这两点(+抛错补栈)。
-    console.info(`%c[fx-action]%c ▶ ${id} (${src})`, 'color:#818cf8;font-weight:bold', 'color:inherit', { args });
-    const done = (r) => {
-        if (r.status === 'rejected') {
-            console.warn(`[fx-action] ✗ ${id} rejected: ${r.reason ?? ''}`);
-        }
-        else {
-            console.info(`%c[fx-action]%c ✔ ${id} → ${r.status}`, 'color:#34d399;font-weight:bold', 'color:inherit', r.stateDigest !== undefined ? { stateDigest: r.stateDigest } : {});
-        }
-        return r;
-    };
-    const def = actions.get(id);
-    if (!def)
-        return done({ status: 'rejected', reason: `unknown action "${id}" (not in the registry)` });
-    const avail = def.available ? safeAvailable(def) : true;
-    if (avail !== true)
-        return done({ status: 'rejected', reason: avail });
-    const valid = validateArgs(def.schema, args);
-    if (valid !== true)
-        return done({ status: 'rejected', reason: valid });
-    try {
-        window.dispatchEvent(new CustomEvent(UI_ACTION_DISPATCH_EVENT, { detail: { id, source: src, args } }));
-    }
-    catch {
-        /* SSR / no window — ignore */
-    }
-    try {
-        const out = await def.run(args);
-        return done(out ?? { status: 'completed' });
-    }
-    catch (e) {
-        console.error(`[fx-action] ✗ ${id} threw`, e); // 抛错补一行栈(定位真异常)
-        return done({ status: 'rejected', reason: `action "${id}" threw: ${e instanceof Error ? e.message : String(e)}` });
-    }
-}
-function safeAvailable(def) {
-    try {
-        return def.available();
-    }
-    catch (e) {
-        return `availability check threw: ${e instanceof Error ? e.message : String(e)}`;
-    }
-}
-/** ui_snapshot 的 action 视图。分层(评审 2.7):默认轻量清单;detail:'schema' + ids
- *  按需展开 schema 与详细说明(长尾几百 action 也不炸 token)。 */
-export function snapshotActions(detail, ids) {
-    const expand = detail === 'schema' ? new Set(ids ?? []) : null;
-    const out = [];
-    for (const def of actions.values()) {
-        const avail = def.available ? safeAvailable(def) : true;
-        const row = {
-            id: def.id,
-            title: def.title,
-            available: avail === true,
-            ...(avail === true ? {} : { reason: avail }),
-        };
-        if (expand?.has(def.id)) {
-            if (def.description)
-                row.description = def.description;
-            row.inputSchema = def.schema ?? { type: 'object', properties: {} };
-        }
-        out.push(row);
-    }
-    return out;
-}
-/** ui_snapshot 的状态摘要:逐片 derive,单片异常不传染(fail-soft)。 */
-export function snapshotState() {
-    const out = {};
-    for (const [id, selector] of stateSlices) {
-        try {
-            out[id] = selector();
-        }
-        catch (e) {
-            out[id] = { error: `state slice threw: ${e instanceof Error ? e.message : String(e)}` };
-        }
-    }
-    return out;
-}
-/** manifest(POST /:sid/ui-manifest 的 payload)—— 只含可序列化声明,函数永不出墙。
- *  它是编排层 trust-gate 的权限输入:capability 必须如实声明。 */
-export function buildManifest() {
-    const out = [];
-    for (const def of actions.values()) {
-        out.push({
-            id: def.id,
-            title: def.title,
-            ...(def.description ? { description: def.description } : {}),
-            inputSchema: def.schema ?? { type: 'object', properties: {} },
-            capability: def.capability,
-            ...(def.surface ? { surface: def.surface } : {}),
-            ...(def.timeoutMs ? { timeoutMs: def.timeoutMs } : {}),
-            ...(def.firstClass ? { firstClass: true } : {}),
-        });
-    }
-    return out;
-}
-/** 测试用:清空注册表(生产代码不要调)。 */
-export function __resetRegistryForTest() {
-    actions.clear();
-    stateSlices.clear();
-    changeListeners.clear();
-}