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

package/dist/internal/serving-contracts/http.js

@@ -0,0 +1,64 @@
+import { rawMaterialDirectoryItemSchema } from '../contracts/index.js';
+import { z } from 'zod';
+import { accessClassificationSchema, isoDateTimeSchema, projectKeySchema, richDocumentSchema, schemaVersionSchema, sha256Schema, stableUriSchema } from '../contracts/index.js';
+import { referenceCorpusRecordSchema, referenceCorpusSummarySchema, servingArtifactDetailSchema, servingArtifactSummarySchema, servingCurrentnessSchema, servingDecisionSchema, servingEvidenceSummarySchema, servingSourceSummarySchema, servingProjectIntentSummarySchema, servingProjectSourceSummarySchema, } from './core.js';
+import { consumerProjectRefSchema, consumerReferenceLookupItemSchema } from './consumer.js';
+const decisionArtifactSummarySchema = z.object({ decision: servingDecisionSchema, artifact: servingArtifactSummarySchema }).strict();
+const decisionEvidenceSummarySchema = z.object({ decision: servingDecisionSchema, evidence: servingEvidenceSummarySchema }).strict();
+const decisionProjectSourceSummarySchema = z.object({ decision: servingDecisionSchema, source: servingProjectSourceSummarySchema }).strict();
+const decisionReferenceSummarySchema = z.object({ decision: servingDecisionSchema, record: referenceCorpusSummarySchema }).strict();
+export const servingApiErrorSchema = z.object({ errorCode: z.string().trim().min(1).max(128).regex(/^[A-Z0-9_]+$/) }).strict();
+export const servingHealthResponseSchema = z.object({ schemaVersion: schemaVersionSchema, status: z.literal('ok'), service: z.literal('knowledge-api'), codeRevision: z.string().trim().min(1).max(128) }).strict();
+export const servingArtifactListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionArtifactSummarySchema).max(1000) }).strict();
+/** Live, authorization-scoped page. A cursor is a position hint, never a grant or snapshot. */
+export const servingArtifactPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionArtifactSummarySchema).max(100), nextAfter: z.string().max(4096).nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED'), versionCoverage: z.literal('AUTHORIZED_REFERENCES_ONLY') }).strict();
+/** Raw immutable snapshots remain separate from governed Knowledge decisions. */
+export const servingArtifactMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('ARTIFACT_SNAPSHOT'), items: z.array(z.object({ decision: servingDecisionSchema, governanceDecision: servingDecisionSchema, artifact: servingArtifactSummarySchema }).strict()).max(100), nextAfter: z.string().max(4096).nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED'), versionCoverage: z.literal('AUTHORIZED_REFERENCES_ONLY') }).strict();
+export const servingArtifactMaterialResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('ARTIFACT_SNAPSHOT'), decision: servingDecisionSchema, governanceDecision: servingDecisionSchema, artifact: servingArtifactDetailSchema.nullable() }).strict();
+export const servingArtifactResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, artifact: servingArtifactDetailSchema.nullable() }).strict();
+export const servingEvidenceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionEvidenceSummarySchema).max(1000) }).strict();
+// 不把文件可下载误称为结构化正文；状态不包含任何未授权的正文派生文本。
+export const servingEvidenceFormatQualitySchema = z.object({ format: z.enum(['HTML', 'PDF', 'FEED', 'XML', 'MARKDOWN', 'CSV', 'JSON', 'IMAGE', 'VIDEO', 'AUDIO', 'TEXT', 'OTHER']), rawFile: z.enum(['AVAILABLE', 'DENIED']), projection: z.enum(['READY', 'EMPTY', 'MISSING', 'UNSUPPORTED', 'DENIED']), media: z.enum(['COMPLETE', 'PARTIAL', 'NONE', 'UNASSESSED']) }).strict();
+// 通用文件发现页区分原始文件读取权和已审核知识的正文消费权。
+export const servingEvidencePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionEvidenceSummarySchema.extend({ fileDecision: servingDecisionSchema, contentDecision: servingDecisionSchema, formatQuality: servingEvidenceFormatQualitySchema.optional(), presentation: z.object({ title: z.string().max(1000).nullable(), summary: z.string().max(4000).nullable(), byline: z.string().max(1000).nullable(), publishedAt: isoDateTimeSchema.nullable(), language: z.string().max(64).nullable(), topics: z.array(z.string().max(160)).max(32).optional(), documentRef: stableUriSchema, documentContentHash: sha256Schema, quality: z.object({ bodyCharacters: z.number().int().nonnegative(), mediaTotal: z.number().int().nonnegative(), mediaMirrored: z.number().int().nonnegative(), mediaUnavailable: z.number().int().nonnegative(), mediaTooLarge: z.number().int().nonnegative() }).strict() }).strict().nullable().optional() })).max(100), nextAfter: stableUriSchema.nullable() }).strict().superRefine((value, ctx) => { for (let index = 0; index < value.items.length; index++) {
+    const item = value.items[index];
+    if (item.presentation && item.fileDecision.action !== 'ALLOW')
+        ctx.addIssue({ code: 'custom', path: ['items', index, 'presentation'], message: 'Body-derived presentation requires raw-file authorization' });
+} });
+/** A readable representation of original Evidence, never a reviewed Knowledge artifact. */
+export const servingEvidencePresentationResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, contentClass: z.literal('RAW_EVIDENCE_PRESENTATION'), presentation: z.object({ sourceEvidenceRef: stableUriSchema, sourceContentHash: sha256Schema, documentRef: stableUriSchema, documentContentHash: sha256Schema, document: richDocumentSchema }).strict().nullable() }).strict().superRefine((value, ctx) => {
+    if ((value.decision.action === 'ALLOW') !== Boolean(value.presentation))
+        ctx.addIssue({ code: 'custom', path: ['presentation'], message: 'Presentation must match the current decision' });
+    if (value.presentation && (value.presentation.document.role !== 'SOURCE_MIRROR' || value.presentation.document.sourceContentHash !== value.presentation.sourceContentHash || value.presentation.document.primarySourceEvidenceRef !== value.presentation.sourceEvidenceRef || value.presentation.document.projectKey !== /^evidence:\/\/([^/]+)\//.exec(value.presentation.sourceEvidenceRef)?.[1]))
+        ctx.addIssue({ code: 'custom', path: ['presentation'], message: 'Presentation source identity mismatch' });
+});
+export const oauthMaterialPresentationResponseSchema = servingEvidencePresentationResponseSchema.safeExtend({ projectRef: consumerProjectRefSchema });
+export const servingEvidenceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, evidence: servingEvidenceSummarySchema.nullable() }).strict();
+export const servingProjectIntentResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, project: servingProjectIntentSummarySchema.nullable() }).strict();
+export const servingProjectSourceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionProjectSourceSummarySchema).max(1000) }).strict();
+export const servingProjectSourceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, source: servingProjectSourceSummarySchema.nullable() }).strict();
+export const servingSourceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, source: servingSourceSummarySchema.nullable() }).strict();
+export const servingCurrentnessResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, currentness: servingCurrentnessSchema.nullable() }).strict();
+export const servingReferenceListResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, items: z.array(decisionReferenceSummarySchema).max(1000) }).strict();
+export const servingReferenceResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, record: referenceCorpusRecordSchema.nullable() }).strict();
+export const servingReferenceMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('REFERENCE_SNAPSHOT'), items: z.array(z.object({ decision: servingDecisionSchema, record: referenceCorpusSummarySchema }).strict()).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const servingReferenceMaterialResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('REFERENCE_SNAPSHOT'), decision: servingDecisionSchema, record: referenceCorpusRecordSchema.nullable() }).strict();
+/** Type-neutral discovery over current project references; kind is descriptive, never an admission list. */
+export const servingMaterialDirectoryItemSchema = rawMaterialDirectoryItemSchema;
+export const servingMaterialPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('MATERIAL_DIRECTORY'), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable(), scanSemantics: z.literal('LIVE_AUTHORIZED') }).strict();
+export const servingMaterialRoutePageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, routeId: z.string().regex(/^[a-f0-9]{64}$/), contentClass: z.literal('MATERIAL_DIRECTORY'), routeState: z.enum(['ACTIVE', 'REVOKED', 'UNBOUND']), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const materialRoutePartitionSchema = z.object({ routeId: z.string().regex(/^[a-f0-9]{64}$/), sourceProjectKey: projectKeySchema, matchType: z.enum(['SOURCE_PROJECT', 'SOURCE_SET', 'REF']), matchValue: z.string().min(1).max(4096) }).strict();
+export const servingMaterialPartitionsResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, coverage: z.literal('OWNER_LEGACY_AND_ACTIVE_ROUTES'), items: z.array(materialRoutePartitionSchema).max(100), nextAfterRouteId: z.string().regex(/^[a-f0-9]{64}$/).nullable() }).strict();
+export const servingMaterialPartitionPageResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, contentClass: z.literal('MATERIAL_DIRECTORY'), partition: z.enum(['OWNER', 'LEGACY']), items: z.array(servingMaterialDirectoryItemSchema).max(100), nextAfter: stableUriSchema.nullable() }).strict();
+export const servingMaterialSearchResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, queryCoverage: z.literal('DESCRIPTIVE_METADATA_V1'), order: z.literal('INDEX_ROWID_ASC'), indexState: z.enum(['PARTIAL_BACKFILL', 'SYNCED_AS_OF_LAST_OBSERVATION']), configuredSourceCount: z.number().int().nonnegative(), items: z.array(z.object({ item: servingMaterialDirectoryItemSchema, title: z.string().max(512), summary: z.string().max(1024) }).strict()).max(20), nextAfterId: z.number().int().positive().nullable() }).strict();
+export const oauthMaterialPageResponseSchema = z.discriminatedUnion('resourceType', [
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('all'), contentClass: z.literal('MATERIAL_DIRECTORY'), items: servingMaterialPageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('artifact'), contentClass: z.literal('ARTIFACT_SNAPSHOT'), items: servingArtifactMaterialPageResponseSchema.shape.items, nextAfter: z.string().max(4096).nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('evidence'), contentClass: z.literal('RAW_EVIDENCE'), items: servingEvidencePageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+    z.object({ schemaVersion: schemaVersionSchema, projectRef: consumerProjectRefSchema, projectKey: projectKeySchema, resourceType: z.literal('reference'), contentClass: z.literal('REFERENCE_SNAPSHOT'), items: servingReferenceMaterialPageResponseSchema.shape.items, nextAfter: stableUriSchema.nullable() }).strict(),
+]);
+export const servingReferenceLookupResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, lookupCoverage: z.literal('AUTHORIZED_REFERENCE_SELECTORS_V1'), items: z.array(consumerReferenceLookupItemSchema).max(100) }).strict();
+export const servingContentDecisionResponseSchema = z.object({ schemaVersion: schemaVersionSchema, projectKey: projectKeySchema, decision: servingDecisionSchema, content: z.null() }).strict();
+export const servingContentHeadersSchema = z.object({ contentHash: sha256Schema, mediaType: z.string().trim().min(1).max(256), byteLength: z.number().int().nonnegative(), assessedAt: z.string().datetime({ offset: true }) }).strict();
+/** Recovery checkpoint is captured before bootstrap; incremental replay starts after headSeq. */
+export const materialOutboxWindowSchema = z.object({ schemaVersion: schemaVersionSchema, tenantId: z.string().min(1), retainedThroughSeq: z.number().int().nonnegative().safe(), headSeq: z.number().int().nonnegative().safe() }).strict().refine(value => value.retainedThroughSeq <= value.headSeq, { message: 'Outbox floor must not exceed head' });

package/dist/internal/serving-contracts/index.d.ts

@@ -0,0 +1,24 @@
+export * from './core.js';
+export * from './http.js';
+export * from './consumer.js';
+export * from './mcp.js';
+export * from './management.js';
+export * from './material-capabilities.js';
+export * from './material-index-status.js';
+export * from './workflow.js';
+export * from './tenant-governance.js';
+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 './tenant-session.js';
+export * from './agent-entry.js';
+export * from './agent-catalog.js';
+export * from './body-search.js';
+export * from './agent-guidance-shapes.js';
+export * from './agent-input-hints.js';

package/dist/internal/serving-contracts/index.js

@@ -0,0 +1,25 @@
+export * from './core.js';
+export * from './http.js';
+export * from './consumer.js';
+export * from './mcp.js';
+export * from './management.js';
+export * from './material-capabilities.js';
+export * from './material-index-status.js';
+// CLI、MCP 与 HTTPS 共享同一 Agent 治理合同，避免各入口自行解释状态。
+export * from './workflow.js';
+export * from './tenant-governance.js';
+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 './tenant-session.js';
+export * from './agent-entry.js';
+export * from './agent-catalog.js';
+export * from './body-search.js';
+export * from './agent-guidance-shapes.js';
+export * from './agent-input-hints.js';

package/dist/internal/serving-contracts/management.d.ts

@@ -0,0 +1,424 @@
+/** 管理 MCP 的参数只携带项目引用和治理输入；项目 Key、Tenant 和节点均由服务端绑定解析。 */
+import { z } from 'zod';
+export declare const managementComposeInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    sourceEvidenceRefs: z.ZodArray<z.ZodString>;
+    primarySourceEvidenceRef: z.ZodOptional<z.ZodString>;
+    artifactId: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    composedAt: z.ZodISODateTime;
+    validUntil: z.ZodOptional<z.ZodISODateTime>;
+    outputKind: z.ZodEnum<{
+        KNOWLEDGE: "KNOWLEDGE";
+        INSIGHT: "INSIGHT";
+    }>;
+    publicationProfile: z.ZodOptional<z.ZodEnum<{
+        HUMAN_ARTICLE_V1: "HUMAN_ARTICLE_V1";
+        KNOWLEDGE_CARD_V1: "KNOWLEDGE_CARD_V1";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    composition: z.ZodOptional<z.ZodObject<{
+        summary: z.ZodString;
+        byline: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"HEADING">;
+            level: z.ZodNumber;
+            text: z.ZodString;
+            inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                text: z.ZodString;
+                href: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>>;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"PARAGRAPH">;
+            text: z.ZodString;
+            inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                text: z.ZodString;
+                href: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>>;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"LIST_ITEM">;
+            text: z.ZodString;
+            ordered: z.ZodBoolean;
+            level: z.ZodNumber;
+            index: z.ZodNullable<z.ZodNumber>;
+            inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                text: z.ZodString;
+                href: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>>;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"QUOTE">;
+            text: z.ZodString;
+            inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                text: z.ZodString;
+                href: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>>>;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"CODE">;
+            text: z.ZodString;
+            language: z.ZodNullable<z.ZodString>;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"IMAGE">;
+            alt: z.ZodNullable<z.ZodString>;
+            width: z.ZodNullable<z.ZodNumber>;
+            height: z.ZodNullable<z.ZodNumber>;
+            ordinal: z.ZodNumber;
+            sourceUrl: z.ZodString;
+            canonicalUrl: z.ZodNullable<z.ZodString>;
+            availability: z.ZodEnum<{
+                MIRRORED: "MIRRORED";
+                REMOTE_ONLY: "REMOTE_ONLY";
+                UNAVAILABLE: "UNAVAILABLE";
+            }>;
+            mediaRef: z.ZodNullable<z.ZodString>;
+            evidenceRef: z.ZodNullable<z.ZodString>;
+            contentHash: z.ZodNullable<z.ZodString>;
+            mediaType: z.ZodNullable<z.ZodString>;
+            byteLength: z.ZodNullable<z.ZodNumber>;
+            caption: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"VIDEO">;
+            title: z.ZodNullable<z.ZodString>;
+            posterUrl: z.ZodNullable<z.ZodString>;
+            posterEvidenceRef: z.ZodNullable<z.ZodString>;
+            ordinal: z.ZodNumber;
+            sourceUrl: z.ZodString;
+            canonicalUrl: z.ZodNullable<z.ZodString>;
+            availability: z.ZodEnum<{
+                MIRRORED: "MIRRORED";
+                REMOTE_ONLY: "REMOTE_ONLY";
+                UNAVAILABLE: "UNAVAILABLE";
+            }>;
+            mediaRef: z.ZodNullable<z.ZodString>;
+            evidenceRef: z.ZodNullable<z.ZodString>;
+            contentHash: z.ZodNullable<z.ZodString>;
+            mediaType: z.ZodNullable<z.ZodString>;
+            byteLength: z.ZodNullable<z.ZodNumber>;
+            caption: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"AUDIO">;
+            title: z.ZodNullable<z.ZodString>;
+            ordinal: z.ZodNumber;
+            sourceUrl: z.ZodString;
+            canonicalUrl: z.ZodNullable<z.ZodString>;
+            availability: z.ZodEnum<{
+                MIRRORED: "MIRRORED";
+                REMOTE_ONLY: "REMOTE_ONLY";
+                UNAVAILABLE: "UNAVAILABLE";
+            }>;
+            mediaRef: z.ZodNullable<z.ZodString>;
+            evidenceRef: z.ZodNullable<z.ZodString>;
+            contentHash: z.ZodNullable<z.ZodString>;
+            mediaType: z.ZodNullable<z.ZodString>;
+            byteLength: z.ZodNullable<z.ZodNumber>;
+            caption: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"EMBED">;
+            sourceUrl: z.ZodString;
+            provider: z.ZodNullable<z.ZodString>;
+            title: z.ZodNullable<z.ZodString>;
+            caption: z.ZodNullable<z.ZodString>;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"DIVIDER">;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"TABLE">;
+            rows: z.ZodArray<z.ZodObject<{
+                cells: z.ZodArray<z.ZodObject<{
+                    text: z.ZodString;
+                    header: z.ZodBoolean;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            ordinal: z.ZodNumber;
+        }, z.core.$strict>], "kind">>;
+        citations: z.ZodArray<z.ZodObject<{
+            blockOrdinal: z.ZodNumber;
+            evidenceRefs: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const managementSubmitInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const managementReviewInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    targetRef: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    decision: z.ZodEnum<{
+        PASS: "PASS";
+        REWORK: "REWORK";
+        REJECT: "REJECT";
+    }>;
+    reviewedAt: z.ZodISODateTime;
+    summary: z.ZodString;
+    evidenceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const managementFinalizeInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+    expectedVersion: z.ZodNumber;
+    nextStatus: z.ZodEnum<{
+        REWORK_REQUIRED: "REWORK_REQUIRED";
+        APPROVED: "APPROVED";
+        REJECTED: "REJECTED";
+    }>;
+    reviewRef: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const managementResultSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+    kind: z.ZodEnum<{
+        REVIEW: "REVIEW";
+        KNOWLEDGE: "KNOWLEDGE";
+        INSIGHT: "INSIGHT";
+    }>;
+    version: z.ZodNumber;
+    status: z.ZodEnum<{
+        DRAFT: "DRAFT";
+        READY_FOR_REVIEW: "READY_FOR_REVIEW";
+        REWORK_REQUIRED: "REWORK_REQUIRED";
+        APPROVED: "APPROVED";
+        REJECTED: "REJECTED";
+    }>;
+    contentHash: z.ZodString;
+    inserted: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const managementToolInputSchemas: {
+    readonly knowledge_compose: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        sourceEvidenceRefs: z.ZodArray<z.ZodString>;
+        primarySourceEvidenceRef: z.ZodOptional<z.ZodString>;
+        artifactId: z.ZodString;
+        expectedVersion: z.ZodNumber;
+        composedAt: z.ZodISODateTime;
+        validUntil: z.ZodOptional<z.ZodISODateTime>;
+        outputKind: z.ZodEnum<{
+            KNOWLEDGE: "KNOWLEDGE";
+            INSIGHT: "INSIGHT";
+        }>;
+        publicationProfile: z.ZodOptional<z.ZodEnum<{
+            HUMAN_ARTICLE_V1: "HUMAN_ARTICLE_V1";
+            KNOWLEDGE_CARD_V1: "KNOWLEDGE_CARD_V1";
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        composition: z.ZodOptional<z.ZodObject<{
+            summary: z.ZodString;
+            byline: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            blocks: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"HEADING">;
+                level: z.ZodNumber;
+                text: z.ZodString;
+                inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    text: z.ZodString;
+                    href: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>>;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"PARAGRAPH">;
+                text: z.ZodString;
+                inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    text: z.ZodString;
+                    href: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>>;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"LIST_ITEM">;
+                text: z.ZodString;
+                ordered: z.ZodBoolean;
+                level: z.ZodNumber;
+                index: z.ZodNullable<z.ZodNumber>;
+                inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    text: z.ZodString;
+                    href: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>>;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"QUOTE">;
+                text: z.ZodString;
+                inlines: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    text: z.ZodString;
+                    href: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>>;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"CODE">;
+                text: z.ZodString;
+                language: z.ZodNullable<z.ZodString>;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"IMAGE">;
+                alt: z.ZodNullable<z.ZodString>;
+                width: z.ZodNullable<z.ZodNumber>;
+                height: z.ZodNullable<z.ZodNumber>;
+                ordinal: z.ZodNumber;
+                sourceUrl: z.ZodString;
+                canonicalUrl: z.ZodNullable<z.ZodString>;
+                availability: z.ZodEnum<{
+                    MIRRORED: "MIRRORED";
+                    REMOTE_ONLY: "REMOTE_ONLY";
+                    UNAVAILABLE: "UNAVAILABLE";
+                }>;
+                mediaRef: z.ZodNullable<z.ZodString>;
+                evidenceRef: z.ZodNullable<z.ZodString>;
+                contentHash: z.ZodNullable<z.ZodString>;
+                mediaType: z.ZodNullable<z.ZodString>;
+                byteLength: z.ZodNullable<z.ZodNumber>;
+                caption: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"VIDEO">;
+                title: z.ZodNullable<z.ZodString>;
+                posterUrl: z.ZodNullable<z.ZodString>;
+                posterEvidenceRef: z.ZodNullable<z.ZodString>;
+                ordinal: z.ZodNumber;
+                sourceUrl: z.ZodString;
+                canonicalUrl: z.ZodNullable<z.ZodString>;
+                availability: z.ZodEnum<{
+                    MIRRORED: "MIRRORED";
+                    REMOTE_ONLY: "REMOTE_ONLY";
+                    UNAVAILABLE: "UNAVAILABLE";
+                }>;
+                mediaRef: z.ZodNullable<z.ZodString>;
+                evidenceRef: z.ZodNullable<z.ZodString>;
+                contentHash: z.ZodNullable<z.ZodString>;
+                mediaType: z.ZodNullable<z.ZodString>;
+                byteLength: z.ZodNullable<z.ZodNumber>;
+                caption: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"AUDIO">;
+                title: z.ZodNullable<z.ZodString>;
+                ordinal: z.ZodNumber;
+                sourceUrl: z.ZodString;
+                canonicalUrl: z.ZodNullable<z.ZodString>;
+                availability: z.ZodEnum<{
+                    MIRRORED: "MIRRORED";
+                    REMOTE_ONLY: "REMOTE_ONLY";
+                    UNAVAILABLE: "UNAVAILABLE";
+                }>;
+                mediaRef: z.ZodNullable<z.ZodString>;
+                evidenceRef: z.ZodNullable<z.ZodString>;
+                contentHash: z.ZodNullable<z.ZodString>;
+                mediaType: z.ZodNullable<z.ZodString>;
+                byteLength: z.ZodNullable<z.ZodNumber>;
+                caption: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"EMBED">;
+                sourceUrl: z.ZodString;
+                provider: z.ZodNullable<z.ZodString>;
+                title: z.ZodNullable<z.ZodString>;
+                caption: z.ZodNullable<z.ZodString>;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"DIVIDER">;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"TABLE">;
+                rows: z.ZodArray<z.ZodObject<{
+                    cells: z.ZodArray<z.ZodObject<{
+                        text: z.ZodString;
+                        header: z.ZodBoolean;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+                ordinal: z.ZodNumber;
+            }, z.core.$strict>], "kind">>;
+            citations: z.ZodArray<z.ZodObject<{
+                blockOrdinal: z.ZodNumber;
+                evidenceRefs: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    readonly knowledge_submit_review: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+        expectedVersion: z.ZodNumber;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    readonly knowledge_review: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        targetRef: z.ZodString;
+        expectedVersion: z.ZodNumber;
+        decision: z.ZodEnum<{
+            PASS: "PASS";
+            REWORK: "REWORK";
+            REJECT: "REJECT";
+        }>;
+        reviewedAt: z.ZodISODateTime;
+        summary: z.ZodString;
+        evidenceRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    readonly knowledge_finalize_review: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+        expectedVersion: z.ZodNumber;
+        nextStatus: z.ZodEnum<{
+            REWORK_REQUIRED: "REWORK_REQUIRED";
+            APPROVED: "APPROVED";
+            REJECTED: "REJECTED";
+        }>;
+        reviewRef: z.ZodString;
+        createdAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+};
+export declare const managementToolErrorOutputSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly errorCode: {
+            readonly type: "string";
+        };
+        readonly completedPhase: {
+            readonly type: "string";
+            readonly enum: readonly ["VALIDATED", "PERSISTED", "CATALOG_PROJECTED"];
+        };
+        readonly ref: z.core.ZodStandardJSONSchemaPayload<z.ZodString>;
+    };
+    readonly required: readonly ["errorCode"];
+    readonly additionalProperties: false;
+};
+export declare const managementToolOutputSchema: {
+    readonly type: "object";
+    readonly oneOf: readonly [z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+        kind: z.ZodEnum<{
+            REVIEW: "REVIEW";
+            KNOWLEDGE: "KNOWLEDGE";
+            INSIGHT: "INSIGHT";
+        }>;
+        version: z.ZodNumber;
+        status: z.ZodEnum<{
+            DRAFT: "DRAFT";
+            READY_FOR_REVIEW: "READY_FOR_REVIEW";
+            REWORK_REQUIRED: "REWORK_REQUIRED";
+            APPROVED: "APPROVED";
+            REJECTED: "REJECTED";
+        }>;
+        contentHash: z.ZodString;
+        inserted: z.ZodBoolean;
+    }, z.core.$strict>>, {
+        readonly type: "object";
+        readonly properties: {
+            readonly errorCode: {
+                readonly type: "string";
+            };
+            readonly completedPhase: {
+                readonly type: "string";
+                readonly enum: readonly ["VALIDATED", "PERSISTED", "CATALOG_PROJECTED"];
+            };
+            readonly ref: z.core.ZodStandardJSONSchemaPayload<z.ZodString>;
+        };
+        readonly required: readonly ["errorCode"];
+        readonly additionalProperties: false;
+    }];
+};

package/dist/internal/serving-contracts/management.js

@@ -0,0 +1,15 @@
+/** 管理 MCP 的参数只携带项目引用和治理输入；项目 Key、Tenant 和节点均由服务端绑定解析。 */
+import { z } from 'zod';
+import { artifactIdSchema, isoDateTimeSchema, publicationProfileSchema, richCompositionDraftSchema, stableUriSchema } from '../contracts/index.js';
+import { consumerProjectRefSchema } from './consumer.js';
+const version = z.number().int().nonnegative();
+const base = z.object({ projectRef: consumerProjectRefSchema }).strict();
+export const managementComposeInputSchema = base.extend({ sourceEvidenceRefs: z.array(stableUriSchema).min(1).max(64), primarySourceEvidenceRef: stableUriSchema.optional(), artifactId: artifactIdSchema, expectedVersion: version, composedAt: isoDateTimeSchema, validUntil: isoDateTimeSchema.optional(), outputKind: z.enum(['KNOWLEDGE', 'INSIGHT']), publicationProfile: publicationProfileSchema.optional(), title: z.string().trim().min(1).max(1000).optional(), composition: richCompositionDraftSchema.optional() }).strict();
+export const managementSubmitInputSchema = base.extend({ ref: stableUriSchema, expectedVersion: version, createdAt: isoDateTimeSchema }).strict();
+export const managementReviewInputSchema = base.extend({ targetRef: stableUriSchema, expectedVersion: version, decision: z.enum(['PASS', 'REWORK', 'REJECT']), reviewedAt: isoDateTimeSchema, summary: z.string().trim().min(1).max(8000), evidenceRefs: z.array(stableUriSchema).max(64).optional() }).strict();
+export const managementFinalizeInputSchema = base.extend({ ref: stableUriSchema, expectedVersion: version, nextStatus: z.enum(['APPROVED', 'REWORK_REQUIRED', 'REJECTED']), reviewRef: stableUriSchema, createdAt: isoDateTimeSchema }).strict();
+export const managementResultSchema = z.object({ schemaVersion: z.literal(1), projectRef: consumerProjectRefSchema, ref: stableUriSchema, kind: z.enum(['KNOWLEDGE', 'INSIGHT', 'REVIEW']), version: z.number().int().positive(), status: z.enum(['DRAFT', 'READY_FOR_REVIEW', 'APPROVED', 'REWORK_REQUIRED', 'REJECTED']), contentHash: z.string().regex(/^sha256:[a-f0-9]{64}$/), inserted: z.boolean() }).strict();
+// MCP 公告和服务端参数校验从同一组合同生成，避免工具描述与实际输入漂移。
+export const managementToolInputSchemas = { knowledge_compose: z.toJSONSchema(managementComposeInputSchema, { target: 'draft-07' }), knowledge_submit_review: z.toJSONSchema(managementSubmitInputSchema, { target: 'draft-07' }), knowledge_review: z.toJSONSchema(managementReviewInputSchema, { target: 'draft-07' }), knowledge_finalize_review: z.toJSONSchema(managementFinalizeInputSchema, { target: 'draft-07' }) };
+export const managementToolErrorOutputSchema = { type: 'object', properties: { errorCode: { type: 'string' }, completedPhase: { type: 'string', enum: ['VALIDATED', 'PERSISTED', 'CATALOG_PROJECTED'] }, ref: z.toJSONSchema(stableUriSchema, { target: 'draft-07' }) }, required: ['errorCode'], additionalProperties: false };
+export const managementToolOutputSchema = { type: 'object', oneOf: [z.toJSONSchema(managementResultSchema, { target: 'draft-07' }), managementToolErrorOutputSchema] };