@world-engines/dag-flow 0.1.3-alpha.0

package/LICENSE

@@ -0,0 +1,46 @@
+WorldEngine 官方作者工具许可证
+
+版权所有 (c) 2026 Nixdorfer。保留所有权利。
+
+本仓库的源代码、构建材料及附带资源（统称“本作品”）不是开源软件，
+不适用任何 OSI 认证的开源许可证。
+
+一、官方作者工具分发许可
+
+版权所有者可以通过其官方网站、npm registry、签名安装包或其他官方渠道，
+复制并分发由本作品构建的 WorldEngine 作者工具及其必要运行资源
+（统称“官方作者工具”）。仅版权所有者或其书面指定的发布者享有此分发权。
+
+二、作者用户许可
+
+从官方渠道取得官方作者工具的作者用户，可以：
+
+1. 安装和运行官方作者工具；
+2. 使用官方作者工具创作、编辑、预览、导入、导出和提交其有权处理的内容；
+3. 为上述使用目的制作合理必要的本地备份副本。
+
+三、未授予的权利
+
+除第二条明确允许的行为外，本许可证不授予作者用户或其他第三方以下权利：
+
+1. 修改、改编、反编译、反汇编或制作官方作者工具的派生作品；
+2. 复制、镜像、转发、再上传、出售、出租、再分发或再许可官方作者工具；
+3. 使用本作品的源代码、构建材料或任何部分开发、提供或训练其他产品或服务；
+4. 删除或规避版权、许可、签名、访问控制或其他权利管理信息。
+
+法律强制允许且合同不得排除的权利不受上述限制影响。
+
+四、源代码查看
+
+第三方可以在已获合法访问权限的范围内查看本作品，用于审查、安全研究或学习参考；
+查看不授予运行、复制、修改、分发、再许可或用于其他产品与服务的权利。
+
+五、无担保与责任限制
+
+本作品与官方作者工具均按“现状”提供，不附带任何明示或暗示的担保。
+在适用法律允许的最大范围内，版权所有者不对因访问或使用本作品或官方作者工具
+造成的任何损失承担责任。
+
+六、终止
+
+违反本许可证将立即终止相应的访问与使用权；终止不影响版权所有者已经产生的权利和救济。

package/dist/document.d.ts

@@ -0,0 +1,193 @@
+/** 浏览器和 Node 共用的作者 Agent DAG 文档。 */
+/** 当前持久化版本。读取器仍接受 v1，并通过 upgradeDagDocument 显式规范化。 */
+export declare const DAG_FLOW_SCHEMA_VERSION: 2;
+export declare const DAG_FLOW_LEGACY_SCHEMA_VERSION: 1;
+export type DagSchemaVersion = typeof DAG_FLOW_LEGACY_SCHEMA_VERSION | typeof DAG_FLOW_SCHEMA_VERSION;
+export declare const DAG_FLOW_SOURCE_SECTION_KEY: "view.agent_dag";
+export declare const DAG_FLOW_VIEW_PERMISSION: "view";
+export declare const SYSTEM_USER_INPUT_NODE_ID: "user_input";
+export declare const SYSTEM_DIRECTOR_NODE_ID: "director";
+export declare const SYSTEM_TEXT_OUTPUT_NODE_ID: "text_output";
+/** 作者 Agent 只能插入这三个由系统调度的阶段，不能改写系统主线。 */
+export declare const DAG_INSERTION_SLOTS: readonly ["before_director", "after_scribe", "after_writer"];
+export type DagInsertionSlot = typeof DAG_INSERTION_SLOTS[number];
+/** v2 将每个可插入阶段的控制流边界作为持久化数据保存。 */
+export interface DagStageBoundary {
+    readonly slot: DagInsertionSlot;
+    readonly start_id: string;
+    readonly handoff_id: string;
+}
+export declare const DAG_STAGE_BOUNDARIES: readonly DagStageBoundary[];
+export interface DagStageStartNode {
+    readonly id: string;
+    readonly kind: "stage_start";
+    readonly slot: DagInsertionSlot;
+    readonly system: true;
+}
+export interface DagStageHandoffNode {
+    readonly id: string;
+    readonly kind: "stage_handoff";
+    readonly slot: DagInsertionSlot;
+    readonly system: true;
+}
+export interface DagStageFlow {
+    readonly enabled: true;
+}
+/** 仅供界面展示的真实系统角色；它们不是可编辑 DAG 节点。 */
+export declare const SYSTEM_AGENT_ROLE_CATALOG: readonly [{
+    readonly id: "director";
+    readonly label: "Director";
+}, {
+    readonly id: "screenwriter";
+    readonly label: "Screenwriter";
+}, {
+    readonly id: "scribe";
+    readonly label: "Scribe";
+}, {
+    readonly id: "writer";
+    readonly label: "Writer";
+}, {
+    readonly id: "scene";
+    readonly label: "Scene";
+}, {
+    readonly id: "photographer";
+    readonly label: "Photographer";
+}, {
+    readonly id: "voice";
+    readonly label: "Voice";
+}];
+export type DagSystemAgentRole = typeof SYSTEM_AGENT_ROLE_CATALOG[number]["id"];
+/** 编剧召回是 WASM 检索工具而非冻结 LLM Agent，不能承载可执行提示词覆盖。 */
+export declare const EDITABLE_SYSTEM_AGENT_ROLES: readonly ["director", "scribe", "writer", "scene", "photographer", "voice"];
+export type EditableDagSystemAgentRole = typeof EDITABLE_SYSTEM_AGENT_ROLES[number];
+/** 可在 DAG 内部传递的有限、无循环、普通 JSON 值。 */
+export type DagJson = null | boolean | number | string | readonly DagJson[] | {
+    readonly [key: string]: DagJson;
+};
+export interface DagPosition {
+    readonly x: number;
+    readonly y: number;
+}
+export interface DagPortRef {
+    readonly node_id: string;
+    readonly port: string;
+}
+export interface DagEdge {
+    readonly id: string;
+    readonly from: DagPortRef;
+    readonly to: DagPortRef;
+}
+/** 后端将三段作者内容注入 Agent 消息；执行器不改写 Agent 的返回正文。 */
+export interface DagPromptTemplates {
+    readonly system: string;
+    readonly primer: string;
+    readonly anchor: string;
+}
+export interface DagPromptBlock {
+    readonly id: string;
+    readonly name: string;
+    readonly role: "system" | "assistant" | "user";
+    readonly content: string;
+}
+/**
+ * 系统角色的作者可编辑消息层。平台安全策略、语言策略和工具协议仍由运行时追加，
+ * 不在这个文档中删除或伪造。键缺省时保留冻结运行时的既有默认层，保证旧文档兼容。
+ */
+export type DagSystemAgentPrompts = Readonly<Partial<Record<DagSystemAgentRole, readonly DagPromptBlock[]>>>;
+export declare function defaultSystemAgentPromptBlocks(role: DagSystemAgentRole): readonly DagPromptBlock[];
+export interface DagAgentNode {
+    readonly id: string;
+    readonly name?: string;
+    readonly kind: "agent";
+    readonly config: {
+        readonly system_prompt: string;
+        readonly model_id: string;
+        readonly require_json: boolean;
+        readonly prompt_injection: "enabled" | "disabled";
+        readonly templates: DagPromptTemplates;
+        readonly prompt_blocks?: readonly DagPromptBlock[];
+    };
+}
+export interface DagScriptNode {
+    readonly id: string;
+    readonly name?: string;
+    readonly kind: "script";
+    readonly config: {
+        readonly source: string;
+        readonly entrypoint?: "main";
+        readonly paths?: readonly string[];
+    };
+}
+export interface DagUserInputNode {
+    readonly id: typeof SYSTEM_USER_INPUT_NODE_ID;
+    readonly kind: "user_input";
+    readonly system: true;
+}
+export interface DagDirectorNode {
+    readonly id: typeof SYSTEM_DIRECTOR_NODE_ID;
+    readonly kind: "director";
+    readonly system: true;
+}
+export interface DagTextOutputNode {
+    readonly id: typeof SYSTEM_TEXT_OUTPUT_NODE_ID;
+    readonly kind: "text_output";
+    readonly system: true;
+    readonly name?: string;
+}
+export interface DagAuthorTextOutputNode {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: "text_output";
+    readonly system?: never;
+}
+export type DagNode = DagAgentNode | DagScriptNode | DagAuthorTextOutputNode | DagUserInputNode | DagDirectorNode | DagTextOutputNode | DagStageStartNode | DagStageHandoffNode;
+export interface DagDocument {
+    readonly schema_version: DagSchemaVersion;
+    readonly section_key: typeof DAG_FLOW_SOURCE_SECTION_KEY;
+    readonly permission: typeof DAG_FLOW_VIEW_PERMISSION;
+    readonly nodes: readonly DagNode[];
+    readonly edges: readonly DagEdge[];
+    /** 各系统 Agent 的作者可编辑消息层；没有键时仍由运行时使用冻结默认提示词。 */
+    readonly system_agent_prompts?: DagSystemAgentPrompts;
+    /** 数组顺序就是该阶段的 Agent 执行顺序；槽内 Agent 不使用作者边。 */
+    readonly insertion_slots?: Readonly<Partial<Record<DagInsertionSlot, readonly string[]>>>;
+    readonly positions?: Readonly<Record<string, DagPosition>>;
+    /** v2 阶段边界；边界本身是控制流算子，不携带业务数据。 */
+    readonly stage_boundaries?: readonly DagStageBoundary[];
+    /** 文本出口是否立即结束本轮；缺省保持 v1 多出口兼容，v2 编辑器显式写 true。 */
+    readonly execution?: Readonly<{
+        readonly terminal_on_text_output?: boolean;
+    }>;
+    /** 存在时由真实三阶段 start/handoff 图执行，不再使用 insertion_slots 投影。 */
+    readonly stage_flow?: DagStageFlow;
+}
+export type DagValidationMode = "draft" | "run" | "publish";
+export interface DagValidationIssue {
+    readonly code: string;
+    readonly message: string;
+    readonly node_id?: string;
+    readonly edge_id?: string;
+}
+export interface DagValidationResult {
+    readonly ok: boolean;
+    readonly issues: readonly DagValidationIssue[];
+}
+export declare function createEmptyDagDocument(): DagDocument;
+/** 创建可序列化、可执行的三阶段控制流图。默认 start → handoff 可由作者删除后重新接线。 */
+export declare function createStageDagDocument(): DagDocument;
+export interface DagUpgradeResult {
+    readonly document: DagDocument;
+    readonly migrated: boolean;
+}
+/**
+ * 将 v1 文档升级为 v2。升级只补齐明确的阶段边界，不猜测节点之间的作者连线；
+ * 形状不明确或版本过新时拒绝，避免把旧数据静默解释成另一条执行路径。
+ */
+export declare function upgradeDagDocument(value: unknown): DagUpgradeResult;
+/** 对不可信 JSON 文档只返回问题清单，永不因形状错误抛出。 */
+export declare function validateDagDocument(document: unknown, options?: {
+    readonly mode?: DagValidationMode;
+}): DagValidationResult;
+/** 判断值能否完整且无损地作为 DAG 内部的 JSON 值传递。 */
+export declare function isDagJson(value: unknown): value is DagJson;
+export declare function dagMixedToString(value: DagJson): string;