@dingyi-tech/chat-renderer-sdk 0.2.1 → 0.2.3

package/README.md

@@ -27,6 +27,7 @@ dingyi-agno component pack .
 ```
 
 `pack` 会自动安装前端依赖、类型检查、构建单文件 ESM 并生成 ZIP，不需要手工维护平台入口。
+SDK 会按锁文件选择对应的包管理器，并在依赖文件未变化时跳过重复安装。
 
 生成的 Renderer 工程保持为普通前端目录，不包含隐藏适配代码：
 
@@ -73,6 +74,9 @@ dingyi-renderer build --framework react
 生产构建固定输出 `dist/renderer.mjs`。自定义源码路径等高级场景可以使用
 `@dingyi-tech/chat-renderer-sdk/vite`，普通组件工程不应自行维护构建入口。
 
+Host 会注入 `presentation.mode`：中台聊天默认是 `user`，本地开发是 `debug`。Renderer
+可以据此折叠技术细节，但应始终保留完整 payload。
+
 ## React
 
 ```tsx
@@ -85,7 +89,8 @@ type SalesData = {
   total: number;
 };
 
-export default function Renderer({ data, action, readonly }: RendererProps<SalesData>) {
+export default function Renderer({ data, action, readonly, presentation }: RendererProps<SalesData>) {
+  const isDebug = presentation.mode === "debug";
   const [busy, setBusy] = useState(false);
 
   const refresh = async () => {
@@ -157,6 +162,8 @@ export default render;
 
 常规筛选、分页和提交只使用 `action()`。只有启动新对话、恢复 HITL 或调用宿主系统时才需要 `runtime`。
 
+自定义 Renderer 只在组件显式输出 `ctx.ui.render()` 时启用。普通字符串或 Markdown 回复继续使用平台默认 Renderer，不要求业务组件处理空 Payload。
+
 ## Python 配套代码
 
 ```python
@@ -210,22 +217,111 @@ pnpm add @dingyi-tech/chat-renderer-sdk
 
 ## 发布到 npm
 
-`dingyi-tech` 是 npm 账号 `dingyi-tech` 自带的个人 scope，不需要额外创建 Organization。发布者需要登录该账号，并为 npm 写操作启用 2FA；自动化发布时则使用具有该 scope 发布权限的 Granular Access Token。令牌只放在本机或 CI 环境，不写入仓库：
+SDK 包名是 `@dingyi-tech/chat-renderer-sdk`，发布地址固定为 npm 官方 Registry：
+`https://registry.npmjs.org/`。发布前必须递增一个尚未发布的版本号，不能覆盖已经存在的版本。
+
+### 方式一：在仓库根目录发布
+
+适合维护本项目的开发者。以下命令会依次完成类型检查、构建、发布文件检查和 npm 发布：
 
 ```bash
-export NPM_TOKEN="npm_xxx"
-npm config set '//registry.npmjs.org/:_authToken' "$NPM_TOKEN" --location=user
-npm whoami --registry https://registry.npmjs.org/
+# 1. 检查 SDK
+npm run check:renderer-sdk
+
+# 2. 递增版本号（按实际变更选择 patch、minor 或 major）
+pnpm --dir sdk/chat-renderer version patch --no-git-tag-version
+
+# 3. 预览将要进入 tarball 的文件
+pnpm --dir sdk/chat-renderer pack --dry-run
+
+# 4. 发布公开包
+npm run publish:renderer-sdk
 ```
 
-先检查实际制品，再发布：
+如果只想生成发布包、不发布到 npm：
 
 ```bash
 npm run pack:renderer-sdk
-npm run publish:renderer-sdk
 ```
 
-`prepack` 会重新构建 `dist` 并检查所有公开入口，`publishConfig` 固定发布到 npm 官方 Registry 且按 public package 发布。正式发版前使用 `pnpm --dir sdk/chat-renderer version patch|minor|major` 更新版本；启用 npm 2FA 的账号还需要按提示输入 OTP。
+### 方式二：在 SDK 目录直接发布
+
+适合只拿 SDK 子目录单独发版：
+
+```bash
+cd sdk/chat-renderer
+
+# 1. 修改版本号
+npm version patch --no-git-tag-version
+
+# 2. 类型检查、构建并检查发布产物
+npm run check
+
+# 3. 预览发布文件
+npm pack --dry-run
+
+# 4. 发布到 npm
+npm publish --access public --registry https://registry.npmjs.org/
+```
+
+`npm publish` 会触发 `prepack`，重新构建 `dist` 并检查公开入口。`package.json` 的
+`files` 白名单只允许发布 `dist/**/*.js`、`dist/**/*.d.ts` 和 `README.md`。
+
+### 发布前认证
+
+先确认当前登录账号和 Registry：
+
+```bash
+npm whoami --registry https://registry.npmjs.org/
+```
+
+未登录时，在交互式终端执行：
+
+```bash
+npm login --auth-type=web --registry https://registry.npmjs.org/
+```
+
+当前 npm 账号使用 WebAuthn / Passkey 认证，不是项目生成的验证码。命令可能提示：
+
+```text
+Press ENTER to open in the browser...
+```
+
+按 Enter 后，在浏览器中使用 Touch ID、指纹或安全密钥确认。发布命令也可能打开相同的浏览器认证流程，因此需要在真实的交互式终端执行；不要把账号密码、Passkey 或 Token 写入仓库。
+
+### CI 自动发布
+
+CI 不适合使用浏览器指纹认证时，使用具有该 scope 发布权限的 npm Granular Access Token，并通过 CI Secret 注入 `NODE_AUTH_TOKEN`：
+
+```bash
+export NODE_AUTH_TOKEN="npm_xxx"
+cat > ~/.npmrc <<'EOF'
+//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
+EOF
+
+cd sdk/chat-renderer
+npm run check
+npm pack --dry-run
+npm publish --access public --registry https://registry.npmjs.org/
+```
+
+Token 只放在本机密钥存储或 CI Secret 中，不要提交 `.npmrc` 或把 Token 写入脚本。
+
+### 发布后验证
+
+```bash
+npm view @dingyi-tech/chat-renderer-sdk versions --json \
+  --registry https://registry.npmjs.org/
+
+npm view @dingyi-tech/chat-renderer-sdk dist-tags --json \
+  --registry https://registry.npmjs.org/
+
+# 在临时目录验证外部安装
+npm install @dingyi-tech/chat-renderer-sdk@latest
+```
+
+### sourcemap 检查
 
-发布包禁止包含 sourcemap。构建会先清空 `dist`，并关闭 JavaScript 与声明文件的
-sourcemap；`prepack` 发现 `.map` 文件或 `sourceMappingURL` 时会直接终止发布。
+发布包禁止包含 sourcemap。构建前会清空 `dist`，并关闭 JavaScript 与声明文件的
+sourcemap；`prepack` 发现 `.map` 文件或 `sourceMappingURL` 时会直接终止发布。执行
+`npm pack --dry-run` 时，清单中不应出现 `.map` 或 `sourceMappingURL`。

package/dist/cli.js

@@ -6,13 +6,14 @@ import { pathToFileURL } from "node:url";
 import { build as viteBuild, createServer, } from "vite";
 import { createRendererViteConfig, resolveRendererSourcePaths, } from "./vite.js";
 const usage = `Usage:
-  dingyi-renderer build --framework <react|vue|native>
+  dingyi-renderer build --framework <react|vue|native> [--watch]
   dingyi-renderer dev --framework <react|vue|native> [--host 127.0.0.1] [--port 4174]
 
 Options:
   --root <path>       Renderer UI root (default: current directory)
   --host <host>       Development server host
   --port <port>       Development server port
+  --watch             Rebuild the Renderer artifact when sources change
   -h, --help          Show this help
 `;
 function optionValue(args, index, inline) {
@@ -38,6 +39,7 @@ function parseArguments(args) {
     let root = process.cwd();
     let host = "127.0.0.1";
     let port = 4174;
+    let watch = false;
     for (let index = 1; index < args.length; index += 1) {
         const argument = args[index];
         const separator = argument.indexOf("=");
@@ -62,13 +64,18 @@ function parseArguments(args) {
                 throw new Error(`Invalid port: ${String(port)}`);
             }
         }
+        else if (flag === "--watch") {
+            watch = true;
+        }
         else {
             throw new Error(`Unknown option: ${argument}`);
         }
     }
     if (!framework)
         throw new Error("--framework is required");
-    return { command, framework, root, host, port };
+    if (watch && command !== "build")
+        throw new Error("--watch is only supported by the build command");
+    return { command, framework, root, host, port, watch };
 }
 async function assertRendererSources(options) {
     const sources = resolveRendererSourcePaths(options);
@@ -103,11 +110,12 @@ async function run(options) {
     const plugins = await loadFrameworkPlugins(options);
     const config = createRendererViteConfig({
         framework: options.framework,
+        mode: options.command === "dev" ? "development" : "production",
         root: options.root,
         plugins,
     });
     if (options.command === "build") {
-        await viteBuild(config);
+        await viteBuild(options.watch ? { ...config, build: { ...config.build, watch: {} } } : config);
         return;
     }
     const server = await createServer({

package/dist/index.d.ts

@@ -1,25 +1,42 @@
 export declare const RENDERER_PROTOCOL: "dingyi.renderer.v1";
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
+export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
+export type JsonObject = {
     [key: string]: JsonValue;
 };
-export type RendererPayload = Record<string, unknown>;
+export type RendererPayload = JsonObject;
+export type RendererPresentation = {
+    mode: "user" | "debug";
+};
+export declare function isJsonValue(value: unknown): value is JsonValue;
+export declare function isJsonObject(value: unknown): value is JsonObject;
+export type RendererSnapshot = {
+    rendererKey?: string;
+    rendererVersion?: string;
+    rendererDigest?: string;
+    messageId?: string;
+    revision?: number;
+    payload?: RendererPayload;
+    fallbackMarkdown?: string;
+};
 export type RendererActionResult = {
-    snapshot?: {
-        rendererKey?: string;
-        rendererVersion?: string;
-        rendererDigest?: string;
-        messageId?: string;
-        revision?: number;
-        payload?: RendererPayload;
-        fallbackMarkdown?: string;
-    };
-    [key: string]: unknown;
+    snapshot?: RendererSnapshot;
+    [key: string]: JsonValue | RendererSnapshot | undefined;
 };
 export type RendererBridge = {
+    /** Read session-owned media. Available in history; never executes a renderer action. */
+    loadMedia?(reference: {
+        storage_key: string;
+        session_id?: string;
+        mime_type?: string;
+        filename?: string;
+    }, options?: {
+        thumbnail?: boolean;
+        signal?: AbortSignal;
+    }): Promise<Blob>;
     invoke(action: string, input: RendererPayload): Promise<RendererActionResult>;
     reply(content: string, metadata?: RendererPayload): Promise<void>;
     resume(input: RendererPayload): Promise<void>;
-    host(action: string, input: RendererPayload): Promise<unknown>;
+    host(action: string, input: RendererPayload): Promise<JsonValue>;
 };
 export type RendererContext = {
     protocol: typeof RENDERER_PROTOCOL;
@@ -40,6 +57,7 @@ export type RendererContext = {
     locale: "zh-CN" | "en-US";
     readonly: boolean;
     theme: Record<string, string>;
+    presentation: RendererPresentation;
     bridge: RendererBridge;
 };
 export type RendererProps<T extends object = RendererPayload> = {
@@ -50,6 +68,7 @@ export type RendererProps<T extends object = RendererPayload> = {
     locale: RendererContext["locale"];
     readonly: boolean;
     theme: RendererContext["theme"];
+    presentation: RendererPresentation;
     action(action: string, input?: RendererPayload): Promise<RendererActionResult>;
     /** Advanced lifecycle operations. Most renderers only need `action()`. */
     runtime: RendererBridge;
@@ -75,6 +94,7 @@ export declare function createRendererPreviewProps<T extends object = RendererPa
     content?: string;
     locale?: RendererContext["locale"];
     readonly?: boolean;
+    presentation?: RendererPresentation;
     onAction?: (action: string, input: RendererPayload) => Promise<RendererActionResult> | RendererActionResult;
 }): RendererProps<T>;
 export declare const rendererThemeVariables: Readonly<{
@@ -100,8 +120,11 @@ export type RendererActionState = {
     result?: RendererActionResult;
     error?: Error;
 };
-export declare function createRendererActionState(onChange?: (state: Readonly<RendererActionState>) => void): {
+export type RendererActionStates = Readonly<Record<string, Readonly<RendererActionState>>>;
+export declare function createRendererActionState(onChange?: (latest: Readonly<RendererActionState>, states: RendererActionStates) => void): {
     readonly value: Readonly<RendererActionState>;
+    readonly values: RendererActionStates;
+    get(action: string): Readonly<RendererActionState>;
     invoke(bridge: RendererBridge, action: string, input: RendererPayload): Promise<RendererActionResult>;
-    reset(): void;
+    reset(action?: string): void;
 };

package/dist/index.js

@@ -1,4 +1,40 @@
 export const RENDERER_PROTOCOL = "dingyi.renderer.v1";
+export function isJsonValue(value) {
+    return validateJsonValue(value, new Set(), 0);
+}
+export function isJsonObject(value) {
+    return Boolean(value) && !Array.isArray(value) && isJsonValue(value);
+}
+function validateJsonValue(value, active, depth) {
+    if (depth > 100)
+        return false;
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object")
+        return false;
+    if (active.has(value))
+        return false;
+    active.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.every((item) => validateJsonValue(item, active, depth + 1));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        if (Object.getOwnPropertySymbols(value).length)
+            return false;
+        return Object.values(value).every((item) => validateJsonValue(item, active, depth + 1));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        active.delete(value);
+    }
+}
 export function defineRenderer(definition) {
     if (!definition || typeof definition.mount !== "function") {
         throw new TypeError("Renderer mount must be a function");
@@ -14,6 +50,7 @@ export function toRendererProps(context) {
         locale: context.locale,
         readonly: context.readonly,
         theme: context.theme,
+        presentation: context.presentation,
         action: (action, input = {}) => context.bridge.invoke(action, input),
         runtime: context.bridge,
     };
@@ -36,7 +73,7 @@ export function createRendererPreviewProps(options) {
         invoke: async (action, input) => options.onAction?.(action, input) ?? {},
         reply: async () => undefined,
         resume: async () => undefined,
-        host: async () => undefined,
+        host: async () => null,
     };
     return toRendererProps({
         protocol: RENDERER_PROTOCOL,
@@ -52,6 +89,7 @@ export function createRendererPreviewProps(options) {
         locale: options.locale || "zh-CN",
         readonly: Boolean(options.readonly),
         theme: {},
+        presentation: options.presentation || { mode: "user" },
         bridge,
     });
 }
@@ -80,30 +118,60 @@ export function observeRendererContainer(element, listener) {
     return () => observer.disconnect();
 }
 export function createRendererActionState(onChange) {
-    let current = { key: "", status: "idle" };
-    const update = (next) => {
-        current = next;
-        onChange?.(Object.freeze({ ...next }));
+    let current = Object.freeze({ key: "", status: "idle" });
+    const states = new Map();
+    const latestRequestByAction = new Map();
+    let sequence = 0;
+    let latestRequest = 0;
+    const snapshot = () => Object.freeze(Object.fromEntries(Array.from(states, ([key, state]) => [key, state])));
+    const update = (request, next) => {
+        if (latestRequestByAction.get(next.key) !== request)
+            return;
+        const frozen = Object.freeze({ ...next });
+        states.set(next.key, frozen);
+        if (request === latestRequest)
+            current = frozen;
+        onChange?.(current, snapshot());
     };
     return {
         get value() {
             return current;
         },
+        get values() {
+            return snapshot();
+        },
+        get(action) {
+            return states.get(action) || Object.freeze({ key: action, status: "idle" });
+        },
         async invoke(bridge, action, input) {
-            update({ key: action, status: "running" });
+            const request = ++sequence;
+            latestRequest = request;
+            latestRequestByAction.set(action, request);
+            update(request, { key: action, status: "running" });
             try {
                 const result = await bridge.invoke(action, input);
-                update({ key: action, status: "completed", result });
+                update(request, { key: action, status: "completed", result });
                 return result;
             }
             catch (cause) {
                 const error = cause instanceof Error ? cause : new Error(String(cause));
-                update({ key: action, status: "failed", error });
+                update(request, { key: action, status: "failed", error });
                 throw error;
             }
         },
-        reset() {
-            update({ key: "", status: "idle" });
+        reset(action) {
+            if (action) {
+                latestRequestByAction.delete(action);
+                states.delete(action);
+                if (current.key === action)
+                    current = Object.freeze({ key: "", status: "idle" });
+            }
+            else {
+                latestRequestByAction.clear();
+                states.clear();
+                current = Object.freeze({ key: "", status: "idle" });
+            }
+            onChange?.(current, snapshot());
         },
     };
 }

package/dist/vite.d.ts

@@ -6,6 +6,7 @@ export type RendererSourcePaths = {
 };
 export type RendererViteOptions = {
     framework: RendererFramework;
+    mode?: "development" | "production";
     root?: string;
     outDir?: string;
     source?: Partial<RendererSourcePaths>;

package/dist/vite.js

@@ -61,12 +61,14 @@ export function rendererEntryPlugin(options) {
 }
 export function createRendererViteConfig(options) {
     const root = resolve(options.root || process.cwd());
+    const mode = options.mode || "production";
     return {
         root,
+        mode,
         configFile: false,
         appType: "spa",
         define: {
-            "process.env.NODE_ENV": JSON.stringify("production"),
+            "process.env.NODE_ENV": JSON.stringify(mode),
         },
         plugins: [
             ...(options.plugins || []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingyi-tech/chat-renderer-sdk",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Framework-neutral custom message Renderer contract for Dingyi AI Platform",
   "type": "module",
   "sideEffects": false,
@@ -40,7 +40,7 @@
     "clean": "node scripts/clean.mjs",
     "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.json",
-    "check": "tsc -p tsconfig.json --noEmit && npm run build && node scripts/check-vite-api.mjs",
+    "check": "tsc -p tsconfig.json --noEmit && npm run build && node scripts/check-runtime.mjs && node scripts/check-vite-api.mjs",
     "prepack": "npm run build && node scripts/check-dist.mjs"
   },
   "publishConfig": {
@@ -54,10 +54,18 @@
     "vite": ">=6 <9"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "react-dom": { "optional": true },
-    "vue": { "optional": true },
-    "vite": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@types/node": "^22.0.0",