Merge pull request #606 from objectstack-ai/copilot/optimize-protocol-report-again

Author: hotlong

PROTOCOL_OPTIMIZATION_REPORT.md

@@ -90,7 +90,7 @@ ObjectStack 协议规范展现出**卓越的架构设计**和**企业级成熟
 | 优先级 | 问题 | 当前状态 | 推荐方案 | 验证状态 |
 |--------|------|----------|----------|----------|
 | ~~🔴 高~~ | ~~缺少游标分页~~ | ~~query.zod.ts注释提及但未实现~~ | ~~添加cursor字段~~ | ✅ **已实现** - query.zod.ts已有keyset pagination cursor字段 |
-| 🟡 中 | 驱动接口过度指定 | driver.zod.ts用Zod `z.function()`验证20+方法签名 | 分离为TypeScript接口，Zod仅描述能力标志 | ⏳ 待处理 |
+| 🟡 中 | 驱动接口过度指定 | driver.zod.ts用Zod `z.function()`验证20+方法签名 | 分离为TypeScript接口，Zod仅描述能力标志 | ✅ **已实现** - contracts/data-driver.ts IDataDriver接口 |
 | 🟡 中 | 外部查找健壮性不足 | external-lookup.zod.ts有缓存策略但缺少重试 | 添加指数退避、请求转换管道、分页支持 | ⏳ 待处理 |
 | 🟢 低 | 命名不一致 | `externalId`(22处) vs `external_id`(2处) | 统一为camelCase `externalId` | ⏳ 待处理 |
 
@@ -205,8 +205,8 @@ export const ViewSchema = z.object({
 | 优先级 | 问题 | 推荐方案 | 验证状态 |
 |--------|------|----------|----------|
 | ~~🔴 高~~ | ~~协议统一查询语言~~ | ~~抽象过滤器为内部规范~~ | ⚠️ **部分实现** - data/query.zod.ts已有统一DSL，降为P1完成API层适配 |
-| 🔴 高 | GraphQL Federation | 添加联邦指令Schema定义 | ⏳ 待处理 - 确认缺失 |
-| 🟡 中 | 实时协议合并 | 统一websocket + realtime为单一规范 | ⏳ 待处理 - 确认重叠 |
+| 🔴 高 | GraphQL Federation | 添加联邦指令Schema定义 | ✅ **已实现** - FederationGateway/Entity/Subgraph完整定义 |
+| 🟡 中 | 实时协议合并 | 统一websocket + realtime为单一规范 | ✅ **已实现** - realtime-shared.zod.ts已提取共享定义 |
 | 🟡 中 | N+1查询预防 | 添加DataLoader等价物到contract.zod.ts | ⏳ 待处理 |
 | 🟢 低 | OpenAPI 3.1升级 | rest-server.zod.ts添加webhooks/callbacks支持 | ⏳ 待处理 |
 
@@ -260,7 +260,7 @@ export function toODataFilter(unified: UnifiedFilter): string {
 #### 改进建议
 | 优先级 | 问题 | 推荐方案 |
 |--------|------|----------|
-| 🔴 高 | 多智能体协调缺失 | 扩展orchestration.zod.ts添加智能体群组、角色分配、协作模式 |
+| 🔴 高 | 多智能体协调缺失 | 扩展orchestration.zod.ts添加智能体群组、角色分配、协作模式 | ✅ **已实现** |
 | 🟡 中 | 代理记忆系统 | 添加长期/短期记忆分层、反思机制、知识图谱集成 |
 | 🟡 中 | 结构化输出保障 | 添加JSON Schema约束、Pydantic模型绑定 |
 | 🟢 低 | 成本预估 | 在agent/workflow执行计划中添加token成本估算 |
@@ -353,40 +353,41 @@ export const MultiAgentOrchestrationSchema = z.object({
 
 ### 第二阶段 (P1 - Sprint 3-6, 1-2个月内)
 
-#### Sprint 3: GraphQL Federation Schema
+#### Sprint 3: GraphQL Federation Schema ✅
 - **任务 3.1**: 在 `api/graphql.zod.ts` 添加Federation指令Schema
-  - 定义 `FederationDirectiveSchema` (key, external, requires, provides)
-  - 添加 `SubgraphConfigSchema` (service URL, schema拼接策略)
-  - 定义 `FederationGatewaySchema` (服务发现, 查询路由)
-- **预估工时**: 3-4天
-- **交付物**: graphql.zod.ts federation扩展 + 测试
-
-#### Sprint 4: AI多智能体协调
-- **任务 4.1**: 扩展 `ai/agent.zod.ts` (当前80行 → 目标200行)
-  - 添加自主推理循环配置 (planningStrategy, maxIterations)
-  - 添加记忆管理 (shortTermMemory, longTermMemory, reflectionInterval)
+  - ✅ 定义 `FederationEntityKeySchema` / `FederationExternalFieldSchema` / `FederationRequiresSchema` / `FederationProvidesSchema`
+  - ✅ 定义 `FederationEntitySchema` (key, external, requires, provides)
+  - ✅ 添加 `SubgraphConfigSchema` (service URL, schema拼接策略, 健康检查)
+  - ✅ 定义 `FederationGatewaySchema` (服务发现, 查询路由, Schema组合)
+  - ✅ 集成到 `GraphQLConfigSchema.federation`
+- **交付物**: graphql.zod.ts federation扩展 + 17项测试
+
+#### Sprint 4: AI多智能体协调 ✅
+- **任务 4.1**: 扩展 `ai/agent.zod.ts`
+  - ✅ 添加自主推理循环配置 (`planning`: react/plan_and_execute/reflexion/tree_of_thought)
+  - ✅ 添加记忆管理 (`memory`: shortTerm/longTerm/reflectionInterval)
+  - ✅ 添加安全护栏 (`guardrails`: maxTokens/maxExecutionTime/blockedTopics)
 - **任务 4.2**: 扩展 `ai/orchestration.zod.ts` 多智能体
-  - 添加 `MultiAgentGroupSchema` (strategy, roles, communication protocol)
-  - 定义智能体间通信 (message_passing, shared_memory, blackboard)
-  - 添加冲突解决策略 (voting, priority, consensus)
-- **预估工时**: 4-5天
-- **交付物**: 增强的agent.zod.ts + orchestration.zod.ts + 测试
+  - ✅ 添加 `MultiAgentGroupSchema` (5种策略: sequential/parallel/debate/hierarchical/swarm)
+  - ✅ 定义 `AgentGroupMemberSchema` (roles, capabilities, dependencies)
+  - ✅ 定义 `AgentCommunicationProtocolSchema` (message_passing/shared_memory/blackboard)
+  - ✅ 添加冲突解决策略 (voting/priorityBased/consensusBased/coordinatorDecides)
+- **交付物**: 增强的agent.zod.ts + orchestration.zod.ts + 18项测试
 
-#### Sprint 5: 驱动接口重构
+#### Sprint 5: 驱动接口重构 ✅
 - **任务 5.1**: 将 `data/driver.zod.ts` 中的 `z.function()` 签名迁移到TypeScript接口
-  - 创建 `contracts/data-driver.ts` 纯TS接口
-  - driver.zod.ts 仅保留 `DriverCapabilitiesSchema` 和 `DriverConfigSchema`
-  - 保持向后兼容: 导出旧Schema作为deprecated
-- **预估工时**: 3-4天
-- **交付物**: contracts/data-driver.ts + 精简的driver.zod.ts
+  - ✅ 创建 `contracts/data-driver.ts` 纯TS接口 (`IDataDriver`)
+  - ✅ driver.zod.ts 保留完整 (向后兼容) — Zod Schema继续用于运行时验证
+  - ✅ 导出到 `contracts/index.ts`
+- **交付物**: contracts/data-driver.ts + 3项测试
 
-#### Sprint 6: API层查询DSL适配
+#### Sprint 6: API层查询DSL适配 ✅
 - **任务 6.1**: 创建 `api/query-adapter.zod.ts` 协议转换定义
-  - 定义 REST → 统一DSL 映射规则Schema
-  - 定义 GraphQL → 统一DSL 映射规则Schema
-  - 定义 OData → 统一DSL 映射规则Schema
-- **预估工时**: 3-4天
-- **交付物**: query-adapter.zod.ts + 测试
+  - ✅ 定义 REST → 统一DSL 映射规则Schema (`RestQueryAdapterSchema`)
+  - ✅ 定义 GraphQL → 统一DSL 映射规则Schema (`GraphQLQueryAdapterSchema`)
+  - ✅ 定义 OData → 统一DSL 映射规则Schema (`ODataQueryAdapterSchema`)
+  - ✅ 定义 `QueryAdapterConfigSchema` 根配置 + `OperatorMappingSchema`
+- **交付物**: query-adapter.zod.ts + 20项测试
 
 ### 第三阶段 (P2 - Sprint 7-10, 3-6个月内)
 
@@ -634,10 +635,10 @@ ObjectStack协议规范已具备**世界级企业管理软件框架**的基础
 4. ⏳ **实时协议统一** - 合并websocket/realtime重叠 (Sprint 2, 新增)
 
 ### 战略性改进 (Next 3 Months) - 4 Sprints
-5. ⏳ **GraphQL Federation** - 联邦指令Schema定义 (Sprint 3)
-6. ⏳ **AI智能体生态** - 多智能体协调、记忆管理 (Sprint 4)
-7. ⏳ **驱动接口重构** - 分离Zod/TS定义 (Sprint 5)
-8. ⏳ **API查询适配** - 协议层绑定统一DSL (Sprint 6)
+5. ✅ **GraphQL Federation** - 联邦指令Schema定义 (Sprint 3)
+6. ✅ **AI智能体生态** - 多智能体协调、记忆管理 (Sprint 4)
+7. ✅ **驱动接口重构** - 分离Zod/TS定义 (Sprint 5)
+8. ✅ **API查询适配** - 协议层绑定统一DSL (Sprint 6)
 
 ### 长期愿景 (6+ Months) - 4 Sprints
 9. ⏳ **灾难恢复** - 多区域容错和备份模式 (Sprint 7)

packages/spec/src/ai/agent.test.ts

@@ -439,4 +439,134 @@ Be precise, data-driven, and clear in your explanations.`,
       expect(result.lifecycle?.initial).toBe('idle');
     });
   });
+
+  describe('Autonomous Reasoning', () => {
+    it('should accept agent with planning configuration', () => {
+      const agent = AgentSchema.parse({
+        name: 'planner_agent',
+        label: 'Planning Agent',
+        role: 'Strategic Planner',
+        instructions: 'Plan and execute complex tasks.',
+        planning: {
+          strategy: 'plan_and_execute',
+          maxIterations: 20,
+          allowReplan: true,
+        },
+      });
+
+      expect(agent.planning?.strategy).toBe('plan_and_execute');
+      expect(agent.planning?.maxIterations).toBe(20);
+      expect(agent.planning?.allowReplan).toBe(true);
+    });
+
+    it('should accept all planning strategies', () => {
+      const strategies = ['react', 'plan_and_execute', 'reflexion', 'tree_of_thought'] as const;
+
+      strategies.forEach(strategy => {
+        const agent = AgentSchema.parse({
+          name: 'test_agent',
+          label: 'Test',
+          role: 'Test',
+          instructions: 'Test',
+          planning: { strategy },
+        });
+        expect(agent.planning?.strategy).toBe(strategy);
+      });
+    });
+
+    it('should apply default planning values', () => {
+      const agent = AgentSchema.parse({
+        name: 'default_agent',
+        label: 'Default',
+        role: 'Default',
+        instructions: 'Test',
+        planning: {},
+      });
+
+      expect(agent.planning?.strategy).toBe('react');
+      expect(agent.planning?.maxIterations).toBe(10);
+      expect(agent.planning?.allowReplan).toBe(true);
+    });
+
+    it('should enforce maxIterations constraints', () => {
+      expect(() => AgentSchema.parse({
+        name: 'test',
+        label: 'Test',
+        role: 'Test',
+        instructions: 'Test',
+        planning: { maxIterations: 0 },
+      })).toThrow();
+
+      expect(() => AgentSchema.parse({
+        name: 'test',
+        label: 'Test',
+        role: 'Test',
+        instructions: 'Test',
+        planning: { maxIterations: 101 },
+      })).toThrow();
+    });
+  });
+
+  describe('Memory Management', () => {
+    it('should accept agent with memory configuration', () => {
+      const agent = AgentSchema.parse({
+        name: 'memory_agent',
+        label: 'Memory Agent',
+        role: 'Persistent Assistant',
+        instructions: 'Remember across sessions.',
+        memory: {
+          shortTerm: {
+            maxMessages: 100,
+            maxTokens: 4096,
+          },
+          longTerm: {
+            enabled: true,
+            store: 'vector',
+            maxEntries: 10000,
+          },
+          reflectionInterval: 5,
+        },
+      });
+
+      expect(agent.memory?.shortTerm?.maxMessages).toBe(100);
+      expect(agent.memory?.longTerm?.enabled).toBe(true);
+      expect(agent.memory?.longTerm?.store).toBe('vector');
+      expect(agent.memory?.reflectionInterval).toBe(5);
+    });
+
+    it('should accept all memory store backends', () => {
+      const stores = ['vector', 'database', 'redis'] as const;
+
+      stores.forEach(store => {
+        const agent = AgentSchema.parse({
+          name: 'test_agent',
+          label: 'Test',
+          role: 'Test',
+          instructions: 'Test',
+          memory: { longTerm: { enabled: true, store } },
+        });
+        expect(agent.memory?.longTerm?.store).toBe(store);
+      });
+    });
+  });
+
+  describe('Guardrails', () => {
+    it('should accept agent with guardrails', () => {
+      const agent = AgentSchema.parse({
+        name: 'safe_agent',
+        label: 'Safe Agent',
+        role: 'Restricted Assistant',
+        instructions: 'Operate within guardrails.',
+        guardrails: {
+          maxTokensPerInvocation: 8192,
+          maxExecutionTimeSec: 60,
+          blockedTopics: ['financial_advice', 'medical_diagnosis'],
+        },
+      });
+
+      expect(agent.guardrails?.maxTokensPerInvocation).toBe(8192);
+      expect(agent.guardrails?.maxExecutionTimeSec).toBe(60);
+      expect(agent.guardrails?.blockedTopics).toContain('financial_advice');
+    });
+  });
 });

packages/spec/src/ai/agent.zod.ts

@@ -81,6 +81,57 @@ export const AgentSchema = z.object({
   /** Multi-tenancy & Visibility */
   tenantId: z.string().optional().describe('Tenant/Organization ID'),
   visibility: z.enum(['global', 'organization', 'private']).default('organization'),
+
+  /** Autonomous Reasoning */
+  planning: z.object({
+    /** Planning strategy for autonomous reasoning loops */
+    strategy: z.enum(['react', 'plan_and_execute', 'reflexion', 'tree_of_thought']).default('react').describe('Autonomous reasoning strategy'),
+
+    /** Maximum reasoning iterations before stopping */
+    maxIterations: z.number().int().min(1).max(100).default(10).describe('Maximum planning loop iterations'),
+
+    /** Whether the agent can revise its own plan mid-execution */
+    allowReplan: z.boolean().default(true).describe('Allow dynamic re-planning based on intermediate results'),
+  }).optional().describe('Autonomous reasoning and planning configuration'),
+
+  /** Memory Management */
+  memory: z.object({
+    /** Short-term (working) memory configuration */
+    shortTerm: z.object({
+      /** Maximum number of recent messages to retain */
+      maxMessages: z.number().int().min(1).default(50).describe('Max recent messages in working memory'),
+
+      /** Maximum token budget for short-term context */
+      maxTokens: z.number().int().min(100).optional().describe('Max tokens for short-term context window'),
+    }).optional().describe('Short-term / working memory'),
+
+    /** Long-term (persistent) memory configuration */
+    longTerm: z.object({
+      /** Whether long-term memory is enabled */
+      enabled: z.boolean().default(false).describe('Enable long-term memory persistence'),
+
+      /** Storage backend for long-term memory */
+      store: z.enum(['vector', 'database', 'redis']).default('vector').describe('Long-term memory storage backend'),
+
+      /** Maximum number of persisted memory entries */
+      maxEntries: z.number().int().min(1).optional().describe('Max entries in long-term memory'),
+    }).optional().describe('Long-term / persistent memory'),
+
+    /** Reflection interval — how often the agent reflects on past actions */
+    reflectionInterval: z.number().int().min(1).optional().describe('Reflect every N interactions to improve behavior'),
+  }).optional().describe('Agent memory management'),
+
+  /** Guardrails */
+  guardrails: z.object({
+    /** Maximum tokens the agent may consume per invocation */
+    maxTokensPerInvocation: z.number().int().min(1).optional().describe('Token budget per single invocation'),
+
+    /** Maximum wall-clock time per invocation in seconds */
+    maxExecutionTimeSec: z.number().int().min(1).optional().describe('Max execution time in seconds'),
+
+    /** Topics or actions the agent must avoid */
+    blockedTopics: z.array(z.string()).optional().describe('Forbidden topics or action names'),
+  }).optional().describe('Safety guardrails for the agent'),
 });
 
 export type Agent = z.infer<typeof AgentSchema>;