@finddatatechnology/yongyi-client 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# @finddatatechnology/yongyi-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+永忆（YongYi / fd-memory）客户端 SDK：把壹座与 agent-runner 里经过旗舰验证的接入件下放为独立 npm 包，任何 harness 集成方与自有产品条线拿到同一套接入件，消灭跨仓漂移拷贝。
+
+**零运行时依赖**——只用 Node 内置 fetch 打永忆内核的 HTTP 面（`/digest`、`/pages`、`/admin/mint`、`/observe`），与内核之间是网络契约，不是代码契约。
+
+- 模块：`ladder`（注入阶梯）、`discipline`（纪律文本单源）、`facts`（五类事实捕获）、`tokens`（令牌铸造缓存）、`observe`（/observe 上报）、`http`（出站死线包装）。
+- 契约：降级开放——注入与捕获的任何失败都以缺席告终，绝不向宿主回合抛错；铸造失败则原样抛给调用方计数处理，绝不静默假装成功。
+- 字节同源：注入块与壹座现行输出逐字节一致（金样固化于 `test/goldens/`，由 paas 现役实现实跑产出）。
+
+```bash
+npm install @finddatatechnology/yongyi-client
+```
+
+## ladder — 注入阶梯
+
+digest 面优先（服务端渲染块），失败降级标题列表，再降级缺席；digest 读死线默认 9000ms（必须高于内核 embed 预算帽 8000ms）。
+
+```js
+import { clusterMemoryFor, memoryInjectionFor, chatMemoryInjectionFor } from "@finddatatechnology/yongyi-client";
+
+const env = {
+  CELL_MEMORY_ENABLED: "1",
+  CELL_MEMORY_URL: "http://127.0.0.1:8080",
+  CELL_MEMORY_PLATFORM_TOKEN: "<平台令牌>",
+  CELL_MEMORY_DATA: "/var/lib/my-harness",   // 令牌磁盘缓存根（0600）
+};
+const cm = await clusterMemoryFor(env, "owner@example.com");
+if (cm) {
+  // 集群车道：prompt 追加记忆块；source ∈ digest | titles | none
+  const { prompt, source } = await memoryInjectionFor(cm, "cluster-42", userPrompt, { k: 5, budget: 1500 });
+  // 聊天车道：项目固定 default；CELL_MEMORY_CHAT_DIGEST=0 为总开关（经 opts.env 传入）
+  const chat = await chatMemoryInjectionFor(cm, userPrompt, { env });
+}
+```
+
+任何失败（服务不可达、digest 超时）都返回空块与 `source: "none"`，prompt 保持未注入形态。
+
+## discipline — 纪律文本单源
+
+双语（zh + en）纪律文本的单源导出。消费者经本接口取文本用于自己的 persona 注入，不得手抄副本；文本更新随 SDK 版本发布。
+
+```js
+import { MEMORY_DISCIPLINE } from "@finddatatechnology/yongyi-client";
+personaSuffix += MEMORY_DISCIPLINE;  // 与壹座现行注入逐字节一致
+```
+
+## facts — 五类事实捕获
+
+封闭五类：`turn`、`health` 落成员 own 分区（`d/<pack>/<member>`）；`decision-opened`、`decision-resolved`、`swap` 落团队 shared 分区。每页携带一等 metadata `{fleetId, memberId, kind}`；进程内有界幂等去重窗（512，键含内容）；未知类型计失败而非误落分区。
+
+```js
+import { fleetMemoryFor, createFleetMemoryCapture, createHealthFlipTracker } from "@finddatatechnology/yongyi-client";
+
+const fm = await fleetMemoryFor(env, "owner@example.com");
+if (fm) {
+  const capture = createFleetMemoryCapture({ memory: fm });
+  const healthFlip = createHealthFlipTracker();
+  if (healthFlip("fleet-9", "writer-a", "failed")) {
+    await capture("fleet-9", "writer-a", "health", "writer-a 开始失败", "digest HTTP 503 ×3");
+  }
+  await capture("fleet-9", "writer-a", "decision-resolved", "采用方案 B", "理由……");
+  // capture 失败只进计数器：capture.failures / capture.captured
+}
+```
+
+## tokens — 令牌铸造与缓存
+
+经平台令牌铸造 person（`u/`）与 deployment（`d/<pack>/<member>`）令牌；磁盘缓存 0600、重启稳定、同身份只铸一次（namespace 校验后复用）。
+
+```js
+import { cellMemoryConfig, personTokenFor, memberTokenFor, memoryMcpEntry } from "@finddatatechnology/yongyi-client";
+
+const cfg = cellMemoryConfig(env);          // 四件套缺一即 null（整体关闭）
+const person = await personTokenFor(cfg, "owner@example.com");   // 失败 → throw，调用方计数
+const member = await memberTokenFor(cfg, { packId: "fleet-9", memberId: "writer-a", ownerEmail: "owner@example.com" });
+const mcpEntry = memoryMcpEntry(cfg.url, person);                // dsh-mcp-client 加载行（http 分支）
+```
+
+## observe — /observe 上报
+
+事件投递到内核 `POST /observe`（封闭集 `turn_outcome | tool_call | health_flip`）。幂等键缺省自动 `crypto.randomUUID()`；`observeFireAndForget` 失败即丢、无重试、有界超时（默认 10s），永不阻塞宿主。
+
+```js
+import { observeFireAndForget, observeOnce } from "@finddatatechnology/yongyi-client";
+
+observeFireAndForget({
+  url: "http://127.0.0.1:8080", token: person,
+  type: "turn_outcome", title: "回合收尾", body: "完成 X，下一步 Y",
+  harness: "claude-code",           // 来源标注（跨 harness 合流）
+});
+// 要结果（如 hook 转发器收尾前确认）用 await observeOnce(...)
+```
+
+## 挂载行形状（参照）
+
+dsh / ACP 载体的记忆挂载行形状（见 `paas/agent-runner/memory-mount.js` 的 `dshMemoryMount` / `acpMemoryMount`）：
+
+```js
+// dsh：dsh-mcp-client 加载行
+{ id: "mcp-fd-memory", name: "@deepseek-ai/dsh-mcp-client",
+  config: { serverName: "fd-memory", failOnStartupError: false, transport: "streamable-http",
+            url: "<url>/mcp", headers: { Authorization: "Bearer <token>" } } }
+// ACP：SDK wire 行（headers 为 {name,value} 数组）
+{ type: "http", name: "fd-memory", url: "<url>/mcp",
+  headers: [{ name: "Authorization", value: "Bearer <token>" }] }
+```
+
+## 构建与测试
+
+```bash
+npm install        # 开发依赖：typescript、@types/node（运行时零依赖）
+npm run build      # tsc -p tsconfig.json → dist/
+npm test           # 编译 src+test → dist-test/，node --test 全绿（mock fetch，无网络）
+npm pack --dry-run # 文件清单：dist/ + README.md，无测试产物泄漏
+```
+
+## License
+
+MIT

package/dist/discipline.d.ts

@@ -0,0 +1 @@
+export declare const MEMORY_DISCIPLINE = "\n\n## \u5DE5\u4F5C\u8BB0\u5FC6\uFF08fd-memory\uFF09/ Working memory (fd-memory)\n\nMCP \u670D\u52A1\u5668 fd-memory \u5DF2\u6302\u8F7D\uFF08\u5DE5\u5177\u540D mcp__fd-memory__*\uFF09\u3002 / An MCP server \"fd-memory\" is mounted (tools appear as mcp__fd-memory__*).\n\n- \u4F1A\u8BDD\u6536\u5C3E\u505A\u6210\u4E86\u6709\u610F\u4E49\u7684\u5DE5\u4F5C\u65F6\uFF0C\u8C03\u7528 memory_handoff_begin \u5199\u4EA4\u63A5\uFF1A\u5B8C\u6210\u4E86\u4EC0\u4E48\u3001\u63A5\u53E3\u5F62\u72B6\u3001\u4E0B\u4E00\u6B65\u3001\u5751\u3001\u6D89\u53CA\u7684\u6587\u4EF6\u3002\n  When you finish meaningful work in a session, call memory_handoff_begin before stopping: what is done, interface shapes, next steps, known pitfalls, files touched.\n- \u5F00\u573A\u82E5\u53EF\u80FD\u5728\u7EED\u4F5C\u5148\u524D\u5DE5\u4F5C\uFF0C\u5148 memory_handoff_list\uFF1B\u6709\u7ED9\u81EA\u5DF1\u7684 open handoff \u5C31\u7528 memory_handoff_accept \u8BA4\u9886\u540E\u7EED\u4F5C\uFF0C\u4E0D\u8981\u91CD\u63A8\u80CC\u666F\u3002\n  When you start and may be resuming prior work, call memory_handoff_list first; if an open handoff is addressed to you, claim it with memory_handoff_accept and continue from it instead of re-deriving the background.\n- \u5F53\u7528\u6237\u660E\u786E\u8BF4\u300C\u8BB0\u4F4F\u8FD9\u4E2A\uFF0F\u522B\u5FD8\u4E86\u300D\uFF0C\u6216\u4F60\u5B66\u5230\u8DE8\u4F1A\u8BDD\u4ECD\u6709\u4EF7\u503C\u7684\u504F\u597D\u6216\u4E8B\u5B9E\u65F6\uFF0C\u8C03\u7528 memory_write_page \u8BB0\u4E00\u6761 note\uFF1B\u4E4B\u540E\u7684\u4F1A\u8BDD\u5F00\u573A\u4F1A\u81EA\u52A8\u5E26\u4E0A\u6700\u8FD1\u7684 note\u3002\u5199\u4E4B\u524D\u5148 memory_query \u67E5\u4E00\u4E0B\u662F\u5426\u5DF2\u6709\u540C\u4E3B\u9898 note\u2014\u2014\u66F4\u65B0\u5C31\u5199\u4E00\u6761\u65B0\u7684\u66F4\u6B63 note\uFF08\u6807\u660E\u300C\u66F4\u6B63\u300D\uFF09\uFF0C\u84B8\u998F\u5C42\u4F1A\u81EA\u52A8\u63A5\u66FF\u65E7\u7ED3\u8BBA\uFF0C\u4F46 note \u539F\u6587\u4F1A\u4E00\u76F4\u90FD\u5728\uFF0C\u91CD\u590D\u5199\u540C\u4E00\u6761\u53EA\u4F1A\u7A00\u91CA\u5F00\u573A\u8BB0\u5FC6\u3002\n  When the user explicitly asks you to remember something, or you learn a preference or fact worth carrying into later sessions, call memory_write_page; recent notes are surfaced automatically at the start of later sessions. Before writing, memory_query for an existing note on the topic \u2014 to update, write a new correction note (marked as such); distillation supersedes the old conclusion automatically, but the raw notes persist, and rewriting the same note only dilutes the opening memory.\n- \u8BFB\u8D44\u6599\u5E93\u7684\u6587\u6863\u65F6\uFF08library \u5DE5\u5177\uFF09\uFF0C\u628A\u4E0E\u672C\u804C\u76F8\u5173\u7684\u8981\u70B9\u6D88\u5316\u6210\u81EA\u5DF1\u7684\u8BB0\u5FC6\uFF1A\u8C03\u7528 memory_write_page \u5199\u8FDB\u81EA\u5DF1\u7684\u5206\u533A\uFF0C\u6B63\u6587\u6CE8\u660E\u51FA\u5904\uFF08\u6765\u81EA\u54EA\u4EFD\u6587\u6863\uFF09\u3002\u6587\u6863\u662F\u539F\u6599\u3001\u8BB0\u5FC6\u662F\u6D88\u5316\u8FC7\u7684\u7ECF\u9A8C\u2014\u2014\u53EA\u6709\u4F60\u7406\u89E3\u5E76\u8F6C\u8FF0\u8FC7\u7684\u5185\u5BB9\u624D\u503C\u5F97\u5199\uFF1B\u539F\u6837\u7167\u6284\u6587\u6863\u4E0D\u7B97\u8BB0\u5FC6\u3002\n  When reading library documents (the library tools), distill what matters for YOUR role into your own memory via memory_write_page, citing the source document in the note body. Documents are raw material; memory is processed experience \u2014 only what you understood and restated is worth writing; verbatim copying is not memory.\n";

package/dist/discipline.js

@@ -0,0 +1,10 @@
+// ── 工作记忆纪律文本 · 单源（自 paas/memory-discipline.js 下放） ─────────────
+//
+// 双语单源（zh + en，一行对一行）：舰队侧（dsh persona 行 / ACP workspace
+// CLAUDE.md）与 cell 侧（预设 persona 后缀）都追加本字符串，两面的引导永不
+// 漂移。工具名无论中英都是 ASCII。消费者 MUST 经本接口取文本，不得手抄副本；
+// 文本更新随 SDK 版本发布。
+//
+// 字节契约：本字符串与壹座现行注入逐字节一致（金样 fixture 见
+// test/goldens/discipline.txt，由 paas 现役实现实跑产出）。
+export const MEMORY_DISCIPLINE = "\n\n## 工作记忆（fd-memory）/ Working memory (fd-memory)\n\nMCP 服务器 fd-memory 已挂载（工具名 mcp__fd-memory__*）。 / An MCP server \"fd-memory\" is mounted (tools appear as mcp__fd-memory__*).\n\n- 会话收尾做成了有意义的工作时，调用 memory_handoff_begin 写交接：完成了什么、接口形状、下一步、坑、涉及的文件。\n  When you finish meaningful work in a session, call memory_handoff_begin before stopping: what is done, interface shapes, next steps, known pitfalls, files touched.\n- 开场若可能在续作先前工作，先 memory_handoff_list；有给自己的 open handoff 就用 memory_handoff_accept 认领后续作，不要重推背景。\n  When you start and may be resuming prior work, call memory_handoff_list first; if an open handoff is addressed to you, claim it with memory_handoff_accept and continue from it instead of re-deriving the background.\n- 当用户明确说「记住这个／别忘了」，或你学到跨会话仍有价值的偏好或事实时，调用 memory_write_page 记一条 note；之后的会话开场会自动带上最近的 note。写之前先 memory_query 查一下是否已有同主题 note——更新就写一条新的更正 note（标明「更正」），蒸馏层会自动接替旧结论，但 note 原文会一直都在，重复写同一条只会稀释开场记忆。\n  When the user explicitly asks you to remember something, or you learn a preference or fact worth carrying into later sessions, call memory_write_page; recent notes are surfaced automatically at the start of later sessions. Before writing, memory_query for an existing note on the topic — to update, write a new correction note (marked as such); distillation supersedes the old conclusion automatically, but the raw notes persist, and rewriting the same note only dilutes the opening memory.\n- 读资料库的文档时（library 工具），把与本职相关的要点消化成自己的记忆：调用 memory_write_page 写进自己的分区，正文注明出处（来自哪份文档）。文档是原料、记忆是消化过的经验——只有你理解并转述过的内容才值得写；原样照抄文档不算记忆。\n  When reading library documents (the library tools), distill what matters for YOUR role into your own memory via memory_write_page, citing the source document in the note body. Documents are raw material; memory is processed experience — only what you understood and restated is worth writing; verbatim copying is not memory.\n";

package/dist/facts.d.ts

@@ -0,0 +1,61 @@
+import { FetchLike, EnvLike } from "./http.js";
+export declare const CAPTURE_DEDUP_MAX = 512;
+/** 封闭五类：五类之外没有第六种口径（映射刻意不可配置）。 */
+export type FleetFactKind = "turn" | "health" | "decision-opened" | "decision-resolved" | "swap";
+export type FactPartition = "own" | "shared";
+export declare const KIND_PARTITION: Readonly<Record<FleetFactKind, FactPartition>>;
+export declare function fleetProjectId(fleetId: unknown): string;
+export declare function memberProjectId(memberId: unknown): string;
+/** 捕获件依赖的写面（fleetMemoryFor 产物或任何同形实现）。 */
+export interface FleetMemoryWriter {
+    writeFact(input: {
+        fleetId: string;
+        memberId: string;
+        kind: string;
+        partition: FactPartition;
+        title: string;
+        body: string;
+    }): Promise<unknown>;
+}
+export interface FleetMemoryCapture {
+    readonly failures: number;
+    readonly captured: number;
+    capture(fleetId: string, memberId: string, kind: FleetFactKind | (string & {}), title: string, body: string): Promise<boolean | null>;
+}
+export declare function createFleetMemoryCapture({ memory, clock }?: {
+    memory?: FleetMemoryWriter;
+    clock?: () => number;
+}): FleetMemoryCapture | null;
+export declare function createHealthFlipTracker(): (fleetId: string, memberId: string, status: string) => boolean;
+/** 舰队记忆客户端三面（writeFact / writeSharedPage / readDigest）。 */
+export interface FleetMemory {
+    writeFact(input: {
+        fleetId: string;
+        memberId: string;
+        kind: string;
+        partition: FactPartition;
+        title: string;
+        body: string;
+    }): Promise<void>;
+    writeSharedPage(input: {
+        fleetId: string;
+        memberId: string;
+        title: string;
+        body: string;
+        metadata?: Record<string, unknown> | null;
+    }): Promise<any>;
+    readDigest(fleetId: string, memberId: string, q?: string, opts?: {
+        k?: number;
+        budget?: number;
+        scope?: "own+shared" | "shared" | "off";
+    }): Promise<{
+        sources: string[];
+        block: string;
+    } | null>;
+}
+export interface FleetDigestSegment {
+    source: "own" | "shared" | "legacy";
+    block: string;
+}
+export declare const FLEET_SEGMENT_LABELS: Record<FleetDigestSegment["source"], string>;
+export declare function fleetMemoryFor(env: EnvLike, ownerEmail: string, fetchImpl?: FetchLike): Promise<FleetMemory | null>;

package/dist/facts.js

@@ -0,0 +1,238 @@
+// ── 舰队工作记忆（自 paas/server/fleet-memory.js 下放） ──────────────────────
+//
+// 舰队（FLEET）工作记忆的 cell 侧车道。成员拆分后，事实落 DEPLOYMENT 命名
+// 空间、用每成员的 deployment 令牌：
+//   岗位私有 (turn / health)      → 成员自己的分区 d/<pack>/<member>
+//   团队事实 (decision-* / swap) → 该队的共享分区（shared）
+// 每页携带一等 metadata {fleetId, memberId, kind}（openspec: agent-memory-
+// foundation）——标题重新只是人话，永不做机器寻址。遗留的 `f/<fleetId>`
+// owner 项目停止收写；其页保持可读，过渡窗内 digest 仍会合成它们（自然衰减
+// ——不再有新行落进去）。
+//
+// 降级开放是契约（spec: capture 失败 MUST NOT 阻塞回合，digest 缺席即段缺
+// 席）：每个失败都是一个计数器，绝不把错误抛进回合。
+//
+// 五类事实（spec: fleet-turn-memory）：turn（经 outcome 的报数摘要）、health
+// （ok↔failed 状态迁移翻转）、decision-opened、decision-resolved、swap。
+// 幂等：进程内有界键集对 (fleetId, memberId, kind, ts) 重放去重；跨重启重放
+// 是非目标（fire-and-forget 捕获）。
+import { cellMemoryConfig, personTokenFor, memberTokenFor } from "./tokens.js";
+import { digestTimeoutMs } from "./ladder.js";
+import { fetchWithTimeout } from "./http.js";
+export const CAPTURE_DEDUP_MAX = 512;
+// 封闭的 own/shared 拆分（spec：五类是封闭集——映射刻意不可配置；这里的第
+// 四种意见就是第四种口径）。turn/health 是岗位的私有产出；决定与换防是全员
+// 必须看见的团队事实。
+export const KIND_PARTITION = {
+    turn: "own",
+    health: "own",
+    "decision-opened": "shared",
+    "decision-resolved": "shared",
+    swap: "shared",
+};
+export function fleetProjectId(fleetId) {
+    const out = String(fleetId ?? "").trim().replace(/[/\\]+/g, "-").slice(0, 128);
+    return out ? `f/${out}` : "f/unknown";
+}
+// d/ 根内成员自有分区的项目名：fd-memory 把 d/<packId>/<memberId> 解析为根
+// "d-<packId>"、项目 "<memberId>"——线上的 project 就是 memberId（registry
+// metadata.agentId 坐标，与 agent-runner/memory-mount.js 在 runner 载体上跑
+// 的是同一条规则）。
+export function memberProjectId(memberId) {
+    const out = String(memberId ?? "").trim().replace(/[/\\]+/g, "-").slice(0, 128);
+    return out || "unknown";
+}
+export function createFleetMemoryCapture({ memory, clock = Date.now } = {}) {
+    if (!memory)
+        return null;
+    const seen = new Set();
+    const seenKeys = [];
+    let failures = 0;
+    let captured = 0;
+    return {
+        get failures() {
+            return failures;
+        },
+        get captured() {
+            return captured;
+        },
+        async capture(fleetId, memberId, kind, title, body) {
+            const ts = clock();
+            // 幂等键包含「内容」而不只是时间戳：固定时钟（测试、快速连发回合）不
+            // 能把两条不同的事实去重掉；真正的重放（同一事实重复投递）仍然会。
+            const key = `${fleetId}|${memberId}|${kind}|${ts}|${title}|${body}`;
+            if (seen.has(key))
+                return null; // 窗内重放 → 幂等
+            seen.add(key);
+            seenKeys.push(key);
+            if (seenKeys.length > CAPTURE_DEDUP_MAX)
+                seen.delete(seenKeys.shift());
+            const partition = KIND_PARTITION[kind];
+            if (!partition) {
+                // 未知类型：绝不静默落进错误分区——计为失败，让运维看见第五类漂移。
+                failures += 1;
+                return false;
+            }
+            try {
+                await memory.writeFact({ fleetId, memberId, kind, partition, title, body });
+                captured += 1;
+                return true;
+            }
+            catch {
+                failures += 1; // 回合永不知情；计数器就是可观测性
+                return false; // false = 失败（null = 重放去重，未尝试）
+            }
+        },
+    };
+}
+// 健康翻转追踪器：记住每成员最近一次落定的状态，只在「翻转」（ok↔failed）
+// 时产出一条观察——留下"谁恢复了/谁开始失败"的记忆叙事，不被逐回合噪音淹没。
+export function createHealthFlipTracker() {
+    const last = new Map();
+    return (fleetId, memberId, status) => {
+        const key = `${fleetId}|${memberId}`;
+        const prev = last.get(key);
+        last.set(key, status);
+        if (prev === undefined || prev === status)
+            return false;
+        return true;
+    };
+}
+// 三段标签：壹座现行字符串，逐字节金样（test/goldens/fleet-digest-block.txt）。
+export const FLEET_SEGMENT_LABELS = {
+    own: "本岗位记忆",
+    shared: "团队记忆",
+    legacy: "历史团队记忆",
+};
+// 返回 { writeFact, writeSharedPage, readDigest } 或 null（配置关 / 无 owner /
+// 铸造失败）——fleetMemoryFor 确立的降级开放姿态。
+export async function fleetMemoryFor(env, ownerEmail, fetchImpl = fetch) {
+    const cfg = cellMemoryConfig(env);
+    if (!cfg || !ownerEmail)
+        return null;
+    try {
+        // person 令牌留给遗留过渡读（f/ digest）；成员令牌按舰队成员懒铸造——
+        // 舰队就是 deployment（d/<fleetId>/<memberId>，shared = d/<fleetId>/
+        // shared），每支队伍有自己的根与自己的团队事实分区。缓存按 (fleetId,
+        // memberId)：换防不换（令牌属于岗位），舰队改名 id 不变。
+        const token = await personTokenFor(cfg, ownerEmail, fetchImpl);
+        const memberTokens = new Map();
+        const tokenForMember = async (fleetId, memberId) => {
+            const key = `${fleetId}|${memberId}`;
+            const cached = memberTokens.get(key);
+            if (cached)
+                return cached;
+            const t = await memberTokenFor(cfg, { packId: fleetId, memberId, ownerEmail }, fetchImpl);
+            memberTokens.set(key, t);
+            return t;
+        };
+        const post = async (tok, project, title, body, metadata) => {
+            // 出站纪律：共享死线包装（默认 env 界）；fetchImpl 保持测试缝。
+            const r = await fetchWithTimeout(`${cfg.url}/pages`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${tok}`, "content-type": "application/json" },
+                body: JSON.stringify({ project, title, body, ...(metadata ? { metadata } : {}) }),
+            }, { fetchImpl });
+            if (!r.ok)
+                throw new Error(`pages HTTP ${r.status}`);
+            return await r.json();
+        };
+        const digestOnce = async (tok, project, q, { k = 5, budget = 1200 } = {}) => {
+            const u = new URL(`${cfg.url}/digest`);
+            u.searchParams.set("project", project);
+            if (q)
+                u.searchParams.set("q", String(q));
+            u.searchParams.set("k", String(k));
+            u.searchParams.set("budget", String(budget));
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), digestTimeoutMs(env));
+            try {
+                const r = await fetchImpl(u, { headers: { authorization: `Bearer ${tok}` }, signal: controller.signal });
+                if (!r.ok)
+                    throw new Error(`digest HTTP ${r.status}`);
+                const json = await r.json();
+                // fd-memory 的面把渲染文本叫 `digest`；下面的阶梯读 `.block`——在此
+                // 归一化，让每一段都说同一种形状。
+                return { block: typeof json?.digest === "string" ? json.digest : (json?.block ?? "") };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        };
+        return {
+            // 拆分写：分区来自封闭类型映射；metadata 携带结构化三元组，标题保持
+            // 人话。重要：两个分区都走成员的 deployment 令牌——fd-memory 只对
+            // deployment 令牌把项目名 "shared" 解析到该队的共享分区
+            // （d/<fleetId>/shared），这里用 person 令牌会把团队事实误归到 owner
+            // 的 u/ 根。
+            async writeFact({ fleetId, memberId, kind, partition, title, body }) {
+                const metadata = { fleetId, memberId, kind };
+                const tok = await tokenForMember(fleetId, memberId);
+                if (partition === "own") {
+                    await post(tok, memberProjectId(memberId), title, body, metadata);
+                }
+                else {
+                    await post(tok, "shared", title, body, metadata);
+                }
+            },
+            // 团队级直接共享写（本来就知道自己是团队级的车道用，如其他载体上的
+            // 换防记录员）。走执行成员的 deployment 令牌，理由同上。
+            async writeSharedPage({ fleetId, memberId, title, body, metadata }) {
+                const tok = await tokenForMember(fleetId, memberId);
+                await post(tok, "shared", title, body, metadata ?? null);
+            },
+            // fleetContext 记忆段——阶梯在一个预算下合成三个来源，按成员的知识
+            // 范围门控：成员自有分区、舰队共享分区（两者都走成员的 deployment
+            // 令牌——共享项目名只对 deployment 令牌解析到 d/<fleetId>/shared），
+            // 以及经 person 令牌的遗留 f/ digest（过渡窗；随停写自然衰减）。每段
+            // 以同样的预算纪律服务端渲染；任何一段失败只丢那一段，绝不丢整节。
+            // scope "shared" 跳过自有探测；"off" 到不了这个调用（调用方先查）。
+            async readDigest(fleetId, memberId, q, { k = 5, budget = 1200, scope = "own+shared" } = {}) {
+                const segBudget = Math.max(64, Math.floor(budget / 3));
+                let memberTok = null;
+                if (scope === "own+shared") {
+                    try {
+                        memberTok = await tokenForMember(fleetId, memberId);
+                    }
+                    catch {
+                        // 成员令牌就是 own/shared 两段的身份——没有它两段都丢，只剩遗留
+                        // f/ digest 能渲染
+                    }
+                }
+                const segments = [];
+                const probes = [
+                    { name: "own", project: memberProjectId(memberId), token: memberTok, q: q ?? "" },
+                    { name: "shared", project: "shared", token: memberTok, q: q ?? "" },
+                    { name: "legacy", project: fleetProjectId(fleetId), token, q: (q ?? "") || String(memberId ?? "") },
+                ];
+                for (const probe of probes) {
+                    if (!probe.token)
+                        continue;
+                    try {
+                        const out = await digestOnce(probe.token, probe.project, probe.q, { k, budget: segBudget });
+                        if (typeof out?.block === "string" && out.block.trim()) {
+                            segments.push({ source: probe.name, block: out.block });
+                        }
+                    }
+                    catch {
+                        // 单段失败是计数器形状的缺席，不是错误
+                    }
+                }
+                if (segments.length === 0)
+                    return null;
+                // 渲染器自己的头每段重复——阶梯给每个来源标一次签、拼接正文；空段
+                // 消失。
+                return {
+                    sources: segments.map((s) => s.source),
+                    block: segments
+                        .map((s) => `【${FLEET_SEGMENT_LABELS[s.source]}】\n${s.block}`)
+                        .join("\n\n"),
+                };
+            },
+        };
+    }
+    catch (e) {
+        console.warn(`[fleet-memory] unavailable (degrade open): ${e?.message || e}`);
+        return null;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,33 @@
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 10000;
+/** 环境对象形状（process.env 的结构子集，便于测试注入）。 */
+export type EnvLike = Record<string, string | undefined>;
+/** 响应的最小结构面：SDK 各面只用 ok/status/json。 */
+export interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    json(): Promise<any>;
+}
+/** 出站请求 init 的最小面。 */
+export interface FetchInitLike {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+/**
+ * 可注入的 fetch 缝（测试缝）：签名比全局 fetch 窄，全局 fetch 天然可赋值。
+ * 参照 paas 各面的做法——fetchImpl 永远作为参数保留。
+ */
+export type FetchLike = (input: string | URL, init?: FetchInitLike) => Promise<FetchResponseLike>;
+export declare function platformFetchTimeoutMs(env?: EnvLike): number;
+export declare class FetchTimeoutError extends Error {
+    constructor(timeoutMs: number, url?: string);
+    code: string;
+    retryable: boolean;
+    timeoutMs: number;
+}
+export declare function fetchWithTimeout(input: string | URL, init?: FetchInitLike, opts?: {
+    timeoutMs?: number;
+    fetchImpl?: FetchLike;
+    env?: EnvLike;
+}): Promise<FetchResponseLike>;

package/dist/http.js

@@ -0,0 +1,69 @@
+// ── 出站 fetch 超时纪律（自 paas/lib/fetch-with-timeout.js 下放） ────────────
+//
+// SDK 对内核（fd-memory）的每一次出站调用都有界：fetchWithTimeout() 以默认
+// 死线（环境 PLATFORM_FETCH_TIMEOUT_MS，10s）包住 fetch，任何调用点可按次
+// 覆盖。死线到点以结构化 FetchTimeoutError（code "FETCH_TIMEOUT"）失败，绝
+// 不悬挂。死线覆盖到「响应头到达」为止；之后的正文流式不在此约束内（内核
+// /digest 等面都是一次性 JSON，不涉及长流）。
+//
+// SDK 纪律：零运行时依赖——本模块只用 Node 内置的全局 fetch / AbortController。
+export const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+const TIMEOUT_ENV_KEY = "PLATFORM_FETCH_TIMEOUT_MS";
+// 生效死线在调用时读取（而非模块加载时），测试与一次性脚本可经 env 重调。
+export function platformFetchTimeoutMs(env = process.env) {
+    const raw = Number(env[TIMEOUT_ENV_KEY]);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_FETCH_TIMEOUT_MS;
+}
+export class FetchTimeoutError extends Error {
+    constructor(timeoutMs, url) {
+        super(`outbound fetch timed out after ${timeoutMs}ms${url ? `: ${url}` : ""}`);
+        this.name = "FetchTimeoutError";
+        this.code = "FETCH_TIMEOUT";
+        this.retryable = true;
+        this.timeoutMs = timeoutMs;
+    }
+    code;
+    retryable;
+    timeoutMs;
+}
+// 合成调用方 signal 与死线 signal，让两者都能取消：调用方中止保留自身原因
+// （AbortError），死线到点把 FetchTimeoutError 作为中止原因带上。
+// AbortSignal.any 自 Node 20.3 起可用；监听器兜底覆盖更老运行时。
+function composeSignals(caller, deadline) {
+    if (!caller)
+        return deadline.signal;
+    if (caller.aborted)
+        return caller;
+    if (typeof AbortSignal.any === "function")
+        return AbortSignal.any([caller, deadline.signal]);
+    const composed = new AbortController();
+    const relay = (from) => () => composed.abort(from.reason);
+    caller.addEventListener("abort", relay(caller), { once: true });
+    deadline.signal.addEventListener("abort", relay(deadline.signal), { once: true });
+    return composed.signal;
+}
+// 共享包装。opts.timeoutMs 按调用点覆盖 env 默认；opts.fetchImpl 穿插模块注入
+// 的 fetch 缝（可测性）；opts.env 从非 process 环境对象读默认值。拒绝原样
+// 上抛，唯一例外：死线到点以 FetchTimeoutError 拒绝——中止原因随 signal 走，
+// 尊重 init.signal 的注入式 fetch 自然会把它暴露出来。
+export function fetchWithTimeout(input, init = {}, opts = {}) {
+    const impl = opts.fetchImpl ?? fetch;
+    const timeoutMs = Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0
+        ? opts.timeoutMs
+        : platformFetchTimeoutMs(opts.env);
+    // 壹座原样：URL 对象上没有 .url 字段，错误消息里的地址回退为空串。
+    const url = typeof input === "string" ? input : (input?.url ?? "");
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(new FetchTimeoutError(timeoutMs, url)), timeoutMs);
+    let promise;
+    try {
+        promise = Promise.resolve(impl(input, { ...init, signal: composeSignals(init.signal, deadline) }));
+    }
+    catch (err) {
+        // 同步抛出的 impl（坏 mock、非法请求形状）不能泄漏挂起的定时器。
+        clearTimeout(timer);
+        throw err;
+    }
+    // 死线只覆盖「等响应头」；promise 落定后定时器即撤，正文自由流动。
+    return promise.finally(() => clearTimeout(timer));
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./http.js";
+export * from "./discipline.js";
+export * from "./tokens.js";
+export * from "./ladder.js";
+export * from "./facts.js";
+export * from "./observe.js";

package/dist/index.js

@@ -0,0 +1,20 @@
+// ── @finddatatechnology/yongyi-client · 出口面 ───────────────────────────────
+//
+// 永忆（fd-memory）客户端 SDK：把壹座与 agent-runner 里经过旗舰验证的接入件
+// 下放为独立发包。零运行时依赖——只用 Node 内置 fetch 打内核 HTTP 面
+// （/digest、/pages、/admin/mint、/observe），与服务端之间是网络契约，不是
+// 代码契约。
+//
+// 模块地图（design D6）：
+//   ladder     注入阶梯 digest→titles→absent（自 cluster-memory.js 移植）
+//   discipline 纪律文本双语单源（自 memory-discipline.js 移植）
+//   facts      五类事实捕获 own/shared（自 fleet-memory.js 移植）
+//   tokens     person/deployment 令牌铸造 + 磁盘缓存 0600（自 cell-memory.js 移植）
+//   observe    /observe 上报客户端（幂等键、失败即丢）
+//   http       出站 fetch 死线包装（fetchImpl 测试缝、FetchTimeoutError）
+export * from "./http.js";
+export * from "./discipline.js";
+export * from "./tokens.js";
+export * from "./ladder.js";
+export * from "./facts.js";
+export * from "./observe.js";

package/dist/ladder.d.ts

@@ -0,0 +1,72 @@
+import { FetchLike, EnvLike } from "./http.js";
+export declare function clusterProjectId(clusterId: unknown): string;
+export declare function digestTimeoutMs(env?: EnvLike): number;
+/** 一条记忆页的最小读取面（/pages GET 的行形状）。 */
+export interface MemoryPage {
+    title?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+}
+/** /digest 响应的服务端形状：渲染文本在 `digest` 字段。 */
+export interface DigestDoc {
+    digest?: string;
+}
+export type LadderSource = "digest" | "titles" | "none";
+/** 阶梯依赖的客户端最小面（createClusterMemoryClient 的产物子集）。 */
+export interface LadderMemory {
+    readDigest(project: string, q: string, opts?: {
+        k?: number;
+        budget?: number;
+    }): Promise<DigestDoc>;
+    readShared(project: string, limit?: number): Promise<MemoryPage[]>;
+}
+/** 集群记忆客户端三面（/digest、/pages 读、/pages 写）。 */
+export interface ClusterMemoryClient extends LadderMemory {
+    writeDigest(project: string, title: string, body: string): Promise<any>;
+}
+export interface ClusterClientOptions {
+    url: string;
+    token: string;
+    fetchImpl?: FetchLike;
+    /** digest 读死线（毫秒）；缺省读 env.CELL_MEMORY_DIGEST_TIMEOUT_MS，默认 9000。 */
+    timeoutMs?: number;
+    env?: EnvLike;
+}
+export declare function createClusterMemoryClient(opts: ClusterClientOptions): ClusterMemoryClient;
+export declare function clusterMemoryFor(env: EnvLike, ownerEmail: string, fetchImpl?: FetchLike): Promise<ClusterMemoryClient | null>;
+export interface DigestLadderOptions {
+    digestOn: boolean;
+    k: number;
+    budget: number;
+    titlesLabel: string;
+    warnTag: string;
+    warnName: string;
+}
+export interface LadderResult {
+    block: string;
+    source: LadderSource;
+}
+export declare function digestLadder(cm: LadderMemory | null, project: string, prompt: string, { digestOn, k, budget, titlesLabel, warnTag, warnName }: DigestLadderOptions): Promise<LadderResult>;
+export interface LadderCallOptions {
+    /** 读取 CELL_MEMORY_* 键的环境对象；缺省 process.env。 */
+    env?: EnvLike;
+    /** 显式覆盖 digest 面开关（集群键 env.CELL_MEMORY_DIGEST，聊天键 CELL_MEMORY_CHAT_DIGEST）。 */
+    digestOn?: boolean;
+    /** digest 召回条数；缺省 env.CELL_MEMORY_DIGEST_K，默认 5。 */
+    k?: number;
+    /** digest 字符预算；缺省 env.CELL_MEMORY_DIGEST_BUDGET，默认 1500。 */
+    budget?: number;
+}
+export declare const CHAT_TITLES_LABEL = "\u3010\u5DE5\u4F5C\u8BB0\u5FC6\u3011\u6B64\u524D\u4F1A\u8BDD\u7684\u6C89\u6DC0\uFF0C\u4F9B\u53C2\u8003\uFF1A";
+export declare const CLUSTER_TITLES_LABEL = "\u3010\u96C6\u7FA4\u5171\u4EAB\u8BB0\u5FC6\u3011\u672C\u96C6\u7FA4\u6B64\u524D\u56DE\u5408\u7684\u6C89\u6DC0\uFF0C\u4F9B\u53C2\u8003\uFF1A";
+export declare function memoryInjectionFor(clusterMemory: LadderMemory | null, clusterId: string, prompt: string, opts?: LadderCallOptions): Promise<{
+    prompt: string;
+    source: LadderSource;
+}>;
+export declare function chatMemoryInjectionFor(clusterMemory: LadderMemory | null, prompt: string, opts?: LadderCallOptions): Promise<{
+    prompt: string;
+    source: LadderSource;
+}>;
+export declare function chatMemoryBlockFor(ownerEmail: string | null | undefined, query: string, env?: EnvLike, fetchImpl?: FetchLike): Promise<LadderResult>;
+export declare function chatMemoryClientFor(ownerEmail: string | null | undefined, env?: EnvLike, fetchImpl?: FetchLike): Promise<ClusterMemoryClient | null>;
+export declare function chatPromptWithMemory(ownerEmail: string | null | undefined, prompt: string, env?: EnvLike, fetchImpl?: FetchLike): Promise<string>;

package/dist/ladder.js

@@ -0,0 +1,217 @@
+// ── 召回注入阶梯（自 paas/server/cluster-memory.js 下放） ────────────────────
+//
+// 集群共享记忆的 cell 侧车道：owner 的 person 令牌经 fd-memory 平台缝 /pages
+// 面读写集群-id 项目的页。降级开放是契约：任何失败返回缺席（空块），集群/
+// 聊天回合照常进行——记忆永不弄破回合。
+//
+// 注入阶梯（add-cluster-digest-injection design D3）：digest 面优先（服务端
+// 渲染块，经续作评测验证），失败降级标题列表，再降级缺席。每一级降级恰一条
+// warn；记忆永不失败一个回合。返回块本身（记忆关闭/不可用时为空串），调用方
+// 拼装自己的 prompt 时追加的文本与聊天车道产出的完全一致。
+//
+// 字节同源纪律：标题标签与行组装字符串与壹座现行注入逐字节一致，金样固化在
+// test/goldens/（由 paas 现役实现实跑产出）。
+//
+// 环境参数化：壹座侧从 process.env 读的开关与默认（CELL_MEMORY_DIGEST*）在
+// SDK 里参数化为 options（env 字段仍可传环境对象），默认值不变。
+import { cellMemoryConfig, personTokenFor } from "./tokens.js";
+import { fetchWithTimeout } from "./http.js";
+export function clusterProjectId(clusterId) {
+    const out = String(clusterId ?? "").trim().replace(/[/\\]+/g, "-").slice(0, 128);
+    return out || "cluster";
+}
+// digest 读超时（fix-digest-adaptive-embed-deadline）。必须高于 fd-memory 的
+// 内部 embed 预算帽，否则会在被叫方仍在收尾时挂断——块整个丢掉而不是收到
+// 降级形态。默认 9000（帽 8000 + 传输余量）；设得比帽还低，阶梯会直接跳过
+// digest 级——这正是这条配置要暴露的错误用法。
+export function digestTimeoutMs(env = process.env) {
+    const raw = Number(env.CELL_MEMORY_DIGEST_TIMEOUT_MS ?? 9000);
+    const n = Number.isFinite(raw) && raw > 0 ? Math.round(raw) : 9000;
+    return Math.max(500, Math.min(60_000, n));
+}
+// 从壹座 cell 配置构建的客户端三面（clusterMemoryFor 的 faces 移植）。
+export function createClusterMemoryClient(opts) {
+    const { url, token } = opts;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const env = opts.env ?? process.env;
+    return {
+        async readShared(project, limit = 5) {
+            // 出站纪律：共享死线包装（默认 env 界）；fetchImpl 保持测试缝。
+            const r = await fetchWithTimeout(`${url}/pages?project=${encodeURIComponent(project)}&limit=${limit}`, { headers: { authorization: `Bearer ${token}` } }, { fetchImpl });
+            if (!r.ok)
+                throw new Error(`pages HTTP ${r.status}`);
+            const doc = await r.json();
+            return Array.isArray(doc?.pages) ? doc.pages : [];
+        },
+        async writeDigest(project, title, body) {
+            const r = await fetchWithTimeout(`${url}/pages`, {
+                method: "POST",
+                headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+                body: JSON.stringify({ project, title, body }),
+            }, { fetchImpl });
+            if (!r.ok)
+                throw new Error(`pages HTTP ${r.status}`);
+            return await r.json();
+        },
+        // digest 读面（add-cluster-digest-injection）：服务端渲染块——一次机会、
+        // 不重试（调用方的阶梯在任何失败时降级标题列表）。
+        //
+        // 超时（fix-digest-adaptive-embed-deadline）：这里曾有平的 5s，低于
+        // fd-memory 自身的 embed 预算（8000ms）。嵌入上游慢时，fd-memory 还在
+        // 做答案而我们已挂断——块整个丢掉而不是收到降级（关键词）形态。调用方
+        // 必须比被叫方的内部预算更有耐心，故默认 9s；快路径毫秒级零成本，可配置。
+        async readDigest(project, q, { k = 5, budget = 1500 } = {}) {
+            const u = new URL(`${url}/digest`);
+            u.searchParams.set("project", project);
+            u.searchParams.set("q", String(q ?? ""));
+            u.searchParams.set("k", String(k));
+            u.searchParams.set("budget", String(budget));
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? digestTimeoutMs(env));
+            try {
+                const r = await fetchImpl(u, { headers: { authorization: `Bearer ${token}` }, signal: controller.signal });
+                if (!r.ok)
+                    throw new Error(`digest HTTP ${r.status}`);
+                return await r.json();
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+// 壹座位形的整体构建（clusterMemoryFor 移植）：返回客户端或 null（配置关 /
+// 无 owner / 铸造失败）。person 令牌与记忆挂载铸的是同一枚并缓存磁盘——每
+// owner 一铸，重启稳定。
+export async function clusterMemoryFor(env, ownerEmail, fetchImpl = fetch) {
+    const cfg = cellMemoryConfig(env);
+    if (!cfg || !ownerEmail)
+        return null;
+    try {
+        const token = await personTokenFor(cfg, ownerEmail, fetchImpl);
+        return createClusterMemoryClient({ url: cfg.url, token, fetchImpl, env });
+    }
+    catch (e) {
+        console.warn(`[cluster-memory] unavailable (degrade open): ${e?.message || e}`);
+        return null;
+    }
+}
+// 阶梯本体：digest 面优先，降级标题列表，再降级缺席。每个降级级恰一条 warn。
+export async function digestLadder(cm, project, prompt, { digestOn, k, budget, titlesLabel, warnTag, warnName }) {
+    if (!cm)
+        return { block: "", source: "none" };
+    if (digestOn) {
+        try {
+            const d = await cm.readDigest(project, prompt, { k, budget });
+            if (d?.digest)
+                return { block: d.digest, source: "digest" };
+        }
+        catch (e) {
+            console.warn(`[${warnTag}] digest read failed for ${warnName} (fallback to titles): ${e?.message || e}`);
+        }
+    }
+    try {
+        const sharedPages = await cm.readShared(project, 5);
+        if (sharedPages.length) {
+            const lines = sharedPages.map((p) => `- ${p.title}（${String(p.updated_at ?? "").slice(0, 10)}）`).join("\n");
+            return { block: `${titlesLabel}\n${lines}`, source: "titles" };
+        }
+    }
+    catch (e) {
+        console.warn(`[${warnTag}] shared-memory read failed for ${warnName} (degrade open): ${e?.message || e}`);
+    }
+    return { block: "", source: "none" };
+}
+const ladderEnv = (env) => ({
+    k: Number(env.CELL_MEMORY_DIGEST_K ?? 5) || 5,
+    budget: Number(env.CELL_MEMORY_DIGEST_BUDGET ?? 1500) || 1500,
+});
+// 标题标签：壹座现行字符串，逐字节金样（test/goldens/*-titles-block.txt）。
+export const CHAT_TITLES_LABEL = "【工作记忆】此前会话的沉淀，供参考：";
+export const CLUSTER_TITLES_LABEL = "【集群共享记忆】本集群此前回合的沉淀，供参考：";
+// 聊天车道阶梯配置：prompt 包装器与块读取面共用同一份，两面永不漂移
+// （房间车道从这里读块）。项目固定 "default"——person 令牌的 MCP 写入落点
+// （fd-memory namespaceParts），读面即写面。
+const chatLadder = (cm, query, env) => digestLadder(cm, "default", String(query ?? ""), {
+    digestOn: true,
+    ...ladderEnv(env),
+    titlesLabel: CHAT_TITLES_LABEL,
+    warnTag: "chat-memory",
+    warnName: "default",
+});
+// 集群车道注入：CELL_MEMORY_DIGEST=0 是只跳过 digest 级的回滚杆。签名与行为
+// 不变（env 语义经 options.env 传入）。
+export async function memoryInjectionFor(clusterMemory, clusterId, prompt, opts = {}) {
+    const env = opts.env ?? process.env;
+    const envDefaults = ladderEnv(env);
+    const { block, source } = await digestLadder(clusterMemory, clusterProjectId(clusterId), prompt, {
+        digestOn: opts.digestOn ?? env.CELL_MEMORY_DIGEST !== "0",
+        k: opts.k ?? envDefaults.k,
+        budget: opts.budget ?? envDefaults.budget,
+        titlesLabel: CLUSTER_TITLES_LABEL,
+        warnTag: "cluster",
+        warnName: clusterId,
+    });
+    return { prompt: block ? `${prompt}\n\n${block}` : prompt, source };
+}
+// 聊天车道（add-chat-memory-injection D2/D3）：owner 记忆根上的同一阶梯。
+// CELL_MEMORY_CHAT_DIGEST=0 是聊天车道的总开关（spec：prompt 逐字节一致、
+// 零 fd-memory 请求）——不同于集群杆只跳 digest 级；k/budget 与集群共用。
+export async function chatMemoryInjectionFor(clusterMemory, prompt, opts = {}) {
+    const env = opts.env ?? process.env;
+    if (opts.digestOn != null ? !opts.digestOn : env.CELL_MEMORY_CHAT_DIGEST === "0") {
+        return { prompt, source: "none" };
+    }
+    const { block, source } = await chatLadder(clusterMemory, prompt, env);
+    return { prompt: block ? `${prompt}\n\n${block}` : prompt, source };
+}
+// 聊天车道的块面（add-unified-memory-and-outputs D7）：自己拼 prompt 的调用方
+// （智语房间回合）得到同一文本、同一开关，车道与聊天永不分歧。关/杀/不可用
+// 一律 ""——永不抛。
+export async function chatMemoryBlockFor(ownerEmail, query, env = process.env, fetchImpl = fetch) {
+    if (!ownerEmail || env.CELL_MEMORY_CHAT_DIGEST === "0")
+        return { block: "", source: "none" };
+    try {
+        const cm = await chatMemoryClientFor(ownerEmail, env, fetchImpl);
+        if (!cm)
+            return { block: "", source: "none" };
+        return await chatLadder(cm, query, env);
+    }
+    catch (e) {
+        console.warn(`[chat-memory] block read failed for ${ownerEmail} (degrade open): ${e?.message || e}`);
+        return { block: "", source: "none" };
+    }
+}
+// ws 聊天车道的客户端缓存：每 owner email 一个记忆客户端。已解析的客户端按
+// 进程生命周期缓存；配置开着时的 null 结果（瞬时铸造失败）会被丢弃，下一回
+// 合重试而不是黑到重启。
+const chatClients = new Map();
+export async function chatMemoryClientFor(ownerEmail, env = process.env, fetchImpl = fetch) {
+    if (!ownerEmail)
+        return null;
+    let p = chatClients.get(ownerEmail);
+    if (!p) {
+        p = clusterMemoryFor(env, ownerEmail, fetchImpl);
+        chatClients.set(ownerEmail, p);
+    }
+    const cm = await p;
+    if (!cm && cellMemoryConfig(env))
+        chatClients.delete(ownerEmail);
+    return cm;
+}
+// ws 车道接线（add-chat-memory-injection D1）：无身份或任何失败都不动 prompt
+// ——记忆永不失败一次聊天回合。
+export async function chatPromptWithMemory(ownerEmail, prompt, env = process.env, fetchImpl = fetch) {
+    if (!ownerEmail)
+        return prompt;
+    try {
+        const cm = await chatMemoryClientFor(ownerEmail, env, fetchImpl);
+        if (!cm)
+            return prompt;
+        return (await chatMemoryInjectionFor(cm, prompt, { env })).prompt;
+    }
+    catch (e) {
+        console.warn(`[chat-memory] injection failed for ${ownerEmail} (degrade open): ${e?.message || e}`);
+        return prompt;
+    }
+}

package/dist/observe.d.ts

@@ -0,0 +1,35 @@
+import { FetchLike, EnvLike } from "./http.js";
+/** /observe 的封闭事件集（内核侧权威；运行时透传，4xx 即裁决）。 */
+export type ObserveEventType = "turn_outcome" | "tool_call" | "health_flip";
+export interface ObserveInput {
+    /** 永忆内核基址（尾部斜杠容忍）。 */
+    url: string;
+    /** person 或 deployment 令牌。 */
+    token: string;
+    type: ObserveEventType;
+    title: string;
+    body: string;
+    /** 幂等键；缺省自动 crypto.randomUUID()。 */
+    idempotencyKey?: string;
+    /** 成员/agent 标识（可选）。 */
+    subject?: string;
+    /** ISO8601；缺省=服务端时钟。 */
+    ts?: string;
+    /** 来源标注（跨 harness 合流，design D5）。 */
+    harness?: string;
+    metadata?: Record<string, unknown>;
+    /** 有界超时（毫秒）；缺省 10s（PLATFORM_FETCH_TIMEOUT_MS 语义）。 */
+    timeoutMs?: number;
+    fetchImpl?: FetchLike;
+    env?: EnvLike;
+}
+export interface ObserveOutcome {
+    delivered: boolean;
+    status?: number;
+    page?: any;
+    truncated?: boolean;
+    error?: string;
+}
+export declare function newIdempotencyKey(): string;
+export declare function observeOnce(input: ObserveInput): Promise<ObserveOutcome>;
+export declare function observeFireAndForget(input: ObserveInput): void;

package/dist/observe.js

@@ -0,0 +1,68 @@
+// ── /observe 客户端（新写，design D6） ───────────────────────────────────────
+//
+// 面向内核 POST /observe（design D3 schema）的客户端：幂等键调用方生成（缺
+// 省自动 crypto.randomUUID()），重复投递由内核按 (namespace, idempotency_key)
+// 幂等。上报纪律与捕获契约对齐：fire-and-forget、失败即丢、无重试、有界超
+// 时——observe 永不阻塞、永不弄破宿主回合。
+//
+// 事件类型是内核侧的封闭集（turn_outcome / tool_call / health_flip）：客户端
+// 类型上收窄、运行时透传，4xx {error, code} 即封闭集/护栏的权威裁决。
+import { randomUUID } from "node:crypto";
+import { fetchWithTimeout } from "./http.js";
+export function newIdempotencyKey() {
+    return randomUUID();
+}
+function observeBase(input) {
+    return `${input.url.replace(/\/+$/, "")}/observe`;
+}
+function observePayload(input) {
+    const payload = {
+        type: input.type,
+        idempotency_key: input.idempotencyKey ?? newIdempotencyKey(),
+        title: input.title,
+        body: input.body,
+    };
+    if (input.subject != null)
+        payload.subject = input.subject;
+    if (input.ts != null)
+        payload.ts = input.ts;
+    if (input.harness != null)
+        payload.harness = input.harness;
+    if (input.metadata != null)
+        payload.metadata = input.metadata;
+    return payload;
+}
+// 单次投递：校验-POST-返回，无排队。任何失败（网络/超时/4xx/5xx）都折算成
+// { delivered: false, ... } 返回，绝不向调用方抛错——要原始结果用本函数，
+// 要「丢了就丢了」用 observeFireAndForget。
+export async function observeOnce(input) {
+    try {
+        const r = await fetchWithTimeout(observeBase(input), {
+            method: "POST",
+            headers: { authorization: `Bearer ${input.token}`, "content-type": "application/json" },
+            body: JSON.stringify(observePayload(input)),
+        }, { fetchImpl: input.fetchImpl, timeoutMs: input.timeoutMs, env: input.env });
+        if (!r.ok) {
+            let error = `observe HTTP ${r.status}`;
+            try {
+                const doc = await r.json();
+                if (doc?.error)
+                    error = String(doc.error);
+            }
+            catch { /* 非法错误体保留 HTTP 状态文本 */ }
+            return { delivered: false, status: r.status, error };
+        }
+        const doc = await r.json();
+        return { delivered: true, status: r.status, page: doc?.page, truncated: doc?.truncated === true };
+    }
+    catch (e) {
+        return { delivered: false, error: String(e?.message || e) };
+    }
+}
+// fire-and-forget：挂上即走，失败即丢（永不产生 unhandled rejection）。
+// hook 转发器等「绝不能阻塞宿主」的车道用本函数。
+export function observeFireAndForget(input) {
+    void observeOnce(input).catch(() => {
+        // 双保险：observeOnce 已不抛；这里兜住未来重构引入的意外，保持「失败即丢」。
+    });
+}

package/dist/tokens.d.ts

@@ -0,0 +1,35 @@
+import { MEMORY_DISCIPLINE } from "./discipline.js";
+import { FetchLike, EnvLike } from "./http.js";
+export { MEMORY_DISCIPLINE };
+/** 永忆内核连接三元组（cellMemoryConfig 的产物）。 */
+export interface CellMemoryConfig {
+    url: string;
+    platformToken: string;
+    dataRoot: string;
+}
+export declare function cellMemoryConfig(env?: EnvLike): CellMemoryConfig | null;
+export declare function personTokenFor(cfg: CellMemoryConfig, ownerEmail: string, fetchImpl?: FetchLike): Promise<string>;
+export declare function memoryMcpEntry(url: string, token: string): {
+    id: string;
+    name: string;
+    config: {
+        serverName: string;
+        failOnStartupError: boolean;
+        transport: string;
+        url: string;
+        headers: {
+            Authorization: string;
+        };
+    };
+};
+export declare function cellMemoryMount(env: EnvLike, ownerEmail: string, fetchImpl?: FetchLike): Promise<{
+    mcpEntry: ReturnType<typeof memoryMcpEntry>;
+    discipline: string;
+} | null>;
+export declare function memberCachePath(dataRoot: string, packId: string, memberId: string): string;
+export interface MemberTokenInput {
+    packId: string;
+    memberId: string;
+    ownerEmail?: string;
+}
+export declare function memberTokenFor(cfg: CellMemoryConfig, { packId, memberId, ownerEmail }: MemberTokenInput, fetchImpl?: FetchLike): Promise<string>;

package/dist/tokens.js

@@ -0,0 +1,113 @@
+// ── 永忆挂载客户端：令牌铸造与缓存（自 paas/cell-memory.js 下放） ────────────
+//
+// 平台缝：CELL_MEMORY_ENABLED=1 且平台令牌与永忆 URL 配齐时，person 令牌
+// 按 owner 首次铸造并缓存到数据根磁盘下——每个用户只铸一次，重启稳定。
+//
+// 契约（fail-open 面与 fail-loud 面的分界）：铸造/URL 缺失/磁盘等任何失败，
+// 组合层（cellMemoryMount）返回 null、落点与「记忆关闭」基线逐字节一致；
+// 但令牌函数本身（personTokenFor/memberTokenFor）把铸造失败原样抛给调用方
+// 计数处理——绝不静默假装成功。
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { MEMORY_DISCIPLINE } from "./discipline.js";
+import { fetchWithTimeout } from "./http.js";
+export { MEMORY_DISCIPLINE };
+// 开关四件套：ENABLED=1 + URL + 平台令牌 + 数据根，缺一即整体关闭（返回
+// null，上层按「记忆不存在」处理）。
+export function cellMemoryConfig(env = process.env) {
+    const enabled = env.CELL_MEMORY_ENABLED === "1";
+    const url = String(env.CELL_MEMORY_URL || "").replace(/\/+$/, "");
+    const platformToken = String(env.CELL_MEMORY_PLATFORM_TOKEN || "");
+    const dataRoot = String(env.CELL_MEMORY_DATA || "");
+    return enabled && url && platformToken && dataRoot ? { url, platformToken, dataRoot } : null;
+}
+function cachePath(dataRoot, ownerEmail) {
+    const safe = String(ownerEmail || "unknown").replace(/[^a-zA-Z0-9@._-]/g, "_");
+    return join(dataRoot, "cell-memory-tokens", `${safe}.json`);
+}
+// 铸造 person（u/）令牌：磁盘缓存优先（namespace 校验后复用），未命中才打
+// /admin/mint；写盘 0600。铸造失败抛错——计数处理归调用方。
+export async function personTokenFor(cfg, ownerEmail, fetchImpl = fetch) {
+    const p = cachePath(cfg.dataRoot, ownerEmail);
+    try {
+        const cached = JSON.parse(readFileSync(p, "utf8"));
+        if (cached?.token && cached?.namespace === `u/${ownerEmail}`)
+            return cached.token;
+    }
+    catch { /* 未命中 → 铸造 */ }
+    // 出站纪律：令牌铸造走共享死线包装（默认 env 界）；fetchImpl 保持测试缝。
+    const res = await fetchWithTimeout(`${cfg.url}/admin/mint`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${cfg.platformToken}` },
+        body: JSON.stringify({ namespace: `u/${ownerEmail}`, label: `cell:${ownerEmail}` }),
+    }, { fetchImpl });
+    if (!res.ok)
+        throw new Error(`person mint HTTP ${res.status}`);
+    const { token } = await res.json();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify({ token, namespace: `u/${ownerEmail}`, mintedAt: new Date().toISOString() }), { mode: 0o600 });
+    return token;
+}
+// dsh-mcp-client 的加载行（http 分支），mcpEntry 形状逐字段保留。
+export function memoryMcpEntry(url, token) {
+    return {
+        id: "mcp-fd-memory",
+        name: "@deepseek-ai/dsh-mcp-client",
+        config: {
+            serverName: "fd-memory",
+            failOnStartupError: false,
+            transport: "streamable-http",
+            url: `${url}/mcp`,
+            headers: { Authorization: `Bearer ${token}` },
+        },
+    };
+}
+// 组合助手：返回 { mcpEntry, discipline } 或 null（fail-open）。任何失败都
+// 不改变调用方的落点——与「记忆关闭」基线逐字节一致。
+export async function cellMemoryMount(env, ownerEmail, fetchImpl = fetch) {
+    const cfg = cellMemoryConfig(env);
+    if (!cfg || !ownerEmail)
+        return null;
+    try {
+        const token = await personTokenFor(cfg, ownerEmail, fetchImpl);
+        return { mcpEntry: memoryMcpEntry(cfg.url, token), discipline: MEMORY_DISCIPLINE };
+    }
+    catch (e) {
+        console.warn(`[cell-memory] mount skipped (fail-open): ${e?.message || e}`);
+        return null;
+    }
+}
+// ── Deployment 成员令牌（自 paas/cell-memory.js 下放） ───────────────────────
+//
+// 平台缝为每个成员铸一枚 deployment 令牌（d/<packId>/<memberId>，在 fd-memory
+// 侧绑 owner 作为督导锚点），缓存到 cell 数据根——每成员只铸一次、重启稳定、
+// 0600。令牌属于「岗位」而不属于背后的模型实例：换防保留缓存，新上岗模型
+// 继承旧岗写下的分区。fail-open 同 person 面契约：铸造失败 = 计数 + 把错误
+// 抛给调用方，绝不弄破回合。
+export function memberCachePath(dataRoot, packId, memberId) {
+    const safe = (s) => String(s ?? "x").replace(/[^a-zA-Z0-9@._-]/g, "_");
+    return join(dataRoot, "cell-memory-tokens", `d-${safe(packId)}-${safe(memberId)}.json`);
+}
+export async function memberTokenFor(cfg, { packId, memberId, ownerEmail }, fetchImpl = fetch) {
+    const p = memberCachePath(cfg.dataRoot, packId, memberId);
+    const namespace = `d/${packId}/${memberId}`;
+    try {
+        const cached = JSON.parse(readFileSync(p, "utf8"));
+        if (cached?.token && cached?.namespace === namespace)
+            return cached.token;
+    }
+    catch { /* 未命中 → 铸造 */ }
+    if (!ownerEmail)
+        throw new Error("member mint requires ownerEmail (the oversight anchor)");
+    const res = await fetchWithTimeout(`${cfg.url}/admin/mint`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${cfg.platformToken}` },
+        body: JSON.stringify({ namespace, owner: `u/${ownerEmail}`, label: `member:${packId}:${memberId}` }),
+    }, { fetchImpl });
+    if (!res.ok)
+        throw new Error(`member mint HTTP ${res.status}`);
+    const { token } = await res.json();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify({ token, namespace, owner: ownerEmail, mintedAt: new Date().toISOString() }), { mode: 0o600 });
+    return token;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@finddatatechnology/yongyi-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "type": "module",
+  "description": "永忆（YongYi / fd-memory）客户端 SDK：召回注入阶梯、纪律文本单源、五类事实捕获、令牌铸造缓存、/observe 上报。零运行时依赖，只以 fetch 打内核 HTTP 面。",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test \"dist-test/test/*.test.js\""
+  },
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "keywords": [
+    "agent",
+    "memory",
+    "llm",
+    "mcp",
+    "working-memory",
+    "yongyi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FindDataTechnology/fd-memory.git",
+    "directory": "sdk"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
 }