@native-knowledge/knowledge-sdk 0.0.0-stage → 0.1.0-rc.2

package/dist/index.d.ts

@@ -0,0 +1,290 @@
+/// <reference types="node" />
+import { type MaterialStreamOptions } from './material-stream.js';
+export * from './resource.js';
+export type { MaterialStreamOptions, MaterialStreamResponse } from './material-stream.js';
+export * from './oauth.js';
+import { type MaterialOutboxWindow, type ServingArtifactListResponse, type ServingArtifactPageResponse, type ServingArtifactMaterialPageResponse, type ServingArtifactMaterialResponse, type ServingMaterialPageResponse, type ServingMaterialRoutePageResponse, type ServingMaterialPartitionsResponse, type ServingMaterialPartitionPageResponse, type ServingMaterialSearchResponse, type ServingArtifactResponse, type ServingContentDecisionResponse, type ServingCurrentnessResponse, type ServingEvidenceListResponse, type ServingEvidencePageResponse, type ServingEvidencePresentationResponse, type ServingEvidenceResponse, type ServingHealthResponse, type ServingReferenceListResponse, type ServingReferenceLookupResponse, type ServingReferenceResponse, type ServingReferenceMaterialPageResponse, type ServingReferenceMaterialResponse, type ReferenceLookupFilter, type ServingProjectIntentResponse, type ServingProjectSourceListResponse, type ServingProjectSourceResponse, type ServingSourceResponse } from './internal/serving-contracts/index.js';
+export interface KnowledgeServingClientOptions {
+    baseUrl: string;
+    token: string;
+    projectKey: string;
+    fetchImpl?: typeof fetch;
+    allowInsecureHttp?: boolean;
+}
+export interface ServingContentResponse {
+    decision: ServingContentDecisionResponse['decision'];
+    descriptor: {
+        contentHash: string;
+        mediaType: string;
+        byteLength: number;
+    };
+    content: Buffer;
+}
+export declare class KnowledgeServingClient {
+    readonly projectKey: string;
+    private readonly root;
+    private readonly basePath;
+    private readonly token;
+    private readonly fetchImpl;
+    constructor(options: KnowledgeServingClientOptions);
+    private url;
+    private request;
+    private json;
+    health(): Promise<ServingHealthResponse>;
+    listArtifacts(options?: {
+        kind?: string;
+        limit?: number;
+    }): Promise<ServingArtifactListResponse>;
+    pageArtifacts(options?: {
+        kind?: string;
+        limit?: number;
+        after?: string;
+    }): Promise<ServingArtifactPageResponse>;
+    pageArtifactMaterials(options?: {
+        kind?: string;
+        limit?: number;
+        after?: string;
+    }): Promise<ServingArtifactMaterialPageResponse>;
+    getMaterialOutboxWindow(): Promise<MaterialOutboxWindow>;
+    pageMaterials(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<ServingMaterialPageResponse>;
+    pageRouteMaterials(routeId: string, options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<ServingMaterialRoutePageResponse>;
+    pageMaterialPartitions(options?: {
+        afterRouteId?: string;
+        limit?: number;
+    }): Promise<ServingMaterialPartitionsResponse>;
+    pageMaterialPartition(partition: 'OWNER' | 'LEGACY', options?: {
+        after?: string;
+        limit?: number;
+    }): Promise<ServingMaterialPartitionPageResponse>;
+    searchMaterials(query: string, options?: {
+        afterId?: number;
+        limit?: number;
+        resourceType?: string;
+        sourceProjectKey?: string;
+    }): Promise<ServingMaterialSearchResponse>;
+    getArtifactMaterial(ref: string): Promise<ServingArtifactMaterialResponse>;
+    getArtifact(ref: string): Promise<ServingArtifactResponse>;
+    listEvidence(options?: {
+        sourceId?: string;
+        limit?: number;
+    }): Promise<ServingEvidenceListResponse>;
+    /** 通用采集文件目录按 ref 续页；fileDecision 控制原文件，contentDecision 控制受治理正文。 */
+    pageEvidence(options?: {
+        sourceId?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<ServingEvidencePageResponse>;
+    getEvidencePresentation(ref: string): Promise<ServingEvidencePresentationResponse>;
+    getEvidence(ref: string): Promise<ServingEvidenceResponse>;
+    getProjectIntent(): Promise<ServingProjectIntentResponse>;
+    listProjectSources(options?: {
+        enabled?: boolean;
+        limit?: number;
+    }): Promise<ServingProjectSourceListResponse>;
+    getProjectSource(sourceId: string): Promise<ServingProjectSourceResponse>;
+    getGovernanceSource(sourceId: string): Promise<ServingSourceResponse>;
+    getSource(sourceId: string): Promise<ServingSourceResponse>;
+    getCurrentness(ref: string): Promise<ServingCurrentnessResponse>;
+    listReferences(corpusKey: string, options?: {
+        recordType?: string;
+        limit?: number;
+    }): Promise<ServingReferenceListResponse>;
+    getReference(corpusKey: string, ref: string): Promise<ServingReferenceResponse>;
+    pageReferenceMaterials(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<ServingReferenceMaterialPageResponse>;
+    getReferenceMaterial(ref: string): Promise<ServingReferenceMaterialResponse>;
+    lookupReferences(options: ReferenceLookupFilter): Promise<ServingReferenceLookupResponse>;
+    private rawContent;
+    getMaterialContract(): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        authentication: "API_KEY";
+        resourceTypeMode: "OPEN_IDENTIFIER";
+        capabilitiesEndpoint: "/v3/material-capabilities";
+        capabilityPageEndpoint: "/v3/material-page";
+        fileEndpoint: "/v2/material-file";
+        mediaPageEndpoint: "/v3/material-media-page";
+        indexStatusEndpoint: "/v3/material-index-status";
+        fileMethods: ["GET", "HEAD"];
+        fileRange: "SINGLE";
+    }>;
+    getMaterialCapabilities(ref: string): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        material: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("GET" | "HEAD")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        };
+    }>;
+    pageMaterialCapabilities(options?: {
+        limit?: number;
+        after?: string;
+        resourceType?: string;
+        sourceProjectKey?: string;
+        refPrefix?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        items: {
+            item: {
+                ref: string;
+                resourceType: string;
+                sourceProjectKey: string;
+                identityHash: string;
+                kind: string;
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                mediaType: string;
+                decision: {
+                    schemaVersion: 1;
+                    action: "ALLOW" | "DENY";
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    assessedAt: string;
+                };
+            };
+            materialAccess: {
+                schemaVersion: 1;
+                action: "ALLOW" | "DENY";
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                assessedAt: string;
+            };
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("GET" | "HEAD")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            };
+        }[];
+        nextAfter: string | null;
+    }>;
+    pageMaterialMedia(ref: string, options?: {
+        afterOrdinal?: number;
+        limit?: number;
+        documentRef?: string;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        ref: string;
+        sourceContentHash: string;
+        documentRef: string | null;
+        documentContentHash: string | null;
+        state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+        items: {
+            ordinal: number;
+            kind: "IMAGE" | "AUDIO" | "VIDEO";
+            sourceUrl: string;
+            canonicalUrl: string | null;
+            availability: "UNAVAILABLE" | "MIRRORED" | "REMOTE_ONLY";
+            mediaRef: string | null;
+            contentHash: string | null;
+            mediaType: string | null;
+            byteLength: number | null;
+            state: "MISSING" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "READY" | "DENIED" | "REMOTE_ONLY";
+            representation: {
+                state: "MISSING" | "UNSUPPORTED" | "INTEGRITY_MISMATCH" | "READY" | "DENIED";
+                format: "JSON" | "BYTES";
+                transfer: "UNSUPPORTED" | "VERIFIED_STREAM" | "BUFFERED_JSON";
+                contentHash: string | null;
+                mediaType: string;
+                byteLength: number | null;
+                methods: ("GET" | "HEAD")[];
+                range: "NONE" | "SINGLE";
+                verification: "ON_READ";
+                verificationChunkBytes: number | null;
+            } | null;
+        }[];
+        nextAfterOrdinal: number | null;
+    }>;
+    getMaterialIndexStatus(options?: {
+        afterSourceKey?: string;
+        afterNodeId?: string;
+        sourceProjectKey?: string;
+        limit?: number;
+    }): Promise<{
+        schemaVersion: 2;
+        projectKey: string;
+        queryCoverage: "DESCRIPTIVE_METADATA_V1";
+        indexedFields: ["TITLE", "SUMMARY"];
+        bodyIndexed: false;
+        semanticIndexed: false;
+        items: {
+            sourceProjectKey: string;
+            nodeId: string;
+            directoryThroughSeq: number;
+            searchThroughSeq: number | null;
+            observedMaxSeq: number | null;
+            checkpointUpdatedAt: string | null;
+            state: "PARTIAL_BACKFILL" | "SYNCED_AS_OF_CHECKPOINT";
+        }[];
+        nextAfter: {
+            sourceProjectKey: string;
+            nodeId: string;
+        } | null;
+    }>;
+    openMaterialStream(ref: string, options?: MaterialStreamOptions): Promise<import("./material-stream.js").MaterialStreamResponse>;
+    getMaterialFile(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getContent(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getArtifactFile(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getMedia(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    getEvidenceMedia(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+    /** 读取未经知识审核的原始 Evidence 文件；调用方仍需自己处理其时效与适用性。 */
+    getEvidenceFile(ref: string): Promise<ServingContentResponse | ServingContentDecisionResponse>;
+}
+export * from './tenant-management.js';
+export * from './tenant-workspace.js';
+export * from './tenant-project.js';
+export * from './tenant-runtime.js';
+export * from './tenant-web.js';
+export * from './tenant-web-crawl.js';
+export * from './tenant-web-dynamic.js';
+export * from './tenant-web-content.js';
+export * from './tenant-web-workflow.js';
+export * from './auth.js';
+export * from './token-provider.js';
+export * from './tenant-client.js';
+export * from './agent-entry.js';
+export * from './agent-guidance-error.js';

package/dist/index.js

@@ -0,0 +1,166 @@
+import { materialStream } from './material-stream.js';
+export * from './resource.js';
+import { apiKeyMaterialContractSchema, materialCapabilityResponseSchema, materialCapabilityPageSchema, materialMediaCapabilityPageSchema, materialIndexStatusSchema } from './internal/serving-contracts/index.js';
+import { createHash } from 'node:crypto';
+// OAuth 完整文件读取复用本包导出入口，避免每个消费者自行拼接鉴权 URL。
+export * from './oauth.js';
+import { projectKeySchema } from './internal/contracts/index.js';
+import { materialOutboxWindowSchema, servingApiErrorSchema, servingArtifactListResponseSchema, servingArtifactPageResponseSchema, servingArtifactMaterialPageResponseSchema, servingArtifactMaterialResponseSchema, servingMaterialPageResponseSchema, servingMaterialRoutePageResponseSchema, servingMaterialPartitionsResponseSchema, servingMaterialPartitionPageResponseSchema, servingMaterialSearchResponseSchema, servingArtifactResponseSchema, servingContentDecisionResponseSchema, servingCurrentnessResponseSchema, servingEvidenceListResponseSchema, servingEvidencePageResponseSchema, servingEvidencePresentationResponseSchema, servingEvidenceResponseSchema, servingHealthResponseSchema, servingReferenceListResponseSchema, servingReferenceLookupResponseSchema, servingReferenceResponseSchema, servingReferenceMaterialPageResponseSchema, servingReferenceMaterialResponseSchema, servingProjectIntentResponseSchema, servingProjectSourceListResponseSchema, servingProjectSourceResponseSchema, servingSourceResponseSchema, } from './internal/serving-contracts/index.js';
+function sha(bytes) { return `sha256:${createHash('sha256').update(bytes).digest('hex')}`; }
+function baseUrl(value, allowInsecureHttp) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash)
+        throw new Error('SERVING_SDK_BASE_URL_INVALID');
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new Error('SERVING_SDK_SCHEME_INVALID');
+    if (url.protocol === 'http:' && !allowInsecureHttp)
+        throw new Error('SERVING_SDK_HTTPS_REQUIRED');
+    url.pathname = url.pathname.replace(/\/+$/, '');
+    return url;
+}
+export class KnowledgeServingClient {
+    projectKey;
+    root;
+    basePath;
+    token;
+    fetchImpl;
+    constructor(options) { this.projectKey = projectKeySchema.parse(options.projectKey); if (!options.token || options.token.length < 16 || options.token.length > 4096)
+        throw new Error('SERVING_SDK_TOKEN_INVALID'); this.token = options.token; this.root = baseUrl(options.baseUrl, options.allowInsecureHttp === true); this.basePath = this.root.pathname === '/' ? '' : this.root.pathname.replace(/\/+$/, ''); this.fetchImpl = options.fetchImpl ?? fetch; }
+    url(pathname, params = {}) { const url = new URL(`${this.basePath}${pathname}`, this.root.origin); url.searchParams.set('projectKey', this.projectKey); for (const [key, value] of Object.entries(params))
+        if (value !== undefined)
+            url.searchParams.set(key, String(value)); return url; }
+    async request(url) { let response; try {
+        response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${this.token}`, accept: 'application/json,application/octet-stream' }, redirect: 'error' });
+    }
+    catch {
+        throw new Error('SERVING_SDK_TRANSPORT_FAILURE');
+    } return response; }
+    async json(url, schema) { const response = await this.request(url); let raw; try {
+        raw = await response.json();
+    }
+    catch {
+        throw new Error('SERVING_SDK_RESPONSE_INVALID');
+    } if (!response.ok) {
+        const parsed = servingApiErrorSchema.safeParse(raw);
+        if (parsed.success)
+            throw new Error(parsed.data.errorCode);
+        throw new Error('SERVING_SDK_HTTP_FAILURE');
+    } return schema.parse(raw); }
+    health() { const url = new URL(`${this.basePath}/healthz`, this.root.origin); return this.json(url, servingHealthResponseSchema); }
+    listArtifacts(options = {}) { return this.json(this.url('/v1/artifacts', options), servingArtifactListResponseSchema); }
+    pageArtifacts(options = {}) { return this.json(this.url('/v2/artifact-page', options), servingArtifactPageResponseSchema); }
+    pageArtifactMaterials(options = {}) { return this.json(this.url('/v2/artifact-material-page', options), servingArtifactMaterialPageResponseSchema); }
+    getMaterialOutboxWindow() { return this.json(this.url('/v2/material-outbox-window'), materialOutboxWindowSchema); }
+    pageMaterials(options = {}) { return this.json(this.url('/v2/material-page', options), servingMaterialPageResponseSchema); }
+    pageRouteMaterials(routeId, options = {}) { return this.json(this.url('/v2/material-route-page', { routeId, ...options }), servingMaterialRoutePageResponseSchema); }
+    pageMaterialPartitions(options = {}) { return this.json(this.url('/v3/material-partitions', options), servingMaterialPartitionsResponseSchema); }
+    pageMaterialPartition(partition, options = {}) { return this.json(this.url('/v3/material-partition-page', { partition, ...options }), servingMaterialPartitionPageResponseSchema); }
+    searchMaterials(query, options = {}) { return this.json(this.url('/v2/material-search', { query, ...options }), servingMaterialSearchResponseSchema); }
+    getArtifactMaterial(ref) { return this.json(this.url('/v2/artifact-material', { ref }), servingArtifactMaterialResponseSchema); }
+    getArtifact(ref) { return this.json(this.url('/v1/artifact', { ref }), servingArtifactResponseSchema); }
+    listEvidence(options = {}) { return this.json(this.url('/v1/evidence-list', options), servingEvidenceListResponseSchema); }
+    /** 通用采集文件目录按 ref 续页；fileDecision 控制原文件，contentDecision 控制受治理正文。 */
+    pageEvidence(options = {}) { return this.json(this.url('/v1/evidence-page', options), servingEvidencePageResponseSchema); }
+    async getEvidencePresentation(ref) {
+        const response = await this.request(this.url('/v2/evidence-presentation', { ref }));
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('SERVING_SDK_RESPONSE_INVALID');
+        }
+        const result = servingEvidencePresentationResponseSchema.safeParse(raw);
+        if (result.success)
+            return result.data;
+        const error = servingApiErrorSchema.safeParse(raw);
+        if (error.success)
+            throw new Error(error.data.errorCode);
+        throw new Error('SERVING_SDK_RESPONSE_INVALID');
+    }
+    getEvidence(ref) { return this.json(this.url('/v1/evidence', { ref }), servingEvidenceResponseSchema); }
+    getProjectIntent() { return this.json(this.url('/v1/project-intent'), servingProjectIntentResponseSchema); }
+    listProjectSources(options = {}) { return this.json(this.url('/v1/project-sources', { ...(options.enabled !== undefined ? { enabled: String(options.enabled) } : {}), ...(options.limit !== undefined ? { limit: options.limit } : {}) }), servingProjectSourceListResponseSchema); }
+    getProjectSource(sourceId) { return this.json(this.url('/v1/project-source', { sourceId }), servingProjectSourceResponseSchema); }
+    getGovernanceSource(sourceId) { return this.json(this.url('/v1/governance-source', { sourceId }), servingSourceResponseSchema); }
+    getSource(sourceId) { return this.getGovernanceSource(sourceId); }
+    getCurrentness(ref) { return this.json(this.url('/v1/currentness', { ref }), servingCurrentnessResponseSchema); }
+    listReferences(corpusKey, options = {}) { return this.json(this.url('/v1/references', { corpusKey, ...options }), servingReferenceListResponseSchema); }
+    getReference(corpusKey, ref) { return this.json(this.url('/v1/reference', { corpusKey, ref }), servingReferenceResponseSchema); }
+    pageReferenceMaterials(options = {}) { return this.json(this.url('/v2/reference-material-page', options), servingReferenceMaterialPageResponseSchema); }
+    getReferenceMaterial(ref) { return this.json(this.url('/v2/reference-material', { ref }), servingReferenceMaterialResponseSchema); }
+    lookupReferences(options) {
+        const url = this.url('/v1/reference-lookup', { ...(options.jurisdiction ? { jurisdiction: options.jurisdiction } : {}), ...(options.effectiveAt ? { effectiveAt: options.effectiveAt } : {}), ...(options.limit !== undefined ? { limit: options.limit } : {}) });
+        for (const value of options.corpusKeys ?? [])
+            url.searchParams.append('corpusKey', value);
+        for (const value of options.recordTypes ?? [])
+            url.searchParams.append('recordType', value);
+        for (const [key, values] of Object.entries(options.selectors ?? {}).sort(([a], [b]) => a.localeCompare(b)))
+            for (const value of values)
+                url.searchParams.append(`selector.${key}`, value);
+        return this.json(url, servingReferenceLookupResponseSchema);
+    }
+    async rawContent(pathname, ref) {
+        const response = await this.request(this.url(pathname, { ref }));
+        const action = response.headers.get('x-knowledge-serving-action');
+        if (response.ok && action === 'ALLOW') {
+            // 原始文件必须显式标注其语义，防止代理错误路由后把受治理正文当作文件响应。
+            if (pathname === '/v1/evidence-file' && response.headers.get('x-knowledge-evidence-class') !== 'RAW_EVIDENCE')
+                throw new Error('SERVING_SDK_EVIDENCE_CLASS_MISSING');
+            if (pathname === '/v2/evidence-media' && response.headers.get('x-knowledge-evidence-class') !== 'RAW_EVIDENCE_MEDIA')
+                throw new Error('SERVING_SDK_EVIDENCE_CLASS_MISSING');
+            if (pathname === '/v2/artifact-file' && response.headers.get('x-knowledge-content-class') !== 'ARTIFACT_SNAPSHOT')
+                throw new Error('SERVING_SDK_ARTIFACT_CLASS_MISSING');
+            if (pathname === '/v2/material-file' && !['ARTIFACT_SNAPSHOT', 'RAW_EVIDENCE', 'RAW_EVIDENCE_MEDIA', 'REFERENCE_SNAPSHOT', 'REGISTERED_MATERIAL'].includes(response.headers.get('x-knowledge-content-class') ?? ''))
+                throw new Error('SERVING_SDK_MATERIAL_CLASS_MISSING');
+            const content = Buffer.from(await response.arrayBuffer()), contentHash = response.headers.get('x-knowledge-content-hash'), mediaType = response.headers.get('content-type'), rawLength = response.headers.get('content-length'), assessedAt = response.headers.get('x-knowledge-assessed-at');
+            if (!contentHash || !mediaType || !rawLength || !assessedAt)
+                throw new Error('SERVING_SDK_CONTENT_HEADERS_MISSING');
+            const byteLength = Number(rawLength);
+            if (!Number.isSafeInteger(byteLength) || byteLength !== content.byteLength || sha(content) !== contentHash)
+                throw new Error('SERVING_SDK_CONTENT_INTEGRITY_MISMATCH');
+            return { decision: { schemaVersion: 1, action: 'ALLOW', reasonCodes: [], assessedAt }, descriptor: { contentHash, mediaType, byteLength }, content };
+        }
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('SERVING_SDK_RESPONSE_INVALID');
+        }
+        const parsed = servingContentDecisionResponseSchema.safeParse(raw);
+        if (parsed.success)
+            return parsed.data;
+        const api = servingApiErrorSchema.safeParse(raw);
+        if (api.success)
+            throw new Error(api.data.errorCode);
+        throw new Error('SERVING_SDK_HTTP_FAILURE');
+    }
+    getMaterialContract() { return this.json(this.url('/v3/material-contract'), apiKeyMaterialContractSchema); }
+    getMaterialCapabilities(ref) { return this.json(this.url('/v3/material-capabilities', { ref }), materialCapabilityResponseSchema); }
+    pageMaterialCapabilities(options = {}) { return this.json(this.url('/v3/material-page', options), materialCapabilityPageSchema); }
+    pageMaterialMedia(ref, options = {}) { return this.json(this.url('/v3/material-media-page', { ref, ...options }), materialMediaCapabilityPageSchema); }
+    getMaterialIndexStatus(options = {}) { return this.json(this.url('/v3/material-index-status', options), materialIndexStatusSchema); }
+    openMaterialStream(ref, options = {}) { return materialStream(this.fetchImpl, this.url('/v2/material-file', { ref }), this.token, options); }
+    getMaterialFile(ref) { return this.rawContent('/v2/material-file', ref); }
+    getContent(ref) { return this.rawContent('/v1/content', ref); }
+    getArtifactFile(ref) { return this.rawContent('/v2/artifact-file', ref); }
+    getMedia(ref) { return this.rawContent('/v1/media', ref); }
+    getEvidenceMedia(ref) { return this.rawContent('/v2/evidence-media', ref); }
+    /** 读取未经知识审核的原始 Evidence 文件；调用方仍需自己处理其时效与适用性。 */
+    getEvidenceFile(ref) { return this.rawContent('/v1/evidence-file', ref); }
+}
+export * from './tenant-management.js';
+export * from './tenant-workspace.js';
+export * from './tenant-project.js';
+export * from './tenant-runtime.js';
+export * from './tenant-web.js';
+export * from './tenant-web-crawl.js';
+export * from './tenant-web-dynamic.js';
+export * from './tenant-web-content.js';
+export * from './tenant-web-workflow.js';
+export * from './auth.js';
+export * from './token-provider.js';
+export * from './tenant-client.js';
+export * from './agent-entry.js';
+export * from './agent-guidance-error.js';

package/dist/internal/contracts/artifact.d.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+export declare const artifactIdSchema: z.ZodString;
+export declare const artifactKindSchema: z.ZodEnum<{
+    SIGNAL_GENERATION: "SIGNAL_GENERATION";
+    RESEARCH: "RESEARCH";
+    REVIEW: "REVIEW";
+    KNOWLEDGE: "KNOWLEDGE";
+    INSIGHT: "INSIGHT";
+}>;
+export declare const artifactStatusSchema: z.ZodEnum<{
+    GENERATED: "GENERATED";
+    DRAFT: "DRAFT";
+    READY_FOR_REVIEW: "READY_FOR_REVIEW";
+    REWORK_REQUIRED: "REWORK_REQUIRED";
+    APPROVED: "APPROVED";
+    REJECTED: "REJECTED";
+    SUPERSEDED: "SUPERSEDED";
+}>;
+export declare const artifactManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    artifactId: z.ZodString;
+    kind: z.ZodEnum<{
+        SIGNAL_GENERATION: "SIGNAL_GENERATION";
+        RESEARCH: "RESEARCH";
+        REVIEW: "REVIEW";
+        KNOWLEDGE: "KNOWLEDGE";
+        INSIGHT: "INSIGHT";
+    }>;
+    projectKey: z.ZodString;
+    projectRef: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+    ref: z.ZodString;
+    identityRef: z.ZodString;
+    status: z.ZodEnum<{
+        GENERATED: "GENERATED";
+        DRAFT: "DRAFT";
+        READY_FOR_REVIEW: "READY_FOR_REVIEW";
+        REWORK_REQUIRED: "REWORK_REQUIRED";
+        APPROVED: "APPROVED";
+        REJECTED: "REJECTED";
+        SUPERSEDED: "SUPERSEDED";
+    }>;
+    access: z.ZodDefault<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    observedAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    validUntil: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    contentHash: z.ZodString;
+    mediaType: z.ZodString;
+    byteLength: z.ZodNumber;
+    evidenceRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    relatedRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    supersedesRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type ArtifactId = z.infer<typeof artifactIdSchema>;
+export type ArtifactKind = z.infer<typeof artifactKindSchema>;
+export type ArtifactStatus = z.infer<typeof artifactStatusSchema>;
+export type ArtifactManifest = z.infer<typeof artifactManifestSchema>;
+export declare const artifactWriteMetadataSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    artifactId: z.ZodString;
+    kind: z.ZodEnum<{
+        SIGNAL_GENERATION: "SIGNAL_GENERATION";
+        RESEARCH: "RESEARCH";
+        REVIEW: "REVIEW";
+        KNOWLEDGE: "KNOWLEDGE";
+        INSIGHT: "INSIGHT";
+    }>;
+    projectKey: z.ZodString;
+    projectRef: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+    status: z.ZodEnum<{
+        GENERATED: "GENERATED";
+        DRAFT: "DRAFT";
+        READY_FOR_REVIEW: "READY_FOR_REVIEW";
+        REWORK_REQUIRED: "REWORK_REQUIRED";
+        APPROVED: "APPROVED";
+        REJECTED: "REJECTED";
+        SUPERSEDED: "SUPERSEDED";
+    }>;
+    access: z.ZodDefault<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        PUBLIC_METADATA: "PUBLIC_METADATA";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+        ACCESS_CONTROLLED: "ACCESS_CONTROLLED";
+        UNKNOWN: "UNKNOWN";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    observedAt: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    validUntil: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    mediaType: z.ZodString;
+    evidenceRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    relatedRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    supersedesRef: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const reviewDecisionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    targetRef: z.ZodString;
+    decision: z.ZodEnum<{
+        PASS: "PASS";
+        REWORK: "REWORK";
+        REJECT: "REJECT";
+    }>;
+    reviewedAt: z.ZodISODateTime;
+    summary: z.ZodString;
+    evidenceRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ArtifactWriteMetadata = z.infer<typeof artifactWriteMetadataSchema>;
+export type ReviewDecision = z.infer<typeof reviewDecisionSchema>;