zentao-api 0.6.5 → 0.6.7

package/dist/modules/registry.js

@@ -4,13 +4,9 @@
 // - ./define         —— 定义/写入模块（defineModules / defineModuleActions / resetModuleDefinitions）。
 // - ./override       —— 内置覆盖/扩展（基于 define，随 SDK 发布并在加载/重置时自动应用）。
 // - ./query          —— 获取模块信息（getModule / getModuleAction / getModuleNames / isModuleName）。
-import { BUILTIN_MODULES } from './generated.js';
 import { applyBuiltinOverrides } from './override.js';
 import { setPostResetHook } from './registry-store.js';
-export { BUILTIN_MODULES };
-export const MODULES = BUILTIN_MODULES;
 export { defineModules, defineModuleActions, extendModuleAction, resetModuleDefinitions, } from './define.js';
-export { applyBuiltinOverrides };
 // 内置覆盖接线：避免 define ↔ override 之间的循环依赖。
 // - 加载时应用一次；
 // - 注册为 store 的「重置后钩子」，使 resetModuleDefinitions 还原内置基线后自动重新应用。

package/dist/modules/resolve.js

@@ -162,7 +162,7 @@ function buildQuery(action, params) {
             value = params.page;
         }
         if (value === undefined) {
-            value = param.defaultValue ?? param.options?.[0]?.value;
+            value = param.defaultValue;
         }
         if (value === undefined && param.required) {
             throw new ZentaoError('E_MISSING_PARAM', { param: param.name });

package/dist/profiles/index.d.ts

@@ -1,4 +1,4 @@
-import type { ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
+import type { ServerConfig, ZentaoProfile, ZentaoProfileRecord } from '../types/index.js';
 /**
  * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
  *
@@ -50,6 +50,8 @@ export declare function getProfile(profileKey?: string): Promise<ZentaoProfileRe
  *   `E_INVALID_BASE_URL`、`E_PROFILE_STORAGE_INVALID`、`E_PROFILE_STORAGE_UNAVAILABLE`。
  */
 export declare function addProfile(profile: ZentaoProfile): Promise<ZentaoProfileRecord>;
+/** 只刷新已有 profile 的服务器配置，不切换当前账号或重建已删除的记录。 @internal */
+export declare function updateProfileServerConfig(profileKey: string, serverConfig: ServerConfig, fetchedAt: string): Promise<void>;
 /**
  * 删除指定 profile。
  *

package/dist/profiles/index.js

@@ -1,6 +1,6 @@
 import { ZentaoError } from '../misc/errors.js';
 import { isNodeRuntime } from '../misc/environment.js';
-import { normalizeSiteUrl } from '../utils/index.js';
+import { isRecord, normalizeSiteUrl } from '../utils/index.js';
 /**
  * 浏览器环境下用于在 `localStorage` 中保存 profile 数据的 key。
  *
@@ -8,9 +8,6 @@ import { normalizeSiteUrl } from '../utils/index.js';
  */
 export const ZENTAO_PROFILES_STORAGE_KEY = 'ZENTAO_PROFILES';
 const PROFILE_FILE_PARTS = ['.config', 'zentao', 'zentao.json'];
-function isRecord(value) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
 function cloneJson(value) {
     if (value === undefined)
         return value;
@@ -241,6 +238,18 @@ export function addProfile(profile) {
         return toRecord(normalized);
     });
 }
+/** 只刷新已有 profile 的服务器配置，不切换当前账号或重建已删除的记录。 @internal */
+export function updateProfileServerConfig(profileKey, serverConfig, fetchedAt) {
+    return withStoreMutex(async () => {
+        const store = await readStore();
+        const profile = findProfile(store, profileKey);
+        if (!profile)
+            return;
+        profile.serverConfig = cloneJson(serverConfig);
+        profile.serverConfigFetchedAt = fetchedAt;
+        await writeStore(store);
+    });
+}
 /**
  * 删除指定 profile。
  *

package/dist/request/index.d.ts

@@ -27,17 +27,28 @@ export type RequestResultFor<Name extends BuiltinRequestName> = ActionMetaOf<Nam
  * 选项优先级为：本次调用 options > 全局 options > 客户端默认值。
  * 当响应 `status` 为 `"fail"` 时，默认按原样返回；若 `options.throwOnFail`
  * 或全局 `throwOnFail` 为真，则改为抛出 `E_API_FAILED`。
+ * 请求前按 Action 的 `minVersion` 检查服务器版本；全局 `version` 可避免配置探测，
+ * `forceRefreshConfig` 则强制使用实际版本。无法获取配置时默认抛错，
+ * `skipVersionCheckOnConfigError` 可允许本次跳过检查，但不能忽略明确的版本不匹配。
  *
  * 对 `update` 动作，当 `options.autoFill` 或全局 `autoFill` 为真时，会先 GET 当前对象，
  * 用现值补齐用户未显式传入的 body 字段后再 PUT，避免禅道覆盖未提交字段。详见 {@link RequestOptions.autoFill}。
  *
- * @typeParam T 期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
+ * @typeParam T 归一化响应中期望的 `data` 字段类型；不传时为 `unknown`，调用方需要自行收窄。
  * @param name - 请求名，例如 `product`、`product/list` 或 `product/1`。
  * @param params - 请求参数。
  * @param options - 请求选项。
- * @returns 归一化后的禅道 API 响应。
+ * @returns 默认返回归一化后的禅道 API 响应；`options.raw` 为 true 时返回未经归一化的原始响应。
  * @throws {ZentaoError} 传输层错误、参数缺失或 `throwOnFail` 启用时的业务失败。
  */
-export declare function request<Name extends BuiltinRequestName>(name: Name, params?: RequestParamsFor<Name>, options?: RequestOptions): Promise<ResponseData<RequestResultFor<Name>>>;
-export declare function request<T = unknown>(name: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<ResponseData<T>>;
+export declare function request(name: string, params: Record<string, unknown> | undefined, options: RequestOptions & {
+    raw: true;
+}): Promise<unknown>;
+export declare function request<Name extends BuiltinRequestName>(name: Name, params?: RequestParamsFor<Name>, options?: RequestOptions & {
+    raw?: false;
+}): Promise<ResponseData<RequestResultFor<Name>>>;
+export declare function request<T = unknown>(name: string, params?: Record<string, unknown>, options?: RequestOptions & {
+    raw?: false;
+}): Promise<ResponseData<T>>;
+export declare function request(name: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<unknown>;
 export {};

package/dist/request/index.js

@@ -1,4 +1,5 @@
-import { ZentaoError } from '../misc/errors.js';
+import { isZentaoConfigFetchError, ZentaoError } from '../misc/errors.js';
+import { parseZentaoVersion, supportsZentaoVersion } from '../misc/zentao-version.js';
 import { getGlobalOptions } from '../misc/global-options.js';
 import { getModule, getModuleAction } from '../modules/registry.js';
 import { extractPager, extractResult, resolveActionRequest } from '../modules/resolve.js';
@@ -50,24 +51,24 @@ function getExplicitDataKeys(data) {
 /**
  * 在执行 `update` 动作前，用当前对象的现值填充用户未显式传入的 body 字段。
  *
- * 仅当模块存在 `type: 'get'` 动作且 update 动作声明了对象类型 body schema 时生效；
+ * 仅当模块存在与 update 路径相同的 `type: 'get'` 动作，且 update 动作声明了对象类型 body schema 时生效；
  * 否则原样返回参数。GET 返回失败状态时会抛出 `E_API_FAILED`，避免继续发送未补齐的 PUT；
  * GET 成功但返回非对象时跳过填充，交由后续 PUT 正常处理。
  *
  * 字段归属判断同时覆盖平铺 `params` 字段与 `params.data` 中的字段；只有 schema 中声明、
  * 用户未传且当前对象存在的字段才会被补齐，避免覆盖用户本次想修改的字段。
  */
-async function autoFillUpdateParams(module, action, params, options) {
+async function autoFillUpdateParams(module, action, params, options, version) {
     const properties = action.requestBody?.schema?.properties;
-    const getAction = module.actions.find((candidate) => candidate.type === 'get');
+    const getAction = module.actions.find((candidate) => candidate.type === 'get' && candidate.path === action.path);
     if (!properties || !getAction)
         return params;
-    const current = (await request(`${module.name}/${getAction.name}`, params, {
+    const current = (await requestInternal(`${module.name}/${getAction.name}`, params, {
         client: options.client,
         timeout: options.timeout,
         insecure: options.insecure,
         throwOnFail: true,
-    })).data;
+    }, version)).data;
     if (!isRecord(current))
         return params;
     const explicitDataKeys = getExplicitDataKeys(params.data);
@@ -172,6 +173,10 @@ function normalizeResponse(command, raw, options) {
     return response;
 }
 export async function request(name, params = {}, options = {}) {
+    return requestInternal(name, params, options);
+}
+/** version 为 undefined 时解析一次，null 表示本次调用已选择跳过版本检查。 */
+async function requestInternal(name, params, options, version) {
     const globals = getGlobalOptions();
     const client = options.client ?? globals.client;
     if (!client) {
@@ -195,8 +200,35 @@ export async function request(name, params = {}, options = {}) {
     if (!action) {
         throw new ZentaoError('E_INVALID_ACTION', { module: moduleName, action: actionName });
     }
+    if (version === undefined) {
+        if (!options.forceRefreshConfig && globals.version !== undefined) {
+            version = globals.version;
+        }
+        else {
+            try {
+                version = (await client.getZentaoConfig({
+                    forceRefresh: options.forceRefreshConfig,
+                    timeout: options.timeout ?? globals.timeout,
+                    insecure: options.insecure ?? globals.insecure,
+                })).version;
+            }
+            catch (error) {
+                if (!(options.skipVersionCheckOnConfigError ?? globals.skipVersionCheckOnConfigError)
+                    || !isZentaoConfigFetchError(error))
+                    throw error;
+                version = null;
+            }
+        }
+    }
+    if (version !== null && !supportsZentaoVersion(parseZentaoVersion(version), action.minVersion)) {
+        throw new ZentaoError('E_UNSUPPORTED_ZENTAO_VERSION', {
+            action: `${module.name}/${action.name}`,
+            version,
+            minVersion: action.minVersion.join(', '),
+        }, { action: `${module.name}/${action.name}`, version, minVersion: action.minVersion });
+    }
     const finalParams = action.type === 'update' && (options.autoFill ?? globals.autoFill)
-        ? await autoFillUpdateParams(module, action, mergedParams, options)
+        ? await autoFillUpdateParams(module, action, mergedParams, { ...options, client }, version)
         : mergedParams;
     const command = resolveActionRequest(module, actionName, finalParams);
     const preparedBody = await prepareActionBody(command, {

package/dist/types/client.d.ts

@@ -23,12 +23,12 @@ export interface ClientRequestOptions {
     body?: unknown;
     /** 请求体序列化方式。默认 `json`；传入 `FormData` 等原生 body 时会自动按 `raw` 处理。 */
     bodyType?: ClientRequestBodyType;
-    /** 响应体解析方式。默认 `auto`，会优先尝试 JSON，失败后回落为文本。 */
+    /** 响应体解析方式。默认 `auto`，会优先尝试 JSON，失败后回落为文本；`response` 会让 signal 和 timeout 继续控制响应体。 */
     responseType?: ClientResponseType;
     /** 额外请求头；会与 SDK 自动注入的 `Token` / `Content-Type` 合并。 */
     headers?: HeadersInit;
-    /** URL 查询参数；`undefined` 值会被跳过。 */
-    query?: Record<string, string | number | boolean | undefined>;
+    /** URL 查询参数；对象和数组使用 deepObject 风格序列化，`undefined` 值会被跳过。 */
+    query?: Record<string, unknown>;
     /** 外部取消信号；会与 SDK 自身的超时控制合并。 */
     signal?: AbortSignal;
     /** 单次请求超时时间，优先级高于全局和客户端默认值。 */
@@ -36,3 +36,8 @@ export interface ClientRequestOptions {
     /** 单次请求 TLS 跳过证书验证选项；仅 Node.js 运行时支持。 */
     insecure?: boolean;
 }
+/** {@link ZentaoClient.getZentaoConfig} 的选项。 */
+export interface GetZentaoConfigOptions extends Pick<ClientRequestOptions, 'timeout' | 'insecure' | 'signal'> {
+    /** 忽略已有缓存并重新获取配置，默认 false；同一客户端的并发获取会合并。 */
+    forceRefresh?: boolean;
+}

package/dist/types/module.d.ts

@@ -27,9 +27,13 @@ export interface ModuleActionParam {
     /** 未显式传入时使用的默认值。 */
     defaultValue?: unknown;
     /** 参数值类型，用于基础类型转换。 */
-    type?: 'string' | 'number' | 'boolean';
+    type?: 'string' | 'number' | 'boolean' | 'array' | 'object';
     /** OpenAPI schema format，例如 `binary` 或 `int32`。 */
     format?: string;
+    /** OpenAPI 查询参数序列化样式，例如 `deepObject`。 */
+    style?: string;
+    /** OpenAPI 查询参数是否展开序列化。 */
+    explode?: boolean;
     /** 参数可选值。 */
     options?: readonly ModuleActionParamOption[];
 }
@@ -86,6 +90,8 @@ export type ModuleActionGetterFn<T, O = RequestProcessOptions> = (data: unknown,
 export interface ModuleAction {
     /** 动作名称，例如 `list`、`get`、`close`。 */
     name: ModuleActionName;
+    /** 各系列支持的最低禅道正式版本，例如 `['22.0', 'biz13.0', 'max8.0', 'ipd5.0']`；不能为空或重复系列，未列出的系列不支持。 */
+    minVersion: readonly string[];
     /** 动作类型，决定高阶 request 的路径/参数解析策略，并在 `method`、`resultType` 省略时作为推导依据。 */
     type: ModuleActionType;
     /** 面向用户展示的动作名称。 */
@@ -136,6 +142,11 @@ export interface ModuleDefinition {
     /** 模块支持的动作集合。 */
     actions: readonly ModuleAction[];
 }
+/** 注册库查询选项；不传版本时返回完整的当前定义，不使用全局版本。 */
+export interface ModuleQueryOptions {
+    /** 仅返回该禅道版本支持的动作，以及至少含有一个支持动作的模块。 */
+    version?: string;
+}
 /** 将模块动作和参数解析后的可执行请求描述。 */
 export interface ModuleActionRequest {
     /** 模块名称。 */
@@ -147,7 +158,7 @@ export interface ModuleActionRequest {
     /** 已替换路径参数后的 API 路径。 */
     path: string;
     /** 已组装的查询参数。 */
-    query?: Record<string, string | number>;
+    query?: Record<string, unknown>;
     /** 已组装的请求体。 */
     data?: Record<string, unknown>;
     /** 从 `id` 或 `{module}ID` 推断出的对象 ID。 */

package/dist/types/options.d.ts

@@ -2,6 +2,10 @@ import type { ZentaoClient } from '../client/index.js';
 import type { ProcessListOptions, ProcessSingleOptions } from './data.js';
 /** SDK 进程级全局默认选项，供高阶 {@link request} 调用复用。 */
 export interface GlobalOptions {
+    /** 当前禅道正式版本，例如 `biz13.5`；普通高阶请求直接使用，单次强制刷新时使用实际版本。不会自动写入 profile。 */
+    version?: string;
+    /** 配置网络或响应获取失败时，允许登录继续或高阶请求跳过版本检查，默认 false；不忽略版本不匹配、格式错误或存储错误。 */
+    skipVersionCheckOnConfigError?: boolean;
     /** 默认客户端；通常由 `ZentaoClient.init()` 设置。 */
     client?: ZentaoClient;
     /** 默认每页记录数，会映射到模块动作的 `recPerPage` 参数。 */
@@ -25,6 +29,10 @@ export interface GlobalOptions {
 }
 /** 高阶 `request("moduleName")` / `request("moduleName/methodName")` / `request("moduleName/<objectID>")` 的单次调用选项。 */
 export interface RequestOptions extends ProcessListOptions {
+    /** 强制刷新服务器配置并用实际版本校验本次请求，优先于全局 version；不会改写全局版本。 */
+    forceRefreshConfig?: boolean;
+    /** 配置网络或响应获取失败时跳过本次版本检查；优先于全局设置，默认 false，不忽略版本不匹配或格式错误。 */
+    skipVersionCheckOnConfigError?: boolean;
     /** 本次调用使用的客户端；优先级高于全局客户端。 */
     client?: ZentaoClient;
     /** 本次调用使用的每页记录数，优先级高于全局 `recPerPage`。 */
@@ -49,6 +57,7 @@ export interface RequestOptions extends ProcessListOptions {
      * 动作 body schema 中声明的字段用现值补齐，再发起 PUT，避免禅道用空值覆盖未提交字段。
      * 因此只需传想修改的字段即可。仅对 `type: 'update'` 且模块存在 `type: 'get'` 动作时生效。
      *
+     * 只有模块中存在与 update 路径相同的 GET 动作时才会预取；否则直接发送更新请求。
      * 不传时回落到全局 `autoFill`，默认 false。
      */
     autoFill?: boolean;

package/dist/types/profile.d.ts

@@ -36,6 +36,8 @@ export interface ZentaoProfile {
     lastUsedTime?: string;
     /** 禅道服务端配置。 */
     serverConfig?: ServerConfig;
+    /** 成功从 `?mode=getconfig` 获取配置的本地 ISO 时间；缺失时缓存需要刷新。 */
+    serverConfigFetchedAt?: string;
     /** 客户端自定义配置。 */
     config?: ZentaoProfileConfig;
     /** 允许上层应用保存额外字段。 */

package/dist/types/response.d.ts

@@ -58,6 +58,13 @@ export interface LoginResponse extends ApiResponse {
 }
 /** 禅道 `?mode=getconfig` 返回的服务端配置。 */
 export interface ServerConfig {
+    /**
+     * 禅道版本，不同系列以不同的前缀表示，下面为例子：
+     * - `22.5`：开源版 22.5
+     * - `biz13.5`：企业版 13.5
+     * - `max8.5`：旗舰版 8.5
+     * - `ipd5.5`：IPD 5.5
+     */
     version: string;
     systemMode: string;
     sprintConcept: string;
@@ -67,4 +74,6 @@ export interface ServerConfig {
     methodVar: string;
     viewVar: string;
     sessionVar: string;
+    /** 保留服务端返回的其他配置字段。 */
+    [key: string]: unknown;
 }

package/dist/utils/doc-helper/index.d.ts

@@ -1,3 +1,2 @@
-export { snapshotToHtml } from './html.js';
 export { snapshotToMarkdown } from './markdown.js';
-export type { BlockRenderer, BlockSnapshot, ConvertOptions, DeltaInsert, DocSnapshot, DocSnapshotMeta, DocumentReference, HtmlOptions, JsonRecord, MarkdownOptions, OutputFormat, RenderBlockContext, SliceSnapshot, Snapshot, SnapshotEnvelope, SnapshotInput, TextSnapshot, UnknownBlockStrategy, } from './types.js';
+export type { BlockRenderer, BlockSnapshot, ConvertOptions, DeltaInsert, DocSnapshot, DocSnapshotMeta, DocumentReference, JsonRecord, MarkdownOptions, RenderBlockContext, SliceSnapshot, Snapshot, SnapshotEnvelope, SnapshotInput, TextSnapshot, UnknownBlockStrategy, } from './types.js';

package/dist/utils/doc-helper/index.js

@@ -1,2 +1 @@
-export { snapshotToHtml } from './html.js';
 export { snapshotToMarkdown } from './markdown.js';

package/dist/utils/doc-helper/inline.d.ts

@@ -1,3 +1,2 @@
 import type { BlockSnapshot, ConvertOptions } from './types.js';
 export declare function deltaToMarkdown(value: unknown, options: ConvertOptions, block?: BlockSnapshot): string;
-export declare function deltaToHtml(value: unknown, options: ConvertOptions, block?: BlockSnapshot): string;

package/dist/utils/doc-helper/inline.js

@@ -1,4 +1,4 @@
-import { deltaFrom, escapeMarkdownMath, escapeHtml, escapeHtmlAttribute, isRecord, resolveDocumentUrl, safeCssColor, safeFontSize, sanitizeUrl, toRecord, toStringValue, } from './shared.js';
+import { deltaFrom, escapeMarkdownMath, resolveDocumentUrl, sanitizeUrl, toRecord, toStringValue, } from './shared.js';
 function escapeMarkdownText(value) {
     return value
         .replace(/\\/g, '\\\\')
@@ -48,9 +48,8 @@ function renderMarkdownDelta(delta, options, block) {
     const latex = toStringValue(attributes.latex);
     const reference = referenceFrom(delta);
     const rawLink = toStringValue(attributes.link);
-    // The existing Markdown adapter has no holder matcher and therefore keeps
-    // the underlying insert (normally a single space). HTML has a dedicated
-    // readable holder representation below.
+    // The Markdown adapter has no holder matcher and therefore keeps the
+    // underlying insert (normally a single space).
     let raw = mention ?? delta.insert;
     const linkIsPlainText = !reference && (raw === '' || raw === rawLink);
     if (!reference && raw === '' && rawLink)
@@ -89,80 +88,3 @@ export function deltaToMarkdown(value, options, block) {
         .map(delta => renderMarkdownDelta(delta, options, block))
         .join('');
 }
-function htmlDataAttributes(data) {
-    if (!isRecord(data))
-        return '';
-    return ` data-holder-data="${escapeHtmlAttribute(JSON.stringify(data))}"`;
-}
-function renderHtmlDelta(delta, options, block) {
-    if (typeof delta.insert !== 'string')
-        return '';
-    const attributes = toRecord(delta.attributes);
-    const holder = toRecord(attributes.holder);
-    if (Object.keys(holder).length) {
-        const text = toStringValue(holder.text) || toStringValue(holder.name) || delta.insert;
-        const id = toStringValue(holder.id);
-        const name = toStringValue(holder.name);
-        const hint = toStringValue(holder.hint);
-        return `<code class="affine-zui-holder"${id ? ` data-holder-id="${escapeHtmlAttribute(id)}"` : ''}${name ? ` data-holder-name="${escapeHtmlAttribute(name)}"` : ''}${hint ? ` title="${escapeHtmlAttribute(hint)}"` : ''}${htmlDataAttributes(holder.data)}>${escapeHtml(text)}</code>`;
-    }
-    const mention = toRecord(attributes.mention);
-    if (Object.keys(mention).length) {
-        const label = toStringValue(mention.label) || toStringValue(mention.name);
-        const id = toStringValue(mention.id);
-        const type = toStringValue(mention.type);
-        return `<span class="affine-zui-mention-label"${id ? ` data-id="${escapeHtmlAttribute(id)}"` : ''}${type ? ` data-type="${escapeHtmlAttribute(type)}"` : ''}>@${escapeHtml(label)}</span>`;
-    }
-    const latex = toStringValue(attributes.latex);
-    if (latex) {
-        return `<span class="affine-inline-latex" data-latex="${escapeHtmlAttribute(latex)}">${escapeHtml(latex)}</span>`;
-    }
-    const reference = referenceFrom(delta);
-    const visibleText = reference
-        ? options.resolveDocTitle?.(reference.pageId) ||
-            delta.insert.trim() ||
-            reference.pageId
-        : delta.insert;
-    let output = escapeHtml(visibleText).replace(/\n/g, '<br>');
-    if (attributes.bold)
-        output = `<strong>${output}</strong>`;
-    if (attributes.italic)
-        output = `<em>${output}</em>`;
-    if (attributes.strike)
-        output = `<del>${output}</del>`;
-    if (attributes.underline)
-        output = `<u>${output}</u>`;
-    if (attributes.code)
-        output = `<code>${output}</code>`;
-    if (attributes.sub)
-        output = `<sub>${output}</sub>`;
-    if (attributes.sup)
-        output = `<sup>${output}</sup>`;
-    const styles = [];
-    const color = safeCssColor(attributes.color);
-    const background = safeCssColor(attributes.background);
-    const fontSize = safeFontSize(attributes.fontSize);
-    if (color)
-        styles.push(`color:${color}`);
-    if (background)
-        styles.push(`background-color:${background}`);
-    if (fontSize)
-        styles.push(`font-size:${fontSize}`);
-    if (styles.length)
-        output = `<span style="${styles.join(';')}">${output}</span>`;
-    let url = sanitizeUrl(attributes.link);
-    if (reference) {
-        url = resolveDocumentUrl(options, {
-            ...reference,
-            title: options.resolveDocTitle?.(reference.pageId),
-        }, block);
-    }
-    return url
-        ? `<a href="${escapeHtmlAttribute(url)}">${output}</a>`
-        : output;
-}
-export function deltaToHtml(value, options, block) {
-    return deltaFrom(value)
-        .map(delta => renderHtmlDelta(delta, options, block))
-        .join('');
-}

package/dist/utils/doc-helper/shared.d.ts

@@ -22,9 +22,6 @@ export declare function validateSnapshotTree(blocks: readonly BlockSnapshot[], o
 export declare function deltaFrom(value: unknown): DeltaInsert[];
 export declare function plainText(value: unknown): string;
 export declare function pageTitleDelta(normalized: NormalizedSnapshot): DeltaInsert[];
-export declare function pageTitleText(normalized: NormalizedSnapshot): string;
-export declare function escapeHtml(value: unknown): string;
-export declare function escapeHtmlAttribute(value: unknown): string;
 export declare function sanitizeUrl(value: unknown, kind?: 'link' | 'image'): string;
 export declare function resolveAssetUrl(options: ConvertOptions, block: BlockSnapshot, kind: 'image' | 'attachment'): string;
 export declare function resolveZuiImageUrl(options: ConvertOptions, block: BlockSnapshot): string;
@@ -33,5 +30,3 @@ export declare function formatFileSize(value: unknown): string;
 export declare function isEdgelessOnly(block: BlockSnapshot): boolean;
 export declare function safeLanguage(value: unknown): string;
 export declare function escapeMarkdownMath(value: unknown): string;
-export declare function safeCssColor(value: unknown): string;
-export declare function safeFontSize(value: unknown): string;

package/dist/utils/doc-helper/shared.js

@@ -160,23 +160,6 @@ export function pageTitleDelta(normalized) {
     const metaTitle = normalized.meta?.title;
     return typeof metaTitle === 'string' ? [{ insert: metaTitle }] : [];
 }
-export function pageTitleText(normalized) {
-    const metaTitle = normalized.meta?.title;
-    if (typeof metaTitle === 'string')
-        return metaTitle;
-    return plainText(toRecord(normalized.root?.props).title);
-}
-export function escapeHtml(value) {
-    return String(value ?? '')
-        .replace(/&/g, '&')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;');
-}
-export function escapeHtmlAttribute(value) {
-    return escapeHtml(value)
-        .replace(/"/g, '&quot;')
-        .replace(/'/g, '&#39;');
-}
 export function sanitizeUrl(value, kind = 'link') {
     if (typeof value !== 'string')
         return '';
@@ -286,20 +269,3 @@ export function escapeMarkdownMath(value) {
         return `${prefix}${target.replace(/:|&(?:#0*58|#x0*3a|colon);/i, '%3A')}`;
     });
 }
-export function safeCssColor(value) {
-    if (typeof value !== 'string')
-        return '';
-    const color = value.trim();
-    if (/^(#[\da-f]{3,8}|(?:rgb|hsl)a?\([\d\s.,%+-]+\)|var\(--[\w-]+\)|[a-z]+)$/i.test(color)) {
-        return color;
-    }
-    return '';
-}
-export function safeFontSize(value) {
-    if (typeof value !== 'string')
-        return '';
-    const size = value.trim();
-    return /^(?:\d+(?:\.\d+)?(?:px|em|rem|%|pt)|var\(--[\w-]+\))$/i.test(size)
-        ? size
-        : '';
-}

package/dist/utils/doc-helper/types.d.ts

@@ -37,7 +37,6 @@ export interface SnapshotEnvelope {
     snapshot: Snapshot | readonly BlockSnapshot[];
 }
 export type SnapshotInput = Snapshot | readonly BlockSnapshot[] | SnapshotEnvelope | string;
-export type OutputFormat = 'markdown' | 'html';
 export type UnknownBlockStrategy = 'children' | 'omit' | 'throw';
 export interface DocumentReference {
     pageId: string;
@@ -45,7 +44,7 @@ export interface DocumentReference {
     title?: string;
 }
 export interface RenderBlockContext {
-    format: OutputFormat;
+    format: 'markdown';
     renderChildren(children?: readonly BlockSnapshot[]): string;
     renderInline(text: unknown): string;
 }
@@ -73,14 +72,3 @@ export interface ConvertOptions {
     unknownBlock?: UnknownBlockStrategy;
 }
 export type MarkdownOptions = ConvertOptions;
-export interface HtmlOptions extends ConvertOptions {
-    /**
-     * Defaults to true for a DocSnapshot/page root and false for block/slice input.
-     */
-    fullDocument?: boolean;
-    /**
-     * Render stored HTML from affine:embed-zui-html or zui-custom as trusted HTML.
-     * Disabled by default.
-     */
-    allowUnsafeHtml?: boolean;
-}

package/dist/version.js

@@ -1,5 +1,5 @@
-const fallbackBuild = "2026-08-21T05:05:30.639Z";
-const fallbackVersion = "0.6.5";
+const fallbackBuild = "2026-09-05T14:37:58.417Z";
+const fallbackVersion = "0.6.7";
 /**
  * 构建标识，由构建脚本通过 `__ZENTAO_API_BUILD__` 注入。
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zentao-api",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "type": "module",
   "description": "Browser and Node.js SDK for ZenTao API",
   "license": "MIT",
@@ -47,6 +47,7 @@
     "typecheck": "tsc --noEmit",
     "typecheck:tests": "tsc -p tsconfig.test.json --noEmit",
     "registry:check": "bun run scripts/update-registry.ts --check",
+    "registry:audit": "bun run .agents/skills/update-openapi-registry/scripts/audit-generated-registry.ts",
     "build": "rm -rf dist && tsc -p tsconfig.json && bun run scripts/build-browser.ts",
     "smoke:node": "node scripts/smoke-node.mjs",
     "smoke:browser": "bun run scripts/smoke-browser-bundler.ts",
@@ -57,16 +58,16 @@
     "docs:dev": "bun run docs:generate && vitepress dev docs",
     "docs:build": "bun run docs:generate && vitepress build docs",
     "docs:preview": "bun run docs:build && vitepress preview docs",
-    "check": "bun run test:coverage && bun run typecheck && bun run typecheck:tests && bun run registry:check && bun run build && bun run smoke:node && bun run smoke:browser && bun run smoke:package",
+    "check": "bun run test:coverage && bun run typecheck && bun run typecheck:tests && bun run registry:check && bun run registry:audit && bun run build && bun run smoke:node && bun run smoke:browser && bun run smoke:package",
     "prepublishOnly": "bun run check"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.13",
-    "@types/node": "^24.10.0",
-    "typedoc": "^0.28.19",
-    "typedoc-plugin-markdown": "^4.11.0",
-    "typedoc-vitepress-theme": "^1.1.2",
-    "typescript": "^5.7.0",
+    "@types/bun": "^1.4.0",
+    "@types/node": "^24.13.3",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0",
+    "typedoc-vitepress-theme": "^1.1.3",
+    "typescript": "^5.9.3",
     "vitepress": "^1.6.4"
   },
   "engines": {

package/dist/utils/doc-helper/html.d.ts

@@ -1,3 +0,0 @@
-import type { HtmlOptions, SnapshotInput } from './types.js';
-/** Convert a BlockSuite 0.19.x snapshot to semantic, escaped HTML. */
-export declare function snapshotToHtml(input: SnapshotInput, options?: HtmlOptions): string;