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

package/dist/types/serving-contracts/workflow.d.ts

@@ -0,0 +1,439 @@
+/** Agent 的治理合同描述真实状态和下一步，不把写入权限解释为审核或正文权限。 */
+import { z } from 'zod';
+export declare const workflowPlanInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+}, z.core.$strict>;
+export declare const workflowGuideInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+}, z.core.$strict>;
+export declare const workflowActionSchema: z.ZodEnum<{
+    SUBMIT_REVIEW: "SUBMIT_REVIEW";
+    FINALIZE_REVIEW: "FINALIZE_REVIEW";
+    PREPARE_SOURCE: "PREPARE_SOURCE";
+    REGISTER: "REGISTER";
+}>;
+export declare const workflowAdvanceInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+    action: z.ZodEnum<{
+        SUBMIT_REVIEW: "SUBMIT_REVIEW";
+        FINALIZE_REVIEW: "FINALIZE_REVIEW";
+        PREPARE_SOURCE: "PREPARE_SOURCE";
+        REGISTER: "REGISTER";
+    }>;
+    expectedVersion: z.ZodOptional<z.ZodNumber>;
+    actedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>;
+export declare const agentSubmitInputSchema: z.ZodObject<{
+    projectRef: z.ZodString;
+    sourceId: z.ZodString;
+    contentBase64: z.ZodString;
+    mediaType: z.ZodString;
+    access: z.ZodDefault<z.ZodEnum<{
+        PUBLIC: "PUBLIC";
+        TENANT: "TENANT";
+        INTERNAL: "INTERNAL";
+        FDE_INTERNAL: "FDE_INTERNAL";
+    }>>;
+    submittedAt: z.ZodOptional<z.ZodISODateTime>;
+    freshnessSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const workflowNextActionSchema: z.ZodObject<{
+    id: z.ZodString;
+    tool: z.ZodNullable<z.ZodString>;
+    arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    requiredScopes: z.ZodArray<z.ZodString>;
+    missingScopes: z.ZodArray<z.ZodString>;
+    missingFields: z.ZodArray<z.ZodString>;
+    canExecute: z.ZodBoolean;
+    automatic: z.ZodBoolean;
+    reasonCode: z.ZodString;
+    cli: z.ZodObject<{
+        command: z.ZodString;
+        flags: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    }, z.core.$strict>;
+    http: z.ZodObject<{
+        method: z.ZodLiteral<"POST">;
+        path: z.ZodLiteral<"/mcp/management">;
+        tool: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+declare const readDecision: z.ZodObject<{
+    action: z.ZodEnum<{
+        ALLOW: "ALLOW";
+        REVIEW_REQUIRED: "REVIEW_REQUIRED";
+        DENY: "DENY";
+    }>;
+    reasonCodes: z.ZodArray<z.ZodString>;
+    authority: z.ZodEnum<{
+        AUTHENTICATED_READER: "AUTHENTICATED_READER";
+        LOCAL_PROFILE_SIMULATION: "LOCAL_PROFILE_SIMULATION";
+    }>;
+}, z.core.$strict>;
+export declare const workflowPlanSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    projectRef: z.ZodString;
+    ref: z.ZodString;
+    contentHash: z.ZodString;
+    kind: z.ZodString;
+    version: z.ZodNullable<z.ZodNumber>;
+    status: z.ZodUnion<[z.ZodEnum<{
+        GENERATED: "GENERATED";
+        DRAFT: "DRAFT";
+        READY_FOR_REVIEW: "READY_FOR_REVIEW";
+        REWORK_REQUIRED: "REWORK_REQUIRED";
+        APPROVED: "APPROVED";
+        REJECTED: "REJECTED";
+        SUPERSEDED: "SUPERSEDED";
+    }>, z.ZodEnum<{
+        RAW_MATERIAL: "RAW_MATERIAL";
+        RAW_EVIDENCE: "RAW_EVIDENCE";
+    }>]>;
+    productionPhase: z.ZodEnum<{
+        REGISTERED: "REGISTERED";
+        PERSISTED: "PERSISTED";
+        CATALOG_PROJECTED: "CATALOG_PROJECTED";
+    }>;
+    rawMaterialAvailable: z.ZodNullable<z.ZodBoolean>;
+    readiness: z.ZodNullable<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        profile: z.ZodEnum<{
+            HUMAN_ARTICLE_V1: "HUMAN_ARTICLE_V1";
+            KNOWLEDGE_CARD_V1: "KNOWLEDGE_CARD_V1";
+        }>;
+        ready: z.ZodBoolean;
+        reasons: z.ZodArray<z.ZodEnum<{
+            ROLE_MISMATCH: "ROLE_MISMATCH";
+            TITLE_REQUIRED: "TITLE_REQUIRED";
+            SUMMARY_REQUIRED: "SUMMARY_REQUIRED";
+            TEXT_TOO_SHORT: "TEXT_TOO_SHORT";
+            STRUCTURE_TOO_THIN: "STRUCTURE_TOO_THIN";
+            SOURCE_EVIDENCE_REQUIRED: "SOURCE_EVIDENCE_REQUIRED";
+            CITATION_COVERAGE_REQUIRED: "CITATION_COVERAGE_REQUIRED";
+            EVIDENCE_MISMATCH: "EVIDENCE_MISMATCH";
+            MEDIA_UNAVAILABLE: "MEDIA_UNAVAILABLE";
+        }>>;
+        metrics: z.ZodObject<{
+            textCharacters: z.ZodNumber;
+            blockCount: z.ZodNumber;
+            textBlockCount: z.ZodNumber;
+            mediaBlockCount: z.ZodNumber;
+            sourceEvidenceCount: z.ZodNumber;
+            citationCount: z.ZodNumber;
+            citedBlockCount: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    reviewRef: z.ZodNullable<z.ZodString>;
+    reviewDecision: z.ZodNullable<z.ZodEnum<{
+        PASS: "PASS";
+        REWORK: "REWORK";
+        REJECT: "REJECT";
+    }>>;
+    support: z.ZodNullable<z.ZodObject<{
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        reasonCodes: z.ZodArray<z.ZodString>;
+        missingEvidenceRefs: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    governedPolicyReady: z.ZodBoolean;
+    consumerReadDecision: z.ZodNullable<z.ZodObject<{
+        action: z.ZodEnum<{
+            ALLOW: "ALLOW";
+            REVIEW_REQUIRED: "REVIEW_REQUIRED";
+            DENY: "DENY";
+        }>;
+        reasonCodes: z.ZodArray<z.ZodString>;
+        authority: z.ZodEnum<{
+            AUTHENTICATED_READER: "AUTHENTICATED_READER";
+            LOCAL_PROFILE_SIMULATION: "LOCAL_PROFILE_SIMULATION";
+        }>;
+    }, z.core.$strict>>;
+    externalReady: z.ZodBoolean;
+    successorRef: z.ZodNullable<z.ZodString>;
+    blockers: z.ZodArray<z.ZodString>;
+    nextActions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tool: z.ZodNullable<z.ZodString>;
+        arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        requiredScopes: z.ZodArray<z.ZodString>;
+        missingScopes: z.ZodArray<z.ZodString>;
+        missingFields: z.ZodArray<z.ZodString>;
+        canExecute: z.ZodBoolean;
+        automatic: z.ZodBoolean;
+        reasonCode: z.ZodString;
+        cli: z.ZodObject<{
+            command: z.ZodString;
+            flags: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+        }, z.core.$strict>;
+        http: z.ZodObject<{
+            method: z.ZodLiteral<"POST">;
+            path: z.ZodLiteral<"/mcp/management">;
+            tool: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const workflowAdvanceResultSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    action: z.ZodEnum<{
+        SUBMIT_REVIEW: "SUBMIT_REVIEW";
+        FINALIZE_REVIEW: "FINALIZE_REVIEW";
+        PREPARE_SOURCE: "PREPARE_SOURCE";
+        REGISTER: "REGISTER";
+    }>;
+    previousRef: z.ZodString;
+    inserted: z.ZodBoolean;
+    plan: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+        contentHash: z.ZodString;
+        kind: z.ZodString;
+        version: z.ZodNullable<z.ZodNumber>;
+        status: z.ZodUnion<[z.ZodEnum<{
+            GENERATED: "GENERATED";
+            DRAFT: "DRAFT";
+            READY_FOR_REVIEW: "READY_FOR_REVIEW";
+            REWORK_REQUIRED: "REWORK_REQUIRED";
+            APPROVED: "APPROVED";
+            REJECTED: "REJECTED";
+            SUPERSEDED: "SUPERSEDED";
+        }>, z.ZodEnum<{
+            RAW_MATERIAL: "RAW_MATERIAL";
+            RAW_EVIDENCE: "RAW_EVIDENCE";
+        }>]>;
+        productionPhase: z.ZodEnum<{
+            REGISTERED: "REGISTERED";
+            PERSISTED: "PERSISTED";
+            CATALOG_PROJECTED: "CATALOG_PROJECTED";
+        }>;
+        rawMaterialAvailable: z.ZodNullable<z.ZodBoolean>;
+        readiness: z.ZodNullable<z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            profile: z.ZodEnum<{
+                HUMAN_ARTICLE_V1: "HUMAN_ARTICLE_V1";
+                KNOWLEDGE_CARD_V1: "KNOWLEDGE_CARD_V1";
+            }>;
+            ready: z.ZodBoolean;
+            reasons: z.ZodArray<z.ZodEnum<{
+                ROLE_MISMATCH: "ROLE_MISMATCH";
+                TITLE_REQUIRED: "TITLE_REQUIRED";
+                SUMMARY_REQUIRED: "SUMMARY_REQUIRED";
+                TEXT_TOO_SHORT: "TEXT_TOO_SHORT";
+                STRUCTURE_TOO_THIN: "STRUCTURE_TOO_THIN";
+                SOURCE_EVIDENCE_REQUIRED: "SOURCE_EVIDENCE_REQUIRED";
+                CITATION_COVERAGE_REQUIRED: "CITATION_COVERAGE_REQUIRED";
+                EVIDENCE_MISMATCH: "EVIDENCE_MISMATCH";
+                MEDIA_UNAVAILABLE: "MEDIA_UNAVAILABLE";
+            }>>;
+            metrics: z.ZodObject<{
+                textCharacters: z.ZodNumber;
+                blockCount: z.ZodNumber;
+                textBlockCount: z.ZodNumber;
+                mediaBlockCount: z.ZodNumber;
+                sourceEvidenceCount: z.ZodNumber;
+                citationCount: z.ZodNumber;
+                citedBlockCount: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        reviewRef: z.ZodNullable<z.ZodString>;
+        reviewDecision: z.ZodNullable<z.ZodEnum<{
+            PASS: "PASS";
+            REWORK: "REWORK";
+            REJECT: "REJECT";
+        }>>;
+        support: z.ZodNullable<z.ZodObject<{
+            action: z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>;
+            reasonCodes: z.ZodArray<z.ZodString>;
+            missingEvidenceRefs: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+        governedPolicyReady: z.ZodBoolean;
+        consumerReadDecision: z.ZodNullable<z.ZodObject<{
+            action: z.ZodEnum<{
+                ALLOW: "ALLOW";
+                REVIEW_REQUIRED: "REVIEW_REQUIRED";
+                DENY: "DENY";
+            }>;
+            reasonCodes: z.ZodArray<z.ZodString>;
+            authority: z.ZodEnum<{
+                AUTHENTICATED_READER: "AUTHENTICATED_READER";
+                LOCAL_PROFILE_SIMULATION: "LOCAL_PROFILE_SIMULATION";
+            }>;
+        }, z.core.$strict>>;
+        externalReady: z.ZodBoolean;
+        successorRef: z.ZodNullable<z.ZodString>;
+        blockers: z.ZodArray<z.ZodString>;
+        nextActions: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            tool: z.ZodNullable<z.ZodString>;
+            arguments: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+            requiredScopes: z.ZodArray<z.ZodString>;
+            missingScopes: z.ZodArray<z.ZodString>;
+            missingFields: z.ZodArray<z.ZodString>;
+            canExecute: z.ZodBoolean;
+            automatic: z.ZodBoolean;
+            reasonCode: z.ZodString;
+            cli: z.ZodObject<{
+                command: z.ZodString;
+                flags: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            http: z.ZodObject<{
+                method: z.ZodLiteral<"POST">;
+                path: z.ZodLiteral<"/mcp/management">;
+                tool: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const workflowErrorSchema: z.ZodObject<{
+    errorCode: z.ZodString;
+    completedPhase: z.ZodOptional<z.ZodEnum<{
+        REGISTERED: "REGISTERED";
+        VALIDATED: "VALIDATED";
+        PERSISTED: "PERSISTED";
+        CATALOG_PROJECTED: "CATALOG_PROJECTED";
+    }>>;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const workflowToolInputSchemas: {
+    readonly knowledge_workflow_guide: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+    }, z.core.$strict>>;
+    readonly knowledge_workflow_plan: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+    }, z.core.$strict>>;
+    readonly knowledge_workflow_advance: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        ref: z.ZodString;
+        action: z.ZodEnum<{
+            SUBMIT_REVIEW: "SUBMIT_REVIEW";
+            FINALIZE_REVIEW: "FINALIZE_REVIEW";
+            PREPARE_SOURCE: "PREPARE_SOURCE";
+            REGISTER: "REGISTER";
+        }>;
+        expectedVersion: z.ZodOptional<z.ZodNumber>;
+        actedAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    readonly knowledge_agent_submit: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+        projectRef: z.ZodString;
+        sourceId: z.ZodString;
+        contentBase64: z.ZodString;
+        mediaType: z.ZodString;
+        access: z.ZodDefault<z.ZodEnum<{
+            PUBLIC: "PUBLIC";
+            TENANT: "TENANT";
+            INTERNAL: "INTERNAL";
+            FDE_INTERNAL: "FDE_INTERNAL";
+        }>>;
+        submittedAt: z.ZodOptional<z.ZodISODateTime>;
+        freshnessSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+};
+export declare const workflowToolScopes: {
+    readonly knowledge_workflow_guide: "knowledge.workflow.read";
+    readonly knowledge_workflow_plan: "knowledge.workflow.read";
+    readonly knowledge_workflow_advance: "knowledge.workflow.read";
+    readonly knowledge_agent_submit: "knowledge.material.write";
+};
+export declare const workflowActionScopes: {
+    readonly PREPARE_SOURCE: "knowledge.compose";
+    readonly SUBMIT_REVIEW: "knowledge.compose";
+    readonly FINALIZE_REVIEW: "knowledge.approve";
+    readonly REGISTER: "knowledge.material.write";
+};
+export type WorkflowPlan = z.infer<typeof workflowPlanSchema>;
+export type WorkflowNextAction = z.infer<typeof workflowNextActionSchema>;
+export type WorkflowAction = z.infer<typeof workflowActionSchema>;
+export type WorkflowReadDecision = z.infer<typeof readDecision>;
+/** 网络成功和失败共享可发现 schema，阶段包含已经完成注册后的尾部失败。 */
+export declare const agentSubmitResultSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    production: z.ZodObject<{
+        phase: z.ZodEnum<{
+            REGISTERED: "REGISTERED";
+            CATALOG_PROJECTED: "CATALOG_PROJECTED";
+        }>;
+        ref: z.ZodString;
+        registered: z.ZodBoolean;
+        identity: z.ZodEnum<{
+            NOT_CONFIGURED: "NOT_CONFIGURED";
+            CONFIGURED: "CONFIGURED";
+        }>;
+    }, z.core.$strict>;
+    presentation: z.ZodNullable<z.ZodObject<{
+        documentRef: z.ZodString;
+        inserted: z.ZodBoolean;
+        contentHash: z.ZodString;
+    }, z.core.$strict>>;
+    evidenceRef: z.ZodString;
+    projectRef: z.ZodString;
+    contentHash: z.ZodString;
+    byteLength: z.ZodNumber;
+    inserted: z.ZodBoolean;
+    lifecycle: z.ZodLiteral<"QUEUED">;
+    contentClass: z.ZodLiteral<"RAW_EVIDENCE">;
+    nextStep: z.ZodObject<{
+        tool: z.ZodLiteral<"knowledge_workflow_plan">;
+        arguments: z.ZodObject<{
+            projectRef: z.ZodString;
+            ref: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const workflowToolOutputSchemas: {
+    readonly knowledge_workflow_guide: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+    readonly knowledge_workflow_plan: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+    readonly knowledge_workflow_advance: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+    readonly knowledge_agent_submit: {
+        type: string;
+        oneOf: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>[];
+    };
+};
+/** 同一份模型与参数 schema 供 CLI、MCP guide 和文档示例使用；不给 review 默认 PASS。 */
+export declare function workflowGuide(): {
+    schemaVersion: number;
+    model: {
+        raw: string;
+        reviewed: string;
+        lifecycle: string[];
+        publication: string[];
+    };
+    rules: string[];
+    tools: Record<string, {
+        requiredScope: string;
+        inputSchema: unknown;
+    }>;
+    advanceScopes: {
+        readonly PREPARE_SOURCE: "knowledge.compose";
+        readonly SUBMIT_REVIEW: "knowledge.compose";
+        readonly FINALIZE_REVIEW: "knowledge.approve";
+        readonly REGISTER: "knowledge.material.write";
+    };
+    https: {
+        method: string;
+        path: string;
+        body: {
+            tool: string;
+            arguments: string;
+        };
+        authorization: string;
+    };
+};
+export {};

package/package.json

@@ -1,6 +1,36 @@
 {
+  "version": "0.1.0-rc.1",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SENLIN746/native-knowledge.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "name": "@native-knowledge/knowledge-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Governed native-knowledge clients for Node.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/sdk/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/types/sdk/index.d.ts",
+  "dependencies": {
+    "zod": "4.6.7",
+    "@types/node": "24.13.3"
+  }
+}