hiwork-core 0.0.19 → 0.0.22

package/README.md

@@ -136,6 +136,14 @@ ctx.inject(['hiworkFeatureCenter'], (scope) => {
 - [src/office-relay.ts](src/office-relay.ts)：文档中继的 host 侧服务（`hiworkOfficeRelay`）——
   跨 NAT 的在线编辑：插件把文档暂存到 DS 能访问的服务器侧（上传/轮询/取回/关闭），
   用户侧不再需要入向可达性；同样只在 Host 持 cookie、失败用稳定信封。
+- [src/identity.ts](src/identity.ts)：当前登录身份的只读 host 服务（`hiworkIdentity`）——
+  业务插件（hiwork-memory 的记忆隔离键等）经 `ctx.get('hiworkIdentity')` 取
+  `{ loggedIn, subject, username, displayName, employeeName, teamName }`；`subject` 是
+  账号名的 sha256 前 16 位（`u_` 前缀，**不含账号原文**），未登录回 `{ loggedIn: false }`。
+- [src/memory-config.ts](src/memory-config.ts)：记忆系统配置下发的只读 host 服务（`hiworkMemory`）——
+  hiwork-memory 经 `ctx.get('hiworkMemory').config()` 取网关下发的 `panelUrl` / `serviceId` /
+  `teamIds` / `apiKey`（网关 `GET /api/me/memory-config`；snake_case → camelCase 的转换只在 Host 做），
+  成功结果 5 分钟内存缓存、`force` 可绕过；凭据只在内存里活、不落盘、不进日志。
 - [src/default-model.ts](src/default-model.ts)：供给成功后校正 `agent-default-model`（默认模型落点）。
 - [src/client/login-gate.tsx](src/client/login-gate.tsx)：全屏登录门禁页。
 - [src/client/section.tsx](src/client/section.tsx)：设置页「AI Router 网关」卡片。

package/lib/client.js

@@ -142,7 +142,7 @@ function browserLoginViewOf(value) {
   if (loginMode === "form") return { loginMode, browserLoginUrl: void 0, browserLoginPending: false };
   return { loginMode, browserLoginUrl: authorizeUrlOf(value), browserLoginPending: browserLoginPendingOf(value) };
 }
-function openAuthorizeUrl(url) {
+function openExternalUrl(url) {
   if (url === void 0 || url === "") return;
   if (typeof window === "undefined") return;
   let protocol;
@@ -154,6 +154,9 @@ function openAuthorizeUrl(url) {
   if (protocol !== "https:" && protocol !== "http:") return;
   window.open(url, "_blank", "noopener,noreferrer");
 }
+function openAuthorizeUrl(url) {
+  openExternalUrl(url);
+}
 async function requestBrowserLogin(scope) {
   await scope.set("browserLoginRequest", { at: (/* @__PURE__ */ new Date()).toISOString() });
 }
@@ -1318,6 +1321,64 @@ function removeStaleHeroGreeting(doc) {
   for (const stale of Array.from(doc.querySelectorAll("[data-hiwork-hero-greeting]"))) stale.remove();
 }
 
+// src/client/manual-link.ts
+var MANUAL_URL = "https://hiworkapp.hivery.cn/manual.html";
+var MANUAL_STYLE_ID = "hiwork-core-manual-style";
+var MANUAL_STYLE = `
+[data-hiwork-core-manual-entry]{box-sizing:border-box;flex:none;display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;margin-left:auto;padding:0;border:0;border-radius:999px;background:transparent;color:var(--dsw-alias-label-tertiary,#71717a);font-family:inherit;font-size:14px;line-height:1;font-weight:600;cursor:pointer;user-select:none;transition:background .16s ease,color .16s ease}
+[data-hiwork-core-manual-entry]:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(24,24,27,.06));color:var(--dsw-alias-label-secondary,#3f3f46)}
+[data-hiwork-core-manual-entry]:focus-visible{outline:2px solid var(--dsw-alias-button-info-fill,#4c8dff);outline-offset:2px}
+body[data-ds-dark-theme] [data-hiwork-core-manual-entry]{color:var(--dsw-alias-label-tertiary,#9ba3b4)}
+body[data-ds-dark-theme] [data-hiwork-core-manual-entry]:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.08));color:var(--dsw-alias-label-secondary,#a6adb8)}
+@media (prefers-reduced-motion: reduce){[data-hiwork-core-manual-entry]{transition:none}}
+`;
+function ensureManualStyle(doc) {
+  if (doc.getElementById(MANUAL_STYLE_ID) !== null) return;
+  if (doc.head === null) return;
+  const style = doc.createElement("style");
+  style.id = MANUAL_STYLE_ID;
+  style.textContent = MANUAL_STYLE;
+  doc.head.append(style);
+}
+function openManual() {
+  openExternalUrl(MANUAL_URL);
+}
+function findManualMount(doc) {
+  const hero = doc.querySelector('[data-phase="hero"]');
+  if (hero === null) return null;
+  return hero.querySelector('[class*="_heroWorkspaceRow"]');
+}
+function buildButton(doc) {
+  const button = doc.createElement("button");
+  button.dataset.hiworkCoreManualEntry = "";
+  button.type = "button";
+  button.title = "\u4F7F\u7528\u624B\u518C";
+  button.setAttribute("aria-label", "\u4F7F\u7528\u624B\u518C");
+  button.append(doc.createTextNode("?"));
+  button.addEventListener("click", (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    openManual();
+  });
+  return button;
+}
+function removeStaleManualEntry(doc) {
+  for (const stale of Array.from(doc.querySelectorAll("[data-hiwork-core-manual-entry]"))) {
+    stale.remove();
+  }
+}
+function decorateManualEntry(doc) {
+  const row = findManualMount(doc);
+  if (row === null) {
+    removeStaleManualEntry(doc);
+    return;
+  }
+  const existing = row.querySelector(":scope > [data-hiwork-core-manual-entry]");
+  if (existing !== null) return;
+  removeStaleManualEntry(doc);
+  row.append(buildButton(doc));
+}
+
 // src/client/daily-card.ts
 var DAILY_CARD_STYLE_ID = "dcu-daily-card-style";
 var DAILY_MAIN_FONT_SIZE_MAX = 64;
@@ -1608,6 +1669,7 @@ function observeHeroDecorations(doc, quotes) {
   };
   ensureDailyCardStyle(doc);
   ensureHeroStyle(doc);
+  ensureManualStyle(doc);
   let applying = false;
   let frame;
   let lastDailyDay = -1;
@@ -1620,6 +1682,7 @@ function observeHeroDecorations(doc, quotes) {
       if (today !== lastDailyDay) lastDailyDay = today;
       decorateDailyCard(doc, quotes);
       decorateHeroGreeting(doc);
+      decorateManualEntry(doc);
     } finally {
       applying = false;
     }
@@ -1752,6 +1815,8 @@ var footStyle = { margin: "2px 0 0", fontSize: 11, color: INK_CAPTION, textAlign
 var browserHintStyle = { margin: 0, fontSize: 12, lineHeight: 1.6, color: INK_CAPTION, textAlign: "center" };
 var browserActionsStyle = { display: "flex", alignItems: "center", justifyContent: "center", gap: 18 };
 var toggleStyle = { ...linkButton, alignSelf: "center", fontSize: 12.5 };
+var footBlockStyle = { display: "flex", flexDirection: "column", alignItems: "center", gap: 4 };
+var manualLinkStyle = { ...linkButton, fontWeight: 500 };
 function describeLoginError(error) {
   if (error === void 0) return void 0;
   if (error.code === "GATEWAY_UNREACHABLE") return "\u7F51\u5173\u6682\u65F6\u4E0D\u53EF\u7528\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\uFF0C\u6216\u6539\u7528\u8D26\u53F7\u5BC6\u7801\u767B\u5F55";
@@ -1887,7 +1952,10 @@ function LoginGateModal(props) {
         browserLogin,
         form,
         showBrowserLogin && formVisible ? /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("button", { "data-hiwork-core-secondary": true, "data-hiwork-core-form-collapse": true, type: "button", style: toggleStyle, onClick: () => setFormOpen(false), children: "\u6536\u8D77\u8D26\u53F7\u5BC6\u7801\u767B\u5F55" }) : null,
-        /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: footStyle, children: "\u4F01\u4E1A\u7EDF\u4E00\u8EAB\u4EFD\u8BA4\u8BC1 \xB7 LDAP" })
+        /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: footBlockStyle, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: footStyle, children: "\u4F01\u4E1A\u7EDF\u4E00\u8EAB\u4EFD\u8BA4\u8BC1 \xB7 LDAP" }),
+          /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("button", { "data-hiwork-core-secondary": true, "data-hiwork-core-manual-login": true, type: "button", style: manualLinkStyle, onClick: openManual, children: "\u4F7F\u7528\u624B\u518C" })
+        ] })
       ] })
     ] })
   ] });

package/lib/identity.js

@@ -0,0 +1,111 @@
+/**
+ * 当前登录身份的只读 host 服务（`hiworkIdentity`）。
+ *
+ * 背景：hiwork-core 已经把「谁登录了」完整地记在 `ai-router` 设置命名空间里
+ * （`username` / `displayName` / `keys`），但那是**本插件的私有状态段**——业务插件
+ * 要拿「当前登录员工」做数据隔离（hiwork-memory 的记忆隔离键、按人区分的本地
+ * 目录名等），既不该去解析别人的设置段，也不该把登录态复制一份自己维护。
+ * 本模块把那层读取收敛成一个稳定的小服务：消费方 `ctx.get('hiworkIdentity')`
+ * 拿到的是一份**只读视图**，登录态怎么变、什么时候变都由 Host 说了算。
+ *
+ * 设计要点（与宿主既有 RPC 服务同构，参照 `src/office-credentials.ts`）：
+ *  - **只读、同步、不抛异常**：`current()` 同步返回快照，未登录返回
+ *    `{ loggedIn: false }`，已登录但还没拉到 keys 时 `employeeName` / `teamName`
+ *    缺省而不是报错（首次登录的中间态、老网关不带这两个字段都会走到这里）；
+ *  - **绝不外泄账号原文进隔离键**：`subject = 'u_' + sha256(username) 的前 16 位 hex`。
+ *    subject 会进存储键 / 目录名，哈希保证它同一账号恒等（跨会话、跨设备稳定）、
+ *    不同账号几乎必然不同，同时不把企业账号明文写进磁盘或日志；
+ *    `username` 字段仍在视图里（界面要显示账号），但**不承担隔离键职责**；
+ *  - **不缓存、不订阅**：每次 `current()` 都读一次当前命名空间值，消费方不再需要
+ *    关心 Host 何时刷新过登录态；
+ *  - 服务经 `ctx.provide` 提供给同进程的其他插件，消费方用 `ctx.get` 探测
+ *    （老 core 上它是 undefined → 插件自行回退，不假设本服务存在）。
+ *
+ * 本模块不 import cordis 运行时：provide 走结构化的 {@link IdentityContext} 端口，
+ * 调用方（index.ts）传真实 ctx；单测直接伪造。
+ */
+import { createHash } from 'node:crypto';
+/** cordis 服务名（hiwork-memory 等消费方按此名 `ctx.get` 探测）。 */
+export const HIWORK_IDENTITY_SERVICE = 'hiworkIdentity';
+/** 视图字段名的语义名（供消费方日志 / 文档引用，避免各处硬编码字符串）。 */
+export const IDENTITY_SUBJECT_PREFIX = 'u_';
+/** 裁掉两侧空白；非字符串或空白串一律视同缺省。 */
+function textOrUndefined(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.trim();
+    return text === '' ? undefined : text;
+}
+/**
+ * 由登录账号派生稳定 subject：`u_` + `sha256(账号名).hex` 的前 16 位。
+ *
+ * 输入先裁掉两侧空白（与视图里的 `username` 同口径），因此 `' alice '` 与 `'alice'`
+ * 派生同一个 subject；大小写不折叠——账号名在网关侧就是区分大小写的。
+ * **本函数绝不返回账号名原文**：subject 会落进存储键 / 目录名，哈希是隔离键
+ * 既能稳定标识同一员工、又不外泄账号的那条界线。
+ */
+export function deriveSubject(username) {
+    const digest = createHash('sha256').update(username.trim(), 'utf8').digest('hex');
+    return `${IDENTITY_SUBJECT_PREFIX}${digest.slice(0, 16)}`;
+}
+/**
+ * 从 keys 里挑员工名 / 团队名：逐条取第一个非空值，两项**互不掩盖**
+ * （某把 Key 只带了 team_name，不会让另一把 Key 的 employee_name 被丢掉）。
+ * 同一账号的各把 Key 属于同一个人，命名相同的部分取值一致，因此不需要按 keyId 挑。
+ */
+function pickKeyNames(keys) {
+    let employeeName;
+    let teamName;
+    for (const key of keys ?? []) {
+        if (employeeName === undefined)
+            employeeName = textOrUndefined(key?.employee_name);
+        if (teamName === undefined)
+            teamName = textOrUndefined(key?.team_name);
+        if (employeeName !== undefined && teamName !== undefined)
+            break;
+    }
+    return {
+        ...(employeeName === undefined ? {} : { employeeName }),
+        ...(teamName === undefined ? {} : { teamName }),
+    };
+}
+/** 视图投影（无状态；未登录 / 读失败一律收敛为 `{ loggedIn: false }`）。 */
+class IdentityProvider {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    current() {
+        try {
+            const state = this.deps.current();
+            const username = textOrUndefined(state?.username);
+            // 未登录：只给 loggedIn，绝不带半份身份出去。
+            if (username === undefined)
+                return { loggedIn: false };
+            const displayName = textOrUndefined(state?.displayName);
+            const { employeeName, teamName } = pickKeyNames(state?.keys);
+            return {
+                loggedIn: true,
+                subject: deriveSubject(username),
+                username,
+                ...(displayName === undefined ? {} : { displayName }),
+                ...(employeeName === undefined ? {} : { employeeName }),
+                ...(teamName === undefined ? {} : { teamName }),
+            };
+        }
+        catch (error) {
+            // 只读服务不该把宿主的读失败变成消费方的异常：收敛成「未登录」并记一笔。
+            this.deps.log?.(`hiwork-core: 登录身份读取失败（${error instanceof Error ? error.name : typeof error}）`);
+            return { loggedIn: false };
+        }
+    }
+}
+/**
+ * 提供 host 侧服务 `hiworkIdentity`；返回 disposer（交给 `ctx.effect` 管理生命周期，
+ * 插件卸载时服务随 fiber 一并注销）。
+ */
+export function provideIdentity(ctx, deps) {
+    const service = new IdentityProvider(deps);
+    const dispose = ctx.provide(HIWORK_IDENTITY_SERVICE, service);
+    return typeof dispose === 'function' ? dispose : () => { };
+}

package/lib/index.js

@@ -3137,7 +3137,7 @@ function isUnloading(ctx) {
 }
 
 // src/version.ts
-var PKG_VERSION = false ? "dev" : "0.0.19";
+var PKG_VERSION = false ? "dev" : "0.0.22";
 
 // src/ai-router-client.ts
 var AUTH_AUTHORIZE_PATH = "/api/auth/authorize";
@@ -6385,6 +6385,228 @@ function registerPluginUpdatesRpc(ctx, deps) {
   };
 }
 
+// src/identity.ts
+import { createHash as createHash2 } from "node:crypto";
+var HIWORK_IDENTITY_SERVICE = "hiworkIdentity";
+var IDENTITY_SUBJECT_PREFIX = "u_";
+function textOrUndefined5(value) {
+  if (typeof value !== "string") return void 0;
+  const text = value.trim();
+  return text === "" ? void 0 : text;
+}
+function deriveSubject(username) {
+  const digest = createHash2("sha256").update(username.trim(), "utf8").digest("hex");
+  return `${IDENTITY_SUBJECT_PREFIX}${digest.slice(0, 16)}`;
+}
+function pickKeyNames(keys) {
+  let employeeName;
+  let teamName;
+  for (const key of keys ?? []) {
+    if (employeeName === void 0) employeeName = textOrUndefined5(key?.employee_name);
+    if (teamName === void 0) teamName = textOrUndefined5(key?.team_name);
+    if (employeeName !== void 0 && teamName !== void 0) break;
+  }
+  return {
+    ...employeeName === void 0 ? {} : { employeeName },
+    ...teamName === void 0 ? {} : { teamName }
+  };
+}
+var IdentityProvider = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  current() {
+    try {
+      const state = this.deps.current();
+      const username = textOrUndefined5(state?.username);
+      if (username === void 0) return { loggedIn: false };
+      const displayName = textOrUndefined5(state?.displayName);
+      const { employeeName, teamName } = pickKeyNames(state?.keys);
+      return {
+        loggedIn: true,
+        subject: deriveSubject(username),
+        username,
+        ...displayName === void 0 ? {} : { displayName },
+        ...employeeName === void 0 ? {} : { employeeName },
+        ...teamName === void 0 ? {} : { teamName }
+      };
+    } catch (error) {
+      this.deps.log?.(
+        `hiwork-core: \u767B\u5F55\u8EAB\u4EFD\u8BFB\u53D6\u5931\u8D25\uFF08${error instanceof Error ? error.name : typeof error}\uFF09`
+      );
+      return { loggedIn: false };
+    }
+  }
+};
+function provideIdentity(ctx, deps) {
+  const service = new IdentityProvider(deps);
+  const dispose = ctx.provide(HIWORK_IDENTITY_SERVICE, service);
+  return typeof dispose === "function" ? dispose : () => {
+  };
+}
+
+// src/memory-config.ts
+var HIWORK_MEMORY_SERVICE = "hiworkMemory";
+var ME_MEMORY_CONFIG_PATH = "/api/me/memory-config";
+var MEMORY_CONFIG_TTL_MS = 5 * 60 * 1e3;
+var MEMORY_CONFIG_TIMEOUT_MS = 1e4;
+var MESSAGE_NOT_CONFIGURED = "\u7BA1\u7406\u5458\u8FD8\u6CA1\u5F00\u542F\u56E2\u961F\u8BB0\u5FC6\uFF0C\u8BF7\u8054\u7CFB\u7BA1\u7406\u5458\u5F00\u901A";
+var MESSAGE_UNAUTHENTICATED = "\u767B\u5F55\u72B6\u6001\u5DF2\u8FC7\u671F\uFF0C\u8BF7\u91CD\u65B0\u767B\u5F55";
+var MESSAGE_UNREACHABLE = "\u8BB0\u5FC6\u670D\u52A1\u6682\u65F6\u4E0D\u53EF\u7528\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+var MESSAGE_NO_GATEWAY = "\u8FD8\u6CA1\u8FDE\u4E0A\u4F01\u4E1A\u7F51\u5173\uFF0C\u8BF7\u5148\u767B\u5F55\u540E\u518D\u8BD5";
+var MESSAGE_GENERIC = "\u8BB0\u5FC6\u914D\u7F6E\u6682\u65F6\u65E0\u6CD5\u83B7\u53D6\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+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;
+  }
+}
+function failure9(reason, message) {
+  return { ok: false, reason, message: message ?? messageFor(reason) };
+}
+function textOrUndefined6(value) {
+  if (typeof value !== "string") return void 0;
+  const text = value.trim();
+  return text === "" ? void 0 : text;
+}
+function teamIdsOf(value) {
+  if (!Array.isArray(value)) return [];
+  const ids = [];
+  for (const item of value) {
+    const text = textOrUndefined6(item);
+    if (text !== void 0) ids.push(text);
+  }
+  return ids;
+}
+function projectMemoryConfig(body) {
+  const panelUrl = textOrUndefined6(body["panel_url"] ?? body["panelUrl"]);
+  const serviceId = textOrUndefined6(body["service_id"] ?? body["serviceId"]);
+  const apiKey = textOrUndefined6(body["api_key"] ?? body["apiKey"] ?? body["userKey"]);
+  if (panelUrl === void 0 || serviceId === void 0 || apiKey === void 0) return void 0;
+  return {
+    ok: true,
+    panelUrl,
+    serviceId,
+    teamIds: teamIdsOf(body["team_ids"] ?? body["teamIds"]),
+    apiKey
+  };
+}
+function errorName2(error) {
+  return error instanceof Error ? error.name : typeof error;
+}
+function reasonOfErrorCode(error) {
+  const code = error?.code;
+  if (typeof code !== "string") return void 0;
+  switch (code) {
+    case "SESSION_EXPIRED":
+      return "unauthenticated";
+    case "MEMORY_NOT_CONFIGURED":
+      return "not-configured";
+    case "MEMORY_UNREACHABLE":
+    case "GATEWAY_UNREACHABLE":
+      return "unreachable";
+    default:
+      return void 0;
+  }
+}
+function reasonOfStatus(status) {
+  if (status === 401) return "unauthenticated";
+  if (status === 503) return "not-configured";
+  if (status === 504) return "unreachable";
+  return "error";
+}
+var MemoryConfigProvider = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  cached;
+  async config(opts) {
+    const force = opts?.force === true;
+    let sessionCookie;
+    try {
+      sessionCookie = await this.deps.resolveSession();
+    } catch (error) {
+      this.deps.log?.(`hiwork-core: \u8BB0\u5FC6\u914D\u7F6E\u83B7\u53D6\u5931\u8D25\uFF08${errorName2(error)}\uFF09`);
+      return failure9("error");
+    }
+    if (sessionCookie === void 0 || sessionCookie === "") return failure9("unauthenticated");
+    if (!force) {
+      const hit = this.cached;
+      if (hit !== void 0 && hit.sessionCookie === sessionCookie && this.now() - hit.at < MEMORY_CONFIG_TTL_MS) {
+        return hit.view;
+      }
+    }
+    const gateway = this.deps.gateway();
+    if (gateway === void 0) return failure9("unreachable", MESSAGE_NO_GATEWAY);
+    let outcome;
+    try {
+      outcome = await gateway.getMyMemoryConfig(sessionCookie);
+    } catch (error) {
+      const mapped = reasonOfErrorCode(error);
+      if (mapped !== void 0) return failure9(mapped);
+      this.deps.log?.(`hiwork-core: \u8BB0\u5FC6\u914D\u7F6E\u83B7\u53D6\u5931\u8D25\uFF08${errorName2(error)}\uFF09`);
+      return failure9("error");
+    }
+    if (!outcome.ok) {
+      if (outcome.kind === "network") return failure9("unreachable");
+      if (outcome.kind === "http") return failure9(reasonOfStatus(outcome.status));
+      return failure9("error");
+    }
+    const view = projectMemoryConfig(outcome.body);
+    if (view === void 0) {
+      this.deps.log?.("hiwork-core: \u7F51\u5173\u8FD4\u56DE\u7684 memory-config \u4E0D\u5B8C\u6574\uFF08\u7F3A panel_url / service_id / api_key \u4E4B\u4E00\uFF09");
+      return failure9("error");
+    }
+    this.cached = { sessionCookie, view, at: this.now() };
+    return view;
+  }
+  now() {
+    return (this.deps.now ?? Date.now)();
+  }
+};
+function provideMemoryConfig(ctx, deps) {
+  const service = new MemoryConfigProvider(deps);
+  const dispose = ctx.provide(HIWORK_MEMORY_SERVICE, service);
+  return typeof dispose === "function" ? dispose : () => {
+  };
+}
+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 {
+          return { ok: false, kind: "invalid" };
+        }
+        if (body === null || typeof body !== "object") return { ok: false, kind: "invalid" };
+        return { ok: true, body };
+      } catch {
+        return { ok: false, kind: "network" };
+      }
+    }
+  };
+}
+
 // src/office-credentials.ts
 var OFFICE_CREDENTIALS_SERVICE = "hiworkOfficeCredentials";
 var OFFICE_MESSAGE_FALLBACK = {
@@ -6664,7 +6886,7 @@ function parseDeviceInfo(message) {
     ...version === void 0 || version === "" ? {} : { appVersion: version }
   };
 }
-function errorName2(error) {
+function errorName3(error) {
   return error instanceof Error ? error.name : typeof error;
 }
 function registerIpcMessageHandler(ports) {
@@ -6691,12 +6913,12 @@ function registerIpcMessageHandler(ports) {
       authInFlight = true;
       try {
         void Promise.resolve(ports.complete(input)).catch((error) => {
-          log(`hiwork-core: \u6D4F\u89C8\u5668\u6388\u6743\u56DE\u8C03\u5904\u7406\u5F02\u5E38\uFF08${errorName2(error)}\uFF09`);
+          log(`hiwork-core: \u6D4F\u89C8\u5668\u6388\u6743\u56DE\u8C03\u5904\u7406\u5F02\u5E38\uFF08${errorName3(error)}\uFF09`);
         }).finally(() => {
           authInFlight = false;
         });
       } catch (error) {
-        log(`hiwork-core: \u6D4F\u89C8\u5668\u6388\u6743\u56DE\u8C03\u5206\u53D1\u5931\u8D25\uFF08${errorName2(error)}\uFF09`);
+        log(`hiwork-core: \u6D4F\u89C8\u5668\u6388\u6743\u56DE\u8C03\u5206\u53D1\u5931\u8D25\uFF08${errorName3(error)}\uFF09`);
         authInFlight = false;
       }
       return;
@@ -6744,12 +6966,12 @@ async function projectLoginMode(opts) {
       }
     }
   } catch (error) {
-    opts.log?.(`hiwork-core: \u5BA2\u6237\u7AEF\u7B56\u7565\u62C9\u53D6\u5931\u8D25\uFF0C\u767B\u5F55\u65B9\u5F0F\u56DE\u9000 both\uFF08${errorName2(error)}\uFF09`);
+    opts.log?.(`hiwork-core: \u5BA2\u6237\u7AEF\u7B56\u7565\u62C9\u53D6\u5931\u8D25\uFF0C\u767B\u5F55\u65B9\u5F0F\u56DE\u9000 both\uFF08${errorName3(error)}\uFF09`);
   }
   try {
     await opts.state.patch({ set: { loginMode, passwordLogin } });
   } catch (error) {
-    opts.log?.(`hiwork-core: \u5BA2\u6237\u7AEF\u7B56\u7565\u5199\u5165\u5931\u8D25\uFF08${errorName2(error)}\uFF09`);
+    opts.log?.(`hiwork-core: \u5BA2\u6237\u7AEF\u7B56\u7565\u5199\u5165\u5931\u8D25\uFF08${errorName3(error)}\uFF09`);
   }
   return loginMode;
 }
@@ -6995,6 +7217,22 @@ function apply(ctx, config) {
       ctx.logger.warn(message);
     }
   }), "hiwork-core: office credentials");
+  ctx.effect(() => provideIdentity(ctx, {
+    current: () => current(),
+    log: (message) => {
+      ctx.logger.warn(message);
+    }
+  }), "hiwork-core: identity service");
+  ctx.effect(() => provideMemoryConfig(ctx, {
+    resolveSession: async () => (await ports.credentials.resolve(SESSION_REF))?.value,
+    gateway: () => {
+      const baseURL = current().baseURL;
+      return baseURL === void 0 || baseURL === "" ? void 0 : createMemoryConfigGateway(baseURL);
+    },
+    log: (message) => {
+      ctx.logger.warn(message);
+    }
+  }), "hiwork-core: memory config service");
   ctx.effect(() => provideOfficeRelay(ctx, {
     resolveSession: async () => (await ports.credentials.resolve(SESSION_REF))?.value,
     gateway: () => {

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' };
+            }
+        },
+    };
+}

package/lib/types/client/controller.d.ts

@@ -158,8 +158,16 @@ export declare function browserLoginViewOf(value: AiRouterCardSettings | undefin
     browserLoginPending: boolean;
 };
 /**
- * 打开授权页（渲染层职责）：桌面端 `shell.openExternal` 路由接管 https 外链，桌面端无需改动。
- * 命名空间值可被任意写入，因此只放行 http(s)，其余静默忽略。
+ * 在系统浏览器里打开外链（渲染层职责）：桌面端 `shell.openExternal` 路由接管 https 外链，
+ * 桌面端无需改动。
+ *
+ * 只放行 http(s)：调用方给的可能是命名空间里被任意写入的值，也可能是将来变成用户可填的常量，
+ * `javascript:` / `file:` 之类一律静默忽略。URL 非法同样 no-op —— 外链打开失败不该抛错打断调用方。
+ * @param url - 目标地址；缺省 / 非 http(s) / 非法时为 no-op。
+ */
+export declare function openExternalUrl(url: string | undefined): void;
+/**
+ * 打开授权页。
  * @param url - Host 回写的授权页 URL；缺省 / 非法时为 no-op。
  */
 export declare function openAuthorizeUrl(url: string | undefined): void;

package/lib/types/client/daily-card.d.ts

@@ -72,8 +72,10 @@ export declare function decorateDailyCard(doc: Document, quotes: DailyQuoteSourc
 export declare function removeStaleDailyCard(doc: Document): void;
 /**
  * 观察新建任务 hero 页并装饰同页组件：每日一句（服务端下发）+ hero 问候语轮换
- * （见 hero-greeting.ts）。DOM 变更按帧合并，避免流式输出时每个 token 都全文档扫描；
- * 页面完全空闲跨午夜时 MutationObserver 不会触发，靠周期轮询兜底换日（本地日变更
- * 触发重新拉取，服务端日期随之更新）。返回卸载清理函数。
+ * （见 hero-greeting.ts）+ 输入框右上方居右的「使用手册」问号按钮（见 manual-link.ts）。
+ * DOM 变更按帧合并，避免流式输出时每个 token 都全文档扫描；页面完全空闲跨午夜时
+ * MutationObserver 不会触发，靠周期轮询兜底换日（本地日变更触发重新拉取，服务端日期
+ * 随之更新）。三个装饰共用一个观察循环，不各自起 MutationObserver。
+ * 返回卸载清理函数。
  */
 export declare function observeHeroDecorations(doc: Document, quotes: DailyQuoteSource): () => void;

package/lib/types/client/manual-link.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 使用手册地址 —— **全仓唯一一处**写死这个域名的地方（与 pms-client 的 PMS_BASE_URL 同一约定）。
+ *
+ * 为什么固定而不是配置项：官网是组织自建且只有这一个生产部署，做成设置项只会多一个能填错、
+ * 又没人能集中改的地方；真要换部署，改这一个常量、发一版即可。**任何别处都不许再写这个域名**
+ * （包括错误消息、日志、文档示例之外的代码），否则「唯一的基址」立刻变成两处能漂移的真相。
+ */
+export declare const MANUAL_URL = "https://hiworkapp.hivery.cn/manual.html";
+export declare const MANUAL_STYLE_ID = "hiwork-core-manual-style";
+/**
+ * 问号按钮：28×28 的圆形热区、无边框（与输入框自身的图标按钮同语言），hover 才浮出一层浅底。
+ * `margin-left:auto` 是「居右」的全部机制——该行是 flex 容器，自动外边距吃掉剩余空间。
+ * `flex:none` 保证窄窗口下被两个 chip 挤扁时不至于缩成一个点。
+ */
+export declare const MANUAL_STYLE = "\n[data-hiwork-core-manual-entry]{box-sizing:border-box;flex:none;display:inline-flex;align-items:center;justify-content:center;width:28px;height:28px;margin-left:auto;padding:0;border:0;border-radius:999px;background:transparent;color:var(--dsw-alias-label-tertiary,#71717a);font-family:inherit;font-size:14px;line-height:1;font-weight:600;cursor:pointer;user-select:none;transition:background .16s ease,color .16s ease}\n[data-hiwork-core-manual-entry]:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(24,24,27,.06));color:var(--dsw-alias-label-secondary,#3f3f46)}\n[data-hiwork-core-manual-entry]:focus-visible{outline:2px solid var(--dsw-alias-button-info-fill,#4c8dff);outline-offset:2px}\nbody[data-ds-dark-theme] [data-hiwork-core-manual-entry]{color:var(--dsw-alias-label-tertiary,#9ba3b4)}\nbody[data-ds-dark-theme] [data-hiwork-core-manual-entry]:hover{background:var(--dsw-alias-interactive-bg-hover,rgba(255,255,255,.08));color:var(--dsw-alias-label-secondary,#a6adb8)}\n@media (prefers-reduced-motion: reduce){[data-hiwork-core-manual-entry]{transition:none}}\n";
+export declare function ensureManualStyle(doc: Document): void;
+/** 在系统浏览器里打开使用手册（桌面端 shell 接管 https 外链）。 */
+export declare function openManual(): void;
+/**
+ * hero 页里 workspace 行的定位：只在 `[data-phase="hero"]` 下找。
+ * 类名后缀稳定、前缀是构建哈希，故按 `*=` 匹配（同 daily-card 的 `[class$="_headline"]`）。
+ * 行本身缺失（非 hero 页 / 宿主改版）→ null，调用方只做清理。
+ */
+export declare function findManualMount(doc: Document): HTMLElement | null;
+/** 清掉非 hero 状态下（以及行被重建后）残留的按钮节点。 */
+export declare function removeStaleManualEntry(doc: Document): void;
+/**
+ * 幂等装饰：把问号按钮挂到 hero 输入框那一行的末尾（`margin-left:auto` 使其居右）。
+ *
+ * 已挂着且仍在该行内 → 不动（宿主流式重渲染时不做无谓的摘挂，避免按钮闪一下）；
+ * 行不在场（会话记录页 / 登录门禁 / 宿主未渲染）→ 清掉残留。
+ * 只在**最后一个**子节点插入：宿主自己的 chip 顺序不受影响，将来它再往行里加东西，
+ * 我们的按钮仍在右侧。
+ */
+export declare function decorateManualEntry(doc: Document): void;

package/lib/types/identity.d.ts

@@ -0,0 +1,64 @@
+import type { GatewayKey } from './ai-router-client.ts';
+/** cordis 服务名（hiwork-memory 等消费方按此名 `ctx.get` 探测）。 */
+export declare const HIWORK_IDENTITY_SERVICE = "hiworkIdentity";
+/** 当前登录身份的稳定视图；未登录是 `{ loggedIn: false }`（其余字段可省略）。 */
+export interface HiworkIdentityView {
+    /** 是否已登录（有账号名即视为已登录）。false 时其余字段无意义。 */
+    loggedIn: boolean;
+    /**
+     * 隔离键：`u_` + `sha256(账号名)` 前 16 位 hex。
+     * **恒不是账号名原文**；同一账号恒等、不同账号不同。消费方把它当不透明字符串用。
+     */
+    subject?: string;
+    /** 登录账号（网关 LDAP 账号名）；供界面显示，**不得**当隔离键用。 */
+    username?: string;
+    /** 账号显示名（中文名）；命名空间里没有时缺省（界面按既有约定回退 username）。 */
+    displayName?: string;
+    /** 员工姓名（来自 keys 的 `employee_name`）；还没有 keys 或缺省时为 undefined。 */
+    employeeName?: string;
+    /** 团队名（来自 keys 的 `team_name`）；还没有 keys 或缺省时为 undefined。 */
+    teamName?: string;
+}
+/** 本服务对宿主的可调用面（只读、同步、永不抛异常）。 */
+export interface HiworkIdentityService {
+    /** 当前登录身份的稳定视图；未登录返回 { loggedIn: false }。 */
+    current(): HiworkIdentityView;
+}
+/** 身份的原始来源：`ai-router` 命名空间的相关字段 + 最近一次拉取到的 keys 列表。 */
+export interface IdentityState {
+    username?: string | undefined;
+    /** 登录账号的显示名（网关 LDAP displayName）；缺省时视图里也不出现。 */
+    displayName?: string | undefined;
+    /** 最近一次拉取到的当前用户全部虚拟 Key（`employee_name` / `team_name` 的来源）。 */
+    keys?: readonly GatewayKey[] | undefined;
+}
+/** Host 侧依赖：当前命名空间快照读取 + 日志出口。 */
+export interface IdentityDeps {
+    /**
+     * 读一次当前 `ai-router` 命名空间值。**每次 `current()` 都会调用**（本服务不缓存）；
+     * 传 `() => current()` 即可（`AiRouterNamespaceValue` 结构兼容 {@link IdentityState}）。
+     */
+    current(): IdentityState;
+    /** Host 日志出口（只记错误类型，不记账号名之外的任何凭据）。 */
+    log?: ((message: string) => void) | undefined;
+}
+/** `ctx.provide` 的最小端口（结构兼容 cordis Context，便于单测伪造）。 */
+export interface IdentityContext {
+    provide(name: string, value?: unknown): unknown;
+}
+/** 视图字段名的语义名（供消费方日志 / 文档引用，避免各处硬编码字符串）。 */
+export declare const IDENTITY_SUBJECT_PREFIX = "u_";
+/**
+ * 由登录账号派生稳定 subject：`u_` + `sha256(账号名).hex` 的前 16 位。
+ *
+ * 输入先裁掉两侧空白（与视图里的 `username` 同口径），因此 `' alice '` 与 `'alice'`
+ * 派生同一个 subject；大小写不折叠——账号名在网关侧就是区分大小写的。
+ * **本函数绝不返回账号名原文**：subject 会落进存储键 / 目录名，哈希是隔离键
+ * 既能稳定标识同一员工、又不外泄账号的那条界线。
+ */
+export declare function deriveSubject(username: string): string;
+/**
+ * 提供 host 侧服务 `hiworkIdentity`；返回 disposer（交给 `ctx.effect` 管理生命周期，
+ * 插件卸载时服务随 fiber 一并注销）。
+ */
+export declare function provideIdentity(ctx: IdentityContext, deps: IdentityDeps): () => void;

package/lib/types/memory-config.d.ts

@@ -0,0 +1,113 @@
+/** cordis 服务名（hiwork-memory 的 Host 半边按此名 `ctx.get` 探测）。 */
+export declare const HIWORK_MEMORY_SERVICE = "hiworkMemory";
+/** 网关侧端点（跨仓冻结；与 `/api/me/office-config` 同一条会话鉴权）。 */
+export declare const ME_MEMORY_CONFIG_PATH = "/api/me/memory-config";
+/** 成功结果的缓存 TTL：5 分钟。 */
+export declare const MEMORY_CONFIG_TTL_MS: number;
+/** 出网超时（与 `AiRouterClient` 的缺省一致）。 */
+export declare const MEMORY_CONFIG_TIMEOUT_MS = 10000;
+/**
+ * 失败原因（稳定枚举，消费方据此决定提示与自愈策略）：
+ *  - `not-configured`：管理员还没开通团队记忆（网关 503 `MEMORY_NOT_CONFIGURED`）；
+ *  - `unauthenticated`：没有可用会话（未登录 / 会话已失效）；
+ *  - `unreachable`：超时、网络不通、网关地址未配置，或记忆服务自身暂时不可用（504）；
+ *  - `error`：其余非 200、响应不符合契约、宿主内部故障等。
+ */
+export type HiworkMemoryFailureReason = 'not-configured' | 'unauthenticated' | 'unreachable' | 'error';
+/**
+ * 对外视图（camelCase，插件侧唯一接口面）：
+ * 成功时 `ok: true` 且带 `panelUrl` / `serviceId` / `teamIds` / `apiKey`；
+ * 失败时 `ok: false` 且带 `reason` / `message`，**不带任何半个字段**。
+ */
+export interface HiworkMemoryConfigView {
+    ok: boolean;
+    panelUrl?: string;
+    serviceId?: string;
+    teamIds?: string[];
+    apiKey?: string;
+    reason?: HiworkMemoryFailureReason;
+    message?: string;
+}
+/** 本服务对宿主的可调用面（只读、永不抛异常）。 */
+export interface HiworkMemoryService {
+    /** 取当前登录员工的记忆配置；force=true 绕过缓存（用于「重新获取配置」与 401 自愈）。 */
+    config(opts?: {
+        force?: boolean;
+    }): Promise<HiworkMemoryConfigView>;
+}
+/**
+ * 网关侧原始响应（**snake_case**，跨仓冻结契约；本文件是唯一读它的地方）。
+ * 仅供文档与类型自证——真正的读取走宽容投影 {@link projectMemoryConfig}。
+ */
+export interface GatewayMemoryConfig {
+    panel_url: string;
+    service_id: string;
+    /** 按优先级排好；**空数组 / 缺省 = 只用个人域**，不是错误。 */
+    team_ids?: string[];
+    api_key: string;
+    provisioned_at?: string;
+}
+/**
+ * 传输层结果：**失败是数据而不是异常**（本模块不依赖调用方捕获异常来判失败）。
+ *  - `kind: 'http'`：拿到了非 200 状态码；
+ *  - `kind: 'network'`：超时 / 连接失败 / DNS / 请求被中断；
+ *  - `kind: 'invalid'`：200 但响应体不是可用的 JSON 对象（契约破坏）。
+ */
+export type MemoryConfigOutcome = {
+    readonly ok: true;
+    readonly body: unknown;
+} | {
+    readonly ok: false;
+    readonly kind: 'http';
+    readonly status: number;
+} | {
+    readonly ok: false;
+    readonly kind: 'network';
+} | {
+    readonly ok: false;
+    readonly kind: 'invalid';
+};
+/** 网关客户端的 memory-config 子集：只声明本模块真正调用的方法（便于单测打桩计数）。 */
+export interface MemoryConfigGatewayPort {
+    /** 调 `GET /api/me/memory-config`，返回 snake_case 原始响应或一个稳定失败原因。 */
+    getMyMemoryConfig(sessionCookie: string): Promise<MemoryConfigOutcome>;
+}
+/** Host 侧取数依赖：会话解析 + 当前 baseURL 下的网关出网端口。 */
+export interface MemoryConfigDeps {
+    /**
+     * 解析网关会话 cookie。未登录 / 会话缺失返回 undefined。
+     * **返回值只在本模块内部使用**（缓存判等 + 出网），绝不出现在视图与日志里。
+     */
+    resolveSession(): Promise<string | undefined>;
+    /** 当前 baseURL 对应的网关出网端口；baseURL 未配置时返回 undefined。 */
+    gateway(): MemoryConfigGatewayPort | undefined;
+    /** Host 日志出口（只记事件与异常类型名，绝不记凭据 / URL / 响应内容）。 */
+    log?: ((message: string) => void) | undefined;
+    /** 时钟注入（测试用）；缺省 `Date.now`。 */
+    now?: (() => number) | undefined;
+}
+/** `ctx.provide` 的最小端口（结构兼容 cordis Context，便于单测伪造）。 */
+export interface MemoryConfigContext {
+    provide(name: string, value?: unknown): unknown;
+}
+/**
+ * 提供 host 侧服务 `hiworkMemory`；返回 disposer（交给 `ctx.effect` 管理生命周期，
+ * 插件卸载时服务随 fiber 一并注销）。
+ */
+export declare function provideMemoryConfig(ctx: MemoryConfigContext, deps: MemoryConfigDeps): () => void;
+/**
+ * 本端点的出网实现（形状与 `AiRouterClient` 的 `request()` 同款：user-agent 带包版本、
+ * 会话 cookie 走 `cookie` 头、超时用 `AbortSignal.timeout`）。
+ *
+ * **不新造鉴权**：只复用 Host 侧已有的登录会话 cookie（由 `resolveSession` 从凭据库取），
+ * 没有任何密钥/令牌在这一层生成或保存。
+ *
+ * **永不抛异常、绝不回显响应原文**：失败收敛成 {@link MemoryConfigOutcome}，日志与
+ * 异常里都不会出现 URL、状态码或响应体——响应体里带的是该员工自己的记忆凭据。
+ *
+ * `fetchImpl` / `timeoutMs` 仅用于测试注入。
+ */
+export declare function createMemoryConfigGateway(baseURL: string, opts?: {
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): MemoryConfigGatewayPort;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hiwork-core",
-  "version": "0.0.19",
+  "version": "0.0.22",
   "type": "module",
   "description": "HiWork 企业统一登录与模型自动供给插件（ai-router 网关登录，Web 表单，无 CLI 认证）",
   "license": "UNLICENSED",