hiwork-core 0.0.18 → 0.0.21

package/lib/types/client/pms-todo.d.ts

@@ -0,0 +1,357 @@
+/**
+ * 「PMS 个人待办」客户端取数层：经 `/hiwork-pms-todo` loopback RPC 拿到自己的待办、计数，
+ * 并托管登录 / 登出（凭据本身**不经过本层**，见下），交给工作台插件（hiwork-workbench）的
+ * 右栏 tab 渲染。
+ *
+ * 契约见 spec `docs/superpowers/specs/2026-09-17-pms-todo-integration-design.md` §4.1（Host 频道）、
+ * §4.2（`TodoItem`）、§4.3（本面）、§3 D7（**我的任务**：待办之外还要直接查未完成的项目任务）。
+ * 本文件与 `src/client/managed-workbench.ts` 同款，是同一副骨架的**第四条链**，差别只有一处：
+ * 那条链是纯只读，这一条还带「登录 / 登出」两个动作。
+ *
+ * 铁律：
+ *  - **本层不持有任何凭据**：账号密码只在 `login()` 的入参里出现一次，随即交给 Host；access /
+ *    refresh token、PMS 的域名与路径**全都不在本文件里**（client bundle 里搜不到 PMS 凭据，§7）；
+ *  - **不 fetch、不直连 PMS**：一切经 Host 频道——这正是 §3 D6「凭据与数据流都在 Host」在
+ *    客户端一侧的落地形状；
+ *  - **错误码原样透传**：Host 的六个稳定码（`NOT_CONFIGURED` / `UNAUTHORIZED` / `FORBIDDEN` /
+ *    `UPSTREAM_UNAVAILABLE` / `BAD_REQUEST` / `INTERNAL`）由消费方决定文案（未配置 → 引导填
+ *    凭据；`UNAUTHORIZED` → 要求重新输入；`FORBIDDEN` → 「到 PMS 操作」，**不是**重新登录）。
+ *    本层**不改写、不吞掉**它们。
+ *
+ * client bundle 纯度：本文件不 import 任何 `@deepseek-ai/*` 运行时值，也不 import Host 代码
+ * （类型按结构重声明，字段名与契约一致）。
+ */
+/** RPC 频道；必须与 Host `src/pms-todo-bridge.ts` 的 `PMS_TODO_RPC_CHANNEL` 一致（由测试锁定）。 */
+export declare const PMS_TODO_CHANNEL = "/hiwork-pms-todo";
+/**
+ * 端点白名单；必须与 Host `PMS_TODO_RPC_ENDPOINTS` 一致（由测试锁定）。
+ * 顺序即冻结契约里的顺序（`status` / `login` / `logout` 是凭据生命周期，
+ * `today` / `statistics` / `setStatus` 是待办数据，`myTasks` / `completeTask` 是项目任务 —— §3 D7）。
+ */
+export declare const PMS_TODO_ENDPOINTS: readonly ["status", "login", "logout", "today", "statistics", "setStatus", "myTasks", "completeTask"];
+export type PmsTodoEndpoint = (typeof PMS_TODO_ENDPOINTS)[number];
+/** 勾选用的两个字面量（PMS 只认这两个）。 */
+export type PmsTodoStatusValue = 'PENDING' | 'COMPLETED';
+/**
+ * 一条待办（**冻结契约**，spec §4.2 的 `TodoItem` 投影，字段名与 Host 一一对应）。
+ *
+ * 两处开放的形状（消费方按它降级，与工作台清单的 `executor.kind` 同款纪律）：
+ *  - `status` / `priority` / `category` 都是**开放集合**：不认识的取值必须原样出现在这里，
+ *    由消费方自己决定怎么渲染（例如不认识的 `priority` 就不显示徽标），**绝不**因为它不认识
+ *    就把这条待办判为无效——那会让用户看到一份莫名变少的列表；
+ *  - 可选字段按服务端给没给来（没给就没有这个键）。
+ */
+export interface PmsTodoItem {
+    id: number;
+    title: string;
+    description?: string;
+    /** `TODO` | `TEMP` | 将来新增的值。 */
+    category?: string;
+    /** `HIGH` | `MEDIUM` | `LOW` | 将来新增的值。 */
+    priority?: string;
+    /** `PENDING` | `COMPLETED` | 将来新增的值（**原样透传**）。 */
+    status: string;
+    startDate?: string;
+    dueDate?: string;
+    completedTime?: string;
+    /** 服务端判定（客户端不重算）。 */
+    isOverdue?: boolean;
+    isDueSoon?: boolean;
+}
+/** `status` / `login` / `logout` 的返回值（spec §4.1）。 */
+export interface PmsTodoStatus {
+    configured: boolean;
+    loggedIn: boolean;
+    username?: string;
+    /** access token 的绝对过期时刻（ISO 8601）。**不是** token 本身。 */
+    expiresAt?: string;
+}
+/** `today` 的返回值。 */
+export interface PmsTodoToday {
+    items: PmsTodoItem[];
+    /** 本次成功拉取的时刻（ISO 8601）；界面用它显示「更新于 …」。 */
+    fetchedAt: string;
+}
+/** `statistics` 的返回值。 */
+export interface PmsTodoStatistics {
+    total: number;
+    pending: number;
+    completed: number;
+    overdue: number;
+}
+/** setStatus 的返回值（面里折成 void，仓库里保留给诊断与测试）。 */
+export interface PmsTodoSetStatusResult {
+    id: number;
+    status: PmsTodoStatusValue;
+    completedTime?: string;
+}
+/**
+ * 一条**项目任务**（spec §3 D7；Host `PmsTaskItem` 的**结构重声明**——本层不 import Host 代码）。
+ * 数字 / 字符串字段与 PMS `TaskVO` 一一对应；`projectStageName` / `requirementName` /
+ * `moduleName` / `estimatedHours` / `actualHours` 是设计里明确可选的五项（服务端没给就没有这个键）。
+ *
+ * 演进纪律（与 {@link PmsTodoItem} 同款）：`status`（0-待办 / 1-进行中 / 2-已完成 / 3-逾期）与
+ * `priority` 是**数字**，将来 PMS 加档位照样原样透传；`statusName` / `priorityName` 是给人看的
+ * 名字，同样不校验取值。**未知字段忽略**（老 client 不认识的新字段不进契约面）。
+ */
+export interface PmsTaskItem {
+    id: number;
+    taskName: string;
+    description: string;
+    projectId: number;
+    projectName: string;
+    projectStageName?: string;
+    assigneeId: number;
+    assigneeName: string;
+    /** `yyyy-MM-dd HH:mm:ss`；没有截止时间时是空串。 */
+    deadline: string;
+    /** 0-待办 / 1-进行中 / 2-已完成 / 3-逾期。 */
+    status: number;
+    statusName: string;
+    /** 1-低 / 2-中 / 3-高。 */
+    priority: number;
+    priorityName: string;
+    taskType: string;
+    taskTypeName: string;
+    /** 0-待审核 / 1-已通过 / 2-已驳回。 */
+    auditStatus: number;
+    auditStatusName: string;
+    requirementName?: string;
+    moduleName?: string;
+    estimatedHours?: number;
+    actualHours?: number;
+}
+/**
+ * `myTasks` 的返回值（§3 D7）：**分页对象**，不是数组。
+ * 与 `today`（`{items, fetchedAt}`）形状不同是有意的：任务那边服务端就是分页的（`PageResult`），
+ * 本层把 `records` 收进 `items` 但**保留** total / current / size，免得界面想显示「共 N 条」时
+ * 只能数当前这一页。
+ */
+export interface PmsTaskList {
+    items: PmsTaskItem[];
+    total: number;
+    current: number;
+    size: number;
+}
+/** `completeTask` 的返回值（面里折成 void，仓库里保留给诊断与测试）。 */
+export interface PmsTaskCompleteResult {
+    id: number;
+    /** 任务状态数字（完成是 2）。 */
+    status: number;
+}
+/** 登录入参。 */
+export interface PmsTodoLoginInput {
+    username: string;
+    password: string;
+    /** 是否把凭据交给 credentials 服务加密保存（Host 侧语义，见 spec §4.4）。 */
+    remember?: boolean;
+}
+/**
+ * 「PMS 待办」面（spec §4.3 冻结的七项 + §3 D7 追加的两项）。
+ *
+ * 它挂在 `HiWorkCoreClientFace` 上作为**可选成员** `pmsTodo?`：老 core 没有这个面，老
+ * workbench 也不会来取；两侧因此不必同发一个版本——老 core 遇新 workbench 就是
+ * 「请升级 HiWork 客户端」（spec §6 的降级矩阵第一行）。
+ *
+ * ⚠️ **`myTasks` / `completeTask` 是这一面里的两级可选**（版本闸口）：§3 D7 是 2026-09-18 追加的，
+ * 装着的旧 core 有 `pmsTodo` 面但**没有**这两项。所以它们是**可选成员**，消费方必须按
+ * `face.pmsTodo.myTasks !== undefined` 判断（拿不到就只显示待办那一半，而不是崩页、也不是把
+ * 「我的任务」渲染成空列表——那会让人以为任务都完成了）。反过来说，**不许**把它们改成必填：
+ * 那会让新插件在旧 core 上直接抛 TypeError（测试用「只实现旧七项的 face 仍满足本接口」钉死这一点）。
+ */
+export interface PmsTodoFace {
+    /**
+     * 本地镜像（**同步读**，可能是 `undefined`）。
+     *
+     * ⚠️ 它是镜像是**有意的**：界面渲染是同步的，而「有没有配置凭据」是异步来的。镜像由
+     * `login` / `logout` 的返回值、以及**首次调用本方法时的一次惰性探测**写入（结果到达后通知
+     * 订阅者），所以调用方必须 `subscribe()` ——首次渲染很可能拿到 `undefined`，等通知到了再重渲。
+     */
+    readonly status: () => PmsTodoStatus | undefined;
+    /** 登录（凭据经 Host 换成 JWT；密码只在这一次调用里出现，本层不留存）。失败抛错。 */
+    readonly login: (input: PmsTodoLoginInput) => Promise<PmsTodoStatus>;
+    /** 登出（Host 清内存凭据 + 抹掉 credentials 记录）。 */
+    readonly logout: () => Promise<PmsTodoStatus>;
+    /** 今日待办（⚠️ 口径比名字宽：今天 + 明天 + 无截止日期，spec §D4）。失败抛错。 */
+    readonly today: (signal?: AbortSignal) => Promise<PmsTodoToday>;
+    /** total / pending / completed / overdue 计数。失败抛错。 */
+    readonly statistics: (signal?: AbortSignal) => Promise<PmsTodoStatistics>;
+    /**
+     * 勾完成 / 取消完成。
+     *
+     * ⚠️ 副作用（spec §D5）：这是某个任务的最后一条待办时，**PMS 会把项目任务一并标记完成**。
+     * 确认文案是 UI 的职责，本层不替它决定要不要问。
+     */
+    readonly setStatus: (input: {
+        id: number;
+        status: PmsTodoStatusValue;
+    }) => Promise<void>;
+    /**
+     * **我的未完成项目任务**（spec §3 D7）。**可选成员**——旧 core 上没有它（见本接口的抬头）。
+     *
+     * 「谁的任务」由 Host 从凭据记录里取（客户端传不进来），所以这里没有 `userId` 入参。
+     * 失败抛错，错误码可判 `FORBIDDEN`（没有完成任务权限的角色会在**完成**时报它）。
+     */
+    readonly myTasks?: (signal?: AbortSignal) => Promise<PmsTaskList>;
+    /**
+     * 完成一条项目任务（`status=2`）。**可选成员**——旧 core 上没有它（见本接口的抬头）。
+     *
+     * ⚠️ 与 `setStatus`（待办）是**两条不同的上游路径**：待办那条没有权限注解，这一条需要
+     * `task:list:edit`；缺权限时抛 `FORBIDDEN`，界面要按 §3 D7 说「在 HiWork 里没有完成任务的权限，
+     * 请到 PMS 操作」，**不要**当成「登录过期」让用户重新输密码。
+     */
+    readonly completeTask?: (input: {
+        id: number;
+    }) => Promise<void>;
+    /** 订阅镜像变化（登出 / 换账号时会被清空）。返回退订函数。 */
+    readonly subscribe: (listener: () => void) => () => void;
+}
+/** 宿主 loopback RPC 调用面（结构兼容 `ctx.connection.rpc`）。 */
+export interface PmsTodoRpcPort {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/** 带稳定 code 的取数错误（message 已由 Host 消毒，可直接展示）。 */
+export declare class PmsTodoRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 解开 DSH Connection 的结果信封。
+ * 宿主返回 `{ok:true,value}` / `{ok:false,error:{code,message}}`；形状不合法时抛
+ * 通用失败，绝不把未知结构当数据用。
+ *
+ * `ok:false` 一律**抛错**——这是「拉取失败」与「拉到一份空列表」之间的那道闸：把它读成
+ * `value`，一次网络抖动就会变成「今天没有待办」（用户以为活都干完了）。返回 `value` 的唯一
+ * 前提是 `ok === true`。
+ */
+export declare function unwrapPmsTodoResult<T>(value: unknown): T;
+/** 任意异常 → 可展示的 `{code, message}`（传输层异常不暴露原始 message）。 */
+export declare function pmsTodoErrorOf(error: unknown): {
+    code: string;
+    message: string;
+};
+/**
+ * PMS 待办的取数仓库。
+ *
+ * 本地镜像（`status()` 同步读）是有必要的：DSH 的 client 半边在不同插件之间只通过这个面同步取
+ * 状态，而「配没配凭据」是异步来的。镜像**只由成功响应覆写**，失败时不改动它。
+ */
+export declare class PmsTodoStore {
+    private readonly rpc;
+    private current;
+    private readonly listeners;
+    /**
+     * 在飞请求**连同它所属的世代与端点**一起记账。
+     *
+     * 世代：`clear()`（登出 / 换账号）之后，账上那条是**上一个人**发起的，它的待办属于上一个人
+     * ——复用它等于让新账号看到上一个人的待办。端点：`today` 与 `statistics` 的返回值形状不同，
+     * 只有同一个端点的并发调用才允许合并。
+     */
+    private inFlight;
+    /** 世代号：`clear()` 每调用一次 +1，用来作废它之前发起的在飞请求。 */
+    private generation;
+    /** 是否已经为「镜像还空着」的情况探过一次 `status`（避免每次同步读都发一次 RPC）。 */
+    private statusProbed;
+    constructor(rpc: PmsTodoRpcPort);
+    /**
+     * 本地镜像（同步）。从没同步过返回 `undefined`。
+     *
+     * ⚠️ 本方法有一次**惰性探测**：镜像还空着且从没探过时，它顺手发起一次 `status` 端点调用
+     * （结果到达后写镜像 + 通知订阅者）。理由——渲染是同步的，而「配没配凭据」只有主机知道；
+     * 没有这一步，`status` 端点就永远没有调用方，界面也只能靠一次失败的 `today()` 去反推。
+     * 因此调用方看到 `undefined` **不是**「未配置」，而是「还不知道」：必须订阅。
+     */
+    status(): PmsTodoStatus | undefined;
+    /**
+     * 显式去主机取一次状态并写镜像（`status()` 的异步入口）。
+     *
+     * 失败**不改镜像**（保留上一次已知状态），也**不在镜像里记错误**：错误属于这一次调用，
+     * 调用方（或下一次 `today()`）自己决定怎么展示。
+     */
+    refreshStatus(signal?: AbortSignal): Promise<PmsTodoStatus>;
+    /**
+     * 登录（凭据交给 Host；**本层不留存密码、不写任何缓存**）。
+     *
+     * 成功时把返回的状态写进镜像——登录是「身份刚变过」，镜像必须跟着变。
+     */
+    login(input: PmsTodoLoginInput): Promise<PmsTodoStatus>;
+    /** 登出（Host 侧清凭据）；返回登出后的状态并写镜像。 */
+    logout(): Promise<PmsTodoStatus>;
+    /**
+     * 今日待办。
+     *
+     * 不做本地缓存（返回**刚拉到的**那一份）：待办的时效性就是它的全部价值，把上一次的结果当
+     * 「今日」交出去正是这个功能最容易犯的错；界面要离线态时自己留一份 + 标陈旧（spec §6）。
+     */
+    today(signal?: AbortSignal): Promise<PmsTodoToday>;
+    /** total / pending / completed / overdue 计数。 */
+    statistics(signal?: AbortSignal): Promise<PmsTodoStatistics>;
+    /**
+     * 勾完成 / 取消完成。
+     *
+     * 返回值里带服务端回声的 id / status（`PmsTodoFace.setStatus` 折成 `void`；面里不需要它，
+     * 但仓库保留着——回滚那一条待办时用它认人最稳）。
+     */
+    setStatus(input: {
+        id: number;
+        status: PmsTodoStatusValue;
+    }): Promise<PmsTodoSetStatusResult>;
+    /**
+     * **我的未完成项目任务**（spec §3 D7）：`myTasks` 端点的取数。
+     *
+     * 入参是**空对象**，没有 `userId`——「谁的任务」由 Host 从凭据记录里取（客户端连自己的
+     * PMS userId 都拿不到，这是 §3 D6 形状的一部分）。
+     *
+     * 与 `today` 同款：**不做本地缓存**（返回刚拉到的那一份），但**并发调用合并**（同一时刻问两遍
+     * 没有意义；世代判据同其他端点，换账号之后不复用）。
+     */
+    myTasks(signal?: AbortSignal): Promise<PmsTaskList>;
+    /**
+     * **完成一条项目任务**（spec §3 D7）。
+     *
+     * 返回值里带服务端回声的 id / status（`PmsTodoFace.completeTask` 折成 `void`；仓库保留着
+     * ——回滚那一条任务时用它认人最稳）。缺权限时抛 `PmsTodoRpcError('FORBIDDEN')`。
+     *
+     * ⚠️ **刻意不走 {@link PmsTodoStore.call}**（即不参与并发合并）：`dedupe` 的键是**端点名**，
+     * 而这是带参数的命令——把它并进同一格会让「几乎同时完成 A 和 B」的第二次调用**复用第一次的
+     * 结果**，用户以为 B 完成了，其实请求根本没发出去。Host 侧的 `completeTask` 同样不合并
+     * （那里也注明「点了两次就是两次动作」）。
+     */
+    completeTask(input: {
+        id: number;
+    }): Promise<PmsTaskCompleteResult>;
+    /** 订阅镜像变化（右栏 tab 据此重渲染）。返回退订函数。 */
+    subscribe(listener: () => void): () => void;
+    /**
+     * 清空镜像（登出 / 换账号：状态是**按人**的，留着会串号），并**作废在飞的请求**。
+     *
+     * 只清镜像是不够的：清空那一刻正有一次拉取在飞时，那次拉取是**上一个人**发起的。所以世代
+     * +1：那之后的调用者一律不复用旧世代的那条，自己重新发一次 RPC。用世代号而**不是**把
+     * `inFlight` 直接抹成 undefined，理由与 `src/client/managed-workbench.ts` 的同名方法逐字相同
+     * （旧 promise 的 `finally` 会回头把新发起的那条记账清掉，两者互相踩）。
+     *
+     * 同时把 `statusProbed` 复位：新账号的镜像必须能再探一次，否则换账号后 `status()` 会一直
+     * 返回 `undefined` 且再也不去问主机。
+     */
+    clear(): void;
+    /**
+     * 发一次 RPC、解开信封、过第二道形状校验。
+     *
+     * 返回值里带上**发起时的世代**：只有它等于当前世代时，调用方才写镜像（见 {@link adopt}）。
+     */
+    private call;
+    /**
+     * 并发合并：同一世代 + 同一端点撞在一起（面板挂载与手动刷新常常同拍）时共用一次请求，
+     * 且**共用同一个返回值**——两边对「这一次拉到了什么」的判断必须一致。
+     */
+    private dedupe;
+    /**
+     * 采纳一份成功状态：写镜像 + 通知订阅者。
+     *
+     * 世代不符的那一份**不写镜像**（但仍原样返回给调用方）：它是 `clear()` 之前发起的请求，
+     * 属于上一个人。允许它写回等于「清空之后又被上一个人的状态占住」，而换账号时界面正好靠
+     * `status()` 判断该显示引导还是列表。
+     */
+    private adopt;
+    private emit;
+}

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;