@h-ai/feedback 0.0.0-stage → 0.1.0-alpha.69

package/dist/bundle/index.d.ts

@@ -0,0 +1,212 @@
+import { PaginatedResult, HaiResult } from '@h-ai/core';
+
+/**
+ * 离线证据项；业务字段放在 data 中，读取器不理解业务表结构。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleEvidence } from '@h-ai/feedback/bundle'
+ * const event: FeedbackBundleEvidence = { source: 'browser', kind: 'log', timestamp: 1, data: { message: 'ready' } }
+ * ```
+ */
+interface FeedbackBundleEvidence {
+    id?: string;
+    source: string;
+    kind: string;
+    timestamp: number;
+    sequence?: number;
+    requestId?: string;
+    errorId?: string;
+    missingReason?: string;
+    data?: unknown;
+}
+/**
+ * 随包传输的二进制附件，名称只作显示，不用于构造文件路径。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleAttachment } from '@h-ai/feedback/bundle'
+ * const file: FeedbackBundleAttachment = { id: 'file-1', name: 'notes.txt', contentType: 'text/plain', bytes: new TextEncoder().encode('diagnostic notes') }
+ * ```
+ */
+interface FeedbackBundleAttachment {
+    id: string;
+    name: string;
+    contentType: string;
+    bytes: Uint8Array;
+    checksum?: string;
+}
+/**
+ * 离线包的输入；泛型允许直接传入框架报告类型，不要求调用方添加索引签名。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleInput } from '@h-ai/feedback/bundle'
+ * const input: FeedbackBundleInput = { report: { id: 'report-1' }, evidence: [], missing: ['screenshot-unavailable'] }
+ * ```
+ */
+interface FeedbackBundleInput<TReport extends {
+    id: string;
+} = {
+    id: string;
+}> {
+    report: TReport;
+    evidence: readonly FeedbackBundleEvidence[];
+    history?: readonly object[];
+    attachments?: readonly FeedbackBundleAttachment[];
+    missing?: readonly string[];
+}
+/**
+ * manifest 中单个文件的完整性与展示信息。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleFile } from '@h-ai/feedback/bundle'
+ * const metadata: FeedbackBundleFile = { path: 'report.json', size: 2, sha256: '0'.repeat(64), kind: 'report' }
+ * ```
+ */
+interface FeedbackBundleFile {
+    path: string;
+    size: number;
+    sha256: string;
+    kind: 'report' | 'evidence' | 'history' | 'attachment' | 'summary' | 'viewer';
+    attachmentId?: string;
+    name?: string;
+    contentType?: string;
+}
+/**
+ * 版本化的离线包清单；manifest 本身不声称具备来源签名。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleManifest } from '@h-ai/feedback/bundle'
+ * const manifest: FeedbackBundleManifest = { format: 'hai-feedback', version: 1, reportId: 'report-1', evidenceRevision: 1, createdAt: 1, missing: [], files: [] }
+ * ```
+ */
+interface FeedbackBundleManifest {
+    format: 'hai-feedback';
+    version: 1;
+    reportId: string;
+    evidenceRevision: number;
+    createdAt: number;
+    missing: string[];
+    files: FeedbackBundleFile[];
+}
+/**
+ * 校验后的离线包；files 中的内容仍是待显示的非可信输入。
+ * @example
+ * ```ts
+ * import type { FeedbackBundle } from '@h-ai/feedback/bundle'
+ * import { readFeedbackBundle } from '@h-ai/feedback/bundle'
+ * async function parse(bytes: Uint8Array): Promise<FeedbackBundle | undefined> {
+ *   const result = await readFeedbackBundle(bytes)
+ *   return result.success ? result.data : undefined
+ * }
+ * ```
+ */
+interface FeedbackBundle {
+    manifest: FeedbackBundleManifest;
+    report: Record<string, unknown> & {
+        id: string;
+    };
+    evidence: FeedbackBundleEvidence[];
+    history: Record<string, unknown>[];
+    files: Readonly<Record<string, Uint8Array>>;
+}
+/**
+ * ZIP 解压与读取上限，在解压前及解压后均核对。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleReadOptions } from '@h-ai/feedback/bundle'
+ * const limits: FeedbackBundleReadOptions = { maxFiles: 100, maxBytes: 8 * 1024 * 1024, maxFileBytes: 2 * 1024 * 1024 }
+ * ```
+ */
+interface FeedbackBundleReadOptions {
+    maxFiles?: number;
+    maxBytes?: number;
+    maxFileBytes?: number;
+}
+/**
+ * 按索引分页读取证据，不要求把所有日志送入 AI 上下文。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleQuery } from '@h-ai/feedback/bundle'
+ * const query: FeedbackBundleQuery = { errorId: 'error-1', page: 1, pageSize: 20 }
+ * ```
+ */
+interface FeedbackBundleQuery {
+    page?: number;
+    pageSize?: number;
+    kind?: string;
+    requestId?: string;
+    errorId?: string;
+    from?: number;
+    to?: number;
+}
+/**
+ * 离线证据分页结果。
+ * @example
+ * ```ts
+ * import type { FeedbackBundleEvidencePage } from '@h-ai/feedback/bundle'
+ * const page: FeedbackBundleEvidencePage = { items: [], total: 0, page: 1, pageSize: 20 }
+ * ```
+ */
+type FeedbackBundleEvidencePage = PaginatedResult<FeedbackBundleEvidence>;
+
+/**
+ * 生成含摘要、证据索引、附件与静态查看器的 ZIP；调用前应完成授权与脱敏。
+ * @example
+ * ```ts
+ * import { createFeedbackBundle } from '@h-ai/feedback/bundle'
+ * const result = await createFeedbackBundle({ report: { id: 'fb_1' }, evidence: [] })
+ * if (result.success) { const bytes: Uint8Array = result.data }
+ * ```
+ */
+declare function createFeedbackBundle<TReport extends {
+    id: string;
+}>(input: FeedbackBundleInput<TReport>): Promise<HaiResult<Uint8Array>>;
+/**
+ * 校验 ZIP 路径、容量、协议与所有文件的 SHA-256 后读取；不执行包内代码。
+ * @example
+ * ```ts
+ * import { createFeedbackBundle, readFeedbackBundle } from '@h-ai/feedback/bundle'
+ * const created = await createFeedbackBundle({ report: { id: 'fb_1' }, evidence: [] })
+ * if (created.success) {
+ *   const parsed = await readFeedbackBundle(created.data, { maxBytes: 32 * 1024 * 1024 })
+ *   if (parsed.success) { const reportId: string = parsed.data.report.id }
+ * }
+ * ```
+ */
+declare function readFeedbackBundle(bytes: Uint8Array, options?: FeedbackBundleReadOptions): Promise<HaiResult<FeedbackBundle>>;
+/**
+ * 生成人工与 AI 可读摘要，明确用户描述与采集事实。
+ * @example
+ * ```ts
+ * import { createFeedbackBundle, readFeedbackBundle, summarizeFeedbackBundle } from '@h-ai/feedback/bundle'
+ * const created = await createFeedbackBundle({ report: { id: 'fb_1' }, evidence: [] })
+ * if (created.success) {
+ *   const parsed = await readFeedbackBundle(created.data)
+ *   if (parsed.success) { const markdown: string = summarizeFeedbackBundle(parsed.data) }
+ * }
+ * ```
+ */
+declare function summarizeFeedbackBundle(bundle: FeedbackBundle): string;
+/**
+ * 通过时间、请求、错误与类型筛选离线证据；错误按锚点来源和请求取前后各 100 条，分页最大 100 条。
+ * @example
+ * ```ts
+ * import { createFeedbackBundle, queryFeedbackBundle, readFeedbackBundle } from '@h-ai/feedback/bundle'
+ * const created = await createFeedbackBundle({ report: { id: 'fb_1' }, evidence: [] })
+ * if (created.success) {
+ *   const parsed = await readFeedbackBundle(created.data)
+ *   if (parsed.success) { const page = queryFeedbackBundle(parsed.data, { requestId: 'req_1', page: 1, pageSize: 20 }) }
+ * }
+ * ```
+ */
+declare function queryFeedbackBundle(bundle: FeedbackBundle, query?: FeedbackBundleQuery): FeedbackBundleEvidencePage;
+/**
+ * 获取内置可信离线查看器；本地服务必须使用此资源而不是执行导入包中的脚本。
+ * @example
+ * ```ts
+ * import { getFeedbackBundleViewerFiles } from '@h-ai/feedback/bundle'
+ * const html: Uint8Array | undefined = getFeedbackBundleViewerFiles()['viewer/index.html']
+ * ```
+ */
+declare function getFeedbackBundleViewerFiles(): Readonly<Record<string, Uint8Array>>;
+
+export { type FeedbackBundle, type FeedbackBundleAttachment, type FeedbackBundleEvidence, type FeedbackBundleEvidencePage, type FeedbackBundleFile, type FeedbackBundleInput, type FeedbackBundleManifest, type FeedbackBundleQuery, type FeedbackBundleReadOptions, createFeedbackBundle, getFeedbackBundleViewerFiles, queryFeedbackBundle, readFeedbackBundle, summarizeFeedbackBundle };

package/dist/bundle/index.js

@@ -0,0 +1,3 @@
+export { createFeedbackBundle, getFeedbackBundleViewerFiles, queryFeedbackBundle, readFeedbackBundle, summarizeFeedbackBundle } from '../chunk-43AOXE4W.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/bundle/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}