hiwork-core 0.0.18 → 0.0.21

package/lib/memory-config.js

@@ -0,0 +1,266 @@
+/**
+ * 记忆系统配置下发的只读 host 服务（`hiworkMemory`）。
+ *
+ * 背景：HiWork 给员工接了一套「记忆系统」（腾讯 TencentDB Agent Memory）。规范是
+ * **员工零操作**——记忆的服务地址、实例 ID、团队 ID、凭据**全部由网关下发**，插件
+ * 不得让员工填任何技术字段。本模块是这条链中间的那一环：
+ *
+ * ```
+ * hiwork-admin  GET /api/me/memory-config      ← 网关侧（provision + 下发）
+ *    ↑ 本文件（hiwork-core，用登录会话调它）
+ * hiwork-memory ctx.get('hiworkMemory').config()   ← 插件侧
+ * ```
+ *
+ * 设计要点（形状照 `src/identity.ts`，出网照 `src/ai-router-client.ts`）：
+ *  - **只读、失败不抛异常**：一律返回 `{ ok: false, reason, message }`，reason 四取值
+ *    `not-configured` / `unauthenticated` / `unreachable` / `error`。失败是**数据**不是
+ *    异常：插件侧按 `ok` 判断，绝不会因为宿主的一次网络抖动把异常漏进会话。
+ *  - **字段名分层只在本文件做**：网关那层是 **snake_case**（`panel_url` /
+ *    `service_id` / `team_ids` / `api_key`，跨仓冻结契约），本文件把它转成 camelCase 的
+ *    {@link HiworkMemoryConfigView} 再对外暴露——插件侧**永远不感知上游命名**。
+ *  - **凭据只在内存里活**：`apiKey` 不写 settings、不写任何 storage、不写任何缓存文件
+ *    （与 `src/office-credentials.ts` 同口径），也**不进任何日志**（含调试日志与错误
+ *    日志）——本模块只记事件与异常类型名，绝不记字段值。
+ *  - **5 分钟内存缓存**：命中即不出网（省一次往返，也少一次网关侧的 provision 幂等压力）；
+ *    `force: true` 绕过缓存（「重新获取配置」与 401 自愈走这条）。缓存与**会话 cookie
+ *    绑定**：换了登录账号（登出再登入）时旧缓存直接失效，绝不把上一个员工的凭据发给
+ *    下一个员工（粘错 = 串号）。
+ *  - **失败不进缓存**：拉不到时下一次调用重新出网——否则一次网关抖动会把员工锁在
+ *    「记忆不可用」里整整一个 TTL。
+ *  - **message 是给非技术员工看的中文**：不含凭据、不含 URL 原文、不含 HTTP 状态码。
+ *
+ * 本模块不 import cordis 运行时：provide 走结构化的 {@link MemoryConfigContext} 端口，
+ * 调用方（index.ts）传真实 ctx；单测直接伪造。
+ */
+import { PKG_VERSION } from "./version.js";
+/** cordis 服务名（hiwork-memory 的 Host 半边按此名 `ctx.get` 探测）。 */
+export const HIWORK_MEMORY_SERVICE = 'hiworkMemory';
+/** 网关侧端点（跨仓冻结；与 `/api/me/office-config` 同一条会话鉴权）。 */
+export const ME_MEMORY_CONFIG_PATH = '/api/me/memory-config';
+/** 成功结果的缓存 TTL：5 分钟。 */
+export const MEMORY_CONFIG_TTL_MS = 5 * 60 * 1000;
+/** 出网超时（与 `AiRouterClient` 的缺省一致）。 */
+export const MEMORY_CONFIG_TIMEOUT_MS = 10_000;
+/** 失败文案（给非技术员工看的中文；不含凭据、URL 原文、HTTP 状态码）。 */
+const MESSAGE_NOT_CONFIGURED = '管理员还没开启团队记忆，请联系管理员开通';
+const MESSAGE_UNAUTHENTICATED = '登录状态已过期，请重新登录';
+const MESSAGE_UNREACHABLE = '记忆服务暂时不可用，请稍后重试';
+const MESSAGE_NO_GATEWAY = '还没连上企业网关，请先登录后再试';
+const MESSAGE_GENERIC = '记忆配置暂时无法获取，请稍后重试';
+/** 按 reason 取文案（未登录的两条路径共用同一句，避免措辞分叉）。 */
+function messageFor(reason) {
+    switch (reason) {
+        case 'not-configured': return MESSAGE_NOT_CONFIGURED;
+        case 'unauthenticated': return MESSAGE_UNAUTHENTICATED;
+        case 'unreachable': return MESSAGE_UNREACHABLE;
+        case 'error': return MESSAGE_GENERIC;
+    }
+}
+/** 失败视图（**只带 reason 与 message**，绝不带半个字段）。 */
+function failure(reason, message) {
+    return { ok: false, reason, message: message ?? messageFor(reason) };
+}
+/** 裁掉两侧空白；非字符串或空白串一律视同缺省。 */
+function textOrUndefined(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    return text === '' ? undefined : text;
+}
+/**
+ * 读团队列表：只保留非空字符串，**保持网关下发的顺序**（按优先级排好的，插件取第一个）。
+ * `[]` / 缺省 / 形状非法一律视同「只用个人域」——**不是错误**（spec §4.4 消费规则 3）。
+ */
+function teamIdsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    const ids = [];
+    for (const item of value) {
+        const text = textOrUndefined(item);
+        if (text !== undefined)
+            ids.push(text);
+    }
+    return ids;
+}
+/**
+ * snake_case → camelCase 投影（**全仓唯一做这层转换的地方**）。
+ *
+ * 三个必需字段（`panel_url` / `service_id` / `api_key`）任一缺失即返回 undefined：
+ * 网关 200 却缺字段 = 契约破坏，宁可报「暂时无法获取」，也绝不把半份配置交给终端
+ * （半份配置的下场是插件拿空地址去打请求，错误信息离真正的原因十万八千里）。
+ *
+ * 同时宽容接受 camelCase 别名（`panelUrl` / `serviceId` / `apiKey` / `userKey`）：
+ * 兄弟仓的 spec 里这两个名字都出现过（`hiwork-admin` 的
+ * `docs/superpowers/specs/2026-09-18-memory-provisioning-design.md` §4.1 写的是 camelCase
+ * 且字段名为 `userKey`），读取端宽容不会掩盖错误，却能让本服务在两种落地之间都能工作。
+ * **写出永远是 camelCase 视图**——插件侧不感知任何一种上游命名。
+ */
+function projectMemoryConfig(body) {
+    const panelUrl = textOrUndefined(body['panel_url'] ?? body['panelUrl']);
+    const serviceId = textOrUndefined(body['service_id'] ?? body['serviceId']);
+    const apiKey = textOrUndefined(body['api_key'] ?? body['apiKey'] ?? body['userKey']);
+    if (panelUrl === undefined || serviceId === undefined || apiKey === undefined)
+        return undefined;
+    return {
+        ok: true,
+        panelUrl,
+        serviceId,
+        teamIds: teamIdsOf(body['team_ids'] ?? body['teamIds']),
+        apiKey,
+    };
+}
+/** 异常类型名（日志只记类型，不记消息，避免把凭据/URL 带进日志）。 */
+function errorName(error) {
+    return error instanceof Error ? error.name : typeof error;
+}
+/**
+ * 把「会抛错的网关实现」的稳定 code 映射成 reason。
+ *
+ * 本模块自带的出网端口（{@link createMemoryConfigGateway}）**从不抛错**，这一支是为了
+ * 容忍接线侧传进来的其它实现（例如将来把本端点加进 `AiRouterClient` 后直接复用
+ * `gatewayFor(baseURL)`）：按结构化 `code` 字段判别，不 import 对方的类，也不读 message
+ * （message 里可能带 URL 原文）。
+ */
+function reasonOfErrorCode(error) {
+    const code = error?.code;
+    if (typeof code !== 'string')
+        return undefined;
+    switch (code) {
+        case 'SESSION_EXPIRED': return 'unauthenticated';
+        case 'MEMORY_NOT_CONFIGURED': return 'not-configured';
+        case 'MEMORY_UNREACHABLE':
+        case 'GATEWAY_UNREACHABLE': return 'unreachable';
+        default: return undefined;
+    }
+}
+/** 非 200 状态码 → reason（逐字对应契约：401 / 503 / 504 各有确定语义）。 */
+function reasonOfStatus(status) {
+    if (status === 401)
+        return 'unauthenticated';
+    // 网关 503 `MEMORY_NOT_CONFIGURED`：管理员还没开启团队记忆（部署状态，不是故障）。
+    if (status === 503)
+        return 'not-configured';
+    // 网关 504 `MEMORY_UNREACHABLE`：记忆服务自己暂时不可用——语义上就是「够不着」。
+    if (status === 504)
+        return 'unreachable';
+    return 'error';
+}
+/** 视图投影 + 5 分钟内存缓存（无状态依赖，只有一条内存缓存）。 */
+class MemoryConfigProvider {
+    deps;
+    cached;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async config(opts) {
+        const force = opts?.force === true;
+        let sessionCookie;
+        try {
+            sessionCookie = await this.deps.resolveSession();
+        }
+        catch (error) {
+            // 凭据服务读取失败是宿主故障，不是「没登录」：如实报 error，不诱导用户反复重登。
+            this.deps.log?.(`hiwork-core: 记忆配置获取失败（${errorName(error)}）`);
+            return failure('error');
+        }
+        if (sessionCookie === undefined || sessionCookie === '')
+            return failure('unauthenticated');
+        if (!force) {
+            const hit = this.cached;
+            if (hit !== undefined && hit.sessionCookie === sessionCookie && this.now() - hit.at < MEMORY_CONFIG_TTL_MS) {
+                return hit.view;
+            }
+        }
+        const gateway = this.deps.gateway();
+        // 没有网关地址 = 还没完成登录（baseURL 是登录时写下的），与网络不通归同一档。
+        if (gateway === undefined)
+            return failure('unreachable', MESSAGE_NO_GATEWAY);
+        let outcome;
+        try {
+            outcome = await gateway.getMyMemoryConfig(sessionCookie);
+        }
+        catch (error) {
+            const mapped = reasonOfErrorCode(error);
+            if (mapped !== undefined)
+                return failure(mapped);
+            this.deps.log?.(`hiwork-core: 记忆配置获取失败（${errorName(error)}）`);
+            return failure('error');
+        }
+        if (!outcome.ok) {
+            if (outcome.kind === 'network')
+                return failure('unreachable');
+            if (outcome.kind === 'http')
+                return failure(reasonOfStatus(outcome.status));
+            return failure('error');
+        }
+        const view = projectMemoryConfig(outcome.body);
+        if (view === undefined) {
+            // 只记事件与字段名，不记任何值（响应体里带凭据）。
+            this.deps.log?.('hiwork-core: 网关返回的 memory-config 不完整（缺 panel_url / service_id / api_key 之一）');
+            return failure('error');
+        }
+        // 只缓存成功结果：拉不到时下一次调用重新出网（一次抖动不该锁住一个 TTL）。
+        this.cached = { sessionCookie, view, at: this.now() };
+        return view;
+    }
+    now() {
+        return (this.deps.now ?? Date.now)();
+    }
+}
+/**
+ * 提供 host 侧服务 `hiworkMemory`；返回 disposer（交给 `ctx.effect` 管理生命周期，
+ * 插件卸载时服务随 fiber 一并注销）。
+ */
+export function provideMemoryConfig(ctx, deps) {
+    const service = new MemoryConfigProvider(deps);
+    const dispose = ctx.provide(HIWORK_MEMORY_SERVICE, service);
+    return typeof dispose === 'function' ? dispose : () => { };
+}
+/**
+ * 本端点的出网实现（形状与 `AiRouterClient` 的 `request()` 同款：user-agent 带包版本、
+ * 会话 cookie 走 `cookie` 头、超时用 `AbortSignal.timeout`）。
+ *
+ * **不新造鉴权**：只复用 Host 侧已有的登录会话 cookie（由 `resolveSession` 从凭据库取），
+ * 没有任何密钥/令牌在这一层生成或保存。
+ *
+ * **永不抛异常、绝不回显响应原文**：失败收敛成 {@link MemoryConfigOutcome}，日志与
+ * 异常里都不会出现 URL、状态码或响应体——响应体里带的是该员工自己的记忆凭据。
+ *
+ * `fetchImpl` / `timeoutMs` 仅用于测试注入。
+ */
+export function createMemoryConfigGateway(baseURL, opts = {}) {
+    const root = baseURL.replace(/\/+$/, '');
+    const timeoutMs = opts.timeoutMs ?? MEMORY_CONFIG_TIMEOUT_MS;
+    const doFetch = opts.fetchImpl ?? fetch;
+    return {
+        async getMyMemoryConfig(sessionCookie) {
+            try {
+                const res = await doFetch(`${root}${ME_MEMORY_CONFIG_PATH}`, {
+                    method: 'GET',
+                    headers: {
+                        'user-agent': `hiwork-core/${PKG_VERSION}`,
+                        cookie: sessionCookie,
+                    },
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                if (!res.ok)
+                    return { ok: false, kind: 'http', status: res.status };
+                let body;
+                try {
+                    body = await res.json();
+                }
+                catch {
+                    // 非 JSON 响应：只报「不可解析」，不把响应片段带进任何返回值或日志。
+                    return { ok: false, kind: 'invalid' };
+                }
+                if (body === null || typeof body !== 'object')
+                    return { ok: false, kind: 'invalid' };
+                return { ok: true, body };
+            }
+            catch {
+                // 超时（AbortSignal.timeout → TimeoutError）/ 连接失败 / DNS：一律按不可达。
+                return { ok: false, kind: 'network' };
+            }
+        },
+    };
+}