@gt-fe/eap-runtime 0.0.17 → 0.0.18

package/README.md

@@ -277,26 +277,28 @@ EAP_TOOL_EXECUTION_MODE=mcp                  # 仅 createDevRuntime / eap chat
 
 ---
 
-## 11. 发布到公司私有 npm（可选）
+## 11. 发布 npm 包
 
-私服：`https://maven.gtcloud.cn/repository/npm-local/`（模板 [`.npmrc.example`](./.npmrc.example)）。
+升版、CHANGELOG、`git commit` / `git push` 不在脚本里，先做完再跑脚本。脚本只做构建、发布、核对 registry 上的版本号。
 
-> `@eap:registry=...` 须写入 `.npmrc` 文件，不可在 shell 中作为命令直接执行。
+| 脚本 | 包 | registry |
+|------|----|----------|
+| [`scripts/publish-intranet.sh`](./scripts/publish-intranet.sh) | `@eap/runtime` | Nexus `https://maven.gtcloud.cn/repository/npm-local/` |
+| [`scripts/publish-public.sh`](./scripts/publish-public.sh) | `@gt-fe/eap-runtime` | npmjs。临时目录改名；dist 里 `@eap/contracts` 改为 `@gt-fe/eap-contracts`。不改源码 `package.json` |
 
 ```bash
+# 登录（一次性）
 cp .npmrc.example .npmrc
 npm login --registry https://maven.gtcloud.cn/repository/npm-local/
+npm login --registry https://registry.npmjs.org/
 
-# 1) 先发 @eap/contracts（version 改为目标版，如 0.0.1）
-cd ../eap-contracts && cp .npmrc.example .npmrc
-pnpm run build && npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
-
-# 2) runtime：package.json 中 @eap/contracts 改为版本号（勿再用 file:）
-cd ../runtime && pnpm run build
-npm publish --registry https://maven.gtcloud.cn/repository/npm-local/
+./scripts/publish-intranet.sh
+./scripts/publish-public.sh
 ```
 
-含 `_authToken` 的 `.npmrc` 已 gitignore，勿提交凭证。
+不要在源码目录对 npmjs 执行 `npm publish`（`publishConfig` 指向 Nexus；公网 dist 必须改写 contracts）。含 `_authToken` 的 `.npmrc` 已 gitignore，勿提交凭证。`@eap:registry=...` 须写入 `.npmrc` 文件，不可在 shell 中当命令执行。
+
+UAT Hosting 吃公网包：把 `@eap/runtime` 指到 `npm:@gt-fe/eap-runtime@<本版>` 后重建镜像。
 
 ---
 

package/dist/checkpoint/checkpoint-serializer.d.ts

@@ -40,13 +40,17 @@ export interface CreateCheckpointParams {
  * 确保所有必要字段的一致性。
  */
 export declare function createCheckpointData(params: CreateCheckpointParams): CheckpointData;
+/**
+ * 落盘用快照：可 JSON 往返的数据留下；定时器 / 函数 / 环丢掉。
+ * 环用栈判定，同一对象出现两次但不成环（菱形）仍保留。
+ */
+export declare function toJsonSafe(value: unknown, stack?: Set<object>): unknown;
+/** 所有 Checkpoint Saver 落盘共用，禁止裸 JSON.stringify(state)。 */
+export declare function stringifyJsonSafe(value: unknown): string;
 /**
  * 序列化 CheckpointData 为 JSON 字符串
  *
- * 处理边界情况：
- * - Date 对象 → ISO 字符串
- * - undefined 值自动剔除（JSON.stringify 默认行为）
- * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ * Date → ISO；定时器 / 循环引用省略，不抛 TypeError。
  */
 export declare function serializeCheckpoint(data: CheckpointData): string;
 /**

package/dist/checkpoint/checkpoint-serializer.js

@@ -37,30 +37,69 @@ export function createCheckpointData(params) {
 // ─────────────────────────────────────────────
 // 序列化 / 反序列化
 // ─────────────────────────────────────────────
+function isTimerHandle(value) {
+    const name = value.constructor?.name;
+    if (name === 'Timeout' || name === 'TimersList' || name === 'Immediate')
+        return true;
+    return Object.prototype.hasOwnProperty.call(value, '_idlePrev')
+        && Object.prototype.hasOwnProperty.call(value, '_idleNext');
+}
+/**
+ * 落盘用快照：可 JSON 往返的数据留下；定时器 / 函数 / 环丢掉。
+ * 环用栈判定，同一对象出现两次但不成环（菱形）仍保留。
+ */
+export function toJsonSafe(value, stack = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'undefined' || typeof value === 'function' || typeof value === 'symbol') {
+        return undefined;
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value !== 'object')
+        return undefined;
+    if (isTimerHandle(value))
+        return undefined;
+    if (stack.has(value))
+        return undefined;
+    const maybeToJSON = value.toJSON;
+    if (typeof maybeToJSON === 'function') {
+        return toJsonSafe(maybeToJSON.call(value), stack);
+    }
+    if (Array.isArray(value)) {
+        stack.add(value);
+        const out = value.map((item) => {
+            const next = toJsonSafe(item, stack);
+            return next === undefined ? null : next;
+        });
+        stack.delete(value);
+        return out;
+    }
+    stack.add(value);
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        const next = toJsonSafe(child, stack);
+        if (next !== undefined)
+            out[key] = next;
+    }
+    stack.delete(value);
+    return out;
+}
+/** 所有 Checkpoint Saver 落盘共用，禁止裸 JSON.stringify(state)。 */
+export function stringifyJsonSafe(value) {
+    return JSON.stringify(toJsonSafe(value));
+}
 /**
  * 序列化 CheckpointData 为 JSON 字符串
  *
- * 处理边界情况：
- * - Date 对象 → ISO 字符串
- * - undefined 值自动剔除（JSON.stringify 默认行为）
- * - 循环引用检测（抛出明确错误而非默认 TypeError）
+ * Date → ISO；定时器 / 循环引用省略，不抛 TypeError。
  */
 export function serializeCheckpoint(data) {
-    const seen = new WeakSet();
-    return JSON.stringify(data, (_key, value) => {
-        // Date → ISO 字符串
-        if (value instanceof Date) {
-            return value.toISOString();
-        }
-        // 循环引用检测
-        if (typeof value === 'object' && value !== null) {
-            if (seen.has(value)) {
-                throw new Error(`[CheckpointSerializer] Circular reference detected during serialization`);
-            }
-            seen.add(value);
-        }
-        return value;
-    });
+    return stringifyJsonSafe(data);
 }
 /**
  * 反序列化 JSON 字符串为 CheckpointData

package/dist/checkpoint/file-checkpoint-saver.js

@@ -4,6 +4,7 @@
  */
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 export class FileCheckpointSaver {
     baseDir;
     constructor(baseDir) {
@@ -12,7 +13,7 @@ export class FileCheckpointSaver {
     async save(threadId, data) {
         const dir = join(this.baseDir, threadId);
         await mkdir(dir, { recursive: true });
-        await writeFile(join(dir, `${data.checkpointId}.json`), JSON.stringify(data));
+        await writeFile(join(dir, `${data.checkpointId}.json`), stringifyJsonSafe(data));
         // 更新 latest 指针
         await writeFile(join(dir, 'latest.json'), JSON.stringify({ checkpointId: data.checkpointId }));
     }

package/dist/checkpoint/index.d.ts

@@ -4,7 +4,7 @@ export type { RedisCheckpointSaverOptions } from './redis-checkpoint-saver.js';
 export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
 export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
-export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
 export type { CreateCheckpointParams } from './checkpoint-serializer.js';
 export { FileCheckpointSaver } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';

package/dist/checkpoint/index.js

@@ -4,7 +4,7 @@ export { RedisCheckpointSaver } from './redis-checkpoint-saver.js';
 export { CompositeCheckpointSaver } from './composite-checkpoint-saver.js';
 export { restoreCheckpoint } from './restore-checkpoint.js';
 export { notifyCheckpointRef, stripCheckpointCollectors } from './checkpoint-ref-notify.js';
-export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, } from './checkpoint-serializer.js';
+export { createCheckpointData, serializeCheckpoint, deserializeCheckpoint, stringifyJsonSafe, toJsonSafe, } from './checkpoint-serializer.js';
 export { FileCheckpointSaver } from './file-checkpoint-saver.js';
 export { InMemoryCheckpointSaver } from './in-memory-checkpoint-saver.js';
 export { MongoCheckpointSaver } from './mongo-checkpoint-saver.js';

package/dist/checkpoint/pg-checkpoint-saver.js

@@ -7,6 +7,7 @@
  * @see design.md §1.3 checkpoints 数据模型
  * @see checkpoint-saver.contract.ts ICheckpointSaver 接口定义
  */
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 // ─────────────────────────────────────────────
 // PostgresCheckpointSaver
 // ─────────────────────────────────────────────
@@ -38,9 +39,9 @@ export class PostgresCheckpointSaver {
             threadId,
             data.checkpointId,
             data.currentNodeId,
-            JSON.stringify(data.historyPath),
-            JSON.stringify(data.state),
-            data.engineSnapshot == null ? null : JSON.stringify(data.engineSnapshot),
+            stringifyJsonSafe(data.historyPath),
+            stringifyJsonSafe(data.state),
+            data.engineSnapshot == null ? null : stringifyJsonSafe(data.engineSnapshot),
             data.createdBy || 'system',
             data.createdAt,
             data.updatedBy || 'system',

package/dist/checkpoint/redis-checkpoint-saver.js

@@ -9,6 +9,7 @@
  *
  * @see design.md §1.3 checkpoints 数据模型
  */
+import { stringifyJsonSafe } from './checkpoint-serializer.js';
 /**
  * RedisCheckpointSaver — ICheckpointSaver 的 Redis 实现
  *
@@ -52,7 +53,7 @@ export class RedisCheckpointSaver {
         const idxKey = this.threadIndexKey(threadId);
         const ltKey = this.latestKey(threadId);
         const revKey = this.reverseIndexKey(data.checkpointId);
-        const json = JSON.stringify(data);
+        const json = stringifyJsonSafe(data);
         const score = new Date(data.createdAt).getTime();
         const pipeline = this.redis.pipeline();
         // 存储 Checkpoint JSON

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gt-fe/eap-runtime",
-  "version": "0.0.17",
-  "description": "Enterprise Agent Platform \u2014 Runtime\u6838\u5fc3\uff1aGraph\u6267\u884c\u5f15\u64ce\u3001Task\u751f\u547d\u5468\u671f\u3001Session\u7ba1\u7406\u3001Checkpoint\u6301\u4e45\u5316",
+  "version": "0.0.18",
+  "description": "Enterprise Agent Platform — Runtime核心：Graph执行引擎、Task生命周期、Session管理、Checkpoint持久化",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",