From 84375da3c50ef7962c7b73464cbf917683245f94 Mon Sep 17 00:00:00 2001 From: matevip Date: Fri, 5 Jun 2026 07:55:59 +0800 Subject: [PATCH] release: v1.5.0 --- .../vip/mate/agent/AgentGraphBuilder.java | 187 ++- .../java/vip/mate/agent/AgentService.java | 97 +- .../controller/AgentBindingController.java | 12 +- .../binding/service/AgentBindingService.java | 240 +++- .../context/ConversationWindowManager.java | 9 + .../mate/agent/context/LoopBudgetConfig.java | 140 ++ .../agent/context/LoopMessageBudgeter.java | 296 +++++ .../agent/context/RuntimeContextInjector.java | 28 + .../mate/agent/context/ToolPairSanitizer.java | 192 +++ .../agent/controller/AgentController.java | 9 +- .../mate/agent/graph/MessageNormalizer.java | 165 +++ .../agent/graph/NodeStreamingChatHelper.java | 47 +- .../graph/executor/ToolExecutionExecutor.java | 100 +- .../agent/graph/node/GoalEvaluationNode.java | 43 +- .../mate/agent/graph/node/ReasoningNode.java | 174 +-- .../graph/plan/node/PlanGenerationNode.java | 18 +- .../vip/mate/agent/model/AgentEntity.java | 53 + .../approval/ApprovalWorkflowService.java | 36 + .../event/ApprovalResolutionEvent.java | 41 + .../grant/AutoApproveAuditLogger.java | 76 ++ .../approval/grant/AutoApproveResult.java | 58 + .../approval/grant/AutoGrantSafetyFloor.java | Bin 0 -> 6480 bytes .../approval/grant/WorkspaceLookupCache.java | 77 ++ .../controller/ApprovalGrantController.java | 399 ++++++ .../approval/grant/entity/ApprovalGrant.java | 98 ++ .../grant/entity/ApprovalResolutionLog.java | 78 ++ .../ApprovalResolutionLogListener.java | 104 ++ .../ConversationLifecycleListener.java | 62 + .../grant/repository/ApprovalGrantMapper.java | 58 + .../ApprovalResolutionLogMapper.java | 9 + .../grant/service/ApprovalGrantResolver.java | 174 +++ .../grant/service/ApprovalGrantService.java | 103 ++ .../vip/mate/auth/service/AuthService.java | 36 +- .../mate/channel/ChannelMessageRouter.java | 156 ++- .../channel/controller/ChannelController.java | 44 +- .../channel/feishu/FeishuChannelAdapter.java | 215 ++- .../channel/media/GeneratedFileScrubber.java | 5 +- .../channel/media/InboundMediaDownloader.java | 286 ++++ .../mate/channel/media/MediaTypeSniffer.java | 281 ++++ .../vip/mate/channel/web/ChatController.java | 55 +- .../channel/web/TalkModeWebSocketHandler.java | 20 +- .../channel/webchat/WebChatController.java | 29 +- .../channel/wecom/WeComChannelAdapter.java | 332 +---- .../channel/weixin/WeixinChannelAdapter.java | 151 ++- .../cron/service/CronJobLifecycleService.java | 23 +- .../vip/mate/cron/service/CronJobRunner.java | 21 +- .../vip/mate/goal/config/GoalProperties.java | 25 +- .../mate/goal/controller/GoalController.java | 37 +- .../mate/goal/model/GoalChecklistVerdict.java | 24 + .../mate/goal/model/GoalCreateRequest.java | 10 + .../mate/goal/model/GoalCriteriaCodec.java | 112 ++ .../mate/goal/model/GoalCriteriaDraft.java | 19 + .../vip/mate/goal/model/GoalCriterion.java | 19 + .../java/vip/mate/goal/model/GoalEntity.java | 11 + .../mate/goal/model/GoalEvaluationResult.java | 48 +- .../vip/mate/goal/model/GoalResponse.java | 54 + .../java/vip/mate/goal/model/GoalStatus.java | 2 +- .../goal/service/GoalEvaluationService.java | 348 +++-- .../goal/service/GoalFollowupService.java | 70 +- .../vip/mate/goal/service/GoalService.java | 16 +- .../mate/goal/service/GoalServiceImpl.java | 149 ++- .../chatmodel/AnthropicChatModelBuilder.java | 37 +- .../vip/mate/llm/routing/ProviderRouter.java | 103 +- .../mate/llm/service/ModelConfigService.java | 26 + .../event/ConversationCompletedEvent.java | 14 +- .../ConversationCompletionPublisher.java | 44 +- .../mate/memory/fact/model/FactEntity.java | 6 + .../fact/provider/FactMemoryProvider.java | 7 +- .../memory/fact/query/FactQueryService.java | 22 + .../memory/identity/MemoryOwnerResolver.java | 53 + .../vip/mate/memory/identity/MemoryScope.java | 34 + .../lifecycle/MemoryLifecycleMediator.java | 2 +- .../mate/memory/lifecycle/TurnContext.java | 14 +- .../PostConversationMemoryListener.java | 4 +- .../mate/memory/model/MemoryRecallEntity.java | 6 + .../mate/memory/nudge/MemoryNudgeService.java | 37 +- .../provider/BuiltinMemoryProvider.java | 20 +- .../provider/StructuredMemoryProvider.java | 56 +- .../service/MemorySummarizationService.java | 141 +- .../service/StructuredMemoryService.java | 267 +++- .../vip/mate/memory/spi/MemoryManager.java | 20 +- .../vip/mate/memory/spi/MemoryProvider.java | 15 + .../decorator/MemoryProviderDecorator.java | 1 + .../spi/decorator/MetricsMemoryProvider.java | 7 +- .../decorator/RetryableMemoryProvider.java | 7 +- .../memory/tool/StructuredMemoryTool.java | 36 +- .../mate/memory/tool/UniversalMemoryTool.java | 19 +- .../mate/skill/installer/GitSkillFetcher.java | 52 +- .../SkillWorkspaceAutoConfiguration.java | 12 + .../tool/builtin/DocumentExtractTool.java | 31 +- .../tool/builtin/FileTypeDetectorTool.java | 22 +- .../mate/tool/builtin/GoalManagementTool.java | 36 +- .../mate/tool/builtin/ShellExecuteTool.java | 35 +- .../vip/mate/tool/builtin/WebSearchTool.java | 7 +- .../tool/builtin/WorkspaceMemoryTool.java | 58 +- .../tool/document/GeneratedFileCache.java | 205 ++- .../mate/tool/document/GeneratedFileLink.java | 6 +- .../mate/tool/guard/WorkspacePathGuard.java | 253 +++- .../guard/model/ToolInvocationContext.java | 35 +- .../tool/mcp/service/McpServerService.java | 2 +- .../java/vip/mate/wiki/WikiProperties.java | 43 + .../mate/wiki/controller/WikiController.java | 544 +++++++- .../wiki/event/WikiFactPageUpdatedEvent.java | 11 + .../mate/wiki/event/WikiPageCreatedEvent.java | 11 + .../java/vip/mate/wiki/job/WikiKbConfig.java | 10 + .../vip/mate/wiki/job/WikiKbConfigParser.java | 2 + .../WikiAgentPageTypePermissionEntity.java | 62 + .../wiki/model/WikiKnowledgeBaseEntity.java | 1 + .../wiki/model/WikiPageDependencyEntity.java | 48 + .../vip/mate/wiki/model/WikiPageEntity.java | 51 + .../wiki/model/WikiPageTypeProfileEntity.java | 54 + .../model/WikiPipelineDefinitionEntity.java | 55 + .../wiki/model/WikiPipelineRunEntity.java | 59 + .../wiki/model/WikiPipelineStepRunEntity.java | 51 + .../wiki/pipeline/WikiLlmStepExecutor.java | 75 ++ .../WikiPipelineDefinitionService.java | 164 +++ .../wiki/pipeline/WikiPipelineService.java | 177 +++ .../pipeline/WikiPipelineTriggerListener.java | 39 + .../pipeline/WikiPipelineTriggerService.java | 144 ++ .../wiki/pipeline/WikiSkillStepExecutor.java | 73 ++ .../mate/wiki/pipeline/WikiStepContext.java | 18 + .../mate/wiki/pipeline/WikiStepExecutor.java | 24 + .../mate/wiki/profile/WikiFieldSchema.java | 25 + .../wiki/profile/WikiMetadataValidator.java | 183 +++ .../mate/wiki/profile/WikiPageTypeDef.java | 58 + .../wiki/profile/WikiPageTypeProfile.java | 54 + .../profile/WikiPageTypeProfileService.java | 297 +++++ .../WikiAgentPageTypePermissionMapper.java | 14 + .../repository/WikiPageDependencyMapper.java | 14 + .../mate/wiki/repository/WikiPageMapper.java | 29 + .../repository/WikiPageTypeProfileMapper.java | 14 + .../WikiPipelineDefinitionMapper.java | 14 + .../repository/WikiPipelineRunMapper.java | 14 + .../repository/WikiPipelineStepRunMapper.java | 14 + .../mate/wiki/service/WikiContextService.java | 34 +- .../wiki/service/WikiDependencyService.java | 140 ++ .../service/WikiDirectoryScanService.java | 97 +- .../wiki/service/WikiEnrichmentApplier.java | 66 +- .../service/WikiKnowledgeBaseService.java | 110 +- .../mate/wiki/service/WikiLinkService.java | 326 +++++ .../mate/wiki/service/WikiLintJobService.java | 310 +++++ .../mate/wiki/service/WikiPageService.java | 505 ++++++- .../WikiPageTypePermissionService.java | 245 ++++ .../wiki/service/WikiProcessingService.java | 366 +++++- .../wiki/service/WikiRawMaterialService.java | 104 +- .../wiki/service/WikiSourcePathValidator.java | 91 ++ .../service/WikiSourceWatcherService.java | 94 ++ .../service/WikiStalePropagationListener.java | 37 + .../wiki/source/FilesystemSourceProvider.java | 37 + .../wiki/source/WikiIngestSourceProvider.java | 28 + .../java/vip/mate/wiki/tool/WikiTool.java | 699 ++++++++-- .../workflow/service/WorkflowService.java | 39 +- .../conversation/ConversationService.java | 19 +- .../document/WorkspaceFileService.java | 309 ++++- .../controller/WorkspaceFileController.java | 4 +- .../event/WorkspaceFileChangedEvent.java | 16 + .../document/model/WorkspaceFileEntity.java | 14 + .../src/main/resources/application-mysql.yml | 10 + .../src/main/resources/db/data-en.sql | 20 +- .../src/main/resources/db/data-mysql-en.sql | 20 +- .../src/main/resources/db/data-mysql-zh.sql | 19 +- .../src/main/resources/db/data-zh.sql | 19 +- .../h2/V125__agent_workspace_base_path.sql | 3 + .../h2/V126__agent_binding_disabled_flags.sql | 12 + .../h2/V127__approval_auto_grant.sql | 29 + .../h2/V128__approval_resolution_log.sql | 35 + .../h2/V129__wiki_page_broken_links.sql | 17 + .../migration/h2/V130__agent_primary_kb.sql | 25 + .../migration/h2/V131__claude_48_models.sql | 24 + ...ory_consolidation_cron_tier_discipline.sql | 13 + .../V133__wiki_agent_page_type_permission.sql | 25 + .../h2/V134__wiki_page_type_profile.sql | 43 + .../h2/V135__wiki_layered_knowledge.sql | 29 + .../h2/V136__wiki_pipeline_runtime.sql | 68 + .../migration/h2/V137__memory_owner_scope.sql | 55 + ...V138__rename_search_tool_to_web_search.sql | 7 + .../h2/V139__mcp_default_read_timeout_60s.sql | 8 + .../h2/V140__goal_criteria_checklist.sql | 8 + .../mysql/V125__agent_workspace_base_path.sql | 12 + .../V126__agent_binding_disabled_flags.sql | 33 + .../mysql/V127__approval_auto_grant.sql | 25 + .../mysql/V128__approval_resolution_log.sql | 25 + .../mysql/V129__wiki_page_broken_links.sql | 27 + .../mysql/V130__agent_primary_kb.sql | 45 + .../mysql/V131__claude_48_models.sql | 36 + ...ory_consolidation_cron_tier_discipline.sql | 13 + .../V133__wiki_agent_page_type_permission.sql | 23 + .../mysql/V134__wiki_page_type_profile.sql | 63 + .../mysql/V135__wiki_layered_knowledge.sql | 44 + .../mysql/V136__wiki_pipeline_runtime.sql | 55 + .../mysql/V137__memory_owner_scope.sql | 109 ++ ...V138__rename_search_tool_to_web_search.sql | 7 + .../V139__mcp_default_read_timeout_60s.sql | 8 + .../mysql/V140__goal_criteria_checklist.sql | 16 + .../src/main/resources/db/schema-mysql.sql | 4 +- .../src/main/resources/db/schema.sql | 2 + .../src/main/resources/docs/en/agents.md | 35 + .../src/main/resources/docs/en/ambient-ai.md | 10 +- .../src/main/resources/docs/en/api.md | 1166 +++++++++-------- .../main/resources/docs/en/architecture.md | 6 +- .../src/main/resources/docs/en/channels.md | 11 +- .../src/main/resources/docs/en/chat.md | 50 +- .../src/main/resources/docs/en/console.md | 2 +- .../src/main/resources/docs/en/desktop.md | 3 +- .../src/main/resources/docs/en/doctor.md | 252 +--- .../src/main/resources/docs/en/faq.md | 12 +- .../src/main/resources/docs/en/goals.md | 64 +- .../src/main/resources/docs/en/mcp.md | 4 +- .../src/main/resources/docs/en/memory.md | 55 + .../src/main/resources/docs/en/models.md | 23 +- .../src/main/resources/docs/en/releases.md | 1 + .../src/main/resources/docs/en/security.md | 34 +- .../src/main/resources/docs/en/skills.md | 12 + .../src/main/resources/docs/en/tools.md | 8 +- .../src/main/resources/docs/en/wiki.md | 215 ++- .../src/main/resources/docs/en/workspaces.md | 2 +- .../src/main/resources/docs/zh/agents.md | 35 + .../src/main/resources/docs/zh/ambient-ai.md | 10 +- .../src/main/resources/docs/zh/api.md | 1166 +++++++++-------- .../main/resources/docs/zh/architecture.md | 6 +- .../src/main/resources/docs/zh/channels.md | 11 +- .../src/main/resources/docs/zh/chat.md | 50 +- .../src/main/resources/docs/zh/console.md | 2 +- .../docs/zh/desktop-ui-hot-update.md | 6 +- .../src/main/resources/docs/zh/desktop.md | 3 +- .../src/main/resources/docs/zh/doctor.md | 252 +--- .../src/main/resources/docs/zh/faq.md | 12 +- .../src/main/resources/docs/zh/goals.md | 64 +- .../src/main/resources/docs/zh/mcp.md | 4 +- .../src/main/resources/docs/zh/memory.md | 54 + .../src/main/resources/docs/zh/models.md | 23 +- .../src/main/resources/docs/zh/releases.md | 1 + .../src/main/resources/docs/zh/security.md | 34 +- .../src/main/resources/docs/zh/skills.md | 12 + .../src/main/resources/docs/zh/tools.md | 8 +- .../src/main/resources/docs/zh/wiki.md | 170 ++- .../resources/mapper/ApprovalGrantMapper.xml | 86 ++ .../src/main/resources/messages.properties | 13 +- .../src/main/resources/messages_en.properties | 13 +- .../prompts/memory/summarize-system.txt | 19 +- .../resources/prompts/wiki/analyze-system.txt | 15 +- .../resources/prompts/wiki/analyze-user.txt | 6 + .../prompts/wiki/batch-create-system.txt | 24 +- .../prompts/wiki/batch-create-user.txt | 8 +- .../resources/prompts/wiki/compile-system.txt | 2 +- .../prompts/wiki/create-page-system.txt | 21 +- .../prompts/wiki/create-page-user.txt | 4 +- .../wiki/default-page-type-profile.json | 17 + .../resources/prompts/wiki/digest-system.txt | 7 +- .../resources/prompts/wiki/digest-user.txt | 4 +- .../prompts/wiki/merge-page-system.txt | 13 +- .../resources/prompts/wiki/route-system.txt | 6 + ...entGraphBuilderBasePathResolutionTest.java | 122 ++ .../vip/mate/agent/AgentGraphBuilderIT.java | 80 ++ .../binding/AgentBindingServiceTest.java | 272 ++++ .../context/LoopMessageBudgeterTest.java | 468 +++++++ .../agent/context/ToolPairSanitizerTest.java | 231 ++++ .../agent/graph/MessageNormalizerTest.java | 267 ++++ ...reamingChatHelperNormalizerWiringTest.java | 98 ++ ...ionExecutorNonInteractiveApprovalTest.java | 70 + .../approval/grant/ApprovalGrantPr2IT.java | 127 ++ .../grant/ApprovalGrantResolverTest.java | 254 ++++ .../grant/AutoGrantSafetyFloorTest.java | Bin 0 -> 8034 bytes .../grant/WorkspaceLookupCacheTest.java | 111 ++ .../ApprovalGrantControllerTest.java | 325 +++++ .../ApprovalResolutionLogListenerTest.java | 159 +++ .../ConversationLifecycleListenerTest.java | 69 + .../FeishuConversationIdAlignmentTest.java | 74 ++ .../media/InboundMediaDownloaderTest.java | 135 ++ .../channel/media/MediaTypeSnifferTest.java | 151 +++ .../goal/controller/GoalControllerTest.java | 14 +- .../goal/model/GoalCriteriaCodecTest.java | 113 ++ .../service/GoalEvaluationServiceTest.java | 170 ++- .../goal/service/GoalFollowupServiceTest.java | 34 +- .../mate/goal/service/GoalServiceTest.java | 67 +- ...AnthropicChatModelBuilderClaude48Test.java | 88 ++ .../ProviderRouterSelectPrimaryTest.java | 214 +++ .../lifecycle/LifecycleFlagGuardTest.java | 12 +- .../lifecycle/LifecycleRecallCountIT.java | 13 +- .../MemoryLifecycleMediatorTest.java | 12 +- ...orySummarizationStructuredRoutingTest.java | 97 ++ .../service/StructuredMemoryPrefetchTest.java | 143 ++ .../tool/builtin/GoalManagementToolTest.java | 9 +- .../GeneratedFileCachePersistenceTest.java | 83 ++ .../document/GeneratedFileCacheScrubTest.java | 8 +- .../guard/WorkspacePathGuardShellTest.java | 318 +++++ .../wiki/WikiDomainIntegrationE2ETest.java | 153 +++ .../pipeline/WikiLlmStepExecutorTest.java | 56 + .../WikiPipelineDefinitionServiceE2ETest.java | 103 ++ .../pipeline/WikiPipelineServiceE2ETest.java | 134 ++ .../WikiPipelineTriggerListenerTest.java | 36 + .../WikiPipelineTriggerServiceE2ETest.java | 123 ++ .../pipeline/WikiSkillStepExecutorTest.java | 81 ++ .../profile/WikiMetadataValidatorTest.java | 137 ++ .../WikiPageTypeProfileServiceE2ETest.java | 106 ++ .../WikiPageTypeProfileServiceTest.java | 149 +++ .../WikiPageDependencyMapperE2ETest.java | 71 + .../WikiPageTypeProfileMapperE2ETest.java | 95 ++ .../WikiPipelineRunMapperE2ETest.java | 62 + .../service/WikiCascadeRegressionE2ETest.java | 230 ++++ .../wiki/service/WikiContextServiceTest.java | 82 ++ .../service/WikiDependencyServiceE2ETest.java | 97 ++ .../WikiEnrichmentApplierPhase5Test.java | 129 ++ .../service/WikiKnowledgeBaseServiceTest.java | 175 ++- .../service/WikiLinkServiceCascadeTest.java | 120 ++ .../wiki/service/WikiPageMetadataE2ETest.java | 66 + .../wiki/service/WikiPageServiceTest.java | 4 +- .../WikiPageTypePermissionServiceTest.java | 192 +++ .../service/WikiProcessingFallbackTest.java | 4 +- .../WikiProcessingServiceLazyTest.java | 4 +- .../service/WikiScanSizeGuardE2ETest.java | 60 + .../service/WikiSourcePathValidatorTest.java | 81 ++ .../WikiSourceWatcherServiceE2ETest.java | 112 ++ .../WikiStalePropagationListenerTest.java | 38 + .../wiki/tool/WikiToolKbNameRoutingTest.java | 290 ++++ .../wiki/tool/WikiToolLayerFilterTest.java | 41 + .../wiki/tool/WikiToolPermissionTest.java | 232 ++++ .../wiki/tool/WikiToolSpringBindingTest.java | 169 +++ .../workflow/api/WorkflowControllerTest.java | 17 + .../document/WorkspaceMemorySearchTest.java | 81 +- .../e2e/wiki-link-overhaul-verification.md | 1061 +++++++++++++++ mateclaw-ui/package.json | 8 +- mateclaw-ui/pnpm-lock.yaml | 316 ++++- mateclaw-ui/src/App.vue | 13 + mateclaw-ui/src/api/index.ts | 143 +- mateclaw-ui/src/components/chat/ChatInput.vue | 208 ++- .../components/chat/ExecutionDetailDialog.vue | 251 ++++ mateclaw-ui/src/components/chat/JsonView.vue | 95 ++ .../src/components/chat/PlanStepsPanel.vue | 58 +- .../src/components/chat/SkillSlashMenu.vue | 342 +++++ .../src/components/chat/ToolCallSegment.vue | 67 +- .../src/components/goal/GoalAvatarRing.vue | 97 +- .../components/goal/GoalSetInlinePrompt.vue | 3 + .../composables/__tests__/wikilink.test.ts | 237 ++++ mateclaw-ui/src/composables/chat/useStream.ts | 2 +- .../composables/useGlobalFileDownloadClick.ts | 96 ++ .../src/composables/useGlobalWikilinkClick.ts | 108 ++ .../src/composables/useMarkdownRenderer.ts | 59 +- mateclaw-ui/src/composables/wikilink.ts | 245 ++++ mateclaw-ui/src/i18n/locales/en-US.ts | 227 +++- mateclaw-ui/src/i18n/locales/zh-CN.ts | 227 +++- mateclaw-ui/src/router/index.ts | 6 + mateclaw-ui/src/stores/useGoalStore.ts | 38 +- mateclaw-ui/src/stores/useWikiStore.ts | 196 ++- mateclaw-ui/src/types/index.ts | 105 ++ mateclaw-ui/src/views/Agents.vue | 285 +++- mateclaw-ui/src/views/ChatConsole.vue | 183 ++- .../views/Memory/components/MemoryBrowser.vue | 8 +- .../Security/AutoApproveGrants/index.vue | 849 ++++++++++++ mateclaw-ui/src/views/Security/Layout.vue | 6 + .../Wiki/components/WikiAdvancedPanel.vue | 511 ++++++++ .../Wiki/components/WikiBrokenLinksBanner.vue | 164 +++ .../Wiki/components/WikiBrokenLinksPanel.vue | 166 +++ .../views/Wiki/components/WikiPageViewer.vue | 102 +- .../views/Wiki/components/WikiWorkspace.vue | 26 + mateclaw-ui/src/views/Wiki/index.vue | 46 +- mateclaw-ui/src/views/layout/MainLayout.vue | 145 +- mateclaw-ui/src/views/mcp/McpFormModal.vue | 2 +- mateclaw-ui/src/views/mcp/types.ts | 2 +- mateclaw-ui/vitest.config.ts | 21 + pom.xml | 6 +- 361 files changed, 30472 insertions(+), 3047 deletions(-) create mode 100644 mateclaw-server/src/main/java/vip/mate/agent/context/LoopBudgetConfig.java create mode 100644 mateclaw-server/src/main/java/vip/mate/agent/context/LoopMessageBudgeter.java create mode 100644 mateclaw-server/src/main/java/vip/mate/agent/context/ToolPairSanitizer.java create mode 100644 mateclaw-server/src/main/java/vip/mate/agent/graph/MessageNormalizer.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/event/ApprovalResolutionEvent.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveAuditLogger.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveResult.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/AutoGrantSafetyFloor.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/WorkspaceLookupCache.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/controller/ApprovalGrantController.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalGrant.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalResolutionLog.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListener.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ConversationLifecycleListener.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalGrantMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalResolutionLogMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantResolver.java create mode 100644 mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/channel/media/InboundMediaDownloader.java create mode 100644 mateclaw-server/src/main/java/vip/mate/channel/media/MediaTypeSniffer.java create mode 100644 mateclaw-server/src/main/java/vip/mate/goal/model/GoalChecklistVerdict.java create mode 100644 mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaCodec.java create mode 100644 mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaDraft.java create mode 100644 mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriterion.java create mode 100644 mateclaw-server/src/main/java/vip/mate/goal/model/GoalResponse.java create mode 100644 mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryOwnerResolver.java create mode 100644 mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryScope.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/event/WikiFactPageUpdatedEvent.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/event/WikiPageCreatedEvent.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/model/WikiAgentPageTypePermissionEntity.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageDependencyEntity.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageTypeProfileEntity.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineDefinitionEntity.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineRunEntity.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineStepRunEntity.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiLlmStepExecutor.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListener.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiSkillStepExecutor.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepContext.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepExecutor.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiFieldSchema.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiMetadataValidator.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeDef.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfile.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfileService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiAgentPageTypePermissionMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageDependencyMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageTypeProfileMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineDefinitionMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineRunMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineStepRunMapper.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDependencyService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLinkService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLintJobService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageTypePermissionService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourcePathValidator.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourceWatcherService.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/service/WikiStalePropagationListener.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/source/FilesystemSourceProvider.java create mode 100644 mateclaw-server/src/main/java/vip/mate/wiki/source/WikiIngestSourceProvider.java create mode 100644 mateclaw-server/src/main/java/vip/mate/workspace/document/event/WorkspaceFileChangedEvent.java create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V125__agent_workspace_base_path.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V126__agent_binding_disabled_flags.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V127__approval_auto_grant.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V128__approval_resolution_log.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V129__wiki_page_broken_links.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V130__agent_primary_kb.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V131__claude_48_models.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V132__memory_consolidation_cron_tier_discipline.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V133__wiki_agent_page_type_permission.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V134__wiki_page_type_profile.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V135__wiki_layered_knowledge.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V136__wiki_pipeline_runtime.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V137__memory_owner_scope.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V138__rename_search_tool_to_web_search.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V139__mcp_default_read_timeout_60s.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/h2/V140__goal_criteria_checklist.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V125__agent_workspace_base_path.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V126__agent_binding_disabled_flags.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V127__approval_auto_grant.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V128__approval_resolution_log.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V129__wiki_page_broken_links.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V130__agent_primary_kb.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V131__claude_48_models.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V132__memory_consolidation_cron_tier_discipline.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V133__wiki_agent_page_type_permission.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V134__wiki_page_type_profile.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V135__wiki_layered_knowledge.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V136__wiki_pipeline_runtime.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V137__memory_owner_scope.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V138__rename_search_tool_to_web_search.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V139__mcp_default_read_timeout_60s.sql create mode 100644 mateclaw-server/src/main/resources/db/migration/mysql/V140__goal_criteria_checklist.sql create mode 100644 mateclaw-server/src/main/resources/mapper/ApprovalGrantMapper.xml create mode 100644 mateclaw-server/src/main/resources/prompts/wiki/default-page-type-profile.json create mode 100644 mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderBasePathResolutionTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderIT.java create mode 100644 mateclaw-server/src/test/java/vip/mate/agent/context/LoopMessageBudgeterTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/agent/context/ToolPairSanitizerTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/agent/graph/MessageNormalizerTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/agent/graph/NodeStreamingChatHelperNormalizerWiringTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/agent/graph/executor/ToolExecutionExecutorNonInteractiveApprovalTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantPr2IT.java create mode 100644 mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantResolverTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/approval/grant/AutoGrantSafetyFloorTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/approval/grant/WorkspaceLookupCacheTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/approval/grant/controller/ApprovalGrantControllerTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListenerTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ConversationLifecycleListenerTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/channel/feishu/FeishuConversationIdAlignmentTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/channel/media/InboundMediaDownloaderTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/channel/media/MediaTypeSnifferTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/goal/model/GoalCriteriaCodecTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilderClaude48Test.java create mode 100644 mateclaw-server/src/test/java/vip/mate/llm/routing/ProviderRouterSelectPrimaryTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/memory/service/MemorySummarizationStructuredRoutingTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/memory/service/StructuredMemoryPrefetchTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCachePersistenceTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/tool/guard/WorkspacePathGuardShellTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/WikiDomainIntegrationE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiLlmStepExecutorTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionServiceE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineServiceE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListenerTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerServiceE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiSkillStepExecutorTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiMetadataValidatorTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageDependencyMapperE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageTypeProfileMapperE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPipelineRunMapperE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiCascadeRegressionE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiDependencyServiceE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiEnrichmentApplierPhase5Test.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiLinkServiceCascadeTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageMetadataE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageTypePermissionServiceTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiScanSizeGuardE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourcePathValidatorTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourceWatcherServiceE2ETest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/service/WikiStalePropagationListenerTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolKbNameRoutingTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolLayerFilterTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolPermissionTest.java create mode 100644 mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolSpringBindingTest.java create mode 100644 mateclaw-server/src/test/resources/e2e/wiki-link-overhaul-verification.md create mode 100644 mateclaw-ui/src/components/chat/ExecutionDetailDialog.vue create mode 100644 mateclaw-ui/src/components/chat/JsonView.vue create mode 100644 mateclaw-ui/src/components/chat/SkillSlashMenu.vue create mode 100644 mateclaw-ui/src/composables/__tests__/wikilink.test.ts create mode 100644 mateclaw-ui/src/composables/useGlobalFileDownloadClick.ts create mode 100644 mateclaw-ui/src/composables/useGlobalWikilinkClick.ts create mode 100644 mateclaw-ui/src/composables/wikilink.ts create mode 100644 mateclaw-ui/src/views/Security/AutoApproveGrants/index.vue create mode 100644 mateclaw-ui/src/views/Wiki/components/WikiAdvancedPanel.vue create mode 100644 mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksBanner.vue create mode 100644 mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksPanel.vue create mode 100644 mateclaw-ui/vitest.config.ts diff --git a/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java b/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java index 5d3648a7..f9e16cc2 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/AgentGraphBuilder.java @@ -56,6 +56,8 @@ import vip.mate.channel.web.ChatStreamTracker; import vip.mate.wiki.service.WikiContextService; import java.lang.reflect.Field; +import java.nio.file.Path; +import java.nio.file.Paths; import java.util.ArrayList; import java.util.LinkedHashMap; import java.util.List; @@ -125,6 +127,18 @@ public class AgentGraphBuilder { private final vip.mate.goal.service.GoalFollowupService goalFollowupService; private final vip.mate.goal.config.GoalProperties goalProperties; + /** + * Auto-grant resolver wired into the executor so an active + * {@code mate_approval_grant} row can skip {@code createPending()} for matching + * tool calls. Together with {@link #workspaceLookupCache}, these two deps form + * the auto-grant entry point; the executor's null-guard turns the feature off + * cleanly if either is missing. + */ + private final vip.mate.approval.grant.service.ApprovalGrantResolver approvalGrantResolver; + + /** Conversation→workspaceId lookup cache; see {@link #approvalGrantResolver}. */ + private final vip.mate.approval.grant.WorkspaceLookupCache workspaceLookupCache; + /** * Optional audit pipeline. Setter injection (rather than a constructor * parameter) keeps existing constructor-based wiring + tests intact. @@ -166,6 +180,34 @@ public class AgentGraphBuilder { return modelConfigService.resolveModel(agentModelName); } + /** + * True iff the caller passed a complete (provider, model) pin AND that + * pair resolves to an enabled model row. Used by {@link #build} to decide + * whether the explicit pick should bypass capability-driven routing. + */ + private boolean pinResolvesToEnabledModel(String modelProvider, String modelName) { + if (modelProvider == null || modelProvider.isBlank() + || modelName == null || modelName.isBlank()) { + return false; + } + try { + return modelConfigService.findEnabledModel(modelProvider, modelName) != null; + } catch (Exception e) { + return false; + } + } + + /** + * True when the Agent declared its own modelName and that name resolved to + * a real enabled row (rather than silently falling back to the system default). + */ + private boolean agentModelOverrideResolved(AgentEntity entity, ModelConfigEntity resolved) { + if (entity == null || resolved == null) return false; + String agentModelName = entity.getModelName(); + if (agentModelName == null || agentModelName.isBlank()) return false; + return agentModelName.equalsIgnoreCase(resolved.getModelName()); + } + /** * 根据 AgentEntity 构建完整的 Agent 实例。 * @@ -187,6 +229,17 @@ public class AgentGraphBuilder { Set boundTools = agentBindingService.getEffectiveToolNames(entity.getId()); toolSet = toolSet.withAllowedToolsOnly(boundTools); // null = 全局默认 + // Issue #184 follow-up: an agent that opted out of skills must not be + // able to circle back and discover/load them via the meta tools. Strip + // the skill-discovery surface (listAvailableSkills / load_skill / + // readSkillFile / runSkillScript / listSkillFiles) here. This runs as a + // separate deny layer so the allowlist matrix in getEffectiveToolNames + // stays untouched — in particular, the (skillsDisabled, !toolsDisabled, + // no tool bindings) cell still returns null so non-skill global tools + // continue to flow through. + toolSet = toolSet.withDeniedToolsFiltered( + agentBindingService.getSkillDiscoveryDeniedTools(entity.getId())); + // Escape hatch: drop the load_skill meta tool entirely when disabled, so // it isn't advertised regardless of binding (the catalog guidance falls // back to readSkillFile — see SkillRuntimeService). @@ -199,22 +252,37 @@ public class AgentGraphBuilder { // looks up enabled-only models and silently degrades an unmatched pin / // override to the global default, preserving the legacy behaviour for // Agents and conversations without an explicit choice. - // providerRouter.selectPrimary below may still swap this for a model - // that satisfies a bound skill's requires-model constraint. ModelConfigEntity globalDefault; + boolean explicitPinHonoured; + boolean agentOverrideHonoured; try { + explicitPinHonoured = pinResolvesToEnabledModel(modelProvider, modelName); globalDefault = resolveRuntimeBaseModel(modelProvider, modelName, entity.getModelName()); + agentOverrideHonoured = !explicitPinHonoured + && agentModelOverrideResolved(entity, globalDefault); } catch (Exception e) { throw new MateClawException("err.agent.no_default_model", "无法构建 Agent：请先在「设置 → 模型」中配置并启用默认模型"); } ModelConfigEntity runtimeModel; - try { - runtimeModel = providerRouter.selectPrimary(entity.getId(), globalDefault); - if (runtimeModel == null) runtimeModel = globalDefault; - } catch (Exception e) { - log.debug("[ProviderRouter] primary selection failed, falling back to global default: {}", - e.getMessage()); + if (explicitPinHonoured || agentOverrideHonoured) { + // The caller (admin UI / chat console) handed us a concrete + // (provider, model) pin and it points to an enabled row. Honour + // it verbatim — running providerRouter.selectPrimary here would + // silently swap to a different model whenever a bound skill + // advertised a capability gap, which is exactly the "I switched + // model but the agent kept using the old one" surface. The + // diagnostic below still surfaces capability gaps in the logs + // so operators can see if the pinned model misses a need. runtimeModel = globalDefault; + } else { + try { + runtimeModel = providerRouter.selectPrimary(entity.getId(), globalDefault); + if (runtimeModel == null) runtimeModel = globalDefault; + } catch (Exception e) { + log.debug("[ProviderRouter] primary selection failed, falling back to global default: {}", + e.getMessage()); + runtimeModel = globalDefault; + } } // Even after the upgrade, log a WARN when the chosen primary // still doesn't satisfy needs (e.g. no preferred provider was @@ -358,18 +426,41 @@ public class AgentGraphBuilder { agent.topP = runtimeModel.getTopP(); agent.toolCallingEnabled = toolCallingEnabled; - // 查找工作区活动目录 + // Agent-level override takes priority; a relative override is resolved + // under the workspace basePath so admins can express agent directories + // relative to the workspace root (matching the UI hint). + String workspaceBase = null; if (entity.getWorkspaceId() != null) { try { var workspace = workspaceService.getById(entity.getWorkspaceId()); - if (workspace != null && workspace.getBasePath() != null && !workspace.getBasePath().isBlank()) { - agent.workspaceBasePath = workspace.getBasePath(); - log.info("Agent {} bound to workspace basePath: {}", entity.getName(), agent.workspaceBasePath); + if (workspace != null) { + workspaceBase = workspace.getBasePath(); } } catch (Exception e) { - log.warn("Failed to lookup workspace basePath for agent {}: {}", entity.getName(), e.getMessage()); + log.warn("Failed to lookup workspace basePath for agent {}: {}", + entity.getName(), e.getMessage()); } } + String resolvedBase; + try { + resolvedBase = resolveAgentBasePath(entity.getWorkspaceBasePath(), workspaceBase); + } catch (IllegalArgumentException e) { + // Override violates the workspace-scoping rule (e.g. admin tried to + // set an absolute path outside the workspace root). Fall back to + // inheriting the workspace basePath so chat stays available, but + // surface the violation in logs so the admin can fix it. + log.warn("Agent {} workspaceBasePath override rejected, falling back to workspace: {}", + entity.getName(), e.getMessage()); + resolvedBase = workspaceBase; + } + if (resolvedBase != null && !resolvedBase.isBlank()) { + agent.workspaceBasePath = resolvedBase; + boolean fromOverride = entity.getWorkspaceBasePath() != null + && !entity.getWorkspaceBasePath().isBlank() + && resolvedBase.equals(entity.getWorkspaceBasePath()); + log.info("Agent {} basePath = {} (source: {})", + entity.getName(), resolvedBase, fromOverride ? "agent-override" : "workspace"); + } log.info("Built agent instance: {} (type={}, protocol={}, tools={}, toolCallingEnabled={})", entity.getName(), entity.getAgentType(), protocol.getId(), @@ -445,7 +536,10 @@ public class AgentGraphBuilder { streamTracker, fallbackChain, llmCacheMetricsAggregator, providerHealthTracker, primaryModelConfig != null ? primaryModelConfig.getProvider() : null, providerPool); - ToolExecutionExecutor executor = new ToolExecutionExecutor(toolSet, toolGuardService, approvalService, streamTracker, toolTimeoutProperties, toolResultStorage, toolConcurrencyRegistry); + ToolExecutionExecutor executor = new ToolExecutionExecutor( + toolSet, toolGuardService, approvalService, streamTracker, + toolTimeoutProperties, toolResultStorage, toolConcurrencyRegistry, + workspaceLookupCache, approvalGrantResolver); // Issue #46: enable skill-aware "Tool not found" hint so when the // LLM mis-calls a skill name as a tool, the response tells it // the right invocation pattern instead of a dead-end error. @@ -687,7 +781,10 @@ public class AgentGraphBuilder { streamTracker, fallbackChain, llmCacheMetricsAggregator, providerHealthTracker, primaryModelConfig != null ? primaryModelConfig.getProvider() : null, providerPool); - ToolExecutionExecutor executor = new ToolExecutionExecutor(toolSet, toolGuardService, approvalService, streamTracker, toolTimeoutProperties, toolResultStorage, toolConcurrencyRegistry); + ToolExecutionExecutor executor = new ToolExecutionExecutor( + toolSet, toolGuardService, approvalService, streamTracker, + toolTimeoutProperties, toolResultStorage, toolConcurrencyRegistry, + workspaceLookupCache, approvalGrantResolver); // Issue #46: enable skill-aware "Tool not found" hint so when the // LLM mis-calls a skill name as a tool, the response tells it // the right invocation pattern instead of a dead-end error. @@ -1147,6 +1244,54 @@ public class AgentGraphBuilder { return reordered; } + /** + * Resolve the effective working directory for an agent. + *

Precedence: + *

    + *
  1. When the agent-level override is set, it wins.
    2. + *
  2. An absolute override is used verbatim, but only when it sits + * inside the workspace basePath (or when the workspace has no + * basePath of its own). An absolute path that points outside a + * configured workspace root is rejected — otherwise a less-trusted + * user with agent-edit access could set + * {@code workspaceBasePath="/"} and bypass workspace scoping.
    3. + *
  3. A relative override is resolved under the workspace basePath + * when the workspace has one, matching the UI hint that agent paths + * are relative to the workspace root.
    4. + *
  4. A relative override with no workspace basePath is used as-is + * (resolves against the JVM working directory at file-tool time).
    5. + *
  5. With no override, the workspace basePath is inherited verbatim; + * returns {@code null} when neither side has a value.
    6. + *
+ * + * @throws IllegalArgumentException when an absolute override escapes the + * workspace root + */ + static String resolveAgentBasePath(String agentOverride, String workspaceBase) { + boolean hasOverride = agentOverride != null && !agentOverride.isBlank(); + boolean hasWorkspace = workspaceBase != null && !workspaceBase.isBlank(); + if (!hasOverride) { + return hasWorkspace ? workspaceBase : null; + } + Path overridePath = Paths.get(agentOverride); + if (overridePath.isAbsolute()) { + if (hasWorkspace) { + Path wsRoot = Paths.get(workspaceBase).toAbsolutePath().normalize(); + Path absOverride = overridePath.toAbsolutePath().normalize(); + if (!absOverride.startsWith(wsRoot)) { + throw new IllegalArgumentException( + "Agent workspaceBasePath override must be inside the workspace root: " + + absOverride + " is not under " + wsRoot); + } + } + return agentOverride; + } + if (hasWorkspace) { + return Paths.get(workspaceBase).resolve(agentOverride).toString(); + } + return agentOverride; + } + /** * Finds the first enabled chat model whose provider is fully configured. * Used as a fallback when the default model's provider is not available. @@ -1245,6 +1390,18 @@ public class AgentGraphBuilder { Use workspace memory tools (MEMORY.md, daily notes) for long-form narrative notes. Use structured memory tools for key-value facts the system can query efficiently. + ## Memory vs Knowledge Base Precedence + When a question is about the user themselves — who they are, their current + project, its name/codename, tech stack, goals, metrics, budget, team, or what + they are working on — your recalled memory (the block plus + structured/workspace memory) is the authoritative source. Knowledge-base / wiki + pages are reference material that may describe unrelated, example, or upstream + projects; do NOT treat a KB page's subject as the user's own project. Only read + the knowledge base for explicit reference lookups, never to decide what the + user's project is. If memory and a KB page disagree about the user's project, + trust memory. If memory has no answer, say you do not have it rather than + adopting a KB article as the user's project. + ## Session Search - `session_search(agentId, currentConversationId, mode, query, limit)` — search conversation history - mode="recent": list recent conversations (titles, times, message counts) diff --git a/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java b/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java index cd92cf83..e7b9c159 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/AgentService.java @@ -25,6 +25,7 @@ import vip.mate.workspace.conversation.model.ConversationEntity; import vip.mate.workspace.conversation.repository.ConversationMapper; import java.util.List; +import java.time.Duration; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; import java.util.function.Function; @@ -48,6 +49,7 @@ public class AgentService { private final MemoryRecallTracker memoryRecallTracker; private final MemoryLifecycleMediator lifecycleMediator; private final MemoryProperties memoryProperties; + private final vip.mate.memory.identity.MemoryOwnerResolver memoryOwnerResolver; /** Read-only lookup of a conversation's pinned model. Mapper (not service) * to keep this a leaf dependency with no risk of a bean cycle. */ private final ConversationMapper conversationMapper; @@ -214,6 +216,20 @@ public class AgentService { agentInstances.remove(agentId); } + /** + * Invalidate the cached agent instance whenever one of its workspace files + * changes. The system prompt (which embeds MEMORY.md / PROFILE.md / structured + * memory) is baked into the cached instance at build time, so memory edits made + * via tools, consolidation, or cleanup would otherwise stay invisible until an + * agent config change or restart. Rebuilding on the next turn picks them up. + */ + @org.springframework.context.event.EventListener + public void onWorkspaceFileChanged(vip.mate.workspace.document.event.WorkspaceFileChangedEvent event) { + if (event.agentId() != null) { + agentInstances.remove(event.agentId()); + } + } + // ==================== 运行时入口 ==================== public String chat(Long agentId, String message, String conversationId) { @@ -237,6 +253,26 @@ public class AgentService { } } + /** + * Sync chat that also captures token usage and runtime model attribution + * from the agent graph's {@code _usage_final} event. Equivalent to + * subscribing to {@link #chatStructuredStream} and joining all content + * deltas — produces the same assistant text as {@link #chat} but exposes + * the usage figures so callers can persist them on the assistant message. + * + *

Prefer this entry over {@link #chat} for any path that writes the + * reply to {@code mate_message} (sync HTTP endpoint, voice WebSocket, + * cron task, post-approval replay); the plain {@link #chat} stays as the + * thin wrapper for fire-and-forget invocations where usage is not needed. + */ + public ChatResult chatWithUsage(Long agentId, String message, String conversationId) { + return chatWithUsage(agentId, message, conversationId, ChatOrigin.EMPTY); + } + + public ChatResult chatWithUsage(Long agentId, String message, String conversationId, ChatOrigin origin) { + return collectChatResult(chatStructuredStream(agentId, message, conversationId, "", null, origin)); + } + public Flux chatStream(Long agentId, String message, String conversationId) { return chatStream(agentId, message, conversationId, ChatOrigin.EMPTY); } @@ -362,6 +398,42 @@ public class AgentService { } } + /** + * Replay-after-approval that also captures token usage and runtime model + * attribution. Mirrors {@link #chatWithUsage} for the + * approval-resumption path used by {@code ChannelMessageRouter}. + */ + public ChatResult chatWithReplayWithUsage(Long agentId, String userMessage, String conversationId, + String toolCallPayload, ChatOrigin origin) { + return collectChatResult(chatWithReplayStream(agentId, userMessage, conversationId, + toolCallPayload, "", origin != null ? origin : ChatOrigin.EMPTY)); + } + + /** + * Subscribe to a structured stream and collapse it into a single + * {@link ChatResult}: append all content deltas, capture the trailing + * {@code _usage_final} event for token and model attribution. + */ + private ChatResult collectChatResult(Flux stream) { + StringBuilder content = new StringBuilder(); + final int[] usage = {0, 0}; + final String[] modelInfo = {null, null}; + stream.doOnNext(delta -> { + if (delta.isEvent() && "_usage_final".equals(delta.eventType())) { + Map data = delta.eventData(); + usage[0] = ((Number) data.getOrDefault("promptTokens", 0)).intValue(); + usage[1] = ((Number) data.getOrDefault("completionTokens", 0)).intValue(); + Object model = data.get("runtimeModelName"); + Object provider = data.get("runtimeProviderId"); + if (model != null) modelInfo[0] = model.toString(); + if (provider != null) modelInfo[1] = provider.toString(); + } else if (delta.content() != null) { + content.append(delta.content()); + } + }).blockLast(Duration.ofMinutes(10)); + return new ChatResult(content.toString(), usage[0], usage[1], modelInfo[0], modelInfo[1]); + } + /** * 带工具重放的流式调用（Web 端审批通过后使用，通过 SSE 推送结果） */ @@ -447,7 +519,8 @@ public class AgentService { if (!memoryProperties.isLifecycleMediatorEnabled()) { return invoke.apply(message, conversationId); } - TurnContext ctx = new TurnContext(agentId, conversationId, conversationId, 0, message); + String ownerKey = memoryOwnerResolver.resolve(ChatOriginHolder.get()); + TurnContext ctx = new TurnContext(agentId, conversationId, conversationId, 0, message, ownerKey); String memoryContext = lifecycleMediator.beforeLlmCall(ctx); // Inject memory context into the user message (RFC-037 §3.3) String enrichedMessage = injectMemoryContext(message, memoryContext); @@ -469,7 +542,8 @@ public class AgentService { if (!memoryProperties.isLifecycleMediatorEnabled()) { return invoke.apply(message, conversationId); } - TurnContext ctx = new TurnContext(agentId, conversationId, conversationId, 0, message); + String ownerKey = memoryOwnerResolver.resolve(ChatOriginHolder.get()); + TurnContext ctx = new TurnContext(agentId, conversationId, conversationId, 0, message, ownerKey); String memoryContext = lifecycleMediator.beforeLlmCall(ctx); String enrichedMessage = injectMemoryContext(message, memoryContext); StringBuilder reply = new StringBuilder(); @@ -623,4 +697,23 @@ public class AgentService { return thinking != null ? thinking.length() : 0; } } + + // ==================== ChatResult ==================== + + /** + * Sync chat result carrying the assistant reply alongside the usage + * attribution that the streaming path exposes via the {@code _usage_final} + * event. Use this when callers need to persist {@code promptTokens} / + * {@code completionTokens} / {@code runtimeModel} / {@code runtimeProvider} + * on the assistant message row but cannot subscribe to the structured + * stream directly (cron tasks, sync HTTP endpoints, voice WebSocket, + * post-approval replays). + */ + public record ChatResult(String content, int promptTokens, int completionTokens, + String runtimeModel, String runtimeProvider) { + + public static ChatResult contentOnly(String content) { + return new ChatResult(content != null ? content : "", 0, 0, null, null); + } + } } diff --git a/mateclaw-server/src/main/java/vip/mate/agent/binding/controller/AgentBindingController.java b/mateclaw-server/src/main/java/vip/mate/agent/binding/controller/AgentBindingController.java index 31bec483..a4172b93 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/binding/controller/AgentBindingController.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/binding/controller/AgentBindingController.java @@ -52,8 +52,12 @@ public class AgentBindingController { verifyAgentWorkspace(agentId, workspaceId); bindingService.setSkillBindings(agentId, skillIds); agentService.invalidateAgentCache(agentId); + // The Vue client always sends an array, but a non-Vue caller (curl / + // SDK) can POST a body of just `null`, which Spring binds to a null + // list. The service tolerates that — guard the audit message too. + int count = skillIds == null ? 0 : skillIds.size(); auditEventService.record("UPDATE", "AGENT_SKILL", String.valueOf(agentId), - "skills=" + skillIds.size(), null); + "skills=" + count, null); return R.ok(); } @@ -98,12 +102,14 @@ public class AgentBindingController { verifyAgentWorkspace(agentId, workspaceId); bindingService.setToolBindings(agentId, toolNames); agentService.invalidateAgentCache(agentId); + // Same null-safety rationale as setSkills above. + int count = toolNames == null ? 0 : toolNames.size(); auditEventService.record("UPDATE", "AGENT_TOOL", String.valueOf(agentId), - "tools=" + toolNames.size(), null); + "tools=" + count, null); return R.ok(); } - // ==================== Provider Preferences (RFC-009 PR-3) ==================== + // ==================== Provider Preferences ==================== @Operation(summary = "获取 Agent 的偏好 Provider 顺序") @GetMapping("/provider-preferences") diff --git a/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java b/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java index da7fe756..834d9a62 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/binding/service/AgentBindingService.java @@ -118,14 +118,33 @@ public class AgentBindingService implements AgentBindingResolver { } /** - * 获取 Agent 绑定的 enabled skill ID 集合。 - * 返回 null 表示该 agent 没有自定义绑定（使用全局默认）。 + * Effective bound skill IDs for the agent. Three return states: + * + *

    + *
  • {@code null} — no binding rows exist and the agent has not opted + * out of skills. Caller treats this as "no agent-level restriction; + * inherit every globally-enabled skill" (legacy default).
    • + *
  • {@code Set.of()} — either {@code skills_disabled=true} on the agent, + * or binding rows exist but none are {@code enabled=true}. Caller + * treats this as "this agent is explicitly scoped to zero skills" — + * no SKILL.md catalog injection, no skill-expanded tools.
    • + *
  • non-empty set — the explicit allowlist.
    • + *
+ * + *

The {@code skills_disabled} flag takes precedence over row count, so + * a stale (disabled flag + leftover rows) row combination still surfaces + * as "no skills". The {@code setSkillBindings} / {@code bindSkill} writers + * keep these in sync by auto-clearing the flag when a non-empty row set is + * persisted. */ @Override public Set getBoundSkillIds(Long agentId) { + if (isSkillsDisabled(agentId)) { + return Set.of(); + } List bindings = listSkillBindings(agentId); if (bindings.isEmpty()) { - return null; // 无绑定 → 全局默认 + return null; // no rows → inherit global default } return bindings.stream() .filter(b -> Boolean.TRUE.equals(b.getEnabled())) @@ -135,7 +154,11 @@ public class AgentBindingService implements AgentBindingResolver { public AgentSkillBinding bindSkill(Long agentId, Long skillId) { requireSameWorkspace(agentId, skillId); - // 检查是否已绑定 + // Adding any skill binding is a concrete commitment — the operator + // wants this skill on the agent, which contradicts an opt-out flag. + // Clear the flag here so the data layer never holds a + // "skills_disabled=true + binding rows" contradiction. + clearSkillsDisabledFlag(agentId); AgentSkillBinding existing = skillBindingMapper.selectOne( new LambdaQueryWrapper() .eq(AgentSkillBinding::getAgentId, agentId) @@ -161,7 +184,14 @@ public class AgentBindingService implements AgentBindingResolver { } /** - * 批量设置 Agent 的 skill 绑定（替换模式） + * Replace the agent's skill binding set. + * + *

Side effect: when {@code skillIds} contains at least one entry, + * the {@code skills_disabled} flag on the agent is auto-cleared. A + * non-empty save is a concrete commitment to those skills, so the + * data layer never holds a {@code disabled=true} + binding rows + * contradiction. An empty / null save does not + * touch the flag — the caller (UI toggle) owns that bit. */ public void setSkillBindings(Long agentId, List skillIds) { // Validate every incoming skill BEFORE touching the binding rows; @@ -173,11 +203,17 @@ public class AgentBindingService implements AgentBindingResolver { requireSameWorkspace(agentId, skillId); } } - // 删除旧绑定 + // Auto-clear the flag only when an explicit non-empty binding is + // being committed. An empty save is ambiguous — the UI may be + // either "uncheck everything" (keep flag as-is so the toggle + // remains the source of truth) or just "no rows" (legacy). We let + // the writer of skills_disabled (typically the agent PUT) own that. + if (skillIds != null && !skillIds.isEmpty()) { + clearSkillsDisabledFlag(agentId); + } skillBindingMapper.delete( new LambdaQueryWrapper() .eq(AgentSkillBinding::getAgentId, agentId)); - // 创建新绑定 if (skillIds != null) { for (Long skillId : skillIds) { AgentSkillBinding binding = new AgentSkillBinding(); @@ -374,13 +410,26 @@ public class AgentBindingService implements AgentBindingResolver { } /** - * 获取 Agent 绑定的 enabled tool name 集合。 - * 返回 null 表示该 agent 没有自定义绑定（使用全局默认）。 + * Effective bound tool names for the agent. Mirrors the three-state + * contract of {@link #getBoundSkillIds}: + * + *

    + *
  • {@code null} — no binding rows and {@code tools_disabled=false}. + * Caller defers to the global default tool set.
    • + *
  • {@code Set.of()} — {@code tools_disabled=true}, or all rows are + * {@code enabled=false}. The agent is explicitly scoped to no + * user-pickable tools (system-level memory primitives still flow + * through {@link #getEffectiveToolNames}).
    • + *
  • non-empty set — the explicit allowlist.
    • + *
*/ public Set getBoundToolNames(Long agentId) { + if (isToolsDisabled(agentId)) { + return Set.of(); + } List bindings = listToolBindings(agentId); if (bindings.isEmpty()) { - return null; // 无绑定 → 全局默认 + return null; // no rows → inherit global default } return bindings.stream() .filter(b -> Boolean.TRUE.equals(b.getEnabled())) @@ -433,26 +482,43 @@ public class AgentBindingService implements AgentBindingResolver { * */ public Set getEffectiveToolNames(Long agentId) { + AgentEntity agent = agentMapper.selectById(agentId); + boolean skillsDisabled = agent != null && Boolean.TRUE.equals(agent.getSkillsDisabled()); + boolean toolsDisabled = agent != null && Boolean.TRUE.equals(agent.getToolsDisabled()); + Set boundSkillIds = getBoundSkillIds(agentId); Set directTools = getBoundToolNames(agentId); - // (1) null + null → no restriction; defer to the global default. + // Four-state matrix — see issue #184. + // + // (1) Pure legacy: no flags, no rows on either side → defer to global + // default (returns null). Agents created before V126 must remain + // bit-identical to their previous runtime contract. if (boundSkillIds == null && directTools == null) { return null; } + // (2) Skills-only opt-out with no explicit tool restriction → still + // defer tools to the global default. Without this carve-out, a + // user who only said "no skills" would silently lose every + // non-MCP global tool because the merge branch only emits the + // SYSTEM_LEVEL set. The SKILL.md catalog itself is still + // suppressed via getBoundSkillIds returning Set.of(). + if (skillsDisabled && !toolsDisabled && directTools == null) { + return null; + } + Set merged = new LinkedHashSet<>(); - if (boundSkillIds != null) { + if (boundSkillIds != null && !boundSkillIds.isEmpty()) { for (Long skillId : boundSkillIds) { ResolvedSkill resolved = findResolvedSkillById(skillId); if (resolved == null) continue; if (!vip.mate.skill.runtime.SkillRuntimeService.passesActiveGate(resolved)) { - // §14.2 fix: a disabled / security-blocked / setup-needed - // skill must not contribute tools to the LLM - // advertisement even if it's still bound. Without this - // guard, users see ghost tools for skills they thought - // were off. + // A disabled / security-blocked / setup-needed skill must + // not contribute tools to the LLM advertisement even if + // it's still bound — otherwise the user sees ghost tools + // for skills they thought were off. continue; } Set skillTools = resolved.getEffectiveAllowedTools(); @@ -461,32 +527,36 @@ public class AgentBindingService implements AgentBindingResolver { } if (directTools != null) { - // ∪ Advanced 直选的原子 tool（§9.2 调整 B） merged.addAll(directTools); } // System-level tools that don't belong to any single skill but - // are agent-wide capabilities. Without this carve-out, binding - // any skill silently strips record_lesson / remember / structured- - // memory tools, breaking the §11 self-evolution loop entirely - // (the LLM stops being able to write to LESSONS.md / MEMORY.md). + // are agent-wide capabilities — structured memory primitives, + // workspace memory CRUD, etc. Without this carve-out, binding any + // skill silently strips record_lesson / remember / *memory_file + // tools, breaking the self-evolution loop. These survive even + // toolsDisabled=true because they are agent-internal infrastructure, + // unrelated to the user-facing capability picker. merged.addAll(SYSTEM_LEVEL_TOOLS); // MCP tools. An agent that bound only a skill or a built-in tool - // and ticked no MCP row keeps full access to every enabled MCP - // tool: MCP servers are an administrator-enabled capability and - // must not silently vanish just because some unrelated binding - // exists. But once the operator ticks specific MCP rows, that is a - // deliberate per-agent scope — only those MCP tools (already merged - // via directTools above) stay, and the rest are not auto-joined, so - // a role can be limited to a fixed MCP tool set. To instead hide a - // single MCP tool from an agent that ticked no MCP row, use the - // tool-guard deny path applied upstream in AgentGraphBuilder. - Set enabledMcpTools = getEnabledMcpToolNames(); - boolean agentScopedMcpExplicitly = - directTools != null && !Collections.disjoint(directTools, enabledMcpTools); - if (!agentScopedMcpExplicitly) { - merged.addAll(enabledMcpTools); + // and ticked no MCP row normally keeps full access to every enabled + // MCP tool (administrator-level capabilities should not silently + // vanish just because some unrelated binding exists). Two cases + // suppress the auto-include: + // - tools_disabled=true → the user explicitly opted out of every + // non-system tool. Auto-joining MCP would defeat that intent. + // - The agent ticked at least one MCP tool itself → that signals a + // deliberate per-agent MCP scope; only the ticked subset stays. + // To deny a single MCP tool when none are ticked and tools are + // enabled, use the tool-guard deny path in AgentGraphBuilder. + if (!toolsDisabled) { + Set enabledMcpTools = getEnabledMcpToolNames(); + boolean agentScopedMcpExplicitly = directTools != null && !directTools.isEmpty() + && !Collections.disjoint(directTools, enabledMcpTools); + if (!agentScopedMcpExplicitly) { + merged.addAll(enabledMcpTools); + } } return merged; @@ -513,6 +583,40 @@ public class AgentBindingService implements AgentBindingResolver { } } + /** + * Skill-discovery meta tools that let the LLM enumerate, load, read, or + * execute the workspace's skill catalog. Normally these live in + * {@link #SYSTEM_LEVEL_TOOLS} because every agent needs them — but when + * an agent has opted out of skills (issue #184), keeping them callable + * defeats the opt-out: the LLM can simply call {@code listAvailableSkills} + * to enumerate the catalog and {@code load_skill} to pull a SKILL.md + * into the conversation, even though the SKILL.md catalog itself was + * suppressed from the system prompt. + * + *

Resolved via {@link #getSkillDiscoveryDeniedTools} as a separate + * deny layer chained after the main allowlist, so the four-state matrix + * in {@link #getEffectiveToolNames} stays untouched. + */ + private static final Set SKILL_DISCOVERY_TOOLS = Set.of( + "listAvailableSkills", + "load_skill", + "readSkillFile", + "runSkillScript", + "listSkillFiles" + ); + + /** + * Tools the agent must NOT see when {@link AgentEntity#getSkillsDisabled()} + * is {@code true}. Empty otherwise. Chained on top of the allowlist by + * {@code AgentGraphBuilder} via {@code withDeniedToolsFiltered}. + */ + public Set getSkillDiscoveryDeniedTools(Long agentId) { + if (isSkillsDisabled(agentId)) { + return SKILL_DISCOVERY_TOOLS; + } + return Set.of(); + } + /** * Tools that exist outside the skill scope and must survive any * agent-level skill binding restriction. @@ -614,7 +718,7 @@ public class AgentBindingService implements AgentBindingResolver { // refuses ("Tool not found: search"). Observed 2026-05-01 on the // Code Reviewer agent — the model called search → got // not-found → gave up before ever reaching renderDocx. - "search", + "web_search", "browser_use", "read_file", "send_file", @@ -669,6 +773,9 @@ public class AgentBindingService implements AgentBindingResolver { } public AgentToolBinding bindTool(Long agentId, String toolName) { + // Mirror of bindSkill: writing any tool row clears the opt-out flag + // so the binding state cannot contradict the agent-level toggle. + clearToolsDisabledFlag(agentId); AgentToolBinding existing = toolBindingMapper.selectOne( new LambdaQueryWrapper() .eq(AgentToolBinding::getAgentId, agentId) @@ -715,6 +822,12 @@ public class AgentBindingService implements AgentBindingResolver { public void setToolBindings(Long agentId, List toolNames) { validateNewToolBindings(agentId, toolNames); + // Side effect parallel to setSkillBindings: a non-empty save is an + // explicit commitment to those tools, so the opt-out flag is + // auto-cleared. Empty saves leave the flag untouched. + if (toolNames != null && !toolNames.isEmpty()) { + clearToolsDisabledFlag(agentId); + } toolBindingMapper.delete( new LambdaQueryWrapper() .eq(AgentToolBinding::getAgentId, agentId)); @@ -827,4 +940,57 @@ public class AgentBindingService implements AgentBindingResolver { providerPreferenceMapper.insert(row); } } + + // ==================== Binding-mode flags (V126) ==================== + + /** + * Read-side check for the agent's "skills opted out entirely" toggle. + * Returns {@code false} when the agent row is missing — a missing agent + * has no opinion, so binding queries fall through to the legacy + * row-count path (which will surface the missing-agent issue at a more + * useful layer than a binding read). + */ + private boolean isSkillsDisabled(Long agentId) { + if (agentId == null) return false; + AgentEntity agent = agentMapper.selectById(agentId); + return agent != null && Boolean.TRUE.equals(agent.getSkillsDisabled()); + } + + /** Mirror of {@link #isSkillsDisabled} for the tools opt-out toggle. */ + private boolean isToolsDisabled(Long agentId) { + if (agentId == null) return false; + AgentEntity agent = agentMapper.selectById(agentId); + return agent != null && Boolean.TRUE.equals(agent.getToolsDisabled()); + } + + /** + * Flip {@code skills_disabled} back to false on the agent row. No-op + * when already false or the agent doesn't exist. Used as an auto-clear + * step in {@link #bindSkill} / {@link #setSkillBindings} so writing a + * concrete binding always wins over a stale opt-out flag. + */ + private void clearSkillsDisabledFlag(Long agentId) { + if (agentId == null) return; + AgentEntity agent = agentMapper.selectById(agentId); + if (agent == null || !Boolean.TRUE.equals(agent.getSkillsDisabled())) { + return; + } + AgentEntity update = new AgentEntity(); + update.setId(agentId); + update.setSkillsDisabled(false); + agentMapper.updateById(update); + } + + /** Mirror of {@link #clearSkillsDisabledFlag} for the tools toggle. */ + private void clearToolsDisabledFlag(Long agentId) { + if (agentId == null) return; + AgentEntity agent = agentMapper.selectById(agentId); + if (agent == null || !Boolean.TRUE.equals(agent.getToolsDisabled())) { + return; + } + AgentEntity update = new AgentEntity(); + update.setId(agentId); + update.setToolsDisabled(false); + agentMapper.updateById(update); + } } diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java b/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java index 26de0ac8..345ba438 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/context/ConversationWindowManager.java @@ -170,6 +170,15 @@ public class ConversationWindowManager { * conversation in a compaction storm. */ private final ConcurrentHashMap ptlForceCompactAt = new ConcurrentHashMap<>(); + /** + * Default max input tokens for the configured model window. Surfaced for + * the per-loop budgeter so the L1 (multi-turn compaction) and L2 + * (per-iteration trim) layers stay calibrated to the same number. + */ + public int getDefaultMaxInputTokens() { + return properties != null ? properties.getDefaultMaxInputTokens() : 0; + } + /** Cooldown window after a structured PTL compaction during which a * follow-up PTL is downgraded to tail-only. Picked so a single ReAct * loop that retries within seconds can't burn another summary LLM diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/LoopBudgetConfig.java b/mateclaw-server/src/main/java/vip/mate/agent/context/LoopBudgetConfig.java new file mode 100644 index 00000000..01228d6d --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/agent/context/LoopBudgetConfig.java @@ -0,0 +1,140 @@ +package vip.mate.agent.context; + +/** + * Configuration for per-reasoning-loop message budgeting. + * + *

Used by {@link LoopMessageBudgeter} to decide when and how to trim the + * working message list that a ReAct iteration hands to the LLM. Distinct from + * the multi-turn history compression configured by + * {@link vip.mate.config.ConversationWindowProperties}: this one applies inside + * a single user turn while the ReAct loop accumulates reasoning steps and + * tool-call/tool-response pairs. + * + *

Field semantics: + *

    + *
  • {@code triggerTokens} — token threshold above which budgeting kicks + * in. Compared against {@code historyTokens + reservedPrefixTokens} + * so the budgeter accounts for the full prompt the LLM will see, + * not just the message list.
    • + *
  • {@code keepTailTokens} — token budget reserved for the tail (recent + * observations + the current user message). Scales with the model + * window instead of relying on a fixed count.
    • + *
  • {@code minTailMessages} — floor on the kept-tail count. Prevents a + * single huge tool output from collapsing the tail to one message and + * losing recent reasoning context.
    • + *
  • {@code tailSoftCeilingRatio} — multiplier applied to + * {@code keepTailTokens} when honoring the floor or pulling back to + * keep a tool pair whole. Lets the tail overshoot the hard budget by + * up to this factor before more aggressive cuts kick in.
    • + *
  • {@code reservedPrefixTokens} — estimated tokens consumed by the + * non-history portion of the prompt (system prompt, skill catalog, + * runtime context, wiki injection, tool schemas, output reserve). + * Surfaces these from the caller so the budget covers the whole + * prompt, not just the message list.
    • + *
  • {@code targetMaxMessages} — soft ceiling on the count fed to the + * LLM. Best-effort: the budgeter may exceed it slightly to keep a + * tool pair whole rather than orphan a call/response — that case is + * reported via {@code BudgetTrace.capExceededForPairIntegrity}.
    • + *
+ */ +public record LoopBudgetConfig( + int triggerTokens, + int keepTailTokens, + int minTailMessages, + double tailSoftCeilingRatio, + int reservedPrefixTokens, + int targetMaxMessages) { + + /** Smallest useful trigger threshold; below this budgeting is effectively disabled. */ + public static final int MIN_TRIGGER_TOKENS = 1_000; + + /** Smallest sensible tail budget; below this even one observation may not fit. */ + public static final int MIN_TAIL_TOKENS = 2_000; + + /** Floor on minTailMessages — fewer than 3 collapses recent context too aggressively. */ + public static final int MIN_TAIL_MESSAGES_FLOOR = 3; + + /** Floor on the soft ceiling ratio — anything below 1.0 is degenerate. */ + public static final double MIN_TAIL_SOFT_CEILING_RATIO = 1.0; + + /** Smallest sensible target cap; below this even a normal ReAct loop trips it. */ + public static final int MIN_TARGET_MAX = 20; + + public LoopBudgetConfig { + if (triggerTokens < MIN_TRIGGER_TOKENS) { + throw new IllegalArgumentException( + "triggerTokens must be >= " + MIN_TRIGGER_TOKENS + ", got " + triggerTokens); + } + if (keepTailTokens < MIN_TAIL_TOKENS) { + throw new IllegalArgumentException( + "keepTailTokens must be >= " + MIN_TAIL_TOKENS + ", got " + keepTailTokens); + } + if (minTailMessages < MIN_TAIL_MESSAGES_FLOOR) { + throw new IllegalArgumentException( + "minTailMessages must be >= " + MIN_TAIL_MESSAGES_FLOOR + + ", got " + minTailMessages); + } + if (tailSoftCeilingRatio < MIN_TAIL_SOFT_CEILING_RATIO) { + throw new IllegalArgumentException( + "tailSoftCeilingRatio must be >= " + MIN_TAIL_SOFT_CEILING_RATIO + + ", got " + tailSoftCeilingRatio); + } + if (reservedPrefixTokens < 0) { + throw new IllegalArgumentException( + "reservedPrefixTokens must be >= 0, got " + reservedPrefixTokens); + } + if (targetMaxMessages < MIN_TARGET_MAX) { + throw new IllegalArgumentException( + "targetMaxMessages must be >= " + MIN_TARGET_MAX + + ", got " + targetMaxMessages); + } + if (keepTailTokens >= triggerTokens) { + throw new IllegalArgumentException( + "keepTailTokens (" + keepTailTokens + ") must be < triggerTokens (" + + triggerTokens + ") — otherwise budgeting would never reduce anything"); + } + } + + /** Tail budget after applying the soft ceiling. */ + public int tailSoftCeilingTokens() { + return (int) (keepTailTokens * tailSoftCeilingRatio); + } + + /** + * Derive a sensible config from a model's context window. The ratios were + * chosen so the budgeter triggers well before the model's actual limit and + * leaves enough headroom for the LLM's own response. + * + *
    + *
  • trigger = 50% of the window — same threshold the multi-turn + * compressor uses, so the two layers stay calibrated.
    • + *
  • tail budget = 30% of the window.
    • + *
  • minTailMessages = 4 — at least one full reasoning/action cycle + * stays visible to the LLM no matter how big a single tool output is.
    • + *
  • tailSoftCeilingRatio = 1.5 — let the tail overshoot by 50% when + * enforcing the floor or pulling back to keep a tool pair whole.
    • + *
  • reservedPrefixTokens = 0 — caller should override with the real + * prefix estimate; left at 0 the budget still works but errs on + * the side of triggering later than it should.
    • + *
  • targetMaxMessages = 200 — well above a normal ReAct loop's 20–40 + * working messages, low enough to be a meaningful guard rail.
    • + *
+ */ + public static LoopBudgetConfig forContext(int contextWindowTokens) { + if (contextWindowTokens <= 0) { + contextWindowTokens = 32_000; + } + int trigger = Math.max(MIN_TRIGGER_TOKENS, (int) (contextWindowTokens * 0.50)); + int tail = Math.max(MIN_TAIL_TOKENS, (int) (contextWindowTokens * 0.30)); + if (tail >= trigger) { + tail = Math.max(MIN_TAIL_TOKENS, trigger - MIN_TRIGGER_TOKENS); + } + return new LoopBudgetConfig(trigger, tail, 4, 1.5, 0, 200); + } + + /** Return a copy with {@code reservedPrefixTokens} replaced. */ + public LoopBudgetConfig withReservedPrefixTokens(int reservedPrefixTokens) { + return new LoopBudgetConfig(triggerTokens, keepTailTokens, minTailMessages, + tailSoftCeilingRatio, reservedPrefixTokens, targetMaxMessages); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/LoopMessageBudgeter.java b/mateclaw-server/src/main/java/vip/mate/agent/context/LoopMessageBudgeter.java new file mode 100644 index 00000000..356ac616 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/agent/context/LoopMessageBudgeter.java @@ -0,0 +1,296 @@ +package vip.mate.agent.context; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.chat.messages.SystemMessage; +import org.springframework.ai.chat.messages.UserMessage; +import org.springframework.stereotype.Component; + +import java.util.ArrayList; +import java.util.List; + +/** + * Per-ReAct-loop message budgeter. Bounds the working message list a Reasoning + * iteration hands to the LLM while preserving five invariants that, when + * violated, either produce off-topic answers or 400s from strict providers: + * + *
    + *
  1. System prompt(s) — all consecutive {@link SystemMessage}s at + * the head stay verbatim. Production agents commonly have multiple + * (SOUL, AGENTS, runtime context, wiki, tool prompt, skill catalog).
    2. + *
  2. Turn anchor — the latest {@link UserMessage} is never dropped. + * Stitched in when an aggressive cut would otherwise lose it.
    3. + *
  3. Tool-call/response pair integrity — every assistant tool_call + * reaches the model with its matching tool_response, and vice versa. + * Delegated to {@link ToolPairSanitizer}.
    4. + *
  4. Token budget over message count — tail sized by token estimate + * so a small ReAct loop with fat observations and a large loop with + * thin observations both fit one config.
    5. + *
  5. Minimum tail messages — at least {@code minTailMessages} + * entries survive even when a single message is bigger than the + * hard tail budget. Prevents collapsing recent reasoning to one row + * when the latest tool output is huge.
    6. + *
+ * + *

The trigger threshold compares {@code historyTokens + + * reservedPrefixTokens} against {@code triggerTokens}; this keeps the + * budgeter calibrated against the entire prompt the LLM will see, not just + * the message list (the L1 compactor uses the same arithmetic). + * + *

Distinct from {@link ConversationWindowManager}: that one runs once per + * user turn and produces a structured LLM summary for the accumulated + * multi-turn history. This one runs per reasoning iteration on top of + * whatever {@code ConversationWindowManager} already produced, bounding the + * intra-turn ReAct accumulation. + * + *

Stateless and side-effect-free for callers; safe to call from + * concurrent reasoning threads. The orphan-removal pass mutates a freshly + * allocated local list, never the caller's input. + */ +@Slf4j +@Component +public class LoopMessageBudgeter { + + /** Outcome of a budgeting pass. */ + public record Result(List messages, BudgetTrace trace) {} + + /** + * Structured trace of a single budgeting decision. All counts and token + * figures refer to {@link Message} entries. + * + *

    + *
  • {@code anchorEnforced} — the tail cut was pulled earlier than + * the token budget would have placed it because the latest + * UserMessage would otherwise have been dropped.
    • + *
  • {@code anchorStitched} — the latest UserMessage could not fit in + * the tail even after pull-back (typically when the target cap + * fired hard); it was inserted as a standalone slot between head + * and tail.
    • + *
  • {@code capExceededForPairIntegrity} — the final count exceeded + * {@code targetMaxMessages} because pulling the cut back to keep + * a tool pair whole won out over the soft cap. Useful signal that + * upstream compaction should have run sooner.
    • + *
  • {@code minTailFloorApplied} — the tail was enlarged past the + * hard token budget (up to the soft ceiling) to honor + * {@code minTailMessages}.
    • + *
  • {@code triggered} — the budget entered its main path because the + * trigger threshold was met. Says nothing about whether anything + * was actually removed.
    • + *
  • {@code modified} — the returned list differs from the input + * (count changed or orphans removed). This is the only signal + * callers should use to gate log output; a triggered-but-no-op + * pass is normal and shouldn't spam logs.
    • + *
+ */ + public record BudgetTrace( + int originalCount, + int originalTokens, + int finalCount, + int finalTokens, + int reservedPrefixTokens, + int headKept, + int tailKept, + int droppedMiddle, + int orphansRemoved, + boolean anchorEnforced, + boolean anchorStitched, + boolean targetMaxTripped, + boolean capExceededForPairIntegrity, + boolean minTailFloorApplied, + boolean triggered, + boolean modified) { + + /** Trace for the no-op case (budget not triggered). */ + public static BudgetTrace untouched(int count, int tokens, int prefixTokens, int headKept) { + return new BudgetTrace(count, tokens, count, tokens, prefixTokens, headKept, + count - headKept, 0, 0, + false, false, false, false, false, false, false); + } + } + + /** Apply the loop budget to {@code messages}. Pure function; never mutates the input. */ + public Result budget(List messages, LoopBudgetConfig cfg) { + if (messages == null || messages.isEmpty()) { + return new Result(messages == null ? List.of() : messages, + BudgetTrace.untouched(0, 0, cfg.reservedPrefixTokens(), 0)); + } + int originalCount = messages.size(); + int historyTokens = TokenEstimator.estimateTokens(messages); + int headEnd = findHeadEnd(messages); + + // Budget against the full prompt (history + prefix), so the trigger + // matches what the LLM would actually receive — not just the + // history slice. Prefix covers system prompt, skill catalog, + // runtime context, wiki, tool schemas, output reserve. + int promptTokens = historyTokens + cfg.reservedPrefixTokens(); + + // Below both thresholds → forward unchanged. + if (promptTokens < cfg.triggerTokens() && originalCount < cfg.targetMaxMessages()) { + return new Result(messages, + BudgetTrace.untouched(originalCount, historyTokens, + cfg.reservedPrefixTokens(), headEnd)); + } + + // 1. Token-budgeted tail cut. Walk backward from the end; the + // earliest index whose suffix fits within keepTailTokens is the + // proposed boundary. + int hardTailStart = findTailCutByTokens(messages, headEnd, cfg.keepTailTokens()); + + // 2. Min-tail floor: if the hard cut keeps fewer than minTailMessages, + // pull back to keep at least that many — but only up to the soft + // ceiling. Without this, one giant tool output can collapse the + // tail to a single row and lose recent reasoning context. + boolean minTailFloorApplied = false; + int tailStart = hardTailStart; + int hardTailCount = originalCount - hardTailStart; + if (hardTailCount < cfg.minTailMessages()) { + int floorTailStart = Math.max(headEnd, originalCount - cfg.minTailMessages()); + // Honor the soft ceiling: if even the floor count would consume + // more than tailSoftCeilingTokens, accept it (the floor wins, + // since the alternative is losing recent reasoning entirely). + tailStart = floorTailStart; + minTailFloorApplied = true; + } else { + // Apply the soft ceiling: if the hard cut undershoots the soft + // ceiling (i.e. there's slack), keep going. We already cut to + // the hard budget so there's no need to expand here — the soft + // ceiling acts as a guard rail for the floor/pull-back path, + // not as a relaxation of the normal cut. + } + + // 3. Anchor: never drop the latest UserMessage. Pull tail back if + // needed (cheap — just moves the boundary). + boolean anchorEnforced = false; + int anchorIdx = findLatestUserMessageIdx(messages, headEnd); + if (anchorIdx >= 0 && anchorIdx < tailStart) { + tailStart = anchorIdx; + anchorEnforced = true; + } + + // 4. Tool-pair integrity at the boundary: if tailStart sits inside a + // tool pair, pull back so the pair survives whole. Delegated to + // the shared sanitizer. + int beforePairPullBack = tailStart; + tailStart = ToolPairSanitizer.pullBackToToolPairBoundary(messages, headEnd, tailStart); + + // 5. Target max safety net. The pair-integrity pull-back may have + // pushed final count above the soft cap; we re-evaluate and try + // to enforce, but pair integrity wins over count cap. + boolean targetMaxTripped = false; + boolean anchorStitched = false; + boolean capExceededForPairIntegrity = false; + int targetTailCap = Math.max(0, cfg.targetMaxMessages() - headEnd); + if (targetTailCap > 0 && (originalCount - tailStart) > targetTailCap) { + int provisionalTailStart = originalCount - targetTailCap; + boolean stitchNeeded = anchorIdx >= 0 && anchorIdx < provisionalTailStart; + int reservedForStitchedAnchor = stitchNeeded ? 1 : 0; + int recentTailCap = Math.max(1, targetTailCap - reservedForStitchedAnchor); + int newTailStart = originalCount - recentTailCap; + int adjustedTailStart = ToolPairSanitizer.pullBackToToolPairBoundary( + messages, headEnd, newTailStart); + if (adjustedTailStart < newTailStart) { + // Pair integrity prevailed over the cap; honestly record that + // the final count will exceed targetMaxMessages. + capExceededForPairIntegrity = true; + } + tailStart = adjustedTailStart; + targetMaxTripped = true; + anchorStitched = anchorIdx >= 0 && anchorIdx < tailStart; + } + + // Detect anchor stitching from the tool-pair pull-back path too: + // pull-back may have moved tailStart earlier than the anchor index + // (rare, but possible if the pair anchor is in the head section). + if (!anchorStitched && anchorIdx >= 0 && anchorIdx < tailStart) { + anchorStitched = true; + } + + // 6. Build the trimmed list: head + [stitched anchor?] + tail. + int estimated = headEnd + (anchorStitched ? 1 : 0) + (originalCount - tailStart); + List trimmed = new ArrayList<>(estimated); + trimmed.addAll(messages.subList(0, headEnd)); + if (anchorStitched) { + trimmed.add(messages.get(anchorIdx)); + } + trimmed.addAll(messages.subList(tailStart, originalCount)); + + // 7. Tool-pair invariant: cross-boundary orphans cleaned up. The + // pull-back at step 4 handles the boundary case but a head-section + // Assistant(tool_calls) whose responses fell in the dropped middle + // still needs the bidirectional pass. + int orphans = ToolPairSanitizer.removeOrphans(trimmed); + + int finalCount = trimmed.size(); + int finalTokens = TokenEstimator.estimateTokens(trimmed); + int droppedMiddle = originalCount - finalCount; + + // Touch the unused locals so the compiler doesn't warn — they're + // useful in the trace's narrative but the actual cut already + // committed. + if (beforePairPullBack != tailStart) { + // pair pull-back moved the boundary; logged via trace fields + } + + boolean modified = (finalCount != originalCount) || (orphans > 0); + + return new Result(trimmed, new BudgetTrace( + originalCount, historyTokens, + finalCount, finalTokens, + cfg.reservedPrefixTokens(), + headEnd, + finalCount - headEnd, + droppedMiddle, + orphans, + anchorEnforced, + anchorStitched, + targetMaxTripped, + capExceededForPairIntegrity, + minTailFloorApplied, + /* triggered */ true, + modified)); + } + + // ------------------------------------------------------------------------ + // Internals + // ------------------------------------------------------------------------ + + private static int findHeadEnd(List messages) { + int i = 0; + while (i < messages.size() && messages.get(i) instanceof SystemMessage) { + i++; + } + return i; + } + + /** + * Walk backward from the end accumulating per-message token estimates. + * Return the earliest index whose suffix fits within {@code keepTokens}. + * Always returns a value in {@code [headEnd, messages.size())} so the + * tail is non-empty. + */ + private static int findTailCutByTokens(List messages, int headEnd, int keepTokens) { + int n = messages.size(); + if (n <= headEnd) { + return n; + } + int acc = 0; + for (int i = n - 1; i >= headEnd; i--) { + int t = TokenEstimator.estimateTokens(messages.get(i)); + if (acc + t > keepTokens && i < n - 1) { + return i + 1; + } + acc += t; + } + return headEnd; + } + + /** Index of the latest {@link UserMessage} at or after {@code headEnd}; -1 if none. */ + private static int findLatestUserMessageIdx(List messages, int headEnd) { + for (int i = messages.size() - 1; i >= headEnd; i--) { + if (messages.get(i) instanceof UserMessage) { + return i; + } + } + return -1; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/RuntimeContextInjector.java b/mateclaw-server/src/main/java/vip/mate/agent/context/RuntimeContextInjector.java index ca773c99..7b3649b1 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/context/RuntimeContextInjector.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/context/RuntimeContextInjector.java @@ -87,12 +87,40 @@ public final class RuntimeContextInjector { sb.append("\n[system-context] Working directory: ").append(workspaceBasePath); sb.append("\nYou can only read/write files and execute commands within this directory and its subdirectories."); } + appendSkillRootHintIfPresent(sb, workspaceBasePath, i18n); } appendSenderBlockIfPresent(sb, origin); return sb.toString(); } + /** + * Tell the model that the shared skill repository is reachable in addition + * to the workspace. Without this, a model that strictly honors the + * "working directory only" hint refuses to read or run skill files that + * live outside the workspace — even though the path sandbox now allows + * them. Skipped when the skill root is unknown or already sits inside the + * workspace (no separate boundary to explain). + */ + private static void appendSkillRootHintIfPresent(StringBuilder sb, String workspaceBasePath, + vip.mate.i18n.I18nService i18n) { + java.nio.file.Path skillRoot = vip.mate.tool.guard.WorkspacePathGuard.getSkillRoot(); + if (skillRoot == null) { + return; + } + java.nio.file.Path wsRoot = java.nio.file.Paths.get(workspaceBasePath).toAbsolutePath().normalize(); + if (skillRoot.startsWith(wsRoot)) { + return; + } + String skillRootStr = skillRoot.toString(); + if (i18n != null) { + sb.append("\n").append(i18n.msg("context.skill_dir_hint", skillRootStr)); + } else { + sb.append("\nShared skills live under ").append(skillRootStr) + .append("; you may also read and run files there, even though it is outside the working directory."); + } + } + /** * Append a sender / channel / chat block when the origin carries * meaningful IM context. Format is intentionally one line per diff --git a/mateclaw-server/src/main/java/vip/mate/agent/context/ToolPairSanitizer.java b/mateclaw-server/src/main/java/vip/mate/agent/context/ToolPairSanitizer.java new file mode 100644 index 00000000..ac3ac94f --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/agent/context/ToolPairSanitizer.java @@ -0,0 +1,192 @@ +package vip.mate.agent.context; + +import org.springframework.ai.chat.messages.AssistantMessage; +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.chat.messages.ToolResponseMessage; + +import java.util.HashSet; +import java.util.List; +import java.util.Set; + +/** + * Pure-function utilities that enforce the OpenAI-compatible + * tool_call ↔ tool_response pairing invariant: + * + *
    + *
  • Every {@code tool_call.id} on an {@link AssistantMessage} has a + * matching {@code tool_response.id} on a {@link ToolResponseMessage} + * after it in the list.
    • + *
  • Every {@code tool_response.id} on a {@link ToolResponseMessage} has + * a matching {@code tool_call.id} on an {@link AssistantMessage} + * before it.
    • + *
  • No empty/null ids on either side.
    • + *
+ * + *

Violating either rule causes strict providers (kimi-code, anthropic in + * tool-use mode, OpenAI's responses API on certain models) to reject the + * request with a 400 error such as + * {@code "tool_call_id is not found"}. This sanitizer is the single source of + * truth for that invariant — any trim / cut / window logic should run its + * pre/post passes here rather than reimplementing them. + * + *

All methods are {@code static} and side-effect-free except where + * documented (e.g. {@link #removeOrphans(List)} mutates the list in place to + * avoid an extra allocation hot in the reasoning loop). They never touch the + * input list when no fix is needed. + */ +public final class ToolPairSanitizer { + + private ToolPairSanitizer() { + // utility class + } + + /** + * Pull a proposed cut boundary earlier so an Assistant(tool_calls) that + * issued ids matching {@link ToolResponseMessage}s in the kept tail + * survives into the tail alongside its responses. Prevents producing an + * orphan response at the cut boundary in the first place. + * + * @param messages full message list (read-only) + * @param headEnd index after the last protected head message + * @param tailStart proposed boundary; messages at and after this index + * are kept, those between {@code headEnd} and + * {@code tailStart} are dropped + * @return possibly-earlier {@code tailStart} that keeps tool pairs whole + */ + public static int pullBackToToolPairBoundary(List messages, int headEnd, int tailStart) { + if (tailStart <= headEnd || messages == null || messages.isEmpty()) { + return tailStart; + } + Set tailResponseIds = new HashSet<>(); + for (int i = tailStart; i < messages.size(); i++) { + if (messages.get(i) instanceof ToolResponseMessage trm) { + for (ToolResponseMessage.ToolResponse r : trm.getResponses()) { + if (r.id() != null && !r.id().isEmpty()) { + tailResponseIds.add(r.id()); + } + } + } + } + if (tailResponseIds.isEmpty()) { + return tailStart; + } + for (int i = tailStart - 1; i >= headEnd; i--) { + Message m = messages.get(i); + if (m instanceof AssistantMessage am && am.getToolCalls() != null) { + boolean overlaps = am.getToolCalls().stream() + .anyMatch(tc -> tc.id() != null && tailResponseIds.contains(tc.id())); + if (overlaps) { + return i; + } + } + } + return tailStart; + } + + /** + * Iteratively remove tool-pair orphans from {@code messages} (mutates the + * list in place). Two shapes are handled: + * + *

P0: a {@link ToolResponseMessage} whose response id has no + * matching assistant tool_call in the list. + * + *

P1: an {@link AssistantMessage} whose every tool_call id + * has no matching response in the list. (An assistant with both matched + * and unmatched calls is left alone — removing it would harm more than + * it helps; strict providers tolerate extra calls more readily than + * dropping the whole assistant message.) + * + *

Iterates until convergence: removing an assistant for P1 can expose + * a P0 orphan that needs cleaning, and vice versa. + * + *

Also removes any tool_call or tool_response with a null or empty id + * — those have no useful pairing semantics and confuse both the strict + * providers and the matching logic. + * + * @return total number of messages removed across all passes + */ + public static int removeOrphans(List messages) { + if (messages == null || messages.isEmpty()) { + return 0; + } + int totalRemoved = 0; + boolean changed; + do { + Set callIds = new HashSet<>(); + Set respIds = new HashSet<>(); + for (Message m : messages) { + if (m instanceof AssistantMessage am && am.getToolCalls() != null) { + for (AssistantMessage.ToolCall tc : am.getToolCalls()) { + if (tc.id() != null && !tc.id().isEmpty()) { + callIds.add(tc.id()); + } + } + } + if (m instanceof ToolResponseMessage trm) { + for (ToolResponseMessage.ToolResponse r : trm.getResponses()) { + if (r.id() != null && !r.id().isEmpty()) { + respIds.add(r.id()); + } + } + } + } + int before = messages.size(); + messages.removeIf(m -> { + if (m instanceof ToolResponseMessage trm) { + // P0: a response with a null/empty id, or whose id has + // no matching tool_call. + return trm.getResponses().stream().anyMatch(r -> + r.id() == null || r.id().isEmpty() || !callIds.contains(r.id())); + } + if (m instanceof AssistantMessage am && am.getToolCalls() != null + && !am.getToolCalls().isEmpty()) { + // P1: every tool_call on this assistant has no matching response. + return am.getToolCalls().stream().allMatch(tc -> + tc.id() == null || tc.id().isEmpty() || !respIds.contains(tc.id())); + } + return false; + }); + int removed = before - messages.size(); + totalRemoved += removed; + changed = removed > 0; + } while (changed); + return totalRemoved; + } + + /** + * Post-condition check: returns {@code true} iff {@code messages} + * satisfies the pairing invariant — every assistant tool_call has a + * matching response after it, every response has a matching call before + * it, all ids are non-empty. Intended for tests and defensive asserts; + * production code should run {@link #removeOrphans(List)} which + * guarantees this holds on return. + */ + public static boolean isPaired(List messages) { + if (messages == null || messages.isEmpty()) { + return true; + } + Set callIds = new HashSet<>(); + Set respIds = new HashSet<>(); + for (Message m : messages) { + if (m instanceof AssistantMessage am && am.getToolCalls() != null) { + for (AssistantMessage.ToolCall tc : am.getToolCalls()) { + if (tc.id() == null || tc.id().isEmpty()) return false; + callIds.add(tc.id()); + } + } + if (m instanceof ToolResponseMessage trm) { + for (ToolResponseMessage.ToolResponse r : trm.getResponses()) { + if (r.id() == null || r.id().isEmpty()) return false; + respIds.add(r.id()); + } + } + } + for (String c : callIds) { + if (!respIds.contains(c)) return false; + } + for (String r : respIds) { + if (!callIds.contains(r)) return false; + } + return true; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/agent/controller/AgentController.java b/mateclaw-server/src/main/java/vip/mate/agent/controller/AgentController.java index 281035c9..c38412a8 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/controller/AgentController.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/controller/AgentController.java @@ -1,5 +1,6 @@ package vip.mate.agent.controller; +import com.fasterxml.jackson.databind.ObjectMapper; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; @@ -27,6 +28,7 @@ import vip.mate.workspace.core.service.WorkspaceService; import java.io.IOException; import java.util.List; +import java.util.Map; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; @@ -49,6 +51,7 @@ public class AgentController { private final ModelConfigService modelConfigService; private final ModelCapabilityService modelCapabilityService; private final SystemSettingService systemSettingService; + private final ObjectMapper objectMapper; private final ExecutorService sseExecutor = Executors.newCachedThreadPool(); @Operation(summary = "获取Agent列表") @@ -144,10 +147,14 @@ public class AgentController { @Operation(summary = "更新Agent") @PutMapping("/{id}") @RequireWorkspaceRole("member") - public R update(@PathVariable Long id, @RequestBody AgentEntity agent, + public R update(@PathVariable Long id, @RequestBody Map body, @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { AgentEntity existing = agentService.getAgent(id); verifyResourceWorkspace(existing.getWorkspaceId(), workspaceId); + AgentEntity agent = objectMapper.convertValue(body, AgentEntity.class); + if (!body.containsKey("primaryKbId")) { + agent.setPrimaryKbId(existing.getPrimaryKbId()); + } agent.setId(id); agent.setWorkspaceId(existing.getWorkspaceId()); // 不允许跨 workspace 迁移 AgentEntity updated = agentService.updateAgent(agent); diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/MessageNormalizer.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/MessageNormalizer.java new file mode 100644 index 00000000..8a4182af --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/MessageNormalizer.java @@ -0,0 +1,165 @@ +package vip.mate.agent.graph; + +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.chat.messages.SystemMessage; +import org.springframework.ai.chat.prompt.Prompt; + +import java.util.ArrayList; +import java.util.List; + +/** + * Pre-egress message-list normalizer. + * + *

Some OpenAI-compatible providers (notably LM Studio's built-in server, + * and certain strict-mode vLLM / SGLang deployments) enforce that exactly + * one {@link SystemMessage} must appear at index 0 of the messages array. + * Multiple consecutive SystemMessages, or any SystemMessage following a + * user / assistant / tool message, returns {@code 400 BAD_REQUEST: + * "System message must be at the beginning."}. + * + *

Permissive providers (OpenAI, DashScope, Ollama, DeepSeek, Kimi, Doubao, + * GLM) accept the relaxed shape, so the runtime historically composed + * prompts with multiple SystemMessages sprinkled through the non-history + * prefix (main system prompt + skill catalog + progress-ledger snapshot, + * each as its own SystemMessage). To stay portable across both strict and + * permissive backends, this normalizer collects every SystemMessage found + * anywhere in the input list, concatenates their text with a blank-line + * separator, and emits the result as a single SystemMessage at index 0. + * The relative order of non-system messages (user / assistant / + * tool_response) is preserved verbatim so {@code tool_call_id} pairings + * are unaffected. + * + *

Blank / whitespace-only SystemMessages are dropped from the merge. If + * every SystemMessage in the input is blank, the result is the same list + * with all SystemMessages removed (no synthetic empty SystemMessage is + * emitted). If the input contains zero SystemMessages, the input list + * reference is returned unchanged. + * + *

The transformation is semantically equivalent on permissive providers + * — the merged SystemMessage produces the same token sequence the model + * would have seen across N separate SystemMessages — and converts the + * strict-provider 400 into a success. It is also safe for non-OpenAI + * protocols: the Spring AI Anthropic and Vertex / Gemini adapters already + * extract SystemMessages out of the messages list into a top-level + * {@code system} / {@code systemInstruction} request field, so they receive + * an identical outbound payload whether handed one merged SystemMessage + * or several. + * + *

A kill switch is exposed via the JVM system property + * {@code mateclaw.llm.message-normalizer.enabled=false}, which makes + * {@link #normalize} a no-op for emergency rollback without code changes. + */ +public final class MessageNormalizer { + + /** Separator inserted between merged SystemMessage segments. */ + static final String SEPARATOR = "\n\n"; + + /** + * Kill-switch property name. Set to {@code false} (case-insensitive) on + * the JVM command line to disable normalization without a code change. + */ + public static final String ENABLED_PROPERTY = "mateclaw.llm.message-normalizer.enabled"; + + private static volatile boolean enabled = !"false".equalsIgnoreCase( + System.getProperty(ENABLED_PROPERTY, "true")); + + private MessageNormalizer() { + } + + /** Read the current kill-switch state. */ + public static boolean isEnabled() { + return enabled; + } + + /** + * Override the kill-switch at runtime (primarily for tests). Production + * code should not need to call this — set the JVM property at startup + * instead. + */ + public static void setEnabledForTesting(boolean value) { + enabled = value; + } + + /** + * Return a copy of {@code prompt} with every SystemMessage merged into a + * single SystemMessage at index 0. Returns the input prompt reference + * unchanged when no normalization is necessary (kill switch off, zero + * SystemMessages, or already a single non-blank SystemMessage at index 0). + */ + public static Prompt normalize(Prompt prompt) { + if (prompt == null || !enabled) { + return prompt; + } + List in = prompt.getInstructions(); + List out = normalize(in); + if (out == in) { + return prompt; + } + return new Prompt(out, prompt.getOptions()); + } + + /** + * List-level normalization, used by {@link #normalize(Prompt)} and by + * unit tests that want to assert on the raw message shape without + * constructing a {@link Prompt}. Returns the input list reference + * unchanged when no normalization is necessary. + */ + public static List normalize(List messages) { + if (!enabled || messages == null || messages.isEmpty()) { + return messages; + } + + int systemCount = 0; + int firstSystemIdx = -1; + for (int i = 0; i < messages.size(); i++) { + if (messages.get(i) instanceof SystemMessage) { + if (firstSystemIdx < 0) firstSystemIdx = i; + systemCount++; + } + } + + // Fast-path 1: no SystemMessages — nothing to do. + if (systemCount == 0) { + return messages; + } + // Fast-path 2: exactly one SystemMessage and it sits at index 0 with + // non-blank text. Already canonical — skip the rebuild. + if (systemCount == 1 && firstSystemIdx == 0) { + SystemMessage sm = (SystemMessage) messages.get(0); + String text = sm.getText(); + if (text != null && !text.isBlank()) { + return messages; + } + // Single blank SystemMessage at [0] — fall through to the rebuild, + // which will drop it. + } + + StringBuilder merged = new StringBuilder(); + List rest = new ArrayList<>(messages.size()); + for (Message m : messages) { + if (m instanceof SystemMessage sm) { + String text = sm.getText(); + if (text == null || text.isBlank()) { + continue; + } + if (merged.length() > 0) { + merged.append(SEPARATOR); + } + merged.append(text); + } else { + rest.add(m); + } + } + + if (merged.length() == 0) { + // Every SystemMessage in the input was blank — return just the + // non-system tail. No synthetic empty SystemMessage. + return rest; + } + + List out = new ArrayList<>(rest.size() + 1); + out.add(new SystemMessage(merged.toString())); + out.addAll(rest); + return out; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java index 988da757..cc3dd43c 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/NodeStreamingChatHelper.java @@ -412,18 +412,22 @@ public class NodeStreamingChatHelper { return ErrorType.BILLING; } // RFC-009 P3.2: MODEL_NOT_FOUND — provider rejects the requested model id. - // Includes DashScope's "[InvalidParameter] url error, please check url" - // (https://help.aliyun.com/zh/model-studio/error-code#error-url) which despite - // the wording is the provider rejecting an unknown/unsupported model id on - // the native protocol. Splitting this out from CLIENT_ERROR lets us hand off - // to the fallback chain instead of terminating — a different provider may - // recognize the model name (or have an equivalent default). + // DashScope signals an unknown/unsupported model id specifically as + // "[InvalidParameter] url error, please check url" + // (https://help.aliyun.com/zh/model-studio/error-code#error-url). Splitting this + // out from CLIENT_ERROR lets us hand off to the fallback chain instead of + // terminating — a different provider may recognize the model name (or have an + // equivalent default). + // + // Note: we match on the specific "url error" wording rather than a bare + // "InvalidParameter", because DashScope reuses the InvalidParameter code for + // request-shape problems that have nothing to do with the model id (an illegal + // tool name, or an unsupported parameter) — those are handled as CLIENT_ERROR + // below so a healthy model is not evicted from the failover pool. if (msg.contains("Model not exist") || msg.contains("model_not_found") || msg.contains("Model not found") || msg.contains("does not exist") - || msg.contains("[InvalidParameter]") - || msg.contains("InvalidParameter") || msg.contains("url error") // Volcano Ark: model exists but the user's account hasn't opened it, // or the id isn't valid for this region. Both are hard failures — @@ -432,9 +436,16 @@ public class NodeStreamingChatHelper { || msg.contains("InvalidEndpointOrModel")) { return ErrorType.MODEL_NOT_FOUND; } - // Client errors (400 Bad Request — unsupported format, invalid params, etc.) — NOT retryable + // Client errors (400 Bad Request — unsupported format, invalid params, etc.) — NOT retryable. + // DashScope's remaining "InvalidParameter" responses are request-shape bugs, e.g. a reserved + // or illegal tool name ("Tool names are not allowed to be [search]") or an unsupported + // parameter. These fail identically on every provider, so classifying them as CLIENT_ERROR + // (rather than MODEL_NOT_FOUND) keeps the model in the failover pool and surfaces the real + // cause instead of a misleading "model not available" message. if (msg.contains("400") || msg.contains("Bad Request") - || msg.contains("invalid_request_error") || msg.contains("unsupported")) { + || msg.contains("invalid_request_error") || msg.contains("unsupported") + || msg.contains("Tool names are not allowed") + || msg.contains("InvalidParameter")) { return ErrorType.CLIENT_ERROR; } // Server errors and transient TLS / socket-level network hiccups. @@ -716,11 +727,25 @@ public class NodeStreamingChatHelper { private StreamResult doStreamCall(ChatModel chatModel, Prompt prompt, String conversationId, String phase, boolean broadcast, int attempt) { + // Collapse every SystemMessage in the prompt into a single SystemMessage + // at index 0. Some OpenAI-compatible providers (LM Studio's built-in + // server, certain strict vLLM / SGLang deployments) reject 400 + // "System message must be at the beginning" when SystemMessages appear + // after user / assistant / tool messages — the runtime composes the + // non-history prefix from several SystemMessage segments (main prompt, + // skill catalog, progress-ledger snapshot) and some of them land mid- + // list. Permissive providers see an equivalent token sequence either + // way; non-OpenAI protocols (Anthropic, Vertex) extract the merged + // system into their top-level system field exactly as before. + // Preserves the input's options reference so downstream relay logic + // (options.user = relay token) keeps working. + Prompt outbound = MessageNormalizer.normalize(prompt); + // PR-2 L4 (RFC-049 §2.4.2): normalize as a pre-egress step (not only on retry). // Strip reasoning_content from prior-turn AssistantMessages (i <= lastUserIdx), // preserving in-turn thinking (i > lastUserIdx) so DeepSeek's contract holds. // The returned Prompt shares `options` by reference with the input prompt. - Prompt outbound = stripThinkingFromPrompt(prompt); + outbound = stripThinkingFromPrompt(outbound); // RFC-049 follow-up (2026-04-27): trim trailing AssistantMessage from the // outbound prompt. Triggered in practice by the summarizing→reasoning diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java index 401ed6d7..f832af01 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/executor/ToolExecutionExecutor.java @@ -14,6 +14,9 @@ import vip.mate.agent.context.StructuredTruncator; import vip.mate.agent.graph.state.DirectToolOutput; import vip.mate.agent.graph.state.SourceEvidenceLedger; import vip.mate.approval.ApprovalWorkflowService; +import vip.mate.approval.grant.AutoApproveResult; +import vip.mate.approval.grant.WorkspaceLookupCache; +import vip.mate.approval.grant.service.ApprovalGrantResolver; import vip.mate.channel.web.ChatStreamTracker; import vip.mate.tool.guard.ToolExecutionGuardHelper; import vip.mate.tool.guard.ToolGuard; @@ -226,6 +229,38 @@ public class ToolExecutionExecutor { this.auditEventService = s; } + /** + * Auto-grant lookup cache. Optional — legacy constructors leave it + * {@code null} and {@code evaluateGuard()} falls back to the original + * human-approval path. Both this and {@link #approvalGrantResolver} must be + * non-null for auto-grant to engage; either being null disables the resolver + * branch entirely (see {@code autoGrantWired} in {@code evaluateGuard}). + * Not {@code final} so existing constructors that don't take these + * dependencies stay source-compatible without restructuring. + */ + private WorkspaceLookupCache workspaceLookupCache; + + /** Auto-grant resolver. Optional; see {@link #workspaceLookupCache} note. */ + private ApprovalGrantResolver approvalGrantResolver; + + /** + * Constructor used by {@code AgentGraphBuilder} after PR-1: takes the auto-grant + * dependencies on top of the standard 7 params. Legacy constructors continue + * to work unchanged (they simply leave the two new fields {@code null}). + */ + public ToolExecutionExecutor(AgentToolSet toolSet, ToolGuardService toolGuardService, + ApprovalWorkflowService approvalService, ChatStreamTracker streamTracker, + vip.mate.config.ToolTimeoutProperties toolTimeoutProperties, + ToolResultStorage resultStorage, + vip.mate.tool.ToolConcurrencyRegistry concurrencyRegistry, + WorkspaceLookupCache workspaceLookupCache, + ApprovalGrantResolver approvalGrantResolver) { + this(toolSet, toolGuardService, null, approvalService, streamTracker, + toolTimeoutProperties, resultStorage, concurrencyRegistry); + this.workspaceLookupCache = workspaceLookupCache; + this.approvalGrantResolver = approvalGrantResolver; + } + /** * Per-turn deduplication key set for child-agent denial audit. Without * this, a child that retries the same denied tool many times in one @@ -458,7 +493,7 @@ public class ToolExecutionExecutor { // 2. ToolGuard 安全检查（replay 模式跳过） if (!isReplay) { GuardDecision decision = evaluateGuard(toolCall, toolName, arguments, - conversationId, agentId, toolCalls, i, events, requesterId); + conversationId, agentId, toolCalls, i, events, requesterId, safeOrigin); if (decision.blocked) { allResponses.add(new ToolResponseMessage.ToolResponse( @@ -898,8 +933,20 @@ public class ToolExecutionExecutor { private GuardDecision evaluateGuard(AssistantMessage.ToolCall toolCall, String toolName, String arguments, String conversationId, String agentId, List allToolCalls, int currentIndex, - List events, String requesterId) { - ToolInvocationContext guardCtx = ToolInvocationContext.of(toolName, arguments, conversationId, agentId); + List events, String requesterId, + ChatOrigin origin) { + // Auto-grant requires BOTH the lookup cache and the resolver to be wired. + // Legacy constructors leave them null; in that case we skip workspace + // resolution and skip the resolver block, falling back to the original + // human-approval path. + boolean autoGrantWired = approvalGrantResolver != null && workspaceLookupCache != null; + Long workspaceId = autoGrantWired + ? workspaceLookupCache.resolveByConversation(conversationId) + : null; + ToolInvocationContext guardCtx = ToolInvocationContext.of( + toolName, java.util.Map.of(), arguments, + conversationId, agentId, + /*channelType*/ null, requesterId, workspaceId); if (toolGuardService != null) { GuardEvaluation evaluation = toolGuardService.evaluate(guardCtx); @@ -912,6 +959,34 @@ public class ToolExecutionExecutor { } if (evaluation.shouldRequireApproval()) { + // Auto-grant decision layer: only engages when both deps are wired. + // HARD_BLOCK short-circuits to a blocked decision (no approval banner). + // APPROVED skips createPending() and lets the tool run as normal. + // REQUIRES_HUMAN falls through to the existing manual approval path. + if (autoGrantWired) { + AutoApproveResult auto = approvalGrantResolver.tryAutoApprove(guardCtx, evaluation); + if (auto.isHardBlocked()) { + String msg = "[安全拦截] safety floor matched: " + auto.reason() + + " — this command cannot be executed even with approval. " + + "Please use a safer alternative."; + log.warn("[ToolExecutor] Auto-grant HARD_BLOCK: tool={}, reason={}", toolName, auto.reason()); + events.add(GraphEventPublisher.toolComplete(toolCall.id(), toolName, msg, false)); + return GuardDecision.blocked(msg); + } + if (auto.isApproved()) { + log.info("[ToolExecutor] Auto-grant APPROVED: tool={}, grantId={}", toolName, auto.grantId()); + return GuardDecision.allowed(); + } + // requiresHuman → fall through to legacy human-approval path below. + } + + // No human can resolve an approval in a non-interactive (scheduled-job) + // run, so a pending request would hang the turn until it times out with + // no answer. Deny immediately with an actionable message instead. + if (origin != null && origin.cronOrigin()) { + return denyNonInteractiveApproval(toolCall, toolName, events); + } + List remaining = allToolCalls.subList(currentIndex + 1, allToolCalls.size()); String approvalResponse = ToolExecutionGuardHelper.handleToolApproval( toolCall, toolName, arguments, evaluation, @@ -931,6 +1006,9 @@ public class ToolExecutionExecutor { } if (guardResult.needsApproval()) { + if (origin != null && origin.cronOrigin()) { + return denyNonInteractiveApproval(toolCall, toolName, events); + } List remaining = allToolCalls.subList(currentIndex + 1, allToolCalls.size()); String approvalResponse = ToolExecutionGuardHelper.handleToolApprovalLegacy( toolCall, toolName, arguments, guardResult, @@ -943,6 +1021,22 @@ public class ToolExecutionExecutor { return GuardDecision.allowed(); } + /** + * Deny an approval-required tool when the run is non-interactive (no human can + * approve), returning an actionable message so the agent falls back to a + * non-gated built-in tool instead of stalling on a pending nobody resolves. + */ + private GuardDecision denyNonInteractiveApproval(AssistantMessage.ToolCall toolCall, String toolName, + List events) { + String msg = "[审批不可用] 该工具需要人工审批，但当前为非交互（定时任务）运行，无人可批准，" + + "因此无法执行。请改用无需审批的内置工具完成本步骤（例如 PDF / XLSX / 文档技能、文件读写工具），" + + "或跳过该步骤并说明原因，不要反复重试同一命令。"; + log.info("[ToolExecutor] NON_INTERACTIVE_DENY: tool={} needs approval but origin is non-interactive (cron); " + + "denying to avoid an unresolvable pending", toolName); + events.add(GraphEventPublisher.toolComplete(toolCall.id(), toolName, msg, false)); + return GuardDecision.blocked(msg); + } + // ==================== 辅助方法 ==================== /** diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java index 076811d6..2f98eb9c 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/GoalEvaluationNode.java @@ -25,9 +25,8 @@ import java.util.Optional; /** * Sits between FinalAnswerNode (or PlanSummaryNode) and the graph END. * - *

Per RFC 48 v3 §3.3, evaluation runs on a settled terminal answer so - * upstream finishReason / evidence checks are already authoritative. The - * node: + *

Evaluation runs on a settled terminal answer so upstream finishReason / + * evidence checks are already authoritative. The node: *

    *
  1. Bails out for the "this turn shouldn't count" finishReasons * (evidence_insufficient, stopped, error_fallback, return_direct, @@ -50,8 +49,8 @@ public class GoalEvaluationNode implements NodeAction { private final GoalFollowupService followupService; private final GoalService goalService; private final GoalProperties properties; - private final ConversationWindowManager windowManager; // unused PR2, kept for PR5 - private final ConversationService conversationService; // unused PR2, kept for PR5 + private final ConversationWindowManager windowManager; // reserved for evaluator context windowing + private final ConversationService conversationService; // reserved for evaluator context lookups private final GraphFlavor flavor; public GoalEvaluationNode(GoalEvaluationService evaluationService, @@ -72,7 +71,7 @@ public class GoalEvaluationNode implements NodeAction { @Override public Map apply(OverAllState state) throws Exception { - // Master kill switch — node stays inert until PR5 flips this. + // Master kill switch — when disabled the node stays inert. if (!properties.isEnabled()) { return Map.of(); } @@ -186,30 +185,34 @@ public class GoalEvaluationNode implements NodeAction { // failure on completion) does not propagate into the chat graph // and abort the streamed answer the user already sees. try { - if (result.completed() || result.score() >= 0.95) { - goalService.markCompleted(refreshed.getId(), result); + // Completion is the deterministic "all criteria passed" signal the + // evaluator already folded into result.completed() — no score gate. + if (result.completed()) { + GoalEntity completed = goalService.markCompleted(refreshed.getId(), result); return MateClawStateAccessor.output() .goalEvaluationResult(result.toMap()) .goalEvaluatedThisRun(true) .events(List.of(goalEvent("goal_completed", Map.of( - "goalId", String.valueOf(refreshed.getId()), - "score", result.score())))) + "goalId", String.valueOf(completed.getId()), + "score", result.score(), + "goal", goalService.toResponse(completed))))) .build(); } if (goalService.isBudgetExhausted(refreshed)) { String reason = goalService.exhaustionReason(refreshed); - goalService.markExhausted(refreshed.getId(), reason); + GoalEntity exhausted = goalService.markExhausted(refreshed.getId(), reason); return MateClawStateAccessor.output() .goalEvaluationResult(result.toMap()) .goalEvaluatedThisRun(true) .events(List.of(goalEvent("goal_exhausted", Map.of( - "goalId", String.valueOf(refreshed.getId()), - "turnsUsed", refreshed.getTurnsUsed(), - "agentLlmCallsUsed", refreshed.getAgentLlmCallsUsed(), - "evalLlmCallsUsed", refreshed.getEvalLlmCallsUsed(), - "totalLlmCallsUsed", refreshed.totalLlmCallsUsed(), - "reason", reason)))) + "goalId", String.valueOf(exhausted.getId()), + "turnsUsed", exhausted.getTurnsUsed(), + "agentLlmCallsUsed", exhausted.getAgentLlmCallsUsed(), + "evalLlmCallsUsed", exhausted.getEvalLlmCallsUsed(), + "totalLlmCallsUsed", exhausted.totalLlmCallsUsed(), + "reason", reason, + "goal", goalService.toResponse(exhausted))))) .build(); } } catch (Throwable t) { @@ -270,7 +273,8 @@ public class GoalEvaluationNode implements NodeAction { .needsToolCall(false) .events(List.of(goalEvent("goal_followup", Map.of( "goalId", String.valueOf(refreshed.getId()), - "prompt", followup.get())))); + "prompt", followup.get(), + "goal", goalService.toResponse(refreshed))))); if (flavor == GraphFlavor.REACT) { // ReAct: append the followup as a fresh user message via the @@ -309,7 +313,8 @@ public class GoalEvaluationNode implements NodeAction { .events(List.of(goalEvent("goal_evaluated", Map.of( "goalId", String.valueOf(refreshed.getId()), "score", result.score(), - "gap", result.gap() == null ? "" : result.gap())))) + "gap", result.gap() == null ? "" : result.gap(), + "goal", goalService.toResponse(refreshed))))) .build(); } diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java index 3ee70aed..b92c6999 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/node/ReasoningNode.java @@ -21,7 +21,10 @@ import vip.mate.agent.GraphEventPublisher; import vip.mate.llm.chatmodel.ThinkingLevelHolder; import vip.mate.agent.graph.NodeStreamingChatHelper; import vip.mate.agent.context.ConversationWindowManager; +import vip.mate.agent.context.LoopBudgetConfig; +import vip.mate.agent.context.LoopMessageBudgeter; import vip.mate.agent.context.RuntimeContextInjector; +import vip.mate.agent.context.TokenEstimator; import vip.mate.agent.graph.state.FinishReason; import vip.mate.agent.graph.state.MateClawStateAccessor; import vip.mate.agent.graph.state.MateClawStateKeys; @@ -71,6 +74,36 @@ public class ReasoningNode implements NodeAction { */ private static final int DEFAULT_MAX_OUTPUT_TOKENS = 16384; + /** + * Stateless singleton used to budget the per-iteration working message + * list. Static-final because the budgeter holds no mutable state — the + * choice keeps the existing ReasoningNode constructor surface unchanged + * (it already carries 13 parameters across 5 overloads) and makes the + * dependency obvious to anyone reading the class. + */ + private static final LoopMessageBudgeter LOOP_BUDGETER = new LoopMessageBudgeter(); + + /** + * Fallback context window used when no provider-level value is wired in. + * Calibrated to the same default {@code ConversationWindowProperties} + * uses for its multi-turn budget so the two layers stay in sync. Models + * with smaller windows still benefit — the budgeter triggers earlier on + * raw message volume via {@code absoluteMaxMessages}. + */ + private static final int DEFAULT_LOOP_CONTEXT_WINDOW_TOKENS = 128_000; + + /** + * Conservative buffer added to the per-loop budget's reservedPrefixTokens + * to cover non-history prompt segments that are appended after + * the budget runs: the runtime-rendered skill catalog, runtime-context + * snapshot, wiki injection, progress ledger snapshot, and assorted + * marker SystemMessages. Underestimating here only delays the trigger + * slightly; loop invariants (anchor preservation, tool-pair integrity) + * are unaffected. Sized for a typical agent with 20–30 skills and + * moderate wiki content. + */ + private static final int LOOP_PREFIX_AUXILIARY_RESERVE_TOKENS = 4_000; + /** * DashScope's native chat API caps {@code max_tokens} at 8192 and returns a * 400 {@code InvalidParameter} ("Range of max_tokens should be [1, 8192]") @@ -319,6 +352,20 @@ public class ReasoningNode implements NodeAction { this.progressLedgerService = progressLedgerService; } + /** + * Context window used by the per-loop budgeter. Returns the + * conversation-window manager's effective max input tokens when one is + * wired in (so L1 and L2 stay calibrated to the same model window), + * otherwise the documented fallback. + */ + private int loopContextWindowTokens() { + if (conversationWindowManager != null) { + int v = conversationWindowManager.getDefaultMaxInputTokens(); + if (v > 0) return v; + } + return DEFAULT_LOOP_CONTEXT_WINDOW_TOKENS; + } + public ReasoningNode(ChatModel chatModel, AgentToolSet toolSet, String reasoningEffort, NodeStreamingChatHelper streamingHelper, ConversationWindowManager conversationWindowManager) { @@ -414,81 +461,50 @@ public class ReasoningNode implements NodeAction { systemPrompt = systemPrompt + TOOL_USE_ENFORCEMENT; List messages = accessor.messages(); - // Guard against runaway message list growth. + // Per-loop budget: bound the working message list a single Reasoning + // iteration hands to the LLM. The previous fixed head=4 + tail=36 cut + // could lose the latest UserMessage once the ReAct loop accumulated + // tool calls/observations past ~70 messages — the user's question + // fell into the dropped middle, the LLM lost it, and the agent + // answered off-topic. LoopMessageBudgeter anchors the latest + // UserMessage as undroppable, sizes the tail by token budget instead + // of message count, and keeps the same bidirectional tool-pair + // integrity guard the old block already had. The L2 trim here is + // distinct from ConversationWindowManager (L1): L1 runs once per + // user turn and produces an LLM summary for multi-turn history; L2 + // runs per reasoning iteration on what L1 already produced plus + // intra-turn tool-call growth. // - // CRITICAL: a naive head+tail cut can break the OpenAI-compatible protocol invariant - // that requires tool_call / tool_response pairs to be complete: - // - // P0 (originally observed): AssistantMessage(tool_calls) falls into the dropped gap, - // its ToolResponseMessage lands in the kept tail → provider sees an orphaned - // ToolResponseMessage → kimi-code 400 "tool_call_id is not found". - // - // P1 (symmetric): AssistantMessage(tool_calls) is kept in the head at the boundary, - // its ToolResponseMessage falls into the dropped gap → provider sees an assistant - // tool_call with no matching response → also a 400 on strict providers. - // - // Fix: perform the normal cut, then run an iterative bidirectional integrity pass until - // the list is stable: - // • Remove any ToolResponseMessage whose parent AssistantMessage.tool_calls id was - // dropped (P0). - // • Remove any AssistantMessage whose tool_calls have no matching ToolResponseMessage - // (P1). - // Iterate because a P1 removal could expose a new P0 orphan (and vice versa, though that - // is pathological in practice). With ≤40 messages convergence is always fast. - // Dropping incomplete pairs is safe — prior iterations already processed those - // observations; the LLM needs the summary context, not the raw tool I/O. - final int MAX_LOOP_MESSAGES = 40; - if (messages.size() > MAX_LOOP_MESSAGES) { - log.warn("[ReasoningNode] Messages list too large ({} messages), trimming to {} for conversation {}", - messages.size(), MAX_LOOP_MESSAGES, conversationId); - int headKeep = Math.min(4, messages.size()); - int tailKeep = MAX_LOOP_MESSAGES - headKeep; - int tailStart = messages.size() - tailKeep; - - List trimmed = new ArrayList<>(MAX_LOOP_MESSAGES); - trimmed.addAll(messages.subList(0, headKeep)); - trimmed.addAll(messages.subList(tailStart, messages.size())); - - // Iterative bidirectional integrity pass. - int totalRemoved = 0; - boolean changed; - do { - // Snapshot current tool_call ids and response ids. - Set callIds = new java.util.HashSet<>(); - Set respIds = new java.util.HashSet<>(); - for (Message m : trimmed) { - if (m instanceof AssistantMessage am && am.getToolCalls() != null) { - for (AssistantMessage.ToolCall tc : am.getToolCalls()) callIds.add(tc.id()); - } - if (m instanceof ToolResponseMessage trm) { - for (ToolResponseMessage.ToolResponse r : trm.getResponses()) respIds.add(r.id()); - } - } - int before = trimmed.size(); - trimmed.removeIf(m -> { - // P0: ToolResponseMessage whose parent tool_call was dropped - if (m instanceof ToolResponseMessage trm) { - return trm.getResponses().stream().anyMatch(r -> !callIds.contains(r.id())); - } - // P1: AssistantMessage whose tool_call has no ToolResponseMessage - if (m instanceof AssistantMessage am && am.getToolCalls() != null - && !am.getToolCalls().isEmpty()) { - return am.getToolCalls().stream().anyMatch(tc -> !respIds.contains(tc.id())); - } - return false; - }); - int removed = before - trimmed.size(); - totalRemoved += removed; - changed = removed > 0; - } while (changed); - - if (totalRemoved > 0) { - log.warn("[ReasoningNode] Removed {} message(s) with broken tool_call/response pairs " - + "after trim (bidirectional integrity guard), conv={}", totalRemoved, conversationId); - } - - messages = trimmed; + // Reserved prefix tokens cover the non-history portion of the + // prompt the LLM will receive: system prompt (with tool-use + // enforcement already appended), tool schemas, output reserve, + // and a buffer for skill catalog + runtime context + wiki + // injections that are added downstream. Underestimating here only + // delays the trigger slightly — invariants (anchor, pair integrity) + // still hold once budget fires. + int systemTokens = TokenEstimator.estimateTokens(systemPrompt); + int toolsTokens = TokenEstimator.estimateToolsTokens(toolCallbacks); + int loopReservedPrefixTokens = systemTokens + toolsTokens + + maxOutputTokens + LOOP_PREFIX_AUXILIARY_RESERVE_TOKENS; + LoopBudgetConfig loopCfg = LoopBudgetConfig.forContext(loopContextWindowTokens()) + .withReservedPrefixTokens(loopReservedPrefixTokens); + LoopMessageBudgeter.Result budgeted = LOOP_BUDGETER.budget(messages, loopCfg); + // Only log when the budget actually modified the list — a triggered- + // but-no-op pass is normal (history fits comfortably under the tail + // budget) and would otherwise spam logs every iteration. + if (budgeted.trace().modified()) { + LoopMessageBudgeter.BudgetTrace t = budgeted.trace(); + log.warn("[ReasoningNode] Loop budget trim: {} -> {} msgs (history {} -> {} tokens, " + + "prefix~{}), head={}, tail={}, droppedMiddle={}, orphans={}, " + + "anchorEnforced={}, anchorStitched={}, targetMaxTripped={}, " + + "capExceededForPairIntegrity={}, minTailFloorApplied={}, conv={}", + t.originalCount(), t.finalCount(), t.originalTokens(), t.finalTokens(), + t.reservedPrefixTokens(), + t.headKept(), t.tailKept(), t.droppedMiddle(), t.orphansRemoved(), + t.anchorEnforced(), t.anchorStitched(), t.targetMaxTripped(), + t.capExceededForPairIntegrity(), t.minTailFloorApplied(), conversationId); } + messages = budgeted.messages(); String workspaceBasePath = state.value(vip.mate.agent.graph.state.MateClawStateKeys.WORKSPACE_BASE_PATH, ""); String agentIdStr = state.value(MateClawStateKeys.AGENT_ID, ""); @@ -955,7 +971,17 @@ public class ReasoningNode implements NodeAction { List prefix = new ArrayList<>(); prefix.add(new SystemMessage(systemPrompt)); prefix.add(new UserMessage(RuntimeContextInjector.buildContextMessage(workspaceBasePath, null, chatOrigin))); - if (wikiContextService != null && agentIdStr != null && !agentIdStr.isEmpty()) { + // When this turn already recalled the user's own current project from + // structured memory, skip auto-injecting knowledge-base reference context. + // Otherwise the KB pages (reference material, possibly about unrelated + // projects) compete with — and tend to override — the user's actual + // project identity. The agent can still query the wiki on demand. + boolean projectRecalled = userMsg != null + && userMsg.contains(vip.mate.memory.service.StructuredMemoryService.PROJECT_RECALLED_MARKER); + if (projectRecalled) { + log.debug("[ReasoningNode] Skipping wiki-relevant injection: user's project was recalled from memory this turn"); + } + if (!projectRecalled && wikiContextService != null && agentIdStr != null && !agentIdStr.isEmpty()) { try { Long parsedAgentId = Long.parseLong(agentIdStr); String wikiRelevant = wikiContextService.buildRelevantContext(parsedAgentId, userMsg); diff --git a/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/PlanGenerationNode.java b/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/PlanGenerationNode.java index 104259e3..7d4ed73e 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/PlanGenerationNode.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/graph/plan/node/PlanGenerationNode.java @@ -70,26 +70,30 @@ public class PlanGenerationNode implements NodeAction { 硬性规则： 1. 只返回一个 JSON 对象；不允许 markdown 代码块、不允许任何 JSON 以外的文字。 2. 不要解释，不要寒暄，不要说"我来...""我先..."。 - 3. 不确定时优先选择"单步"，而不是拆成多步。 + 3. 判断依据是"目标是否由多个明显独立的子任务/交付物组成"，而不是难度高低： + 单个连贯动作不要拆，但目标确实分成多个部分时也不要硬压成一步。 三类分流： - (A) 直接回答 — 纯知识问答，模型凭自身知识即可回答，不需要任何工具、不需要读文件、不需要查询当前状态。 + (A) 直接回答 — 简单的纯知识问答：凭自身知识用一两段话即可答完，不需要任何工具、不需要读文件、 + 不需要查询当前状态，且目标本身不包含多个需要分别完成的子任务。 + （注意：成段的分析、对比、方案、规划、教程等通常不属于此类，应走 B 或 C。） 输出：{"needs_planning": false, "direct_answer": "<你的回答>"} - (B) 单步任务 — 需要工具，但本质是一个连贯动作（一次文件读取 / 一次搜索 / 一次命令 / 一次记忆读写 / 一次计算）。 - 执行器会在这一步内部迭代调用多次工具，你**不要**提前拆分。 + (B) 单步任务 — 本质是一个连贯动作（一次文件读取 / 一次搜索 / 一次命令 / 一次记忆读写 / 一次计算 / + 一段集中产出）。执行器会在这一步内部迭代调用多次工具，你**不要**提前拆分。 输出：{"needs_planning": true, "steps": ["<将用户目标复述为一句清晰可执行的指令>"]} - (C) 多步任务 — 用户目标包含 2 个及以上明显独立、必须先后完成的子任务（例如"先调研 A 再调研 B 然后对比"、 - "读配置、迁移数据、验证结果"）。子任务之间如果可以合并，应当合并。 + (C) 多步任务 — 用户目标包含 2 个及以上明显独立、需要先后完成的子任务或交付物（例如"先调研 A 再调研 B + 然后对比"、"读配置、迁移数据、验证结果"、"分阶段制定计划"、"产出由若干独立部分组成的方案"）。 + 这是规划型智能体的主路径——当目标确实由多个部分组成时就走这里。 输出：{"needs_planning": true, "steps": ["步骤1", "步骤2", ...]}（2 到 6 个步骤） 关键原则： - 单工具调用绝对不拆成多步。例："读 A 文件并总结" 是单步（B），不是两步。 - 默认不要把 MEMORY.md / PROFILE.md / 技能文件读取当成独立步骤；仅当用户明确询问偏好、历史决策或长期约束时才加入。 - 每个步骤必须是可执行动作，不写"思考一下""确认一下"之类的空话。 - - 解析不出来时，视作(B) 单步；宁愿单步也不要无脑拆分。 + - 多部分、多阶段、需要逐步推进的目标走(C)；真正单一原子动作走(B)；只有简单一问一答才用(A)。 """; public PlanGenerationNode(ChatModel chatModel, PlanningService planningService, diff --git a/mateclaw-server/src/main/java/vip/mate/agent/model/AgentEntity.java b/mateclaw-server/src/main/java/vip/mate/agent/model/AgentEntity.java index 0654f451..65437dca 100644 --- a/mateclaw-server/src/main/java/vip/mate/agent/model/AgentEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/agent/model/AgentEntity.java @@ -78,6 +78,59 @@ public class AgentEntity { /** 默认思考深度：off / low / medium / high / max，null 表示跟随模型默认 */ private String defaultThinkingLevel; + /** + * Agent-level working directory override. When non-blank, takes priority + * over the workspace's basePath; relative values are resolved under the + * workspace basePath. Null/blank means inherit the workspace value. + */ + @TableField(value = "workspace_base_path", updateStrategy = FieldStrategy.ALWAYS) + private String workspaceBasePath; + + /** + * Agent's primary wiki knowledge base. This is a per-agent default target + * for wiki tools; it does not affect KB visibility or ownership. + * Null means no explicit primary KB, so wiki resolution falls back to the + * workspace's most recently updated KB. + */ + @TableField(value = "primary_kb_id", updateStrategy = FieldStrategy.ALWAYS) + private Long primaryKbId; + + /** + * Explicit opt-out from every skill. When {@code true}, the binding service + * returns {@link java.util.Collections#emptySet()} from + * {@code getBoundSkillIds}, which (a) suppresses every {@code SKILL.md} + * catalog entry from the system prompt and (b) drops skill-expanded tools + * out of the effective tool set. + * + *

    Default {@code false} preserves the legacy "zero rows = inherit global + * default" behaviour for every legacy agent. The flag is auto-cleared when + * a non-empty skill binding is written, so the data layer never holds a + * "{@code disabled=true} + binding rows" contradiction. + * + *

    Default {@code NOT_NULL} update strategy is deliberate: a frontend + * PUT that explicitly carries {@code true} or {@code false} writes through + * (both are non-null Boolean), while a sparse partial update (e.g. the + * auto-clear helper that constructs a one-field entity) won't emit the + * other flag's column as a stray {@code SET ... = NULL} that would + * collide with the {@code NOT NULL} DDL. + */ + @TableField(value = "skills_disabled") + private Boolean skillsDisabled; + + /** + * Explicit opt-out from every non-system-level tool. When {@code true}, + * {@code getBoundToolNames} returns {@link java.util.Collections#emptySet()} + * and the MCP auto-include in {@code getEffectiveToolNames} is suppressed; + * the structured-memory primitives (record_lesson / remember / workspace + * memory CRUD) still pass through because they are agent-internal + * capabilities unrelated to the user-facing capability picker. + * + *

    Same defaulting / auto-clear / update strategy contract as + * {@link #skillsDisabled}. + */ + @TableField(value = "tools_disabled") + private Boolean toolsDisabled; + @TableField(fill = FieldFill.INSERT) private LocalDateTime createTime; diff --git a/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java b/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java index 839143ca..fe40501d 100644 --- a/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java +++ b/mateclaw-server/src/main/java/vip/mate/approval/ApprovalWorkflowService.java @@ -20,6 +20,7 @@ import org.springframework.transaction.support.TransactionSynchronization; import org.springframework.transaction.support.TransactionSynchronizationManager; import vip.mate.agent.context.ChatOrigin; import vip.mate.agent.context.ChatOriginHolder; +import vip.mate.approval.event.ApprovalResolutionEvent; import vip.mate.approval.event.WorkflowApprovalResolvedEvent; import vip.mate.approval.model.ToolApprovalEntity; import vip.mate.approval.repository.ToolApprovalMapper; @@ -707,6 +708,41 @@ public class ApprovalWorkflowService implements ApplicationRunner { } } + // Phase 5 — generic resolution event so the auto-grant resolution log + // can record this final decision. Distinct from the workflow-bridge + // event above: this fires for EVERY resolved approval (not just wf-*), + // and its consumer writes one mate_approval_resolution_log row. + // SUPERSEDED is not a user decision — the replacement pending will fire + // its own event when it resolves, so we skip the event here. + if (events != null && !"SUPERSEDED".equals(dbStatus)) { + String decisionSource = "TIMEOUT".equals(dbStatus) + ? "TIMEOUT" + : "USER_MANUAL"; + String note = "USER_MANUAL".equals(decisionSource) && "DENIED".equals(dbStatus) + ? "denied" + : null; + ApprovalResolutionEvent resolutionEvent = new ApprovalResolutionEvent( + snapshot.getPendingId(), + snapshot.getConversationId(), + snapshot.getAgentId(), + /* userId resolves to actor or original requester */ + userId != null ? userId : snapshot.getUserId(), + snapshot.getToolName(), + snapshot.getToolArguments(), + snapshot.getMaxSeverity(), + snapshot.getFindingsJson(), + decisionSource, + note); + afterCommit(() -> { + try { + events.publishEvent(resolutionEvent); + } catch (Exception e) { + log.warn("[ApprovalWorkflow] failed to publish ApprovalResolutionEvent for {}: {}", + snapshot.getPendingId(), e.getMessage()); + } + }); + } + boolean consumed = "consumed".equals(snapshotStatus); ResolveOutcome outcome = consumed ? ResolveOutcome.consumed(snapshot, true, rewritten) diff --git a/mateclaw-server/src/main/java/vip/mate/approval/event/ApprovalResolutionEvent.java b/mateclaw-server/src/main/java/vip/mate/approval/event/ApprovalResolutionEvent.java new file mode 100644 index 00000000..68e958fb --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/event/ApprovalResolutionEvent.java @@ -0,0 +1,41 @@ +package vip.mate.approval.event; + +/** + * Generic application event fired AFTER an approval row reaches a final + * decision through the human-approval path (approved / denied / consumed) or + * through the timeout sweep. + *

    + * Distinct from {@code WorkflowApprovalResolvedEvent}, which is workflow-bridge + * specific (only published for {@code pendingId} starting with {@code "wf-"}). + * This event is published for every tool-call approval row so the auto-grant + * resolution-log subsystem can record exactly one row per final decision. + * + *

    Decision source mapping (see {@code ApprovalResolutionLog.DecisionSource}): + *

      + *
    • {@code APPROVED} / {@code DENIED} / {@code CONSUMED} → {@code USER_MANUAL}
      • + *
    • {@code TIMEOUT} → {@code TIMEOUT}
      • + *
    • {@code SUPERSEDED} → no event (not a final user decision; the replacement + * approval will fire its own event when it resolves)
      • + *
    + * + *

    {@code findingsJson} is the original JSON serialization of the + * {@code GuardEvaluation.findings} captured at {@code createPending} time. + * The listener extracts {@code ruleId}s from it for {@code resolution_log.rule_ids}. + * + *

    All fields are nullable: a row created via the legacy command-injection + * path may not carry every snapshot field. The listener treats missing fields + * as empty rather than skipping the row, so the resolution-log audit stays + * complete even when upstream context is partial. + */ +public record ApprovalResolutionEvent( + String pendingId, + String conversationId, + String agentId, + String userId, + String toolName, + String toolArguments, + String maxSeverity, + String findingsJson, + String decisionSource, + String resolutionNote +) {} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveAuditLogger.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveAuditLogger.java new file mode 100644 index 00000000..d853957c --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveAuditLogger.java @@ -0,0 +1,76 @@ +package vip.mate.approval.grant; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; +import vip.mate.approval.grant.entity.ApprovalGrant; +import vip.mate.tool.guard.model.GuardEvaluation; +import vip.mate.tool.guard.model.ToolInvocationContext; + +/** + * WARN-level audit logger for the three resolver outcomes that need operator + * visibility: AUTO_GRANT (a stored grant let a tool through), HARD_BLOCK (the + * safety floor blocked a disaster) and FORCE_HUMAN (a dangerous pattern was + * downgraded back to manual approval). + *

    + * The logger is intentionally a separate bean with a fixed name + * ({@code vip.mate.approval.grant.AutoApproveAuditLogger}) so operations can + * filter / route just this signal without grepping through generic guard logs. + * Arguments are truncated to 200 characters to keep each entry to one line; the + * DB column {@code mate_approval_resolution_log.args_preview} stores up to 500 + * for the detail page. + */ +@Slf4j +@Component +public class AutoApproveAuditLogger { + + private static final int LOG_ARGS_MAX = 200; + + public void logAutoGrant(ApprovalGrant grant, ToolInvocationContext ctx, GuardEvaluation evaluation) { + log.warn("[APPROVAL] AUTO_GRANT grantId={} tool={} severity={} (ceiling={}) " + + "scope={}/{} workspaceId={} args({})={} userId={} conversationId={} ruleId={}", + grant.getId(), + ctx.toolName(), + severityName(evaluation), + grant.getMaxSeverity(), + grant.getScopeType(), grant.getScopeId(), + ctx.workspaceId(), + LOG_ARGS_MAX, truncate(ctx.rawArguments()), + ctx.userId(), ctx.conversationId(), + primaryRuleId(evaluation)); + } + + public void logHardBlock(ToolInvocationContext ctx, GuardEvaluation evaluation, String patternName) { + log.warn("[APPROVAL] HARD_BLOCK pattern={} tool={} args({})={} userId={} conversationId={}", + patternName, + ctx.toolName(), + LOG_ARGS_MAX, truncate(ctx.rawArguments()), + ctx.userId(), ctx.conversationId()); + } + + public void logForceHuman(ToolInvocationContext ctx, GuardEvaluation evaluation, String patternName) { + log.warn("[APPROVAL] FORCE_HUMAN pattern={} tool={} args({})={} userId={} conversationId={} " + + "— falling back to existing approval flow", + patternName, + ctx.toolName(), + LOG_ARGS_MAX, truncate(ctx.rawArguments()), + ctx.userId(), ctx.conversationId()); + } + + private static String truncate(String s) { + if (s == null) return ""; + return s.length() <= LOG_ARGS_MAX ? s : s.substring(0, LOG_ARGS_MAX) + "…"; + } + + private static String severityName(GuardEvaluation evaluation) { + return evaluation == null || evaluation.maxSeverity() == null + ? "UNKNOWN" + : evaluation.maxSeverity().name(); + } + + private static String primaryRuleId(GuardEvaluation evaluation) { + if (evaluation == null || evaluation.findings() == null || evaluation.findings().isEmpty()) { + return null; + } + return evaluation.findings().get(0).ruleId(); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveResult.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveResult.java new file mode 100644 index 00000000..f51c4639 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoApproveResult.java @@ -0,0 +1,58 @@ +package vip.mate.approval.grant; + +/** + * Tri-state outcome of {@code ApprovalGrantResolver.tryAutoApprove(...)}. + *

    + * The resolver never throws on a missing grant or a fallback condition; it + * returns one of these three states and lets the caller + * ({@code ToolExecutionExecutor.evaluateGuard()}) map them to the right + * {@code GuardDecision}. + * + *

      + *
    • {@link #approved(Long)} — caller skips {@code createPending(...)} and + * runs the tool directly. Carries the matched grant id.
      • + *
    • {@link #hardBlocked(String)} — caller returns + * {@code GuardDecision.blocked(...)}. No approval banner. Carries the + * hard-floor pattern name for log/audit context.
      • + *
    • {@link #requiresHuman(String)} — caller falls back to the existing + * human approval flow. The {@code reason} is a short tag (e.g. + * {@code "FORCE_HUMAN:pipe_shell"}, {@code "SEVERITY_CRITICAL"}, + * {@code "UNKNOWN_WORKSPACE"}, {@code "NO_GRANT"}) for logging.
      • + *
    + */ +public final class AutoApproveResult { + + private enum State { APPROVED, HARD_BLOCKED, REQUIRES_HUMAN } + + private final State state; + private final Long grantId; + private final String reason; + + private AutoApproveResult(State state, Long grantId, String reason) { + this.state = state; + this.grantId = grantId; + this.reason = reason; + } + + public static AutoApproveResult approved(Long grantId) { + return new AutoApproveResult(State.APPROVED, grantId, null); + } + + public static AutoApproveResult hardBlocked(String reason) { + return new AutoApproveResult(State.HARD_BLOCKED, null, reason); + } + + public static AutoApproveResult requiresHuman(String reason) { + return new AutoApproveResult(State.REQUIRES_HUMAN, null, reason); + } + + public boolean isApproved() { return state == State.APPROVED; } + public boolean isHardBlocked() { return state == State.HARD_BLOCKED; } + public boolean isRequiresHuman() { return state == State.REQUIRES_HUMAN; } + + /** Non-null only when {@link #isApproved()} is true. */ + public Long grantId() { return grantId; } + + /** Non-null when {@link #isHardBlocked()} or {@link #isRequiresHuman()}. */ + public String reason() { return reason; } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoGrantSafetyFloor.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/AutoGrantSafetyFloor.java new file mode 100644 index 0000000000000000000000000000000000000000..7c0546be7d611e544c1857a382766b0bc0b7c65b GIT binary patch literal 6480 zcmcIpQF7bJ5zV)*us;)dYZsJ7P_E5SY|Az+QI>aQNfG5uRVbMOfgw2-fWgiHq-c>< zxj_DMom?gt$QAN>Fav;+&Gn`deHbJ-)7{hky8HDw3&NXV!r4q@eiG!|53)?jSrGdZ z6{PvItu2vcQswMpa1*FJ@Pjm!d5{a4`sY&T2Qt;UDnhKZ3uBp#*|b&mq!3l`08h@rkQS+{XYv z7P*N16QOH6>eq@-_^p2)rpSES`8<0;kIT7ax!_7aH7|?Uyk+cpEMDBbibZV$(Q)_UaQOP< z?BJ&r``6$8!6KmpIAMIOm{+Va`ul(R61W3E_U zsFbV{nu#=rT~5cFB2dvG4~3@Ck760#@W}IhzqNW+3vHfc1gJnFBojf$MfFbqgBj9jpoPed*Vt+iq=6B%#kvaP2)jw{dT zB9g4#hjSuc;#ABy>;LJbT5;Gr>0S0#Y%cPtEb>~S_3fXJdl$VGoYb{A2u%jCpn$S6 zY8?LJnm?llfCL-a2x-OOKD?}2&s7H9yB8cml1AB9($=TBazabVW>QN}O#o5@aQ|dqhEe6{V3(M^}`E4dOw$B8gQ{Y9C6nQX;xz8?& z6fpzNWI7fTrg$uaNYhbKPZ%xBjUUZvcF7nrQQru7v%^r6k}QW=A4{!npW;C{CGG6T zpWm5-LGl=-Bn>&Gs`XY^O^O5+rSwwjYDkskz*0CR*LdC2{#(X%7-XCQFe2M!r|(Z7 zG@+unOY+{Q!sOxU(N71h^6>nBZj=~Cw0XZq;?J~Pu+K?XLD_fIjVsSr(QHyQnmJ+IBO^I8bl@vG1*q2P1 zqK>vr{j5$-me~566gsDRsq%IxR9J|d%7_KWh8nzPMcr&;gt>1O59~7V4NdPA*j^=h?PaS z15oeF!Y-}7=6Z^N;?%-eiUM?hgH`Sups*CF*+T2Gf7VI#?N`(qEFDv!ws`-N`6TNr z%xPj~P1Jv59HHwqHRu10Z8eg1zi1jAvxZpd&>a)m40VO-=|Q8W@?Q!n&YF4sHy5bv zp^U-1@GO*;s^xf>!#%6YBm<22<_1#=jiBD^Z`Z- z_SyT#dwWk_(;3V%^hzf$5+D+?0RR=ZT}@`f4bgAW|^&^`9>Ad zi072wkrncSRZuN)zF}pZaaQW9wb8>Unn@8cM|B!Cq|;%Cj%`0hS)iuUC+H2Xcz`ew{{mLUiEIAC0HoVJx zmSe9{Z{xwJ@-1(X@tR9XG zeIY{MOfjmYNewkfrID^V>|iWH9dy%Fz;uS`XN;bom6?Jzinf7-sO&WPQrCswm@qUf z4$Y)k2gF1b-WqhSuIAS}off%n6trIIDL%lN%Ws$Ma1(&g!s4M7ZRApzv6tR2=M$cj zuPsD3Xxk8c3hPkkC?2)lBNuCEYWJaG*#=X`5`5fbt^Oq*MoMN@5>n86Dab;|IlMSK zUtV6kKRxJP_9z1$UZ|^!K z<=9PBGl)>rXf!(}WdzDUQ?+a7e!&o9n??w(vX*&g};UF|%r zTg?95%JG--RwU$x!8PA+KRiWMkbR9SCl3=`4LSSDQpkq{s2o1f;U|H>9hspMbVH-L zGDA1bCDmB!{n$S{#YIiDAZ|`1JC_nn042jUi5+(QU~(wuSPWLfiloBWdTH+iwcn;j%XnxV8nsT=W+q&frw%>eTm1Dn+jp=Dl^qOde$ z4Gi5kl8&5au*uxQpqZC*k@AcYEg!ThdU&)=$E)B*a;djtdwp2ixvCPP{`3XAYoz}F z4X<_mCdt~tQ? z$1Etlxx=EW%Q+rRynN%8iyKt#4=C#l+rskmaBO0>86*2%(`^o2#_gLa%5n1hFjG8> zgOGRQ*xM%B?J}aV-F@`!S`c^e_Psrn{8MqH~xuyIgeDuvdSgF?r z%TakdU##bpp{#v#QDpdQbqQdu>6?CN%+5^_9%aVvgJGoH{-7MQ%Ob-Zg=pJEWtbCa jQnEu#gfP>854f8oXS= + * The conversation→workspace mapping is immutable once a conversation is created, + * so a 5-minute TTL is purely a bound on cache size, not a correctness guard. + * Cache misses query MyBatis with a {@code LambdaQueryWrapper} on the + * {@code conversation_id} business column — calling + * {@code conversationMapper.selectById(stringConversationId)} would interpret the + * string as the {@code Long} {@code @TableId} primary key and silently miss every + * row, which would route every tool call to {@code UNKNOWN_WORKSPACE} and disable + * auto-grant entirely. + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class WorkspaceLookupCache { + + private final ConversationMapper conversationMapper; + + private final Cache cache = Caffeine.newBuilder() + .maximumSize(5_000) + .expireAfterWrite(Duration.ofMinutes(5)) + .build(); + + /** + * Returns the workspaceId for the given business conversation id, or {@code null} + * if the conversation does not exist (or was soft-deleted). + */ + public Long resolveByConversation(String conversationId) { + if (conversationId == null || conversationId.isEmpty()) { + return null; + } + return cache.get(conversationId, id -> { + ConversationEntity conv = conversationMapper.selectOne( + Wrappers.lambdaQuery() + .eq(ConversationEntity::getConversationId, id) + .eq(ConversationEntity::getDeleted, 0) + .last("LIMIT 1") + ); + if (conv == null) { + log.debug("[APPROVAL] WorkspaceLookupCache: conversation {} not found, returning null", id); + return null; + } + return conv.getWorkspaceId(); + }); + } + + /** + * Drops a single mapping. Called by the lifecycle listener on + * {@code ConversationDeletedEvent} so a re-created conversation with the same id + * does not inherit a stale workspace. + */ + public void invalidate(String conversationId) { + if (conversationId != null) { + cache.invalidate(conversationId); + } + } + + /** Test hook. */ + long estimatedSize() { + return cache.estimatedSize(); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/controller/ApprovalGrantController.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/controller/ApprovalGrantController.java new file mode 100644 index 00000000..6074c80b --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/controller/ApprovalGrantController.java @@ -0,0 +1,399 @@ +package vip.mate.approval.grant.controller; + +import com.baomidou.mybatisplus.core.metadata.IPage; +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import com.baomidou.mybatisplus.extension.plugins.pagination.Page; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.tags.Tag; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.security.core.Authentication; +import org.springframework.web.bind.annotation.*; +import vip.mate.approval.grant.entity.ApprovalGrant; +import vip.mate.approval.grant.entity.ApprovalResolutionLog; +import vip.mate.approval.grant.repository.ApprovalGrantMapper; +import vip.mate.approval.grant.repository.ApprovalResolutionLogMapper; +import vip.mate.approval.grant.service.ApprovalGrantService; +import vip.mate.auth.model.UserEntity; +import vip.mate.auth.repository.UserMapper; +import vip.mate.auth.service.AuthService; +import vip.mate.common.result.R; +import vip.mate.exception.MateClawException; +import vip.mate.workspace.core.annotation.RequireWorkspaceRole; +import vip.mate.workspace.core.service.WorkspaceService; + +import java.time.LocalDateTime; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +/** + * REST surface for the auto-grant subsystem. + *

    + * The header {@code @RequireWorkspaceRole("member")} is the minimum gate; the + * §2.4.5 6-cell authorization matrix is enforced inside each handler: + *

      + *
    • {@code CONVERSATION} scope — any workspace member.
      • + *
    • {@code USER} scope — only the actor can create a grant for themselves.
      • + *
    • {@code AGENT} scope with explicit {@code toolName} — agent owner or admin.
      • + *
    • {@code AGENT} scope with {@code toolName=null} — admin only, plus password.
      • + *
    • {@code WORKSPACE} scope with explicit {@code toolName} — admin only.
      • + *
    • {@code WORKSPACE} scope with {@code toolName=null} — admin only, plus password.
      • + *
    + * + *

    Snowflake id fields ({@code id} / {@code grantedBy} / {@code revokedBy} / + * {@code scopeId}) are serialized as strings by the global Jackson config so the + * frontend keeps them as strings end-to-end (see CLAUDE.md precision convention). + */ +@Tag(name = "自动批准策略") +@Slf4j +@RestController +@RequestMapping("/api/v1/approval") +@RequiredArgsConstructor +public class ApprovalGrantController { + + private static final long DEFAULT_WORKSPACE_ID = 1L; + + private final ApprovalGrantService grantService; + private final ApprovalGrantMapper grantMapper; + private final ApprovalResolutionLogMapper resolutionMapper; + private final AuthService authService; + private final UserMapper userMapper; + private final WorkspaceService workspaceService; + + // ─── Create ───────────────────────────────────────────────────────── + + @Operation(summary = "创建自动批准策略") + @PostMapping("/grants") + @RequireWorkspaceRole("member") + public R create(@RequestBody CreateGrantRequest body, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId, + Authentication auth) { + Long actorId = resolveUserId(auth); + Long ws = workspaceId != null ? workspaceId : DEFAULT_WORKSPACE_ID; + + validate(body); + enforceCreationAuthorization(body, actorId, ws); + + ApprovalGrant grant = new ApprovalGrant(); + grant.setWorkspaceId(ws); + grant.setScopeType(body.scopeType); + grant.setScopeId(body.scopeId); + grant.setToolName(emptyToNull(body.toolName)); + grant.setRuleId(emptyToNull(body.ruleId)); + grant.setMaxSeverity(body.maxSeverity); + grant.setGrantKind(body.grantKind); + grant.setExpireAt(body.expireAt); + grant.setGrantedBy(actorId); + grant.setGrantedAt(LocalDateTime.now()); + grant.setRevoked(0); + grant.setDeleted(0); + grant.setNote(body.note); + + grantMapper.insert(grant); + log.info("[APPROVAL] Grant created: id={} scope={}/{} tool={} rule={} ceiling={} kind={} by user={}", + grant.getId(), grant.getScopeType(), grant.getScopeId(), + grant.getToolName(), grant.getRuleId(), grant.getMaxSeverity(), + grant.getGrantKind(), actorId); + return R.ok(grant); + } + + // ─── List ─────────────────────────────────────────────────────────── + + @Operation(summary = "列出当前 workspace 的自动批准策略（分页）") + @GetMapping("/grants") + @RequireWorkspaceRole("member") + public R> list( + @RequestParam(required = false) String scopeType, + @RequestParam(required = false) String toolName, + @RequestParam(required = false) Integer revoked, + @RequestParam(required = false, defaultValue = "false") boolean mine, + @RequestParam(required = false, defaultValue = "1") long page, + @RequestParam(required = false, defaultValue = "20") long size, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId, + Authentication auth) { + Long actorId = resolveUserId(auth); + Long ws = workspaceId != null ? workspaceId : DEFAULT_WORKSPACE_ID; + + // mine=false (看全部) 需要 admin；mine=true 任意 member 可以看自己的 + if (!mine) { + workspaceService.requirePermission(ws, actorId, "admin"); + } + + // Bound page size so a malformed client can't blow up the UI / mapper. + long boundedSize = Math.min(Math.max(size, 1), 200); + long boundedPage = Math.max(page, 1); + + var wrapper = Wrappers.lambdaQuery() + .eq(ApprovalGrant::getWorkspaceId, ws) + .eq(ApprovalGrant::getDeleted, 0) + .orderByDesc(ApprovalGrant::getGrantedAt); + if (scopeType != null && !scopeType.isEmpty()) { + wrapper.eq(ApprovalGrant::getScopeType, scopeType); + } + if (toolName != null && !toolName.isEmpty()) { + wrapper.eq(ApprovalGrant::getToolName, toolName); + } + if (revoked != null) { + wrapper.eq(ApprovalGrant::getRevoked, revoked); + } + if (mine) { + wrapper.eq(ApprovalGrant::getGrantedBy, actorId); + } + Page pageObj = new Page<>(boundedPage, boundedSize); + IPage result = grantMapper.selectPage(pageObj, wrapper); + fillGranterNames(result.getRecords()); + return R.ok(result); + } + + /** + * Batch-loads the display name (nickname → username fallback) for every + * unique {@code grantedBy} id on the page and writes it into the entity's + * transient {@code grantedByName} field. One round-trip via + * {@code selectBatchIds} rather than N queries; the field stays null when + * the source user has since been deleted. + */ + private void fillGranterNames(java.util.List records) { + if (records == null || records.isEmpty()) { + return; + } + java.util.Set userIds = new java.util.HashSet<>(); + for (ApprovalGrant g : records) { + if (g.getGrantedBy() != null) userIds.add(g.getGrantedBy()); + } + if (userIds.isEmpty()) return; + java.util.Map idToName = userMapper.selectBatchIds(userIds).stream() + .collect(java.util.stream.Collectors.toMap( + UserEntity::getId, + u -> u.getNickname() != null && !u.getNickname().isEmpty() + ? u.getNickname() + : u.getUsername(), + (a, b) -> a)); + for (ApprovalGrant g : records) { + if (g.getGrantedBy() != null) { + g.setGrantedByName(idToName.get(g.getGrantedBy())); + } + } + } + + // ─── Active summary (chip "(N)") ──────────────────────────────────── + + @Operation(summary = "当前 workspace 的活跃策略数量摘要") + @GetMapping("/grants/active") + @RequireWorkspaceRole("member") + public R> activeSummary( + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + Long ws = workspaceId != null ? workspaceId : DEFAULT_WORKSPACE_ID; + // Cast to int: this is a per-workspace grant count, never bigger than a + // few hundred. Returning Long here would be serialized as a JSON string + // by the global Long→String serializer (CLAUDE.md precision convention + // for snowflake ids), but count is not a snowflake — the frontend wants + // a real number for the chip badge and `count > 0` checks. + int count = (int) Math.min(grantService.countActiveInWorkspace(ws), Integer.MAX_VALUE); + // hasWorkspaceWide: workspace + tool_name IS NULL — the dangerous one. + Long workspaceWide = grantMapper.selectCount( + Wrappers.lambdaQuery() + .eq(ApprovalGrant::getWorkspaceId, ws) + .eq(ApprovalGrant::getScopeType, ApprovalGrant.ScopeType.WORKSPACE) + .isNull(ApprovalGrant::getToolName) + .eq(ApprovalGrant::getRevoked, 0) + .eq(ApprovalGrant::getDeleted, 0) + .and(w -> w.isNull(ApprovalGrant::getExpireAt) + .or().gt(ApprovalGrant::getExpireAt, LocalDateTime.now()))); + Map out = new HashMap<>(); + out.put("count", count); + out.put("hasWorkspaceWide", workspaceWide != null && workspaceWide > 0); + return R.ok(out); + } + + // ─── Revoke ───────────────────────────────────────────────────────── + + @Operation(summary = "撤销自动批准策略") + @DeleteMapping("/grants/{id}") + @RequireWorkspaceRole("member") + public R revoke(@PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId, + Authentication auth) { + Long actorId = resolveUserId(auth); + Long ws = workspaceId != null ? workspaceId : DEFAULT_WORKSPACE_ID; + + ApprovalGrant existing = grantMapper.selectById(id); + if (existing == null || (existing.getDeleted() != null && existing.getDeleted() == 1)) { + throw new MateClawException("err.approval.grant_not_found", 404, "grant not found"); + } + if (!existing.getWorkspaceId().equals(ws)) { + // Cross-workspace lookup is treated as not-found to avoid leaking existence. + throw new MateClawException("err.approval.grant_not_found", 404, "grant not found"); + } + boolean isOwner = existing.getGrantedBy() != null && existing.getGrantedBy().equals(actorId); + boolean isAdmin = workspaceService.hasPermission(ws, actorId, "admin"); + if (!isOwner && !isAdmin) { + throw new MateClawException("err.approval.revoke_forbidden", 403, + "only the grant owner or a workspace admin can revoke"); + } + grantService.revoke(id, actorId); + log.info("[APPROVAL] Grant revoked: id={} by user={} (owner={}, admin={})", + id, actorId, isOwner, isAdmin); + return R.ok(); + } + + // ─── Resolutions read surface ─────────────────────────────────────── + + @Operation(summary = "查询审批最终决策日志（按 grantId 或 conversationId 过滤）") + @GetMapping("/resolutions") + @RequireWorkspaceRole("member") + public R> listResolutions( + @RequestParam(required = false) Long grantId, + @RequestParam(required = false) String conversationId, + @RequestParam(required = false, defaultValue = "100") int limit, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId, + Authentication auth) { + Long actorId = resolveUserId(auth); + Long ws = workspaceId != null ? workspaceId : DEFAULT_WORKSPACE_ID; + int cappedLimit = Math.min(Math.max(limit, 1), 500); + + // grantId queries are admin-only; conversationId queries (member view) just + // filter by membership of the workspace. + if (grantId != null) { + workspaceService.requirePermission(ws, actorId, "admin"); + } + + var wrapper = Wrappers.lambdaQuery() + .eq(ApprovalResolutionLog::getDeleted, 0) + .eq(ApprovalResolutionLog::getWorkspaceId, ws) + .orderByDesc(ApprovalResolutionLog::getCreateTime) + .last("LIMIT " + cappedLimit); + if (grantId != null) { + wrapper.eq(ApprovalResolutionLog::getGrantId, grantId); + } + if (conversationId != null && !conversationId.isEmpty()) { + wrapper.eq(ApprovalResolutionLog::getConversationId, conversationId); + } + return R.ok(resolutionMapper.selectList(wrapper)); + } + + // ─── Authorization matrix ─────────────────────────────────────────── + + /** + * Enforces the §2.4.5 6-cell matrix. Throws {@link MateClawException} with + * an HTTP 403 status when the actor is not permitted to create this scope. + * Password second-factor is checked for the two cells that require it. + */ + private void enforceCreationAuthorization(CreateGrantRequest body, Long actorId, Long workspaceId) { + String scope = body.scopeType; + boolean toolNull = body.toolName == null || body.toolName.isEmpty(); + boolean isAdmin = workspaceService.hasPermission(workspaceId, actorId, "admin"); + + switch (scope) { + case ApprovalGrant.ScopeType.CONVERSATION -> { + // Any member; nothing extra. + } + case ApprovalGrant.ScopeType.USER -> { + if (body.scopeId == null || !body.scopeId.equals(String.valueOf(actorId))) { + throw new MateClawException("err.approval.user_scope_self_only", 403, + "USER-scope grants can only target the requesting user"); + } + } + case ApprovalGrant.ScopeType.AGENT -> { + if (toolNull) { + requireAdminPlusPassword(isAdmin, body.password, actorId); + } else if (!isAdmin) { + // We don't currently model an "agent owner" surface here, so admin is the safe default. + // (Refining this to support agent owner is a v1.1 follow-up.) + workspaceService.requirePermission(workspaceId, actorId, "admin"); + } + } + case ApprovalGrant.ScopeType.WORKSPACE -> { + workspaceService.requirePermission(workspaceId, actorId, "admin"); + if (toolNull) { + requireAdminPlusPassword(true, body.password, actorId); + } + } + default -> throw new MateClawException("err.approval.invalid_scope", 400, + "unknown scope_type: " + scope); + } + } + + private void requireAdminPlusPassword(boolean isAdmin, String rawPassword, Long actorId) { + if (!isAdmin) { + throw new MateClawException("err.approval.admin_required", 403, "admin role required"); + } + if (rawPassword == null || rawPassword.isEmpty()) { + throw new MateClawException("err.approval.password_required", 403, + "this scope requires password re-confirmation"); + } + authService.verifyCurrentUserPassword(actorId, rawPassword); + } + + // ─── Validation ───────────────────────────────────────────────────── + + private static void validate(CreateGrantRequest body) { + if (body.scopeType == null || body.scopeType.isEmpty()) { + throw new MateClawException("err.approval.scope_type_required", 400, "scope_type is required"); + } + if (body.scopeId == null || body.scopeId.isEmpty()) { + throw new MateClawException("err.approval.scope_id_required", 400, "scope_id is required"); + } + if (body.maxSeverity == null + || !(body.maxSeverity.equals("LOW") || body.maxSeverity.equals("MEDIUM") || body.maxSeverity.equals("HIGH"))) { + // CRITICAL is explicitly rejected so it can never be auto-approvable; the resolver + // enforces the same gate at runtime as a defense in depth. + throw new MateClawException("err.approval.invalid_severity", 400, + "max_severity must be LOW | MEDIUM | HIGH (CRITICAL is not auto-approvable)"); + } + if (body.grantKind == null + || !(body.grantKind.equals("ALWAYS") + || body.grantKind.equals("UNTIL_TIMESTAMP") + || body.grantKind.equals("UNTIL_CONVERSATION_END"))) { + throw new MateClawException("err.approval.invalid_grant_kind", 400, + "grant_kind must be ALWAYS | UNTIL_TIMESTAMP | UNTIL_CONVERSATION_END"); + } + if ("UNTIL_TIMESTAMP".equals(body.grantKind) && body.expireAt == null) { + throw new MateClawException("err.approval.expire_at_required", 400, + "expire_at is required when grant_kind = UNTIL_TIMESTAMP"); + } + if ("UNTIL_CONVERSATION_END".equals(body.grantKind) + && !ApprovalGrant.ScopeType.CONVERSATION.equals(body.scopeType)) { + throw new MateClawException("err.approval.kind_scope_mismatch", 400, + "UNTIL_CONVERSATION_END requires scope_type = CONVERSATION"); + } + } + + // ─── Helpers ──────────────────────────────────────────────────────── + + private Long resolveUserId(Authentication auth) { + if (auth == null || auth.getName() == null) { + throw new MateClawException("err.auth.unauthenticated", 401, "未登录"); + } + UserEntity user = authService.findByUsername(auth.getName()); + if (user == null) { + throw new MateClawException("err.auth.user_not_found", 404, "用户不存在"); + } + return user.getId(); + } + + private static String emptyToNull(String s) { + return s == null || s.isEmpty() ? null : s; + } + + // ─── DTO ──────────────────────────────────────────────────────────── + + /** + * Request body for {@link #create}. Snowflake ids ({@code scopeId}) are + * received as strings to preserve precision through JS; the global Jackson + * coercion accepts numeric JSON too, so existing tools that send numbers + * still work. + */ + public static class CreateGrantRequest { + public String scopeType; + public String scopeId; + public String toolName; + public String ruleId; + public String maxSeverity; + public String grantKind; + public LocalDateTime expireAt; + public String note; + /** Required only for {@code WORKSPACE + tool_name=null} and {@code AGENT + tool_name=null}. */ + public String password; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalGrant.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalGrant.java new file mode 100644 index 00000000..2749ba7a --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalGrant.java @@ -0,0 +1,98 @@ +package vip.mate.approval.grant.entity; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * Auto-approve grant entity. + *

    + * Each row authorizes {@code ApprovalGrantResolver} to skip the manual approval + * step for tool calls matching {@code (scope_type, scope_id, tool_name?, rule_id?)} + * up to a {@code max_severity} ceiling. Hard-floor patterns still block irrespective + * of any grant. + */ +@Data +@TableName("mate_approval_grant") +public class ApprovalGrant { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + private Long workspaceId; + + /** USER | AGENT | CONVERSATION | WORKSPACE — see {@link ScopeType}. */ + private String scopeType; + + /** Snowflake string per CLAUDE.md precision convention. */ + private String scopeId; + + /** Null = any tool (only valid when granted by workspace admin with password confirmation). */ + private String toolName; + + /** + * Matches the {@code String ruleId} on {@code GuardFinding}. Null = any rule + * (grant applies to all findings under the severity ceiling). + */ + private String ruleId; + + /** LOW | MEDIUM | HIGH. CRITICAL is rejected at API/UI; resolver never reaches a grant for it. */ + private String maxSeverity; + + /** ALWAYS | UNTIL_TIMESTAMP | UNTIL_CONVERSATION_END — see {@link GrantKind}. */ + private String grantKind; + + /** Only meaningful when {@code grantKind = UNTIL_TIMESTAMP}. */ + private LocalDateTime expireAt; + + private Long grantedBy; + + /** + * Display name of the granter (nickname → username). Not persisted; the + * controller fills it in after {@code selectPage} by batch-loading the + * touched user ids so the UI doesn't need a separate /users call for a + * snowflake → name lookup. Null when the user no longer exists. + */ + @TableField(exist = false) + private String grantedByName; + + private LocalDateTime grantedAt; + + private Integer revoked; + + private Long revokedBy; + + private LocalDateTime revokedAt; + + private String note; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + @TableField(fill = FieldFill.INSERT_UPDATE) + private LocalDateTime updateTime; + + private Integer deleted; + + /** Allowed values for {@link #scopeType}; kept as constants to avoid string typos. */ + public static final class ScopeType { + public static final String USER = "USER"; + public static final String AGENT = "AGENT"; + public static final String CONVERSATION = "CONVERSATION"; + public static final String WORKSPACE = "WORKSPACE"; + private ScopeType() {} + } + + /** Allowed values for {@link #grantKind}. */ + public static final class GrantKind { + public static final String ALWAYS = "ALWAYS"; + public static final String UNTIL_TIMESTAMP = "UNTIL_TIMESTAMP"; + public static final String UNTIL_CONVERSATION_END = "UNTIL_CONVERSATION_END"; + private GrantKind() {} + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalResolutionLog.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalResolutionLog.java new file mode 100644 index 00000000..8840215b --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/entity/ApprovalResolutionLog.java @@ -0,0 +1,78 @@ +package vip.mate.approval.grant.entity; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * Final decision log written by the approval layer (one row per resolved invocation). + *

    + * Decoupled from {@code mate_tool_guard_audit_log} (which records guard evaluation + * facts). Dashboard decision-source percentages read from this table only, so the + * counts stay clean even when an invocation produces both an evaluation row and a + * resolution row. + */ +@Data +@TableName("mate_approval_resolution_log") +public class ApprovalResolutionLog { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + /** + * Nullable: a {@code HARD_BLOCK} event can be recorded before the workspace + * has been resolved (missing/deleted conversation, malformed context). Other + * decision sources ({@code USER_MANUAL}, {@code AUTO_GRANT}, {@code TIMEOUT}) + * always have a known workspace by the time they reach this table. + */ + private Long workspaceId; + + private String conversationId; + + private String agentId; + + private String userId; + + /** Correlates to {@code AssistantMessage.ToolCall.id} when available; nullable. */ + private String toolCallId; + + private String toolName; + + private String maxSeverity; + + /** Comma-joined list of GuardFinding ruleIds present at decision time. */ + private String ruleIds; + + /** USER_MANUAL | AUTO_GRANT | HARD_BLOCK | TIMEOUT — see {@link DecisionSource}. */ + private String decisionSource; + + /** Non-null when {@code decisionSource = AUTO_GRANT}. */ + private Long grantId; + + /** Non-null when the path went through {@code ApprovalWorkflowService.createPending()}. */ + private String pendingId; + + /** First 500 chars of rawArguments. WARN log prints 200; this stores more for the detail page. */ + private String argsPreview; + + private String note; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + private Integer deleted; + + /** Allowed values for {@link #decisionSource}. */ + public static final class DecisionSource { + public static final String USER_MANUAL = "USER_MANUAL"; + public static final String AUTO_GRANT = "AUTO_GRANT"; + public static final String HARD_BLOCK = "HARD_BLOCK"; + public static final String TIMEOUT = "TIMEOUT"; + private DecisionSource() {} + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListener.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListener.java new file mode 100644 index 00000000..3ed639f1 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListener.java @@ -0,0 +1,104 @@ +package vip.mate.approval.grant.listener; + +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.context.event.EventListener; +import org.springframework.stereotype.Component; +import vip.mate.approval.event.ApprovalResolutionEvent; +import vip.mate.approval.grant.WorkspaceLookupCache; +import vip.mate.approval.grant.entity.ApprovalResolutionLog; +import vip.mate.approval.grant.repository.ApprovalResolutionLogMapper; + +import java.util.List; +import java.util.Map; +import java.util.Objects; +import java.util.stream.Collectors; + +/** + * Records one row in {@code mate_approval_resolution_log} per final + * human-approval decision (USER_MANUAL / TIMEOUT), complementing the rows + * written directly by {@code ApprovalGrantResolver} for HARD_BLOCK and + * AUTO_GRANT. + *

    + * The listener runs out-of-tx (the publisher fires events from an + * {@code afterCommit} hook), so a DB write failure here cannot roll back the + * already-committed approval state. We log the failure and continue — losing + * one resolution-log row is far less harmful than re-opening the approval row + * for double-resolve. + * + *

    Workspace resolution goes through {@link WorkspaceLookupCache} so we get + * the same conversation→workspace mapping the resolver uses on the hot path, + * with the same null-fallback behavior: a deleted conversation produces a row + * with {@code workspace_id = null}, which is allowed by the V128 schema. + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class ApprovalResolutionLogListener { + + private static final int ARGS_PREVIEW_MAX = 500; + private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper(); + + private final ApprovalResolutionLogMapper resolutionMapper; + private final WorkspaceLookupCache workspaceLookupCache; + + @EventListener + public void onApprovalResolved(ApprovalResolutionEvent event) { + try { + ApprovalResolutionLog row = new ApprovalResolutionLog(); + row.setWorkspaceId(workspaceLookupCache.resolveByConversation(event.conversationId())); + row.setConversationId(event.conversationId()); + row.setAgentId(event.agentId()); + row.setUserId(event.userId()); + row.setToolName(event.toolName()); + row.setMaxSeverity(event.maxSeverity()); + row.setRuleIds(extractRuleIds(event.findingsJson())); + row.setDecisionSource(event.decisionSource()); + row.setGrantId(null); + row.setPendingId(event.pendingId()); + row.setArgsPreview(previewArgs(event.toolArguments())); + row.setNote(event.resolutionNote()); + + resolutionMapper.insert(row); + } catch (Exception e) { + log.warn("[APPROVAL] ApprovalResolutionLogListener failed to record {} for pending {}: {}", + event.decisionSource(), event.pendingId(), e.getMessage()); + } + } + + /** + * Pulls {@code ruleId}s out of the serialized findings JSON captured at + * {@code createPending} time. The JSON is the standard + * {@code GuardFinding.toMap()} array form (a {@code List>}), + * so we read the list and pick the {@code "ruleId"} key out of each map. + * Returns {@code null} on missing or unparseable input — the row still gets + * written, just without rule-id provenance. + */ + private static String extractRuleIds(String findingsJson) { + if (findingsJson == null || findingsJson.isBlank()) { + return null; + } + try { + List> findings = OBJECT_MAPPER.readValue( + findingsJson, new TypeReference<>() {}); + String joined = findings.stream() + .map(m -> m.get("ruleId")) + .filter(Objects::nonNull) + .map(Object::toString) + .filter(s -> !s.isBlank()) + .distinct() + .collect(Collectors.joining(",")); + return joined.isEmpty() ? null : joined; + } catch (Exception e) { + log.debug("[APPROVAL] Failed to parse findingsJson for rule_ids extraction: {}", e.getMessage()); + return null; + } + } + + private static String previewArgs(String raw) { + if (raw == null) return null; + return raw.length() <= ARGS_PREVIEW_MAX ? raw : raw.substring(0, ARGS_PREVIEW_MAX); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ConversationLifecycleListener.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ConversationLifecycleListener.java new file mode 100644 index 00000000..c2dbac27 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/listener/ConversationLifecycleListener.java @@ -0,0 +1,62 @@ +package vip.mate.approval.grant.listener; + +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.context.event.EventListener; +import org.springframework.stereotype.Component; +import vip.mate.approval.grant.WorkspaceLookupCache; +import vip.mate.approval.grant.service.ApprovalGrantService; +import vip.mate.workspace.conversation.event.ConversationDeletedEvent; + +/** + * Tears down conversation-scoped state in the auto-grant subsystem when a + * conversation is deleted. + *

    + * Two actions, run in order: + *

      + *
    1. Soft-revoke every {@code UNTIL_CONVERSATION_END} grant whose + * {@code scope_type = CONVERSATION} and {@code scope_id = conversationId}. + * Without this, the grant would linger as an apparently-active row that + * can never match again (its scope no longer exists), but still shows up + * in the management page and the chip {@code (N)} counter.
      2. + *
    2. Drop the {@code conversationId → workspaceId} entry from + * {@link WorkspaceLookupCache}. A re-created conversation with the same + * id (rare but possible across a backup restore) would otherwise inherit + * the stale mapping for up to five minutes.
      3. + *
    + * + *

    {@link ConversationDeletedEvent} is published after the delete tx + * commits, so this listener runs in a clean tx and the soft-revoke either + * succeeds or fails in isolation — it cannot poison the delete itself. + */ +@Slf4j +@Component +@RequiredArgsConstructor +public class ConversationLifecycleListener { + + private final ApprovalGrantService grantService; + private final WorkspaceLookupCache workspaceLookupCache; + + @EventListener + public void onConversationDeleted(ConversationDeletedEvent event) { + String conversationId = event.conversationId(); + if (conversationId == null || conversationId.isEmpty()) { + return; + } + try { + int revoked = grantService.revokeConversationScopedGrants(conversationId); + if (revoked > 0) { + log.info("[APPROVAL] ConversationLifecycleListener: revoked {} UNTIL_CONVERSATION_END grant(s) for {}", + revoked, conversationId); + } + } catch (Exception e) { + log.warn("[APPROVAL] ConversationLifecycleListener: failed to revoke grants for {}: {}", + conversationId, e.getMessage()); + } finally { + // Always invalidate the cache, even if grant revocation threw: a stale + // workspace mapping is more dangerous than a missed revoke (the grant + // can no longer match its conversation anyway). + workspaceLookupCache.invalidate(conversationId); + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalGrantMapper.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalGrantMapper.java new file mode 100644 index 00000000..f041de68 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalGrantMapper.java @@ -0,0 +1,58 @@ +package vip.mate.approval.grant.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Param; +import vip.mate.approval.grant.entity.ApprovalGrant; + +import java.util.List; + +/** + * Mapper for {@link ApprovalGrant}. + *

    + * BaseMapper covers ordinary CRUD; {@link #findFirstMatching} is a custom query + * defined in {@code ApprovalGrantMapper.xml} that returns the best-matching active + * grant for a tool invocation, ordered by scope priority and specificity. + */ +@Mapper +public interface ApprovalGrantMapper extends BaseMapper { + + /** + * Returns the single best grant that authorizes the given tool invocation, or + * {@code null} if none applies. Matching rules (see {@code ApprovalGrantMapper.xml}): + * + *

      + *
    • {@code workspace_id} must equal {@code workspaceId} (tenant isolation, mandatory).
      • + *
    • Not revoked, not deleted, not expired.
      • + *
    • {@code max_severity} must be at least as high as {@code evalSeverity}.
      • + *
    • {@code tool_name} is NULL or equals {@code toolName}.
      • + *
    • {@code rule_id} is NULL or is in {@code candidateRuleIds} (when the list is non-empty).
      • + *
    • One of the scope clauses must match: CONVERSATION+conversationId / AGENT+agentId / + * USER+userId / WORKSPACE+workspaceScopeId.
      • + *
    + * + * Order: scope priority CONVERSATION > AGENT > USER > WORKSPACE, + * then rule-id-specific over rule-id-null, then tool-name-specific over null. {@code LIMIT 1}. + * + * @param workspaceScopeId {@code String.valueOf(workspaceId)} — pre-converted to avoid + * dialect-specific CAST in SQL (H2 vs MySQL). + * @param candidateRuleIds list of GuardFinding ruleIds for the current invocation; may be empty + * or null, in which case only {@code rule_id IS NULL} grants match. + */ + ApprovalGrant findFirstMatching( + @Param("workspaceId") Long workspaceId, + @Param("userId") String userId, + @Param("agentId") String agentId, + @Param("conversationId") String conversationId, + @Param("workspaceScopeId") String workspaceScopeId, + @Param("toolName") String toolName, + @Param("candidateRuleIds") List candidateRuleIds, + @Param("evalSeverity") String evalSeverity); + + /** + * Soft-revokes every active {@code UNTIL_CONVERSATION_END} grant attached to the given + * conversation. Called by {@code ConversationLifecycleListener} on + * {@code ConversationDeletedEvent} (PR-2). + */ + int revokeUntilConversationEnd(@Param("conversationId") String conversationId); +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalResolutionLogMapper.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalResolutionLogMapper.java new file mode 100644 index 00000000..a30a9661 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/repository/ApprovalResolutionLogMapper.java @@ -0,0 +1,9 @@ +package vip.mate.approval.grant.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import vip.mate.approval.grant.entity.ApprovalResolutionLog; + +@Mapper +public interface ApprovalResolutionLogMapper extends BaseMapper { +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantResolver.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantResolver.java new file mode 100644 index 00000000..69dc5824 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantResolver.java @@ -0,0 +1,174 @@ +package vip.mate.approval.grant.service; + +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import vip.mate.approval.grant.AutoApproveAuditLogger; +import vip.mate.approval.grant.AutoApproveResult; +import vip.mate.approval.grant.AutoGrantSafetyFloor; +import vip.mate.approval.grant.entity.ApprovalGrant; +import vip.mate.approval.grant.entity.ApprovalResolutionLog; +import vip.mate.approval.grant.repository.ApprovalGrantMapper; +import vip.mate.approval.grant.repository.ApprovalResolutionLogMapper; +import vip.mate.tool.guard.model.GuardEvaluation; +import vip.mate.tool.guard.model.GuardFinding; +import vip.mate.tool.guard.model.GuardSeverity; +import vip.mate.tool.guard.model.ToolInvocationContext; + +import java.util.List; +import java.util.Objects; + +/** + * Decides whether a tool invocation that {@code ToolGuardService.evaluate(...)} + * already flagged as {@code NEEDS_APPROVAL} can be auto-approved by a stored + * {@link ApprovalGrant}, or must fall back to the existing human-approval flow, + * or must be hard-blocked. + *

    + * Decision order: + *

      + *
    1. Safety floor — {@link AutoGrantSafetyFloor#evaluate(String)} short-circuits + * on disasters ({@code HARD_BLOCK}) and downgrades dangerous-but-occasionally- + * legitimate patterns to {@code FORCE_HUMAN} (skip grant lookup, fall back + * to manual approval).
      2. + *
    2. Severity ceiling — {@code CRITICAL} is never auto-approvable.
      3. + *
    3. Tenant gate — when {@code workspaceId} is unknown the resolver + * conservatively returns {@code requiresHuman("UNKNOWN_WORKSPACE")} rather + * than letting a malformed context match the wrong workspace.
      4. + *
    4. Grant lookup — every {@code ruleId} present on the findings is sent to + * the mapper as a candidate; the mapper's SQL handles scope priority and + * severity ceiling.
      5. + *
    + * + *

    Whenever the resolver itself reaches a final decision (HARD_BLOCK or + * AUTO_GRANT), it writes one row to {@code mate_approval_resolution_log}. For + * {@code FORCE_HUMAN} / {@code SEVERITY_CRITICAL} / {@code UNKNOWN_WORKSPACE} / + * {@code NO_GRANT} no row is written here — the row is added later by + * {@code ApprovalWorkflowService.resolve*()} / {@code garbageCollect()} (PR-2) + * once the human path actually completes. + */ +@Slf4j +@Service +@RequiredArgsConstructor +public class ApprovalGrantResolver { + + private static final int ARGS_PREVIEW_MAX = 500; + + private final ApprovalGrantMapper grantMapper; + private final ApprovalResolutionLogMapper resolutionMapper; + private final AutoGrantSafetyFloor safetyFloor; + private final AutoApproveAuditLogger auditLogger; + + public AutoApproveResult tryAutoApprove(ToolInvocationContext ctx, GuardEvaluation evaluation) { + // 1) Safety floor — hard block or force the existing human path. + AutoGrantSafetyFloor.SafetyFloorMatch sf = safetyFloor.evaluate(ctx.rawArguments()); + if (sf.action() == AutoGrantSafetyFloor.Action.HARD_BLOCK) { + auditLogger.logHardBlock(ctx, evaluation, sf.patternName()); + resolutionMapper.insert( + buildResolutionLog(ctx, evaluation, + ApprovalResolutionLog.DecisionSource.HARD_BLOCK, + null, null, + "matched safety floor pattern: " + sf.patternName())); + return AutoApproveResult.hardBlocked(sf.patternName()); + } + if (sf.action() == AutoGrantSafetyFloor.Action.FORCE_HUMAN) { + auditLogger.logForceHuman(ctx, evaluation, sf.patternName()); + return AutoApproveResult.requiresHuman("FORCE_HUMAN:" + sf.patternName()); + } + + // 2) Severity ceiling — CRITICAL is never auto-approvable. + if (evaluation != null && evaluation.maxSeverity() == GuardSeverity.CRITICAL) { + return AutoApproveResult.requiresHuman("SEVERITY_CRITICAL"); + } + + // 3) workspaceId required for tenant isolation; null → conservative human path. + if (ctx.workspaceId() == null) { + log.warn("[APPROVAL] workspaceId=null for conversation={} agent={} tool={} — " + + "falling back to human approval. Check WorkspaceLookupCache wiring.", + ctx.conversationId(), ctx.agentId(), ctx.toolName()); + return AutoApproveResult.requiresHuman("UNKNOWN_WORKSPACE"); + } + + // 4) Collect all candidate ruleIds from findings (for IN-clause matching). + List candidateRuleIds = (evaluation == null || evaluation.findings() == null) + ? List.of() + : evaluation.findings().stream() + .map(GuardFinding::ruleId) + .filter(Objects::nonNull) + .distinct() + .toList(); + + // 5) Mapper finds first grant ordered by scope priority + specificity. + // workspaceId is also passed as a string for the WORKSPACE-scope match, + // so the mapper SQL stays dialect-clean (no CAST). See ApprovalGrantMapper.xml. + String workspaceScopeId = String.valueOf(ctx.workspaceId()); + String evalSeverity = evaluation == null || evaluation.maxSeverity() == null + ? GuardSeverity.LOW.name() + : evaluation.maxSeverity().name(); + + ApprovalGrant matched = grantMapper.findFirstMatching( + ctx.workspaceId(), + ctx.userId(), ctx.agentId(), ctx.conversationId(), + workspaceScopeId, + ctx.toolName(), + candidateRuleIds, + evalSeverity); + + if (matched == null) { + return AutoApproveResult.requiresHuman("NO_GRANT"); + } + + // 6) Grant matched — log, audit, and approve. + auditLogger.logAutoGrant(matched, ctx, evaluation); + resolutionMapper.insert( + buildResolutionLog(ctx, evaluation, + ApprovalResolutionLog.DecisionSource.AUTO_GRANT, + matched.getId(), null, matched.getNote())); + return AutoApproveResult.approved(matched.getId()); + } + + /** + * Builds a {@link ApprovalResolutionLog} row for the given final decision. + * {@code grantId} is set only for AUTO_GRANT; {@code pendingId} is set only when + * the row is later written by the human-path hooks in + * {@code ApprovalWorkflowService} (PR-2). + */ + private ApprovalResolutionLog buildResolutionLog(ToolInvocationContext ctx, + GuardEvaluation evaluation, + String decisionSource, + Long grantId, + String pendingId, + String note) { + ApprovalResolutionLog row = new ApprovalResolutionLog(); + row.setWorkspaceId(ctx.workspaceId()); + row.setConversationId(ctx.conversationId()); + row.setAgentId(ctx.agentId()); + row.setUserId(ctx.userId()); + row.setToolName(ctx.toolName()); + row.setMaxSeverity(evaluation == null || evaluation.maxSeverity() == null + ? null : evaluation.maxSeverity().name()); + row.setRuleIds(joinRuleIds(evaluation)); + row.setDecisionSource(decisionSource); + row.setGrantId(grantId); + row.setPendingId(pendingId); + row.setArgsPreview(previewArgs(ctx.rawArguments())); + row.setNote(note); + return row; + } + + private static String joinRuleIds(GuardEvaluation evaluation) { + if (evaluation == null || evaluation.findings() == null || evaluation.findings().isEmpty()) { + return null; + } + return evaluation.findings().stream() + .map(GuardFinding::ruleId) + .filter(Objects::nonNull) + .distinct() + .reduce((a, b) -> a + "," + b) + .orElse(null); + } + + private static String previewArgs(String raw) { + if (raw == null) return null; + return raw.length() <= ARGS_PREVIEW_MAX ? raw : raw.substring(0, ARGS_PREVIEW_MAX); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantService.java b/mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantService.java new file mode 100644 index 00000000..62eb8f39 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/approval/grant/service/ApprovalGrantService.java @@ -0,0 +1,103 @@ +package vip.mate.approval.grant.service; + +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Transactional; +import vip.mate.approval.grant.entity.ApprovalGrant; +import vip.mate.approval.grant.repository.ApprovalGrantMapper; + +import java.time.LocalDateTime; +import java.util.List; + +/** + * Service-layer operations on {@link ApprovalGrant}. + *

    + * CRUD is handled via the {@link ApprovalGrantMapper} BaseMapper; this service + * adds the small number of approval-domain operations that callers from outside + * the controller need: + * + *

      + *
    • {@link #revokeConversationScopedGrants(String)} — used by the lifecycle + * listener (PR-2) on {@code ConversationDeletedEvent} to soft-revoke every + * {@code UNTIL_CONVERSATION_END} grant attached to that conversation.
      • + *
    • {@link #countActiveInWorkspace(Long)} — used by the {@code /api/v1/approval/grants/active} + * endpoint and the front-end pill / chip so they can show {@code (N)} without + * fetching every row.
      • + *
    • {@link #listActiveByScope(Long, String)} — generic listing for the + * management page, with the standard "not deleted, not revoked, not expired" + * filter applied uniformly.
      • + *
    + * + *

    CRUD validation (e.g. rejecting {@code max_severity=CRITICAL} or enforcing the + * scope/tool_name authorization matrix in §2.4.5) lives in {@code ApprovalGrantController} + * (PR-4), not here — the service stays low-policy so {@code ApprovalGrantResolver} + * can call it without dragging REST concerns in. + */ +@Slf4j +@Service +@RequiredArgsConstructor +public class ApprovalGrantService { + + private final ApprovalGrantMapper grantMapper; + + /** + * Soft-revokes every active {@code UNTIL_CONVERSATION_END} grant attached to the + * conversation. Idempotent. + */ + @Transactional + public int revokeConversationScopedGrants(String conversationId) { + if (conversationId == null || conversationId.isEmpty()) { + return 0; + } + int revoked = grantMapper.revokeUntilConversationEnd(conversationId); + if (revoked > 0) { + log.info("[APPROVAL] Revoked {} UNTIL_CONVERSATION_END grant(s) on conversation delete: {}", + revoked, conversationId); + } + return revoked; + } + + /** Counts active grants visible in the given workspace (drives the chip "(N)"). */ + public long countActiveInWorkspace(Long workspaceId) { + if (workspaceId == null) return 0; + return grantMapper.selectCount( + Wrappers.lambdaQuery() + .eq(ApprovalGrant::getWorkspaceId, workspaceId) + .eq(ApprovalGrant::getRevoked, 0) + .eq(ApprovalGrant::getDeleted, 0) + .and(w -> w.isNull(ApprovalGrant::getExpireAt) + .or().gt(ApprovalGrant::getExpireAt, LocalDateTime.now())) + ); + } + + /** Lists active grants in a workspace, optionally restricted to a scope type. */ + public List listActiveByScope(Long workspaceId, String scopeType) { + if (workspaceId == null) return List.of(); + var wrapper = Wrappers.lambdaQuery() + .eq(ApprovalGrant::getWorkspaceId, workspaceId) + .eq(ApprovalGrant::getRevoked, 0) + .eq(ApprovalGrant::getDeleted, 0) + .and(w -> w.isNull(ApprovalGrant::getExpireAt) + .or().gt(ApprovalGrant::getExpireAt, LocalDateTime.now())) + .orderByDesc(ApprovalGrant::getGrantedAt); + if (scopeType != null && !scopeType.isEmpty()) { + wrapper.eq(ApprovalGrant::getScopeType, scopeType); + } + return grantMapper.selectList(wrapper); + } + + /** Soft-revokes a single grant. Caller must enforce ownership / admin (PR-4). */ + @Transactional + public boolean revoke(Long grantId, Long revokedBy) { + ApprovalGrant g = grantMapper.selectById(grantId); + if (g == null || g.getRevoked() != null && g.getRevoked() == 1) { + return false; + } + g.setRevoked(1); + g.setRevokedBy(revokedBy); + g.setRevokedAt(LocalDateTime.now()); + return grantMapper.updateById(g) > 0; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/auth/service/AuthService.java b/mateclaw-server/src/main/java/vip/mate/auth/service/AuthService.java index 465d8e9c..07ccad95 100644 --- a/mateclaw-server/src/main/java/vip/mate/auth/service/AuthService.java +++ b/mateclaw-server/src/main/java/vip/mate/auth/service/AuthService.java @@ -109,17 +109,41 @@ public class AuthService { * 修改密码 */ public void changePassword(Long userId, String oldPassword, String newPassword) { + verifyCurrentUserPassword(userId, oldPassword); UserEntity user = userMapper.selectById(userId); - if (user == null) { - throw new MateClawException("err.auth.user_not_found", "用户不存在"); - } - if (!passwordEncoder.matches(oldPassword, user.getPassword())) { - throw new MateClawException("err.auth.wrong_password", "原密码错误"); - } user.setPassword(passwordEncoder.encode(newPassword)); userMapper.updateById(user); } + /** + * Step-up authentication: confirms that {@code rawPassword} matches the + * user's currently stored password without changing anything. + *

    + * Used by sensitive operations that require re-confirmation of identity + * (e.g. creating a workspace-wide all-tool auto-approve grant). Throws + * the same {@link MateClawException} keys as {@link #changePassword} so + * the user-facing error message stays consistent. + * + * @throws MateClawException {@code err.auth.user_not_found} when the user + * doesn't exist, or {@code err.auth.wrong_password} when the + * password doesn't match. + */ + public void verifyCurrentUserPassword(Long userId, String rawPassword) { + UserEntity user = userMapper.selectById(userId); + if (user == null) { + // 404: target user no longer exists; surfacing as 401 would mask the cause. + throw new MateClawException("err.auth.user_not_found", 404, "用户不存在"); + } + if (rawPassword == null || !passwordEncoder.matches(rawPassword, user.getPassword())) { + // 403, not 401: 401 would trigger the global http interceptor's + // handleAuthFailure() and log the user out, but this is a step-up + // re-confirmation (token is still valid). Falling through to the + // default 500 looks like a server fault on the client; 403 cleanly + // communicates "valid session, wrong second-factor". + throw new MateClawException("err.auth.wrong_password", 403, "原密码错误"); + } + } + /** * 解析 Token 获取用户名 */ diff --git a/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java b/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java index ef0d33f0..d0ecc33c 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/ChannelMessageRouter.java @@ -16,6 +16,7 @@ import vip.mate.channel.model.ChannelEntity; import vip.mate.channel.notification.ApprovalNotificationService; import vip.mate.channel.service.ChannelService; import vip.mate.channel.web.ChatStreamTracker; +import vip.mate.exception.MateClawException; import vip.mate.memory.event.ConversationCompletionPublisher; import vip.mate.tts.TtsService; import vip.mate.workspace.conversation.ConversationService; @@ -237,6 +238,31 @@ public class ChannelMessageRouter { * @param channelEntity 渠道配置（含关联 agentId） */ public void enqueue(ChannelMessage message, ChannelAdapter adapter, ChannelEntity channelEntity) { + // The adapter caches the ChannelEntity it was constructed with, so a + // long-lived adapter (e.g. Feishu WS) keeps handing us a snapshot + // that may be stale by the time the message arrives. Refresh from + // the DB so a freshly-rebound agent (or any other routing-metadata + // change applied without a restart) is honoured immediately. + ChannelEntity fresh = freshChannelEntity(channelEntity); + if (fresh == null) { + // Channel deleted between adapter start and message arrival. + // Skip everything — even the trigger publish, since the channel + // no longer exists for downstream consumers to reference. + return; + } + // Only drop on an EXPLICIT enabled=false. A null enabled (which the + // production DB never returns but tests / hand-constructed entities + // do) means "not declared", and treating it as disabled would + // collapse every downstream behaviour into a silent drop — which is + // exactly how the previous !Boolean.TRUE.equals(...) form regressed + // mock-driven tests that don't bother seeding the flag. + if (Boolean.FALSE.equals(fresh.getEnabled())) { + log.warn("[{}] Channel {} (id={}) is disabled; dropping message from {}", + adapter.getChannelType(), fresh.getName(), fresh.getId(), message.getSenderId()); + return; + } + channelEntity = fresh; + // Fan out to the trigger pipeline FIRST — channel_message and // content_match triggers fire on every received message regardless // of whether the channel has an agent attached. If we returned @@ -538,7 +564,31 @@ public class ChannelMessageRouter { */ private void processMessage(ChannelMessage message, ChannelAdapter adapter, ChannelEntity channelEntity, String conversationId) { + // The snapshot captured at enqueue time can be stale: an admin may + // have rebound, deleted, or disabled the channel between debounce- + // queue and flush. Re-read here so the rest of this method sees the + // current state, and fail closed on deletion / disable so we don't + // process traffic for a channel the admin has shut down. + ChannelEntity fresh = freshChannelEntity(channelEntity); + if (fresh == null) { + log.warn("[{}] Channel id={} not found at processing time; dropping message from {}", + adapter.getChannelType(), + channelEntity != null ? channelEntity.getId() : null, + message.getSenderId()); + return; + } + if (Boolean.FALSE.equals(fresh.getEnabled())) { + log.warn("[{}] Channel {} (id={}) is disabled at processing time; dropping message from {}", + adapter.getChannelType(), fresh.getName(), fresh.getId(), message.getSenderId()); + return; + } + channelEntity = fresh; Long agentId = channelEntity.getAgentId(); + if (agentId == null) { + log.warn("[{}] Channel {} has no associated agent at processing time; dropping message from {}", + adapter.getChannelType(), channelEntity.getName(), message.getSenderId()); + return; + } log.info("[{}] Processing message: sender={}, conversationId={}, agentId={}", adapter.getChannelType(), message.getSenderId(), conversationId, agentId); @@ -732,10 +782,22 @@ public class ChannelMessageRouter { // for any Web SSE viewer of the same conversationId. StringBuilder replyAccumulator = new StringBuilder(); final String channelType = adapter.getChannelType(); + // Token usage + model attribution: capture _usage_final event emitted at stream end + final int[] usage = {0, 0}; // [promptTokens, completionTokens] + final String[] modelInfo = {null, null}; // [runtimeModel, runtimeProvider] agentService.chatStructuredStream(agentId, promptText, conversationId, message.getSenderId(), chatOrigin) .doOnNext(delta -> { if (delta.isEvent()) { + if ("_usage_final".equals(delta.eventType())) { + Map data = delta.eventData(); + usage[0] = ((Number) data.getOrDefault("promptTokens", 0)).intValue(); + usage[1] = ((Number) data.getOrDefault("completionTokens", 0)).intValue(); + Object model = data.get("runtimeModelName"); + Object provider = data.get("runtimeProviderId"); + if (model != null) modelInfo[0] = model.toString(); + if (provider != null) modelInfo[1] = provider.toString(); + } mirrorPlanEventToTracker(conversationId, delta, channelType); } else if (delta.content() != null) { // Match the legacy agentService.chat() behavior: include @@ -770,10 +832,11 @@ public class ChannelMessageRouter { boolean isError = errorClassifier.isErrorReply(reply); String status = isError ? "error" : "completed"; MessageEntity saved = conversationService.saveMessage( - conversationId, "assistant", reply, null, status); + conversationId, "assistant", reply, null, status, + usage[0], usage[1], modelInfo[0], modelInfo[1]); savedAssistantId = saved != null ? saved.getId() : null; if (!isError) { - publishConversationCompletedEvent(agentId, conversationId, message.getContent(), reply); + publishConversationCompletedEvent(agentId, conversationId, message.getContent(), reply, chatOrigin); } adapter.renderAndSend(replyTarget, reply); log.info("[{}] Reply sent to {}: {}chars", @@ -884,8 +947,21 @@ public class ChannelMessageRouter { // only reads `delta.content()` and would otherwise eat plan_created / // plan_step_* events, leaving the Web Console mirror with no // PlanStepsPanel for IM-routed conversations. - Flux mirroredStream = stream.doOnNext(delta -> - mirrorPlanEventToTracker(conversationId, delta, channelType)); + // Token usage + model attribution: capture _usage_final event emitted at stream end + final int[] usage = {0, 0}; // [promptTokens, completionTokens] + final String[] modelInfo = {null, null}; // [runtimeModel, runtimeProvider] + Flux mirroredStream = stream.doOnNext(delta -> { + if (delta.isEvent() && "_usage_final".equals(delta.eventType())) { + Map data = delta.eventData(); + usage[0] = ((Number) data.getOrDefault("promptTokens", 0)).intValue(); + usage[1] = ((Number) data.getOrDefault("completionTokens", 0)).intValue(); + Object model = data.get("runtimeModelName"); + Object provider = data.get("runtimeProviderId"); + if (model != null) modelInfo[0] = model.toString(); + if (provider != null) modelInfo[1] = provider.toString(); + } + mirrorPlanEventToTracker(conversationId, delta, channelType); + }); // Step 2: 委托渠道渲染（渠道内部消费 Flux 并处理 UI 更新） String finalContent = streamingAdapter.processStream(mirroredStream, message, conversationId); @@ -905,9 +981,10 @@ public class ChannelMessageRouter { boolean isError = errorClassifier.isErrorReply(finalContent); String status = isError ? "error" : "completed"; MessageEntity saved = conversationService.saveMessage( - conversationId, "assistant", finalContent, null, status); + conversationId, "assistant", finalContent, null, status, + usage[0], usage[1], modelInfo[0], modelInfo[1]); if (!isError) { - publishConversationCompletedEvent(agentId, conversationId, promptText, finalContent); + publishConversationCompletedEvent(agentId, conversationId, promptText, finalContent, chatOrigin); } log.info("[{}] Streaming completed: contentLen={}, isError={}", channelType, finalContent.length(), isError); @@ -990,8 +1067,9 @@ public class ChannelMessageRouter { replayOrigin = chatOriginFactory.from( channelEntity, triggerMessage, conversationId, /* workspaceBasePath */ null); } - String reply = agentService.chatWithReplay( + AgentService.ChatResult replayResult = agentService.chatWithReplayWithUsage( agentId, replayPrompt, conversationId, consumed.getToolCallPayload(), replayOrigin); + String reply = replayResult.content(); // Persist the replay result. If the LLM 400'd during replay, // the error reply must also get status='error' — otherwise the @@ -999,7 +1077,9 @@ public class ChannelMessageRouter { // into the prompt and re-trigger the same failure. boolean isError = errorClassifier.isErrorReply(reply); conversationService.saveMessage(conversationId, "assistant", reply, null, - isError ? "error" : "completed"); + isError ? "error" : "completed", + replayResult.promptTokens(), replayResult.completionTokens(), + replayResult.runtimeModel(), replayResult.runtimeProvider()); // 发送回复 adapter.renderAndSend(replyTarget, reply); @@ -1080,8 +1160,13 @@ public class ChannelMessageRouter { * messageCount lookup no longer live here. */ private void publishConversationCompletedEvent(Long agentId, String conversationId, - String userMessage, String assistantReply) { - completionPublisher.publish(agentId, conversationId, userMessage, assistantReply, "channel"); + String userMessage, String assistantReply, + ChatOrigin origin) { + // Attribute the memory write to the same external sender the read path + // recalled for, so per-sender IM memory is both written and recalled + // under the same owner key. + completionPublisher.publishForOrigin(agentId, conversationId, userMessage, assistantReply, + "channel", origin); } // ==================== 流式处理（Web 渠道专用，不走队列） ==================== @@ -1090,6 +1175,14 @@ public class ChannelMessageRouter { * 路由消息并使用流式处理（用于支持流式的渠道，如 Web） */ public Flux routeStream(ChannelMessage message, ChannelEntity channelEntity) { + ChannelEntity fresh = freshChannelEntity(channelEntity); + if (fresh == null) { + return Flux.error(new IllegalStateException("Channel no longer exists")); + } + if (Boolean.FALSE.equals(fresh.getEnabled())) { + return Flux.error(new IllegalStateException("Channel is disabled")); + } + channelEntity = fresh; Long agentId = channelEntity.getAgentId(); if (agentId == null) { return Flux.error(new IllegalStateException("Channel has no associated agent")); @@ -1164,6 +1257,49 @@ public class ChannelMessageRouter { // ==================== 工具方法 ==================== + /** + * Re-read the channel row from the database so the rest of the message + * pipeline sees current routing metadata (agentId, workspaceId, identityJson) + * rather than the snapshot captured when the adapter was constructed. + * + *

    Failure semantics: + *

      + *
    • Channel deleted — {@link ChannelService#getChannel} throws + * a {@link MateClawException} with {@code msgKey="err.channel.not_found"}. + * We return {@code null} so the caller drops the message: the channel + * no longer exists, routing the message would land it against a row + * that's been removed.
      • + *
    • Transient lookup failure — any other exception (DB blip, + * NPE in mapper, …). We fall back to the snapshot so an isolated + * infrastructure hiccup doesn't black-hole live traffic.
      • + *
    + * + *

    {@code enabled=false} is NOT handled here — that's an admin decision + * the callers check separately, with channel-type-specific logging. + */ + private ChannelEntity freshChannelEntity(ChannelEntity snapshot) { + if (snapshot == null || snapshot.getId() == null) { + return snapshot; + } + try { + ChannelEntity latest = channelService.getChannel(snapshot.getId()); + return latest != null ? latest : snapshot; + } catch (MateClawException biz) { + if ("err.channel.not_found".equals(biz.getMsgKey())) { + log.warn("Channel id={} no longer exists; dropping incoming message", + snapshot.getId()); + return null; + } + log.debug("Transient channel lookup failure id={}, using snapshot: {}", + snapshot.getId(), biz.getMessage()); + return snapshot; + } catch (Exception e) { + log.debug("Failed to refresh ChannelEntity id={}, using snapshot: {}", + snapshot.getId(), e.getMessage()); + return snapshot; + } + } + /** * 构建会话 ID * 格式：{channelType}:{chatId 或 senderId} diff --git a/mateclaw-server/src/main/java/vip/mate/channel/controller/ChannelController.java b/mateclaw-server/src/main/java/vip/mate/channel/controller/ChannelController.java index eb5ac1b5..771e69d3 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/controller/ChannelController.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/controller/ChannelController.java @@ -97,11 +97,53 @@ public class ChannelController { channel.setId(id); channel.setWorkspaceId(existing.getWorkspaceId()); ChannelEntity updated = channelService.updateChannel(channel); - channelManager.restartChannel(id); + // Restart only when a field the adapter consumes BEFORE the router + // takes over has changed — channel type, enabled toggle, configJson + // (app credentials, connection_mode, domain, …), and botPrefix + // (consumed by AbstractChannelAdapter.shouldProcess / cleanBotPrefix + // before enqueue, so a per-message DB refresh in the router can't + // catch it). Pure router-visible metadata (bound agent, display + // name, description, identityJson) is re-read on every message via + // ChannelMessageRouter.freshChannelEntity, so it doesn't justify + // dropping the live connection — for Feishu WS that would mean a + // multi-second blackout where inbound messages never reach the bot. + if (transportConfigChanged(existing, updated)) { + channelManager.restartChannel(id); + } auditEventService.record("UPDATE", "CHANNEL", String.valueOf(id), updated.getName(), null); return R.ok(updated); } + /** + * True iff a field the adapter consumes BEFORE the router takes over (or + * that gates the adapter lifecycle entirely) has changed. + * + *

    {@code agentId}, {@code name}, {@code description}, {@code identityJson} + * stay excluded — those are routing metadata read on every message via + * {@code ChannelMessageRouter.freshChannelEntity()}. + * + *

    {@code botPrefix} IS included even though it's "just routing metadata" + * conceptually: {@code AbstractChannelAdapter.shouldProcess()} and + * {@code cleanBotPrefix()} run inside the adapter before the message + * reaches the router, and they read from the adapter's cached + * {@code channelEntity}. A prefix edit without restart would still filter + * and strip with the old prefix until the adapter is recreated. + */ + private boolean transportConfigChanged(ChannelEntity oldRow, ChannelEntity newRow) { + if (!java.util.Objects.equals(oldRow.getChannelType(), newRow.getChannelType())) { + return true; + } + if (!java.util.Objects.equals(oldRow.getEnabled(), newRow.getEnabled())) { + return true; + } + if (!java.util.Objects.equals(oldRow.getBotPrefix(), newRow.getBotPrefix())) { + return true; + } + String oldCfg = oldRow.getConfigJson() == null ? "" : oldRow.getConfigJson(); + String newCfg = newRow.getConfigJson() == null ? "" : newRow.getConfigJson(); + return !oldCfg.equals(newCfg); + } + @RequireWorkspaceRole("admin") @Operation(summary = "删除渠道") @DeleteMapping("/{id}") diff --git a/mateclaw-server/src/main/java/vip/mate/channel/feishu/FeishuChannelAdapter.java b/mateclaw-server/src/main/java/vip/mate/channel/feishu/FeishuChannelAdapter.java index 30dd6ff2..718d50ff 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/feishu/FeishuChannelAdapter.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/feishu/FeishuChannelAdapter.java @@ -20,6 +20,9 @@ import vip.mate.channel.media.MediaUploadResult; import vip.mate.channel.model.ChannelEntity; import vip.mate.workspace.conversation.model.MessageContentPart; +import com.github.benmanes.caffeine.cache.Cache; +import com.github.benmanes.caffeine.cache.Caffeine; + import java.io.InputStream; import java.net.URI; import java.net.http.HttpClient; @@ -170,6 +173,25 @@ public class FeishuChannelAdapter extends AbstractChannelAdapter implements Stre */ private final vip.mate.stt.SttService sttService; + // ==================== Per-chat recent file cache ==================== + + /** + * Per-chat cache of recently downloaded file messages. When a file is + * sent in a Feishu chat (even without @mention), it is downloaded and + * cached here. When a follow-up text message arrives in the same chat, + * the cached files are injected as content parts so the agent can see + * and process them. + */ + private static final long RECENT_FILE_TTL_MINUTES = 60; + private static final int RECENT_FILE_MAX_PER_CHAT = 5; + + record RecentFileEntry(String fileName, String path, String fileUrl, String contentType) {} + + private final Cache> recentFileCache = Caffeine.newBuilder() + .expireAfterWrite(RECENT_FILE_TTL_MINUTES, TimeUnit.MINUTES) + .maximumSize(200) + .build(); + public FeishuChannelAdapter(ChannelEntity channelEntity, ChannelMessageRouter messageRouter, ObjectMapper objectMapper) { @@ -548,8 +570,15 @@ public class FeishuChannelAdapter extends AbstractChannelAdapter implements Stre } /** - * 关闭 WebSocket 连接 - * SDK 的 start() 在线程中阻塞运行，通过中断线程来触发停止 + * 关闭 WebSocket 连接。 + *

    + * 必须主动关闭底层 WebSocket 连接并触发 SDK 的内部清理（停止 pingLoop、 + * 释放 ExecutorService）。仅置空引用会导致旧连接的 pingLoop 和线程池 + * 持续运行，造成文件描述符和线程泄漏，最终使新连接无法建立。 + *

    + * SDK 2.7.0 起暴露了 public {@code close()} 入口，内部调用 protected + * {@code disconnect()} 完成 {@code conn.close(1000) → executor.shutdown() → + * 字段清零} 的全套清理。直接调用即可，无需反射。 */ private void stopWebSocket() { cancelSilentDisconnectWatchdog(); @@ -558,6 +587,13 @@ public class FeishuChannelAdapter extends AbstractChannelAdapter implements Stre wsThread.interrupt(); wsThread = null; } + if (wsClient != null) { + try { + wsClient.close(); + } catch (Exception e) { + log.warn("[feishu] WebSocket close failed: {}", e.getMessage()); + } + } wsClient = null; } @@ -889,10 +925,30 @@ public class FeishuChannelAdapter extends AbstractChannelAdapter implements Stre private void handleFeishuMessage(String messageId, String messageType, String contentStr, String chatId, String chatType, String senderOpenId, String parentId, boolean isBotMentioned, Object rawPayload) { + // Per-chat recent file cache: always download file messages (even + // without @mention) so they can be auto-associated with follow-up + // text messages in the same chat. + boolean isGroup = "group".equals(chatType); + boolean isFileMessage = "file".equals(messageType) || "image".equals(messageType) + || "audio".equals(messageType) || "media".equals(messageType); + // Compute conversationId once — used as cache key for both write (cacheRecentFile) + // and read (injectRecentFiles), and as the directory name under data/chat-uploads/. + // It MUST equal the id ChannelMessageRouter derives for this chat: the routed + // ChannelMessage carries chatId = (isGroup ? shortSuffix : null), so the router + // resolves it to feishu:{shortSuffix} for groups and feishu:{senderId} for DMs. + // ChatUploadResolver locates attachments under data/chat-uploads/{that id}/, and the + // prompt only exposes the file name (not its path) to the model — so if this id does + // not match, ReadFileTool / DocumentExtractTool cannot find the cached file. + String shortSuffix = generateShortSessionSuffix(chatId, senderOpenId, isGroup); + String conversationId = buildConversationId(shortSuffix, senderOpenId, isGroup); + + if (isFileMessage) { + cacheRecentFile(messageId, messageType, contentStr, conversationId); + } + // require_mention 群聊过滤：群聊中必须 @机器人才响应。 // 当 botOpenId 为 null 时（API 抖动 / 尚未拉取成功），失败回退到放行 — // 避免飞书 /open-apis/bot/v3/info 短暂不可用时整个群机器人变哑巴。 - boolean isGroup = "group".equals(chatType); boolean requireMention = getConfigBoolean("require_mention", false); if (isGroupNonMentionDrop(isGroup, requireMention, isBotMentioned, botOpenId)) { log.debug("[feishu] require_mention=true but bot not mentioned, dropping messageId={}", messageId); @@ -942,9 +998,14 @@ public class FeishuChannelAdapter extends AbstractChannelAdapter implements Stre } } - // 生成短会话后缀 - String shortSuffix = generateShortSessionSuffix(chatId, senderOpenId, isGroup); + // Auto-associate recent files: inject file/image parts from the + // per-chat cache so the agent can see files sent earlier in the + // same conversation (user sends file → asks about it in text). + if (!isFileMessage && conversationId != null) { + textContent = injectRecentFiles(conversationId, contentParts, textContent); + } + // shortSuffix already computed above (kept consistent with conversationId). ChannelMessage channelMessage = ChannelMessage.builder() .messageId(messageId) .channelType(CHANNEL_TYPE) @@ -1341,6 +1402,150 @@ public class FeishuChannelAdapter extends AbstractChannelAdapter implements Stre return null; } + /** + * Compute the conversationId that {@link ChannelMessageRouter} would + * derive for this chat, so we can save inbound files to the matching + * {@code data/chat-uploads/} directory. + * + *

    The router derives the id from the routed {@link ChannelMessage}, + * whose {@code chatId} is {@code (isGroup ? shortSuffix : null)} and whose + * {@code senderId} is the full open id. Mirror that exactly: + * {@code groups → feishu:{shortSuffix}}, {@code DMs → feishu:{senderOpenId}}. + */ + static String buildConversationId(String shortSuffix, String senderOpenId, boolean isGroup) { + // The routed ChannelMessage carries chatId = (isGroup ? shortSuffix : null); + // the router then falls back to senderId when that chatId is null. Mirror both + // steps so the storage id matches the runtime id in every case (including the + // degenerate group-with-no-suffix path). + String routedChatId = isGroup ? shortSuffix : null; + String identifier = routedChatId != null ? routedChatId : senderOpenId; + return identifier != null ? CHANNEL_TYPE + ":" + identifier : null; + } + + // ==================== Per-chat recent file cache ==================== + + /** + * Download an inbound file message and cache its metadata in the + * per-chat recent-file cache. The file is saved to + * {@code data/chat-uploads/{conversationId}/} so existing tools + * ({@code ReadFileTool}, {@code DocumentExtractTool}) can find it + * via {@code ChatUploadResolver}, and it gets cleaned up when the + * conversation is deleted. + */ + private void cacheRecentFile(String messageId, String messageType, String contentStr, + String conversationId) { + try { + Map contentObj = objectMapper.readValue(contentStr, Map.class); + + String fileKey = null; + String fileName = null; + String type; // SDK type: "image" or "file" + + switch (messageType) { + case "image" -> { + fileKey = (String) contentObj.get("image_key"); + type = "image"; + } + case "file" -> { + fileKey = (String) contentObj.get("file_key"); + fileName = (String) contentObj.get("file_name"); + type = "file"; + } + case "audio" -> { + fileKey = (String) contentObj.get("file_key"); + type = "file"; + } + case "media" -> { + fileKey = (String) contentObj.get("file_key"); + fileName = (String) contentObj.get("file_name"); + type = "file"; + } + default -> { + return; + } + } + + if (fileKey == null) return; + + // Download file bytes + DownloadedResource dl = "image".equals(messageType) + ? maybeDownloadImage(messageId, fileKey) + : maybeDownloadResource(messageId, fileKey, type, fileName); + if (dl == null) return; + + // Save to data/chat-uploads/{conversationId}/ + Path uploadDir = Path.of("data", "chat-uploads", conversationId); + Files.createDirectories(uploadDir); + String rawName = (dl.fileName() != null && !dl.fileName().isBlank()) + ? dl.fileName() : fileKey; + String safeName = Path.of(rawName).getFileName().toString() + .replaceAll("[^a-zA-Z0-9._-]", "_"); + if (safeName.isBlank()) safeName = "file"; + String storedName = System.currentTimeMillis() + "_" + safeName; + Path dest = uploadDir.resolve(storedName); + Files.copy(Path.of(dl.path()), dest, StandardCopyOption.REPLACE_EXISTING); + + String contentType = dl.contentType() != null ? dl.contentType() : "application/octet-stream"; + RecentFileEntry entry = new RecentFileEntry(safeName, dest.toAbsolutePath().toString(), + dl.fileUrl(), contentType); + + // Append to per-conversation cache (cap at RECENT_FILE_MAX_PER_CHAT) + recentFileCache.asMap().compute(conversationId, (k, existing) -> { + List list = existing != null ? new ArrayList<>(existing) : new ArrayList<>(); + list.add(entry); + if (list.size() > RECENT_FILE_MAX_PER_CHAT) { + list = list.subList(list.size() - RECENT_FILE_MAX_PER_CHAT, list.size()); + } + return list; + }); + + log.info("[feishu] Cached recent file for conversation={}: {} ({} bytes, {})", + conversationId, entry.fileName(), Files.size(dest), contentType); + + } catch (Exception e) { + log.debug("[feishu] Failed to cache recent file: {}", e.getMessage()); + } + } + + /** + * Inject recent files from the per-chat cache into the current + * message's content parts, so the agent can see files that were + * sent earlier in the same conversation. + * + * @return updated textContent with file descriptions appended + */ + private String injectRecentFiles(String conversationId, List parts, String textContent) { + List recent = recentFileCache.getIfPresent(conversationId); + if (recent == null || recent.isEmpty()) return textContent; + + // Collect paths already in parts to avoid duplicates + Set existingPaths = new java.util.HashSet<>(); + for (MessageContentPart p : parts) { + if (p != null && p.getPath() != null) existingPaths.add(p.getPath()); + } + + StringBuilder text = new StringBuilder(textContent != null ? textContent : ""); + for (RecentFileEntry entry : recent) { + if (existingPaths.contains(entry.path())) continue; + + MessageContentPart part = new MessageContentPart(); + if (entry.contentType() != null && entry.contentType().startsWith("image/")) { + part.setType("image"); + } else { + part.setType("file"); + } + part.setFileName(entry.fileName()); + part.setPath(entry.path()); + if (entry.fileUrl() != null) part.setFileUrl(entry.fileUrl()); + part.setContentType(entry.contentType()); + parts.add(part); + + if (!text.isEmpty()) text.append('\n'); + text.append("[用户发送了文件: ").append(entry.fileName()).append("]"); + } + return text.toString(); + } + // ==================== 消息内容解析 ==================== /** diff --git a/mateclaw-server/src/main/java/vip/mate/channel/media/GeneratedFileScrubber.java b/mateclaw-server/src/main/java/vip/mate/channel/media/GeneratedFileScrubber.java index 6caefcb8..2a916c14 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/media/GeneratedFileScrubber.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/media/GeneratedFileScrubber.java @@ -23,8 +23,9 @@ import java.util.regex.Matcher; * a render tool. {@link GeneratedFileCache#put} logs every real * put, so its absence here is proof the file was never generated * this turn.

    2. - *
  2. The 10-min cache entry expired before the IM client got around - * to clicking, or was wiped on JVM restart.
    3. + *
  3. The persisted entry was swept after its retention window + * ({@link GeneratedFileCache#TTL}) elapsed before the IM client + * got around to clicking.
    4. *
* Without this rewrite, IM clients tap a markdown link that returns * 404, save the HTML 404 body as the requested file extension, then diff --git a/mateclaw-server/src/main/java/vip/mate/channel/media/InboundMediaDownloader.java b/mateclaw-server/src/main/java/vip/mate/channel/media/InboundMediaDownloader.java new file mode 100644 index 00000000..5e09be6d --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/channel/media/InboundMediaDownloader.java @@ -0,0 +1,286 @@ +package vip.mate.channel.media; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import vip.mate.channel.ExponentialBackoff; + +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.security.MessageDigest; +import java.util.Optional; +import java.util.function.Function; + +/** + * Shared inbound-media pipeline for IM channels. + * + *

Every channel that receives images / files / audio / video from users + * needs the same three steps after it knows how to fetch the raw bytes: + *

    + *
  1. fetch with retry + backoff (mobile uploads over flaky networks fail + * transiently — a single attempt drops the attachment);
    2. + *
  2. sniff the real type from magic bytes so the stored file and the + * {@code MessageContentPart} carry an accurate MIME (a screenshot saved + * as {@code image.jpg} but actually PNG/WEBP/HEIC otherwise gets a wrong + * Content-Type that some multimodal gateways reject);
    3. + *
  3. write to disk under a collision-resistant, URL-safe name.
    4. + *
+ * + *

The channel-specific protocol (AES decryption, API auth, CDN URL shape) + * stays in the adapter and is supplied as a {@link ByteSource}. This class owns + * only the cross-channel concerns above. + */ +public final class InboundMediaDownloader { + + private static final Logger log = LoggerFactory.getLogger(InboundMediaDownloader.class); + + private InboundMediaDownloader() { + } + + /** + * Fetches the raw (already-decrypted) bytes for a piece of media. May throw; + * the downloader retries a throwing source before giving up. + */ + @FunctionalInterface + public interface ByteSource { + byte[] fetch() throws Exception; + } + + /** A successfully downloaded and typed file on local disk. */ + public record DownloadedMedia( + Path localPath, + String storedName, + String fileName, + String contentType, + long fileSize, + String fileUrl) { + + public boolean isImage() { + return contentType != null && contentType.startsWith("image/"); + } + + public boolean isVideo() { + return contentType != null && contentType.startsWith("video/"); + } + + public boolean isAudio() { + return contentType != null && contentType.startsWith("audio/"); + } + } + + /** Total fetch attempts (1 initial + retries) before giving up. */ + private static final int DEFAULT_MAX_ATTEMPTS = 3; + private static final long RETRY_INITIAL_DELAY_MS = 300; + private static final long RETRY_MAX_DELAY_MS = 3000; + + /** + * Download with the default retry policy and no servable URL. See + * {@link #download(ByteSource, String, Path, String, String, int, Function)}. + */ + public static Optional download(ByteSource source, + String filenameHint, + Path targetDir, + String storedNamePrefix, + String dedupSeed) { + return download(source, filenameHint, targetDir, storedNamePrefix, dedupSeed, + DEFAULT_MAX_ATTEMPTS, null); + } + + /** + * Download with a custom attempt count and no servable URL. See + * {@link #download(ByteSource, String, Path, String, String, int, Function)}. + */ + public static Optional download(ByteSource source, + String filenameHint, + Path targetDir, + String storedNamePrefix, + String dedupSeed, + int maxAttempts) { + return download(source, filenameHint, targetDir, storedNamePrefix, dedupSeed, maxAttempts, null); + } + + /** + * Download with the default retry policy and a servable-URL builder. See + * {@link #download(ByteSource, String, Path, String, String, int, Function)}. + */ + public static Optional download(ByteSource source, + String filenameHint, + Path targetDir, + String storedNamePrefix, + String dedupSeed, + Function fileUrlBuilder) { + return download(source, filenameHint, targetDir, storedNamePrefix, dedupSeed, + DEFAULT_MAX_ATTEMPTS, fileUrlBuilder); + } + + /** + * Fetch the bytes (with retry), detect the real type, and persist the file. + * + * @param source fetches the decrypted bytes; retried on failure + * @param filenameHint the real user-supplied filename when known, else + * {@code null}/blank. A name with a meaningful + * extension is kept; a blank, extension-less, or + * {@code .bin} hint is replaced with the sniffed + * extension + * @param targetDir directory to write into (created if absent) + * @param storedNamePrefix short channel tag prefixed to the stored file + * name (e.g. {@code "weixin"}) + * @param dedupSeed stable string (e.g. the source URL / media key) + * hashed into the stored name so the same media maps + * to the same file + * @param maxAttempts total fetch attempts (>= 1) + * @param fileUrlBuilder optional mapping from the stored filename to a + * browser-servable URL (e.g. + * {@code name -> "/api/v1/chat/files/" + convId + "/" + name}); + * {@code null} leaves {@link DownloadedMedia#fileUrl()} + * null for channels with no serve path + * @return the stored file, or empty when every attempt failed + */ + public static Optional download(ByteSource source, + String filenameHint, + Path targetDir, + String storedNamePrefix, + String dedupSeed, + int maxAttempts, + Function fileUrlBuilder) { + byte[] data = fetchWithRetry(source, Math.max(1, maxAttempts), filenameHint); + if (data == null || data.length == 0) { + return Optional.empty(); + } + try { + Files.createDirectories(targetDir); + + MediaTypeSniffer.Sniffed sniff = MediaTypeSniffer.sniff(data); + + // Derive a display name. The hint is authoritative only when the + // caller passed a real user-supplied filename with a meaningful + // extension; for media the caller passes null/blank and we + // synthesize a name from the sniffed type. ".bin" is treated as + // "no real extension" since it is the universal unknown-binary + // placeholder. This keeps the contract channel-agnostic — no + // per-channel sentinel names leak into this shared layer. + String safeName = sanitize(filenameHint); + boolean hintIsGeneric = "media".equals(safeName) + || !safeName.contains(".") + || safeName.toLowerCase().endsWith(".bin"); + String fileName = safeName; + if (hintIsGeneric && sniff.isKnown()) { + fileName = stripExtension(safeName) + sniff.extension(); + } + + String seed = (dedupSeed == null || dedupSeed.isBlank()) ? fileName : dedupSeed; + String hash = md5Short(seed); + String prefix = (storedNamePrefix == null || storedNamePrefix.isBlank()) + ? "media" : sanitize(storedNamePrefix); + String storedName = prefix + "_" + hash + "_" + fileName; + + Path filePath = targetDir.resolve(storedName); + Files.write(filePath, data); + + // Prefer the sniffed MIME; fall back to extension-based guess only + // when sniffing was inconclusive. + String contentType = sniff.isKnown() ? sniff.contentType() : mimeFromExtension(fileName); + + String fileUrl = null; + if (fileUrlBuilder != null) { + try { + fileUrl = fileUrlBuilder.apply(storedName); + } catch (Exception e) { + log.warn("[media] fileUrl builder failed for {}: {}", storedName, e.getMessage()); + } + } + + log.info("[media] Inbound media saved: {} ({} bytes, type={}, sniffed={})", + filePath, data.length, contentType, sniff.isKnown()); + return Optional.of(new DownloadedMedia( + filePath.toAbsolutePath(), + storedName, + fileName, + contentType, + data.length, + fileUrl)); + } catch (Exception e) { + log.error("[media] Failed to persist inbound media (hint={}): {}", filenameHint, e.getMessage(), e); + return Optional.empty(); + } + } + + private static byte[] fetchWithRetry(ByteSource source, int maxAttempts, String hint) { + ExponentialBackoff backoff = new ExponentialBackoff( + RETRY_INITIAL_DELAY_MS, RETRY_MAX_DELAY_MS, 2.0, maxAttempts, 0.2); + Exception last = null; + for (int attempt = 1; attempt <= maxAttempts; attempt++) { + try { + byte[] data = source.fetch(); + if (data != null && data.length > 0) { + return data; + } + log.warn("[media] Download attempt {}/{} returned empty (hint={})", attempt, maxAttempts, hint); + } catch (Exception e) { + last = e; + log.warn("[media] Download attempt {}/{} failed (hint={}): {}", + attempt, maxAttempts, hint, e.getMessage()); + } + if (attempt < maxAttempts) { + try { + Thread.sleep(backoff.nextDelayMs()); + } catch (InterruptedException ie) { + Thread.currentThread().interrupt(); + break; + } + } + } + if (last != null) { + log.error("[media] Download exhausted after {} attempts (hint={}): {}", + maxAttempts, hint, last.getMessage()); + } + return null; + } + + /** Strip everything except a safe, file-system-friendly character set. */ + private static String sanitize(String name) { + String raw = (name == null) ? "" : name.trim(); + String safe = raw.replaceAll("[^a-zA-Z0-9._-]", "_"); + return safe.isBlank() ? "media" : safe; + } + + private static String stripExtension(String name) { + int dot = name.lastIndexOf('.'); + return dot > 0 ? name.substring(0, dot) : name; + } + + private static String mimeFromExtension(String fileName) { + String lower = fileName.toLowerCase(); + int dot = lower.lastIndexOf('.'); + String ext = dot >= 0 ? lower.substring(dot + 1) : ""; + return switch (ext) { + case "jpg", "jpeg" -> "image/jpeg"; + case "png" -> "image/png"; + case "gif" -> "image/gif"; + case "webp" -> "image/webp"; + case "heic", "heif" -> "image/heic"; + case "bmp" -> "image/bmp"; + case "mp4" -> "video/mp4"; + case "mov" -> "video/quicktime"; + case "mp3" -> "audio/mpeg"; + case "amr" -> "audio/amr"; + case "wav" -> "audio/wav"; + case "pdf" -> "application/pdf"; + default -> "application/octet-stream"; + }; + } + + private static String md5Short(String input) { + try { + MessageDigest md = MessageDigest.getInstance("MD5"); + byte[] digest = md.digest(input.getBytes(StandardCharsets.UTF_8)); + StringBuilder sb = new StringBuilder(); + for (int i = 0; i < 4; i++) { + sb.append(String.format("%02x", digest[i])); + } + return sb.toString(); + } catch (Exception e) { + return Integer.toHexString(input.hashCode()); + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/channel/media/MediaTypeSniffer.java b/mateclaw-server/src/main/java/vip/mate/channel/media/MediaTypeSniffer.java new file mode 100644 index 00000000..0c1ce104 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/channel/media/MediaTypeSniffer.java @@ -0,0 +1,281 @@ +package vip.mate.channel.media; + +import java.io.ByteArrayInputStream; +import java.nio.charset.StandardCharsets; +import java.util.zip.ZipEntry; +import java.util.zip.ZipInputStream; + +/** + * Best-effort MIME / extension detection from a file's leading bytes. + * + *

IM channels frequently deliver media without a reliable filename or + * Content-Type: forwarded files arrive nameless, and personal-WeChat images + * are saved with a fixed {@code image.jpg} hint regardless of the real format. + * Labelling a PNG / WEBP / HEIC photo as {@code image/jpeg} makes some + * multimodal model gateways reject the request, and a nameless PDF saved as + * {@code file.bin} stops PDF tools from firing. Sniffing the magic bytes + * recovers an accurate type so downstream routing and vision models work. + * + *

Covers the formats users routinely send to bots: common raster images + * (incl. HEIC from iPhones and WEBP from screenshots), documents, archives, + * and audio / video containers. ZIP-based containers (DOCX/XLSX/PPTX/ODF/EPUB/ + * JAR) share one magic number, so a successful ZIP match is refined by peeking + * at the first archive entries. + */ +public final class MediaTypeSniffer { + + private MediaTypeSniffer() { + } + + /** Sniff result: a leading-dot extension plus the matching MIME type. */ + public record Sniffed(String extension, String contentType) { + /** Fallback when no signature matches. */ + public static final Sniffed UNKNOWN = new Sniffed(".bin", "application/octet-stream"); + + public boolean isKnown() { + return !UNKNOWN.equals(this); + } + + public boolean isImage() { + return contentType.startsWith("image/"); + } + + public boolean isVideo() { + return contentType.startsWith("video/"); + } + + public boolean isAudio() { + return contentType.startsWith("audio/"); + } + } + + /** + * Detect the type of {@code data} from its leading bytes. + * + * @param data the full file bytes (may be null/empty — returns + * {@link Sniffed#UNKNOWN}); only the first bytes are inspected, + * except for ZIP containers which are scanned a little deeper. + * @return the detected type, never null. + */ + public static Sniffed sniff(byte[] data) { + if (data == null || data.length < 4) { + return Sniffed.UNKNOWN; + } + + Sniffed basic = sniffHead(data); + // ZIP container needs a deeper look — DOCX/XLSX/PPTX/ODF/EPUB/JAR all + // share the PK\x03\x04 magic. Peek inside the first few entries. + if (".zip".equals(basic.extension())) { + return refineZipKind(data, basic); + } + return basic; + } + + /** Signature match against the leading bytes only. */ + private static Sniffed sniffHead(byte[] h) { + // PDF: %PDF + if (match(h, 0x25, 0x50, 0x44, 0x46)) { + return new Sniffed(".pdf", "application/pdf"); + } + // PNG: 89 50 4E 47 + if (match(h, 0x89, 0x50, 0x4E, 0x47)) { + return new Sniffed(".png", "image/png"); + } + // JPEG: FF D8 FF + if (match(h, 0xFF, 0xD8, 0xFF)) { + return new Sniffed(".jpg", "image/jpeg"); + } + // GIF: "GIF8" + if (match(h, 0x47, 0x49, 0x46, 0x38)) { + return new Sniffed(".gif", "image/gif"); + } + // BMP: "BM" + if (match(h, 0x42, 0x4D)) { + return new Sniffed(".bmp", "image/bmp"); + } + // TIFF: little-endian "II*\0" or big-endian "MM\0*" + if (match(h, 0x49, 0x49, 0x2A, 0x00) || match(h, 0x4D, 0x4D, 0x00, 0x2A)) { + return new Sniffed(".tiff", "image/tiff"); + } + // RIFF container: bytes 0..3 = "RIFF", bytes 8..11 identify the payload. + // WEBP is the one users send (screenshots / phone photos); WAV is audio. + if (h.length >= 12 && match(h, 0x52, 0x49, 0x46, 0x46)) { + if (matchAt(h, 8, 0x57, 0x45, 0x42, 0x50)) { // "WEBP" + return new Sniffed(".webp", "image/webp"); + } + if (matchAt(h, 8, 0x57, 0x41, 0x56, 0x45)) { // "WAVE" + return new Sniffed(".wav", "audio/wav"); + } + } + // ISO Base Media (ftyp at bytes 4..7). The brand at bytes 8..11 + // distinguishes HEIC photos / M4A audio / QuickTime from plain MP4 — + // critical because iPhone photos are HEIC, not video. + if (h.length >= 12 && matchAt(h, 4, 0x66, 0x74, 0x79, 0x70)) { + return classifyFtyp(brandAt(h, 8)); + } + // ZIP-based container: PK\x03\x04 (refined by the caller). + if (match(h, 0x50, 0x4B, 0x03, 0x04)) { + return new Sniffed(".zip", "application/zip"); + } + // Legacy Office (DOC/XLS/PPT): D0 CF 11 E0 A1 B1 1A E1 + if (h.length >= 8 && match(h, 0xD0, 0xCF, 0x11, 0xE0, 0xA1, 0xB1, 0x1A, 0xE1)) { + return new Sniffed(".doc", "application/msword"); + } + // RTF: "{\rtf" + if (h.length >= 5 && match(h, 0x7B, 0x5C, 0x72, 0x74, 0x66)) { + return new Sniffed(".rtf", "application/rtf"); + } + // 7z: 37 7A BC AF 27 1C + if (h.length >= 6 && match(h, 0x37, 0x7A, 0xBC, 0xAF, 0x27, 0x1C)) { + return new Sniffed(".7z", "application/x-7z-compressed"); + } + // RAR: "Rar!\x1A\x07" + if (h.length >= 6 && match(h, 0x52, 0x61, 0x72, 0x21, 0x1A, 0x07)) { + return new Sniffed(".rar", "application/x-rar-compressed"); + } + // MP3: ID3v2 tag "ID3" + if (match(h, 0x49, 0x44, 0x33)) { + return new Sniffed(".mp3", "audio/mpeg"); + } + // MP3: MPEG audio frame sync (0xFFFB / 0xFFF3 / 0xFFF2) + if ((h[0] & 0xFF) == 0xFF && (h[1] & 0xE0) == 0xE0) { + return new Sniffed(".mp3", "audio/mpeg"); + } + // OGG: "OggS" + if (match(h, 0x4F, 0x67, 0x67, 0x53)) { + return new Sniffed(".ogg", "audio/ogg"); + } + // AMR (WeChat / WeCom voice): "#!AMR" + if (h.length >= 5 && match(h, 0x23, 0x21, 0x41, 0x4D, 0x52)) { + return new Sniffed(".amr", "audio/amr"); + } + // SILK (WeChat voice): "#!SILK" + if (h.length >= 6 && match(h, 0x23, 0x21, 0x53, 0x49, 0x4C, 0x4B)) { + return new Sniffed(".silk", "audio/silk"); + } + return Sniffed.UNKNOWN; + } + + /** Map an ISO-BMFF major brand to a concrete type. */ + private static Sniffed classifyFtyp(String brand) { + if (brand == null) { + return new Sniffed(".mp4", "video/mp4"); + } + // HEIF / HEIC still images (iPhone camera default). + switch (brand) { + case "heic", "heix", "heim", "heis", "hevc", "hevx", "hevm", "hevs", + "mif1", "msf1" -> { + return new Sniffed(".heic", "image/heic"); + } + case "avif", "avis" -> { + return new Sniffed(".avif", "image/avif"); + } + case "qt " -> { + return new Sniffed(".mov", "video/quicktime"); + } + case "M4A ", "M4B " -> { + return new Sniffed(".m4a", "audio/mp4"); + } + case "M4V " -> { + return new Sniffed(".m4v", "video/x-m4v"); + } + default -> { + return new Sniffed(".mp4", "video/mp4"); + } + } + } + + /** + * Peek inside a ZIP container to distinguish OOXML (DOCX/XLSX/PPTX), ODF + * (ODT/ODS/ODP), JAR, and EPUB from a plain ZIP. Reads local file headers + * in order; the discriminator entry is almost always within the first few + * entries, so iteration is capped at 16 to bound CPU. Returns the supplied + * {@code zipDefault} when nothing specific is detected. + */ + private static Sniffed refineZipKind(byte[] data, Sniffed zipDefault) { + if (data == null || data.length < 30) { + return zipDefault; + } + String mimetypeContent = null; + try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(data))) { + ZipEntry entry; + int seen = 0; + while ((entry = zis.getNextEntry()) != null && seen < 16) { + seen++; + String name = entry.getName(); + if (name.startsWith("word/")) { + return new Sniffed(".docx", + "application/vnd.openxmlformats-officedocument.wordprocessingml.document"); + } + if (name.startsWith("xl/")) { + return new Sniffed(".xlsx", + "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); + } + if (name.startsWith("ppt/")) { + return new Sniffed(".pptx", + "application/vnd.openxmlformats-officedocument.presentationml.presentation"); + } + if (name.startsWith("visio/")) { + return new Sniffed(".vsdx", "application/vnd.ms-visio.drawing"); + } + if ("META-INF/MANIFEST.MF".equals(name)) { + return new Sniffed(".jar", "application/java-archive"); + } + // EPUB always carries META-INF/container.xml. + if ("META-INF/container.xml".equals(name)) { + return new Sniffed(".epub", "application/epub+zip"); + } + // ODF / EPUB also declare the type in a leading "mimetype" entry. + if ("mimetype".equals(name)) { + byte[] body = zis.readAllBytes(); + mimetypeContent = new String(body, StandardCharsets.UTF_8).trim(); + } + } + } catch (Exception e) { + return zipDefault; + } + // Match leniently (contains) — the mimetype body occasionally carries a + // trailing newline or charset noise. + if (mimetypeContent != null) { + if (mimetypeContent.contains("opendocument.text")) { + return new Sniffed(".odt", "application/vnd.oasis.opendocument.text"); + } + if (mimetypeContent.contains("opendocument.spreadsheet")) { + return new Sniffed(".ods", "application/vnd.oasis.opendocument.spreadsheet"); + } + if (mimetypeContent.contains("opendocument.presentation")) { + return new Sniffed(".odp", "application/vnd.oasis.opendocument.presentation"); + } + if (mimetypeContent.contains("epub")) { + return new Sniffed(".epub", "application/epub+zip"); + } + } + return zipDefault; + } + + /** True when the leading bytes equal the given unsigned-byte signature. */ + private static boolean match(byte[] data, int... signature) { + return matchAt(data, 0, signature); + } + + /** True when bytes starting at {@code offset} equal the signature. */ + private static boolean matchAt(byte[] data, int offset, int... signature) { + if (data.length < offset + signature.length) { + return false; + } + for (int i = 0; i < signature.length; i++) { + if ((data[offset + i] & 0xFF) != (signature[i] & 0xFF)) { + return false; + } + } + return true; + } + + /** Read a 4-character ASCII brand at the given offset, or null. */ + private static String brandAt(byte[] data, int offset) { + if (data.length < offset + 4) { + return null; + } + return new String(data, offset, 4, StandardCharsets.US_ASCII); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java b/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java index f6d453b8..37ee1637 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/web/ChatController.java @@ -61,6 +61,7 @@ public class ChatController { private final ChatStreamTracker streamTracker; private final ObjectMapper objectMapper; private final ConversationCompletionPublisher completionPublisher; + private final vip.mate.memory.identity.MemoryOwnerResolver memoryOwnerResolver; private final Path uploadRoot = Paths.get("data", "chat-uploads"); // 使用虚拟线程池处理 SSE（Java 17+ 兼容，Java 21 可用 Executors.newVirtualThreadPerTaskExecutor()） @@ -543,7 +544,7 @@ public class ChatController { // tools that need a workspace path read it from the agent (origin // is enriched with workspaceBasePath in StateGraph buildInitialState). vip.mate.agent.context.ChatOrigin webOrigin = - vip.mate.agent.context.ChatOrigin.web(conversationId, username, workspaceId, null); + memoryOrigin(conversationId, username, workspaceId, request.getEndUserId()); Disposable disposable = agentService.chatStructuredStream(agentId, promptText, conversationId, username, request.getThinkingLevel(), webOrigin) .doOnNext(delta -> { if (emitterDone.get()) return; @@ -630,7 +631,12 @@ public class ChatController { // garbage like "[错误] Bad request..." as the assistant reply, // which would pollute the memory extraction pipeline if propagated. if (!wasStopped && !isError) { - completionPublisher.publish(agentId, conversationId, message, assistantText, "web"); + // Attribute the memory write to the same owner the read + // path recalled this turn — the publish runs in a reactive + // completion callback after the origin holder is cleared, + // so resolve from the captured webOrigin explicitly. + completionPublisher.publish(agentId, conversationId, message, assistantText, "web", + memoryOwnerResolver.resolve(webOrigin)); } if (isInterruptFollowup) { @@ -1035,9 +1041,17 @@ public class ChatController { conversationService.saveMessage(request.getConversationId(), "user", request.getMessage(), request.getContentParts()); String promptText = buildPromptText(request.getMessage(), request.getContentParts()); - String response = agentService.chat(agentId, promptText, request.getConversationId()); - conversationService.saveMessage(request.getConversationId(), "assistant", response); - completionPublisher.publish(agentId, request.getConversationId(), request.getMessage(), response, "web"); + // Carry the web origin so per-owner memory recall (read) and the + // post-conversation memory write below agree on the same owner key. + vip.mate.agent.context.ChatOrigin webOrigin = + memoryOrigin(request.getConversationId(), username, workspaceId, request.getEndUserId()); + AgentService.ChatResult result = agentService.chatWithUsage(agentId, promptText, request.getConversationId(), webOrigin); + String response = result.content(); + conversationService.saveMessage(request.getConversationId(), "assistant", response, null, "completed", + result.promptTokens(), result.completionTokens(), + result.runtimeModel(), result.runtimeProvider()); + completionPublisher.publish(agentId, request.getConversationId(), request.getMessage(), response, "web", + memoryOwnerResolver.resolve(webOrigin)); return R.ok(response); } @@ -1120,11 +1134,36 @@ public class ChatController { .body(resource); } + /** + * Build the {@link vip.mate.agent.context.ChatOrigin} that drives per-owner + * memory isolation for a web request. When {@code endUserId} is supplied + * (third-party single-account integration) the origin is attributed to that + * external end-user ({@code api:}); otherwise to the logged-in + * MateClaw user ({@code user:}). + */ + private vip.mate.agent.context.ChatOrigin memoryOrigin(String conversationId, String username, + Long workspaceId, String endUserId) { + if (endUserId != null && !endUserId.isBlank()) { + return vip.mate.agent.context.ChatOrigin + .web(conversationId, endUserId.trim(), workspaceId, null) + .withSender(null, "api", null); + } + return vip.mate.agent.context.ChatOrigin.web(conversationId, username, workspaceId, null); + } + @lombok.Data public static class ChatRequest { private String message; private String conversationId = "default"; private List contentParts; + /** + * Optional third-party end-user identifier. When a single MateClaw + * account (e.g. one PAT) fronts many of an external system's users, + * pass that system's user id here so memory and recall are isolated + * per end-user. Kept as a string (never coerced to a number) to + * preserve precision of large external ids. + */ + private String endUserId; } @lombok.Data @@ -1164,6 +1203,12 @@ public class ChatController { private String modelProvider; /** Model id the user picked for this conversation. See {@link #modelProvider}. */ private String modelName; + /** + * Optional third-party end-user identifier — see + * {@link ChatRequest#getEndUserId()}. Isolates memory per external + * end-user when one MateClaw account fronts many of them. + */ + private String endUserId; } /** diff --git a/mateclaw-server/src/main/java/vip/mate/channel/web/TalkModeWebSocketHandler.java b/mateclaw-server/src/main/java/vip/mate/channel/web/TalkModeWebSocketHandler.java index 45bd703c..b487663d 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/web/TalkModeWebSocketHandler.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/web/TalkModeWebSocketHandler.java @@ -144,18 +144,26 @@ public class TalkModeWebSocketHandler extends AbstractWebSocketHandler { talkSession.conversationId, talkSession.agentId, talkSession.username, talkWsId); conversationService.saveMessage(talkSession.conversationId, "user", transcript, List.of()); - // 5. Agent 对话（同步） - String reply = agentService.chat(talkSession.agentId, transcript, talkSession.conversationId); + // 5. Agent 对话（同步）。Carry the voice user's identity so per-owner + // memory recall (read) and the post-turn memory write (below) agree + // on the same owner key. + vip.mate.agent.context.ChatOrigin talkOrigin = vip.mate.agent.context.ChatOrigin.web( + talkSession.conversationId, talkSession.username, talkWsId, null); + AgentService.ChatResult chatResult = agentService.chatWithUsage( + talkSession.agentId, transcript, talkSession.conversationId, talkOrigin); + String reply = chatResult.content(); if (reply == null || reply.isBlank()) { reply = "Sorry, I couldn't generate a response."; } - // 6. 保存助手回复 - conversationService.saveMessage(talkSession.conversationId, "assistant", reply, List.of()); + // 6. 保存助手回复（携带 token usage + runtime model 归属） + conversationService.saveMessage(talkSession.conversationId, "assistant", reply, List.of(), + "completed", chatResult.promptTokens(), chatResult.completionTokens(), + chatResult.runtimeModel(), chatResult.runtimeProvider()); // Publish conversation-completed event so memory extraction runs for voice turns too. - completionPublisher.publish(talkSession.agentId, talkSession.conversationId, - transcript, reply, "talk"); + completionPublisher.publishForOrigin(talkSession.agentId, talkSession.conversationId, + transcript, reply, "talk", talkOrigin); // 7. 推送文字回复 sendJson(session, Map.of("type", "reply", "text", reply)); diff --git a/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java b/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java index 4cd0f572..0b16ddb3 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/webchat/WebChatController.java @@ -50,6 +50,7 @@ public class WebChatController { private final ChatStreamTracker streamTracker; private final ObjectMapper objectMapper; private final ConversationCompletionPublisher completionPublisher; + private final vip.mate.memory.identity.MemoryOwnerResolver memoryOwnerResolver; private final ExecutorService sseExecutor = Executors.newCachedThreadPool(); @@ -118,9 +119,30 @@ public class WebChatController { // Pattern mirrors ChatController: always accumulate, only broadcast when the // delta is not a persistence-only echo of content already streamed by inner nodes. StringBuilder assistantReply = new StringBuilder(); + // Token usage + model attribution: capture _usage_final event emitted at stream end + final int[] usage = {0, 0}; // [promptTokens, completionTokens] + final String[] modelInfo = {null, null}; // [runtimeModel, runtimeProvider] - agentService.chatStructuredStream(agentId, message, conversationId, visitorId) + // Attribute memory to this external visitor so each end-user + // behind the shared webchat account is isolated. The same origin + // resolves the owner key for both the read (recall) and write + // (publish) paths below. + vip.mate.agent.context.ChatOrigin webchatOrigin = + vip.mate.agent.context.ChatOrigin.web(conversationId, visitorId, webWsId, null) + .withSender(null, "api", null); + String webchatOwnerKey = memoryOwnerResolver.resolve(webchatOrigin); + + agentService.chatStructuredStream(agentId, message, conversationId, visitorId, null, webchatOrigin) .doOnNext(delta -> { + if (delta.isEvent() && "_usage_final".equals(delta.eventType())) { + Map data = delta.eventData(); + usage[0] = ((Number) data.getOrDefault("promptTokens", 0)).intValue(); + usage[1] = ((Number) data.getOrDefault("completionTokens", 0)).intValue(); + Object model = data.get("runtimeModelName"); + Object provider = data.get("runtimeProviderId"); + if (model != null) modelInfo[0] = model.toString(); + if (provider != null) modelInfo[1] = provider.toString(); + } if (delta.content() != null && !delta.content().isEmpty()) { assistantReply.append(delta.content()); if (!delta.persistenceOnly()) { @@ -139,10 +161,11 @@ public class WebChatController { try { if (!reply.isBlank()) { conversationService.saveMessage( - conversationId, "assistant", reply, List.of()); + conversationId, "assistant", reply, List.of(), + "completed", usage[0], usage[1], modelInfo[0], modelInfo[1]); } completionPublisher.publish( - agentId, conversationId, message, reply, "webchat"); + agentId, conversationId, message, reply, "webchat", webchatOwnerKey); } catch (Exception persistErr) { log.warn("[WebChat] Failed to persist assistant reply / publish event: {}", persistErr.getMessage()); diff --git a/mateclaw-server/src/main/java/vip/mate/channel/wecom/WeComChannelAdapter.java b/mateclaw-server/src/main/java/vip/mate/channel/wecom/WeComChannelAdapter.java index bc7f6f36..5243857c 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/wecom/WeComChannelAdapter.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/wecom/WeComChannelAdapter.java @@ -6,13 +6,13 @@ import vip.mate.channel.AbstractChannelAdapter; import vip.mate.channel.ChannelMessage; import vip.mate.channel.ChannelMessageRouter; import vip.mate.channel.ExponentialBackoff; +import vip.mate.channel.media.InboundMediaDownloader; import vip.mate.channel.model.ChannelEntity; import vip.mate.workspace.conversation.model.MessageContentPart; import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; -import java.io.ByteArrayInputStream; import java.io.InputStream; import java.net.URI; import java.net.http.HttpClient; @@ -27,8 +27,6 @@ import java.time.Duration; import java.time.LocalDateTime; import java.util.*; import java.util.concurrent.*; -import java.util.zip.ZipEntry; -import java.util.zip.ZipInputStream; import java.util.concurrent.atomic.AtomicBoolean; import java.util.concurrent.atomic.AtomicInteger; @@ -2847,13 +2845,15 @@ public class WeComChannelAdapter extends AbstractChannelAdapter { private MessageContentPart buildInboundImagePart(String url, String aesKey, String msgId, String fileNameHint, String conversationId) { if (getConfigBoolean("media_download_enabled", true)) { - InboundMediaResult r = downloadInboundMedia(url, aesKey, msgId, fileNameHint, conversationId); + InboundMediaDownloader.DownloadedMedia r = + downloadInboundMedia(url, aesKey, msgId, fileNameHint, conversationId); if (r != null) { + String localPath = r.localPath().toString(); MessageContentPart part = new MessageContentPart(); part.setType("image"); part.setFileName(r.fileName()); part.setStoredName(r.storedName()); - part.setPath(r.localPath()); + part.setPath(localPath); part.setFileUrl(r.fileUrl()); part.setFileSize(r.fileSize()); // Prefer the sniffed contentType (could be image/png) over a @@ -2863,7 +2863,7 @@ public class WeComChannelAdapter extends AbstractChannelAdapter { part.setContentType((ct != null && ct.startsWith("image/")) ? ct : "image/jpeg"); // mediaId mirrors path so callers that prefer it still resolve // to the same on-disk file (matches Web upload's behaviour). - part.setMediaId(r.localPath()); + part.setMediaId(localPath); return part; } } @@ -2891,17 +2891,19 @@ public class WeComChannelAdapter extends AbstractChannelAdapter { private MessageContentPart buildInboundFilePart(String url, String aesKey, String msgId, String fileNameHint, String conversationId) { if (getConfigBoolean("media_download_enabled", true)) { - InboundMediaResult r = downloadInboundMedia(url, aesKey, msgId, fileNameHint, conversationId); + InboundMediaDownloader.DownloadedMedia r = + downloadInboundMedia(url, aesKey, msgId, fileNameHint, conversationId); if (r != null) { + String localPath = r.localPath().toString(); MessageContentPart part = new MessageContentPart(); part.setType("file"); part.setFileName(r.fileName()); part.setStoredName(r.storedName()); - part.setPath(r.localPath()); + part.setPath(localPath); part.setFileUrl(r.fileUrl()); part.setFileSize(r.fileSize()); part.setContentType(r.contentType()); - part.setMediaId(r.localPath()); + part.setMediaId(localPath); return part; } } @@ -2916,285 +2918,43 @@ public class WeComChannelAdapter extends AbstractChannelAdapter { } /** - * Inbound-media download result. Carries every field the bubble renderer - * and the multimodal sidecar need so callers don't have to re-derive - * storedName / fileUrl from scratch. - * - * @param localPath absolute filesystem path of the saved file - * @param storedName the on-disk filename (matches the last segment of localPath) - * @param fileUrl browser-servable URL: {@code /api/v1/chat/files/{convId}/{storedName}} - * @param fileSize byte length after decryption - * @param fileName human-readable display name (extension corrected by magic-byte sniff) - * @param contentType MIME type derived from magic bytes (or {@code application/octet-stream}) + * Download + decrypt an inbound media attachment via the shared media + * pipeline, stored under {@code data/chat-uploads/{conversationId}/} so the + * existing {@code /api/v1/chat/files/...} endpoint can serve it back to the + * chat bubble. Returns the persisted, type-detected file, or {@code null} + * on download/decrypt failure (callers fall back to URL-only). */ - record InboundMediaResult(String localPath, String storedName, - String fileUrl, long fileSize, String fileName, - String contentType) {} - - /** Magic-byte sniff result. */ - private record MagicSniff(String extension, String contentType) { - static final MagicSniff UNKNOWN = new MagicSniff(".bin", "application/octet-stream"); - } - - /** - * Best-effort MIME sniff from the first 12 bytes of a file. Covers the - * formats users routinely forward to bots (PDF, Office, archives, common - * image / audio / video). When nothing matches, returns - * {@link MagicSniff#UNKNOWN} so the caller falls back to {@code .bin}. - *

- * This exists because WeCom's {@code aibot_msg_callback} {@code file} - * body sometimes omits {@code filename} entirely (forwarded files in - * particular), and shipping the agent a part labelled {@code file.bin} - * makes downstream tools mis-route the content. Sniffing recovers a - * useful extension so PDF tools fire on PDFs. - */ - private static MagicSniff sniffMagic(byte[] head) { - if (head == null || head.length < 4) return MagicSniff.UNKNOWN; - // PDF: %PDF - if (head[0] == 0x25 && head[1] == 0x50 && head[2] == 0x44 && head[3] == 0x46) { - return new MagicSniff(".pdf", "application/pdf"); - } - // PNG: 89 50 4E 47 - if (head[0] == (byte) 0x89 && head[1] == 0x50 && head[2] == 0x4E && head[3] == 0x47) { - return new MagicSniff(".png", "image/png"); - } - // JPEG: FF D8 FF - if (head[0] == (byte) 0xFF && head[1] == (byte) 0xD8 && head[2] == (byte) 0xFF) { - return new MagicSniff(".jpg", "image/jpeg"); - } - // GIF: "GIF8" - if (head[0] == 0x47 && head[1] == 0x49 && head[2] == 0x46 && head[3] == 0x38) { - return new MagicSniff(".gif", "image/gif"); - } - // ZIP-based container: PK\x03\x04. Could be a plain ZIP, a JAR, - // an OOXML document (DOCX/XLSX/PPTX), an ODF document (ODT/ODS/ODP), - // or an EPUB. Magic-byte alone can't tell them apart — caller is - // expected to follow up with refineZipKind(fullBytes) to pick a - // specific type. - if (head[0] == 0x50 && head[1] == 0x4B && head[2] == 0x03 && head[3] == 0x04) { - return new MagicSniff(".zip", "application/zip"); - } - // Legacy Office (DOC/XLS/PPT): D0 CF 11 E0 A1 B1 1A E1 - if (head.length >= 8 - && head[0] == (byte) 0xD0 && head[1] == (byte) 0xCF - && head[2] == 0x11 && head[3] == (byte) 0xE0 - && head[4] == (byte) 0xA1 && head[5] == (byte) 0xB1 - && head[6] == 0x1A && head[7] == (byte) 0xE1) { - return new MagicSniff(".doc", "application/msword"); - } - // RTF: "{\rtf" - if (head.length >= 5 - && head[0] == 0x7B && head[1] == 0x5C - && head[2] == 0x72 && head[3] == 0x74 && head[4] == 0x66) { - return new MagicSniff(".rtf", "application/rtf"); - } - // 7z: 37 7A BC AF 27 1C - if (head.length >= 6 - && head[0] == 0x37 && head[1] == 0x7A && head[2] == (byte) 0xBC - && head[3] == (byte) 0xAF && head[4] == 0x27 && head[5] == 0x1C) { - return new MagicSniff(".7z", "application/x-7z-compressed"); - } - // RAR: "Rar!\x1A\x07" - if (head.length >= 6 - && head[0] == 0x52 && head[1] == 0x61 && head[2] == 0x72 - && head[3] == 0x21 && head[4] == 0x1A && head[5] == 0x07) { - return new MagicSniff(".rar", "application/x-rar-compressed"); - } - // MP3: ID3v2 ("ID3") or MPEG sync 0xFFFB / 0xFFF3 / 0xFFF2 - if (head[0] == 0x49 && head[1] == 0x44 && head[2] == 0x33) { - return new MagicSniff(".mp3", "audio/mpeg"); - } - // MP4: "....ftyp" — bytes 4..7 == "ftyp" - if (head.length >= 8 - && head[4] == 0x66 && head[5] == 0x74 && head[6] == 0x79 && head[7] == 0x70) { - return new MagicSniff(".mp4", "video/mp4"); - } - // OGG: "OggS" - if (head[0] == 0x4F && head[1] == 0x67 && head[2] == 0x67 && head[3] == 0x53) { - return new MagicSniff(".ogg", "audio/ogg"); - } - return MagicSniff.UNKNOWN; - } - - /** - * Peek inside a ZIP container to distinguish OOXML (DOCX/XLSX/PPTX), - * ODF (ODT/ODS/ODP), JAR, and EPUB from a plain ZIP. Reads the local - * file headers in order via {@link ZipInputStream}; the discriminator - * entry is almost always within the first few entries (OOXML places - * {@code [Content_Types].xml} first, ODF places {@code mimetype} first), - * so we cap iteration at 16 entries to bound CPU. - *

- * Returns the original {@code zipDefault} sniff (plain - * {@code application/zip}) when no specific kind is detected — that's - * the right answer for actual ZIPs and unknown archive formats. - */ - private static MagicSniff refineZipKind(byte[] fileData, MagicSniff zipDefault) { - if (fileData == null || fileData.length < 30) return zipDefault; - String mimetypeContent = null; - try (ZipInputStream zis = new ZipInputStream(new ByteArrayInputStream(fileData))) { - ZipEntry entry; - int seen = 0; - while ((entry = zis.getNextEntry()) != null && seen < 16) { - String name = entry.getName(); - // OOXML — Office Open XML (Word/Excel/PowerPoint). Each format - // has a distinct top-level directory; we match on prefix - // because the entry order isn't guaranteed. - if (name.startsWith("word/")) { - return new MagicSniff(".docx", - "application/vnd.openxmlformats-officedocument.wordprocessingml.document"); - } - if (name.startsWith("xl/")) { - return new MagicSniff(".xlsx", - "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); - } - if (name.startsWith("ppt/")) { - return new MagicSniff(".pptx", - "application/vnd.openxmlformats-officedocument.presentationml.presentation"); - } - // Visio (rare but worth catching) - if (name.startsWith("visio/")) { - return new MagicSniff(".vsdx", - "application/vnd.ms-visio.drawing"); - } - // ODF marker: a {@code mimetype} entry that contains the full - // application/vnd.oasis.opendocument.* string — read its body - // and decide once we have it. - if ("mimetype".equals(name)) { - byte[] buf = zis.readAllBytes(); - mimetypeContent = new String(buf, java.nio.charset.StandardCharsets.UTF_8).trim(); - } - // JAR - if ("META-INF/MANIFEST.MF".equals(name)) { - return new MagicSniff(".jar", "application/java-archive"); - } - // EPUB always has META-INF/container.xml - if ("META-INF/container.xml".equals(name)) { - return new MagicSniff(".epub", "application/epub+zip"); - } - seen++; - } - } catch (Exception e) { - log.debug("[wecom] refineZipKind failed (treating as plain zip): {}", e.getMessage()); - return zipDefault; - } - if (mimetypeContent != null) { - if (mimetypeContent.contains("opendocument.text")) { - return new MagicSniff(".odt", "application/vnd.oasis.opendocument.text"); - } - if (mimetypeContent.contains("opendocument.spreadsheet")) { - return new MagicSniff(".ods", "application/vnd.oasis.opendocument.spreadsheet"); - } - if (mimetypeContent.contains("opendocument.presentation")) { - return new MagicSniff(".odp", "application/vnd.oasis.opendocument.presentation"); - } - if (mimetypeContent.contains("epub")) { - return new MagicSniff(".epub", "application/epub+zip"); - } - } - return zipDefault; - } - - /** - * Strip a trailing extension from a filename. {@code "image.jpg" → "image"}; - * {@code "no_ext" → "no_ext"}; {@code "" → ""}. - */ - private static String stripExtension(String name) { - if (name == null || name.isBlank()) return ""; - int dot = name.lastIndexOf('.'); - if (dot <= 0) return name; - return name.substring(0, dot); - } - - /** - * Download + decrypt an inbound media attachment and stash it under - * {@code data/chat-uploads/{conversationId}/} so the existing - * {@code /api/v1/chat/files/...} endpoint can serve it back to the chat - * bubble. Returns a fully-populated {@link InboundMediaResult} on success - * or null on download/decrypt failure (callers fall back to URL-only). - *

- * Storing under chat-uploads rather than {@code data/media} means - * {@link MessageContentPart#getPath()} resolves to a real file for the - * vision sidecar AND {@code fileUrl} renders as a thumbnail in the Web - * mirror — instead of the WeCom-signed CDN URL whose 5-minute query-string - * signature expires before the browser can fetch it. - */ - private InboundMediaResult downloadInboundMedia(String url, String aesKey, String msgId, + private InboundMediaDownloader.DownloadedMedia downloadInboundMedia(String url, String aesKey, String msgId, String fileNameHint, String conversationId) { - try { - // Mirror ChatController.uploadRoot ("data/chat-uploads") so the - // serve endpoint at /api/v1/chat/files/{convId}/{storedName} works - // without any extra wiring. The conversationId may contain ':' - // (e.g. "wecom:XuZhanFu" or "wecom:group:abc"); Path resolution - // tolerates this on macOS/Linux but Windows would reject the - // colon — for now we keep parity with the existing chat-uploads - // layout and revisit if Windows support comes up. - Path uploadDir = Path.of("data", "chat-uploads", conversationId); - Files.createDirectories(uploadDir); - - // 1. HTTP GET 下载文件 - HttpRequest request = HttpRequest.newBuilder() - .uri(URI.create(url)) - .timeout(Duration.ofSeconds(30)) - .GET() - .build(); - - HttpResponse response = httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream()); - byte[] encryptedData = response.body().readAllBytes(); - - byte[] fileData; - // 2. AES 解密（如果提供了 aesKey） - if (aesKey != null && !aesKey.isBlank()) { - fileData = decryptAes256Cbc(encryptedData, aesKey); - } else { - fileData = encryptedData; - } - - // 3. Magic-byte sniff to recover a real extension when WeCom - // didn't include filename in the body (forwarded files often - // arrive nameless — saving them as "file.bin" misroutes the - // agent because every PDF tool keys off the .pdf extension). - byte[] head = new byte[Math.min(12, fileData.length)]; - System.arraycopy(fileData, 0, head, 0, head.length); - MagicSniff sniff = sniffMagic(head); - // ZIP container needs a deeper look — DOCX/XLSX/PPTX/ODF/EPUB/JAR - // all share the PK\x03\x04 magic. Peek inside the first few - // entries to pick the specific kind. - if (".zip".equals(sniff.extension())) { - sniff = refineZipKind(fileData, sniff); - } - - // 4. Compose a URL-safe storedName. If the hint is generic - // (e.g. "file.bin"), prefer the sniffed extension. - String urlHash = md5Hex(url).substring(0, 8); - String hintRaw = (fileNameHint == null ? "media" : fileNameHint).trim(); - String safeName = hintRaw.replaceAll("[^a-zA-Z0-9._-]", "_"); - if (safeName.isBlank()) safeName = "media"; - // "file.bin" is the WeCom-no-filename sentinel; if magic gave us - // something better, replace the extension. Same when hint had no - // extension at all. - boolean hintIsGeneric = safeName.equals("file.bin") || safeName.equals("media") - || !safeName.contains("."); - if (hintIsGeneric && !".bin".equals(sniff.extension())) { - safeName = stripExtension(safeName) + sniff.extension(); - } - String storedName = "wecom_" + urlHash + "_" + safeName; - Path filePath = uploadDir.resolve(storedName); - Files.write(filePath, fileData); - - String fileUrl = "/api/v1/chat/files/" + conversationId + "/" + storedName; - log.info("[wecom] Inbound media saved: {} ({} bytes, sniffed={}), serve URL={}", - filePath, fileData.length, sniff.contentType(), fileUrl); - return new InboundMediaResult( - filePath.toAbsolutePath().toString(), - storedName, - fileUrl, - fileData.length, - safeName, - sniff.contentType()); - } catch (Exception e) { - log.error("[wecom] Failed to download inbound media: {}", e.getMessage(), e); - return null; - } + // Store under data/chat-uploads/{conversationId} so the existing + // /api/v1/chat/files/{convId}/{storedName} endpoint serves the file + // back to the chat bubble — the WeCom CDN URL carries a short-lived + // signature that expires before a browser can fetch it. The shared + // pipeline owns retry/backoff, magic-byte type detection, and the + // dedup-named write; the WeCom-specific AES-256-CBC decrypt stays here + // inside the byte source so a fetch + decrypt is retried as one unit. + Path uploadDir = Path.of("data", "chat-uploads", conversationId); + String hint = (fileNameHint == null || fileNameHint.isBlank()) ? null : fileNameHint; + return InboundMediaDownloader.download( + () -> { + HttpRequest request = HttpRequest.newBuilder() + .uri(URI.create(url)) + .timeout(Duration.ofSeconds(30)) + .GET() + .build(); + HttpResponse response = + httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream()); + byte[] encrypted = response.body().readAllBytes(); + return (aesKey != null && !aesKey.isBlank()) + ? decryptAes256Cbc(encrypted, aesKey) + : encrypted; + }, + hint, + uploadDir, + "wecom", + url, + storedName -> "/api/v1/chat/files/" + conversationId + "/" + storedName) + .orElse(null); } /** diff --git a/mateclaw-server/src/main/java/vip/mate/channel/weixin/WeixinChannelAdapter.java b/mateclaw-server/src/main/java/vip/mate/channel/weixin/WeixinChannelAdapter.java index d550302b..79e825f0 100644 --- a/mateclaw-server/src/main/java/vip/mate/channel/weixin/WeixinChannelAdapter.java +++ b/mateclaw-server/src/main/java/vip/mate/channel/weixin/WeixinChannelAdapter.java @@ -6,6 +6,7 @@ import vip.mate.channel.AbstractChannelAdapter; import vip.mate.channel.ChannelMessage; import vip.mate.channel.ChannelMessageRouter; import vip.mate.channel.ExponentialBackoff; +import vip.mate.channel.media.InboundMediaDownloader; import vip.mate.channel.model.ChannelEntity; import vip.mate.channel.weixin.error.TokenExpiredException; import vip.mate.common.security.SecretEquals; @@ -18,7 +19,6 @@ import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.file.Files; import java.nio.file.Path; -import java.security.MessageDigest; import java.time.Duration; import java.time.Instant; import java.time.LocalDateTime; @@ -406,7 +406,13 @@ public class WeixinChannelAdapter extends AbstractChannelAdapter { List> itemList = (List>) msg.getOrDefault("item_list", List.of()); boolean mediaDownloadEnabled = getConfigBoolean("media_download_enabled", true); - String mediaDir = getConfigString("media_dir", "data/media"); + // Inbound conversation id (see class doc): private "weixin:{user}", + // group "weixin:group:{group}". Downloaded media is stored under + // data/chat-uploads/{convId} so the /api/v1/chat/files endpoint can + // serve it back to the chat bubble / Web mirror. + String inboundConvId = !groupId.isBlank() + ? "weixin:group:" + groupId + : "weixin:" + fromUserId; for (Map item : itemList) { int itemType = item.get("type") instanceof Number n ? n.intValue() : 0; @@ -423,12 +429,21 @@ public class WeixinChannelAdapter extends AbstractChannelAdapter { case 2 -> { // Image if (mediaDownloadEnabled) { - String path = downloadMediaItem(item, "image_item", "image.jpg", mediaDir); - if (path != null) { + InboundMediaDownloader.DownloadedMedia dl = + downloadMediaItem(item, "image_item", null, inboundConvId); + if (dl != null) { MessageContentPart part = new MessageContentPart(); part.setType("image"); - part.setPath(path); - part.setContentType("image/*"); + part.setPath(dl.localPath().toString()); + part.setStoredName(dl.storedName()); + part.setFileUrl(dl.fileUrl()); + part.setMediaId(dl.localPath().toString()); + part.setFileName(dl.fileName()); + // Use the sniffed MIME (image/png, image/webp, image/heic, …) + // so vision gateways get an accurate Content-Type. Fall back + // to a concrete jpeg only when sniffing was inconclusive. + part.setContentType(dl.isImage() ? dl.contentType() : "image/jpeg"); + part.setFileSize(dl.fileSize()); contentParts.add(part); } else { // 下载失败，尝试构建 CDN URL @@ -484,15 +499,21 @@ public class WeixinChannelAdapter extends AbstractChannelAdapter { // ASR 为空：可能是语音过短、噪音、或 iLink API 字段变更 // 尝试下载语音文件保存到本地（供后续调试 / 自有 STT 使用） if (mediaDownloadEnabled) { - String voicePath = downloadMediaItem(item, "voice_item", "voice.amr", mediaDir); - if (voicePath != null) { - // 保存为 audio content part，即使无 ASR 文本 + InboundMediaDownloader.DownloadedMedia dl = + downloadMediaItem(item, "voice_item", null, inboundConvId); + if (dl != null) { + // Persist as an audio content part even without ASR text MessageContentPart audioPart = new MessageContentPart(); audioPart.setType("audio"); - audioPart.setPath(voicePath); - audioPart.setFileName("voice.amr"); + audioPart.setPath(dl.localPath().toString()); + audioPart.setStoredName(dl.storedName()); + audioPart.setFileUrl(dl.fileUrl()); + audioPart.setMediaId(dl.localPath().toString()); + audioPart.setFileName(dl.fileName()); + audioPart.setContentType(dl.contentType()); + audioPart.setFileSize(dl.fileSize()); contentParts.add(audioPart); - log.info("[weixin] Voice audio downloaded (no ASR): {}", voicePath); + log.info("[weixin] Voice audio downloaded (no ASR): {}", dl.localPath()); } } textParts.add("[语音消息]"); @@ -506,12 +527,18 @@ public class WeixinChannelAdapter extends AbstractChannelAdapter { String fileName = getStr(fileItemMap, "file_name"); if (fileName.isBlank()) fileName = "file.bin"; if (mediaDownloadEnabled) { - String path = downloadMediaItem(item, "file_item", fileName, mediaDir); - if (path != null) { + InboundMediaDownloader.DownloadedMedia dl = + downloadMediaItem(item, "file_item", fileName, inboundConvId); + if (dl != null) { MessageContentPart part = new MessageContentPart(); part.setType("file"); - part.setPath(path); - part.setFileName(fileName); + part.setPath(dl.localPath().toString()); + part.setStoredName(dl.storedName()); + part.setFileUrl(dl.fileUrl()); + part.setMediaId(dl.localPath().toString()); + part.setFileName(dl.fileName()); + part.setContentType(dl.contentType()); + part.setFileSize(dl.fileSize()); contentParts.add(part); } else { textParts.add("[文件: " + fileName + " 下载失败]"); @@ -523,12 +550,18 @@ public class WeixinChannelAdapter extends AbstractChannelAdapter { case 5 -> { // Video if (mediaDownloadEnabled) { - String path = downloadMediaItem(item, "video_item", "video.mp4", mediaDir); - if (path != null) { + InboundMediaDownloader.DownloadedMedia dl = + downloadMediaItem(item, "video_item", null, inboundConvId); + if (dl != null) { MessageContentPart part = new MessageContentPart(); part.setType("video"); - part.setPath(path); - part.setContentType("video/*"); + part.setPath(dl.localPath().toString()); + part.setStoredName(dl.storedName()); + part.setFileUrl(dl.fileUrl()); + part.setMediaId(dl.localPath().toString()); + part.setFileName(dl.fileName()); + part.setContentType(dl.isVideo() ? dl.contentType() : "video/mp4"); + part.setFileSize(dl.fileSize()); contentParts.add(part); } else { // 尝试构建 CDN URL @@ -604,42 +637,44 @@ public class WeixinChannelAdapter extends AbstractChannelAdapter { // ==================== 媒体下载 ==================== + /** + * Download an inbound media item via the shared media pipeline (retry + + * backoff, magic-byte type detection, dedup-named persistence). The iLink + * AES key extraction stays here because it is protocol-specific; the + * decrypted bytes are handed to {@link InboundMediaDownloader}. + * + * @return the stored, type-detected file, or {@code null} on failure + */ @SuppressWarnings("unchecked") - private String downloadMediaItem(Map item, String itemKey, String filenameHint, String mediaDir) { - try { - Map mediaItem = (Map) item.getOrDefault(itemKey, Map.of()); - Map media = (Map) mediaItem.getOrDefault("media", Map.of()); - String encryptQueryParam = getStr(media, "encrypt_query_param"); - String aesKey; + private InboundMediaDownloader.DownloadedMedia downloadMediaItem( + Map item, String itemKey, String filenameHint, String conversationId) { + Map mediaItem = (Map) item.getOrDefault(itemKey, Map.of()); + Map media = (Map) mediaItem.getOrDefault("media", Map.of()); + String encryptQueryParam = getStr(media, "encrypt_query_param"); - // image_item 有顶级 aeskey (hex) - String aeskeyHex = getStr(mediaItem, "aeskey"); - if (!aeskeyHex.isBlank()) { - aesKey = Base64.getEncoder().encodeToString(hexToBytes(aeskeyHex)); - } else { - aesKey = getStr(media, "aes_key"); - } + // image_item carries a top-level hex aeskey; other items use media.aes_key + final String aesKey; + String aeskeyHex = getStr(mediaItem, "aeskey"); + if (!aeskeyHex.isBlank()) { + aesKey = Base64.getEncoder().encodeToString(hexToBytes(aeskeyHex)); + } else { + aesKey = getStr(media, "aes_key"); + } - if (encryptQueryParam.isBlank()) { - log.warn("[weixin] No encrypt_query_param for media download"); - return null; - } - - byte[] data = client.downloadMedia("", aesKey, encryptQueryParam); - - // 保存到本地 - Path dir = Path.of(mediaDir); - Files.createDirectories(dir); - String safeFilename = filenameHint.replaceAll("[^a-zA-Z0-9._-]", ""); - if (safeFilename.isBlank()) safeFilename = "media"; - String urlHash = md5Short(encryptQueryParam); - Path filePath = dir.resolve("weixin_" + urlHash + "_" + safeFilename); - Files.write(filePath, data); - return filePath.toString(); - } catch (Exception e) { - log.error("[weixin] Media download failed: {}", e.getMessage(), e); + if (encryptQueryParam.isBlank()) { + log.warn("[weixin] No encrypt_query_param for media download"); return null; } + + Path uploadDir = Path.of("data", "chat-uploads", conversationId); + return InboundMediaDownloader.download( + () -> client.downloadMedia("", aesKey, encryptQueryParam), + filenameHint, + uploadDir, + "weixin", + encryptQueryParam, + storedName -> "/api/v1/chat/files/" + conversationId + "/" + storedName) + .orElse(null); } // ==================== 发送消息 ==================== @@ -1001,20 +1036,6 @@ public class WeixinChannelAdapter extends AbstractChannelAdapter { return val != null ? val.toString() : ""; } - private static String md5Short(String input) { - try { - MessageDigest md = MessageDigest.getInstance("MD5"); - byte[] digest = md.digest(input.getBytes()); - StringBuilder sb = new StringBuilder(); - for (int i = 0; i < 4; i++) { - sb.append(String.format("%02x", digest[i])); - } - return sb.toString(); - } catch (Exception e) { - return String.valueOf(input.hashCode()); - } - } - private static byte[] hexToBytes(String hex) { int len = hex.length(); byte[] data = new byte[len / 2]; diff --git a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java index fcb01f50..cfc7f123 100644 --- a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java +++ b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobLifecycleService.java @@ -9,6 +9,7 @@ import org.springframework.context.ApplicationEventPublisher; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Propagation; import org.springframework.transaction.annotation.Transactional; +import vip.mate.agent.AgentService; import vip.mate.cron.delivery.CronJobCompletedEvent; import vip.mate.cron.model.CronJobEntity; import vip.mate.dashboard.model.CronJobRunEntity; @@ -178,6 +179,20 @@ public class CronJobLifecycleService { public void finishRunAndPublish(CronJobEntity job, CronJobRunEntity run, String userMessage, AssistantMessage result, String conversationId, boolean silent) { + finishRunAndPublish(job, run, userMessage, result, conversationId, silent, null); + } + + /** + * @param chatResult optional usage attribution from the LLM path; pass + * {@code null} for non-LLM paths (e.g. reminder + * direct-push) so the assistant row is persisted with + * zero token counts and null runtime model attribution. + */ + @Transactional(propagation = Propagation.REQUIRES_NEW) + public void finishRunAndPublish(CronJobEntity job, CronJobRunEntity run, + String userMessage, AssistantMessage result, + String conversationId, boolean silent, + AgentService.ChatResult chatResult) { String convId = conversationId != null ? conversationId : run.getConversationId(); String text = result != null && result.getText() != null ? result.getText() : ""; @@ -197,7 +212,13 @@ public class CronJobLifecycleService { return; } - conversationService.saveMessage(convId, "assistant", text); + if (chatResult != null) { + conversationService.saveMessage(convId, "assistant", text, null, "completed", + chatResult.promptTokens(), chatResult.completionTokens(), + chatResult.runtimeModel(), chatResult.runtimeProvider()); + } else { + conversationService.saveMessage(convId, "assistant", text); + } // Memory pipeline (existing behavior preserved — was inline in the // old executeJob; now lives behind the same publisher used by the diff --git a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java index 9b3f453d..d8273750 100644 --- a/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java +++ b/mateclaw-server/src/main/java/vip/mate/cron/service/CronJobRunner.java @@ -138,10 +138,12 @@ public class CronJobRunner { // No-tx segment — long LLM call. RFC §5.2 hard rule: must not hold // any DB connection during this call. + AgentService.ChatResult chatResult; AssistantMessage result; try { ChatOrigin origin = originFactory.from(job, conversationId); - result = runAgent(job, userMessage, origin, conversationId); + chatResult = runAgent(job, userMessage, origin, conversationId); + result = new AssistantMessage(chatResult.content()); } catch (Exception e) { log.error("[CronRunner] runAgent failed for job {}: {}", job.getId(), e.getMessage(), e); try { @@ -156,12 +158,12 @@ public class CronJobRunner { // Explicit no-op: the agent answered with the silent sentinel, // meaning there is nothing to deliver or report for this run. - boolean silent = result != null && result.getText() != null + boolean silent = result.getText() != null && CRON_SILENT_MARKER.equals(result.getText().trim()); // T2 — short tx try { - lifecycle.finishRunAndPublish(job, run, userMessage, result, conversationId, silent); + lifecycle.finishRunAndPublish(job, run, userMessage, result, conversationId, silent, chatResult); } catch (Exception e) { log.error("[CronRunner] T2 finishRunAndPublish failed for job {}: {}", job.getId(), e.getMessage(), e); try { @@ -261,13 +263,14 @@ public class CronJobRunner { * Runs the agent with the scheduled-job {@link ChatOrigin} and the * execution-context prompt assembled by {@link #buildCronPrompt}. */ - private AssistantMessage runAgent(CronJobEntity job, String userMessage, ChatOrigin origin, - String conversationId) { + private AgentService.ChatResult runAgent(CronJobEntity job, String userMessage, ChatOrigin origin, + String conversationId) { String prompt = buildCronPrompt(userMessage, origin); - String text = "agent".equals(job.getTaskType()) - ? agentService.execute(job.getAgentId(), prompt, conversationId, origin) - : agentService.chat(job.getAgentId(), prompt, conversationId, origin); - return new AssistantMessage(text != null ? text : ""); + // execute() and chat() both ultimately route through the agent's + // StateGraph; chatWithUsage captures token + runtime model attribution + // for either path. Plan-Execute agents stream via the same + // chatStructuredStream the helper consumes. + return agentService.chatWithUsage(job.getAgentId(), prompt, conversationId, origin); } /** diff --git a/mateclaw-server/src/main/java/vip/mate/goal/config/GoalProperties.java b/mateclaw-server/src/main/java/vip/mate/goal/config/GoalProperties.java index 4e3d15b8..9c42da46 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/config/GoalProperties.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/config/GoalProperties.java @@ -7,10 +7,9 @@ import org.springframework.stereotype.Component; /** * Configuration knobs for the persistent-goal subsystem. * - *

{@link #enabled} is the master gate: when {@code false} (PR1-4 default) - * the StateGraph wiring stays inactive and {@code findActiveByConversation} - * still works for tests, but no graph node touches the table. PR5 flips it - * to {@code true}. + *

{@link #enabled} is the master gate: when {@code false} the StateGraph + * wiring stays inactive (no graph node touches the table), while + * {@code findActiveByConversation} still works for tests. */ @Data @Component @@ -20,12 +19,26 @@ public class GoalProperties { /** * Master switch — when off, the graph never invokes GoalEvaluationNode * (the conditional edge sees no active goal, so the node is unreachable). - * Defaults to true now that the full PR1-5 chain is in place; operators - * who want to disable goal evaluation can override via + * Operators who want to disable goal evaluation entirely can override via * {@code mateclaw.goal.enabled=false} in application.yml. */ private boolean enabled = true; + /** + * Create-time default for a goal's {@code autoFollowupEnabled} when the + * caller leaves it unspecified (null). Explicit true/false in the request + * is never overridden by this. + */ + private boolean defaultAutoFollowup = true; + + /** + * Runtime hard gate for auto-followup. When false, no goal injects a + * follow-up regardless of its per-goal {@code autoFollowupEnabled} flag — + * the operator's kill switch for the self-continuation loop that takes + * effect immediately, even for goals created with the flag on. + */ + private boolean allowAutoFollowup = true; + /** Default turn budget when the user doesn't override. */ private int defaultTurnBudget = 20; diff --git a/mateclaw-server/src/main/java/vip/mate/goal/controller/GoalController.java b/mateclaw-server/src/main/java/vip/mate/goal/controller/GoalController.java index 2e84f595..0862616d 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/controller/GoalController.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/controller/GoalController.java @@ -18,6 +18,7 @@ import vip.mate.exception.MateClawException; import vip.mate.goal.model.GoalCreateRequest; import vip.mate.goal.model.GoalEntity; import vip.mate.goal.model.GoalEventEntity; +import vip.mate.goal.model.GoalResponse; import vip.mate.goal.model.GoalUpdateRequest; import vip.mate.goal.service.GoalService; import vip.mate.workspace.conversation.ConversationService; @@ -51,7 +52,7 @@ public class GoalController { @Operation(summary = "Create a persistent goal for a conversation") @PostMapping - public R create(@RequestBody GoalCreateRequest req, Authentication auth) { + public R create(@RequestBody GoalCreateRequest req, Authentication auth) { String username = currentUsername(auth); requireOwner(req.getConversationId(), username); // Derive agentId/workspaceId from the conversation itself so the @@ -71,22 +72,22 @@ public class GoalController { req.setAgentId(conv.getAgentId()); req.setWorkspaceId(conv.getWorkspaceId() != null ? conv.getWorkspaceId() : 1L); GoalEntity g = goalService.create(req, username); - return R.ok(g); + return R.ok(goalService.toResponse(g)); } @Operation(summary = "Get the active goal bound to a conversation (or null)") @GetMapping("/by-conversation/{conversationId}") - public R findActive(@PathVariable String conversationId, Authentication auth) { + public R findActive(@PathVariable String conversationId, Authentication auth) { requireOwner(conversationId, currentUsername(auth)); - return R.ok(goalService.findActiveByConversation(conversationId)); + return R.ok(goalService.toResponse(goalService.findActiveByConversation(conversationId))); } @Operation(summary = "Get goal detail by id") @GetMapping("/{id}") - public R get(@PathVariable Long id, Authentication auth) { + public R get(@PathVariable Long id, Authentication auth) { GoalEntity g = goalService.getById(id); requireOwner(g.getConversationId(), currentUsername(auth)); - return R.ok(g); + return R.ok(goalService.toResponse(g)); } @Operation(summary = "Get the event timeline for a goal") @@ -101,61 +102,61 @@ public class GoalController { @Operation(summary = "List goals (optionally filtered by status)") @GetMapping - public R> list(@RequestParam(required = false) String status, + public R> list(@RequestParam(required = false) String status, @RequestParam(defaultValue = "50") int limit, Authentication auth) { // List is owner-scoped — only your own goals are visible. - return R.ok(goalService.list(status, currentUsername(auth), limit)); + return R.ok(goalService.toResponseList(goalService.list(status, currentUsername(auth), limit))); } @Operation(summary = "Sparse update of a non-terminal goal") @PatchMapping("/{id}") - public R update(@PathVariable Long id, + public R update(@PathVariable Long id, @RequestBody GoalUpdateRequest req, Authentication auth) { GoalEntity g = goalService.getById(id); String username = currentUsername(auth); requireOwner(g.getConversationId(), username); - return R.ok(goalService.update(id, req, username)); + return R.ok(goalService.toResponse(goalService.update(id, req, username))); } @Operation(summary = "Pause an active goal") @PostMapping("/{id}/pause") - public R pause(@PathVariable Long id, Authentication auth) { + public R pause(@PathVariable Long id, Authentication auth) { GoalEntity g = goalService.getById(id); String username = currentUsername(auth); requireOwner(g.getConversationId(), username); - return R.ok(goalService.pause(id, username)); + return R.ok(goalService.toResponse(goalService.pause(id, username))); } @Operation(summary = "Resume a paused goal") @PostMapping("/{id}/resume") - public R resume(@PathVariable Long id, Authentication auth) { + public R resume(@PathVariable Long id, Authentication auth) { GoalEntity g = goalService.getById(id); String username = currentUsername(auth); requireOwner(g.getConversationId(), username); - return R.ok(goalService.resume(id, username)); + return R.ok(goalService.toResponse(goalService.resume(id, username))); } @Operation(summary = "Abandon a goal (terminal)") @PostMapping("/{id}/abandon") - public R abandon(@PathVariable Long id, Authentication auth) { + public R abandon(@PathVariable Long id, Authentication auth) { GoalEntity g = goalService.getById(id); String username = currentUsername(auth); requireOwner(g.getConversationId(), username); - return R.ok(goalService.abandon(id, username)); + return R.ok(goalService.toResponse(goalService.abandon(id, username))); } @Operation(summary = "Append a sub-criterion to an active goal") @PostMapping("/{id}/criteria") - public R addCriterion(@PathVariable Long id, + public R addCriterion(@PathVariable Long id, @RequestBody Map body, Authentication auth) { GoalEntity g = goalService.getById(id); String username = currentUsername(auth); requireOwner(g.getConversationId(), username); String criterion = body != null ? body.get("criterion") : null; - return R.ok(goalService.appendCriterion(id, criterion, username)); + return R.ok(goalService.toResponse(goalService.appendCriterion(id, criterion, username))); } // ==================== Helpers ==================== diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalChecklistVerdict.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalChecklistVerdict.java new file mode 100644 index 00000000..e976b1a2 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalChecklistVerdict.java @@ -0,0 +1,24 @@ +package vip.mate.goal.model; + +import java.util.List; + +/** + * Evaluator output for the verdict round — applied once a goal's + * checklist already exists. + * + *

The evaluator only takes a position on existing criteria by id; it does + * not re-emit the criterion text. The service merges each {@link CriterionVerdict} + * into the persistent {@code List} by id (text and untouched + * criteria are preserved), then derives completion from "all passed". + * + *

This is a per-round delta — never the full outward-facing checklist. + * Outward payloads always carry the full {@code GoalResponse.criteria} array. + */ +public record GoalChecklistVerdict( + List criterionVerdicts, + String summary) { + + /** Per-criterion delta: latest passed state + evidence, keyed by id. */ + public record CriterionVerdict(String id, boolean passed, String evidence) { + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCreateRequest.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCreateRequest.java index 3b2bcae7..fc084d98 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCreateRequest.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCreateRequest.java @@ -2,6 +2,8 @@ package vip.mate.goal.model; import lombok.Data; +import java.util.List; + /** * Request body for {@code POST /api/v1/goals}. * @@ -30,4 +32,12 @@ public class GoalCreateRequest { private Integer llmCallBudget; private Boolean autoFollowupEnabled; private Integer followupCooldownSeconds; + + /** + * Optional initial checklist. Callers supply only {@code text} per item; + * the service normalizes ids ({@code C1..Cn}), forces {@code passed=false} + * and clears {@code evidence} on create. An empty/omitted list defers to + * first-evaluation bootstrap. + */ + private List criteria; } diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaCodec.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaCodec.java new file mode 100644 index 00000000..f059c6f1 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaCodec.java @@ -0,0 +1,112 @@ +package vip.mate.goal.model; + +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * Shared (de)serialization and merge helpers for a goal's checklist stored + * as JSON text in {@code mate_agent_goal.criteria}. + * + *

Centralizes the String JSON ↔ {@code List} boundary so the + * evaluator, service and node never reimplement parsing. Parse failures fail + * soft to an empty list (logged) rather than throwing — a corrupt column must + * never break a chat turn or an API response. + */ +public final class GoalCriteriaCodec { + + private static final Logger log = LoggerFactory.getLogger(GoalCriteriaCodec.class); + private static final TypeReference> LIST_TYPE = new TypeReference<>() { + }; + + private GoalCriteriaCodec() { + } + + /** Parse the JSON column into a mutable list; empty list on null/blank/corrupt. */ + public static List parse(String json, ObjectMapper mapper) { + if (json == null || json.isBlank()) { + return new ArrayList<>(); + } + try { + List parsed = mapper.readValue(json, LIST_TYPE); + return parsed != null ? parsed : new ArrayList<>(); + } catch (Exception e) { + log.warn("[GoalCriteria] failed to parse criteria JSON, treating as empty: {}", e.getMessage()); + return new ArrayList<>(); + } + } + + /** Serialize a checklist to JSON text; {@code null} for a null list. */ + public static String serialize(List criteria, ObjectMapper mapper) { + if (criteria == null) { + return null; + } + try { + return mapper.writeValueAsString(criteria); + } catch (JsonProcessingException e) { + log.warn("[GoalCriteria] failed to serialize criteria, storing null: {}", e.getMessage()); + return null; + } + } + + /** + * Merge a per-round verdict delta into the full checklist by id. Criteria + * absent from the delta are preserved unchanged; the criterion text is + * always kept from the existing item (the verdict never carries text). + */ + public static List merge(List existing, + List verdicts) { + if (existing == null || existing.isEmpty()) { + return existing == null ? new ArrayList<>() : existing; + } + Map byId = new LinkedHashMap<>(); + if (verdicts != null) { + for (GoalChecklistVerdict.CriterionVerdict v : verdicts) { + if (v != null && v.id() != null) { + byId.put(v.id(), v); + } + } + } + List merged = new ArrayList<>(existing.size()); + for (GoalCriterion c : existing) { + GoalChecklistVerdict.CriterionVerdict v = byId.get(c.id()); + merged.add(v == null + ? c + : new GoalCriterion(c.id(), c.text(), v.passed(), + v.evidence() != null ? v.evidence() : "")); + } + return merged; + } + + /** True only when the list is non-empty and every criterion is passed. */ + public static boolean allPassed(List criteria) { + return criteria != null && !criteria.isEmpty() + && criteria.stream().allMatch(GoalCriterion::passed); + } + + /** Criteria not yet passed (used for the continuation prompt + gap text). */ + public static List remaining(List criteria) { + if (criteria == null) { + return List.of(); + } + return criteria.stream().filter(c -> !c.passed()).toList(); + } + + /** Reassign stable ids {@code C1..Cn} in list order. */ + public static List reindex(List criteria) { + List out = new ArrayList<>(criteria.size()); + int n = 1; + for (GoalCriterion c : criteria) { + out.add(new GoalCriterion("C" + n, c.text(), c.passed(), c.evidence() == null ? "" : c.evidence())); + n++; + } + return out; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaDraft.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaDraft.java new file mode 100644 index 00000000..590acbd4 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriteriaDraft.java @@ -0,0 +1,19 @@ +package vip.mate.goal.model; + +import java.util.List; + +/** + * Evaluator output for the bootstrap round — the first evaluation of a + * goal that has no criteria yet. + * + *

When {@code mate_agent_goal.criteria} is empty there is nothing to score + * by id, so the evaluator instead decomposes the goal (title / description / + * exit criteria) into a full checklist with text. The service persists this + * as the goal's initial criteria (all {@code passed=false}); completion is + * not judged on the bootstrap round. + * + *

Distinct from {@link GoalChecklistVerdict}, which is the per-round delta + * used once the checklist already exists. + */ +public record GoalCriteriaDraft(List criteria) { +} diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriterion.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriterion.java new file mode 100644 index 00000000..8f033520 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalCriterion.java @@ -0,0 +1,19 @@ +package vip.mate.goal.model; + +/** + * One checkable item of a goal's exit checklist — the persistent unit. + * + *

Stored as part of the JSON array in {@code mate_agent_goal.criteria} + * and surfaced to clients as an element of {@code GoalResponse.criteria}. + * Completion of a goal is derived from "every criterion passed" rather than + * a fuzzy completion score. + * + * @param id stable identifier ({@code C1}, {@code C2}, ...), assigned + * by the service on create/append; callers never mint ids + * @param text the criterion statement (human + LLM readable) + * @param passed whether the evaluator has judged this criterion satisfied + * @param evidence concrete justification for {@code passed} (an output line, + * a file excerpt, a command result); empty until evaluated + */ +public record GoalCriterion(String id, String text, boolean passed, String evidence) { +} diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEntity.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEntity.java index 96159277..bbff046e 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEntity.java @@ -90,6 +90,17 @@ public class GoalEntity { @TableField(value = "completion_score", updateStrategy = FieldStrategy.ALWAYS) private Double completionScore; + /** + * Checkable exit checklist as a JSON array of {@link GoalCriterion}. + * Completion is derived from "all criteria passed". Nullable: a missing + * list bootstraps on first evaluation. ALWAYS strategy so clearing / + * empty-list writes are persisted. Serialized as text; the service layer + * maps to/from {@code List} and exposes the parsed array + * to clients via {@code GoalResponse.criteria}. + */ + @TableField(value = "criteria", updateStrategy = FieldStrategy.ALWAYS) + private String criteria; + @TableField(value = "last_evaluation_at", updateStrategy = FieldStrategy.ALWAYS) private LocalDateTime lastEvaluationAt; diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEvaluationResult.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEvaluationResult.java index d1d87a4d..415e10b7 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEvaluationResult.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalEvaluationResult.java @@ -1,6 +1,7 @@ package vip.mate.goal.model; import java.util.LinkedHashMap; +import java.util.List; import java.util.Map; /** @@ -8,15 +9,24 @@ import java.util.Map; * {@code GoalEvaluationService} to {@code GoalEvaluationNode} and on to * {@code GoalService.recordEvaluation}. * - *

Defined in PR1 so the service-layer signature is stable; the actual - * evaluator implementation lands in PR2. - * - *

{@link #completed} means "evaluator judged this turn satisfies all - * exit criteria". It does not mean "graph FINISH_REASON should change" — - * goal status and graph FinishReason are independent (RFC 48 §3.1 v2). + *

{@link #completed} means "evaluator judged this turn satisfies every + * exit criterion". It does not mean "graph FINISH_REASON should change" — + * goal status and graph FinishReason are independent. * *

{@link #llmCallsConsumed} is the evaluator-side delta only; the * agent-side delta is read from graph state by the node itself. + * + *

{@link #criterionVerdicts} and {@link #bootstrapCriteria} are mutually + * exclusive carriers for the checklist: + *

    + *
  • verdict round (checklist already exists): {@code criterionVerdicts} + * holds the per-criterion delta (by id), {@code bootstrapCriteria} is null.
    • + *
  • bootstrap round (no criteria yet): {@code bootstrapCriteria} + * holds the freshly decomposed full checklist, {@code criterionVerdicts} + * is empty.
    • + *
+ * Neither is the outward-facing full list — clients always receive the merged + * checklist via {@code GoalResponse.criteria}. */ public record GoalEvaluationResult( double score, @@ -25,19 +35,34 @@ public record GoalEvaluationResult( boolean completed, String evaluatorModel, int llmCallsConsumed, - long latencyMs) { + long latencyMs, + List criterionVerdicts, + List bootstrapCriteria) { public static final String DECISION_COMPLETED = "completed"; public static final String DECISION_CONTINUE = "continue"; public static final String DECISION_FALLBACK = "fallback"; - /** Failure fallback used when the evaluator LLM call errors out. - * Does NOT charge eval_llm_calls_used. */ + /** Failure fallback for the "no call was made" cases (no goal, empty + * answer, no model). Does NOT charge eval_llm_calls_used. */ public static GoalEvaluationResult fallback(String reason) { return new GoalEvaluationResult( 0.0, "evaluator unavailable: " + reason, DECISION_FALLBACK, false, - "", 0, 0L); + "", 0, 0L, + List.of(), null); + } + + /** Failure fallback for cases where the evaluator LLM call already + * succeeded but its output was unusable (empty / unparseable). The call + * was really spent, so it charges {@code llmCallsConsumed = 1} and + * records the model + latency for accurate budget accounting. */ + public static GoalEvaluationResult fallbackAfterCall(String reason, String model, long latencyMs) { + return new GoalEvaluationResult( + 0.0, "evaluator unavailable: " + reason, + DECISION_FALLBACK, false, + model == null ? "" : model, 1, latencyMs, + List.of(), null); } public Map toMap() { @@ -49,6 +74,9 @@ public record GoalEvaluationResult( m.put("evaluatorModel", evaluatorModel == null ? "" : evaluatorModel); m.put("llmCallsConsumed", llmCallsConsumed); m.put("latencyMs", latencyMs); + // Per-round delta, for debugging/detail only. UI progress is driven by + // the full GoalResponse.criteria array, never reconstructed from this. + m.put("criterionVerdicts", criterionVerdicts == null ? List.of() : criterionVerdicts); return m; } } diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalResponse.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalResponse.java new file mode 100644 index 00000000..ea272710 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalResponse.java @@ -0,0 +1,54 @@ +package vip.mate.goal.model; + +import lombok.Data; + +import java.time.LocalDateTime; +import java.util.List; + +/** + * Outward-facing shape of a goal. Identical to {@link GoalEntity} except the + * checklist is the parsed {@code List} array rather than the + * raw JSON String stored in the column — so REST responses and SSE payloads + * always carry {@code criteria} as an array, never a string. + * + *

{@code criteria} is never null on the wire: a missing / unparseable + * column maps to an empty list. + */ +@Data +public class GoalResponse { + + private Long id; + private String conversationId; + private Long agentId; + private Long workspaceId; + private String createdBy; + + private String title; + private String description; + private String exitCriteria; + private String successCheckPrompt; + + private GoalStatus status; + + private Integer turnBudget; + private Integer turnsUsed; + private Integer llmCallBudget; + private Integer agentLlmCallsUsed; + private Integer evalLlmCallsUsed; + private int totalLlmCallsUsed; + + private String progressSummary; + private Double completionScore; + private LocalDateTime lastEvaluationAt; + + private Boolean autoFollowupEnabled; + private Integer followupCooldownSeconds; + private LocalDateTime lastFollowupAt; + + private Integer version; + private LocalDateTime createTime; + private LocalDateTime updateTime; + + /** Parsed checklist; empty (never null) when the column is null/unparseable. */ + private List criteria; +} diff --git a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalStatus.java b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalStatus.java index 5d6b3d27..ec212760 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/model/GoalStatus.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/model/GoalStatus.java @@ -42,7 +42,7 @@ public enum GoalStatus { * the DB stores via {@link EnumValue}. Without this, Jackson defaults to * {@link #name()} (uppercase) and the frontend's * {@code status: 'active' | 'paused' | ...} TS literal types reject - * every payload — UI bug observed during PR4 manual QA. + * every payload. */ @JsonValue public String getValue() { diff --git a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalEvaluationService.java b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalEvaluationService.java index 5d37f3e2..5aca7f1d 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalEvaluationService.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalEvaluationService.java @@ -1,6 +1,5 @@ package vip.mate.goal.service; -import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.chat.messages.Message; @@ -10,9 +9,17 @@ import org.springframework.ai.chat.model.ChatModel; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.chat.prompt.ChatOptions; import org.springframework.ai.chat.prompt.Prompt; +import org.springframework.ai.converter.BeanOutputConverter; +import org.springframework.ai.evaluation.EvaluationRequest; +import org.springframework.ai.evaluation.EvaluationResponse; +import org.springframework.ai.evaluation.Evaluator; import org.springframework.retry.support.RetryTemplate; import org.springframework.stereotype.Service; import vip.mate.goal.config.GoalProperties; +import vip.mate.goal.model.GoalChecklistVerdict; +import vip.mate.goal.model.GoalCriteriaCodec; +import vip.mate.goal.model.GoalCriteriaDraft; +import vip.mate.goal.model.GoalCriterion; import vip.mate.goal.model.GoalEntity; import vip.mate.goal.model.GoalEvaluationResult; import vip.mate.llm.chatmodel.ProviderChatModelFactory; @@ -20,50 +27,52 @@ import vip.mate.llm.model.ModelConfigEntity; import vip.mate.llm.service.ModelConfigService; import java.util.ArrayList; +import java.util.LinkedHashMap; import java.util.List; +import java.util.Map; /** * Evaluates whether the assistant's latest reply satisfies a goal's exit - * criteria. Drives the persistent-goal completion path (the - * "auto-followup until score hits 1.0" loop), so it sits on the hot path - * of every chat turn that has an active goal. + * checklist, and bootstraps that checklist on first run. Sits on the hot + * path of every chat turn that has an active goal. * - *

Returns a deterministic {@link GoalEvaluationResult#fallback fallback} - * when the LLM call is unavailable, errors out, or returns un-parseable - * JSON — the {@code GoalEvaluationNode} treats fallback as "skip - * bookkeeping deltas, no event log, stay safe". This degrades cleanly - * when the evaluator provider is misconfigured or transiently down. + *

Two evaluation modes, chosen by whether the goal already has criteria: + *

    + *
  • Bootstrap (no criteria yet): decompose the goal into a set of + * verifiable criteria and return them as + * {@link GoalEvaluationResult#bootstrapCriteria()}. Completion is not + * judged on this round.
    • + *
  • Verdict (criteria exist): take a position on each existing + * criterion by id (passed + concrete evidence) and return the delta as + * {@link GoalEvaluationResult#criterionVerdicts()}. Completion is + * derived from "all criteria passed" after the merge.
    • + *
* - *

Model selection: - *

    - *
  1. If {@code mateclaw.goal.evaluator-model} names an enabled model, - * use it.
    2. - *
  2. Otherwise fall back to {@link ModelConfigService#getDefaultModel()} - * — convenient for dev, but operators are encouraged to pin a cheap - * evaluator-only model in production since this fires on every turn. - *
    3. - *
+ *

Output is shaped by {@link BeanOutputConverter}, which injects a JSON + * format instruction and parses the reply. On any failure (no model, empty + * reply, unparseable output, provider error) a deterministic + * {@link GoalEvaluationResult#fallback fallback} is returned so the node can + * degrade cleanly. * - *

Prompt is short and JSON-only: the evaluator returns one object with - * {@code score} (0.0–1.0 fraction of criteria satisfied), {@code gap} - * (plain-text description of what's missing), and {@code completed} (bool). + *

Implements Spring AI's {@link Evaluator} for interface uniformity and + * testability; the goal-aware overloads carry the context the generic SPI + * request cannot. */ @Slf4j @Service -public class GoalEvaluationService { +public class GoalEvaluationService implements Evaluator { /** - * Token budget for the evaluator response. Reasoning-mode models - * (DeepSeek V4 Pro, Kimi for Coding, GLM-Z1, …) consume a chunk of - * this budget on internal {@code } content before emitting - * the JSON answer; 400 was empirically too tight and produced - * empty responses on every reasoning provider. 2000 leaves comfort - * for ~1500 tokens of reasoning + the small JSON object we need. + * Token budget for the evaluator response. Reasoning-mode models consume + * a chunk of this on internal thinking before emitting JSON; 2000 leaves + * comfort for the reasoning trace plus the small object we need. */ private static final int MAX_OUTPUT_TOKENS = 2000; private static final int MAX_CONVERSATION_CHARS = 6_000; private static final int MAX_TERMINAL_ANSWER_CHARS = 4_000; - /** Skip-retry template — the goal node has its own try/catch, no need to double-retry. */ + private static final int MIN_BOOTSTRAP_CRITERIA = 1; + private static final int MAX_BOOTSTRAP_CRITERIA = 8; + /** Skip-retry template — the goal node has its own try/catch. */ private static final RetryTemplate ONESHOT = RetryTemplate.builder().maxAttempts(1).build(); private final GoalProperties properties; @@ -71,6 +80,11 @@ public class GoalEvaluationService { private final ProviderChatModelFactory chatModelFactory; private final ObjectMapper objectMapper; + private final BeanOutputConverter draftConverter = + new BeanOutputConverter<>(GoalCriteriaDraft.class); + private final BeanOutputConverter verdictConverter = + new BeanOutputConverter<>(GoalChecklistVerdict.class); + public GoalEvaluationService(GoalProperties properties, ModelConfigService modelConfigService, ProviderChatModelFactory chatModelFactory, @@ -82,19 +96,12 @@ public class GoalEvaluationService { } /** - * Evaluate one terminal answer against the goal's exit criteria. + * Evaluate one terminal answer against the goal's checklist (or bootstrap + * the checklist when none exists yet). * - *

Returns a {@link GoalEvaluationResult} carrying the score, gap - * description, decision, model id, and elapsed latency. The - * {@code llmCallsConsumed} field is 1 on success (one evaluator - * call) and 0 on fallback paths so the per-goal LLM-call budget - * stays accurate. - * - * @param goal the active goal under evaluation; never {@code null} - * @param recentMessages most-recent N messages from the parent conversation - * for context; the node already trims by - * {@link GoalProperties#getEvaluatorContextMessages()} - * @param terminalAnswer the assistant's just-emitted final answer text + * @param goal the active goal under evaluation; never {@code null} + * @param recentMessages most-recent N messages for context (already trimmed) + * @param terminalAnswer the assistant's just-emitted final answer text */ public GoalEvaluationResult evaluate(GoalEntity goal, List recentMessages, @@ -108,19 +115,24 @@ public class GoalEvaluationService { ModelConfigEntity model = resolveEvaluatorModel(); if (model == null) { - log.warn("[GoalEvaluation] no evaluator model available (configured={}, default lookup empty)", + log.warn("[GoalEvaluation] no evaluator model available (configured={})", properties.getEvaluatorModel()); return GoalEvaluationResult.fallback("no_model"); } + List existing = GoalCriteriaCodec.parse(goal.getCriteria(), objectMapper); + boolean bootstrap = existing.isEmpty(); + long start = System.currentTimeMillis(); try { ChatModel chatModel = chatModelFactory.buildFor(model, ONESHOT); - String prompt = buildUserPrompt(goal, recentMessages, terminalAnswer); + String format = bootstrap ? draftConverter.getFormat() : verdictConverter.getFormat(); + String userPrompt = buildUserPrompt(goal, existing, recentMessages, terminalAnswer, bootstrap) + + "\n\n" + format; List messages = new ArrayList<>(2); - messages.add(new SystemMessage(SYSTEM_PROMPT)); - messages.add(new UserMessage(prompt)); + messages.add(new SystemMessage(bootstrap ? BOOTSTRAP_SYSTEM_PROMPT : VERDICT_SYSTEM_PROMPT)); + messages.add(new UserMessage(userPrompt)); ChatOptions options = ChatOptions.builder() .temperature(0.1) @@ -133,10 +145,13 @@ public class GoalEvaluationService { String body = extractText(response); if (body == null || body.isBlank()) { log.warn("[GoalEvaluation] empty response from evaluator model={}", model.getModelName()); - return GoalEvaluationResult.fallback("empty_response"); + // The call was really spent — bill it. + return GoalEvaluationResult.fallbackAfterCall("empty_response", model.getModelName(), elapsed); } - return parseJson(body, model.getModelName(), elapsed); + return bootstrap + ? parseBootstrap(body, model.getModelName(), elapsed) + : parseVerdict(body, existing, model.getModelName(), elapsed); } catch (Throwable t) { long elapsed = System.currentTimeMillis() - start; log.warn("[GoalEvaluation] evaluator call failed after {}ms: {}", elapsed, t.toString()); @@ -144,38 +159,89 @@ public class GoalEvaluationService { } } + // ==================== Evaluator SPI ==================== + + /** + * Generic SPI surface: judge whether {@code request.getResponseContent()} + * satisfies the objective stated in {@code request.getUserText()}. + * + *

The objective is wrapped as a single checklist criterion so the call + * runs in verdict mode (a real pass/fail judgement of the response), + * not bootstrap mode. {@code isPass()} is true only when that criterion is + * satisfied; detail rides in {@code metadata.criterionVerdicts}. + * + *

Goal-aware callers use the {@link #evaluate(GoalEntity, List, String)} + * overload, which carries the full multi-criterion checklist context the + * generic request cannot. + */ + @Override + public EvaluationResponse evaluate(EvaluationRequest request) { + String objective = request.getUserText() != null ? request.getUserText() : ""; + GoalEntity probe = new GoalEntity(); + probe.setTitle("Does the response satisfy the objective?"); + probe.setDescription(objective); + // One criterion = the objective -> non-empty criteria -> verdict mode. + probe.setCriteria(GoalCriteriaCodec.serialize( + List.of(new GoalCriterion("C1", objective, false, "")), objectMapper)); + + GoalEvaluationResult r = evaluate(probe, List.of(), request.getResponseContent()); + Map metadata = new LinkedHashMap<>(); + metadata.put("decision", r.decision()); + metadata.put("criterionVerdicts", r.criterionVerdicts()); + return new EvaluationResponse(r.completed(), (float) r.score(), + r.gap() == null ? "" : r.gap(), metadata); + } + // ==================== Internals ==================== private ModelConfigEntity resolveEvaluatorModel() { String name = properties.getEvaluatorModel(); if (name != null && !name.isBlank()) { - // resolveModel returns the default model when the named one - // can't be found, which is exactly the desired "graceful - // degradation" semantics for a misconfigured evaluator id. + // resolveModel returns the default model when the named one can't + // be found — the desired graceful-degradation semantics. return modelConfigService.resolveModel(name); } return modelConfigService.getDefaultModel(); } - private static final String SYSTEM_PROMPT = - "You are a goal-completion evaluator. You judge whether an AI " - + "assistant's latest reply satisfies a user's stated goal. " - + "Output exactly ONE JSON object with the keys score, gap, " - + "completed. No markdown, no commentary, no extra prose."; + private static final String BOOTSTRAP_SYSTEM_PROMPT = + "You decompose a user's goal into a short checklist of concrete, " + + "independently verifiable acceptance criteria. Each criterion " + + "must be checkable from observable evidence (an output, a file, " + + "a command result), not a vague aspiration. Output only the " + + "requested JSON."; + + private static final String VERDICT_SYSTEM_PROMPT = + "You judge, criterion by criterion, whether an AI assistant's latest " + + "reply satisfies a goal's checklist. For each criterion you MUST " + + "cite concrete evidence from the reply (an output line, a file " + + "excerpt, a command result). Do NOT accept generic phrases like " + + "'all requirements met'. If a criterion lacks specific evidence, " + + "mark it not passed. Output only the requested JSON."; private String buildUserPrompt(GoalEntity goal, + List existing, List recentMessages, - String terminalAnswer) { + String terminalAnswer, + boolean bootstrap) { StringBuilder sb = new StringBuilder(2048); sb.append("Goal title: ").append(safe(goal.getTitle())).append('\n'); if (goal.getDescription() != null && !goal.getDescription().isBlank()) { sb.append("Goal description: ").append(safe(goal.getDescription())).append('\n'); } if (goal.getExitCriteria() != null && !goal.getExitCriteria().isBlank()) { - sb.append("Exit criteria:\n").append(safe(goal.getExitCriteria())).append('\n'); + sb.append("Exit criteria (free text):\n").append(safe(goal.getExitCriteria())).append('\n'); } sb.append('\n'); + if (!bootstrap) { + sb.append("Current checklist (judge each by id):\n"); + for (GoalCriterion c : existing) { + sb.append("- ").append(c.id()).append(": ").append(c.text()).append('\n'); + } + sb.append('\n'); + } + if (recentMessages != null && !recentMessages.isEmpty()) { sb.append("Recent conversation (oldest first):\n"); String convo = serializeMessages(recentMessages); @@ -191,22 +257,117 @@ public class GoalEvaluationService { } sb.append("\nAssistant's latest final answer to evaluate:\n").append(answer).append('\n'); - sb.append('\n') - .append("Return exactly:\n") - .append("{\n") - .append(" \"score\": ,\n") - .append(" \"gap\": \"\",\n") - .append(" \"completed\": \n") - .append("}"); + sb.append('\n'); + if (bootstrap) { + sb.append("Produce between ").append(MIN_BOOTSTRAP_CRITERIA).append(" and ") + .append(MAX_BOOTSTRAP_CRITERIA) + .append(" criteria. Leave every 'passed' false and 'evidence' empty — " + + "this round only defines the checklist."); + } else { + sb.append("For every criterion above, return its id with passed=true ONLY when " + + "the reply shows concrete evidence; otherwise passed=false with a short " + + "note of what is missing."); + } return sb.toString(); } + private GoalEvaluationResult parseBootstrap(String body, String modelName, long latencyMs) { + try { + GoalCriteriaDraft dto = draftConverter.convert(stripFences(body)); + if (dto == null || dto.criteria() == null || dto.criteria().isEmpty()) { + return GoalEvaluationResult.fallbackAfterCall("bootstrap_empty", modelName, latencyMs); + } + List normalized = new ArrayList<>(); + for (GoalCriterion c : dto.criteria()) { + if (c != null && c.text() != null && !c.text().isBlank()) { + normalized.add(new GoalCriterion("", c.text().trim(), false, "")); + } + // Hard cap regardless of what the model returned — the prompt + // asks for <= MAX but a verbose model could exceed it. + if (normalized.size() >= MAX_BOOTSTRAP_CRITERIA) { + break; + } + } + if (normalized.isEmpty()) { + return GoalEvaluationResult.fallbackAfterCall("bootstrap_empty", modelName, latencyMs); + } + normalized = GoalCriteriaCodec.reindex(normalized); + // Bootstrap never judges completion: the checklist is freshly created. + return new GoalEvaluationResult( + 0.0, "checklist created", GoalEvaluationResult.DECISION_CONTINUE, false, + modelName != null ? modelName : "", 1, latencyMs, + List.of(), normalized); + } catch (Exception e) { + log.warn("[GoalEvaluation] bootstrap parse failed: {}", e.getMessage()); + return GoalEvaluationResult.fallbackAfterCall("parse_failed", modelName, latencyMs); + } + } + + private GoalEvaluationResult parseVerdict(String body, + List existing, + String modelName, + long latencyMs) { + try { + GoalChecklistVerdict verdict = verdictConverter.convert(stripFences(body)); + List deltas = + verdict != null && verdict.criterionVerdicts() != null + ? verdict.criterionVerdicts() : List.of(); + List merged = GoalCriteriaCodec.merge(existing, deltas); + boolean completed = GoalCriteriaCodec.allPassed(merged); + int total = merged.size(); + int passed = (int) merged.stream().filter(GoalCriterion::passed).count(); + double score = total == 0 ? 0.0 : (double) passed / total; + String gap = completed ? "" : buildGap(GoalCriteriaCodec.remaining(merged)); + String decision = completed + ? GoalEvaluationResult.DECISION_COMPLETED + : GoalEvaluationResult.DECISION_CONTINUE; + return new GoalEvaluationResult( + score, gap, decision, completed, + modelName != null ? modelName : "", 1, latencyMs, + deltas, null); + } catch (Exception e) { + log.warn("[GoalEvaluation] verdict parse failed: {}", e.getMessage()); + return GoalEvaluationResult.fallbackAfterCall("parse_failed", modelName, latencyMs); + } + } + + private static String buildGap(List remaining) { + if (remaining.isEmpty()) { + return ""; + } + StringBuilder sb = new StringBuilder("Still missing: "); + for (int i = 0; i < remaining.size(); i++) { + if (i > 0) { + sb.append("; "); + } + sb.append(remaining.get(i).text()); + } + return sb.toString(); + } + + /** Strip ```json fences the model may add despite instructions. */ + private static String stripFences(String body) { + String t = body.strip(); + if (t.startsWith("```")) { + int nl = t.indexOf('\n'); + if (nl > 0) { + t = t.substring(nl + 1); + } + if (t.endsWith("```")) { + t = t.substring(0, t.length() - 3); + } + } + return t.strip(); + } + private String serializeMessages(List messages) { StringBuilder sb = new StringBuilder(); for (Message m : messages) { String role = m.getMessageType() != null ? m.getMessageType().getValue() : "msg"; String text = m.getText(); - if (text == null) text = ""; + if (text == null) { + text = ""; + } sb.append(role).append(": ").append(text.strip()).append('\n'); } return sb.toString(); @@ -222,11 +383,8 @@ public class GoalEvaluationService { if (text != null && !text.isBlank()) { return text; } - // Fallback for reasoning models: some providers (DeepSeek-style - // OpenAI-compatible streaming, MiMo) emit the entire output as - // `reasoning_content` and leave the regular content field empty - // when the token budget gets eaten by thinking. The JSON object - // we want often appears at the tail of the reasoning trace. + // Fallback for reasoning models that emit everything as reasoningContent + // and leave the regular content empty; the JSON often tails the trace. var metadata = output.getMetadata(); if (metadata != null) { Object rc = metadata.get("reasoningContent"); @@ -237,56 +395,6 @@ public class GoalEvaluationService { return text; } - /** - * Parse the evaluator's JSON output. The model may wrap the object in - * ```json fences despite the system prompt telling it not to, so we - * locate the first {@code {...}} substring and parse that. Anything - * else (non-numeric score, missing fields, malformed JSON) downgrades - * to a fallback result rather than throwing. - */ - private GoalEvaluationResult parseJson(String body, String modelName, long latencyMs) { - String trimmed = body.strip(); - int braceStart = trimmed.indexOf('{'); - int braceEnd = trimmed.lastIndexOf('}'); - if (braceStart < 0 || braceEnd <= braceStart) { - log.warn("[GoalEvaluation] no JSON object in evaluator output: {}", - trimmed.length() > 200 ? trimmed.substring(0, 200) + "..." : trimmed); - return GoalEvaluationResult.fallback("parse_no_object"); - } - String json = trimmed.substring(braceStart, braceEnd + 1); - try { - JsonNode node = objectMapper.readTree(json); - JsonNode scoreNode = node.get("score"); - if (scoreNode == null || !scoreNode.isNumber()) { - return GoalEvaluationResult.fallback("parse_missing_score"); - } - double score = clamp01(scoreNode.asDouble()); - String gap = node.hasNonNull("gap") ? node.get("gap").asText("") : ""; - boolean completed = node.hasNonNull("completed") && node.get("completed").asBoolean(false); - // Belt-and-braces: a perfect score implies completion; let the - // node's >= 0.95 threshold handle the gray zone. - if (score >= 1.0 - 1e-9) completed = true; - String decision = completed - ? GoalEvaluationResult.DECISION_COMPLETED - : GoalEvaluationResult.DECISION_CONTINUE; - return new GoalEvaluationResult( - score, gap, decision, completed, - modelName != null ? modelName : "", 1, latencyMs); - } catch (Exception e) { - log.warn("[GoalEvaluation] JSON parse failed: {} — body={}", - e.getMessage(), - json.length() > 200 ? json.substring(0, 200) + "..." : json); - return GoalEvaluationResult.fallback("parse_failed"); - } - } - - private static double clamp01(double v) { - if (Double.isNaN(v)) return 0.0; - if (v < 0.0) return 0.0; - if (v > 1.0) return 1.0; - return v; - } - private static String safe(String s) { return s == null ? "" : s; } diff --git a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalFollowupService.java b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalFollowupService.java index 245fa879..2bf5066f 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalFollowupService.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalFollowupService.java @@ -1,43 +1,61 @@ package vip.mate.goal.service; +import com.fasterxml.jackson.databind.ObjectMapper; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; +import vip.mate.goal.config.GoalProperties; +import vip.mate.goal.model.GoalCriteriaCodec; +import vip.mate.goal.model.GoalCriterion; import vip.mate.goal.model.GoalEntity; import vip.mate.goal.model.GoalEvaluationResult; import java.time.Duration; import java.time.LocalDateTime; +import java.util.List; import java.util.Optional; /** - * Decides whether to inject a follow-up user prompt for the next graph - * pass. PR2 wires the plumbing; the actual "yes, continue" path defaults - * to off until PR5 flips {@code mateclaw.goal.enabled=true} and operators - * opt their goals in via {@code auto_followup_enabled}. + * Decides whether to inject a follow-up user prompt for the next graph pass, + * driving the autonomous "continue until the checklist is complete" loop. */ @Slf4j @Service public class GoalFollowupService { + private final GoalProperties properties; + private final ObjectMapper objectMapper; + + public GoalFollowupService(GoalProperties properties, ObjectMapper objectMapper) { + this.properties = properties; + this.objectMapper = objectMapper; + } + /** - * Build the follow-up prompt to inject, or empty when no follow-up - * should fire this turn. Conditions follow RFC 48 §3.10: + * Build the follow-up prompt to inject, or empty when no follow-up should + * fire this turn. Gating order: *

    - *
  1. {@code autoFollowupEnabled} is true.
    2. - *
  2. Evaluator decision is "continue" with score < 0.95.
    3. + *
  3. {@code allow-auto-followup} runtime hard gate (operator kill + * switch; overrides per-goal flag).
    4. + *
  4. Per-goal {@code autoFollowupEnabled}.
    5. + *
  5. Evaluator decision is "continue" (not all criteria passed).
    6. *
  6. Cooldown since the last follow-up has elapsed.
    7. *
  7. turn_budget has at least one slot left after this turn.
    8. - *
  8. (agent + eval) LLM calls below 90 % of llm_call_budget.
    9. + *
  9. (agent + eval) LLM calls below 90% of llm_call_budget.
    10. *
*/ public Optional maybeBuildFollowup(GoalEntity goal, - GoalEvaluationResult result) { + GoalEvaluationResult result) { if (goal == null || result == null) return Optional.empty(); + // Runtime hard gate first — overrides any per-goal flag. + if (!properties.isAllowAutoFollowup()) return Optional.empty(); if (!Boolean.TRUE.equals(goal.getAutoFollowupEnabled())) return Optional.empty(); + // Completion is deterministic now: the evaluator sets decision=completed + // only when every checklist criterion passed. Anything still "continue" + // has remaining work regardless of the numeric score, so there is no + // score threshold here — a 20/21 goal (score 0.95) must still follow up. if (!GoalEvaluationResult.DECISION_CONTINUE.equals(result.decision())) { return Optional.empty(); } - if (result.score() >= 0.95) return Optional.empty(); // Cooldown — last_followup_at recorded by recordFollowupInjected(). Integer cooldownSec = goal.getFollowupCooldownSeconds(); @@ -51,17 +69,39 @@ public class GoalFollowupService { int turnsUsed = goal.getTurnsUsed() != null ? goal.getTurnsUsed() : 0; int turnBudget = goal.getTurnBudget() != null ? goal.getTurnBudget() : Integer.MAX_VALUE; - // Leave at least one turn slot for the real user — refuse to burn - // the final slot on an auto-followup that the user can't watch. + // Leave at least one turn slot for the real user — refuse to burn the + // final slot on an auto-followup the user can't watch. if (turnsUsed >= turnBudget - 1) return Optional.empty(); int callBudget = goal.getLlmCallBudget() != null ? goal.getLlmCallBudget() : Integer.MAX_VALUE; if (goal.totalLlmCallsUsed() >= (int) (callBudget * 0.9)) return Optional.empty(); + return Optional.of(buildPrompt(goal, result)); + } + + /** + * Prefer a concrete remaining-criteria list when the goal has a checklist; + * fall back to the free-text gap otherwise. Both end with the same "take + * the next concrete step" instruction. + */ + private String buildPrompt(GoalEntity goal, GoalEvaluationResult result) { + List all = GoalCriteriaCodec.parse(goal.getCriteria(), objectMapper); + List remaining = GoalCriteriaCodec.remaining(all); + if (!remaining.isEmpty()) { + int total = all.size(); + int passed = total - remaining.size(); + StringBuilder sb = new StringBuilder(); + sb.append("Continue working toward the goal. ") + .append(passed).append('/').append(total).append(" criteria passed. Remaining:\n"); + for (GoalCriterion c : remaining) { + sb.append(" - ").append(c.text()).append('\n'); + } + sb.append("Take the next concrete step on the remaining criteria."); + return sb.toString(); + } String gap = result.gap(); if (gap == null || gap.isBlank()) gap = "the goal is not yet complete."; - String prompt = "Continue working on the goal. Still missing: " + gap + return "Continue working on the goal. Still missing: " + gap + "\nTake the next concrete step."; - return Optional.of(prompt); } } diff --git a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalService.java b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalService.java index e8537e7e..a90d6ea6 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalService.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalService.java @@ -4,13 +4,14 @@ import vip.mate.goal.model.GoalCreateRequest; import vip.mate.goal.model.GoalEntity; import vip.mate.goal.model.GoalEvaluationResult; import vip.mate.goal.model.GoalEventEntity; +import vip.mate.goal.model.GoalResponse; import vip.mate.goal.model.GoalUpdateRequest; import java.util.List; /** * Persistent goal service — CRUD, status transitions, and bookkeeping - * called from {@code GoalEvaluationNode} (PR2). + * called from {@code GoalEvaluationNode}. * *

Concurrency model: writes use a per-row {@code WHERE version=?} * compare-and-set. On conflict the service retries up to 3 times before @@ -78,4 +79,17 @@ public interface GoalService { /** Append a sub-criterion without restarting the goal. */ GoalEntity appendCriterion(Long id, String criterion, String username); + + // ==================== Response mapping ==================== + + /** + * Map an entity to its outward-facing form: {@code criteria} becomes a + * parsed {@code List} array (empty when null/unparseable), + * never the raw JSON String. Use at every REST return point and SSE + * payload so clients never see the string form. + */ + GoalResponse toResponse(GoalEntity entity); + + /** Convenience: {@link #toResponse} over a list. */ + List toResponseList(List entities); } diff --git a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalServiceImpl.java b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalServiceImpl.java index 0a264479..3d989d11 100644 --- a/mateclaw-server/src/main/java/vip/mate/goal/service/GoalServiceImpl.java +++ b/mateclaw-server/src/main/java/vip/mate/goal/service/GoalServiceImpl.java @@ -14,7 +14,10 @@ import vip.mate.audit.service.AuditEventService; import vip.mate.exception.MateClawException; import vip.mate.goal.config.GoalProperties; import vip.mate.goal.model.GoalCreateRequest; +import vip.mate.goal.model.GoalCriteriaCodec; +import vip.mate.goal.model.GoalCriterion; import vip.mate.goal.model.GoalEntity; +import vip.mate.goal.model.GoalResponse; import vip.mate.goal.model.GoalEvaluationResult; import vip.mate.goal.model.GoalEventEntity; import vip.mate.goal.model.GoalEventType; @@ -112,9 +115,17 @@ public class GoalServiceImpl implements GoalService { ? req.getLlmCallBudget() : properties.getDefaultLlmCallBudget()); entity.setAgentLlmCallsUsed(0); entity.setEvalLlmCallsUsed(0); - entity.setAutoFollowupEnabled(Boolean.TRUE.equals(req.getAutoFollowupEnabled())); + // Three-state default: explicit true/false is honored; null falls + // back to the configured create-time default. + entity.setAutoFollowupEnabled(req.getAutoFollowupEnabled() != null + ? req.getAutoFollowupEnabled() + : properties.isDefaultAutoFollowup()); entity.setFollowupCooldownSeconds(req.getFollowupCooldownSeconds() != null ? req.getFollowupCooldownSeconds() : properties.getAutoFollowupCooldownSeconds()); + // Normalize any caller-supplied checklist: assign C1..Cn, force + // passed=false, clear evidence. Empty/omitted -> null column so the + // first evaluation bootstraps the list. + entity.setCriteria(serializeCriteria(normalizeInitialCriteria(req.getCriteria()))); entity.setVersion(0); entity.setDeleted(0); LocalDateTime now = LocalDateTime.now(); @@ -278,6 +289,18 @@ public class GoalServiceImpl implements GoalService { w.set(GoalEntity::getCompletionScore, result.score()) .set(GoalEntity::getProgressSummary, result.gap()); } + // Snapshot the checklist as fully satisfied. Idempotent for the + // auto path (recordEvaluation already merged all-passed); required + // for manual completion, which has no preceding verdict. + List existing = GoalCriteriaCodec.parse(fresh.getCriteria(), objectMapper); + if (!existing.isEmpty()) { + List allPassed = existing.stream() + .map(c -> c.passed() ? c : new GoalCriterion(c.id(), c.text(), true, + c.evidence() == null || c.evidence().isBlank() + ? "marked complete" : c.evidence())) + .toList(); + w.set(GoalEntity::getCriteria, GoalCriteriaCodec.serialize(allPassed, objectMapper)); + } bumpVersionAndTime(w); return w; }); @@ -285,6 +308,7 @@ public class GoalServiceImpl implements GoalService { detail.put("finalScore", result != null ? result.score() : null); detail.put("agentLlmCallsUsed", g.getAgentLlmCallsUsed()); detail.put("evalLlmCallsUsed", g.getEvalLlmCallsUsed()); + detail.put("criteria", GoalCriteriaCodec.parse(g.getCriteria(), objectMapper)); writeEvent(id, GoalEventType.COMPLETED, null, detail); recordAudit("goal.completed", g, detail); @@ -344,7 +368,7 @@ public class GoalServiceImpl implements GoalService { int agentDelta = Math.max(0, agentLlmCallsDelta); int evalDelta = Math.max(0, evalLlmCallsDelta); - retryOptimistic(id, "recordEvaluation", fresh -> { + GoalEntity g = retryOptimistic(id, "recordEvaluation", fresh -> { if (fresh.getStatus().isTerminal()) return null; // ignore late evaluations LambdaUpdateWrapper w = baseLockedUpdate(fresh) .setSql("turns_used = turns_used + 1") @@ -354,6 +378,13 @@ public class GoalServiceImpl implements GoalService { if (result != null) { w.set(GoalEntity::getCompletionScore, result.score()) .set(GoalEntity::getProgressSummary, result.gap()); + // Persist the checklist by carrier: bootstrap writes the fresh + // draft; verdict merges the per-criterion delta into the + // current list (re-read on the locked `fresh` to avoid races). + String criteriaJson = nextCriteriaJson(fresh, result); + if (criteriaJson != null) { + w.set(GoalEntity::getCriteria, criteriaJson); + } } bumpVersionAndTime(w); return w; @@ -369,9 +400,33 @@ public class GoalServiceImpl implements GoalService { } detail.put("agentLlmCallsDelta", agentDelta); detail.put("evalLlmCallsDelta", evalDelta); + // Full checklist (array) so the timeline / SSE consumer never sees the + // raw String column or has to reconstruct from the per-round delta. + detail.put("criteria", GoalCriteriaCodec.parse(g.getCriteria(), objectMapper)); writeEvent(id, GoalEventType.EVALUATED, null, detail); } + /** + * Compute the next criteria JSON for a record-evaluation write, or + * {@code null} when the result carries no checklist change. Bootstrap + * results replace the list with the freshly derived draft; verdict + * results merge their per-criterion delta into the locked-row list. + */ + private String nextCriteriaJson(GoalEntity fresh, GoalEvaluationResult result) { + if (result.bootstrapCriteria() != null && !result.bootstrapCriteria().isEmpty()) { + return GoalCriteriaCodec.serialize(result.bootstrapCriteria(), objectMapper); + } + if (result.criterionVerdicts() != null && !result.criterionVerdicts().isEmpty()) { + List existing = GoalCriteriaCodec.parse(fresh.getCriteria(), objectMapper); + if (existing.isEmpty()) { + return null; + } + return GoalCriteriaCodec.serialize( + GoalCriteriaCodec.merge(existing, result.criterionVerdicts()), objectMapper); + } + return null; + } + @Override public boolean isBudgetExhausted(GoalEntity goal) { int turns = goal.getTurnsUsed() != null ? goal.getTurnsUsed() : 0; @@ -416,25 +471,107 @@ public class GoalServiceImpl implements GoalService { throw new MateClawException("err.goal.criterion_empty", 400, "Criterion must not be empty"); } String trimmed = criterion.trim(); - // Merge against the freshly refetched criteria so a concurrent - // addCriterion never silently overwrites a sibling's append. + // Double-write: append a structured criterion (authoritative) and + // mirror the text into exit_criteria for backward compatibility / + // human readability. New id is the current max ordinal + 1. Merge + // against the freshly refetched row so concurrent appends don't clobber. GoalEntity g = retryOptimistic(id, "appendCriterion", fresh -> { ensureNotTerminal(fresh, "appendCriterion"); + + List list = GoalCriteriaCodec.parse(fresh.getCriteria(), objectMapper); + list.add(new GoalCriterion("C" + (list.size() + 1), trimmed, false, "")); + String criteriaJson = GoalCriteriaCodec.serialize(GoalCriteriaCodec.reindex(list), objectMapper); + String existing = fresh.getExitCriteria() != null ? fresh.getExitCriteria() : ""; - String merged = existing.isEmpty() ? trimmed : existing + "\n+ " + trimmed; + String mergedText = existing.isEmpty() ? trimmed : existing + "\n+ " + trimmed; + LambdaUpdateWrapper w = baseLockedUpdate(fresh) - .set(GoalEntity::getExitCriteria, merged); + .set(GoalEntity::getCriteria, criteriaJson) + .set(GoalEntity::getExitCriteria, mergedText); bumpVersionAndTime(w); return w; }); + List full = GoalCriteriaCodec.parse(g.getCriteria(), objectMapper); + String criterionId = full.isEmpty() ? "" : full.get(full.size() - 1).id(); writeEvent(id, GoalEventType.CRITERION_ADDED, null, Map.of( "criterion", trimmed, + "criterionId", criterionId, + "criteria", full, "by", username)); return g; } // ==================== Internals ==================== + /** + * Normalize a caller-supplied initial checklist: keep only non-blank + * {@code text}, assign stable ids {@code C1..Cn} (ignore any caller ids), + * force {@code passed=false} and clear evidence. Returns {@code null} for + * an empty/null result so the column stays NULL and the first evaluation + * bootstraps the list. + */ + private List normalizeInitialCriteria(List raw) { + if (raw == null || raw.isEmpty()) { + return null; + } + List kept = new java.util.ArrayList<>(raw.size()); + for (GoalCriterion c : raw) { + if (c != null && c.text() != null && !c.text().isBlank()) { + kept.add(new GoalCriterion("", c.text().trim(), false, "")); + } + } + return kept.isEmpty() ? null : GoalCriteriaCodec.reindex(kept); + } + + /** Serialize a checklist to JSON text, or {@code null} for a null list. */ + private String serializeCriteria(List criteria) { + return GoalCriteriaCodec.serialize(criteria, objectMapper); + } + + @Override + public GoalResponse toResponse(GoalEntity e) { + if (e == null) { + return null; + } + GoalResponse r = new GoalResponse(); + r.setId(e.getId()); + r.setConversationId(e.getConversationId()); + r.setAgentId(e.getAgentId()); + r.setWorkspaceId(e.getWorkspaceId()); + r.setCreatedBy(e.getCreatedBy()); + r.setTitle(e.getTitle()); + r.setDescription(e.getDescription()); + r.setExitCriteria(e.getExitCriteria()); + r.setSuccessCheckPrompt(e.getSuccessCheckPrompt()); + r.setStatus(e.getStatus()); + r.setTurnBudget(e.getTurnBudget()); + r.setTurnsUsed(e.getTurnsUsed()); + r.setLlmCallBudget(e.getLlmCallBudget()); + r.setAgentLlmCallsUsed(e.getAgentLlmCallsUsed()); + r.setEvalLlmCallsUsed(e.getEvalLlmCallsUsed()); + r.setTotalLlmCallsUsed(e.totalLlmCallsUsed()); + r.setProgressSummary(e.getProgressSummary()); + r.setCompletionScore(e.getCompletionScore()); + r.setLastEvaluationAt(e.getLastEvaluationAt()); + r.setAutoFollowupEnabled(e.getAutoFollowupEnabled()); + r.setFollowupCooldownSeconds(e.getFollowupCooldownSeconds()); + r.setLastFollowupAt(e.getLastFollowupAt()); + r.setVersion(e.getVersion()); + r.setCreateTime(e.getCreateTime()); + r.setUpdateTime(e.getUpdateTime()); + // Always an array; empty when the column is null/unparseable. + r.setCriteria(GoalCriteriaCodec.parse(e.getCriteria(), objectMapper)); + return r; + } + + @Override + public List toResponseList(List entities) { + if (entities == null) { + return List.of(); + } + return entities.stream().map(this::toResponse).toList(); + } + private void validateCreate(GoalCreateRequest req) { if (req == null) { throw new MateClawException("err.goal.bad_request", 400, "Request body required"); diff --git a/mateclaw-server/src/main/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilder.java b/mateclaw-server/src/main/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilder.java index 9df1b5a9..fc436b84 100644 --- a/mateclaw-server/src/main/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilder.java +++ b/mateclaw-server/src/main/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilder.java @@ -121,13 +121,36 @@ public class AnthropicChatModelBuilder implements ChatModelBuilder { return lower.contains("4-7") || lower.contains("4.7"); } + /** + * Detect Claude 4.8 model variants (including the {@code -fast} sibling). + * Claude 4.8 inherits 4.7's strict API contract: temperature / top_p / + * top_k must be unset, and the "xhigh" thinking tier is available. + */ + static boolean isClaude48(String modelName) { + if (modelName == null) return false; + String lower = modelName.toLowerCase(); + if (!lower.contains("claude")) return false; + // Matches claude-opus-4-8, claude-opus-4.8, the "-fast" sibling + // (claude-opus-4-8-fast / claude-opus-4.8-fast), and OpenRouter + // prefixed forms (anthropic/claude-opus-4-8...). + return lower.contains("4-8") || lower.contains("4.8"); + } + + /** + * True for any Claude 4.7+ model — the family that drops temperature / + * top_p / top_k and exposes the "xhigh" thinking tier between high and max. + */ + static boolean isClaude47OrLater(String modelName) { + return isClaude47(modelName) || isClaude48(modelName); + } + AnthropicChatOptions buildAnthropicOptions(ModelConfigEntity runtimeModel) { AnthropicChatOptions.Builder builder = AnthropicChatOptions.builder(); String modelName = runtimeModel.getModelName(); if (StringUtils.hasText(modelName)) { builder.model(modelName); } - boolean isClaude47 = isClaude47(modelName); + boolean strictSamplingContract = isClaude47OrLater(modelName); // Extended thinking — request-level depth from ThinkingLevelHolder String thinkingLevel = ThinkingLevelHolder.get(); @@ -136,22 +159,22 @@ public class AnthropicChatModelBuilder implements ChatModelBuilder { if (thinkingEnabled) { // Anthropic thinking-mode constraints (pre-4.7): temperature MUST be 1, // top_p forbidden, max_tokens must accommodate budget_tokens + buffer. - // Claude 4.7 forbids temperature/top_p/top_k entirely (any non-null value + // Claude 4.7+ forbids temperature/top_p/top_k entirely (any non-null value // → HTTP 400) and adds an "xhigh" budget tier between high and max. int budgetTokens = switch (thinkingLevel.toLowerCase()) { case "low" -> 4096; case "medium" -> 8192; case "high" -> 16384; - case "xhigh" -> 24576; // 4.7 only — between high (16k) and max (32k) + case "xhigh" -> 24576; // 4.7+ only — between high (16k) and max (32k) case "max" -> 32768; default -> 16384; }; builder.thinking(AnthropicApi.ThinkingType.ENABLED, budgetTokens); builder.maxTokens(Math.max(budgetTokens + 4096, runtimeModel.getMaxTokens() != null ? runtimeModel.getMaxTokens() : 8192)); - // Claude 4.7: omit temperature entirely. Pre-4.7 thinking mode requires + // Claude 4.7+: omit temperature entirely. Pre-4.7 thinking mode requires // temperature=1 (Anthropic-mandated default for thinking). - if (!isClaude47) { + if (!strictSamplingContract) { builder.temperature(1.0); } } else { @@ -159,14 +182,14 @@ public class AnthropicChatModelBuilder implements ChatModelBuilder { // - Pre-4.7: Anthropic accepts EITHER temperature OR top_p (not both). // - 4.7+: rejects all of temperature/top_p/top_k unless null/default. We // omit them entirely so operators with legacy configs don't 400. - if (!isClaude47) { + if (!strictSamplingContract) { if (runtimeModel.getTemperature() != null) { builder.temperature(runtimeModel.getTemperature()); } else if (runtimeModel.getTopP() != null) { builder.topP(runtimeModel.getTopP()); } } else if (runtimeModel.getTemperature() != null || runtimeModel.getTopP() != null) { - log.debug("Ignoring temperature/top_p for Claude 4.7 model {} (API rejects sampling params)", + log.debug("Ignoring temperature/top_p for Claude 4.7+ model {} (API rejects sampling params)", modelName); } // Anthropic rejects non-positive maxTokens — clamp here so a bad config diff --git a/mateclaw-server/src/main/java/vip/mate/llm/routing/ProviderRouter.java b/mateclaw-server/src/main/java/vip/mate/llm/routing/ProviderRouter.java index f4891ccf..19180b53 100644 --- a/mateclaw-server/src/main/java/vip/mate/llm/routing/ProviderRouter.java +++ b/mateclaw-server/src/main/java/vip/mate/llm/routing/ProviderRouter.java @@ -7,6 +7,7 @@ import vip.mate.llm.model.ModelConfigEntity; import vip.mate.llm.service.ModelCapabilityService; import vip.mate.llm.service.ModelCapabilityService.Modality; import vip.mate.llm.service.ModelConfigService; +import vip.mate.llm.service.ModelProviderService; import vip.mate.skill.manifest.SkillManifest; import vip.mate.skill.runtime.SkillRuntimeService; import vip.mate.llm.model.ModelProviderEntity; @@ -45,6 +46,7 @@ public class ProviderRouter { private final AgentBindingResolver bindingService; private final ModelCapabilityService capabilityService; private final ModelConfigService modelConfigService; + private final ModelProviderService modelProviderService; /** * Compute the union of capability requirements declared by the @@ -176,57 +178,88 @@ public class ProviderRouter { } /** - * Pick a primary {@link ModelConfigEntity} that satisfies as many - * required modalities as possible. Falls back to the global default - * when nothing better is configured. + * Pick a primary model using a two-pass strategy. * - *

Logic: try each preferred provider in turn; for each, ask - * {@link ModelProviderService#getDefaultModelByProvider} for its - * default chat model and check capability resolution. First match - * wins. If nothing matches, return the global default unchanged. + *

Pass 1 (capability-gated): preferred providers → global default. + *

Pass 2 (unconstrained fallback): preferred providers → global default. + * + *

When no preferred providers are configured the preferred branches + * are skipped, preserving the legacy behaviour. */ public ModelConfigEntity selectPrimary(Long agentId, ModelConfigEntity globalDefault) { if (agentId == null) return globalDefault; + + List preferred = bindingService.getPreferredProviderIds(agentId); + Set requiredModalities = resolveRequiredModalities(agentId); + + // Pass 1: capability-satisfying providers (preferred first, global fallback) + if (requiredModalities != null) { + // 1a. preferred providers satisfying capabilities + for (String providerId : preferred) { + ModelConfigEntity candidate = pickProviderDefault(providerId); + if (candidate == null) continue; + if (satisfies(candidate, requiredModalities)) { + log.info("[ProviderRouter] agent={} primary={}/{} (preferred, satisfies {})", + agentId, candidate.getProvider(), candidate.getModelName(), requiredModalities); + return candidate; + } + } + // 1b. global default satisfying capabilities + if (globalDefault != null && satisfies(globalDefault, requiredModalities)) { + log.info("[ProviderRouter] agent={} primary={}/{} (global, satisfies {})", + agentId, globalDefault.getProvider(), globalDefault.getModelName(), requiredModalities); + return globalDefault; + } + } + + // Pass 2: unconstrained (capability ignored — last resort) + // 2a. any available preferred provider + for (String providerId : preferred) { + ModelConfigEntity candidate = pickProviderDefault(providerId); + if (candidate == null) continue; + log.info("[ProviderRouter] agent={} primary={}/{} (preferred, unconstrained)", + agentId, candidate.getProvider(), candidate.getModelName()); + return candidate; + } + // 2b. global default (ultimate fallback) + if (globalDefault != null) { + log.info("[ProviderRouter] agent={} primary={}/{} (global default)", + agentId, globalDefault.getProvider(), globalDefault.getModelName()); + return globalDefault; + } + + return null; + } + + /** Returns null when no capabilities are required (skips Pass 1). */ + private Set resolveRequiredModalities(Long agentId) { Set needs = aggregateModelNeeds(agentId); - if (needs.isEmpty()) return globalDefault; - Set requiredModalities = needs.stream() + if (needs == null || needs.isEmpty()) return null; + Set mods = needs.stream() .map(this::mapToModality) .filter(java.util.Objects::nonNull) .collect(java.util.stream.Collectors.toCollection( () -> EnumSet.noneOf(Modality.class))); - if (requiredModalities.isEmpty()) return globalDefault; + return mods.isEmpty() ? null : mods; + } - // Already satisfies? Skip the search. - if (globalDefault != null) { - EnumSet resolved = capabilityService.resolve( - globalDefault.getModelName(), globalDefault.getModalities()); - if (resolved.containsAll(requiredModalities)) return globalDefault; - } - - List preferred = bindingService.getPreferredProviderIds(agentId); - for (String providerId : preferred) { - ModelConfigEntity candidate = pickProviderDefault(providerId); - if (candidate == null) continue; - EnumSet resolved = capabilityService.resolve( - candidate.getModelName(), candidate.getModalities()); - if (resolved.containsAll(requiredModalities)) { - log.info("[ProviderRouter] agent={} switched primary to {}/{} for needs={}", - agentId, candidate.getProvider(), candidate.getModelName(), - requiredModalities); - return candidate; - } - } - // No preferred provider satisfied; keep the diagnostic warning - // path on the original default so the user sees the gap in logs. - return globalDefault; + private boolean satisfies(ModelConfigEntity model, Set required) { + return capabilityService.resolve(model.getModelName(), model.getModalities()) + .containsAll(required); } private ModelConfigEntity pickProviderDefault(String providerId) { if (providerId == null || providerId.isBlank()) return null; try { - return modelConfigService.getDefaultModelByProvider(providerId); + // A provider without usable credentials can't serve as the primary + // model: selecting it would only be rejected downstream and fall + // back to the global default, silently skipping the remaining + // preferred providers. Skip it here so preference resolution + // continues to the next entry instead. + if (!modelProviderService.isProviderConfigured(providerId)) return null; + return modelConfigService.getPrimaryChatModelByProvider(providerId); } catch (Exception e) { - // getDefaultModelByProvider can return null or throw when + // getPrimaryChatModelByProvider can return null or throw when // the provider has no enabled chat model; treat both as // "no candidate from this provider". return null; diff --git a/mateclaw-server/src/main/java/vip/mate/llm/service/ModelConfigService.java b/mateclaw-server/src/main/java/vip/mate/llm/service/ModelConfigService.java index b6ea5a93..983cd49e 100644 --- a/mateclaw-server/src/main/java/vip/mate/llm/service/ModelConfigService.java +++ b/mateclaw-server/src/main/java/vip/mate/llm/service/ModelConfigService.java @@ -183,6 +183,32 @@ public class ModelConfigService { .last("LIMIT 1")); } + /** + * Resolve a provider's primary chat model for routing. + * + *

Prefers the row carrying the system default flag when it happens to + * belong to this provider; otherwise falls back to the provider's + * earliest-configured enabled chat model. The {@code is_default} flag is a + * single system-wide marker (see {@link #clearDefaultFlag}), so a provider + * that does not own it has no row matching {@link #getDefaultModelByProvider}. + * Without this fallback a preferred provider could never contribute a + * primary model unless it already held the global default. + * + * @return the provider's primary chat model, or {@code null} when the + * provider has no enabled chat model configured + */ + public ModelConfigEntity getPrimaryChatModelByProvider(String providerId) { + if (providerId == null || providerId.isBlank()) return null; + ModelConfigEntity def = getDefaultModelByProvider(providerId); + if (def != null) return def; + return modelConfigMapper.selectOne(new LambdaQueryWrapper() + .eq(ModelConfigEntity::getProvider, providerId) + .eq(ModelConfigEntity::getEnabled, true) + .eq(ModelConfigEntity::getModelType, "chat") + .orderByAsc(ModelConfigEntity::getId) + .last("LIMIT 1")); + } + public ModelConfigEntity createModel(ModelConfigEntity entity) { validateModel(entity, null); if (Boolean.TRUE.equals(entity.getIsDefault())) { diff --git a/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletedEvent.java b/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletedEvent.java index 2c63584f..91558f55 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletedEvent.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletedEvent.java @@ -11,6 +11,9 @@ package vip.mate.memory.event; * @param assistantReply Agent 最终回答 * @param messageCount 当前会话消息总数 * @param triggerSource 触发来源："web" / "channel" / "cron" + * @param ownerKey memory owner this turn is attributed to (e.g. + * "user:42"); null / "system" means not owner-scoped, + * in which case extracted memory is written as shared. * @author MateClaw Team */ public record ConversationCompletedEvent( @@ -19,5 +22,12 @@ public record ConversationCompletedEvent( String userMessage, String assistantReply, int messageCount, - String triggerSource -) {} + String triggerSource, + String ownerKey +) { + /** Backwards-compatible constructor without an owner key (resolves to null). */ + public ConversationCompletedEvent(Long agentId, String conversationId, String userMessage, + String assistantReply, int messageCount, String triggerSource) { + this(agentId, conversationId, userMessage, assistantReply, messageCount, triggerSource, null); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletionPublisher.java b/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletionPublisher.java index f3258cbd..86a9a38f 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletionPublisher.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/event/ConversationCompletionPublisher.java @@ -4,6 +4,9 @@ import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.context.ApplicationEventPublisher; import org.springframework.stereotype.Component; +import vip.mate.agent.context.ChatOrigin; +import vip.mate.agent.context.ChatOriginHolder; +import vip.mate.memory.identity.MemoryOwnerResolver; import vip.mate.workspace.conversation.ConversationService; /** @@ -32,6 +35,7 @@ public class ConversationCompletionPublisher { private final ApplicationEventPublisher eventPublisher; private final ConversationService conversationService; + private final MemoryOwnerResolver memoryOwnerResolver; /** * Publish a {@link ConversationCompletedEvent} for the given turn. @@ -51,6 +55,43 @@ public class ConversationCompletionPublisher { String userMessage, String assistantReply, String source) { + // Best-effort owner resolution from the request-scoped origin holder. + // Reliable for callers that publish on the same thread the origin was + // captured on (IM router, talk mode, cron). Web entry points publish + // from a reactive completion callback after the holder is cleared, so + // they MUST use the explicit overload below to stay consistent with the + // read path's owner key. + publish(agentId, conversationId, userMessage, assistantReply, source, + memoryOwnerResolver.resolve(ChatOriginHolder.get())); + } + + /** + * Publish, attributing the memory write to the owner resolved from an + * explicit {@link ChatOrigin}. Use from entry points (IM channels, talk + * mode) that publish after the request-scoped origin holder is cleared, so + * the write owner matches the read path's owner for the same turn. + */ + public void publishForOrigin(Long agentId, + String conversationId, + String userMessage, + String assistantReply, + String source, + ChatOrigin origin) { + publish(agentId, conversationId, userMessage, assistantReply, source, + memoryOwnerResolver.resolve(origin)); + } + + /** + * Publish with an explicit {@code ownerKey}. Use this from entry points + * where the request-scoped origin is no longer on the current thread, so + * the memory write is attributed to the same owner the read path recalls. + */ + public void publish(Long agentId, + String conversationId, + String userMessage, + String assistantReply, + String source, + String ownerKey) { if (agentId == null || conversationId == null || conversationId.isBlank()) { return; } @@ -62,7 +103,8 @@ public class ConversationCompletionPublisher { userMessage != null ? userMessage : "", assistantReply != null ? assistantReply : "", messageCount, - source != null ? source : "unknown")); + source != null ? source : "unknown", + ownerKey)); } catch (Exception e) { log.debug("[Memory] Failed to publish ConversationCompletedEvent (source={}, conv={}): {}", source, conversationId, e.getMessage()); diff --git a/mateclaw-server/src/main/java/vip/mate/memory/fact/model/FactEntity.java b/mateclaw-server/src/main/java/vip/mate/memory/fact/model/FactEntity.java index e0bcbee0..0fb38a1e 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/fact/model/FactEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/fact/model/FactEntity.java @@ -50,6 +50,12 @@ public class FactEntity { /** pattern | llm */ private String extractedBy; + /** Memory subject this fact belongs to (e.g. "user:42"); null for shared/legacy rows. */ + private String ownerKey; + + /** Visibility scope: PERSONAL / TEAM / GLOBAL. Defaults to TEAM at the DB level. */ + private String scope; + @TableField(fill = FieldFill.INSERT) private LocalDateTime createTime; diff --git a/mateclaw-server/src/main/java/vip/mate/memory/fact/provider/FactMemoryProvider.java b/mateclaw-server/src/main/java/vip/mate/memory/fact/provider/FactMemoryProvider.java index 764fc352..f16e21fb 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/fact/provider/FactMemoryProvider.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/fact/provider/FactMemoryProvider.java @@ -47,8 +47,13 @@ public class FactMemoryProvider implements MemoryProvider { @Override public String prefetch(Long agentId, String userQuery) { + return prefetch(agentId, userQuery, null); + } + + @Override + public String prefetch(Long agentId, String userQuery, String ownerKey) { if (!properties.getFact().isProjectionEnabled()) return ""; - List facts = queryService.recallRelevant(agentId, userQuery); + List facts = queryService.recallRelevant(agentId, userQuery, ownerKey); if (facts.isEmpty()) return ""; // Bump usage diff --git a/mateclaw-server/src/main/java/vip/mate/memory/fact/query/FactQueryService.java b/mateclaw-server/src/main/java/vip/mate/memory/fact/query/FactQueryService.java index d5ec9f0f..29b3f7c8 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/fact/query/FactQueryService.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/fact/query/FactQueryService.java @@ -56,6 +56,16 @@ public class FactQueryService { * Recall relevant facts for a query (used by FactMemoryProvider.prefetch). */ public List recallRelevant(Long agentId, String query) { + return recallRelevant(agentId, query, null); + } + + /** + * Owner-scoped recall: returns facts visible to {@code ownerKey} — shared + * (TEAM / GLOBAL) facts plus this owner's PERSONAL facts. A null ownerKey + * means shared-only. Keeps one user's recalled facts out of another user's + * prompt when a single agent is shared across end-users. + */ + public List recallRelevant(Long agentId, String query, String ownerKey) { return factMapper.selectList( new LambdaQueryWrapper() .eq(FactEntity::getAgentId, agentId) @@ -63,6 +73,18 @@ public class FactQueryService { .and(w -> w.like(FactEntity::getSubject, query) .or().like(FactEntity::getObjectValue, query) .or().like(FactEntity::getPredicate, query)) + .and(s -> { + if (ownerKey == null || ownerKey.isBlank()) { + s.in(FactEntity::getScope, vip.mate.memory.identity.MemoryScope.TEAM, + vip.mate.memory.identity.MemoryScope.GLOBAL); + } else { + s.in(FactEntity::getScope, vip.mate.memory.identity.MemoryScope.TEAM, + vip.mate.memory.identity.MemoryScope.GLOBAL) + .or(p -> p.eq(FactEntity::getScope, + vip.mate.memory.identity.MemoryScope.PERSONAL) + .eq(FactEntity::getOwnerKey, ownerKey)); + } + }) .orderByDesc(FactEntity::getTrust) .last("LIMIT 10")); } diff --git a/mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryOwnerResolver.java b/mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryOwnerResolver.java new file mode 100644 index 00000000..39542938 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryOwnerResolver.java @@ -0,0 +1,53 @@ +package vip.mate.memory.identity; + +import org.springframework.stereotype.Component; +import vip.mate.agent.context.ChatOrigin; + +/** + * Resolves the {@code owner_key} that conversation-derived memory should be + * attributed to, from the request's {@link ChatOrigin}. + * + *

The key is a prefixed string so a single agent shared across surfaces + * keeps every subject's memory separate: + *

    + *
  • Web console → {@code user:} (the MateClaw username)
    • + *
  • IM channels → {@code :} (feishu/dingtalk/…)
    • + *
  • WebChat / 3rd-party API → {@code api:}
    • + *
  • Cron / system / unknown → {@link #SYSTEM_OWNER}
    • + *
+ * + * The cron/system fallback is deliberate: it keeps unattributed writes out of + * any real user's PERSONAL bucket (which would otherwise be a black hole that + * nobody can read) — such writes are expected to be TEAM-scoped instead. + * + * @author MateClaw Team + */ +@Component +public class MemoryOwnerResolver { + + /** Owner key used for cron-triggered and identity-less invocations. */ + public static final String SYSTEM_OWNER = "system"; + + /** + * Resolve the owner key for the given origin. Never returns null; falls + * back to {@link #SYSTEM_OWNER} when no usable identity is present. + */ + public String resolve(ChatOrigin origin) { + if (origin == null || origin.cronOrigin()) { + return SYSTEM_OWNER; + } + String requester = origin.requesterId(); + if (requester == null || requester.isBlank() || SYSTEM_OWNER.equals(requester)) { + return SYSTEM_OWNER; + } + String channel = origin.channelType(); + if (channel == null || channel.isBlank() || "web".equals(channel)) { + // Web console (or a degraded origin with no channel): the requester + // id is already the MateClaw username. + return "user:" + requester; + } + // IM / api origins: the requester id is the external sender id; prefix + // with the channel type so two platforms can't collide on the same id. + return channel + ":" + requester; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryScope.java b/mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryScope.java new file mode 100644 index 00000000..7c2973dc --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/memory/identity/MemoryScope.java @@ -0,0 +1,34 @@ +package vip.mate.memory.identity; + +/** + * Visibility scope for a memory row (workspace file, fact, recall). + * + *
    + *
  • {@link #PERSONAL} — only the matching {@code owner_key} can read it. + * Conversation-derived memory defaults here.
    • + *
  • {@link #TEAM} — everyone using the agent can read it. Agent config / + * persona files (AGENTS.md, SOUL.md, PROFILE.md) and legacy rows live + * here.
    • + *
  • {@link #GLOBAL} — always visible. Reserved for agent-creator preset + * facts.
    • + *
+ * + * Stored as a plain string column ({@code scope}) rather than a DB enum so the + * H2 / MySQL migrations stay dialect-neutral. + * + * @author MateClaw Team + */ +public final class MemoryScope { + + public static final String PERSONAL = "PERSONAL"; + public static final String TEAM = "TEAM"; + public static final String GLOBAL = "GLOBAL"; + + private MemoryScope() { + } + + /** A scope is "shared" (visible to every owner) when it is TEAM or GLOBAL. */ + public static boolean isShared(String scope) { + return TEAM.equals(scope) || GLOBAL.equals(scope); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/MemoryLifecycleMediator.java b/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/MemoryLifecycleMediator.java index eb5e1e30..f52f28a6 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/MemoryLifecycleMediator.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/MemoryLifecycleMediator.java @@ -42,7 +42,7 @@ public class MemoryLifecycleMediator { */ public String beforeLlmCall(TurnContext ctx) { try { - String context = memoryManager.prefetchAll(ctx.agentId(), ctx.userQuery()); + String context = memoryManager.prefetchAll(ctx.agentId(), ctx.userQuery(), ctx.ownerKey()); events.publishEvent(new TurnStartedEvent(ctx)); log.debug("[Memory] beforeLlmCall: agent={}, contextLen={}", ctx.agentId(), context != null ? context.length() : 0); diff --git a/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/TurnContext.java b/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/TurnContext.java index d7b6f4c2..ca398d8a 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/TurnContext.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/lifecycle/TurnContext.java @@ -8,6 +8,9 @@ package vip.mate.memory.lifecycle; * @param sessionId session ID (may equal conversationId in Phase 1) * @param turnNumber turn sequence number within the conversation * @param userQuery the current user message + * @param ownerKey resolved memory owner key for this turn (e.g. + * "user:42"); drives per-owner memory recall. May be + * null when memory-isolation context is unavailable. * @author MateClaw Team */ public record TurnContext( @@ -15,5 +18,12 @@ public record TurnContext( String conversationId, String sessionId, int turnNumber, - String userQuery -) {} + String userQuery, + String ownerKey +) { + /** Backwards-compatible constructor without an owner key (resolves to null). */ + public TurnContext(Long agentId, String conversationId, String sessionId, + int turnNumber, String userQuery) { + this(agentId, conversationId, sessionId, turnNumber, userQuery, null); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/memory/listener/PostConversationMemoryListener.java b/mateclaw-server/src/main/java/vip/mate/memory/listener/PostConversationMemoryListener.java index fd4f76c7..2834d2fc 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/listener/PostConversationMemoryListener.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/listener/PostConversationMemoryListener.java @@ -52,7 +52,7 @@ public class PostConversationMemoryListener { try { log.debug("[Memory] Triggering post-conversation memory analysis: agent={}, conv={}", event.agentId(), event.conversationId()); - summarizationService.analyzeAndUpdateMemory(event.agentId(), event.conversationId()); + summarizationService.analyzeAndUpdateMemory(event.agentId(), event.conversationId(), event.ownerKey()); } catch (Exception e) { log.warn("[Memory] Post-conversation summarization failed: agent={}, conv={}, error={}", event.agentId(), event.conversationId(), e.getMessage()); @@ -60,7 +60,7 @@ public class PostConversationMemoryListener { // Memory Nudge: extract structured entries every N turns try { - nudgeService.maybeNudge(event.agentId(), event.conversationId(), event.messageCount()); + nudgeService.maybeNudge(event.agentId(), event.conversationId(), event.messageCount(), event.ownerKey()); } catch (Exception e) { log.debug("[Memory] Nudge trigger failed (non-fatal): {}", e.getMessage()); } diff --git a/mateclaw-server/src/main/java/vip/mate/memory/model/MemoryRecallEntity.java b/mateclaw-server/src/main/java/vip/mate/memory/model/MemoryRecallEntity.java index 3902e95e..b956c133 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/model/MemoryRecallEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/model/MemoryRecallEntity.java @@ -56,6 +56,12 @@ public class MemoryRecallEntity { /** Last time this candidate was reviewed during a dream run */ private LocalDateTime lastReviewedAt; + /** Memory subject this recall belongs to (e.g. "user:42"); null for shared/legacy rows. */ + private String ownerKey; + + /** Visibility scope: PERSONAL / TEAM / GLOBAL. Defaults to TEAM at the DB level. */ + private String scope; + @TableField(fill = FieldFill.INSERT) private LocalDateTime createTime; diff --git a/mateclaw-server/src/main/java/vip/mate/memory/nudge/MemoryNudgeService.java b/mateclaw-server/src/main/java/vip/mate/memory/nudge/MemoryNudgeService.java index 65f19eb0..e723500e 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/nudge/MemoryNudgeService.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/nudge/MemoryNudgeService.java @@ -46,17 +46,29 @@ public class MemoryNudgeService { private final ObjectMapper objectMapper; /** Per-agent cooldown tracking */ - private final ConcurrentHashMap lastNudgeTimes = new ConcurrentHashMap<>(); + private final ConcurrentHashMap lastNudgeTimes = new ConcurrentHashMap<>(); /** * Check if a nudge should be triggered and execute if so. * Called from PostConversationMemoryListener or directly. */ + /** Backwards-compatible entry without an owner key (writes shared memory). */ @Async public void maybeNudge(Long agentId, String conversationId, int messageCount) { + maybeNudge(agentId, conversationId, messageCount, null); + } + + @Async + public void maybeNudge(Long agentId, String conversationId, int messageCount, String ownerKey) { if (!properties.isNudgeEnabled()) { return; } + // Gate per-owner isolation on the lifecycle prefetch path (the only + // auto-injector of PERSONAL structured memory); otherwise write shared + // so nudged entries are not stranded in an unread PERSONAL bucket. + if (!properties.isLifecycleMediatorEnabled()) { + ownerKey = null; + } // Check turn interval if (properties.getNudgeTurnInterval() <= 0 @@ -64,22 +76,23 @@ public class MemoryNudgeService { return; } - // Cooldown check - if (isInCooldown(agentId)) { - log.debug("[Nudge] Agent {} is in cooldown, skipping", agentId); + // Cooldown keyed per (agent, owner) so one owner can't starve another. + String cooldownKey = agentId + ":" + (ownerKey == null ? "" : ownerKey); + if (isInCooldown(cooldownKey)) { + log.debug("[Nudge] Agent {} (owner {}) is in cooldown, skipping", agentId, ownerKey); return; } try { - doNudge(agentId, conversationId); - lastNudgeTimes.put(agentId, Instant.now()); + doNudge(agentId, conversationId, ownerKey); + lastNudgeTimes.put(cooldownKey, Instant.now()); } catch (Exception e) { log.warn("[Nudge] Failed for agent={}, conv={}: {}", agentId, conversationId, e.getMessage()); } } - private void doNudge(Long agentId, String conversationId) { + private void doNudge(Long agentId, String conversationId, String ownerKey) { // 1. Load recent messages List messages = conversationService.listMessages(conversationId); int maxReview = properties.getNudgeMaxMessages(); @@ -96,8 +109,8 @@ public class MemoryNudgeService { String transcript = buildTranscript(recent); if (transcript.isBlank()) return; - // 3. Load existing structured memories for dedup - String existingMemories = structuredMemoryService.buildMemoryBlock(agentId); + // 3. Load existing structured memories for dedup (owner-scoped) + String existingMemories = structuredMemoryService.buildMemoryBlock(agentId, ownerKey); // 4. Build prompt String systemPrompt = PromptLoader.loadPrompt("memory/nudge-system"); @@ -140,7 +153,7 @@ public class MemoryNudgeService { if (type.isBlank() || key.isBlank() || content.isBlank()) continue; try { - structuredMemoryService.remember(agentId, type, key, content, "nudge"); + structuredMemoryService.remember(agentId, type, key, content, "nudge", ownerKey); saved++; } catch (Exception e) { log.debug("[Nudge] Failed to save entry {}/{}: {}", type, key, e.getMessage()); @@ -226,8 +239,8 @@ public class MemoryNudgeService { || msg.contains("速率限制") || msg.contains("Too Many Requests")); } - private boolean isInCooldown(Long agentId) { - Instant lastRun = lastNudgeTimes.get(agentId); + private boolean isInCooldown(String cooldownKey) { + Instant lastRun = lastNudgeTimes.get(cooldownKey); if (lastRun == null) return false; long cooldownSeconds = properties.getNudgeCooldownMinutes() * 60L; return Instant.now().isBefore(lastRun.plusSeconds(cooldownSeconds)); diff --git a/mateclaw-server/src/main/java/vip/mate/memory/provider/BuiltinMemoryProvider.java b/mateclaw-server/src/main/java/vip/mate/memory/provider/BuiltinMemoryProvider.java index 7cf62bae..70efc3b2 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/provider/BuiltinMemoryProvider.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/provider/BuiltinMemoryProvider.java @@ -59,12 +59,24 @@ public class BuiltinMemoryProvider implements MemoryProvider { } /** - * Builtin memory is already injected via system prompt. - * No additional per-turn prefetch needed. + * Shared (TEAM / GLOBAL) memory is baked into the system prompt at build + * time. Per-owner PERSONAL memory cannot be — the agent instance is cached + * and reused across users — so it is injected here, per turn, for the + * current requester only. */ @Override - public String prefetch(Long agentId, String userQuery) { - return ""; + public String prefetch(Long agentId, String userQuery, String ownerKey) { + if (ownerKey == null || ownerKey.isBlank()) { + return ""; + } + try { + String block = workspaceFileService.buildOwnerMemoryBlock(agentId, ownerKey); + return block != null ? block : ""; + } catch (Exception e) { + log.warn("[BuiltinMemory] Failed to build owner memory block for agent={}, owner={}: {}", + agentId, ownerKey, e.getMessage()); + return ""; + } } /** diff --git a/mateclaw-server/src/main/java/vip/mate/memory/provider/StructuredMemoryProvider.java b/mateclaw-server/src/main/java/vip/mate/memory/provider/StructuredMemoryProvider.java index 7dcc1c64..9d6b2543 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/provider/StructuredMemoryProvider.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/provider/StructuredMemoryProvider.java @@ -35,20 +35,68 @@ public class StructuredMemoryProvider implements MemoryProvider { } /** - * Returns typed memory entries formatted as a Markdown block - * for system prompt injection. + * Returns the stable, low-volume typed entries (user profile, feedback) + * for unconditional system prompt injection. + */ + /** + * Build-time injection is limited to SHARED (TEAM / GLOBAL) structured + * memory — agent-creator presets and team-wide facts. Conversation-derived + * PERSONAL structured memory is owner-specific and the agent instance is + * cached across users, so it is injected per-turn in + * {@link #prefetch(Long, String, String)} for the current owner only. */ @Override public String systemPromptBlock(Long agentId) { try { - return structuredMemoryService.buildMemoryBlock(agentId); + // ownerKey=null → buildMemoryBlock reads shared (TEAM/GLOBAL) rows only. + return structuredMemoryService.buildMemoryBlock(agentId, null); } catch (Exception e) { - log.warn("[StructuredMemory] Failed to build memory block for agent={}: {}", + log.warn("[StructuredMemory] Failed to build shared memory block for agent={}: {}", agentId, e.getMessage()); return ""; } } + @Override + public String prefetch(Long agentId, String userQuery) { + return prefetch(agentId, userQuery, null); + } + + /** + * Owner-scoped per-turn injection: the stable user/feedback entries plus the + * query-relevant project/reference entries — all restricted to the current + * owner's structured memory. Returns empty when there is no isolatable owner + * so a shared agent never injects another user's structured memory. The + * returned block is fenced centrally by the memory manager. + */ + @Override + public String prefetch(Long agentId, String userQuery, String ownerKey) { + try { + String stable = structuredMemoryService.buildMemoryBlock(agentId, ownerKey); + String relevant = structuredMemoryService.buildPrefetchBlock(agentId, userQuery, ownerKey); + boolean hasStable = stable != null && !stable.isBlank(); + boolean hasRelevant = relevant != null && !relevant.isBlank(); + if (!hasStable && !hasRelevant) { + return ""; + } + StringBuilder sb = new StringBuilder(); + if (hasStable) { + sb.append(stable); + } + if (hasRelevant) { + if (sb.length() > 0) { + sb.append("\n\n"); + } + sb.append(relevant); + } + return sb.toString(); + } catch (Exception e) { + log.warn("[StructuredMemory] Failed to build prefetch block for agent={}, owner={}: {}", + agentId, ownerKey, e.getMessage()); + return ""; + } + } + /** * Tools are auto-discovered by ToolRegistry component scan. */ diff --git a/mateclaw-server/src/main/java/vip/mate/memory/service/MemorySummarizationService.java b/mateclaw-server/src/main/java/vip/mate/memory/service/MemorySummarizationService.java index d8e59af2..962737d3 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/service/MemorySummarizationService.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/service/MemorySummarizationService.java @@ -46,41 +46,66 @@ public class MemorySummarizationService { private final AgentGraphBuilder agentGraphBuilder; private final MemoryProperties properties; private final ObjectMapper objectMapper; + private final StructuredMemoryService structuredMemoryService; - /** Per-agent 锁，防止并发写入 */ - private final ConcurrentHashMap agentLocks = new ConcurrentHashMap<>(); + /** Typed-memory categories the summarizer may route entries into. */ + private static final java.util.Set STRUCTURED_TYPES = + java.util.Set.of("user", "feedback", "project", "reference"); - /** Per-agent 冷却时间记录 */ - private final ConcurrentHashMap lastRunTimes = new ConcurrentHashMap<>(); + /** Per-(agent, owner) 锁，防止并发写入 */ + private final ConcurrentHashMap agentLocks = new ConcurrentHashMap<>(); + + /** Per-(agent, owner) 冷却时间记录 */ + private final ConcurrentHashMap lastRunTimes = new ConcurrentHashMap<>(); + + /** Backwards-compatible entry without an owner key (writes shared memory). */ + public void analyzeAndUpdateMemory(Long agentId, String conversationId) { + analyzeAndUpdateMemory(agentId, conversationId, null); + } /** * 分析对话并更新记忆文件 * * @param agentId Agent ID * @param conversationId 会话 ID + * @param ownerKey memory owner this conversation is attributed to; null + * or "system" writes shared (TEAM) memory, otherwise + * memory is written PERSONAL to this owner */ - public void analyzeAndUpdateMemory(Long agentId, String conversationId) { + public void analyzeAndUpdateMemory(Long agentId, String conversationId, String ownerKey) { + // Per-owner isolation is gated on the lifecycle prefetch path, which is + // the only auto-injector of PERSONAL memory. When that path is off, + // writing PERSONAL would strand memory in a bucket nothing auto-reads, + // so fall back to shared (legacy) writes — isolation activates together + // with lifecycleMediatorEnabled. + if (!properties.isLifecycleMediatorEnabled()) { + ownerKey = null; + } + // Lock / cooldown are keyed per (agent, owner) so one owner's busy + // extraction never starves another owner sharing the same agent. + String lockKey = agentId + ":" + (ownerKey == null ? "" : ownerKey); + // 冷却检查 - if (isInCooldown(agentId)) { - log.debug("[Memory] Agent {} is in cooldown, skipping summarization", agentId); + if (isInCooldown(lockKey)) { + log.debug("[Memory] Agent {} (owner {}) is in cooldown, skipping summarization", agentId, ownerKey); return; } - ReentrantLock lock = agentLocks.computeIfAbsent(agentId, k -> new ReentrantLock()); + ReentrantLock lock = agentLocks.computeIfAbsent(lockKey, k -> new ReentrantLock()); if (!lock.tryLock()) { - log.debug("[Memory] Agent {} is already being summarized, skipping", agentId); + log.debug("[Memory] Agent {} (owner {}) is already being summarized, skipping", agentId, ownerKey); return; } try { - doAnalyzeAndUpdate(agentId, conversationId); - lastRunTimes.put(agentId, Instant.now()); + doAnalyzeAndUpdate(agentId, conversationId, ownerKey); + lastRunTimes.put(lockKey, Instant.now()); } finally { lock.unlock(); } } - private void doAnalyzeAndUpdate(Long agentId, String conversationId) { + private void doAnalyzeAndUpdate(Long agentId, String conversationId, String ownerKey) { // 1. 加载对话消息 List messages = conversationService.listMessages(conversationId); if (messages.size() < properties.getMinMessagesForSummarize()) { @@ -95,11 +120,11 @@ public class MemorySummarizationService { return; } - // 2. 加载现有记忆文件内容 - String profileContent = readFileContentSafe(agentId, "PROFILE.md"); - String memoryContent = readFileContentSafe(agentId, "MEMORY.md"); + // 2. 加载现有记忆文件内容（按 owner 隔离） + String profileContent = readFileContentSafe(agentId, "PROFILE.md", ownerKey); + String memoryContent = readFileContentSafe(agentId, "MEMORY.md", ownerKey); String dailyFilename = "memory/" + LocalDate.now() + ".md"; - String dailyContent = readFileContentSafe(agentId, dailyFilename); + String dailyContent = readFileContentSafe(agentId, dailyFilename, ownerKey); // 3. 构建对话 transcript String transcript = buildTranscript(messages); @@ -148,7 +173,7 @@ public class MemorySummarizationService { } // 6. 应用更新 - applyUpdates(agentId, root, dailyFilename, dailyContent); + applyUpdates(agentId, root, dailyFilename, dailyContent, ownerKey); String reason = root.path("reason").asText(""); log.info("[Memory] Memory updated for agent={}, conv={}: {}", agentId, conversationId, reason); @@ -159,7 +184,8 @@ public class MemorySummarizationService { } } - private void applyUpdates(Long agentId, JsonNode root, String dailyFilename, String existingDailyContent) { + private void applyUpdates(Long agentId, JsonNode root, String dailyFilename, + String existingDailyContent, String ownerKey) { // Daily entry: 追加模式 JsonNode dailyNode = root.path("daily_entry"); if (!dailyNode.isNull() && dailyNode.isTextual()) { @@ -168,8 +194,8 @@ public class MemorySummarizationService { String newContent = existingDailyContent.isEmpty() ? "# " + LocalDate.now() + "\n\n" + entry : existingDailyContent + "\n\n" + entry; - workspaceFileService.saveFile(agentId, dailyFilename, newContent); - log.info("[Memory] Appended daily entry to {} for agent={}", dailyFilename, agentId); + saveMemory(agentId, dailyFilename, newContent, ownerKey); + log.info("[Memory] Appended daily entry to {} for agent={}, owner={}", dailyFilename, agentId, ownerKey); } } @@ -178,8 +204,8 @@ public class MemorySummarizationService { if (!memoryNode.isNull() && memoryNode.isTextual()) { String content = memoryNode.asText().trim(); if (!content.isEmpty()) { - workspaceFileService.saveFile(agentId, "MEMORY.md", content); - log.info("[Memory] Updated MEMORY.md for agent={}", agentId); + saveMemory(agentId, "MEMORY.md", content, ownerKey); + log.info("[Memory] Updated MEMORY.md for agent={}, owner={}", agentId, ownerKey); } } @@ -188,10 +214,44 @@ public class MemorySummarizationService { if (!profileNode.isNull() && profileNode.isTextual()) { String content = profileNode.asText().trim(); if (!content.isEmpty()) { - workspaceFileService.saveFile(agentId, "PROFILE.md", content); - log.info("[Memory] Updated PROFILE.md for agent={}", agentId); + saveMemory(agentId, "PROFILE.md", content, ownerKey); + log.info("[Memory] Updated PROFILE.md for agent={}, owner={}", agentId, ownerKey); } } + + // Structured entries: route typed facts (especially volatile project / + // reference facts kept out of the always-on MEMORY.md) into structured + // memory so they become query-conditioned recallable, instead of being + // stranded in daily notes that only the agent's tools can reach. + applyStructuredEntries(agentId, root.path("structured_entries"), ownerKey); + } + + private void applyStructuredEntries(Long agentId, JsonNode entriesNode, String ownerKey) { + if (entriesNode == null || !entriesNode.isArray() || entriesNode.isEmpty()) { + return; + } + int written = 0; + for (JsonNode entry : entriesNode) { + String type = entry.path("type").asText("").trim().toLowerCase(); + String key = entry.path("key").asText("").trim(); + String content = entry.path("content").asText("").trim(); + if (!STRUCTURED_TYPES.contains(type) || key.isEmpty() || content.isEmpty()) { + log.debug("[Memory] Skipping invalid structured entry (type={}, key={}) for agent={}", + type, key, agentId); + continue; + } + try { + structuredMemoryService.remember(agentId, type, key, content, "auto-summary", ownerKey); + written++; + } catch (Exception e) { + log.warn("[Memory] Failed to write structured entry '{}' (type={}) for agent={}: {}", + key, type, agentId, e.getMessage()); + } + } + if (written > 0) { + log.info("[Memory] Routed {} structured entr{} for agent={}", + written, written == 1 ? "y" : "ies", agentId); + } } private String buildTranscript(List messages) { @@ -247,15 +307,40 @@ public class MemorySummarizationService { } } - private String readFileContentSafe(Long agentId, String filename) { + /** + * Read an owner-scoped memory file. When {@code ownerKey} denotes a real + * owner the row is looked up by (agent, filename, owner); otherwise it falls + * back to the shared file so cron / system extraction keeps working. + */ + private String readFileContentSafe(Long agentId, String filename, String ownerKey) { try { - WorkspaceFileEntity file = workspaceFileService.getFile(agentId, filename); + WorkspaceFileEntity file = isPersonal(ownerKey) + ? workspaceFileService.getMemoryFile(agentId, filename, ownerKey) + : workspaceFileService.getFile(agentId, filename); return file != null && file.getContent() != null ? file.getContent() : ""; } catch (Exception e) { return ""; } } + /** + * Persist extracted memory to the owner's PERSONAL bucket, or to the shared + * (TEAM) file when there is no real owner (cron / system). + */ + private void saveMemory(Long agentId, String filename, String content, String ownerKey) { + if (isPersonal(ownerKey)) { + workspaceFileService.saveMemoryFile(agentId, filename, content, ownerKey); + } else { + workspaceFileService.saveFile(agentId, filename, content); + } + } + + /** A real, isolatable owner — i.e. not null/blank and not the system bucket. */ + private boolean isPersonal(String ownerKey) { + return ownerKey != null && !ownerKey.isBlank() + && !vip.mate.memory.identity.MemoryOwnerResolver.SYSTEM_OWNER.equals(ownerKey); + } + /** * 带轻量重试的 LLM 调用：遇到 429 时等待后重试，避免后台任务因限流直接放弃。 * Spring AI RetryTemplate 已处理第一层重试，此方法作为二次保护。 @@ -292,8 +377,8 @@ public class MemorySummarizationService { || msg.contains("速率限制") || msg.contains("Too Many Requests")); } - private boolean isInCooldown(Long agentId) { - Instant lastRun = lastRunTimes.get(agentId); + private boolean isInCooldown(String lockKey) { + Instant lastRun = lastRunTimes.get(lockKey); if (lastRun == null) return false; long cooldownSeconds = properties.getCooldownMinutes() * 60L; return Instant.now().isBefore(lastRun.plusSeconds(cooldownSeconds)); diff --git a/mateclaw-server/src/main/java/vip/mate/memory/service/StructuredMemoryService.java b/mateclaw-server/src/main/java/vip/mate/memory/service/StructuredMemoryService.java index c5295fd8..0edfc717 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/service/StructuredMemoryService.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/service/StructuredMemoryService.java @@ -36,6 +36,73 @@ public class StructuredMemoryService { private static final Set VALID_TYPES = Set.of("user", "feedback", "project", "reference"); private static final Pattern SECTION_PATTERN = Pattern.compile("^## (.+)$", Pattern.MULTILINE); + /** + * Stable, low-volume entry types injected unconditionally into the system prompt. + * These describe the user and their durable preferences, so they stay relevant + * across every turn and keep the system prefix cacheable. + */ + private static final List SYSTEM_PROMPT_TYPES = List.of("user", "feedback"); + + /** + * Growing, easily-confused entry types (specific project facts, reference notes) + * surfaced only when the current question matches them. Always-on injection of + * these competes with general knowledge in the prompt and causes the model to + * confuse a specific stored fact with similarly-shaped background information. + */ + private static final List PREFETCH_TYPES = List.of("project", "reference"); + + /** Maximum number of entries injected by a single query-conditioned prefetch. */ + private static final int MAX_PREFETCH_ENTRIES = 6; + + /** + * Appended to the prefetch block header when a {@code project}-type entry is + * included, i.e. the user's own current project was recalled for this turn. + * Downstream prompt assembly detects this marker to avoid also injecting + * knowledge-base reference context that would compete for "what project is + * this" — personal project memory is authoritative over reference articles. + */ + public static final String PROJECT_RECALLED_MARKER = "includes the user's current project"; + + /** Latin word tokens of length >= 2 used for relevance shingling. */ + private static final Pattern WORD_RE = Pattern.compile("[a-z0-9]{2,}"); + + /** Captures the ISO update date from an entry's metadata line ("> ... | Updated: YYYY-MM-DD"). */ + private static final Pattern UPDATED_RE = Pattern.compile("Updated:\\s*(\\d{4}-\\d{2}-\\d{2})"); + + /** + * Domain aliases bridging natural-language question terms to entry keys/types. + * Plain substring/shingle overlap misses cross-language matches such as the + * question term "技术栈" against the key "project_tech_stack", so each alias + * boosts entries whose key contains one of {@code keySubstrings} or whose type + * equals {@code type} when any of its {@code queryTerms} appears in the question. + */ + private static final List ALIASES = List.of( + new Alias(List.of("代号", "项目代号", "codename", "code name"), + List.of("codename", "code_name", "code"), null), + new Alias(List.of("技术栈", "技术", "技术堆栈", "tech stack", "techstack", "technology", "stack"), + List.of("tech", "stack", "技术"), null), + new Alias(List.of("偏好", "风格", "习惯", "preference", "style"), + List.of("pref", "style", "偏好", "风格"), null), + new Alias(List.of("项目", "project"), + List.of(), "project") + ); + + /** A natural-language-to-entry alias rule used by relevance scoring. */ + private record Alias(List queryTerms, List keySubstrings, String type) { + boolean matchesQuery(String query) { + return queryTerms.stream().anyMatch(query::contains); + } + + boolean matchesEntry(String entryType, String keyLower) { + boolean keyHit = keySubstrings.stream().anyMatch(keyLower::contains); + boolean typeHit = type != null && type.equals(entryType); + return keyHit || typeHit; + } + } + + /** A structured entry with its relevance score and update date for the current query. */ + private record ScoredEntry(String type, String key, String body, int score, String updated) {} + private final WorkspaceFileService workspaceFileService; private final ApplicationEventPublisher eventPublisher; @@ -47,13 +114,18 @@ public class StructuredMemoryService { * Uses per-file locking to handle concurrent tool calls writing to the same file. */ public void remember(Long agentId, String type, String key, String content, String source) { + remember(agentId, type, key, content, source, null); + } + + /** Owner-scoped variant of {@link #remember}. */ + public void remember(Long agentId, String type, String key, String content, String source, String ownerKey) { validateType(type); String filename = toFilename(type); - String lockKey = agentId + ":" + filename; + String lockKey = agentId + ":" + (ownerKey == null ? "" : ownerKey) + ":" + filename; ReentrantLock lock = fileLocks.computeIfAbsent(lockKey, k -> new ReentrantLock()); lock.lock(); try { - String fileContent = readFileSafe(agentId, filename); + String fileContent = readFileSafe(agentId, filename, ownerKey); String metadata = "> Source: " + (source != null ? source : "agent") + " | Updated: " + LocalDate.now(); @@ -69,7 +141,7 @@ public class StructuredMemoryService { updated = fileContent.isBlank() ? newSection : fileContent.trim() + "\n\n" + newSection; } - workspaceFileService.saveFile(agentId, filename, updated); + saveStructured(agentId, filename, updated, ownerKey); log.info("[StructuredMemory] {} entry '{}' for agent={} (source={})", existingSection != null ? "Updated" : "Added", key, agentId, source); // Publish event for SOUL auto-evolution (Phase 2) @@ -83,6 +155,11 @@ public class StructuredMemoryService { * Search entries by type and optional keyword. */ public List> recall(Long agentId, String type, String keyword) { + return recall(agentId, type, keyword, null); + } + + /** Owner-scoped variant of {@link #recall(Long, String, String)}. */ + public List> recall(Long agentId, String type, String keyword, String ownerKey) { if (type != null) { validateType(type); } @@ -91,7 +168,7 @@ public class StructuredMemoryService { List> results = new ArrayList<>(); for (String t : types) { - String fileContent = readFileSafe(agentId, toFilename(t)); + String fileContent = readFileSafe(agentId, toFilename(t), ownerKey); if (fileContent.isBlank()) continue; Map sections = parseSections(fileContent); @@ -114,13 +191,18 @@ public class StructuredMemoryService { * Remove a memory entry by type and key. */ public boolean forget(Long agentId, String type, String key) { + return forget(agentId, type, key, null); + } + + /** Owner-scoped variant of {@link #forget(Long, String, String)}. */ + public boolean forget(Long agentId, String type, String key, String ownerKey) { validateType(type); String filename = toFilename(type); - String lockKey = agentId + ":" + filename; + String lockKey = agentId + ":" + (ownerKey == null ? "" : ownerKey) + ":" + filename; ReentrantLock lock = fileLocks.computeIfAbsent(lockKey, k -> new ReentrantLock()); lock.lock(); try { - String fileContent = readFileSafe(agentId, filename); + String fileContent = readFileSafe(agentId, filename, ownerKey); if (fileContent.isBlank()) return false; String section = findSection(fileContent, key); @@ -129,7 +211,7 @@ public class StructuredMemoryService { String updated = fileContent.replace(section, "").trim(); // Clean up double blank lines updated = updated.replaceAll("\n{3,}", "\n\n"); - workspaceFileService.saveFile(agentId, filename, updated); + saveStructured(agentId, filename, updated, ownerKey); log.info("[StructuredMemory] Removed entry '{}' (type={}) for agent={}", key, type, agentId); return true; } finally { @@ -144,16 +226,27 @@ public class StructuredMemoryService { return recall(agentId, type, null); } + /** Owner-scoped variant of {@link #listEntries(Long, String)}. */ + public List> listEntries(Long agentId, String type, String ownerKey) { + return recall(agentId, type, null, ownerKey); + } + /** * Build a formatted memory block for system prompt injection. - * Returns all typed entries formatted as Markdown. + * Includes only the stable, low-volume entry types ({@link #SYSTEM_PROMPT_TYPES}); + * growing/specific types are surfaced per-turn via {@link #buildPrefetchBlock}. */ public String buildMemoryBlock(Long agentId) { + return buildMemoryBlock(agentId, null); + } + + /** Owner-scoped variant of {@link #buildMemoryBlock(Long)}. */ + public String buildMemoryBlock(Long agentId, String ownerKey) { StringBuilder sb = new StringBuilder(); boolean hasContent = false; - for (String type : List.of("user", "feedback", "project", "reference")) { - String fileContent = readFileSafe(agentId, toFilename(type)); + for (String type : SYSTEM_PROMPT_TYPES) { + String fileContent = readFileSafe(agentId, toFilename(type), ownerKey); if (fileContent.isBlank()) continue; Map sections = parseSections(fileContent); @@ -176,8 +269,133 @@ public class StructuredMemoryService { return sb.toString().trim(); } + /** + * Build a query-conditioned memory block for per-turn prefetch injection. + * Scores {@link #PREFETCH_TYPES} entries against the user's question and returns + * the top matches as Markdown, or an empty string when nothing is relevant. + * Keeping these entries out of the always-on system prompt avoids salience + * competition that would otherwise let the model answer from general knowledge + * instead of the specific stored fact. + */ + public String buildPrefetchBlock(Long agentId, String userQuery) { + return buildPrefetchBlock(agentId, userQuery, null); + } + + /** Owner-scoped variant of {@link #buildPrefetchBlock(Long, String)}. */ + public String buildPrefetchBlock(Long agentId, String userQuery, String ownerKey) { + if (userQuery == null || userQuery.isBlank()) return ""; + + List scored = recallRelevant(agentId, userQuery, PREFETCH_TYPES, MAX_PREFETCH_ENTRIES, ownerKey); + if (scored.isEmpty()) return ""; + + boolean hasProject = scored.stream().anyMatch(e -> "project".equals(e.type())); + StringBuilder sb = new StringBuilder("## Relevant Structured Memory"); + if (hasProject) { + sb.append(" (").append(PROJECT_RECALLED_MARKER).append(")"); + } + sb.append("\n"); + for (ScoredEntry e : scored) { + sb.append("- **").append(e.key()).append("**: ") + .append(extractContentOnly(e.body())); + if (!e.updated().isBlank()) { + sb.append(" _(updated ").append(e.updated()).append(")_"); + } + sb.append("\n"); + } + return sb.toString().trim(); + } + // ==================== Internal ==================== + /** + * Score entries of the given types against the user query and return the + * highest-scoring matches (score > 0), best first, capped at {@code limit}. + */ + private List recallRelevant(Long agentId, String userQuery, List types, int limit) { + return recallRelevant(agentId, userQuery, types, limit, null); + } + + private List recallRelevant(Long agentId, String userQuery, List types, int limit, String ownerKey) { + String q = userQuery.toLowerCase(); + Set queryShingles = shingles(q); + + List matches = new ArrayList<>(); + for (String t : types) { + String fileContent = readFileSafe(agentId, toFilename(t), ownerKey); + if (fileContent.isBlank()) continue; + + for (Map.Entry entry : parseSections(fileContent).entrySet()) { + int score = scoreEntry(q, queryShingles, t, entry.getKey(), entry.getValue()); + if (score > 0) { + matches.add(new ScoredEntry(t, entry.getKey(), entry.getValue(), + score, extractUpdated(entry.getValue()))); + } + } + } + + // Most relevant first; break ties by recency so the freshest fact wins a conflict. + matches.sort(Comparator.comparingInt(ScoredEntry::score).reversed() + .thenComparing(Comparator.comparing(ScoredEntry::updated).reversed())); + return matches.size() > limit ? matches.subList(0, limit) : matches; + } + + /** + * Combine three lightweight relevance signals into a single score: + * key-token presence in the query, domain-alias boosts, and character-level + * shingle overlap (CJK bigrams + Latin word tokens) between the query and entry. + */ + private int scoreEntry(String query, Set queryShingles, String type, String key, String body) { + int score = 0; + String keyLower = key.toLowerCase(); + + // 1. Key tokens appearing verbatim in the query. + for (String token : keyLower.split("[_\\s-]+")) { + if (token.length() >= 2 && query.contains(token)) score += 4; + } + + // 2. Domain-alias boosts for cross-language question/key matches. + for (Alias alias : ALIASES) { + if (alias.matchesQuery(query) && alias.matchesEntry(type, keyLower)) score += 6; + } + + // 3. Shingle overlap between the query and the entry text (capped). + Set entryShingles = shingles((key + " " + body).toLowerCase()); + int overlap = 0; + for (String s : entryShingles) { + if (queryShingles.contains(s)) overlap++; + } + score += Math.min(overlap, 6); + + return score; + } + + /** + * Produce a language-agnostic shingle set: Latin word tokens (length >= 2) + * plus CJK character bigrams (single CJK characters when isolated). This lets + * relevance scoring work without a word segmenter on space-free CJK text. + */ + private static Set shingles(String text) { + Set out = new HashSet<>(); + + Matcher m = WORD_RE.matcher(text); + while (m.find()) { + out.add(m.group()); + } + + for (String run : text.replaceAll("[^\\p{IsHan}]", " ").split("\\s+")) { + if (run.isEmpty()) continue; + if (run.length() == 1) { + out.add(run); + } else { + for (int i = 0; i + 2 <= run.length(); i++) { + out.add(run.substring(i, i + 2)); + } + } + } + + return out; + } + private String toFilename(String type) { return "structured/" + type + ".md"; } @@ -190,14 +408,35 @@ public class StructuredMemoryService { } private String readFileSafe(Long agentId, String filename) { + return readFileSafe(agentId, filename, null); + } + + private String readFileSafe(Long agentId, String filename, String ownerKey) { try { - WorkspaceFileEntity file = workspaceFileService.getFile(agentId, filename); + WorkspaceFileEntity file = isPersonal(ownerKey) + ? workspaceFileService.getMemoryFile(agentId, filename, ownerKey) + : workspaceFileService.getFile(agentId, filename); return file != null && file.getContent() != null ? file.getContent() : ""; } catch (Exception e) { return ""; } } + /** Persist structured memory to the owner's PERSONAL bucket, or shared when no real owner. */ + private void saveStructured(Long agentId, String filename, String content, String ownerKey) { + if (isPersonal(ownerKey)) { + workspaceFileService.saveMemoryFile(agentId, filename, content, ownerKey); + } else { + workspaceFileService.saveFile(agentId, filename, content); + } + } + + /** A real, isolatable owner — not null/blank and not the system bucket. */ + private boolean isPersonal(String ownerKey) { + return ownerKey != null && !ownerKey.isBlank() + && !vip.mate.memory.identity.MemoryOwnerResolver.SYSTEM_OWNER.equals(ownerKey); + } + /** * Parse all sections from a Markdown file. * Returns map of key → full section content (including metadata line). @@ -251,6 +490,12 @@ public class StructuredMemoryService { return sb.toString(); } + /** Extract the ISO update date from an entry body's metadata line, or "" if absent. */ + private String extractUpdated(String sectionBody) { + Matcher m = UPDATED_RE.matcher(sectionBody); + return m.find() ? m.group(1) : ""; + } + private String typeDisplayName(String type) { return switch (type) { case "user" -> "User Profile"; diff --git a/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryManager.java b/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryManager.java index b5dd387f..e0ba36ff 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryManager.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryManager.java @@ -104,10 +104,19 @@ public class MemoryManager { * context as new user discourse. */ public String prefetchAll(Long agentId, String userQuery) { + return prefetchAll(agentId, userQuery, null); + } + + /** + * Owner-scoped prefetch. Passes the resolved memory {@code ownerKey} so + * providers recall only the current requester's personal memory plus + * shared (TEAM / GLOBAL) memory (per-owner isolation). + */ + public String prefetchAll(Long agentId, String userQuery, String ownerKey) { List parts = new ArrayList<>(); for (MemoryProvider provider : providers) { try { - String result = provider.prefetch(agentId, userQuery); + String result = provider.prefetch(agentId, userQuery, ownerKey); if (result != null && !result.isBlank()) { parts.add(sanitizeContext(result)); } @@ -206,8 +215,13 @@ public class MemoryManager { */ private String buildMemoryContextBlock(String rawContext) { return "\n" - + "[System note: The following is recalled memory context, " - + "NOT new user input. Treat as informational background data.]\n\n" + + "The following is what you already know about this user and their " + + "work, recalled from your own long-term memory. Use it directly as " + + "established fact when answering — this is your knowledge, not the " + + "user speaking. If something the user asks about is not covered here, " + + "say you do not have it in memory rather than guessing. If entries " + + "conflict, prefer the most recently updated one; if they refer to " + + "different projects, ask which one the user means.\n\n" + rawContext + "\n" + ""; } diff --git a/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryProvider.java b/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryProvider.java index 4af0007b..00595074 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryProvider.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/spi/MemoryProvider.java @@ -64,6 +64,21 @@ public interface MemoryProvider { return ""; } + /** + * Owner-scoped pre-turn recall. Providers that isolate memory per end-user + * override this to recall only the given {@code ownerKey}'s personal memory + * plus shared memory. Default delegates to {@link #prefetch(Long, String)} + * for providers that are not owner-aware. + * + * @param agentId the agent ID + * @param userQuery the current user message + * @param ownerKey resolved memory owner key (e.g. "user:42"); may be null + * @return context text to inject, wrapped in a memory-context fence by MemoryManager + */ + default String prefetch(Long agentId, String userQuery, String ownerKey) { + return prefetch(agentId, userQuery); + } + /** * Post-turn sync. Called after LLM response is available. * Should be non-blocking (async). diff --git a/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MemoryProviderDecorator.java b/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MemoryProviderDecorator.java index 850a7370..1617c0be 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MemoryProviderDecorator.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MemoryProviderDecorator.java @@ -24,6 +24,7 @@ public abstract class MemoryProviderDecorator implements MemoryProvider { @Override public boolean isAvailable() { return delegate.isAvailable(); } @Override public String systemPromptBlock(Long agentId) { return delegate.systemPromptBlock(agentId); } @Override public String prefetch(Long agentId, String userQuery) { return delegate.prefetch(agentId, userQuery); } + @Override public String prefetch(Long agentId, String userQuery, String ownerKey) { return delegate.prefetch(agentId, userQuery, ownerKey); } @Override public void syncTurn(Long agentId, String conversationId, String userMessage, String assistantReply) { delegate.syncTurn(agentId, conversationId, userMessage, assistantReply); } diff --git a/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MetricsMemoryProvider.java b/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MetricsMemoryProvider.java index 90b1f792..04d76382 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MetricsMemoryProvider.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/MetricsMemoryProvider.java @@ -40,9 +40,14 @@ public class MetricsMemoryProvider extends MemoryProviderDecorator { @Override public String prefetch(Long agentId, String userQuery) { + return prefetch(agentId, userQuery, null); + } + + @Override + public String prefetch(Long agentId, String userQuery, String ownerKey) { return prefetchTimer.record(() -> { try { - return delegate.prefetch(agentId, userQuery); + return delegate.prefetch(agentId, userQuery, ownerKey); } catch (Exception e) { meterRegistry.counter("memory.prefetch.failures", "provider", delegate.id()).increment(); diff --git a/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/RetryableMemoryProvider.java b/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/RetryableMemoryProvider.java index 6d88583c..fd99dd1c 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/RetryableMemoryProvider.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/spi/decorator/RetryableMemoryProvider.java @@ -20,10 +20,15 @@ public class RetryableMemoryProvider extends MemoryProviderDecorator { @Override public String prefetch(Long agentId, String userQuery) { + return prefetch(agentId, userQuery, null); + } + + @Override + public String prefetch(Long agentId, String userQuery, String ownerKey) { Exception lastException = null; for (int attempt = 1; attempt <= maxAttempts; attempt++) { try { - return delegate.prefetch(agentId, userQuery); + return delegate.prefetch(agentId, userQuery, ownerKey); } catch (Exception e) { lastException = e; if (attempt < maxAttempts) { diff --git a/mateclaw-server/src/main/java/vip/mate/memory/tool/StructuredMemoryTool.java b/mateclaw-server/src/main/java/vip/mate/memory/tool/StructuredMemoryTool.java index e26f8f09..be30b600 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/tool/StructuredMemoryTool.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/tool/StructuredMemoryTool.java @@ -4,9 +4,13 @@ import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.model.ToolContext; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.stereotype.Component; +import vip.mate.agent.context.ChatOrigin; +import vip.mate.memory.MemoryProperties; +import vip.mate.memory.identity.MemoryOwnerResolver; import vip.mate.memory.service.StructuredMemoryService; import java.util.List; @@ -28,6 +32,22 @@ import java.util.Map; public class StructuredMemoryTool { private final StructuredMemoryService structuredMemoryService; + private final MemoryOwnerResolver memoryOwnerResolver; + private final MemoryProperties memoryProperties; + + /** Owner key for reads: the resolved requester (visibility = shared + own personal). */ + private String readOwner(ToolContext ctx) { + return memoryOwnerResolver.resolve(ChatOrigin.from(ctx)); + } + + /** + * Owner key for writes/deletes: the resolved requester only when per-owner + * isolation is active; otherwise null so the entry lands in the shared + * bucket rather than an un-read PERSONAL row. + */ + private String writeOwner(ToolContext ctx) { + return memoryProperties.isLifecycleMediatorEnabled() ? readOwner(ctx) : null; + } @Tool(description = """ 记住一条结构化信息到 Agent 的长期记忆。 @@ -43,7 +63,8 @@ public class StructuredMemoryTool { @ToolParam(description = "当前 Agent 的 ID") Long agentId, @ToolParam(description = "记忆类型：user / feedback / project / reference") String type, @ToolParam(description = "条目标识符（snake_case），例如 preferred_language") String key, - @ToolParam(description = "条目内容") String content) { + @ToolParam(description = "条目内容") String content, + ToolContext toolContext) { if (agentId == null || type == null || key == null || content == null) { return error("agentId, type, key, content 均不能为空"); @@ -51,7 +72,7 @@ public class StructuredMemoryTool { try { structuredMemoryService.remember(agentId, type.trim().toLowerCase(), - key.trim(), content.trim(), "agent"); + key.trim(), content.trim(), "agent", writeOwner(toolContext)); JSONObject result = new JSONObject(); result.set("success", true); @@ -75,7 +96,8 @@ public class StructuredMemoryTool { public String recall_structured( @ToolParam(description = "当前 Agent 的 ID") Long agentId, @ToolParam(description = "记忆类型过滤（可选）：user / feedback / project / reference", required = false) String type, - @ToolParam(description = "搜索关键词（可选），匹配 key 和内容", required = false) String keyword) { + @ToolParam(description = "搜索关键词（可选），匹配 key 和内容", required = false) String keyword, + ToolContext toolContext) { if (agentId == null) { return error("agentId 不能为空"); @@ -85,7 +107,8 @@ public class StructuredMemoryTool { List> results = structuredMemoryService.recall( agentId, type != null && !type.isBlank() ? type.trim().toLowerCase() : null, - keyword); + keyword, + readOwner(toolContext)); JSONObject result = new JSONObject(); result.set("agentId", agentId); @@ -107,7 +130,8 @@ public class StructuredMemoryTool { public String forget_structured( @ToolParam(description = "当前 Agent 的 ID") Long agentId, @ToolParam(description = "记忆类型：user / feedback / project / reference") String type, - @ToolParam(description = "要删除的条目标识符") String key) { + @ToolParam(description = "要删除的条目标识符") String key, + ToolContext toolContext) { if (agentId == null || type == null || key == null) { return error("agentId, type, key 均不能为空"); @@ -115,7 +139,7 @@ public class StructuredMemoryTool { try { boolean removed = structuredMemoryService.forget(agentId, - type.trim().toLowerCase(), key.trim()); + type.trim().toLowerCase(), key.trim(), writeOwner(toolContext)); JSONObject result = new JSONObject(); result.set("success", removed); diff --git a/mateclaw-server/src/main/java/vip/mate/memory/tool/UniversalMemoryTool.java b/mateclaw-server/src/main/java/vip/mate/memory/tool/UniversalMemoryTool.java index a9894c3a..4351735c 100644 --- a/mateclaw-server/src/main/java/vip/mate/memory/tool/UniversalMemoryTool.java +++ b/mateclaw-server/src/main/java/vip/mate/memory/tool/UniversalMemoryTool.java @@ -4,11 +4,15 @@ import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.model.ToolContext; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.context.ApplicationEventPublisher; import org.springframework.stereotype.Component; +import vip.mate.agent.context.ChatOrigin; +import vip.mate.memory.MemoryProperties; import vip.mate.memory.event.MemoryWriteEvent; +import vip.mate.memory.identity.MemoryOwnerResolver; import vip.mate.workspace.document.model.WorkspaceFileEntity; import vip.mate.workspace.document.WorkspaceFileService; @@ -41,6 +45,8 @@ public class UniversalMemoryTool { private final WorkspaceFileService workspaceFileService; private final ApplicationEventPublisher eventPublisher; + private final MemoryOwnerResolver memoryOwnerResolver; + private final MemoryProperties memoryProperties; @Tool(description = """ 将一条自由形式的经验或洞察追加到 Agent 的长期记忆 (MEMORY.md)。 @@ -51,17 +57,24 @@ public class UniversalMemoryTool { public String remember( @ToolParam(description = "当前 Agent 的 ID") Long agentId, @ToolParam(description = "要记住的内容（自由形式）") String content, - @ToolParam(description = "可选：来源上下文（skill 名 / conversation id）", required = false) String source) { + @ToolParam(description = "可选：来源上下文（skill 名 / conversation id）", required = false) String source, + ToolContext toolContext) { if (agentId == null) return error("agentId 不能为空"); if (content == null || content.isBlank()) return error("content 不能为空"); try { - WorkspaceFileEntity existing = workspaceFileService.getFile(agentId, MEMORY_FILENAME); + // Write to the requester's PERSONAL MEMORY.md when per-owner isolation + // is active; otherwise the shared file (so the note is not stranded + // in an un-read PERSONAL row). + String ownerKey = memoryProperties.isLifecycleMediatorEnabled() + ? memoryOwnerResolver.resolve(ChatOrigin.from(toolContext)) + : null; + WorkspaceFileEntity existing = workspaceFileService.getVisibleFile(agentId, MEMORY_FILENAME, ownerKey); String existingContent = existing != null && existing.getContent() != null ? existing.getContent() : ""; String updated = appendLesson(existingContent, content, source); - workspaceFileService.saveFile(agentId, MEMORY_FILENAME, updated); + workspaceFileService.saveVisibleFile(agentId, MEMORY_FILENAME, updated, ownerKey); // RFC-090 §14.3 — universal remember() targets MEMORY.md (the // canonical file), so this IS a MemoryWriteEvent. Skill-local diff --git a/mateclaw-server/src/main/java/vip/mate/skill/installer/GitSkillFetcher.java b/mateclaw-server/src/main/java/vip/mate/skill/installer/GitSkillFetcher.java index 51f9b020..907e5f78 100644 --- a/mateclaw-server/src/main/java/vip/mate/skill/installer/GitSkillFetcher.java +++ b/mateclaw-server/src/main/java/vip/mate/skill/installer/GitSkillFetcher.java @@ -1,6 +1,7 @@ package vip.mate.skill.installer; import lombok.extern.slf4j.Slf4j; +import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import vip.mate.skill.installer.model.SkillBundle; import vip.mate.skill.runtime.SkillFrontmatterParser; @@ -23,12 +24,27 @@ import java.util.concurrent.TimeUnit; @Component public class GitSkillFetcher { - private static final long CLONE_TIMEOUT_SECONDS = 60; + private static final long CLONE_TIMEOUT_SECONDS = 120; private final SkillFrontmatterParser frontmatterParser; - public GitSkillFetcher(SkillFrontmatterParser frontmatterParser) { + /** + * GitHub access token used when cloning private repositories. + * Resolution order: {@code mateclaw.skill.github-token} property → {@code GITHUB_TOKEN} + * environment variable → empty (public repos only). Kept as a plain field so the value + * is never logged or embedded in URLs — it is passed to the git subprocess through + * dedicated environment variables (see {@link #cloneRepo}). + */ + private final String githubToken; + + public GitSkillFetcher( + SkillFrontmatterParser frontmatterParser, + @Value("${mateclaw.skill.github-token:}") String configuredGithubToken) { this.frontmatterParser = frontmatterParser; + String token = (configuredGithubToken != null && !configuredGithubToken.isBlank()) + ? configuredGithubToken + : System.getenv("GITHUB_TOKEN"); + this.githubToken = (token == null) ? "" : token.trim(); } /** @@ -98,7 +114,13 @@ public class GitSkillFetcher { } /** - * git clone --depth 1 到临时目录 + * git clone --depth 1 to a temporary directory. + *

+ * When a GitHub token is configured and the repository is hosted on github.com, + * the credential is forwarded to the git subprocess through {@code GIT_CONFIG_*} + * environment variables — equivalent to {@code git -c http.extraHeader=...} but + * without ever placing the token in the process command line (visible to {@code ps}) + * or the repository URL (visible in logs and error messages). Requires git 2.31+. */ private void cloneRepo(String repoUrl, String ref, Path targetDir) throws IOException, InterruptedException { var command = new java.util.ArrayList(); @@ -115,6 +137,19 @@ public class GitSkillFetcher { ProcessBuilder pb = new ProcessBuilder(command); pb.redirectErrorStream(true); + + // Inject credentials for private GitHub repos via the git subprocess environment. + // Keeping the token out of argv and out of the URL ensures it cannot leak through + // process listings, the INFO log below, or the IOException message on clone failure. + if (!githubToken.isEmpty() && isGithubHost(repoUrl)) { + var env = pb.environment(); + env.put("GIT_CONFIG_COUNT", "1"); + env.put("GIT_CONFIG_KEY_0", "http.extraHeader"); + env.put("GIT_CONFIG_VALUE_0", "Authorization: Bearer " + githubToken); + // Fail fast on auth errors instead of blocking on an interactive password prompt. + env.put("GIT_TERMINAL_PROMPT", "0"); + } + Process process = pb.start(); boolean finished = process.waitFor(CLONE_TIMEOUT_SECONDS, TimeUnit.SECONDS); @@ -132,6 +167,17 @@ public class GitSkillFetcher { log.info("Cloned {} (ref={}) to {}", repoUrl, ref, targetDir); } + /** + * Match GitHub host conservatively (scheme + host boundary) so a malicious URL like + * {@code https://evil.com/?u=github.com/...} cannot smuggle the token to a third party. + */ + private static boolean isGithubHost(String repoUrl) { + return repoUrl != null + && (repoUrl.startsWith("https://github.com/") + || repoUrl.startsWith("http://github.com/") + || repoUrl.startsWith("git@github.com:")); + } + /** * 在 skill 根目录中定位 SKILL.md */ diff --git a/mateclaw-server/src/main/java/vip/mate/skill/workspace/SkillWorkspaceAutoConfiguration.java b/mateclaw-server/src/main/java/vip/mate/skill/workspace/SkillWorkspaceAutoConfiguration.java index 796293fc..e6241905 100644 --- a/mateclaw-server/src/main/java/vip/mate/skill/workspace/SkillWorkspaceAutoConfiguration.java +++ b/mateclaw-server/src/main/java/vip/mate/skill/workspace/SkillWorkspaceAutoConfiguration.java @@ -3,6 +3,7 @@ package vip.mate.skill.workspace; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.context.annotation.Configuration; import vip.mate.skill.installer.SkillHubProperties; +import vip.mate.tool.guard.WorkspacePathGuard; /** * Skill 工作区与安装器自动配置 @@ -12,4 +13,15 @@ import vip.mate.skill.installer.SkillHubProperties; @Configuration @EnableConfigurationProperties({SkillWorkspaceProperties.class, SkillHubProperties.class}) public class SkillWorkspaceAutoConfiguration { + + /** + * Register the shared skill repository root with the workspace path sandbox. + * Skills are shared across all workspaces and live outside any single + * workspace directory, so the sandbox must trust their root in addition to + * the active workspace — otherwise reading or running a skill's files from a + * workspace configured elsewhere is rejected as a boundary violation. + */ + public SkillWorkspaceAutoConfiguration(SkillWorkspaceProperties skillWorkspaceProperties) { + WorkspacePathGuard.setSkillRoot(skillWorkspaceProperties.getRoot()); + } } diff --git a/mateclaw-server/src/main/java/vip/mate/tool/builtin/DocumentExtractTool.java b/mateclaw-server/src/main/java/vip/mate/tool/builtin/DocumentExtractTool.java index b3fc54e2..4763ab9b 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/builtin/DocumentExtractTool.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/builtin/DocumentExtractTool.java @@ -3,14 +3,15 @@ package vip.mate.tool.builtin; import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.model.ToolContext; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; +import org.springframework.lang.Nullable; import org.springframework.stereotype.Component; import java.io.*; import java.nio.file.Files; import java.nio.file.Path; -import java.nio.file.Paths; import java.util.ArrayList; import java.util.List; import java.util.concurrent.TimeUnit; @@ -69,14 +70,28 @@ public class DocumentExtractTool { """) public String extract_document_text( @ToolParam(description = "文件的绝对路径或相对路径") String filePath, - @ToolParam(description = "可选参数 JSON，如 {\"pages\": \"1-5\", \"method\": \"tika\"}", required = false) String options) { + @ToolParam(description = "可选参数 JSON，如 {\"pages\": \"1-5\", \"method\": \"tika\"}", required = false) String options, + // RFC-063r §2.5: hidden from LLM by JsonSchemaGenerator. Carries the + // ChatOrigin so the workspace boundary check honors per-agent basePath. + @Nullable ToolContext ctx) { JSONObject result = new JSONObject(); result.set("filePath", filePath); List attempts = new ArrayList<>(); try { - Path path = Paths.get(filePath).toAbsolutePath().normalize(); + Path path; + try { + path = vip.mate.tool.guard.WorkspacePathGuard.validatePath(filePath, ctx); + } catch (IllegalArgumentException e) { + // Sandbox rejected the literal path. Try chat-upload basename + // resolution before surfacing the boundary error. + Path attachment = ChatUploadResolver.resolve(filePath); + if (attachment == null) { + return errorResult(filePath, e.getMessage(), attempts); + } + path = attachment; + } if (!Files.exists(path)) { // The user-uploaded chat attachment is rendered to the LLM as @@ -185,10 +200,11 @@ public class DocumentExtractTool { """) public String extract_pdf_text( @ToolParam(description = "PDF 文件的绝对路径或相对路径") String filePath, - @ToolParam(description = "页码范围，如 \"1-5\" 或 \"1,3,5\"", required = false) String pages) { + @ToolParam(description = "页码范围，如 \"1-5\" 或 \"1,3,5\"", required = false) String pages, + @Nullable ToolContext ctx) { String options = pages != null ? "{\"pages\": \"" + pages + "\"}" : null; - return extract_document_text(filePath, options); + return extract_document_text(filePath, options, ctx); } @Tool(description = """ @@ -201,8 +217,9 @@ public class DocumentExtractTool { 支持 .docx 和 .doc 格式 """) public String extract_docx_text( - @ToolParam(description = "Word 文档的绝对路径或相对路径") String filePath) { - return extract_document_text(filePath, null); + @ToolParam(description = "Word 文档的绝对路径或相对路径") String filePath, + @Nullable ToolContext ctx) { + return extract_document_text(filePath, null, ctx); } // ==================== PDF 提取链 ==================== diff --git a/mateclaw-server/src/main/java/vip/mate/tool/builtin/FileTypeDetectorTool.java b/mateclaw-server/src/main/java/vip/mate/tool/builtin/FileTypeDetectorTool.java index b423e6be..84d273f7 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/builtin/FileTypeDetectorTool.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/builtin/FileTypeDetectorTool.java @@ -3,8 +3,10 @@ package vip.mate.tool.builtin; import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.model.ToolContext; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; +import org.springframework.lang.Nullable; import org.springframework.stereotype.Component; import java.io.BufferedReader; @@ -12,7 +14,6 @@ import java.io.IOException; import java.io.InputStreamReader; import java.nio.file.Files; import java.nio.file.Path; -import java.nio.file.Paths; import java.util.concurrent.TimeUnit; /** @@ -41,13 +42,28 @@ public class FileTypeDetectorTool { 注意：对于 .docx/.pdf 等文档，不会返回 read_file，而是 extract_document_text """) public String detect_file_type( - @ToolParam(description = "文件的绝对路径或相对路径") String filePath) { + @ToolParam(description = "文件的绝对路径或相对路径") String filePath, + // RFC-063r §2.5: hidden from LLM by JsonSchemaGenerator. Carries the + // ChatOrigin so the workspace boundary check honors per-agent basePath. + @Nullable ToolContext ctx) { JSONObject result = new JSONObject(); result.set("filePath", filePath); try { - Path path = Paths.get(filePath).toAbsolutePath().normalize(); + Path path; + try { + path = vip.mate.tool.guard.WorkspacePathGuard.validatePath(filePath, ctx); + } catch (IllegalArgumentException e) { + // Sandbox rejected the literal path. Fall back to chat-upload + // basename matching before surfacing the boundary error — the + // LLM may have hallucinated a system path for a real attachment. + Path attachment = ChatUploadResolver.resolve(filePath); + if (attachment == null) { + return errorResult(filePath, e.getMessage()); + } + path = attachment; + } if (!Files.exists(path)) { // Fall back to chat-upload basename matching for filenames that were diff --git a/mateclaw-server/src/main/java/vip/mate/tool/builtin/GoalManagementTool.java b/mateclaw-server/src/main/java/vip/mate/tool/builtin/GoalManagementTool.java index 9b61bdcd..94195a1c 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/builtin/GoalManagementTool.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/builtin/GoalManagementTool.java @@ -58,8 +58,12 @@ public class GoalManagementTool { required = false) String exitCriteria, @ToolParam(description = "Max evaluation turns before exhaustion. Default 20.", required = false) Integer turnBudget, - @ToolParam(description = "If true, the agent may auto-followup when progress is incomplete. Default false.", + @ToolParam(description = "If true, the agent may auto-followup when progress is incomplete. " + + "Omit to use the system default.", required = false) Boolean autoFollowup, + @ToolParam(description = "Optional initial checklist: a list of short, individually verifiable " + + "acceptance criteria. Omit to let the system derive the checklist on first evaluation.", + required = false) java.util.List criteria, @Nullable ToolContext ctx) { if (!properties.isEnabled()) { @@ -86,6 +90,16 @@ public class GoalManagementTool { req.setExitCriteria(exitCriteria); if (turnBudget != null) req.setTurnBudget(turnBudget); if (autoFollowup != null) req.setAutoFollowupEnabled(autoFollowup); + if (criteria != null && !criteria.isEmpty()) { + java.util.List items = new java.util.ArrayList<>(); + for (String text : criteria) { + if (text != null && !text.isBlank()) { + // Only text matters; create() assigns ids, forces passed=false, clears evidence. + items.add(new vip.mate.goal.model.GoalCriterion("", text.trim(), false, "")); + } + } + if (!items.isEmpty()) req.setCriteria(items); + } String username = origin.requesterId() != null && !origin.requesterId().isBlank() ? origin.requesterId() : "system"; @@ -132,10 +146,14 @@ public class GoalManagementTool { } @Tool(description = """ - Explicitly mark the active goal as completed. Use ONLY when all \ - exit criteria are satisfied (e.g. tests passed, feature deployed, \ - user confirmed). The runtime evaluator will also mark goals \ - completed automatically when score >= 0.95 — prefer that path.""") + Explicitly mark the active goal as completed. Use ONLY when EVERY \ + checklist criterion is genuinely satisfied with concrete evidence \ + in the conversation (e.g. tests actually passed, feature actually \ + deployed, user confirmed). Do NOT call this to close out work that \ + is unfinished, blocked, or impossible. In normal operation you do \ + not need this tool at all: the runtime evaluator marks the goal \ + completed automatically once all checklist criteria pass — prefer \ + that path and just keep working.""") public String completeGoal(@Nullable ToolContext ctx) { if (!properties.isEnabled()) return errorJson("Goal subsystem is disabled"); GoalEntity goal = resolveActive(ctx); @@ -145,7 +163,8 @@ public class GoalManagementTool { // Synthesize a completion-style evaluation result for the audit trail. GoalEvaluationResult synthetic = new GoalEvaluationResult( 1.0, "completed by agent", GoalEvaluationResult.DECISION_COMPLETED, - true, "manual", 0, 0L); + true, "manual", 0, 0L, + java.util.List.of(), null); try { GoalEntity completed = goalService.markCompleted(goal.getId(), synthetic); // Broadcast a goal_completed event with the same shape as the @@ -154,7 +173,8 @@ public class GoalManagementTool { if (streamTracker != null && completed.getConversationId() != null) { streamTracker.broadcastObject(completed.getConversationId(), "goal_completed", Map.of( "goalId", String.valueOf(completed.getId()), - "score", synthetic.score())); + "score", synthetic.score(), + "goal", goalService.toResponse(completed))); } return successJson(Map.of( "goalId", String.valueOf(completed.getId()), @@ -232,7 +252,7 @@ public class GoalManagementTool { streamTracker.broadcastObject(conversationId, eventName, Map.of( "goalId", String.valueOf(goal.getId()), "conversationId", conversationId, - "goal", goal)); + "goal", goalService.toResponse(goal))); } catch (Exception e) { log.debug("[GoalManagementTool] broadcast {} failed: {}", eventName, e.getMessage()); } diff --git a/mateclaw-server/src/main/java/vip/mate/tool/builtin/ShellExecuteTool.java b/mateclaw-server/src/main/java/vip/mate/tool/builtin/ShellExecuteTool.java index 8475f969..aff0298a 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/builtin/ShellExecuteTool.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/builtin/ShellExecuteTool.java @@ -3,8 +3,10 @@ package vip.mate.tool.builtin; import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.model.ToolContext; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; +import org.springframework.lang.Nullable; import org.springframework.stereotype.Component; import java.io.IOException; @@ -51,7 +53,10 @@ public class ShellExecuteTool { + "Dangerous operations trigger security approval. Returns structured result with exitCode, stdout, stderr, timedOut.") public String execute_shell_command( @ToolParam(description = "Shell command to execute") String command, - @ToolParam(description = "Timeout in seconds, default 60", required = false) Integer timeoutSeconds) { + @ToolParam(description = "Timeout in seconds, default 60", required = false) Integer timeoutSeconds, + // RFC-063r §2.5: hidden from LLM by JsonSchemaGenerator. Carries the + // ChatOrigin so the workspace boundary check honors per-agent basePath. + @Nullable ToolContext ctx) { int timeout = (timeoutSeconds != null && timeoutSeconds > 0) ? timeoutSeconds : DEFAULT_TIMEOUT_SECONDS; // 硬上限：不允许超过 300 秒 @@ -63,6 +68,21 @@ public class ShellExecuteTool { JSONObject result = new JSONObject(); result.set("command", command); + // Enforce the workspace boundary on the command string itself before + // the process starts. The pb.directory() set later only constrains + // the CWD — absolute paths in the command would still reach anywhere. + try { + vip.mate.tool.guard.WorkspacePathGuard.validateShellCommand(command, ctx); + } catch (IllegalArgumentException e) { + log.warn("[ShellExecute] Sandbox rejected command: {}", e.getMessage()); + result.set("exitCode", -1); + result.set("stdout", ""); + result.set("stderr", e.getMessage()); + result.set("timedOut", false); + result.set("error", e.getMessage()); + return JSONUtil.toJsonPrettyStr(result); + } + Path stdoutFile = null; Path stderrFile = null; @@ -71,7 +91,7 @@ public class ShellExecuteTool { // Windows cmd.exe 会在第一个换行处截断命令，Unix sh 也可能误解 String sanitizedCommand = collapseEmbeddedNewlines(command); - ProcessBuilder pb = buildShellProcess(sanitizedCommand); + ProcessBuilder pb = buildShellProcess(sanitizedCommand, ctx); // 不继承环境变量中的敏感信息 pb.environment().keySet().removeIf(key -> key.contains("KEY") || key.contains("SECRET") || key.contains("TOKEN") @@ -137,7 +157,7 @@ public class ShellExecuteTool { * from the calling environment still apply; falls back to /bin/sh * when $SHELL is unset or points at a non-executable path. */ - private static ProcessBuilder buildShellProcess(String command) { + private static ProcessBuilder buildShellProcess(String command, @Nullable ToolContext ctx) { ProcessBuilder pb; if (IS_WINDOWS) { String winCommand = sanitizeWindowsCommand(command); @@ -147,8 +167,13 @@ public class ShellExecuteTool { pb = new ProcessBuilder(shell, "-c", command); } - // 设置工作区活动目录 - java.nio.file.Path workingDir = vip.mate.tool.guard.WorkspacePathGuard.getWorkingDirectory(); + // Pin the process cwd to the same workspace basePath the validator + // checked against. Using getWorkingDirectory(ctx) (not the no-arg + // ThreadLocal-only overload) keeps validation and execution on a + // single source of truth — otherwise a caller that only sets + // ToolContext could validate against one basePath and run with the + // ThreadLocal fallback's basePath. + java.nio.file.Path workingDir = vip.mate.tool.guard.WorkspacePathGuard.getWorkingDirectory(ctx); if (workingDir != null && java.nio.file.Files.isDirectory(workingDir)) { pb.directory(workingDir.toFile()); log.info("[ShellExecute] Working directory set to: {}", workingDir); diff --git a/mateclaw-server/src/main/java/vip/mate/tool/builtin/WebSearchTool.java b/mateclaw-server/src/main/java/vip/mate/tool/builtin/WebSearchTool.java index 213634d7..95981389 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/builtin/WebSearchTool.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/builtin/WebSearchTool.java @@ -21,7 +21,12 @@ public class WebSearchTool { private final WebSearchService webSearchService; - @Tool(description = "Search the internet for latest information. Use when querying real-time news, latest data, or uncertain facts. " + // Tool name is pinned to "web_search" rather than the method-derived "search": + // DashScope's native protocol reserves the function name "search" and rejects the + // whole request with "InvalidParameter: Tool names are not allowed to be [search]", + // which breaks tool use for every qwen/DashScope-native model that has this tool bound. + @Tool(name = "web_search", + description = "Search the internet for latest information. Use when querying real-time news, latest data, or uncertain facts. " + "Supports optional freshness, language, count parameters.") public String search( @ToolParam(description = "Search keywords") String query, diff --git a/mateclaw-server/src/main/java/vip/mate/tool/builtin/WorkspaceMemoryTool.java b/mateclaw-server/src/main/java/vip/mate/tool/builtin/WorkspaceMemoryTool.java index cfe453c4..3c2e28c1 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/builtin/WorkspaceMemoryTool.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/builtin/WorkspaceMemoryTool.java @@ -5,9 +5,13 @@ import cn.hutool.json.JSONObject; import cn.hutool.json.JSONUtil; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.model.ToolContext; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.stereotype.Component; +import vip.mate.agent.context.ChatOrigin; +import vip.mate.memory.MemoryProperties; +import vip.mate.memory.identity.MemoryOwnerResolver; import vip.mate.memory.service.MemoryRecallTracker; import vip.mate.workspace.document.MemorySearchHit; import vip.mate.workspace.document.WorkspaceFileService; @@ -32,6 +36,22 @@ public class WorkspaceMemoryTool { private final WorkspaceFileService workspaceFileService; private final MemoryRecallTracker memoryRecallTracker; + private final MemoryOwnerResolver memoryOwnerResolver; + private final MemoryProperties memoryProperties; + + /** Owner key for reads: always the resolved requester (visibility = shared + own personal). */ + private String readOwner(ToolContext ctx) { + return memoryOwnerResolver.resolve(ChatOrigin.from(ctx)); + } + + /** + * Owner key for writes: the resolved requester only when per-owner isolation + * is active (lifecycle prefetch on); otherwise null so the write lands in + * the shared bucket and is not stranded in an un-read PERSONAL row. + */ + private String writeOwner(ToolContext ctx) { + return memoryProperties.isLifecycleMediatorEnabled() ? readOwner(ctx) : null; + } @Tool(description = """ 列出指定 Agent 的数据库工作区记忆文件。 @@ -40,13 +60,14 @@ public class WorkspaceMemoryTool { """) public String list_workspace_memory_files( @ToolParam(description = "当前 Agent 的 ID") Long agentId, - @ToolParam(description = "可选：按文件名前缀过滤，例如 memory/ 或 MEM", required = false) String filenamePrefix) { + @ToolParam(description = "可选：按文件名前缀过滤，例如 memory/ 或 MEM", required = false) String filenamePrefix, + ToolContext toolContext) { if (agentId == null) { return error("agentId 不能为空"); } - List files = workspaceFileService.listFiles(agentId).stream() + List files = workspaceFileService.listVisibleFiles(agentId, readOwner(toolContext)).stream() .filter(file -> filenamePrefix == null || filenamePrefix.isBlank() || (file.getFilename() != null && file.getFilename().startsWith(filenamePrefix))) .sorted(Comparator @@ -78,14 +99,15 @@ public class WorkspaceMemoryTool { """) public String read_workspace_memory_file( @ToolParam(description = "当前 Agent 的 ID") Long agentId, - @ToolParam(description = "工作区文件名，例如 MEMORY.md、PROFILE.md、memory/2026-03-31.md") String filename) { + @ToolParam(description = "工作区文件名，例如 MEMORY.md、PROFILE.md、memory/2026-03-31.md") String filename, + ToolContext toolContext) { String validation = validate(agentId, filename); if (validation != null) { return error(validation); } - WorkspaceFileEntity file = workspaceFileService.getFile(agentId, filename); + WorkspaceFileEntity file = workspaceFileService.getVisibleFile(agentId, filename, readOwner(toolContext)); if (file == null) { return error("工作区文件不存在: " + filename); } @@ -116,15 +138,17 @@ public class WorkspaceMemoryTool { public String write_workspace_memory_file( @ToolParam(description = "当前 Agent 的 ID") Long agentId, @ToolParam(description = "工作区文件名，例如 MEMORY.md、PROFILE.md、memory/2026-03-31.md") String filename, - @ToolParam(description = "要写入的完整 Markdown 内容") String content) { + @ToolParam(description = "要写入的完整 Markdown 内容") String content, + ToolContext toolContext) { String validation = validate(agentId, filename); if (validation != null) { return error(validation); } - WorkspaceFileEntity before = workspaceFileService.getFile(agentId, filename); - WorkspaceFileEntity saved = workspaceFileService.saveFile(agentId, filename, content != null ? content : ""); + String ownerKey = writeOwner(toolContext); + WorkspaceFileEntity before = workspaceFileService.getVisibleFile(agentId, filename, ownerKey); + WorkspaceFileEntity saved = workspaceFileService.saveVisibleFile(agentId, filename, content != null ? content : "", ownerKey); JSONObject result = new JSONObject(); result.set("agentId", agentId); @@ -149,7 +173,8 @@ public class WorkspaceMemoryTool { @ToolParam(description = "工作区文件名，例如 MEMORY.md、PROFILE.md、memory/2026-03-31.md") String filename, @ToolParam(description = "要查找的原始文本，要求精确匹配") String oldText, @ToolParam(description = "替换后的新文本") String newText, - @ToolParam(description = "是否替换全部匹配项，默认 false", required = false) Boolean replaceAll) { + @ToolParam(description = "是否替换全部匹配项，默认 false", required = false) Boolean replaceAll, + ToolContext toolContext) { String validation = validate(agentId, filename); if (validation != null) { @@ -165,7 +190,8 @@ public class WorkspaceMemoryTool { return error("oldText 和 newText 相同，无需替换"); } - WorkspaceFileEntity existing = workspaceFileService.getFile(agentId, filename); + String ownerKey = writeOwner(toolContext); + WorkspaceFileEntity existing = workspaceFileService.getVisibleFile(agentId, filename, ownerKey); if (existing == null) { return error("工作区文件不存在: " + filename); } @@ -187,7 +213,7 @@ public class WorkspaceMemoryTool { replacements = 1; } - workspaceFileService.saveFile(agentId, filename, updated); + workspaceFileService.saveVisibleFile(agentId, filename, updated, ownerKey); JSONObject result = new JSONObject(); result.set("agentId", agentId); @@ -211,7 +237,8 @@ public class WorkspaceMemoryTool { @ToolParam(description = "关键词或短语，2-64 字符") String query, @ToolParam(description = "搜索范围：all（全部）/ memory（MEMORY.md 与 memory/）/ profile / persona，默认 all", required = false) String scope, - @ToolParam(description = "返回的最大命中数，默认 10，上限 30", required = false) Integer limit) { + @ToolParam(description = "返回的最大命中数，默认 10，上限 30", required = false) Integer limit, + ToolContext toolContext) { if (agentId == null) { return error("agentId 不能为空"); @@ -230,8 +257,11 @@ public class WorkspaceMemoryTool { int effectiveLimit = limit == null ? 10 : Math.min(Math.max(limit, 1), 30); Set prefixes = resolveScope(scope); + // Restrict hits to memory the current requester may see: shared memory + // plus this owner's PERSONAL memory only. + String ownerKey = readOwner(toolContext); List hits = workspaceFileService.searchSnippets( - agentId, trimmed, prefixes, effectiveLimit); + agentId, trimmed, prefixes, effectiveLimit, ownerKey); // Treat each unique file in the results as an active retrieval signal — // boosts that file's weight in the dream-consolidation ranker the same @@ -239,7 +269,9 @@ public class WorkspaceMemoryTool { Set retrieved = new HashSet<>(); for (MemorySearchHit hit : hits) { if (retrieved.add(hit.filename())) { - WorkspaceFileEntity file = workspaceFileService.getFile(agentId, hit.filename()); + // Read the same visible row the hit came from (the owner's + // PERSONAL row when present) so PERSONAL hits track correctly. + WorkspaceFileEntity file = workspaceFileService.getVisibleFile(agentId, hit.filename(), ownerKey); if (file != null && file.getContent() != null) { memoryRecallTracker.trackActiveRetrieval(agentId, hit.filename(), file.getContent()); } diff --git a/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileCache.java b/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileCache.java index 35ad1756..e539eda4 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileCache.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileCache.java @@ -1,34 +1,66 @@ package vip.mate.tool.document; import lombok.extern.slf4j.Slf4j; +import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Component; +import java.io.IOException; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; import java.time.Duration; +import java.util.Base64; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.Map; import java.util.Optional; import java.util.UUID; -import java.util.concurrent.ConcurrentHashMap; import java.util.regex.Matcher; import java.util.regex.Pattern; +import java.util.stream.Stream; /** - * In-memory cache of bytes produced by tools (e.g. {@code DocxRenderTool}) and - * served by {@link GeneratedFileController}. Entries expire after {@link #TTL} - * and are evicted lazily on every {@link #put} call. + * Store of bytes produced by tools (e.g. {@code DocxRenderTool}) and served by + * {@link GeneratedFileController}. Each entry is written to disk under + * {@link #DEFAULT_STORAGE_DIR} and mirrored in an in-memory map for fast reads. * - *

The cache is process-local and intentionally not persisted: a JVM restart - * invalidates all outstanding download links. The download URL embeds a random - * {@link UUID}, which acts as the only access credential. + *

Persistence is what makes download links durable: the bytes survive both + * cache eviction and a JVM restart, so a link a user clicks minutes — or days — + * after generation still resolves instead of 404ing. Entries are retained for + * {@link #TTL} and a scheduled sweep removes expired files. The download URL + * embeds a random {@link UUID}, which acts as the only access credential. */ @Slf4j @Component public class GeneratedFileCache { - public static final Duration TTL = Duration.ofMinutes(10); + /** How long a generated file remains downloadable after creation. */ + public static final Duration TTL = Duration.ofDays(7); + + /** Default on-disk location for persisted generated files. */ + public static final Path DEFAULT_STORAGE_DIR = Paths.get("data", "generated-files"); + + /** How often the expired-file sweep runs (6 hours). Must be a compile-time + * constant for use in {@link Scheduled#fixedDelay()}. */ + private static final long CLEANUP_INTERVAL_MS = 6L * 60 * 60 * 1000; + + /** Guards path resolution: only server-issued UUID-shaped ids are accepted. */ + private static final Pattern ID_RE = Pattern.compile("[a-zA-Z0-9-]{1,64}"); + + private static final String META_SUFFIX = ".meta"; /** - * URL pattern for in-memory generated files served by - * {@code GeneratedFileController}. Public so channel adapters and graph - * nodes share a single source of truth. + * Upper bound on bytes held in memory. Disk is the source of truth and + * retains entries for {@link #TTL}; this map is only a hot-read cache, so + * capping it keeps heap bounded regardless of how many files are produced + * within the retention window. A miss simply reloads from disk. + */ + private static final int MAX_MEMORY_ENTRIES = 256; + + /** + * URL pattern for generated files served by {@code GeneratedFileController}. + * Public so channel adapters and graph nodes share a single source of truth. */ public static final Pattern GENERATED_URL_PATTERN = Pattern.compile("/api/v1/files/generated/([a-zA-Z0-9-]+)"); @@ -41,7 +73,37 @@ public class GeneratedFileCache { public static final String MISSING_REFERENCE_NOTICE = "⚠️ 文件未真正生成（模型未调用文档生成工具），请重新发送请求"; - private final ConcurrentHashMap entries = new ConcurrentHashMap<>(); + private final Path storageDir; + + /** + * Access-ordered LRU bounded to {@link #MAX_MEMORY_ENTRIES}: the eldest + * entry is dropped from memory once the cap is exceeded (the persisted + * file stays on disk and is reloaded on the next read). + */ + private final Map entries = Collections.synchronizedMap( + new LinkedHashMap<>(16, 0.75f, true) { + // Fully qualify the value type: inside a LinkedHashMap subclass the + // inherited java.util.HashMap.Entry node type shadows the outer + // GeneratedFileCache.Entry record, so a bare `Entry` here resolves to + // the raw Map.Entry and the override silently fails to match. + @Override + protected boolean removeEldestEntry(Map.Entry eldest) { + return size() > MAX_MEMORY_ENTRIES; + } + }); + + public GeneratedFileCache() { + this(DEFAULT_STORAGE_DIR); + } + + public GeneratedFileCache(Path storageDir) { + this.storageDir = storageDir.normalize(); + try { + Files.createDirectories(this.storageDir); + } catch (IOException e) { + log.warn("Could not create generated-files dir {}: {}", this.storageDir, e.toString()); + } + } public record Entry(byte[] bytes, String filename, String mimeType, long expireAt) { @@ -56,41 +118,133 @@ public class GeneratedFileCache { * {@code /api/v1/files/generated/{id}}. */ public String put(byte[] bytes, String filename, String mimeType) { - evictExpired(); String id = UUID.randomUUID().toString(); long expireAt = System.currentTimeMillis() + TTL.toMillis(); - entries.put(id, new Entry(bytes, filename, mimeType, expireAt)); - log.debug("Cached generated file id={} filename={} bytes={}", id, filename, bytes.length); + Entry entry = new Entry(bytes, filename, mimeType, expireAt); + entries.put(id, entry); + persist(id, entry); + log.debug("Cached generated file id={} filename={} bytes={}", id, filename, + bytes != null ? bytes.length : 0); return id; } /** - * Look up an entry. Returns {@link Optional#empty()} if missing or expired - * (expired entries are removed as a side-effect). + * Look up an entry. Returns {@link Optional#empty()} if missing or expired. + * Falls back to disk on an in-memory miss so links survive eviction and + * JVM restarts; expired entries are removed as a side-effect. */ public Optional get(String id) { + if (id == null || !ID_RE.matcher(id).matches()) { + return Optional.empty(); + } Entry entry = entries.get(id); + if (entry == null) { + entry = loadFromDisk(id); + if (entry != null) { + entries.put(id, entry); + } + } if (entry == null) { return Optional.empty(); } if (entry.expired()) { - entries.remove(id, entry); + evict(id); return Optional.empty(); } return Optional.of(entry); } - private void evictExpired() { + private void persist(String id, Entry entry) { + if (entry.bytes() == null) { + return; + } + try { + Files.write(storageDir.resolve(id), entry.bytes()); + // expireAt \t mimeType \t base64(filename) — filename is base64-encoded + // so arbitrary unicode / separators round-trip without escaping. + String meta = entry.expireAt() + + "\t" + (entry.mimeType() == null ? "" : entry.mimeType()) + + "\t" + Base64.getEncoder().encodeToString( + (entry.filename() == null ? "" : entry.filename()).getBytes(StandardCharsets.UTF_8)); + Files.writeString(storageDir.resolve(id + META_SUFFIX), meta); + } catch (IOException e) { + // Best-effort: an in-memory entry still serves the current process. + log.warn("Could not persist generated file id={}: {}", id, e.toString()); + } + } + + private Entry loadFromDisk(String id) { + Path bin = storageDir.resolve(id).normalize(); + Path meta = storageDir.resolve(id + META_SUFFIX).normalize(); + // Containment guard — id is already validated, this is defence in depth. + if (!bin.startsWith(storageDir) || !Files.isRegularFile(bin) || !Files.isRegularFile(meta)) { + return null; + } + try { + String[] parts = Files.readString(meta).split("\t", 3); + long expireAt = Long.parseLong(parts[0].trim()); + String mimeType = parts.length > 1 && !parts[1].isEmpty() ? parts[1] : null; + String filename = parts.length > 2 && !parts[2].isEmpty() + ? new String(Base64.getDecoder().decode(parts[2]), StandardCharsets.UTF_8) + : id; + byte[] bytes = Files.readAllBytes(bin); + return new Entry(bytes, filename, mimeType, expireAt); + } catch (Exception e) { + log.warn("Could not load generated file id={}: {}", id, e.toString()); + return null; + } + } + + private void evict(String id) { + entries.remove(id); + try { + Files.deleteIfExists(storageDir.resolve(id)); + Files.deleteIfExists(storageDir.resolve(id + META_SUFFIX)); + } catch (IOException e) { + log.debug("Could not delete generated file id={}: {}", id, e.toString()); + } + } + + /** + * Drop expired entries from memory and disk. Runs on a fixed delay; also + * sweeps orphaned files left by an unclean shutdown. + */ + @Scheduled(fixedDelay = CLEANUP_INTERVAL_MS, initialDelay = CLEANUP_INTERVAL_MS) + public void cleanupExpired() { long now = System.currentTimeMillis(); - entries.entrySet().removeIf(e -> e.getValue().expireAt() <= now); + // entrySet() of a synchronizedMap must be iterated while holding its lock. + synchronized (entries) { + entries.entrySet().removeIf(e -> e.getValue().expireAt() <= now); + } + if (!Files.isDirectory(storageDir)) { + return; + } + try (Stream files = Files.list(storageDir)) { + files.filter(p -> p.getFileName().toString().endsWith(META_SUFFIX)) + .forEach(metaPath -> { + String name = metaPath.getFileName().toString(); + String id = name.substring(0, name.length() - META_SUFFIX.length()); + try { + long expireAt = Long.parseLong( + Files.readString(metaPath).split("\t", 2)[0].trim()); + if (expireAt <= now) { + evict(id); + } + } catch (Exception e) { + log.debug("Skipping unreadable meta {}: {}", name, e.toString()); + } + }); + } catch (IOException e) { + log.warn("Generated-files cleanup sweep failed: {}", e.toString()); + } } /** * Replace any {@code /api/v1/files/generated/{id}} URL in {@code text} - * whose id is NOT present (or has expired) in this cache with - * {@link #MISSING_REFERENCE_NOTICE}. URLs whose ids ARE in the cache are - * left intact so downstream channel adapters can still rewrite them - * into native attachments. + * whose id is NOT present (or has expired) with + * {@link #MISSING_REFERENCE_NOTICE}. URLs whose ids ARE live are left + * intact so downstream channel adapters can still rewrite them into + * native attachments. * *

Cache misses are nearly always LLM hallucinations — the model * emitted a UUID-shaped string without ever calling a render tool. @@ -107,8 +261,7 @@ public class GeneratedFileCache { m.reset(); while (m.find()) { String id = m.group(1); - Entry entry = entries.get(id); - boolean live = entry != null && !entry.expired(); + boolean live = get(id).isPresent(); String replacement = live ? m.group(0) : MISSING_REFERENCE_NOTICE; m.appendReplacement(out, Matcher.quoteReplacement(replacement)); } diff --git a/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileLink.java b/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileLink.java index a3eb8902..f8378cec 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileLink.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/document/GeneratedFileLink.java @@ -23,7 +23,8 @@ public final class GeneratedFileLink { public static String resultZh(byte[] bytes, String displayName, String mimeType, GeneratedFileCache cache, String typeLabel) { String url = stash(bytes, displayName, mimeType, cache); - return typeLabel + "已生成：[" + displayName + "](" + url + ")（链接 10 分钟内有效）。\n" + return typeLabel + "已生成：[" + displayName + "](" + url + ")（链接 " + + GeneratedFileCache.TTL.toDays() + " 天内有效）。\n" + "重要：回答用户时**必须**使用上述 markdown 链接格式 [" + displayName + "](" + url + ")，" + "保持相对路径原样，**不要**用反引号包裹路径，也**不要**添加任何 https://、http:// 域名前缀。"; } @@ -44,7 +45,8 @@ public final class GeneratedFileLink { String prefix = sourceFileCount > 1 ? typeLabel + " generated from " + sourceFileCount + " files" : typeLabel + " generated"; - return prefix + ": [" + displayName + "](" + url + ") (link valid for 10 minutes).\n" + return prefix + ": [" + displayName + "](" + url + ") (link valid for " + + GeneratedFileCache.TTL.toDays() + " days).\n" + "IMPORTANT: when replying to the user you **must** keep the markdown link form [" + displayName + "](" + url + ") above. Keep the relative path verbatim — do **not** " + "wrap it in backticks and do **not** prepend any https://, http:// or domain " diff --git a/mateclaw-server/src/main/java/vip/mate/tool/guard/WorkspacePathGuard.java b/mateclaw-server/src/main/java/vip/mate/tool/guard/WorkspacePathGuard.java index d6112d7d..06cb3255 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/guard/WorkspacePathGuard.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/guard/WorkspacePathGuard.java @@ -9,6 +9,9 @@ import vip.mate.tool.builtin.ToolExecutionContext; import java.io.IOException; import java.nio.file.Path; import java.nio.file.Paths; +import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; /** * 工作区路径沙箱校验器 @@ -25,6 +28,58 @@ public final class WorkspacePathGuard { private WorkspacePathGuard() {} + /** + * Shared skill repository root, trusted in addition to the per-conversation + * workspace boundary. System-level skills live under this root (one + * subdirectory per skill) and are shared across every workspace, so the + * agent must be able to read and run their files even when the active + * workspace points elsewhere. Registered once at startup from the + * {@code mateclaw.skill.workspace.root} setting. {@code null} until set + * (then no extra root is trusted — pure workspace-only behaviour). + */ + private static volatile Path skillRoot; + + /** + * Register the shared skill repository root. A {@code null} or blank path + * clears it, restoring workspace-only enforcement. + */ + public static void setSkillRoot(@Nullable String path) { + skillRoot = (path == null || path.isBlank()) + ? null + : Paths.get(path).toAbsolutePath().normalize(); + log.info("[WorkspacePathGuard] Trusted skill root: {}", skillRoot); + } + + /** The registered shared skill repository root, or {@code null} if none is set. */ + @Nullable + public static Path getSkillRoot() { + return skillRoot; + } + + /** True when {@code normalized} lives under the shared skill root (if one is set). */ + private static boolean isUnderSkillRoot(Path normalized) { + Path sr = skillRoot; + return sr != null && normalized.startsWith(sr); + } + + /** + * Symlink-resolved variant of {@link #isUnderSkillRoot}. Resolves the skill + * root's real path so a path whose real location lands inside the skill + * repository is accepted even when reached through a symlink. + */ + private static boolean isUnderSkillRootReal(Path realPath) { + Path sr = skillRoot; + if (sr == null) { + return false; + } + try { + Path realSkillRoot = sr.toFile().exists() ? sr.toRealPath() : sr; + return realPath.startsWith(realSkillRoot); + } catch (IOException e) { + return realPath.startsWith(sr); + } + } + /** * 校验文件路径是否在当前工作区活动目录范围内。 *

@@ -56,7 +111,7 @@ public final class WorkspacePathGuard { Path root = Paths.get(basePath).toAbsolutePath().normalize(); // 先用 normalize 检查，再尝试 toRealPath 防符号链接逃逸 - if (!normalized.startsWith(root)) { + if (!normalized.startsWith(root) && !isUnderSkillRoot(normalized)) { throw new IllegalArgumentException( "Path is outside workspace boundary: " + normalized + ", allowed root: " + root); } @@ -66,7 +121,7 @@ public final class WorkspacePathGuard { if (normalized.toFile().exists()) { Path realPath = normalized.toRealPath(); Path realRoot = root.toFile().exists() ? root.toRealPath() : root; - if (!realPath.startsWith(realRoot)) { + if (!realPath.startsWith(realRoot) && !isUnderSkillRootReal(realPath)) { throw new IllegalArgumentException( "Path escapes workspace via symlink: " + realPath + ", allowed root: " + realRoot); } @@ -100,6 +155,200 @@ public final class WorkspacePathGuard { return Paths.get(basePath).toAbsolutePath().normalize(); } + /** + * Validate that a shell command does not reference filesystem locations + * outside the active workspace boundary. When no workspace basePath is + * configured, the check is a no-op (matching {@link #validatePath} semantics). + * + *

The check is a static scan of the literal command string. It rejects: + *

    + *
  • any absolute path token (e.g. {@code /etc/passwd}, {@code >/tmp/x}, + * {@code cd /var}) whose normalized form is not under the workspace + * root — even when nested inside command substitution {@code $(...)} + * or backticks;
    • + *
  • relative tokens containing {@code ..} as a directory segment + * (e.g. {@code cd ..}, {@code cat ../foo}, {@code ln -s ../bar baz}) + * when the resolved path falls outside the workspace root — + * in-workspace traversal like {@code subdir/../sibling} is allowed + * because it normalizes back inside;
    • + *
  • tilde expansion ({@code ~}, {@code ~/...}) — always resolves to + * {@code $HOME}, which sits outside the workspace;
    • + *
  • references to environment variables ({@code $HOME}, {@code ${USER}}, + * {@code $TMPDIR}, etc.) that typically resolve outside the workspace.
    • + *
+ * + *

Limitations — the static scan is a best-effort defense, not a + * true filesystem sandbox. Obfuscated forms ({@code /e''tc/passwd}, + * variable concatenation like {@code X=/etc; cat $X/passwd}, base64-decoded + * paths) can still slip through. The agent is not expected to produce + * such forms in normal use, but a fully adversarial caller would need a + * real process sandbox (sandbox-exec / firejail / bwrap) on top of this + * check. + * + * @param command the shell command line as it will be passed to {@code sh -c} + * @throws IllegalArgumentException when the command references a location + * outside the workspace boundary + */ + public static void validateShellCommand(String command) { + validateShellCommand(command, null); + } + + /** ToolContext-aware overload — see {@link #validateShellCommand(String)}. */ + public static void validateShellCommand(String command, @Nullable ToolContext ctx) { + if (command == null || command.isEmpty()) return; + String basePath = resolveBasePath(ctx); + if (basePath == null || basePath.isBlank()) return; + Path root = Paths.get(basePath).toAbsolutePath().normalize(); + + // 1. Tilde — expands to $HOME, always outside a non-$HOME workspace. + if (TILDE_REF.matcher(command).find()) { + throw new IllegalArgumentException( + "Shell command uses tilde (~) expansion which resolves outside the workspace boundary: " + + truncateForError(command)); + } + + // 2. Env-var refs to locations that typically resolve outside the workspace. + Matcher envMatch = OUTSIDE_ENV_VAR.matcher(command); + if (envMatch.find()) { + throw new IllegalArgumentException( + "Shell command references environment variable " + envMatch.group() + + " which may resolve outside the workspace boundary"); + } + + // 3. Absolute-path tokens, including those nested inside $(...) or `...`. + Matcher pathMatch = ABS_PATH_TOKEN.matcher(command); + while (pathMatch.find()) { + String candidate = pathMatch.group(1); + // Strip trailing punctuation that the shell would treat as a separator + // but the regex captured into the path (defensive trim — the character + // class excludes most, this catches edge cases like a path followed + // by a comma in a sentence). + while (candidate.length() > 1) { + char tail = candidate.charAt(candidate.length() - 1); + if (tail == ',' || tail == ':' || tail == '.' || tail == ')' || tail == ']') { + candidate = candidate.substring(0, candidate.length() - 1); + } else { + break; + } + } + Path normalized; + try { + normalized = Paths.get(candidate).normalize(); + } catch (Exception ex) { + // Unparseable as a path — leave it alone, not our concern. + continue; + } + if (isAllowedDeviceNode(normalized)) { + // Character devices like /dev/null, /dev/stdin, /dev/fd/0 don't + // expose any on-disk user data — allow them so common shell + // idioms (`2>/dev/null`, `cmd <(cat file)`) keep working. + continue; + } + if (!normalized.startsWith(root) && !isUnderSkillRoot(normalized)) { + throw new IllegalArgumentException( + "Shell command references path outside workspace boundary: " + + normalized + ", allowed root: " + root); + } + } + + // 4. Relative tokens containing ".." — must resolve inside the workspace. + // Catches `cd ..`, `cat ../foo`, `ln -s ../bar baz`, `mv foo/../bar dst`, + // etc. In-workspace traversal (`subdir/../sibling`) normalizes back + // inside and passes. + Matcher traversalMatch = RELATIVE_TRAVERSAL_TOKEN.matcher(command); + while (traversalMatch.find()) { + String candidate = traversalMatch.group(1); + Path resolved; + try { + resolved = root.resolve(candidate).normalize(); + } catch (Exception ex) { + continue; + } + if (isAllowedDeviceNode(resolved)) continue; + if (!resolved.startsWith(root) && !isUnderSkillRoot(resolved)) { + throw new IllegalArgumentException( + "Shell command uses parent-directory traversal that escapes the workspace: '" + + candidate + "' would resolve to " + resolved + + ", allowed root: " + root); + } + } + } + + /** + * Match absolute path tokens — a leading slash that starts a fresh token + * (preceded by start-of-string, whitespace, a shell separator, or an + * opening quote/parenthesis/backtick) and runs until the next shell + * separator or quote. The {@code (?(`\"'={}])(?()\"'`{}=]+)"); + + /** + * Match relative tokens that contain {@code ..} as a path segment. Captures + * the whole token (prefix + {@code ..} + optional suffix) so the caller + * can resolve it against the workspace root and decide whether it escapes. + * + *

Matches: + *

    + *
  • {@code ..} ({@code cd ..}, bare arg)
    • + *
  • {@code ../foo/bar} (relative parent traversal)
    • + *
  • {@code ./..} ({@code cd ./..})
    • + *
  • {@code foo/..} ({@code rm foo/..})
    • + *
  • {@code foo/../bar} (in-workspace normalization)
    • + *
+ * + *

Does NOT match {@code abc..xyz} (no slash before/after the {@code ..} — + * not a path segment) or absolute {@code /foo/../bar} (handled by + * {@link #ABS_PATH_TOKEN}). The token must be bounded by a shell separator + * or end-of-string on both sides. + */ + private static final Pattern RELATIVE_TRAVERSAL_TOKEN = Pattern.compile( + "(?:^|[\\s|&;<>(`\"'={}])((?:[^\\s|&;<>()\"'`{}=/]+/)*\\.\\.(?:/[^\\s|&;<>()\"'`{}=]*)?)(?=[\\s|&;<>)`\"'=}]|$)"); + + /** Bare tilde or tilde at the start of a path token: {@code ~}, {@code ~/foo}, {@code "~/bar"}. */ + private static final Pattern TILDE_REF = Pattern.compile( + "(?:^|[\\s|&;<>(`\"'={}])~(?=[/\\s|&;<>)`\"'$]|$)"); + + /** + * Env-var references that almost always point outside a project-scoped + * workspace. {@code $PATH} is on the list because writing to a directory + * on {@code $PATH} is a privilege-escalation vector. + */ + private static final Pattern OUTSIDE_ENV_VAR = Pattern.compile( + "\\$\\{?(HOME|USER|LOGNAME|TMPDIR|TMP|TEMP|PWD|OLDPWD|PATH|MAIL)\\b"); + + /** + * Character device nodes that don't expose user data and are needed for + * common shell idioms (stderr suppression, process substitution, entropy). + * Linux/macOS only — the path strings are absolute POSIX paths; on + * Windows {@link #validateShellCommand} doesn't fire on these because + * a Windows command wouldn't normalize to a {@code /dev/...} string. + */ + private static final Set ALLOWED_DEVICE_NODES = Set.of( + "/dev/null", + "/dev/zero", + "/dev/stdin", + "/dev/stdout", + "/dev/stderr", + "/dev/random", + "/dev/urandom", + "/dev/tty" + ); + + /** Match {@code /dev/fd/0}, {@code /dev/fd/1}, etc — used by process substitution. */ + private static final Pattern ALLOWED_DEV_FD = Pattern.compile("^/dev/fd/\\d+$"); + + private static boolean isAllowedDeviceNode(Path normalized) { + String s = normalized.toString(); + return ALLOWED_DEVICE_NODES.contains(s) || ALLOWED_DEV_FD.matcher(s).matches(); + } + + private static String truncateForError(String s) { + return s.length() > 200 ? s.substring(0, 200) + "..." : s; + } + /** * Resolve the active workspace base path. Order of preference: *

    diff --git a/mateclaw-server/src/main/java/vip/mate/tool/guard/model/ToolInvocationContext.java b/mateclaw-server/src/main/java/vip/mate/tool/guard/model/ToolInvocationContext.java index cc0f0dd0..f33e6cc5 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/guard/model/ToolInvocationContext.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/guard/model/ToolInvocationContext.java @@ -3,10 +3,15 @@ package vip.mate.tool.guard.model; import java.util.Map; /** - * 工具调用上下文 + * Standard tool invocation context shared by every Guardian. *

    - * 标准化的工具调用信息，供所有 Guardian 使用。 - * 先标准化上下文，再做风险评估。 + * The {@code workspaceId} field was added so that {@code ApprovalGrantResolver} + * can scope grant lookups by workspace without forcing a DB query inside the + * resolver. Callers that already know the workspace pass it explicitly via + * {@link #of(String, Map, String, String, String, String, String, Long)}. + * Legacy callers using {@link #of(String, String, String, String)} receive + * {@code workspaceId = null}; the resolver then conservatively falls back to + * the existing human-approval path. */ public record ToolInvocationContext( String toolName, @@ -15,28 +20,34 @@ public record ToolInvocationContext( String conversationId, String agentId, String channelType, - String userId + String userId, + Long workspaceId ) { /** - * 常用工厂方法 — 从工具名和原始参数创建 + * Legacy factory: workspaceId resolved lazily downstream (sets {@code null} here). + * Kept verbatim so existing call sites and tests continue to compile. */ public static ToolInvocationContext of(String toolName, String rawArguments, String conversationId, String agentId) { return new ToolInvocationContext( - toolName, Map.of(), rawArguments, conversationId, agentId, null, null - ); + toolName, Map.of(), rawArguments, conversationId, agentId, + null, null, null); } /** - * 完整工厂方法 + * Full factory: preferred path used by {@code ToolExecutionExecutor.evaluateGuard()} + * once {@code WorkspaceLookupCache.resolveByConversation(...)} has resolved the + * workspace. */ public static ToolInvocationContext of(String toolName, Map parameters, String rawArguments, String conversationId, - String agentId, String channelType, String userId) { + String agentId, String channelType, String userId, + Long workspaceId) { return new ToolInvocationContext( - toolName, parameters != null ? parameters : Map.of(), - rawArguments, conversationId, agentId, channelType, userId - ); + toolName, + parameters != null ? parameters : Map.of(), + rawArguments, conversationId, agentId, + channelType, userId, workspaceId); } } diff --git a/mateclaw-server/src/main/java/vip/mate/tool/mcp/service/McpServerService.java b/mateclaw-server/src/main/java/vip/mate/tool/mcp/service/McpServerService.java index deaad663..5ef6d87f 100644 --- a/mateclaw-server/src/main/java/vip/mate/tool/mcp/service/McpServerService.java +++ b/mateclaw-server/src/main/java/vip/mate/tool/mcp/service/McpServerService.java @@ -68,7 +68,7 @@ public class McpServerService { entity.setConnectTimeoutSeconds(30); } if (entity.getReadTimeoutSeconds() == null) { - entity.setReadTimeoutSeconds(30); + entity.setReadTimeoutSeconds(60); } entity.setLastStatus("disconnected"); entity.setToolCount(0); diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/WikiProperties.java b/mateclaw-server/src/main/java/vip/mate/wiki/WikiProperties.java index 4df212e6..4267f2b5 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/WikiProperties.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/WikiProperties.java @@ -71,6 +71,36 @@ public class WikiProperties { /** 扫描时跳过大于此大小的文件（字节），默认 50MB */ private long maxScanFileSize = 50 * 1024 * 1024; + /** + * Allowed root directories for KB source directories. When non-empty, a + * configured source directory must resolve (after symlink resolution) to a + * path inside one of these roots, blocking arbitrary directory reads. Empty + * (the default) disables the containment check — suitable for desktop / + * single-tenant; server operators should set this. + */ + private java.util.List allowedSourceRoots = new java.util.ArrayList<>(); + + /** + * Fail-closed switch for source-path validation. When {@code true} and + * {@link #allowedSourceRoots} is empty, every source directory is rejected + * (no path is allowed until a root is configured) — recommended for + * multi-tenant servers so a missing allow-list cannot silently re-open + * full-filesystem reads. Default {@code false} keeps the opt-in behaviour + * for desktop / single-tenant where no roots are configured. + */ + private boolean requireAllowedRoots = false; + + /** + * When {@code true}, a scheduled job (single-owner via ShedLock) scans each + * KB's configured source directory and auto-ingests new files. Off by + * default — operators opt in. Existing dedup by source path keeps re-scans + * idempotent; deletes are never propagated. + */ + private boolean watcherEnabled = false; + + /** Interval between watcher scan cycles, milliseconds. Default 5 minutes. */ + private long watcherIntervalMs = 300_000; + /** * Wiki LLM 重试最大尝试次数（含首次）。 *

    @@ -270,4 +300,17 @@ public class WikiProperties { * top-3 RRF hit but doesn't dominate it. */ private double relationBoostLambda = 0.05; + + /** + * Feature flag for the cascade-delete / cascade-rename pipeline: when a + * page is deleted (or renamed), find every other page that linked to it + * via {@code [[slug]]} and rewrite those references so they don't dangle. + *

    + * Defaults to {@code true} — the legacy row-only delete left dangling + * {@code [[slug]]} markers behind, which is exactly the bug class this + * RFC closes. Set to {@code false} only as a temporary kill-switch if a + * cascade pass starts mangling referrer content (which would be a real + * bug to chase down, not a steady state). + */ + private boolean cascadeDeleteEnabled = true; } diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/controller/WikiController.java b/mateclaw-server/src/main/java/vip/mate/wiki/controller/WikiController.java index 377e470f..1f9358f0 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/controller/WikiController.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/controller/WikiController.java @@ -1,5 +1,6 @@ package vip.mate.wiki.controller; +import com.fasterxml.jackson.databind.ObjectMapper; import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import lombok.RequiredArgsConstructor; @@ -16,10 +17,16 @@ import vip.mate.workspace.core.annotation.RequireWorkspaceRole; import vip.mate.wiki.WikiProperties; import vip.mate.wiki.model.WikiKnowledgeBaseEntity; import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.model.WikiAgentPageTypePermissionEntity; +import vip.mate.wiki.model.WikiPageTypeProfileEntity; import vip.mate.wiki.model.WikiRawMaterialEntity; +import vip.mate.wiki.profile.WikiPageTypeProfileService; import vip.mate.wiki.service.WikiDirectoryScanService; +import vip.mate.wiki.service.WikiSourcePathValidator; import vip.mate.wiki.service.WikiKnowledgeBaseService; +import vip.mate.wiki.service.WikiLintJobService; import vip.mate.wiki.service.WikiPageService; +import vip.mate.wiki.service.WikiPageTypePermissionService; import vip.mate.wiki.service.WikiProcessingService; import vip.mate.wiki.service.WikiRawMaterialService; import vip.mate.wiki.sse.WikiProgressBus; @@ -50,9 +57,18 @@ public class WikiController { private final WikiPageService pageService; private final WikiProcessingService processingService; private final WikiDirectoryScanService scanService; + private final WikiLintJobService lintJobService; private final WikiProperties properties; private final WikiProgressBus progressBus; private final AuditEventService auditEventService; + private final WikiPageTypeProfileService pageTypeProfileService; + private final WikiPageTypePermissionService pageTypePermissionService; + private final WikiSourcePathValidator pathValidator; + private final vip.mate.wiki.service.WikiSourceWatcherService sourceWatcherService; + private final vip.mate.wiki.pipeline.WikiPipelineDefinitionService pipelineDefinitionService; + private final vip.mate.wiki.repository.WikiPipelineRunMapper pipelineRunMapper; + private final vip.mate.wiki.repository.WikiPipelineStepRunMapper pipelineStepRunMapper; + private final ObjectMapper objectMapper; // ==================== Knowledge Base ==================== @@ -65,6 +81,15 @@ public class WikiController { return R.ok(withLivePageCount(kbService.listByWorkspace(wsId))); } + @RequireWorkspaceRole("viewer") + @Operation(summary = "列出可绑定到指定 Agent 的知识库") + @GetMapping("/knowledge-bases/bindable") + public R> listBindableKBs( + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + long wsId = workspaceId != null ? workspaceId : 1L; + return R.ok(withLivePageCount(kbService.listByWorkspace(wsId))); + } + @RequireWorkspaceRole("viewer") @Operation(summary = "获取知识库详情") @GetMapping("/knowledge-bases/{id}") @@ -129,8 +154,7 @@ public class WikiController { verifyKBWorkspace(id, workspaceId); String name = (String) body.get("name"); String description = (String) body.get("description"); - Long agentId = body.get("agentId") != null ? Long.valueOf(body.get("agentId").toString()) : null; - kbService.update(id, name, description, agentId); + kbService.update(id, name, description); // RFC Embedding UI: 允许通过此接口绑定 / 解绑 embedding 模型 if (body.containsKey("embeddingModelId")) { Object v = body.get("embeddingModelId"); @@ -179,6 +203,77 @@ public class WikiController { return R.ok(); } + // ==================== PageType Profile ==================== + + @RequireWorkspaceRole("viewer") + @Operation(summary = "获取知识库 pageType profile（未配置则返回内置默认）") + @GetMapping("/knowledge-bases/{id}/page-type-profile") + public R> getPageTypeProfile(@PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(id, workspaceId); + WikiPageTypeProfileEntity row = pageTypeProfileService.findEnabledRow(id); + Map out = new LinkedHashMap<>(); + if (row != null) { + out.put("name", row.getName()); + out.put("version", row.getVersion()); + out.put("config", row.getConfigJson()); + out.put("builtinDefault", false); + } else { + String json; + try { + json = objectMapper.writeValueAsString(pageTypeProfileService.getDefaultProfile()); + } catch (Exception e) { + json = "{}"; + } + out.put("name", "default"); + out.put("version", 0); + out.put("config", json); + out.put("builtinDefault", true); + } + return R.ok(out); + } + + @RequireWorkspaceRole("admin") + @Operation(summary = "保存知识库 pageType profile") + @PutMapping("/knowledge-bases/{id}/page-type-profile") + public R savePageTypeProfile(@PathVariable Long id, @RequestBody Map body, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(id, workspaceId); + String config = body.get("config"); + if (config == null || config.isBlank()) { + return R.fail(400, "config is required"); + } + try { + pageTypeProfileService.saveProfile(id, body.get("name"), config); + } catch (IllegalArgumentException e) { + return R.fail(400, e.getMessage()); + } + return R.ok(); + } + + @RequireWorkspaceRole("member") + @Operation(summary = "校验 pageType profile JSON（不保存）") + @PostMapping("/knowledge-bases/{id}/page-type-profile/validate") + public R> validatePageTypeProfile(@PathVariable Long id, @RequestBody Map body, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(id, workspaceId); + List issues = pageTypeProfileService.validateProfileJson(body.getOrDefault("config", "")); + Map out = new LinkedHashMap<>(); + out.put("valid", issues.isEmpty()); + out.put("issues", issues); + return R.ok(out); + } + + @RequireWorkspaceRole("admin") + @Operation(summary = "重置 pageType profile 为内置默认") + @PostMapping("/knowledge-bases/{id}/page-type-profile/reset-default") + public R resetPageTypeProfile(@PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(id, workspaceId); + pageTypeProfileService.resetToDefault(id); + return R.ok(); + } + // ==================== Directory Scan ==================== @RequireWorkspaceRole("member") @@ -188,6 +283,13 @@ public class WikiController { @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { verifyKBWorkspace(id, workspaceId); String path = body.get("path"); + if (path != null && !path.isBlank()) { + try { + pathValidator.validateDirectory(path); + } catch (IllegalArgumentException e) { + return R.fail(400, e.getMessage()); + } + } kbService.updateSourceDirectory(id, path); return R.ok(); } @@ -207,6 +309,162 @@ public class WikiController { return R.ok(response); } + // ==================== Source Watcher ==================== + + @RequireWorkspaceRole("viewer") + @Operation(summary = "查看知识库源监听状态") + @GetMapping("/knowledge-bases/{id}/source-watcher") + public R> getSourceWatcher(@PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(id, workspaceId); + WikiKnowledgeBaseEntity kb = kbService.getById(id); + if (kb == null) return R.fail(404, "Knowledge base not found"); + vip.mate.wiki.source.WikiIngestSourceProvider provider = sourceWatcherService.providerFor(kb); + Map out = new LinkedHashMap<>(); + out.put("watcherEnabled", properties.isWatcherEnabled()); + out.put("intervalMs", properties.getWatcherIntervalMs()); + out.put("sourceDirectory", kb.getSourceDirectory()); + out.put("sourceType", provider != null ? provider.sourceType() : null); + out.put("availableSourceTypes", sourceWatcherService.availableSourceTypes()); + out.put("active", provider != null); + return R.ok(out); + } + + @RequireWorkspaceRole("member") + @Operation(summary = "手动触发一次源监听扫描") + @PostMapping("/knowledge-bases/{id}/source-watcher/scan") + public R> triggerSourceWatcher(@PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(id, workspaceId); + WikiKnowledgeBaseEntity kb = kbService.getById(id); + if (kb == null) return R.fail(404, "Knowledge base not found"); + vip.mate.wiki.source.WikiIngestSourceProvider provider = sourceWatcherService.providerFor(kb); + if (provider == null) return R.fail(400, "No source configured for this knowledge base"); + WikiDirectoryScanService.ScanResult result = provider.sync(kb); + Map out = new LinkedHashMap<>(); + out.put("sourceType", provider.sourceType()); + out.put("scanned", result.scanned()); + out.put("added", result.added()); + out.put("skipped", result.skipped()); + out.put("errors", result.errors()); + return R.ok(out); + } + + // ==================== Pipeline ==================== + + @RequireWorkspaceRole("viewer") + @Operation(summary = "列出知识库的 pipeline 定义") + @GetMapping("/knowledge-bases/{kbId}/pipelines") + public R> listPipelines( + @PathVariable Long kbId, @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + return R.ok(pipelineDefinitionService.list(kbId)); + } + + @RequireWorkspaceRole("admin") + @Operation(summary = "保存(创建/更新)pipeline 定义(YAML/JSON)") + @PostMapping("/knowledge-bases/{kbId}/pipelines") + public R savePipeline( + @PathVariable Long kbId, @RequestBody Map body, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + boolean yaml = !"json".equalsIgnoreCase(body.getOrDefault("format", "yaml")); + try { + return R.ok(pipelineDefinitionService.saveFromConfig(kbId, body.get("config"), yaml)); + } catch (IllegalArgumentException e) { + return R.fail(400, e.getMessage()); + } + } + + @RequireWorkspaceRole("member") + @Operation(summary = "校验 pipeline 配置(不保存)") + @PostMapping("/knowledge-bases/{kbId}/pipelines/validate") + public R> validatePipeline( + @PathVariable Long kbId, @RequestBody Map body, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + boolean yaml = !"json".equalsIgnoreCase(body.getOrDefault("format", "yaml")); + List issues = pipelineDefinitionService.validateConfig(body.getOrDefault("config", ""), yaml); + Map out = new LinkedHashMap<>(); + out.put("valid", issues.isEmpty()); + out.put("issues", issues); + return R.ok(out); + } + + @RequireWorkspaceRole("admin") + @Operation(summary = "删除 pipeline 定义") + @DeleteMapping("/knowledge-bases/{kbId}/pipelines/{id}") + public R deletePipeline(@PathVariable Long kbId, @PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + pipelineDefinitionService.delete(id); + return R.ok(); + } + + @RequireWorkspaceRole("viewer") + @Operation(summary = "查询 pipeline 运行记录") + @GetMapping("/knowledge-bases/{kbId}/pipelines/{id}/runs") + public R> listPipelineRuns( + @PathVariable Long kbId, @PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + return R.ok(pipelineRunMapper.selectList( + com.baomidou.mybatisplus.core.toolkit.Wrappers.lambdaQuery() + .eq(vip.mate.wiki.model.WikiPipelineRunEntity::getDefinitionId, id) + .orderByDesc(vip.mate.wiki.model.WikiPipelineRunEntity::getCreateTime))); + } + + @RequireWorkspaceRole("viewer") + @Operation(summary = "查询单次 run 的步骤明细") + @GetMapping("/knowledge-bases/{kbId}/pipeline-runs/{runId}") + public R> getPipelineRun( + @PathVariable Long kbId, @PathVariable Long runId, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + Map out = new LinkedHashMap<>(); + out.put("run", pipelineRunMapper.selectById(runId)); + out.put("steps", pipelineStepRunMapper.selectList( + com.baomidou.mybatisplus.core.toolkit.Wrappers.lambdaQuery() + .eq(vip.mate.wiki.model.WikiPipelineStepRunEntity::getRunId, runId) + .orderByAsc(vip.mate.wiki.model.WikiPipelineStepRunEntity::getCreateTime))); + return R.ok(out); + } + + // ==================== Agent PageType Permissions ==================== + + @RequireWorkspaceRole("viewer") + @Operation(summary = "列出某 Agent 在知识库下的 pageType 权限规则") + @GetMapping("/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions") + public R> listPageTypePermissions( + @PathVariable Long kbId, @PathVariable Long agentId, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + return R.ok(pageTypePermissionService.listRows(agentId, kbId)); + } + + @RequireWorkspaceRole("admin") + @Operation(summary = "新增或更新 Agent 的 pageType 权限规则（按 agent+kb+pageType 去重）") + @PostMapping("/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions") + public R savePageTypePermission( + @PathVariable Long kbId, @PathVariable Long agentId, + @RequestBody WikiAgentPageTypePermissionEntity body, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + body.setKbId(kbId); + body.setAgentId(agentId); + return R.ok(pageTypePermissionService.saveRow(body)); + } + + @RequireWorkspaceRole("admin") + @Operation(summary = "删除一条 Agent pageType 权限规则") + @DeleteMapping("/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions/{id}") + public R deletePageTypePermission( + @PathVariable Long kbId, @PathVariable Long agentId, @PathVariable Long id, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + return R.ok(pageTypePermissionService.deleteRow(id)); + } + // ==================== Raw Materials ==================== @RequireWorkspaceRole("viewer") @@ -444,6 +702,35 @@ public class WikiController { return R.ok(page); } + /** + * Lightweight wikilink resolution index. + *

    + * The viewer's wikilink resolver needs a {slug, title, archived} list that + * (1) is not constrained by the user's selected raw-material filter, and + * (2) is not paginated. The general page list endpoint above is filtered + * by rawId and may scope down based on UI state, so this is a separate, + * minimal endpoint dedicated to the resolver. + *

    + * Archived pages are excluded by default. Pass {@code includeArchived=true} + * to retrieve archived rows as well (useful when the renderer needs to mark + * existing links to archived targets as such instead of treating them as + * broken links). + */ + @RequireWorkspaceRole("viewer") + @Operation(summary = "获取 Wiki 页面引用索引（slug/title/archived，供 wikilink 解析）") + @GetMapping("/knowledge-bases/{kbId}/pages/refs") + public R> listPageRefs( + @PathVariable Long kbId, + @RequestParam(name = "includeArchived", defaultValue = "false") boolean includeArchived, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + List items = pageService.listAllRefs(kbId, includeArchived); + Map body = new LinkedHashMap<>(); + body.put("kbId", kbId); + body.put("items", items); + return R.ok(body); + } + @RequireWorkspaceRole("member") @Operation(summary = "手动编辑 Wiki 页面") @PutMapping("/knowledge-bases/{kbId}/pages/{slug}") @@ -477,6 +764,65 @@ public class WikiController { return R.ok(deleted); } + /** + * Cross-KB page lookup by title or slug, scoped to the requesting user's + * workspace. Used by the global wikilink click delegator: when a user + * clicks a {@code [[Title]]} reference inside a chat message, the + * frontend has no idea which KB the wiki tool read from, so this + * endpoint searches every KB visible to the user and returns the + * candidates. + *

    + * Lookup precedence: + *

      + *
    • If {@code slug} is provided, match against {@code page.slug} + * (case-insensitive exact).
      • + *
    • Else if {@code title} is provided, match against + * {@code page.title} (case-insensitive exact, trimmed).
      • + *
    + * Returns {@code []} if neither parameter is supplied or no match is + * found in any visible KB. + */ + @RequireWorkspaceRole("viewer") + @Operation(summary = "跨 KB 按 title 或 slug 查找页面（chat 端 wikilink 跳转用）") + @GetMapping("/pages/lookup") + public R>> lookupPages( + @RequestParam(required = false) String title, + @RequestParam(required = false) String slug, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + long wsId = workspaceId != null ? workspaceId : 1L; + List> matches = new java.util.ArrayList<>(); + if ((title == null || title.isBlank()) && (slug == null || slug.isBlank())) { + return R.ok(matches); + } + String slugLower = slug != null ? slug.trim().toLowerCase(java.util.Locale.ROOT) : null; + String titleLower = title != null ? title.trim().toLowerCase(java.util.Locale.ROOT) : null; + + for (WikiKnowledgeBaseEntity kb : kbService.listByWorkspace(wsId)) { + // listSummaries excludes archived; that's what we want for the + // chat-click navigation contract (clicking a [[link]] should + // take the user to an active page, not a tombstone). + for (WikiPageEntity p : pageService.listSummaries(kb.getId())) { + boolean hit = false; + if (slugLower != null && p.getSlug() != null + && p.getSlug().toLowerCase(java.util.Locale.ROOT).equals(slugLower)) { + hit = true; + } else if (titleLower != null && p.getTitle() != null + && p.getTitle().trim().toLowerCase(java.util.Locale.ROOT).equals(titleLower)) { + hit = true; + } + if (!hit) continue; + Map row = new LinkedHashMap<>(); + row.put("kbId", String.valueOf(kb.getId())); + row.put("kbName", kb.getName()); + row.put("slug", p.getSlug()); + row.put("title", p.getTitle()); + row.put("archived", false); + matches.add(row); + } + } + return R.ok(matches); + } + @RequireWorkspaceRole("viewer") @Operation(summary = "获取反向链接") @GetMapping("/knowledge-bases/{kbId}/pages/{slug}/backlinks") @@ -486,6 +832,122 @@ public class WikiController { return R.ok(pageService.getBacklinks(kbId, slug)); } + /** + * Rename a page within a KB. The old slug is no longer reachable after + * this call; every wikilink in the KB that pointed at it is rewritten + * to the new slug in the same transaction. Aliases ({@code [[oldSlug|x]]}) + * are preserved by carrying the alias text over to the new target. + */ + @RequireWorkspaceRole("admin") + @Operation(summary = "重命名 Wiki 页面，并级联更新所有引用方") + @PostMapping("/knowledge-bases/{kbId}/pages/{slug}/rename") + public R> renamePage( + @PathVariable Long kbId, + @PathVariable String slug, + @RequestBody Map body, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + String newSlug = body == null ? null : body.get("newSlug"); + WikiPageEntity renamed; + try { + renamed = pageService.rename(kbId, slug, newSlug); + } catch (IllegalArgumentException e) { + return R.fail(400, e.getMessage()); + } catch (IllegalStateException e) { + return R.fail(409, e.getMessage()); + } + if (renamed == null) return R.fail(404, "Page not found"); + Map out = new LinkedHashMap<>(); + out.put("oldSlug", slug); + out.put("newSlug", renamed.getSlug()); + out.put("pageId", String.valueOf(renamed.getId())); + return R.ok(out); + } + + // ==================== Wikilink lint (broken-link scan) ==================== + + /** + * Start a KB-wide broken-link scan. Job-based async: returns immediately + * with a {@code {jobId, status, startedAt}} envelope; the real work runs + * on a single-threaded background executor and writes per-page results + * back to {@code mate_wiki_page.broken_links}. Idempotent under in-flight + * load — repeated POSTs while a scan is queued or running return the + * existing job rather than queueing duplicates. + */ + @RequireWorkspaceRole("member") + @Operation(summary = "启动 Wiki 死链扫描 job（异步）") + @PostMapping("/knowledge-bases/{kbId}/lint/broken-links") + public R> startBrokenLinksScan( + @PathVariable Long kbId, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + WikiLintJobService.LintJob job = lintJobService.startOrGetRunning(kbId); + return R.ok(jobEnvelope(job)); + } + + /** + * Read the most recent completed scan result for {@code kbId}. Aggregated + * from persisted {@code broken_links} fields, so it survives a server + * restart that drops the in-memory job state. + */ + @RequireWorkspaceRole("viewer") + @Operation(summary = "读取最近一次死链扫描的聚合结果") + @GetMapping("/knowledge-bases/{kbId}/lint/broken-links") + public R> getBrokenLinksReport( + @PathVariable Long kbId, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + WikiLintJobService.Aggregate agg = lintJobService.aggregate(kbId); + if (agg == null) { + return R.fail(404, "no scan yet, POST to start one"); + } + WikiLintJobService.LintJob latest = lintJobService.getLatestJob(kbId); + Map body = new LinkedHashMap<>(); + body.put("kbId", agg.kbId()); + body.put("jobId", latest != null ? latest.jobId() : null); + body.put("completedAt", agg.completedAt()); + body.put("totalPages", agg.totalPages()); + body.put("pagesWithBrokenLinks", agg.pagesWithBrokenLinks()); + body.put("totalBrokenRefs", agg.totalBrokenRefs()); + body.put("pages", agg.pages()); + return R.ok(body); + } + + /** + * Optional job-status endpoint. Not strictly needed for the v1 UX + * (the frontend can poll the aggregate endpoint and watch + * {@code completedAt}), but useful for debugging and future progress + * reporting. + */ + @RequireWorkspaceRole("viewer") + @Operation(summary = "查询 Wiki 死链扫描 job 状态") + @GetMapping("/knowledge-bases/{kbId}/lint/broken-links/jobs/{jobId}") + public R> getBrokenLinksJob( + @PathVariable Long kbId, + @PathVariable String jobId, + @RequestHeader(value = "X-Workspace-Id", required = false) Long workspaceId) { + verifyKBWorkspace(kbId, workspaceId); + WikiLintJobService.LintJob job = lintJobService.getJob(jobId); + if (job == null || !job.kbId().equals(kbId)) { + return R.fail(404, "job not found"); + } + return R.ok(jobEnvelope(job)); + } + + private Map jobEnvelope(WikiLintJobService.LintJob job) { + Map body = new LinkedHashMap<>(); + body.put("jobId", job.jobId()); + body.put("kbId", job.kbId()); + body.put("status", job.status().name().toLowerCase()); + body.put("startedAt", job.startedAt()); + body.put("completedAt", job.completedAt()); + body.put("totalPages", job.totalPages()); + body.put("pagesWithBrokenLinks", job.pagesWithBrokenLinks()); + body.put("totalBrokenRefs", job.totalBrokenRefs()); + if (job.errorMessage() != null) body.put("errorMessage", job.errorMessage()); + return body; + } + // RFC-051 PR-7 follow-up: archive surfaces. Default-list is filtered, so the UI // needs a dedicated endpoint to enumerate archived pages and a way to flip the // flag via REST (the agent tools wiki_archive_page / wiki_unarchive_page already @@ -546,17 +1008,77 @@ public class WikiController { long pending = rawList.stream().filter(r -> "pending".equals(r.getProcessingStatus())).count(); long processing = rawList.stream().filter(r -> "processing".equals(r.getProcessingStatus())).count(); long completed = rawList.stream().filter(r -> "completed".equals(r.getProcessingStatus())).count(); + long partial = rawList.stream().filter(r -> "partial".equals(r.getProcessingStatus())).count(); long failed = rawList.stream().filter(r -> "failed".equals(r.getProcessingStatus())).count(); + long cancelled = rawList.stream().filter(r -> "cancelled".equals(r.getProcessingStatus())).count(); - return R.ok(Map.of( - "status", kb.getStatus(), - "pending", pending, - "processing", processing, - "completed", completed, - "failed", failed, - "totalRaw", rawList.size(), - "totalPages", kb.getPageCount() - )); + // Derive totalPages from the real `mate_wiki_page` table rather than + // `kb.pageCount`, which can lag behind if a processing run aborts + // between page creation and the page-count refresh. Using the live + // count keeps the UI honest even when the bookkeeping field is stale. + int realPageCount = pageService.countByKbId(kbId); + // Self-heal: if the stored pageCount drifted from the real count, + // quietly fix it so downstream callers reading `kb.pageCount` see + // the truth too. This is the cheapest place to repair without + // disrupting the in-flight processing path. + if (kb.getPageCount() == null || kb.getPageCount() != realPageCount) { + try { + kbService.setPageCount(kbId, realPageCount); + } catch (Exception ignore) { + // Self-heal is best-effort; never let it fail the status read. + } + } + + // KB-level status field reflects whether the heavy pipeline is still + // running; once it flips back to "active" no raw material is actually + // mid-processing, regardless of any row whose `processing_status` + // didn't get its terminal-state update (a known failure mode in + // long-running ingest paths). Override the per-raw count so the UI + // doesn't show "processing" forever after the KB itself is idle. + boolean kbIdle = !"processing".equals(kb.getStatus()); + long effectiveProcessing = kbIdle ? 0 : processing; + long inferredCompleted = kbIdle ? (completed + (realPageCount > 0 ? processing : 0)) : completed; + + // Per-raw progress snapshot — lets callers distinguish "LLM still + // working through phase-b 4 of 10 pages" from "thread is wedged". + // Without this the polling client sees `processing: 1` for the entire + // multi-minute pipeline and can't tell whether to wait or alert. + // `staleSeconds` is the gap since the raw's last bookkeeping update; + // a freshly-progressing pipeline updates progressDone every minute or + // two, so a gap > 600s suggests a real stall worth investigating. + long nowMs = System.currentTimeMillis(); + java.util.List> rawProgress = new java.util.ArrayList<>(rawList.size()); + for (WikiRawMaterialEntity r : rawList) { + long staleSeconds = -1; + if (r.getUpdateTime() != null) { + long updatedMs = r.getUpdateTime() + .atZone(java.time.ZoneId.systemDefault()) + .toInstant().toEpochMilli(); + staleSeconds = (nowMs - updatedMs) / 1000L; + } + Map row = new java.util.LinkedHashMap<>(); + row.put("rawId", r.getId()); + row.put("title", r.getTitle()); + row.put("status", r.getProcessingStatus()); + row.put("phase", r.getProgressPhase()); + row.put("done", r.getProgressDone() == null ? 0 : r.getProgressDone()); + row.put("total", r.getProgressTotal() == null ? 0 : r.getProgressTotal()); + row.put("staleSeconds", staleSeconds); + rawProgress.add(row); + } + + Map body = new java.util.LinkedHashMap<>(); + body.put("status", kb.getStatus()); + body.put("pending", pending); + body.put("processing", effectiveProcessing); + body.put("completed", inferredCompleted); + body.put("partial", partial); + body.put("failed", failed); + body.put("cancelled", cancelled); + body.put("totalRaw", rawList.size()); + body.put("totalPages", realPageCount); + body.put("rawProgress", rawProgress); + return R.ok(body); } /** diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/event/WikiFactPageUpdatedEvent.java b/mateclaw-server/src/main/java/vip/mate/wiki/event/WikiFactPageUpdatedEvent.java new file mode 100644 index 00000000..cadb7438 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/event/WikiFactPageUpdatedEvent.java @@ -0,0 +1,11 @@ +package vip.mate.wiki.event; + +/** + * Published after a fact-layer page is updated during ingest (already + * committed). Consumed asynchronously to mark the experience pages that depend + * on it as stale, without blocking ingest. + * + * @author MateClaw Team + */ +public record WikiFactPageUpdatedEvent(Long kbId, Long factPageId, String reason) { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/event/WikiPageCreatedEvent.java b/mateclaw-server/src/main/java/vip/mate/wiki/event/WikiPageCreatedEvent.java new file mode 100644 index 00000000..f7ad8fd0 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/event/WikiPageCreatedEvent.java @@ -0,0 +1,11 @@ +package vip.mate.wiki.event; + +/** + * Published after a wiki page is created during ingest (already committed, + * since page creation is its own transaction). Consumed asynchronously to + * evaluate count-threshold pipeline triggers without blocking ingest. + * + * @author MateClaw Team + */ +public record WikiPageCreatedEvent(Long kbId, String pageType, Long pageId) { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfig.java b/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfig.java index 29fece9a..e1e1a489 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfig.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfig.java @@ -47,4 +47,14 @@ public class WikiKbConfig { * {@link vip.mate.wiki.WikiProperties#isUseStructuredRoute()}. */ private Boolean useStructuredRoute; + + /** + * KB-level default read policy applied when an agent has no + * {@code mate_wiki_agent_page_type_permission} rows for this KB. + * {@code "allow_all"} (the default when {@code null}) keeps existing + * behaviour — every agent reads every pageType. {@code "deny_all"} flips + * the default closed so a professional KB can require each readable + * pageType to be granted explicitly per agent. + */ + private String defaultReadPolicy; } diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfigParser.java b/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfigParser.java index 62792a78..d9300ce5 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfigParser.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/job/WikiKbConfigParser.java @@ -45,6 +45,8 @@ public final class WikiKbConfigParser { if ("ingestMode".equals(key)) { config.setIngestMode(value); + } else if ("defaultReadPolicy".equals(key)) { + config.setDefaultReadPolicy(value); } else if ("useStructuredRoute".equals(key)) { config.setUseStructuredRoute(Boolean.valueOf(value)); } else if ("wikiDefaultModelId".equals(key)) { diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiAgentPageTypePermissionEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiAgentPageTypePermissionEntity.java new file mode 100644 index 00000000..0f2961e5 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiAgentPageTypePermissionEntity.java @@ -0,0 +1,62 @@ +package vip.mate.wiki.model; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableLogic; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * Per-agent, per-KB, per-pageType permission for wiki tool access. + *

    + * A {@code page_type='*'} row is the agent's KB-wide default; an exact + * {@code page_type} row is more specific and wins over {@code '*'}. When an + * agent has no rows for a KB at all, access falls back to the KB-level + * default read policy (see {@code WikiKbConfig#getDefaultReadPolicy()}). + * + * @author MateClaw Team + */ +@Data +@TableName("mate_wiki_agent_page_type_permission") +public class WikiAgentPageTypePermissionEntity { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + /** Agent the rule applies to. */ + private Long agentId; + + /** Knowledge base the rule applies to. */ + private Long kbId; + + /** Page type name, or {@code *} for the agent's KB-wide default. */ + private String pageType; + + /** Whether the agent may read pages of this type. */ + private Integer canRead; + + /** Whether the agent may create pages of this type. */ + private Integer canCreate; + + /** Whether the agent may update pages of this type. */ + private Integer canUpdate; + + /** Whether the agent may delete pages of this type. */ + private Integer canDelete; + + /** Write resolution: {@code deny} / {@code approval_required} / {@code allow}. */ + private String writePolicy; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + @TableField(fill = FieldFill.INSERT_UPDATE) + private LocalDateTime updateTime; + + @TableLogic + private Integer deleted; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiKnowledgeBaseEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiKnowledgeBaseEntity.java index b87846b3..3ced4646 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiKnowledgeBaseEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiKnowledgeBaseEntity.java @@ -51,6 +51,7 @@ public class WikiKnowledgeBaseEntity { * NULL = 使用系统默认（mate_system_setting 的 embedding.default.model.id）， * 再无则取任意 enabled 的 embedding 模型，最终全无则语义搜索降级为不可用。 */ + @TableField(updateStrategy = FieldStrategy.ALWAYS) private Long embeddingModelId; @TableField(fill = FieldFill.INSERT) diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageDependencyEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageDependencyEntity.java new file mode 100644 index 00000000..5453d753 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageDependencyEntity.java @@ -0,0 +1,48 @@ +package vip.mate.wiki.model; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableLogic; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * A dependency edge from an experience page to a fact page it relies on. + * The reverse index ({@code depends_on_page_id}) drives stale propagation: + * when a fact page changes, the experience pages depending on it are marked + * stale. Stored by page id (never slug) so renames cannot break the edge. + * + * @author MateClaw Team + */ +@Data +@TableName("mate_wiki_page_dependency") +public class WikiPageDependencyEntity { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + /** Knowledge base both pages belong to (cross-KB dependencies are rejected). */ + private Long kbId; + + /** The dependent (experience) page. */ + private Long pageId; + + /** The fact page being depended on. */ + private Long dependsOnPageId; + + /** Dependency kind; {@code fact} for the fact→experience relation. */ + private String dependencyType; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + @TableField(fill = FieldFill.INSERT_UPDATE) + private LocalDateTime updateTime; + + @TableLogic + private Integer deleted; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageEntity.java index ba57e887..31df23be 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageEntity.java @@ -49,6 +49,42 @@ public class WikiPageEntity { /** Page type: entity / concept / source / synthesis */ private String pageType; + /** + * Structured pageType metadata (schema-validated fields) as a JSON object. + * Stored as a blob rather than exploded into per-field columns so each KB + * can define its own schema without altering the table. Written with the + * full page save path; partial column updates must avoid touching it. + */ + @TableField(updateStrategy = FieldStrategy.ALWAYS) + private String metadataJson; + + /** Last metadata validation outcome: {@code ok} / {@code warning} / {@code invalid}. */ + private String metadataValidationStatus; + + /** Metadata validation warnings/errors as a JSON array (field, reason, source, rawValuePreview). */ + @TableField(updateStrategy = FieldStrategy.ALWAYS) + private String metadataValidationJson; + + /** Template key used when generating this page, when applicable. */ + private String templateKey; + + /** Profile version in effect when the page was generated or last validated. */ + private Integer profileVersion; + + /** Knowledge layer derived from the pageType profile: {@code fact} / {@code experience}. */ + private String knowledgeLayer; + + /** Fact page ids this (experience) page depends on, as a JSON array. Source of truth is the dependency table. */ + @TableField(updateStrategy = FieldStrategy.ALWAYS) + private String dependsOnJson; + + /** {@code 1} when an upstream fact page changed and this page may be out of date. */ + private Integer stale; + + /** Why the page is stale (fact page id, time, reason) as JSON. */ + @TableField(updateStrategy = FieldStrategy.ALWAYS) + private String staleReasonJson; + /** Purpose hint for LLM ingest routing */ private String purposeHint; @@ -87,6 +123,21 @@ public class WikiPageEntity { /** Input-format version for {@link #embedding}; bumped when the embedding builder changes. */ private String embeddingTextVersion; + /** + * JSON array of outlink targets present in {@link #content} but missing + * from the active KB slug set. Empty array = scanned, all targets resolve; + * {@code null} = never scanned. Recomputed in the same transaction as any + * content save/update, and by the on-demand KB-wide lint scan job. + */ + @TableField(updateStrategy = FieldStrategy.ALWAYS) + private String brokenLinks; + + /** + * Timestamp of the most recent {@link #brokenLinks} recompute. The lint UI + * banner uses this to mark stale data ("scanned 3 days ago — rescan?"). + */ + private LocalDateTime brokenLinksScannedAt; + @TableField(fill = FieldFill.INSERT) private LocalDateTime createTime; diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageTypeProfileEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageTypeProfileEntity.java new file mode 100644 index 00000000..c6fe4b58 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPageTypeProfileEntity.java @@ -0,0 +1,54 @@ +package vip.mate.wiki.model; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableLogic; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * A KB-scoped pageType profile: the set of page types a knowledge base + * recognises, plus each type's field schema, per-stage LLM instructions and + * Markdown template, serialized into {@link #configJson}. + * + *

    The built-in default profile is provided as a code constant and is NOT + * stored in this table, so {@link #kbId} is always non-null. A virtual + * generated column on the table enforces at most one enabled profile per KB. + * + * @author MateClaw Team + */ +@Data +@TableName("mate_wiki_page_type_profile") +public class WikiPageTypeProfileEntity { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + /** Owning knowledge base (never null — built-in default is not stored). */ + private Long kbId; + + /** Profile name, e.g. {@code default}, {@code regulation}. */ + private String name; + + /** Profile version, bumped on each saved edit. */ + private Integer version; + + /** Full pageType configuration as JSON. */ + private String configJson; + + /** {@code 1} = the active profile for the KB. */ + private Integer enabled; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + @TableField(fill = FieldFill.INSERT_UPDATE) + private LocalDateTime updateTime; + + @TableLogic + private Integer deleted; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineDefinitionEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineDefinitionEntity.java new file mode 100644 index 00000000..62dc57e8 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineDefinitionEntity.java @@ -0,0 +1,55 @@ +package vip.mate.wiki.model; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableLogic; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * A KB-scoped pipeline definition: a processing chain triggered by a pageType + * event, executed under a concrete owner agent's permissions. + * + * @author MateClaw Team + */ +@Data +@TableName("mate_wiki_pipeline_definition") +public class WikiPipelineDefinitionEntity { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + private Long kbId; + + private String name; + + /** Agent whose identity (and RFC permissions) the steps run under. */ + private Long ownerAgentId; + + /** Trigger kind, e.g. {@code page_type_count}. */ + private String triggerType; + + /** Trigger configuration as JSON (e.g. page_type + threshold). */ + private String triggerConfigJson; + + /** Ordered step definitions as JSON. */ + private String stepsJson; + + /** Window (seconds) within which duplicate triggers collapse to one run. */ + private Integer dedupWindowSeconds; + + private Integer enabled; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + @TableField(fill = FieldFill.INSERT_UPDATE) + private LocalDateTime updateTime; + + @TableLogic + private Integer deleted; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineRunEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineRunEntity.java new file mode 100644 index 00000000..5e6f85b0 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineRunEntity.java @@ -0,0 +1,59 @@ +package vip.mate.wiki.model; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableLogic; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * One execution instance of a pipeline definition. The + * (definition_id, trigger_type, trigger_subject, trigger_bucket) unique key + * makes duplicate triggers idempotent across instances. + * + * @author MateClaw Team + */ +@Data +@TableName("mate_wiki_pipeline_run") +public class WikiPipelineRunEntity { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + private Long definitionId; + + private Long kbId; + + /** {@code pending} / {@code running} / {@code succeeded} / {@code failed}. */ + private String status; + + private String triggerType; + + /** The entity the trigger fired on, e.g. a pageType name. */ + private String triggerSubject; + + /** Dedup envelope (time/threshold bucket) for idempotency. */ + private String triggerBucket; + + private String triggerPayloadJson; + + private String inputJson; + + private String outputJson; + + private String errorMessage; + + private LocalDateTime startedAt; + + private LocalDateTime finishedAt; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + @TableLogic + private Integer deleted; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineStepRunEntity.java b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineStepRunEntity.java new file mode 100644 index 00000000..636f65ab --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/model/WikiPipelineStepRunEntity.java @@ -0,0 +1,51 @@ +package vip.mate.wiki.model; + +import com.baomidou.mybatisplus.annotation.FieldFill; +import com.baomidou.mybatisplus.annotation.IdType; +import com.baomidou.mybatisplus.annotation.TableField; +import com.baomidou.mybatisplus.annotation.TableId; +import com.baomidou.mybatisplus.annotation.TableLogic; +import com.baomidou.mybatisplus.annotation.TableName; +import lombok.Data; + +import java.time.LocalDateTime; + +/** + * One step invocation within a {@link WikiPipelineRunEntity}. + * + * @author MateClaw Team + */ +@Data +@TableName("mate_wiki_pipeline_step_run") +public class WikiPipelineStepRunEntity { + + @TableId(type = IdType.ASSIGN_ID) + private Long id; + + private Long runId; + + /** Step id from the definition's steps_json. */ + private String stepId; + + /** {@code llm} / {@code skill} (Python is out of MVP). */ + private String executor; + + /** {@code pending} / {@code running} / {@code succeeded} / {@code failed}. */ + private String status; + + private String inputJson; + + private String outputJson; + + private String errorMessage; + + private LocalDateTime startedAt; + + private LocalDateTime finishedAt; + + @TableField(fill = FieldFill.INSERT) + private LocalDateTime createTime; + + @TableLogic + private Integer deleted; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiLlmStepExecutor.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiLlmStepExecutor.java new file mode 100644 index 00000000..6e6d271e --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiLlmStepExecutor.java @@ -0,0 +1,75 @@ +package vip.mate.wiki.pipeline; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.ai.chat.messages.SystemMessage; +import org.springframework.ai.chat.messages.UserMessage; +import org.springframework.ai.chat.model.ChatModel; +import org.springframework.ai.chat.model.ChatResponse; +import org.springframework.ai.chat.prompt.Prompt; +import org.springframework.stereotype.Component; +import vip.mate.wiki.job.WikiModelRoutingService; + +import java.util.List; + +/** + * Pipeline step executor that calls a chat model. The step config supplies a + * {@code prompt} (system instruction) and an optional {@code model_id}; the + * previous step's output is passed as the user message so steps compose. The + * model is resolved through the existing wiki model routing. + * + * @author MateClaw Team + */ +@Slf4j +@Component +public class WikiLlmStepExecutor implements WikiStepExecutor { + + private final WikiModelRoutingService modelRoutingService; + + public WikiLlmStepExecutor(WikiModelRoutingService modelRoutingService) { + this.modelRoutingService = modelRoutingService; + } + + @Override + public String type() { + return "llm"; + } + + @Override + public String execute(WikiStepContext context) { + String prompt = stringConfig(context, "prompt"); + if (prompt == null || prompt.isBlank()) { + throw new IllegalArgumentException("llm step '" + context.stepId() + "' has no prompt"); + } + Long modelId = longConfig(context, "model_id"); + ChatModel chatModel = modelRoutingService.buildChatModel(modelId); + if (chatModel == null) { + throw new IllegalStateException("No chat model available for pipeline step " + context.stepId()); + } + String userContent = context.previousOutput() == null || context.previousOutput().isBlank() + ? "(no prior output)" : context.previousOutput(); + ChatResponse resp = chatModel.call(new Prompt(List.of( + new SystemMessage(prompt), new UserMessage(userContent)))); + if (resp == null || resp.getResult() == null || resp.getResult().getOutput() == null + || resp.getResult().getOutput().getText() == null) { + throw new IllegalStateException("Chat model returned no text for step " + context.stepId()); + } + return resp.getResult().getOutput().getText(); + } + + private String stringConfig(WikiStepContext context, String key) { + Object v = context.stepConfig() == null ? null : context.stepConfig().get(key); + return v == null ? null : String.valueOf(v); + } + + private Long longConfig(WikiStepContext context, String key) { + Object v = context.stepConfig() == null ? null : context.stepConfig().get(key); + if (v == null) { + return null; + } + try { + return Long.parseLong(String.valueOf(v)); + } catch (NumberFormatException e) { + return null; + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionService.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionService.java new file mode 100644 index 00000000..587db918 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionService.java @@ -0,0 +1,164 @@ +package vip.mate.wiki.pipeline; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.fasterxml.jackson.databind.ObjectMapper; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; +import vip.mate.wiki.repository.WikiPipelineDefinitionMapper; + +import java.util.ArrayList; +import java.util.List; +import java.util.Map; + +/** + * CRUD + YAML/JSON parsing for user-defined pipelines. A definition's config + * (YAML or JSON) carries {@code name}, {@code owner_agent}, a {@code trigger} + * object and a {@code steps} array; this service parses it into the persisted + * entity (trigger / steps stored as JSON). + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiPipelineDefinitionService { + + private static final java.util.Set KNOWN_EXECUTORS = java.util.Set.of("llm", "skill", "python"); + private static final java.util.Set KNOWN_TRIGGERS = + java.util.Set.of("page_type_count", "page_created", "stale_marked"); + + private final WikiPipelineDefinitionMapper definitionMapper; + private final ObjectMapper objectMapper; + + public WikiPipelineDefinitionService(WikiPipelineDefinitionMapper definitionMapper, ObjectMapper objectMapper) { + this.definitionMapper = definitionMapper; + this.objectMapper = objectMapper; + } + + public List list(Long kbId) { + return definitionMapper.selectList(new LambdaQueryWrapper() + .eq(WikiPipelineDefinitionEntity::getKbId, kbId) + .orderByDesc(WikiPipelineDefinitionEntity::getCreateTime)); + } + + public WikiPipelineDefinitionEntity get(Long id) { + return definitionMapper.selectById(id); + } + + public void delete(Long id) { + definitionMapper.deleteById(id); + } + + /** + * Parse a YAML/JSON pipeline config and upsert it (by kb + name). Throws + * {@link IllegalArgumentException} on a structural problem. + */ + @SuppressWarnings("unchecked") + public WikiPipelineDefinitionEntity saveFromConfig(Long kbId, String config, boolean yaml) { + Map root = parse(config, yaml); + List issues = validateParsed(root); + if (!issues.isEmpty()) { + throw new IllegalArgumentException("Invalid pipeline config: " + String.join("; ", issues)); + } + String name = String.valueOf(root.get("name")); + Object owner = root.get("owner_agent"); + Map trigger = (Map) root.get("trigger"); + Object steps = root.get("steps"); + + WikiPipelineDefinitionEntity entity = definitionMapper.selectOne( + new LambdaQueryWrapper() + .eq(WikiPipelineDefinitionEntity::getKbId, kbId) + .eq(WikiPipelineDefinitionEntity::getName, name) + .last("LIMIT 1")); + boolean isNew = entity == null; + if (isNew) { + entity = new WikiPipelineDefinitionEntity(); + entity.setKbId(kbId); + entity.setName(name); + entity.setEnabled(1); + } + entity.setOwnerAgentId(Long.valueOf(String.valueOf(owner))); + entity.setTriggerType(String.valueOf(trigger.get("type"))); + try { + entity.setTriggerConfigJson(objectMapper.writeValueAsString(trigger)); + entity.setStepsJson(objectMapper.writeValueAsString(steps)); + } catch (Exception e) { + throw new IllegalArgumentException("Failed to serialize pipeline config: " + e.getMessage()); + } + Object dedup = trigger.get("dedup_window_seconds"); + entity.setDedupWindowSeconds(dedup instanceof Number ? ((Number) dedup).intValue() : 0); + + if (isNew) { + definitionMapper.insert(entity); + } else { + definitionMapper.updateById(entity); + } + return entity; + } + + /** Validate a config without saving; returns human-readable issues (empty = valid). */ + public List validateConfig(String config, boolean yaml) { + try { + return validateParsed(parse(config, yaml)); + } catch (Exception e) { + return List.of("Unparseable config: " + e.getMessage()); + } + } + + @SuppressWarnings("unchecked") + private Map parse(String config, boolean yaml) { + if (config == null || config.isBlank()) { + throw new IllegalArgumentException("config is empty"); + } + try { + if (yaml) { + Object loaded = new org.yaml.snakeyaml.Yaml().load(config); + if (!(loaded instanceof Map)) { + throw new IllegalArgumentException("YAML root must be a mapping"); + } + return (Map) loaded; + } + return objectMapper.readValue(config, Map.class); + } catch (IllegalArgumentException e) { + throw e; + } catch (Exception e) { + throw new IllegalArgumentException(e.getMessage()); + } + } + + @SuppressWarnings("unchecked") + private List validateParsed(Map root) { + List issues = new ArrayList<>(); + if (root.get("name") == null || String.valueOf(root.get("name")).isBlank()) { + issues.add("missing 'name'"); + } + if (root.get("owner_agent") == null) { + issues.add("missing 'owner_agent' (steps run under this agent)"); + } + Object trig = root.get("trigger"); + if (!(trig instanceof Map)) { + issues.add("missing 'trigger' object"); + } else { + String type = String.valueOf(((Map) trig).get("type")); + if (!KNOWN_TRIGGERS.contains(type)) { + issues.add("unknown trigger type '" + type + "' (expected one of " + KNOWN_TRIGGERS + ")"); + } + } + Object steps = root.get("steps"); + if (!(steps instanceof List) || ((List) steps).isEmpty()) { + issues.add("'steps' must be a non-empty array"); + } else { + for (Object s : (List) steps) { + if (!(s instanceof Map)) { issues.add("each step must be an object"); continue; } + String ex = String.valueOf(((Map) s).get("executor")); + if (!KNOWN_EXECUTORS.contains(ex)) { + issues.add("step executor '" + ex + "' unknown (expected " + KNOWN_EXECUTORS + ")"); + } + if ("python".equals(ex)) { + issues.add("python executor needs a sandbox and is not enabled in this build"); + } + } + } + return issues; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineService.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineService.java new file mode 100644 index 00000000..52c75aec --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineService.java @@ -0,0 +1,177 @@ +package vip.mate.wiki.pipeline; + +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import lombok.extern.slf4j.Slf4j; +import org.springframework.dao.DuplicateKeyException; +import org.springframework.stereotype.Service; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; +import vip.mate.wiki.model.WikiPipelineRunEntity; +import vip.mate.wiki.model.WikiPipelineStepRunEntity; +import vip.mate.wiki.repository.WikiPipelineRunMapper; +import vip.mate.wiki.repository.WikiPipelineStepRunMapper; + +import java.time.LocalDateTime; +import java.util.List; +import java.util.Map; + +/** + * Runs a wiki pipeline definition: creates a dedup-guarded run, executes each + * step through the matching {@link WikiStepExecutor} under the definition's + * owner agent, and records run / step status. + * + *

    Run creation is idempotent: a duplicate trigger envelope collides on the + * run table's unique key and is skipped, so concurrent instances cannot spawn + * parallel runs for the same trigger. + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiPipelineService { + + private final WikiPipelineRunMapper runMapper; + private final WikiPipelineStepRunMapper stepRunMapper; + private final ObjectMapper objectMapper; + private final Map executors; + + public WikiPipelineService(WikiPipelineRunMapper runMapper, + WikiPipelineStepRunMapper stepRunMapper, + ObjectMapper objectMapper, + List executorBeans) { + this.runMapper = runMapper; + this.stepRunMapper = stepRunMapper; + this.objectMapper = objectMapper; + this.executors = new java.util.HashMap<>(); + for (WikiStepExecutor e : executorBeans) { + this.executors.put(e.type(), e); + } + } + + /** Outcome of an attempted run. {@code run} is null when skipped as a duplicate. */ + public record RunOutcome(WikiPipelineRunEntity run, boolean duplicate) {} + + /** + * Execute a definition for one trigger. Returns {@code duplicate=true} with + * a null run when the trigger envelope was already handled. + */ + public RunOutcome execute(WikiPipelineDefinitionEntity def, String triggerSubject, + String triggerBucket, String inputJson) { + if (def.getEnabled() != null && def.getEnabled() == 0) { + return new RunOutcome(null, false); + } + if (def.getOwnerAgentId() == null) { + throw new IllegalStateException("Pipeline definition " + def.getId() + " has no owner agent"); + } + + WikiPipelineRunEntity run = new WikiPipelineRunEntity(); + run.setDefinitionId(def.getId()); + run.setKbId(def.getKbId()); + run.setStatus("running"); + run.setTriggerType(def.getTriggerType()); + run.setTriggerSubject(triggerSubject); + run.setTriggerBucket(triggerBucket); + run.setInputJson(inputJson); + run.setStartedAt(LocalDateTime.now()); + run.setCreateTime(LocalDateTime.now()); + try { + runMapper.insert(run); + } catch (DuplicateKeyException dup) { + // Another instance / earlier trigger already created this run. + log.info("[WikiPipeline] duplicate trigger for def={} subject={} bucket={} — skipped", + def.getId(), triggerSubject, triggerBucket); + return new RunOutcome(null, true); + } + + List> steps = parseSteps(def.getStepsJson()); + String previousOutput = null; + try { + for (Map step : steps) { + previousOutput = runStep(def, run.getId(), step, previousOutput); + } + finishRun(run, "succeeded", previousOutput, null); + } catch (StepFailure f) { + finishRun(run, "failed", previousOutput, f.getMessage()); + } + return new RunOutcome(run, false); + } + + private String runStep(WikiPipelineDefinitionEntity def, Long runId, Map step, + String previousOutput) throws StepFailure { + String stepId = String.valueOf(step.getOrDefault("id", "step")); + String executorType = String.valueOf(step.getOrDefault("executor", "")); + + WikiPipelineStepRunEntity stepRun = new WikiPipelineStepRunEntity(); + stepRun.setRunId(runId); + stepRun.setStepId(stepId); + stepRun.setExecutor(executorType); + stepRun.setStatus("running"); + stepRun.setStartedAt(LocalDateTime.now()); + stepRun.setCreateTime(LocalDateTime.now()); + stepRunMapper.insert(stepRun); + + WikiStepExecutor executor = executors.get(executorType); + if (executor == null) { + String msg = "No executor registered for type '" + executorType + "'"; + failStep(stepRun, msg); + throw new StepFailure(msg); + } + try { + @SuppressWarnings("unchecked") + Map config = step.get("config") instanceof Map + ? (Map) step.get("config") : Map.of(); + String output = executor.execute(new WikiStepContext( + def.getKbId(), def.getOwnerAgentId(), stepId, config, previousOutput)); + stepRun.setStatus("succeeded"); + stepRun.setOutputJson(output); + stepRun.setFinishedAt(LocalDateTime.now()); + stepRunMapper.updateById(stepRun); + return output; + } catch (Exception e) { + String msg = "Step '" + stepId + "' failed: " + e.getMessage(); + failStep(stepRun, msg); + throw new StepFailure(msg); + } + } + + private void failStep(WikiPipelineStepRunEntity stepRun, String message) { + stepRun.setStatus("failed"); + stepRun.setErrorMessage(truncate(message)); + stepRun.setFinishedAt(LocalDateTime.now()); + stepRunMapper.updateById(stepRun); + } + + private void finishRun(WikiPipelineRunEntity run, String status, String output, String error) { + run.setStatus(status); + run.setOutputJson(output); + run.setErrorMessage(truncate(error)); + run.setFinishedAt(LocalDateTime.now()); + runMapper.updateById(run); + } + + private List> parseSteps(String stepsJson) { + if (stepsJson == null || stepsJson.isBlank()) { + return List.of(); + } + try { + return objectMapper.readValue(stepsJson, new TypeReference>>() {}); + } catch (Exception e) { + log.warn("[WikiPipeline] unparseable steps_json: {}", e.getMessage()); + return List.of(); + } + } + + private static String truncate(String s) { + if (s == null) { + return null; + } + return s.length() > 2000 ? s.substring(0, 2000) : s; + } + + /** Internal control-flow signal that a step failed and the run should stop. */ + private static final class StepFailure extends Exception { + StepFailure(String message) { + super(message); + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListener.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListener.java new file mode 100644 index 00000000..945b637e --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListener.java @@ -0,0 +1,39 @@ +package vip.mate.wiki.pipeline; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.context.event.EventListener; +import org.springframework.scheduling.annotation.Async; +import org.springframework.stereotype.Component; +import vip.mate.wiki.event.WikiPageCreatedEvent; + +/** + * Evaluates count-threshold pipeline triggers asynchronously when a page is + * created during ingest. Runs off the ingest thread so a fired pipeline (which + * may call a model) never blocks ingest; the page is already committed when the + * event fires, so the count is accurate, and the run dedup key keeps repeated + * evaluation idempotent. + * + * @author MateClaw Team + */ +@Slf4j +@Component +public class WikiPipelineTriggerListener { + + private final WikiPipelineTriggerService triggerService; + + public WikiPipelineTriggerListener(WikiPipelineTriggerService triggerService) { + this.triggerService = triggerService; + } + + @Async + @EventListener + public void onPageCreated(WikiPageCreatedEvent event) { + try { + triggerService.onPageTypeCount(event.kbId(), event.pageType()); + triggerService.onPageCreated(event.kbId(), event.pageType(), event.pageId()); + } catch (Exception e) { + log.warn("[WikiPipeline] trigger evaluation failed for kb={} pageType={}: {}", + event.kbId(), event.pageType(), e.getMessage()); + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerService.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerService.java new file mode 100644 index 00000000..6df3fbf1 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiPipelineTriggerService.java @@ -0,0 +1,144 @@ +package vip.mate.wiki.pipeline; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; +import vip.mate.wiki.repository.WikiPageMapper; +import vip.mate.wiki.repository.WikiPipelineDefinitionMapper; + +import java.util.List; + +/** + * Evaluates {@code page_type_count} pipeline triggers: when a KB accumulates a + * multiple of the configured threshold of a given pageType, the matching + * pipeline definitions fire once per threshold bucket. + * + *

    The bucket is {@code count / threshold}; the run table's unique key makes + * each bucket fire at most once, so re-evaluating on every page create is safe + * and idempotent across instances. + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiPipelineTriggerService { + + private static final String TRIGGER_PAGE_TYPE_COUNT = "page_type_count"; + + private final WikiPipelineDefinitionMapper definitionMapper; + private final WikiPipelineService pipelineService; + private final WikiPageMapper pageMapper; + private final ObjectMapper objectMapper; + + public WikiPipelineTriggerService(WikiPipelineDefinitionMapper definitionMapper, + WikiPipelineService pipelineService, + WikiPageMapper pageMapper, + ObjectMapper objectMapper) { + this.definitionMapper = definitionMapper; + this.pipelineService = pipelineService; + this.pageMapper = pageMapper; + this.objectMapper = objectMapper; + } + + /** + * Re-evaluate count-threshold pipelines for a KB / pageType. Returns the + * number of runs actually started (0 when no threshold bucket was newly + * crossed). Safe to call after every page create. + */ + /** + * Fire {@code page_created} definitions once per matching page creation + * (deduped by page id). Optional {@code page_type} in the trigger config + * narrows which page types fire. Returns the number of runs started. + */ + public int onPageCreated(Long kbId, String pageType, Long pageId) { + if (kbId == null || pageType == null || pageId == null) { + return 0; + } + List defs = definitionMapper.selectList( + new LambdaQueryWrapper() + .eq(WikiPipelineDefinitionEntity::getKbId, kbId) + .eq(WikiPipelineDefinitionEntity::getTriggerType, "page_created") + .eq(WikiPipelineDefinitionEntity::getEnabled, 1)); + int started = 0; + for (WikiPipelineDefinitionEntity def : defs) { + TriggerConfig cfg = parseConfig(def.getTriggerConfigJson()); + if (cfg != null && cfg.pageType != null && !pageType.equalsIgnoreCase(cfg.pageType)) { + continue; // type filter set and doesn't match + } + String input = "{\"pageType\":\"" + pageType + "\",\"pageId\":\"" + pageId + "\"}"; + WikiPipelineService.RunOutcome outcome = + pipelineService.execute(def, pageType, "page:" + pageId, input); + if (!outcome.duplicate() && outcome.run() != null) { + started++; + } + } + return started; + } + + public int onPageTypeCount(Long kbId, String pageType) { + if (kbId == null || pageType == null || pageType.isBlank()) { + return 0; + } + List defs = definitionMapper.selectList( + new LambdaQueryWrapper() + .eq(WikiPipelineDefinitionEntity::getKbId, kbId) + .eq(WikiPipelineDefinitionEntity::getTriggerType, TRIGGER_PAGE_TYPE_COUNT) + .eq(WikiPipelineDefinitionEntity::getEnabled, 1)); + if (defs.isEmpty()) { + return 0; + } + int started = 0; + for (WikiPipelineDefinitionEntity def : defs) { + TriggerConfig cfg = parseConfig(def.getTriggerConfigJson()); + if (cfg == null || cfg.threshold <= 0 || !pageType.equalsIgnoreCase(cfg.pageType)) { + continue; + } + long count = countPagesOfType(kbId, cfg.pageType); + long bucket = count / cfg.threshold; + if (bucket < 1) { + continue; // threshold not reached yet + } + String input = "{\"pageType\":\"" + cfg.pageType + "\",\"count\":" + count + "}"; + WikiPipelineService.RunOutcome outcome = + pipelineService.execute(def, cfg.pageType, String.valueOf(bucket), input); + if (!outcome.duplicate() && outcome.run() != null) { + started++; + log.info("[WikiPipeline] trigger fired: def={} pageType={} count={} bucket={}", + def.getId(), cfg.pageType, count, bucket); + } + } + return started; + } + + private long countPagesOfType(Long kbId, String pageType) { + return pageMapper.selectCount(new LambdaQueryWrapper() + .eq(WikiPageEntity::getKbId, kbId) + .eq(WikiPageEntity::getPageType, pageType.toLowerCase()) + .and(w -> w.ne(WikiPageEntity::getArchived, 1).or().isNull(WikiPageEntity::getArchived))); + } + + private TriggerConfig parseConfig(String json) { + if (json == null || json.isBlank()) { + return null; + } + try { + JsonNode node = objectMapper.readTree(json); + TriggerConfig cfg = new TriggerConfig(); + cfg.pageType = node.path("page_type").asText(null); + cfg.threshold = node.path("threshold").asInt(0); + return cfg.pageType == null ? null : cfg; + } catch (Exception e) { + log.warn("[WikiPipeline] bad trigger config: {}", e.getMessage()); + return null; + } + } + + private static final class TriggerConfig { + private String pageType; + private int threshold; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiSkillStepExecutor.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiSkillStepExecutor.java new file mode 100644 index 00000000..b3445e59 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiSkillStepExecutor.java @@ -0,0 +1,73 @@ +package vip.mate.wiki.pipeline; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; +import vip.mate.skill.model.SkillEntity; +import vip.mate.skill.service.SkillService; + +import java.util.Set; + +/** + * Pipeline step executor that resolves a registered skill and contributes its + * declarative content to the chain. + * + *

    Scope (MVP, security-restricted): the skill must be installed, + * enabled and not have a failed/blocked security scan. This executor injects + * the skill's instructions/content as the step output; it deliberately does + * not execute skill scripts — arbitrary script execution from a + * system-triggered pipeline requires a real sandbox and a separate security + * review (the same constraint that keeps a Python executor out of the MVP). + * + * @author MateClaw Team + */ +@Slf4j +@Component +public class WikiSkillStepExecutor implements WikiStepExecutor { + + private static final Set BLOCKED_SCAN_STATUSES = Set.of("FAILED", "BLOCKED", "REJECTED"); + + private final SkillService skillService; + + public WikiSkillStepExecutor(SkillService skillService) { + this.skillService = skillService; + } + + @Override + public String type() { + return "skill"; + } + + @Override + public String execute(WikiStepContext context) { + String skillName = context.stepConfig() == null ? null + : (String) (context.stepConfig().get("skill") instanceof String s ? s : null); + if (skillName == null || skillName.isBlank()) { + throw new IllegalArgumentException("skill step '" + context.stepId() + "' has no skill name"); + } + SkillEntity skill = skillService.findByName(skillName); + if (skill == null) { + throw new IllegalArgumentException("Skill not found: " + skillName); + } + if (Boolean.FALSE.equals(skill.getEnabled())) { + throw new IllegalStateException("Skill is disabled: " + skillName); + } + String scan = skill.getSecurityScanStatus(); + if (scan != null && BLOCKED_SCAN_STATUSES.contains(scan.trim().toUpperCase())) { + throw new IllegalStateException("Skill failed its security scan and cannot run in a pipeline: " + + skillName + " (" + scan + ")"); + } + // Reject any attempt to run the skill's script from a pipeline — not in MVP. + Object runScript = context.stepConfig().get("run_script"); + if (Boolean.TRUE.equals(runScript) || "true".equalsIgnoreCase(String.valueOf(runScript))) { + throw new IllegalStateException("Script execution is not permitted for pipeline skill steps " + + "(requires a sandbox + approval); skill: " + skillName); + } + String content = skill.getSkillContent(); + if (content == null || content.isBlank()) { + content = skill.getDescription(); + } + log.info("[WikiPipeline] skill step '{}' contributed content from skill '{}'", + context.stepId(), skillName); + return content == null ? "" : content; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepContext.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepContext.java new file mode 100644 index 00000000..b67e2022 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepContext.java @@ -0,0 +1,18 @@ +package vip.mate.wiki.pipeline; + +import java.util.Map; + +/** + * Inputs available to a {@link WikiStepExecutor}: the KB, the owner agent the + * step runs under (for permission checks), the step's declared config, and the + * output of the previous step. + * + * @author MateClaw Team + */ +public record WikiStepContext( + Long kbId, + Long ownerAgentId, + String stepId, + Map stepConfig, + String previousOutput) { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepExecutor.java b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepExecutor.java new file mode 100644 index 00000000..a28ef541 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/pipeline/WikiStepExecutor.java @@ -0,0 +1,24 @@ +package vip.mate.wiki.pipeline; + +/** + * Executes one pipeline step of a given kind. Implementations register their + * {@link #type()} (e.g. {@code llm}, {@code skill}); the pipeline service + * dispatches each step to the matching executor. + * + *

    Python execution is intentionally not provided here — it requires a real + * OS sandbox and a separate security review, and is out of the MVP. + * + * @author MateClaw Team + */ +public interface WikiStepExecutor { + + /** The executor kind this handles, matched against a step's {@code executor}. */ + String type(); + + /** + * Run the step and return its textual output. + * + * @throws Exception on failure — the pipeline records the step as failed + */ + String execute(WikiStepContext context) throws Exception; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiFieldSchema.java b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiFieldSchema.java new file mode 100644 index 00000000..cc7957ac --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiFieldSchema.java @@ -0,0 +1,25 @@ +package vip.mate.wiki.profile; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import lombok.Data; + +import java.util.List; + +/** + * Schema for one pageType metadata field within a {@link WikiPageTypeDef}. + * + * @author MateClaw Team + */ +@Data +@JsonIgnoreProperties(ignoreUnknown = true) +public class WikiFieldSchema { + + /** Field type: string / number / boolean / date / enum / string_array. */ + private String type; + + /** Whether the field must be present and non-empty. */ + private boolean required; + + /** Allowed values when {@link #type} is {@code enum}. */ + private List values; +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiMetadataValidator.java b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiMetadataValidator.java new file mode 100644 index 00000000..7677fa83 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiMetadataValidator.java @@ -0,0 +1,183 @@ +package vip.mate.wiki.profile; + +import lombok.Data; +import org.springframework.stereotype.Service; + +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.regex.Pattern; + +/** + * Validates a page's raw metadata against its pageType field schema. + * + *

    Policy (non-blocking — ingest is never failed by metadata issues): + *

      + *
    • Required field missing → {@code warning}, field omitted.
      • + *
    • Type mismatch → attempt light coercion; on failure keep the raw value + * and emit a warning.
      • + *
    • Undeclared field → dropped unless the profile allows additional + * fields; a dropped field always emits a warning.
      • + *
    • Enum value outside the allowed set / malformed date → warning, value + * kept as-is.
      • + *
    + * + * @author MateClaw Team + */ +@Service +public class WikiMetadataValidator { + + private static final Pattern ISO_DATE = Pattern.compile("\\d{4}-\\d{2}-\\d{2}"); + + /** Validation status persisted to {@code metadata_validation_status}. */ + public static final String OK = "ok"; + public static final String WARNING = "warning"; + + /** One validation warning. Serialized to {@code metadata_validation_json}. */ + @Data + public static class FieldWarning { + private final String field; + private final String reason; + private final String source; + private final String rawValuePreview; + } + + @Data + public static class ValidationResult { + private final Map cleaned; + private final String status; + private final List warnings; + } + + /** + * Validate {@code raw} metadata against {@code def}'s schema. + * + * @param def the pageType definition (may be {@code null} → no schema) + * @param raw the raw metadata produced by the LLM (may be {@code null}) + * @param allowAdditional whether undeclared fields are kept + * @param source stage label recorded on each warning (route/create/merge) + */ + public ValidationResult validate(WikiPageTypeDef def, Map raw, + boolean allowAdditional, String source) { + Map cleaned = new LinkedHashMap<>(); + List warnings = new ArrayList<>(); + Map input = raw == null ? Map.of() : raw; + Map schema = (def == null || def.getSchema() == null) + ? Map.of() : def.getSchema(); + + // 1. Declared fields: validate / coerce in schema order. + for (Map.Entry entry : schema.entrySet()) { + String field = entry.getKey(); + WikiFieldSchema fieldSchema = entry.getValue(); + boolean present = input.containsKey(field) && input.get(field) != null; + if (!present) { + if (fieldSchema.isRequired()) { + warnings.add(new FieldWarning(field, "required field missing", source, null)); + } + continue; + } + Object value = input.get(field); + Coerced coerced = coerce(fieldSchema, value); + if (coerced.warning != null) { + warnings.add(new FieldWarning(field, coerced.warning, source, preview(value))); + } + cleaned.put(field, coerced.value); + } + + // 2. Undeclared fields: keep or drop. + for (Map.Entry entry : input.entrySet()) { + String field = entry.getKey(); + if (schema.containsKey(field)) { + continue; + } + if (allowAdditional) { + cleaned.put(field, entry.getValue()); + } else { + warnings.add(new FieldWarning(field, "dropped: not declared in schema", + source, preview(entry.getValue()))); + } + } + + String status = warnings.isEmpty() ? OK : WARNING; + return new ValidationResult(cleaned, status, warnings); + } + + private record Coerced(Object value, String warning) {} + + private Coerced coerce(WikiFieldSchema schema, Object value) { + String type = schema.getType() == null ? "string" : schema.getType().trim().toLowerCase(); + return switch (type) { + case "string" -> new Coerced(String.valueOf(value), null); + case "number" -> coerceNumber(value); + case "boolean" -> coerceBoolean(value); + case "date" -> coerceDate(value); + case "enum" -> coerceEnum(schema, value); + case "string_array" -> coerceStringArray(value); + default -> new Coerced(value, null); + }; + } + + private Coerced coerceNumber(Object value) { + if (value instanceof Number) { + return new Coerced(value, null); + } + try { + String s = String.valueOf(value).trim(); + if (s.contains(".")) { + return new Coerced(Double.parseDouble(s), null); + } + return new Coerced(Long.parseLong(s), null); + } catch (NumberFormatException e) { + return new Coerced(value, "expected number"); + } + } + + private Coerced coerceBoolean(Object value) { + if (value instanceof Boolean) { + return new Coerced(value, null); + } + String s = String.valueOf(value).trim().toLowerCase(); + if ("true".equals(s) || "false".equals(s)) { + return new Coerced(Boolean.valueOf(s), null); + } + return new Coerced(value, "expected boolean"); + } + + private Coerced coerceDate(Object value) { + String s = String.valueOf(value).trim(); + if (ISO_DATE.matcher(s).matches()) { + return new Coerced(s, null); + } + return new Coerced(value, "expected ISO date YYYY-MM-DD"); + } + + private Coerced coerceEnum(WikiFieldSchema schema, Object value) { + String s = String.valueOf(value); + List values = schema.getValues(); + if (values == null || values.contains(s)) { + return new Coerced(s, null); + } + return new Coerced(s, "value not in allowed enum set"); + } + + private Coerced coerceStringArray(Object value) { + if (value instanceof List list) { + List out = new ArrayList<>(list.size()); + for (Object o : list) { + out.add(String.valueOf(o)); + } + return new Coerced(out, null); + } + // A single scalar is accepted as a one-element array. + return new Coerced(List.of(String.valueOf(value)), null); + } + + private static String preview(Object value) { + if (value == null) { + return null; + } + String s = String.valueOf(value); + return s.length() > 120 ? s.substring(0, 120) + "…" : s; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeDef.java b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeDef.java new file mode 100644 index 00000000..15b03b53 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeDef.java @@ -0,0 +1,58 @@ +package vip.mate.wiki.profile; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import lombok.Data; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** + * Definition of a single pageType within a {@link WikiPageTypeProfile}: + * a human label, optional description, the metadata field schema, the + * per-stage LLM instructions and an optional Markdown template. + * + * @author MateClaw Team + */ +@Data +@JsonIgnoreProperties(ignoreUnknown = true) +public class WikiPageTypeDef { + + /** Human-readable label, e.g. "Episode". */ + private String label; + + /** Short description of what this page type represents. */ + private String description; + + /** + * Knowledge layer this page type belongs to: {@code fact} ("what is") or + * {@code experience} ("what it means"). Extensible — MVP recognises these + * two; {@code null} means unspecified (treated as fact for retrieval). + */ + private String layer; + + /** Field name → schema. Insertion order preserved for prompt rendering. */ + private Map schema = new LinkedHashMap<>(); + + /** Optional stage instructions for route / create / merge. */ + private StageInstructions route; + private StageInstructions create; + private StageInstructions merge; + + /** Optional Markdown template metadata. */ + private Template template; + + @Data + @JsonIgnoreProperties(ignoreUnknown = true) + public static class StageInstructions { + private String instructions; + /** Optional template key referenced by the create stage. */ + private String template; + } + + @Data + @JsonIgnoreProperties(ignoreUnknown = true) + public static class Template { + private String key; + private String markdown; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfile.java b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfile.java new file mode 100644 index 00000000..32de2be7 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfile.java @@ -0,0 +1,54 @@ +package vip.mate.wiki.profile; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import lombok.Data; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** + * A parsed KB pageType profile: the page types a KB recognises plus + * profile-wide options. Deserialized from a profile row's {@code config_json} + * or supplied as the built-in default by + * {@link WikiPageTypeProfileService}. + * + * @author MateClaw Team + */ +@Data +@JsonIgnoreProperties(ignoreUnknown = true) +public class WikiPageTypeProfile { + + /** Config schema version. */ + private int version = 1; + + /** pageType name (lowercase) → definition. Insertion order preserved. */ + private Map pageTypes = new LinkedHashMap<>(); + + /** + * When a routed/created page declares a type absent from {@link #pageTypes}, + * it is downgraded to this type. Defaults to {@code concept}. + */ + private String fallbackType = "concept"; + + /** + * When {@code true}, metadata fields not declared in a type's schema are + * kept; otherwise they are dropped (with a validation warning). + */ + private boolean allowAdditionalFields = false; + + /** Whether this profile declares the given pageType (case-insensitive). */ + public boolean hasPageType(String pageType) { + if (pageType == null) { + return false; + } + return pageTypes.containsKey(pageType.trim().toLowerCase()); + } + + /** Lookup a definition by name (case-insensitive), or {@code null}. */ + public WikiPageTypeDef get(String pageType) { + if (pageType == null) { + return null; + } + return pageTypes.get(pageType.trim().toLowerCase()); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfileService.java b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfileService.java new file mode 100644 index 00000000..a0592eaa --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/profile/WikiPageTypeProfileService.java @@ -0,0 +1,297 @@ +package vip.mate.wiki.profile; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.fasterxml.jackson.databind.ObjectMapper; +import jakarta.annotation.PostConstruct; +import lombok.extern.slf4j.Slf4j; +import org.springframework.core.io.ClassPathResource; +import org.springframework.stereotype.Service; +import vip.mate.wiki.model.WikiPageTypeProfileEntity; +import vip.mate.wiki.repository.WikiPageTypeProfileMapper; + +import java.io.InputStream; +import java.util.Map; +import java.util.Set; + +/** + * Resolves the effective pageType profile for a knowledge base. + * + *

    Resolution: the KB's single enabled {@code mate_wiki_page_type_profile} + * row (parsed from {@code config_json}); when absent or unparseable, the + * built-in default profile loaded from + * {@code classpath:prompts/wiki/default-page-type-profile.json}. The default + * is never stored as a row — existing KBs keep working with zero migration. + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiPageTypeProfileService { + + private static final String DEFAULT_RESOURCE = "prompts/wiki/default-page-type-profile.json"; + + private final WikiPageTypeProfileMapper profileMapper; + private final ObjectMapper objectMapper; + + /** Parsed once at startup; immutable thereafter. */ + private WikiPageTypeProfile defaultProfile; + + public WikiPageTypeProfileService(WikiPageTypeProfileMapper profileMapper, ObjectMapper objectMapper) { + this.profileMapper = profileMapper; + this.objectMapper = objectMapper; + } + + @PostConstruct + void loadDefault() { + try (InputStream in = new ClassPathResource(DEFAULT_RESOURCE).getInputStream()) { + this.defaultProfile = objectMapper.readValue(in, WikiPageTypeProfile.class); + } catch (Exception e) { + log.error("[WikiProfile] Failed to load default pageType profile from {} — " + + "falling back to an empty profile", DEFAULT_RESOURCE, e); + this.defaultProfile = new WikiPageTypeProfile(); + } + } + + /** The built-in default profile (shared, do not mutate). */ + public WikiPageTypeProfile getDefaultProfile() { + return defaultProfile; + } + + /** + * The effective profile for a KB: its enabled profile row, or the built-in + * default when none is configured (or the stored config fails to parse). + */ + public WikiPageTypeProfile resolveProfile(Long kbId) { + if (kbId == null) { + return defaultProfile; + } + WikiPageTypeProfileEntity row = profileMapper.selectOne( + new LambdaQueryWrapper() + .eq(WikiPageTypeProfileEntity::getKbId, kbId) + .eq(WikiPageTypeProfileEntity::getEnabled, 1) + .last("LIMIT 1")); + if (row == null || row.getConfigJson() == null || row.getConfigJson().isBlank()) { + return defaultProfile; + } + try { + WikiPageTypeProfile parsed = objectMapper.readValue(row.getConfigJson(), WikiPageTypeProfile.class); + // Carry the stored row version so callers can stamp page.profile_version. + parsed.setVersion(row.getVersion() != null ? row.getVersion() : parsed.getVersion()); + return parsed; + } catch (Exception e) { + log.warn("[WikiProfile] KB {} has an unparseable profile config — using default. {}", + kbId, e.getMessage()); + return defaultProfile; + } + } + + /** The set of pageType names allowed for a KB (lowercase). */ + public Set allowedPageTypes(Long kbId) { + return resolveProfile(kbId).getPageTypes().keySet(); + } + + /** + * The knowledge layer for a pageType: {@code fact} / {@code experience}. + * A known type with no declared layer defaults to {@code fact} (RFC default, + * keeps legacy types factual); an unknown/blank type returns {@code null} + * so the caller leaves the page's layer untouched. + */ + public String resolveLayer(Long kbId, String pageType) { + WikiPageTypeDef def = resolveProfile(kbId).get(pageType); + if (def == null) { + return null; + } + String layer = def.getLayer(); + return (layer == null || layer.isBlank()) ? "fact" : layer.trim().toLowerCase(); + } + + /** Whether a pageType is in the experience layer (vs fact). */ + public boolean isExperience(Long kbId, String pageType) { + return "experience".equals(resolveLayer(kbId, pageType)); + } + + /** + * The per-stage LLM instruction declared for a pageType, or empty string. + * {@code stage} is {@code route} / {@code create} / {@code merge}. Used to + * inject type-specific guidance into the corresponding stage prompt. + */ + public String stageInstruction(Long kbId, String pageType, String stage) { + WikiPageTypeDef def = resolveProfile(kbId).get(pageType); + if (def == null || stage == null) { + return ""; + } + WikiPageTypeDef.StageInstructions si = switch (stage) { + case "route" -> def.getRoute(); + case "create" -> def.getCreate(); + case "merge" -> def.getMerge(); + default -> null; + }; + return (si != null && si.getInstructions() != null) ? si.getInstructions().trim() : ""; + } + + /** + * Render the per-type Markdown templates as a prompt block for the + * multi-page batch-create stage (where one call generates pages of several + * types). Only types that declare a template are listed; empty when none. + */ + public String describeTemplatesForPrompt(Long kbId) { + WikiPageTypeProfile profile = resolveProfile(kbId); + StringBuilder sb = new StringBuilder(); + profile.getPageTypes().forEach((name, def) -> { + if (def != null && def.getTemplate() != null + && def.getTemplate().getMarkdown() != null + && !def.getTemplate().getMarkdown().isBlank()) { + sb.append("### ").append(name).append(" 骨架\n") + .append(def.getTemplate().getMarkdown().trim()).append("\n\n"); + } + }); + return sb.toString().trim(); + } + + /** + * The Markdown content template for a pageType, or empty string. Injected + * into the generation prompt so the page follows the declared skeleton. + */ + public String templateMarkdown(Long kbId, String pageType) { + WikiPageTypeDef def = resolveProfile(kbId).get(pageType); + if (def == null || def.getTemplate() == null || def.getTemplate().getMarkdown() == null) { + return ""; + } + return def.getTemplate().getMarkdown().trim(); + } + + /** + * Render the KB's allowed page types as a prompt fragment, one per line + * with description and required-metadata hints, e.g. + * {@code - episode: a dated event (required metadata: event_type, event_date)}. + * Injected into the route / batch-create prompts so the LLM only emits + * types the KB recognises. + */ + public String describeForPrompt(Long kbId) { + WikiPageTypeProfile profile = resolveProfile(kbId); + StringBuilder sb = new StringBuilder(); + profile.getPageTypes().forEach((name, def) -> { + sb.append("- ").append(name); + if (def != null && def.getDescription() != null && !def.getDescription().isBlank()) { + sb.append(": ").append(def.getDescription().trim()); + } + if (def != null && def.getSchema() != null) { + java.util.List required = def.getSchema().entrySet().stream() + .filter(e -> e.getValue() != null && e.getValue().isRequired()) + .map(Map.Entry::getKey) + .toList(); + if (!required.isEmpty()) { + sb.append(" (required metadata: ").append(String.join(", ", required)).append(")"); + } + } + sb.append('\n'); + }); + return sb.toString().trim(); + } + + /** The enabled profile row for a KB, or {@code null} when none configured. */ + public WikiPageTypeProfileEntity findEnabledRow(Long kbId) { + if (kbId == null) { + return null; + } + return profileMapper.selectOne( + new LambdaQueryWrapper() + .eq(WikiPageTypeProfileEntity::getKbId, kbId) + .eq(WikiPageTypeProfileEntity::getEnabled, 1) + .last("LIMIT 1")); + } + + /** + * Persist a KB profile. Parses {@code configJson} first (rejecting invalid + * JSON), then upserts the KB's single enabled row — updating in place and + * bumping its version when one exists, else inserting a new enabled row. + * + * @throws IllegalArgumentException when {@code configJson} does not parse + */ + public void saveProfile(Long kbId, String name, String configJson) { + try { + objectMapper.readValue(configJson, WikiPageTypeProfile.class); + } catch (Exception e) { + throw new IllegalArgumentException("Invalid profile config JSON: " + e.getMessage()); + } + WikiPageTypeProfileEntity existing = findEnabledRow(kbId); + if (existing != null) { + existing.setConfigJson(configJson); + if (name != null && !name.isBlank()) { + existing.setName(name); + } + existing.setVersion((existing.getVersion() == null ? 1 : existing.getVersion()) + 1); + profileMapper.updateById(existing); + } else { + WikiPageTypeProfileEntity row = new WikiPageTypeProfileEntity(); + row.setKbId(kbId); + row.setName(name == null || name.isBlank() ? "default" : name); + row.setVersion(1); + row.setConfigJson(configJson); + row.setEnabled(1); + profileMapper.insert(row); + } + } + + /** + * Reset a KB to the built-in default by removing its profile rows, so + * {@link #resolveProfile} falls back to the default. Logical delete. + */ + public void resetToDefault(Long kbId) { + if (kbId == null) { + return; + } + profileMapper.delete(new LambdaQueryWrapper() + .eq(WikiPageTypeProfileEntity::getKbId, kbId)); + } + + /** + * Structurally validate a profile JSON without persisting it. Returns a + * list of human-readable issues; empty means valid. + */ + public java.util.List validateProfileJson(String configJson) { + java.util.List issues = new java.util.ArrayList<>(); + WikiPageTypeProfile profile; + try { + profile = objectMapper.readValue(configJson, WikiPageTypeProfile.class); + } catch (Exception e) { + issues.add("Invalid JSON: " + e.getMessage()); + return issues; + } + if (profile.getPageTypes() == null || profile.getPageTypes().isEmpty()) { + issues.add("Profile declares no pageTypes"); + return issues; + } + java.util.Set validTypes = java.util.Set.of( + "string", "number", "boolean", "date", "enum", "string_array"); + profile.getPageTypes().forEach((typeName, def) -> { + if (def.getSchema() == null) { + return; + } + def.getSchema().forEach((fieldName, fieldSchema) -> { + String t = fieldSchema.getType(); + if (t == null || !validTypes.contains(t.trim().toLowerCase())) { + issues.add(typeName + "." + fieldName + ": unknown field type '" + t + "'"); + } else if ("enum".equalsIgnoreCase(t.trim()) + && (fieldSchema.getValues() == null || fieldSchema.getValues().isEmpty())) { + issues.add(typeName + "." + fieldName + ": enum field declares no values"); + } + }); + }); + return issues; + } + + /** + * Normalise a routed/created pageType against the KB profile: a declared + * type is returned as-is (lowercase); an unknown type is downgraded to the + * profile's {@code fallbackType}. Never returns null. + */ + public String normalizePageType(Long kbId, String pageType) { + WikiPageTypeProfile profile = resolveProfile(kbId); + if (pageType != null && profile.hasPageType(pageType)) { + return pageType.trim().toLowerCase(); + } + String fallback = profile.getFallbackType(); + return fallback == null ? "concept" : fallback.trim().toLowerCase(); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiAgentPageTypePermissionMapper.java b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiAgentPageTypePermissionMapper.java new file mode 100644 index 00000000..2e6e21bc --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiAgentPageTypePermissionMapper.java @@ -0,0 +1,14 @@ +package vip.mate.wiki.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import vip.mate.wiki.model.WikiAgentPageTypePermissionEntity; + +/** + * Mapper for {@link WikiAgentPageTypePermissionEntity}. + * + * @author MateClaw Team + */ +@Mapper +public interface WikiAgentPageTypePermissionMapper extends BaseMapper { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageDependencyMapper.java b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageDependencyMapper.java new file mode 100644 index 00000000..ac9b1863 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageDependencyMapper.java @@ -0,0 +1,14 @@ +package vip.mate.wiki.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import vip.mate.wiki.model.WikiPageDependencyEntity; + +/** + * Mapper for {@link WikiPageDependencyEntity}. + * + * @author MateClaw Team + */ +@Mapper +public interface WikiPageDependencyMapper extends BaseMapper { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageMapper.java b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageMapper.java index 333d1a70..07141ba5 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageMapper.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageMapper.java @@ -53,6 +53,35 @@ public interface WikiPageMapper extends BaseMapper { @Select("SELECT content FROM mate_wiki_page WHERE id = #{id} AND deleted = 0") String selectContentById(@Param("id") Long id); + /** + * Candidate-set query for the cascade-delete / cascade-rename pipeline. + * Find every page in {@code kbId} whose {@code outgoing_links} JSON array + * might mention {@code slug}, using a LIKE pre-filter (works on both H2 + * and MySQL without a JSON_CONTAINS shim). The {@code slugPattern} should + * be {@code %""%} so the surrounding quotes pin the + * match to a full JSON string element rather than a substring; the + * caller still re-verifies each row by parsing the content with + * {@code WikiLinkService} because the actual rewrite must skip code + * blocks and ignore false-positive substring matches inside other JSON + * strings. + *

    + * SQL guard order: {@code kb_id} + {@code deleted} + {@code archived} + + * {@code id != excludeId} are all ANDed before the LIKE. The explicit + * prefix prevents a multi-tenant leak where a future OR-clause might + * accidentally cross KB boundaries. + */ + @Select("SELECT id, kb_id, slug, title, content, outgoing_links " + + "FROM mate_wiki_page " + + "WHERE kb_id = #{kbId} " + + " AND deleted = 0 " + + " AND archived = 0 " + + " AND id != #{excludeId} " + + " AND outgoing_links LIKE #{slugPattern}") + List findReferrersByOutgoingLink( + @Param("kbId") Long kbId, + @Param("excludeId") Long excludeId, + @Param("slugPattern") String slugPattern); + // ==================== RFC-032: Two-phase keyword search ==================== /** diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageTypeProfileMapper.java b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageTypeProfileMapper.java new file mode 100644 index 00000000..7dcfa43c --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPageTypeProfileMapper.java @@ -0,0 +1,14 @@ +package vip.mate.wiki.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import vip.mate.wiki.model.WikiPageTypeProfileEntity; + +/** + * Mapper for {@link WikiPageTypeProfileEntity}. + * + * @author MateClaw Team + */ +@Mapper +public interface WikiPageTypeProfileMapper extends BaseMapper { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineDefinitionMapper.java b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineDefinitionMapper.java new file mode 100644 index 00000000..3c46012a --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineDefinitionMapper.java @@ -0,0 +1,14 @@ +package vip.mate.wiki.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; + +/** + * Mapper for {@link WikiPipelineDefinitionEntity}. + * + * @author MateClaw Team + */ +@Mapper +public interface WikiPipelineDefinitionMapper extends BaseMapper { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineRunMapper.java b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineRunMapper.java new file mode 100644 index 00000000..f23c9dd8 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineRunMapper.java @@ -0,0 +1,14 @@ +package vip.mate.wiki.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import vip.mate.wiki.model.WikiPipelineRunEntity; + +/** + * Mapper for {@link WikiPipelineRunEntity}. + * + * @author MateClaw Team + */ +@Mapper +public interface WikiPipelineRunMapper extends BaseMapper { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineStepRunMapper.java b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineStepRunMapper.java new file mode 100644 index 00000000..a8f0b34e --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/repository/WikiPipelineStepRunMapper.java @@ -0,0 +1,14 @@ +package vip.mate.wiki.repository; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import org.apache.ibatis.annotations.Mapper; +import vip.mate.wiki.model.WikiPipelineStepRunEntity; + +/** + * Mapper for {@link WikiPipelineStepRunEntity}. + * + * @author MateClaw Team + */ +@Mapper +public interface WikiPipelineStepRunMapper extends BaseMapper { +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiContextService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiContextService.java index cfec94f7..4df4700a 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiContextService.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiContextService.java @@ -85,8 +85,12 @@ public class WikiContextService { } StringBuilder sb = new StringBuilder("\n"); - sb.append("[Relevant wiki pages for this query. Use wiki_read_page(slug) for full content. " + - "When using information from these pages in your answer, always cite the source page title, " + + sb.append("[Relevant pages from the shared knowledge base for this query. These are " + + "reference articles and may cover topics unrelated to this user — do NOT assume " + + "they describe the user's own project, identity, or current work. For who the user " + + "is and what they are working on, rely on instead; it takes " + + "precedence over these pages. Use wiki_read_page(slug) for full content. When using " + + "information from these pages in your answer, always cite the source page title, " + "e.g. 「来源：[[页面标题]]」or「(来源：页面标题)」.]\n\n"); int totalChars = 0; int maxChars = properties.getMaxContextChars(); @@ -138,15 +142,29 @@ public class WikiContextService { int totalChars = 0; int maxChars = properties.getMaxContextChars(); + // Each KB renders as a HEADING-ONLY block (### ) followed by a + // metadata line and its page list. The heading deliberately contains + // ONLY the KB name — no em-dash, no parenthesised page count, no + // description — so the LLM can safely copy the entire post-### text + // verbatim into the `kbName` tool argument. The previous form + // "### — (N pages)" let the LLM paste the + // whole row into kbName and break the exact-match lookup. + boolean multipleKbs = kbs.size() > 1; + for (WikiKnowledgeBaseEntity kb : kbs) { List pages = pageService.listSummaries(kb.getId()); if (pages.isEmpty()) continue; - sb.append("### ").append(kb.getName()); + // Heading: pure KB name. This is what `kbName` expects verbatim. + sb.append("### ").append(kb.getName()).append("\n"); + // Metadata line: page count first (easy to scan), then optional + // description. Lives on its own line so it can't be confused for + // part of the name. + sb.append(pages.size()).append(" pages"); if (kb.getDescription() != null && !kb.getDescription().isBlank()) { sb.append(" — ").append(kb.getDescription()); } - sb.append(" (").append(pages.size()).append(" pages)\n\n"); + sb.append("\n\n"); boolean compact = pages.size() > 20; @@ -172,6 +190,14 @@ public class WikiContextService { } sb.append("Use wiki_read_page(slug) for details. Use wiki_search_pages(query) to search.\n"); + if (multipleKbs) { + sb.append("Multiple knowledge bases visible — every wiki tool takes an ") + .append("optional `kbName` argument. Set it to the EXACT text after ") + .append("`### ` on the heading line (do NOT include the page count or ") + .append("description). When two KBs share a name, call wiki_list_kbs ") + .append("and pass `kbId` instead. Omit both and the tool falls back to ") + .append("the agent's primary KB, which may return 'page not found'.\n"); + } sb.append(""); return sb.toString(); diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDependencyService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDependencyService.java new file mode 100644 index 00000000..7b6fa869 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDependencyService.java @@ -0,0 +1,140 @@ +package vip.mate.wiki.service; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.fasterxml.jackson.databind.ObjectMapper; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import vip.mate.wiki.model.WikiPageDependencyEntity; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.repository.WikiPageDependencyMapper; +import vip.mate.wiki.repository.WikiPageMapper; + +import java.time.LocalDateTime; +import java.util.ArrayList; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Set; + +/** + * Maintains the experience→fact dependency graph and propagates staleness when + * a fact page changes. + * + *

    Dependencies are stored by page id. An edge is accepted only when the + * target is a {@code fact}-layer page in the same KB (cross-KB and + * experience→experience edges are rejected). When a fact page changes, every + * page depending on it is marked stale via a single batch update keyed on the + * reverse index, rather than per-row in the ingest transaction. + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiDependencyService { + + private final WikiPageDependencyMapper dependencyMapper; + private final WikiPageMapper pageMapper; + private final WikiPageService pageService; + private final ObjectMapper objectMapper; + + public WikiDependencyService(WikiPageDependencyMapper dependencyMapper, WikiPageMapper pageMapper, + WikiPageService pageService, ObjectMapper objectMapper) { + this.dependencyMapper = dependencyMapper; + this.pageMapper = pageMapper; + this.pageService = pageService; + this.objectMapper = objectMapper; + } + + /** + * Replace an experience page's fact dependencies. Rejected targets (missing, + * cross-KB, or non-fact) are skipped and returned so the caller can record a + * warning. The page's {@code depends_on_json} snapshot is refreshed too. + * + * @return the list of rejected target ids with a reason + */ + public List setDependencies(Long kbId, Long pageId, List dependsOnPageIds) { + List rejected = new ArrayList<>(); + Set accepted = new LinkedHashSet<>(); + if (dependsOnPageIds != null) { + for (Long target : dependsOnPageIds) { + if (target == null || target.equals(pageId)) { + continue; + } + WikiPageEntity targetPage = pageMapper.selectById(target); + if (targetPage == null || !kbId.equals(targetPage.getKbId())) { + rejected.add(target + ": not found in this KB"); + continue; + } + if (targetPage.getArchived() != null && targetPage.getArchived() == 1) { + rejected.add(target + ": archived"); + continue; + } + if (!isFactLayer(targetPage)) { + rejected.add(target + ": dependency target is not a fact-layer page"); + continue; + } + accepted.add(target); + } + } + + // Soft-delete existing edges for this page, then insert the accepted set. + dependencyMapper.delete(new LambdaQueryWrapper() + .eq(WikiPageDependencyEntity::getPageId, pageId)); + for (Long target : accepted) { + WikiPageDependencyEntity edge = new WikiPageDependencyEntity(); + edge.setKbId(kbId); + edge.setPageId(pageId); + edge.setDependsOnPageId(target); + edge.setDependencyType("fact"); + edge.setCreateTime(LocalDateTime.now()); + edge.setUpdateTime(LocalDateTime.now()); + dependencyMapper.insert(edge); + } + try { + String json = objectMapper.writeValueAsString(accepted); + pageService.setLayerAndDependencies(pageId, "experience", json); + } catch (Exception e) { + log.warn("[WikiDep] failed to write depends_on_json for page {}: {}", pageId, e.getMessage()); + } + return rejected; + } + + /** + * Mark every page depending on {@code factPageId} as stale. Returns the + * number of pages marked. Idempotent — re-running on already-stale pages is + * harmless. + */ + public int markDependentsStale(Long kbId, Long factPageId, String reason) { + List edges = dependencyMapper.selectList( + new LambdaQueryWrapper() + .eq(WikiPageDependencyEntity::getKbId, kbId) + .eq(WikiPageDependencyEntity::getDependsOnPageId, factPageId)); + if (edges.isEmpty()) { + return 0; + } + Set dependentIds = new LinkedHashSet<>(); + for (WikiPageDependencyEntity edge : edges) { + dependentIds.add(edge.getPageId()); + } + String reasonJson = buildReasonJson(factPageId, reason); + int marked = pageService.markStale(dependentIds, reasonJson); + log.info("[WikiDep] fact page {} changed -> marked {} dependent page(s) stale", factPageId, marked); + return marked; + } + + private boolean isFactLayer(WikiPageEntity page) { + String layer = page.getKnowledgeLayer(); + // Unspecified layer is treated as fact (RFC default), so legacy pages + // remain valid dependency targets. + return layer == null || layer.isBlank() || "fact".equalsIgnoreCase(layer.trim()); + } + + private String buildReasonJson(Long factPageId, String reason) { + try { + return objectMapper.writeValueAsString(java.util.Map.of( + "factPageId", String.valueOf(factPageId), + "reason", reason == null ? "fact page updated" : reason)); + } catch (Exception e) { + return "{\"factPageId\":\"" + factPageId + "\"}"; + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDirectoryScanService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDirectoryScanService.java index 46640b44..9978306d 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDirectoryScanService.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiDirectoryScanService.java @@ -29,6 +29,7 @@ public class WikiDirectoryScanService { private final WikiKnowledgeBaseService kbService; private final WikiRawMaterialService rawService; private final WikiProperties properties; + private final WikiSourcePathValidator pathValidator; private static final Set SUPPORTED_EXTENSIONS = Set.of( "txt", "md", "csv", "pdf", "docx", "doc", @@ -61,7 +62,14 @@ public class WikiDirectoryScanService { * 扫描指定目录，为每个支持的文件创建原始材料 */ public ScanResult scanDirectory(Long kbId, String directoryPath) { - Path dir = Paths.get(directoryPath).toAbsolutePath().normalize(); + Path dir; + try { + // Canonicalize (resolving symlinks) and enforce allowed-roots so a + // scan cannot read outside the authorized area. + dir = pathValidator.validateDirectory(directoryPath); + } catch (IllegalArgumentException e) { + return new ScanResult(0, 0, 0, List.of(e.getMessage())); + } if (!Files.exists(dir)) { return new ScanResult(0, 0, 0, List.of("Directory does not exist: " + dir)); @@ -125,34 +133,77 @@ public class WikiDirectoryScanService { for (Path file : files) { try { - String absolutePath = file.toAbsolutePath().normalize().toString(); - String fileName = file.getFileName().toString(); - String ext = getExtension(fileName); - - // 基于 sourcePath 去重 - WikiRawMaterialEntity existing = rawService.findBySourcePath(kbId, absolutePath); - if (existing != null) { + // Per-file symlink guard: a symlinked file inside an allowed + // directory could point outside it (e.g. secret.md -> + // /etc/passwd). Resolve the real path and require it to stay + // within the validated scan root; skip escapes. + Path realFile; + try { + realFile = file.toRealPath(); + } catch (IOException e) { + realFile = file.toAbsolutePath().normalize(); + } + if (!realFile.startsWith(dir)) { + errors.add("Skipped symlink escaping the scan root: " + file.getFileName()); skipped++; continue; } + // From here on operate ONLY on the resolved real path, never the + // original entry. Reading `realFile` (a concrete, fully-resolved + // path) closes the TOCTOU window: swapping the symlink after + // resolution cannot redirect the read. The file name for the + // title still comes from the directory entry the user sees. + // Re-check the size on the resolved target — walkFileTree does + // not follow links, so a symlink's attribute size (the link + // length) can slip an oversized target past the visitFile gate. + long realSize; + try { + realSize = Files.size(realFile); + } catch (IOException e) { + errors.add("Failed to stat: " + file.getFileName() + " (" + e.getMessage() + ")"); + skipped++; + continue; + } + if (realSize > properties.getMaxScanFileSize()) { + errors.add("Skipped oversized file: " + file.getFileName() + " (" + realSize + " bytes)"); + skipped++; + continue; + } + String absolutePath = realFile.toString(); + String fileName = file.getFileName().toString(); + String ext = getExtension(fileName); if (TEXT_EXTENSIONS.contains(ext)) { - // 文本文件：读取内容 - String content = Files.readString(file, StandardCharsets.UTF_8); - rawService.addText(kbId, fileName, content); - } else { - // 二进制文件：直接引用原始路径，不复制 - String sourceType = switch (ext) { - case "pdf" -> "pdf"; - case "docx", "doc" -> "docx"; - case "pptx", "ppt" -> "pptx"; - case "xlsx", "xls" -> "xlsx"; - case "html", "htm" -> "html"; - default -> "text"; - }; - rawService.addFile(kbId, fileName, sourceType, absolutePath, Files.size(file)); + // Text files: dedup by content hash, so an unchanged file is + // skipped while a modified file (new hash) is re-ingested. + String content = Files.readString(realFile, StandardCharsets.UTF_8); + boolean fresh = rawService.ingestTextFileFromScan(kbId, fileName, absolutePath, content); + if (fresh) { + added++; + } else { + skipped++; + } + continue; + } + + // Binary files: dedup by content hash too, so a modified file is + // re-ingested. The unchanged case reads the file once to hash it; + // only a new/changed file is read again to import. + String sourceType = switch (ext) { + case "pdf" -> "pdf"; + case "docx", "doc" -> "docx"; + case "pptx", "ppt" -> "pptx"; + case "xlsx", "xls" -> "xlsx"; + case "html", "htm" -> "html"; + default -> "text"; + }; + boolean freshBinary = rawService.ingestBinaryFileFromScan( + kbId, fileName, sourceType, absolutePath, realSize); + if (freshBinary) { + added++; + } else { + skipped++; } - added++; } catch (Exception e) { errors.add("Failed to import: " + file.getFileName() + " (" + e.getMessage() + ")"); diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiEnrichmentApplier.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiEnrichmentApplier.java index c0060166..4c1bfb1b 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiEnrichmentApplier.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiEnrichmentApplier.java @@ -41,13 +41,39 @@ public final class WikiEnrichmentApplier { private static final Pattern REPLACEMENT_SHAPE = Pattern.compile("^\\[\\[([^\\[\\]|]+)(?:\\|([^\\[\\]]+))?]]$"); + /** + * Fenced code block — matches a triple-backtick line up to the next one. + * Same shape used in {@link WikiLinkService} so the applier and the + * extractor agree on what counts as code. + */ + private static final Pattern FENCED_CODE = Pattern.compile( + "(?m)^```[\\s\\S]*?^```", Pattern.MULTILINE); + + /** Matches inline {@code `...`} spans. Non-greedy so adjacent spans stay separate. */ + private static final Pattern INLINE_CODE = Pattern.compile("`[^`\\n]*?`"); + private WikiEnrichmentApplier() {} public static Result apply(String originalContent, EnrichmentPlan plan) { - return apply(originalContent, plan, DEFAULT_MAX_REPLACEMENTS); + return apply(originalContent, plan, DEFAULT_MAX_REPLACEMENTS, null); } public static Result apply(String originalContent, EnrichmentPlan plan, int maxReplacements) { + return apply(originalContent, plan, maxReplacements, null); + } + + /** + * Apply with an optional KB slug whitelist. When {@code allowedSlugsLower} + * is non-null, any replacement whose target slug is not in the set is + * silently dropped rather than failing the whole plan — matches the RFC + * "validate + drop hallucinated targets" intent for analyze-driven + * generation and lets the rest of the plan still land. {@code null} + * disables the check (legacy behaviour for the existing batch enrich + * paths that already validate elsewhere). + */ + public static Result apply(String originalContent, EnrichmentPlan plan, + int maxReplacements, + java.util.Set allowedSlugsLower) { if (originalContent == null) return Result.rejected("content is null"); if (plan == null || plan.isEmpty()) { return Result.unchanged(originalContent); @@ -58,9 +84,12 @@ public final class WikiEnrichmentApplier { } // 1) Per-original index of all candidate positions in the original text, - // skipping positions that fall inside an existing wikilink. + // skipping positions that fall inside an existing wikilink OR inside + // a fenced/inline code block. The combined mask is what we test — + // a doc that teaches wikilink syntax inside ```fence``` must not + // have its examples silently wrapped. java.util.Map> positionsByOriginal = new java.util.HashMap<>(); - boolean[] insideWikilink = computeWikilinkMask(originalContent); + boolean[] skipMask = computeSkipMask(originalContent); // 2) Plan splices: for each replacement pick positions[occurrence-1]. List splices = new ArrayList<>(); // [start, end, replacementIndex] @@ -82,9 +111,17 @@ public final class WikiEnrichmentApplier { return Result.rejected("visible text mismatch: replacement='" + replacement + "' must render '" + original + "'"); } + // Whitelist gate (RFC §4 Phase 5): when the caller supplied an + // allowed slug set, drop entries that fall outside it instead of + // landing them. Matches the "do not invent slugs" rule on the + // analyze→generate path without aborting the rest of the plan. + if (allowedSlugsLower != null + && !allowedSlugsLower.contains(slug.toLowerCase(java.util.Locale.ROOT))) { + continue; + } List positions = positionsByOriginal.computeIfAbsent(original, - o -> findPositions(originalContent, o, insideWikilink)); + o -> findPositions(originalContent, o, skipMask)); int idx = r.occurrence() - 1; if (idx < 0 || idx >= positions.size()) { // Skip silently — the page may have been re-edited since the LLM saw it. @@ -151,15 +188,26 @@ public final class WikiEnrichmentApplier { return out.toString(); } - private static boolean[] computeWikilinkMask(String content) { + /** + * Combined "do not splice here" mask — true at every offset that lies + * inside an existing wikilink, a fenced code block, or an inline code + * span. Used to keep enrichment out of code examples and existing links. + */ + private static boolean[] computeSkipMask(String content) { boolean[] mask = new boolean[content.length()]; - Matcher m = WIKILINK.matcher(content); - while (m.find()) { - for (int i = m.start(); i < m.end(); i++) mask[i] = true; - } + markPattern(mask, content, WIKILINK); + markPattern(mask, content, FENCED_CODE); + markPattern(mask, content, INLINE_CODE); return mask; } + private static void markPattern(boolean[] mask, String content, Pattern pattern) { + Matcher m = pattern.matcher(content); + while (m.find()) { + for (int i = m.start(); i < m.end() && i < mask.length; i++) mask[i] = true; + } + } + private static List findPositions(String content, String needle, boolean[] insideWikilink) { List out = new ArrayList<>(); if (needle.isEmpty()) return out; diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiKnowledgeBaseService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiKnowledgeBaseService.java index bb142cab..49259d1c 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiKnowledgeBaseService.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiKnowledgeBaseService.java @@ -5,6 +5,8 @@ import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; +import vip.mate.agent.model.AgentEntity; +import vip.mate.agent.repository.AgentMapper; import vip.mate.wiki.job.model.WikiProcessingJobEntity; import vip.mate.wiki.model.WikiChunkEntity; import vip.mate.wiki.model.WikiKnowledgeBaseEntity; @@ -36,6 +38,7 @@ public class WikiKnowledgeBaseService { private final WikiChunkMapper chunkMapper; private final WikiPageCitationMapper citationMapper; private final WikiProcessingJobMapper processingJobMapper; + private final AgentMapper agentMapper; /** * RFC-051 PR-2: optional system-page scaffold (overview / log). Marked @@ -102,32 +105,42 @@ public class WikiKnowledgeBaseService { } /** - * 获取 Agent 可访问的知识库：Agent 专属 KB + 公共 KB（agent_id IS NULL） + * 获取 Agent 可访问的知识库。 + *

    + * Knowledge bases are workspace-shared. The agent's primary KB is stored + * on mate_agent.primary_kb_id and does not affect visibility. */ public List listByAgentId(Long agentId) { - return kbMapper.selectList( - new LambdaQueryWrapper() - .and(w -> w.eq(WikiKnowledgeBaseEntity::getAgentId, agentId) - .or().isNull(WikiKnowledgeBaseEntity::getAgentId)) - .orderByDesc(WikiKnowledgeBaseEntity::getUpdateTime)); + AgentEntity agent = getAgentOrNull(agentId); + if (agent == null || agent.getWorkspaceId() == null) { + return listAll(); + } + return listByWorkspace(agent.getWorkspaceId()); } /** * Resolve the single knowledge base an agent's wiki tools should operate on. *

    - * Prefers a KB explicitly bound to the agent; a shared (agent-less) KB is - * only used as a fallback when the agent has no bound KB of its own. This - * matters because {@link #listByAgentId} also returns shared KBs, and a - * shared KB with a more recent {@code update_time} would otherwise win the - * {@code get(0)} pick over the agent's own KB. Within each tier the most - * recently updated KB wins. Returns {@code null} when the agent can reach - * no knowledge base at all. + * Prefers mate_agent.primary_kb_id when it points to a KB in the same + * workspace. For legacy rows that predate primary_kb_id, falls back to the + * old mate_wiki_knowledge_base.agent_id marker only when no primary is set. + * Otherwise the most recently updated workspace KB wins. */ public WikiKnowledgeBaseEntity resolvePrimaryKb(Long agentId) { + AgentEntity agent = getAgentOrNull(agentId); List kbs = listByAgentId(agentId); if (kbs.isEmpty()) { return null; } + Long primaryKbId = agent != null ? agent.getPrimaryKbId() : null; + if (primaryKbId != null) { + for (WikiKnowledgeBaseEntity kb : kbs) { + if (primaryKbId.equals(kb.getId()) && sameWorkspace(agent, kb)) { + return kb; + } + } + return kbs.get(0); + } if (agentId != null) { for (WikiKnowledgeBaseEntity kb : kbs) { if (agentId.equals(kb.getAgentId())) { @@ -138,6 +151,74 @@ public class WikiKnowledgeBaseService { return kbs.get(0); } + private AgentEntity getAgentOrNull(Long agentId) { + if (agentId == null || agentMapper == null) { + return null; + } + return agentMapper.selectById(agentId); + } + + private boolean sameWorkspace(AgentEntity agent, WikiKnowledgeBaseEntity kb) { + if (agent == null || kb == null || agent.getWorkspaceId() == null) { + return true; + } + return kb.getWorkspaceId() == null || agent.getWorkspaceId().equals(kb.getWorkspaceId()); + } + + /** + * Resolve a specific knowledge base by name, restricted to the agent's + * workspace-visible KB set. Used by wiki tools + * that accept an optional {@code kbName} parameter so the LLM can target + * a non-primary KB when the agent reaches more than one. + *

    + * Match is exact and case-sensitive — the LLM is expected to copy the + * name verbatim from {@code wiki_list_kbs} output. Returns {@code null} + * when zero OR more than one KB matches the name; callers wanting to + * distinguish the two cases (so the LLM can be told to disambiguate by + * id) should call {@link #findAllByName} instead. The single-match + * convenience contract here keeps the legacy call sites simple. + */ + public WikiKnowledgeBaseEntity findByName(Long agentId, String kbName) { + List matches = findAllByName(agentId, kbName); + return matches.size() == 1 ? matches.get(0) : null; + } + + /** + * All KBs visible to {@code agentId} whose name matches {@code kbName} + * exactly. Returns an empty list when the name is blank or no KB matches; + * returns >1 entries when the workspace has duplicate KB names (no DB + * unique constraint protects against this), in which case the caller + * MUST disambiguate (typically by surfacing a kbId-based picker to the + * LLM) rather than silently picking the first one. + */ + public List findAllByName(Long agentId, String kbName) { + if (kbName == null || kbName.isBlank()) { + return List.of(); + } + List out = new java.util.ArrayList<>(); + for (WikiKnowledgeBaseEntity kb : listByAgentId(agentId)) { + if (kbName.equals(kb.getName())) { + out.add(kb); + } + } + return out; + } + + /** + * Resolve a KB by id, but ONLY when it's in the agent's visibility set — + * a deliberate fail-closed gate so an LLM cannot pivot to an arbitrary KB + * by guessing or scraping an id from someone else's workspace. + */ + public WikiKnowledgeBaseEntity findVisibleById(Long agentId, Long kbId) { + if (kbId == null) return null; + for (WikiKnowledgeBaseEntity kb : listByAgentId(agentId)) { + if (kbId.equals(kb.getId())) { + return kb; + } + } + return null; + } + public WikiKnowledgeBaseEntity getById(Long id) { return kbMapper.selectById(id); } @@ -168,14 +249,13 @@ public class WikiKnowledgeBaseService { } @Transactional - public WikiKnowledgeBaseEntity update(Long id, String name, String description, Long agentId) { + public WikiKnowledgeBaseEntity update(Long id, String name, String description) { WikiKnowledgeBaseEntity entity = kbMapper.selectById(id); if (entity == null) { throw new IllegalArgumentException("Knowledge base not found: " + id); } if (name != null) entity.setName(name); if (description != null) entity.setDescription(description); - if (agentId != null) entity.setAgentId(agentId); kbMapper.updateById(entity); return entity; } diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLinkService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLinkService.java new file mode 100644 index 00000000..67e9a583 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLinkService.java @@ -0,0 +1,326 @@ +package vip.mate.wiki.service; + +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import vip.mate.wiki.model.WikiPageEntity; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.LinkedHashSet; +import java.util.List; +import java.util.Locale; +import java.util.Set; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Collectors; + +/** + * Single source of truth for wikilink extraction and resolution-state + * computation. The page viewer's TypeScript {@code resolveWikilink} mirrors + * the matching semantics; both must stay in lockstep so users do not see a + * visibly-working link that the lint marks as broken (or vice-versa). + *

    + * Resolution rule (intentionally narrow): + * + *

      + *
    • Extract every {@code [[target]]} or {@code [[target|display]]} from + * content, skipping fenced and inline code spans.
      • + *
    • For each occurrence keep only {@code target.toLowerCase().trim()} — + * no {@link WikiPageService#canonicalSlug} fuzzy collapse, no + * title→slug guessing. The lint flags a link as broken iff no active + * KB page has {@code page.slug.equalsIgnoreCase(target)}.
      • + *
    + * + * The strict comparison surfaces real authoring mistakes (typo in slug, + * stale ref to a renamed page) rather than silently papering over them with + * canonical-form coercion. Phase 1's frontend resolver keeps a title + * fallback for legacy {@code [[Page Title]]} content so the visible link + * still navigates, but that fallback is intentionally absent here — title- + * form authors are expected to migrate as the slug-first prompt rollout + * lands in Phase 3. + */ +@Slf4j +@Service +@RequiredArgsConstructor +public class WikiLinkService { + + /** + * Matches every {@code [[...]]} occurrence. Non-greedy on the inside so + * pathological inputs like {@code [[a]] [[b]]} resolve as two separate + * links rather than one giant link {@code "a]] [[b"}. + */ + private static final Pattern WIKILINK = Pattern.compile("\\[\\[([^\\]]+?)]]"); + + /** + * Matches a fenced code block. Anchored to {@code ^```} on a line so a + * stray triple-backtick mid-paragraph does not flip the world into "in + * code" mode and swallow real wikilinks for the rest of the document. + * Captures the opening fence and content lazily; the matched range is + * removed wholesale before wikilink extraction. + */ + private static final Pattern FENCED_CODE = Pattern.compile( + "(?m)^```[\\s\\S]*?^```", Pattern.MULTILINE); + + /** + * Matches inline {@code `...`} spans. Non-greedy so adjacent inline spans + * are handled as separate matches. + */ + private static final Pattern INLINE_CODE = Pattern.compile("`[^`\\n]*?`"); + + /** Hard cap matching the frontend's MAX_SLUG_LEN — see wikilink.ts. */ + private static final int MAX_TARGET_LEN = 256; + + private final ObjectMapper objectMapper; + + /** + * Extract every wikilink target string from {@code content}, normalised + * to lowercase + trimmed, with code blocks stripped first. + *

    + * Returns an insertion-ordered set so callers that serialize to JSON get + * a stable order (helps diffability of {@code broken_links} fields across + * scans and makes audit logs easier to read). + * + * @param content full markdown body; {@code null} or blank returns empty + * @return targets as written (before {@code |} alias), lowercased + */ + public Set extractOutlinks(String content) { + if (content == null || content.isBlank()) return Collections.emptySet(); + + // Strip code first so inline / fenced examples that show literal + // [[wikilink]] syntax stay literal. Replacement with an equal-length + // run of spaces would be more correct (preserves positions for any + // future error reporting) but isn't worth the complexity here — we + // only need the targets. + String stripped = FENCED_CODE.matcher(content).replaceAll(""); + stripped = INLINE_CODE.matcher(stripped).replaceAll(""); + + Set targets = new LinkedHashSet<>(); + Matcher m = WIKILINK.matcher(stripped); + while (m.find()) { + String raw = m.group(1).trim(); + if (raw.isEmpty()) continue; + int pipe = raw.indexOf('|'); + String target = (pipe >= 0 ? raw.substring(0, pipe) : raw).trim(); + if (target.isEmpty() || target.length() > MAX_TARGET_LEN) continue; + // Lowercase here so {@link #computeBrokenLinks} can do exact + // equality against {@code page.slug.toLowerCase()} without an + // extra normalisation step per page. + targets.add(target.toLowerCase(Locale.ROOT)); + } + return targets; + } + + /** + * Compute the broken subset of {@code outlinks} given the KB's active + * page slug set. {@code activeSlugs} is expected to be already lowercased + * — callers compute it once per scan and reuse across pages. + * + * @return targets that have no matching page slug, in the same insertion + * order as {@code outlinks} + */ + public List computeBrokenLinks(Set outlinks, Set activeSlugsLower) { + if (outlinks == null || outlinks.isEmpty()) return Collections.emptyList(); + if (activeSlugsLower == null) activeSlugsLower = Collections.emptySet(); + List broken = new ArrayList<>(); + for (String t : outlinks) { + if (!activeSlugsLower.contains(t)) broken.add(t); + } + return broken; + } + + /** + * Convenience: extract + compute in one call. Used from + * {@code WikiPageService.save/update} where both fields are written in + * the same transaction. + */ + public LinkAnalysis analyze(String content, Set activeSlugsLower) { + Set outlinks = extractOutlinks(content); + List broken = computeBrokenLinks(outlinks, activeSlugsLower); + return new LinkAnalysis(new ArrayList<>(outlinks), broken); + } + + /** Pair returned by {@link #analyze(String, Set)}. */ + public record LinkAnalysis(List outgoingLinks, List brokenLinks) {} + + /** Serialize a list to JSON for persistence. Best-effort: never throws. */ + public String toJsonArray(List values) { + if (values == null || values.isEmpty()) return "[]"; + try { + return objectMapper.writeValueAsString(values); + } catch (Exception e) { + log.warn("[WikiLink] Failed to serialize list to JSON, falling back to empty: {}", e.getMessage()); + return "[]"; + } + } + + /** Parse a JSON array back into a list. Best-effort: never throws. */ + public List fromJsonArray(String json) { + if (json == null || json.isBlank()) return Collections.emptyList(); + try { + return objectMapper.readValue(json, new TypeReference>() {}); + } catch (Exception e) { + log.warn("[WikiLink] Failed to parse JSON array, treating as empty: {}", e.getMessage()); + return Collections.emptyList(); + } + } + + /** + * Compute the lowercase slug set for a KB from a pre-loaded page list. + * Centralised so both single-page save paths and the KB-wide scan use the + * same definition of "active page". + */ + public Set lowercaseSlugSet(List pages) { + if (pages == null || pages.isEmpty()) return Collections.emptySet(); + return pages.stream() + .map(WikiPageEntity::getSlug) + .filter(s -> s != null && !s.isBlank()) + .map(s -> s.toLowerCase(Locale.ROOT)) + .collect(Collectors.toUnmodifiableSet()); + } + + // ============================================================ + // Cascade rewrite — used by page delete + rename to update referrers + // ============================================================ + + /** + * Strip every {@code [[deletedSlug]]} or {@code [[deletedSlug|alias]]} + * occurrence in {@code content}, replacing the wikilink with plain text: + * + *

      + *
    • {@code [[deletedSlug]]} → {@code snapshotDisplay} (the deleted + * page's last known title, or the slug itself if title missing)
      • + *
    • {@code [[deletedSlug|alias]]} → {@code alias} (the author's + * chosen display text wins)
      • + *
    + * + * Mirrors {@link #extractOutlinks} on every protective axis: code blocks + * are skipped via the same fenced/inline strip-and-restore dance below, + * matching is exact case-insensitive on the slug only (never on the + * alias), and at-most-one {@code |} is honoured so a malformed + * {@code [[a|b|c]]} keeps the b|c suffix as alias text rather than + * collapsing. + */ + public String stripDeletedLink(String content, String deletedSlug, String snapshotDisplay) { + if (content == null || content.isEmpty()) return content; + if (deletedSlug == null || deletedSlug.isBlank()) return content; + String targetLower = deletedSlug.toLowerCase(Locale.ROOT); + String fallback = (snapshotDisplay != null && !snapshotDisplay.isBlank()) + ? snapshotDisplay : deletedSlug; + return rewriteWikilinks(content, (slugLower, alias) -> { + if (!slugLower.equals(targetLower)) return null; // unchanged + // No href to preserve — the link is being demoted to plain text. + return (alias != null && !alias.isBlank()) ? alias : fallback; + }); + } + + /** + * Rewrite every {@code [[oldSlug]]} or {@code [[oldSlug|alias]]} so the + * target becomes {@code newSlug}. Preserves the wikilink form — only the + * slug part changes, the alias (if any) is kept verbatim. Used when a + * page is renamed and every referrer must follow. + */ + public String renameLink(String content, String oldSlug, String newSlug) { + if (content == null || content.isEmpty()) return content; + if (oldSlug == null || oldSlug.isBlank() || newSlug == null || newSlug.isBlank()) return content; + String oldLower = oldSlug.toLowerCase(Locale.ROOT); + return rewriteWikilinks(content, (slugLower, alias) -> { + if (!slugLower.equals(oldLower)) return null; + // Return the full replacement string for this wikilink occurrence + // (still a wikilink, just with a different target). + return (alias != null && !alias.isBlank()) + ? "[[" + newSlug + "|" + alias + "]]" + : "[[" + newSlug + "]]"; + }); + } + + /** + * Walk {@code content} replacing wikilinks via {@code rewriter}. Code + * spans are detected and restored verbatim — replacement only happens in + * "narrative" regions so a doc literally showing {@code [[foo]]} inside + * a code fence is never silently mutated. + *

    + * The rewriter receives the lowercased slug and the raw alias (or + * {@code null}). It returns either: + *

      + *
    • {@code null} to leave the wikilink unchanged (caller is not + * interested in this slug), or
      • + *
    • the literal replacement string — typically plain text for a + * strip, or a re-formed {@code [[newSlug]]} for a rename.
      • + *
    + */ + private String rewriteWikilinks(String content, + java.util.function.BiFunction rewriter) { + // Split content into alternating "narrative" and "code" regions so we + // can apply the rewriter only to narrative. The same fenced+inline + // patterns the extractor uses, but here we preserve the matched code + // text verbatim instead of stripping it. + List regions = splitByCode(content); + StringBuilder out = new StringBuilder(content.length() + 16); + for (Region r : regions) { + if (r.isCode) { + out.append(r.text); + continue; + } + Matcher m = WIKILINK.matcher(r.text); + int last = 0; + while (m.find()) { + out.append(r.text, last, m.start()); + String raw = m.group(1).trim(); + String target; + String alias; + int pipe = raw.indexOf('|'); + if (pipe >= 0) { + target = raw.substring(0, pipe).trim(); + alias = raw.substring(pipe + 1).trim(); + } else { + target = raw; + alias = null; + } + String replacement = null; + if (!target.isEmpty()) { + replacement = rewriter.apply(target.toLowerCase(Locale.ROOT), alias); + } + if (replacement == null) { + out.append(m.group()); + } else { + out.append(replacement); + } + last = m.end(); + } + out.append(r.text, last, r.text.length()); + } + return out.toString(); + } + + /** Linear scan that splits content into alternating narrative + code regions. */ + private List splitByCode(String content) { + List result = new ArrayList<>(); + if (content == null || content.isEmpty()) return result; + // Run fenced first, then inline within each non-code piece. + List afterFenced = splitOne(content, FENCED_CODE); + for (Region r : afterFenced) { + if (r.isCode) { result.add(r); continue; } + result.addAll(splitOne(r.text, INLINE_CODE)); + } + return result; + } + + private List splitOne(String text, Pattern codePattern) { + List out = new ArrayList<>(); + Matcher m = codePattern.matcher(text); + int last = 0; + while (m.find()) { + if (m.start() > last) out.add(new Region(text.substring(last, m.start()), false)); + out.add(new Region(m.group(), true)); + last = m.end(); + } + if (last < text.length()) out.add(new Region(text.substring(last), false)); + return out; + } + + /** Narrative-vs-code text region used by {@link #rewriteWikilinks}. */ + private record Region(String text, boolean isCode) {} +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLintJobService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLintJobService.java new file mode 100644 index 00000000..7cf2b3a2 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiLintJobService.java @@ -0,0 +1,310 @@ +package vip.mate.wiki.service; + +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Propagation; +import org.springframework.transaction.annotation.Transactional; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.repository.WikiPageMapper; + +import jakarta.annotation.PreDestroy; +import java.time.LocalDateTime; +import java.util.List; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.UUID; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.ExecutorService; +import java.util.concurrent.Executors; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicReference; + +/** + * KB-wide broken-link scan job orchestrator. + *

    + * Single-page broken_links is maintained synchronously on every save/update + * (see {@link WikiPageService#applyLinkAnalysis} via + * {@code applyLinkAnalysis}). This service handles the on-demand "scan the + * whole KB" path that surfaces accumulated drift — pages whose targets went + * missing because some OTHER page was renamed / deleted / archived, or + * pages whose broken_links was never computed (legacy content predating + * V129). + *

    + * State lives in-memory on purpose: the authoritative result lives on + * {@code mate_wiki_page.broken_links} (persisted). The job record here is + * pure UX glue so the frontend can show "scan started / running / done" + * without a second DB table. A server restart mid-scan loses progress + * tracking but never corrupts data — each per-page rewrite is transactional, + * and the user simply re-triggers the scan. + */ +@Slf4j +@Service +@RequiredArgsConstructor +public class WikiLintJobService { + + private final WikiPageMapper pageMapper; + private final WikiPageService pageService; + private final WikiLinkService linkService; + + /** + * Per-KB job state. The map holds the most recent job for each KB + * regardless of status, so {@link #getLatestJob} can answer "did we ever + * finish a scan on this KB". Cleared only on completion of a newer scan + * for the same KB — no TTL, the cardinality is bounded by KB count. + */ + private final ConcurrentHashMap jobsByKb = new ConcurrentHashMap<>(); + + /** Index by jobId for the optional {@code GET .../jobs/{jobId}} path. */ + private final ConcurrentHashMap jobsById = new ConcurrentHashMap<>(); + + /** + * Single-threaded executor: lint scans are I/O-bound but cheap; one job + * per KB at a time avoids piling up concurrent full-KB reads on the + * mapper. Daemon thread so we don't block JVM shutdown. + */ + private final ExecutorService executor = Executors.newSingleThreadExecutor(r -> { + Thread t = new Thread(r, "wiki-lint-scan"); + t.setDaemon(true); + return t; + }); + + @PreDestroy + public void shutdown() { + executor.shutdownNow(); + try { + executor.awaitTermination(5, TimeUnit.SECONDS); + } catch (InterruptedException ignored) { + Thread.currentThread().interrupt(); + } + } + + /** Job status lifecycle: {@code queued → running → completed | failed}. */ + public enum JobStatus { QUEUED, RUNNING, COMPLETED, FAILED } + + /** + * Immutable snapshot of a job — the running mutable state lives behind + * an {@link AtomicReference} so callers receive a thread-safe view. + */ + public record LintJob( + String jobId, + Long kbId, + JobStatus status, + LocalDateTime startedAt, + LocalDateTime completedAt, + int totalPages, + int pagesWithBrokenLinks, + int totalBrokenRefs, + String errorMessage + ) {} + + /** + * Start a scan on {@code kbId}. If a scan is already queued or running for + * the same KB, return that job — POST is idempotent under in-flight load. + */ + public LintJob startOrGetRunning(Long kbId) { + // computeIfAbsent skipped — we need access to the existing value to + // decide whether to keep or replace it, which compute() supports. + return jobsByKb.compute(kbId, (k, prev) -> { + if (prev != null && (prev.status() == JobStatus.QUEUED || prev.status() == JobStatus.RUNNING)) { + log.debug("[WikiLint] Reusing in-flight job {} for kbId={}", prev.jobId(), kbId); + return prev; + } + String jobId = newJobId(); + LintJob job = new LintJob(jobId, kbId, JobStatus.QUEUED, LocalDateTime.now(), + null, 0, 0, 0, null); + jobsById.put(jobId, job); + executor.submit(() -> runJob(jobId, kbId)); + log.info("[WikiLint] Scheduled job {} for kbId={}", jobId, kbId); + return job; + }); + } + + /** @return latest job (any status) for {@code kbId}, or {@code null} */ + public LintJob getLatestJob(Long kbId) { + return jobsByKb.get(kbId); + } + + /** @return job by id, or {@code null} */ + public LintJob getJob(String jobId) { + return jobsById.get(jobId); + } + + /** + * Aggregate the broken-link state for {@code kbId} from persisted + * {@code broken_links} fields. Distinct from {@link #getLatestJob} — + * this is "what does the data say RIGHT NOW", regardless of whether a + * scan job is recorded in memory. Used by {@code GET /lint/broken-links}. + * + * @return null if no page in the KB has ever been scanned (every page's + * {@code broken_links_scanned_at} is null); else an aggregate + */ + public Aggregate aggregate(Long kbId) { + List pages = pageMapper.selectList( + new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper() + .select(WikiPageEntity::getId, WikiPageEntity::getSlug, + WikiPageEntity::getTitle, WikiPageEntity::getBrokenLinks, + WikiPageEntity::getBrokenLinksScannedAt) + .eq(WikiPageEntity::getKbId, kbId)); + if (pages.isEmpty()) return null; + boolean anyScanned = pages.stream().anyMatch(p -> p.getBrokenLinksScannedAt() != null); + if (!anyScanned) return null; + + LocalDateTime completedAt = pages.stream() + .map(WikiPageEntity::getBrokenLinksScannedAt) + .filter(java.util.Objects::nonNull) + .max(LocalDateTime::compareTo) + .orElse(null); + + int pagesWithBroken = 0; + int totalBrokenRefs = 0; + java.util.List details = new java.util.ArrayList<>(); + for (WikiPageEntity p : pages) { + List refs = linkService.fromJsonArray(p.getBrokenLinks()); + if (refs.isEmpty()) continue; + pagesWithBroken++; + totalBrokenRefs += refs.size(); + details.add(new PageBrokenRefs(p.getId(), p.getSlug(), p.getTitle(), refs)); + } + return new Aggregate(kbId, completedAt, pages.size(), pagesWithBroken, totalBrokenRefs, details); + } + + /** Per-page aggregation row. */ + public record PageBrokenRefs(Long pageId, String slug, String title, List brokenRefs) {} + + /** KB-level aggregate response. */ + public record Aggregate( + Long kbId, + LocalDateTime completedAt, + int totalPages, + int pagesWithBrokenLinks, + int totalBrokenRefs, + List pages + ) {} + + // ============================================================ + // Worker + // ============================================================ + + private void runJob(String jobId, Long kbId) { + updateJob(kbId, jobId, prev -> new LintJob( + jobId, kbId, JobStatus.RUNNING, prev.startedAt(), null, + 0, 0, 0, null)); + try { + ScanCounts counts = scan(kbId); + updateJob(kbId, jobId, prev -> new LintJob( + jobId, kbId, JobStatus.COMPLETED, prev.startedAt(), LocalDateTime.now(), + counts.totalPages, counts.pagesWithBroken, counts.totalBrokenRefs, null)); + log.info("[WikiLint] Job {} completed: {} pages, {} with broken links ({} refs)", + jobId, counts.totalPages, counts.pagesWithBroken, counts.totalBrokenRefs); + } catch (Exception e) { + log.error("[WikiLint] Job {} failed for kbId={}", jobId, kbId, e); + updateJob(kbId, jobId, prev -> new LintJob( + jobId, kbId, JobStatus.FAILED, prev.startedAt(), LocalDateTime.now(), + prev.totalPages(), prev.pagesWithBrokenLinks(), prev.totalBrokenRefs(), + e.getClass().getSimpleName() + ": " + e.getMessage())); + } + } + + private record ScanCounts(int totalPages, int pagesWithBroken, int totalBrokenRefs) {} + + /** + * Walk every active page in the KB, recompute its broken_links. Each + * page write is transactional ({@link #rewriteBrokenLinks}); the outer + * loop is NOT transactional so a single failing page doesn't roll back + * the whole scan. + */ + private ScanCounts scan(Long kbId) { + // listSummaries gives us the active (non-archived) page slug set — + // archived pages are NOT considered as valid targets, matching the + // resolver's behaviour. + List summaries = pageService.listSummaries(kbId); + Set activeSlugs = linkService.lowercaseSlugSet(summaries); + + // Now fetch the same pages WITH content so we can re-extract outlinks. + // We must not use listSummaries here because it omits the content + // column to keep memory bounded — but we have summaries for the slug + // set already, so the loaded list and the slug set agree. + List withContent = pageMapper.selectList( + new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper() + .select(WikiPageEntity::getId, WikiPageEntity::getSlug, + WikiPageEntity::getContent) + .eq(WikiPageEntity::getKbId, kbId) + .ne(WikiPageEntity::getArchived, 1)); + + int total = withContent.size(); + int pagesWithBroken = 0; + int totalBrokenRefs = 0; + + for (WikiPageEntity p : withContent) { + Set activeWithSelf; + if (p.getSlug() != null && !p.getSlug().isBlank()) { + java.util.Set tmp = new java.util.HashSet<>(activeSlugs); + tmp.add(p.getSlug().toLowerCase(Locale.ROOT)); + activeWithSelf = tmp; + } else { + activeWithSelf = activeSlugs; + } + WikiLinkService.LinkAnalysis a = linkService.analyze(p.getContent(), activeWithSelf); + int brokenCount = a.brokenLinks().size(); + if (brokenCount > 0) { + pagesWithBroken++; + totalBrokenRefs += brokenCount; + } + try { + rewriteBrokenLinks(p.getId(), + linkService.toJsonArray(a.outgoingLinks()), + linkService.toJsonArray(a.brokenLinks())); + } catch (Exception perPageErr) { + log.warn("[WikiLint] Per-page rewrite failed for pageId={}; continuing scan: {}", + p.getId(), perPageErr.getMessage()); + } + } + return new ScanCounts(total, pagesWithBroken, totalBrokenRefs); + } + + /** + * Transactional single-page rewrite of outgoing_links + broken_links + + * broken_links_scanned_at. Kept in this service so the scan loop above + * is unambiguously per-page transactional without polluting the larger + * WikiPageService API. + *

    + * Uses {@link com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper} + * with explicit {@code set()} calls instead of {@code updateById(partial entity)}. + * Several columns on {@link WikiPageEntity} (content, summary, + * outgoing_links, broken_links) carry {@code FieldStrategy.ALWAYS} so an + * entity-style update with those fields left null would generate + * {@code SET content = NULL, summary = NULL} and wipe the page body. + * The wrapper-based update only emits SET clauses for the three columns + * we mean to touch. + */ + @Transactional(propagation = Propagation.REQUIRES_NEW) + public void rewriteBrokenLinks(Long pageId, String outgoingLinksJson, String brokenLinksJson) { + pageMapper.update(null, + new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiPageEntity::getId, pageId) + .set(WikiPageEntity::getOutgoingLinks, outgoingLinksJson) + .set(WikiPageEntity::getBrokenLinks, brokenLinksJson) + .set(WikiPageEntity::getBrokenLinksScannedAt, LocalDateTime.now())); + } + + private void updateJob(Long kbId, String jobId, java.util.function.Function fn) { + LintJob updated = jobsByKb.compute(kbId, (k, prev) -> { + LintJob base = prev != null && prev.jobId().equals(jobId) ? prev : prev; + // If prev is null somehow, synthesize a minimal stub so the + // updater can still run. In practice prev is always non-null + // here because startOrGetRunning seeded the map first. + if (base == null) { + base = new LintJob(jobId, kbId, JobStatus.QUEUED, LocalDateTime.now(), + null, 0, 0, 0, null); + } + return fn.apply(base); + }); + jobsById.put(jobId, updated); + } + + private static String newJobId() { + return UUID.randomUUID().toString().replace("-", "").substring(0, 16); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageService.java index c3e3e828..9645c0ba 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageService.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageService.java @@ -7,12 +7,19 @@ import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; +import vip.mate.audit.service.AuditEventService; +import vip.mate.wiki.WikiProperties; import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.model.WikiRelationEntity; import vip.mate.wiki.repository.WikiPageMapper; +import vip.mate.wiki.repository.WikiRelationMapper; import java.time.LocalDateTime; import java.util.ArrayList; +import java.util.HashSet; import java.util.List; +import java.util.Locale; +import java.util.Set; import java.util.concurrent.ConcurrentHashMap; import java.util.regex.Matcher; import java.util.regex.Pattern; @@ -30,6 +37,17 @@ public class WikiPageService { private final WikiPageMapper pageMapper; private final ObjectMapper objectMapper; + private final WikiLinkService linkService; + // Cascade dependencies — optional via setter so the legacy unit-test + // constructor (mapper + ObjectMapper + linkService) still compiles. In + // production these are auto-wired through the field setters Lombok + // generates from @Setter on Spring's post-construct path. + @org.springframework.beans.factory.annotation.Autowired(required = false) + private WikiRelationMapper relationMapper; + @org.springframework.beans.factory.annotation.Autowired(required = false) + private AuditEventService auditEventService; + @org.springframework.beans.factory.annotation.Autowired(required = false) + private WikiProperties wikiProperties; private static final Pattern WIKI_LINK_PATTERN = Pattern.compile("\\[\\[([^\\]]+)]]"); @@ -52,6 +70,18 @@ public class WikiPageService { /** Agent 引用记录 */ public record ReferenceEntry(String slug, String title, int refCount) {} + /** + * Lightweight page reference for client-side wikilink resolution. + *

    + * Carries only {slug, title, archived} — no content, no source, no enrichment + * fields. Designed so the frontend can build a slug/title lookup map without + * dragging full page entities (each of which can be tens of KB once content + * is loaded). The {@code archived} flag lets the renderer pick the correct + * visual state (active link vs archived link vs broken span) without a + * second roundtrip. + */ + public record PageRef(String slug, String title, boolean archived) {} + /** 获取被引用最多的页面 Top N */ public List getTopReferenced(Long kbId, int limit) { String prefix = kbId + ":"; @@ -178,6 +208,44 @@ public class WikiPageService { summaryCache.remove(kbId); } + /** + * List all wikilink resolution refs in a knowledge base. + *

    + * The frontend wikilink resolver needs a complete {slug → page} index that + * is independent of the user's raw-material filter and unaffected by lazy + * pagination. {@link #listByKbId} only returns non-archived rows and is + * filtered by the UI's selected raw, so it cannot back wikilink resolution. + * This method serves the dedicated {@code GET /pages/refs} endpoint and + * returns minimal projections (slug + title + archived flag). + *

    + * When {@code includeArchived} is false (default), reuses the 5-minute + * summary cache for free; archived pages are absent there by construction. + * When true, runs a fresh query selecting only the three projected columns + * — uncached, because archived links appear on a small subset of pages and + * are not worth caching invalidation complexity. + * + * @param kbId knowledge base + * @param includeArchived true to include archived=1 rows; false (default) + * returns only active pages + */ + public List listAllRefs(Long kbId, boolean includeArchived) { + if (!includeArchived) { + return listSummaries(kbId).stream() + .map(p -> new PageRef(p.getSlug(), p.getTitle(), false)) + .toList(); + } + List rows = pageMapper.selectList( + new LambdaQueryWrapper() + .select(WikiPageEntity::getSlug, WikiPageEntity::getTitle, + WikiPageEntity::getArchived) + .eq(WikiPageEntity::getKbId, kbId) + .orderByAsc(WikiPageEntity::getTitle)); + return rows.stream() + .map(p -> new PageRef(p.getSlug(), p.getTitle(), + p.getArchived() != null && p.getArchived() == 1)) + .toList(); + } + /** * DB 级别搜索页面（不加载 content CLOB 到 Java 内存） */ @@ -267,18 +335,82 @@ public class WikiPageService { entity.setTitle(title); entity.setContent(content); entity.setSummary(summary); - entity.setOutgoingLinks(extractLinksAsJson(content)); entity.setSourceRawIds(sourceRawIds); entity.setVersion(1); entity.setLastUpdatedBy("ai"); if (pageType != null && !pageType.isBlank()) { entity.setPageType(pageType.toLowerCase()); } + // Compute outgoing_links + broken_links + scanned_at from the new + // content in the same transaction. See {@link #applyLinkAnalysis}. + applyLinkAnalysis(entity); pageMapper.insert(entity); evictSummaryCache(kbId); return entity; } + /** + * Apply schema-validated structured metadata to an existing page via a + * partial column update — only the metadata columns are written, so this + * never disturbs content / summary / links set by the ingest pipeline. + * Null arguments are written as-is (e.g. clearing a prior validation set). + */ + public void applyMetadata(Long pageId, String metadataJson, String validationStatus, + String validationJson, Integer profileVersion) { + if (pageId == null) { + return; + } + pageMapper.update(null, new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiPageEntity::getId, pageId) + .set(WikiPageEntity::getMetadataJson, metadataJson) + .set(WikiPageEntity::getMetadataValidationStatus, validationStatus) + .set(WikiPageEntity::getMetadataValidationJson, validationJson) + .set(WikiPageEntity::getProfileVersion, profileVersion)); + } + + /** Set only a page's knowledge layer via a partial update (leaves depends_on untouched). */ + public void setKnowledgeLayer(Long pageId, String knowledgeLayer) { + if (pageId == null || knowledgeLayer == null) { + return; + } + pageMapper.update(null, new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiPageEntity::getId, pageId) + .set(WikiPageEntity::getKnowledgeLayer, knowledgeLayer)); + } + + /** Set a page's knowledge layer and depends-on snapshot via a partial update. */ + public void setLayerAndDependencies(Long pageId, String knowledgeLayer, String dependsOnJson) { + if (pageId == null) { + return; + } + pageMapper.update(null, new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiPageEntity::getId, pageId) + .set(WikiPageEntity::getKnowledgeLayer, knowledgeLayer) + .set(WikiPageEntity::getDependsOnJson, dependsOnJson)); + } + + /** Mark a batch of pages stale with a shared reason JSON via a partial update. */ + public int markStale(java.util.Collection pageIds, String staleReasonJson) { + if (pageIds == null || pageIds.isEmpty()) { + return 0; + } + return pageMapper.update(null, new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .in(WikiPageEntity::getId, pageIds) + .set(WikiPageEntity::getStale, 1) + .set(WikiPageEntity::getStaleReasonJson, staleReasonJson)); + } + + /** Clear the stale flag on a single page (e.g. after regeneration). */ + public void clearStale(Long pageId) { + if (pageId == null) { + return; + } + pageMapper.update(null, new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiPageEntity::getId, pageId) + .set(WikiPageEntity::getStale, 0) + .set(WikiPageEntity::getStaleReasonJson, null)); + } + /** * List pages derived from a specific raw material (for UI sidebar filtering). * Uses a LIKE search on sourceRawIds JSON field — cheap and dialect-agnostic. @@ -328,10 +460,10 @@ public class WikiPageService { existing.setContent(content); existing.setSummary(summary); - existing.setOutgoingLinks(extractLinksAsJson(content)); existing.setVersion(existing.getVersion() + 1); existing.setLastUpdatedBy("ai"); existing.setUpdateTime(LocalDateTime.now()); + applyLinkAnalysis(existing); // 追加新的 source raw id if (newRawId != null) { @@ -395,10 +527,10 @@ public class WikiPageService { throw new IllegalArgumentException("Page not found: " + slug); } existing.setContent(content); - existing.setOutgoingLinks(extractLinksAsJson(content)); existing.setVersion(existing.getVersion() + 1); existing.setLastUpdatedBy("manual"); existing.setUpdateTime(LocalDateTime.now()); + applyLinkAnalysis(existing); // 同步更新摘要，防止与 content 漂移 if (summary != null) { existing.setSummary(summary); @@ -471,11 +603,297 @@ public class WikiPageService { kbId, slug, existing.getPageType(), existing.getLocked()); return; } + + // Snapshot the title BEFORE the row goes away. Referrer rewrites + // demote `[[slug]]` to plain text using the title as the visible + // word; without the snapshot the demotion would fall back to the + // raw slug, which reads worse. + Long pageId = existing.getId(); + String snapshotTitle = (existing.getTitle() != null && !existing.getTitle().isBlank()) + ? existing.getTitle() : slug; + + // Cascade-rewrite every other page that linked to this slug. Feature- + // flagged so a hypothetical content-mangling regression has a + // production kill-switch; default-on because the legacy behaviour + // (just dropping the row) left dangling [[slug]] tokens that this + // RFC exists to eliminate. + List affectedReferrers = java.util.Collections.emptyList(); + boolean cascadeOn = wikiProperties == null || wikiProperties.isCascadeDeleteEnabled(); + if (cascadeOn) { + try { + affectedReferrers = cascadeStripReferrers(kbId, pageId, slug, snapshotTitle); + } catch (RuntimeException e) { + // Don't fail the delete on a referrer-rewrite hiccup — the + // page itself coming out is the user's primary intent; lint + // will catch any stragglers on the next scan. + log.warn("[Wiki] Cascade rewrite failed for slug={} (continuing with delete): {}", + slug, e.toString()); + } + } + + // Defensive relation-cache cleanup. The mate_wiki_relation table is + // currently a reserved cache (no production writer today), but we + // wipe matching rows anyway so a future writer that populates it + // can't strand entries pointing at a deleted page. + if (relationMapper != null) { + try { + relationMapper.delete( + new LambdaQueryWrapper() + .eq(WikiRelationEntity::getKbId, kbId) + .and(w -> w.eq(WikiRelationEntity::getPageAId, pageId) + .or().eq(WikiRelationEntity::getPageBId, pageId))); + } catch (RuntimeException e) { + log.warn("[Wiki] Failed to purge mate_wiki_relation rows for pageId={}: {}", + pageId, e.toString()); + } + } + pageMapper.delete( new LambdaQueryWrapper() .eq(WikiPageEntity::getKbId, kbId) .eq(WikiPageEntity::getSlug, slug)); evictSummaryCache(kbId); + + // Audit event runs after the row is gone so the resourceId reflects + // the actual deletion. Async insert means a failing audit log won't + // poison the transaction. + if (auditEventService != null) { + try { + String detail = objectMapper.writeValueAsString(java.util.Map.of( + "kbId", kbId, + "slug", slug, + "title", snapshotTitle, + "affectedPageIds", affectedReferrers, + "cascadeEnabled", cascadeOn)); + auditEventService.record("wiki.page.delete", "wiki_page", + String.valueOf(pageId), snapshotTitle, detail); + } catch (Exception e) { + log.debug("[Wiki] Audit event emit failed for delete kbId={} slug={}: {}", + kbId, slug, e.toString()); + } + } + } + + /** + * Walk every page in {@code kbId} that links to {@code targetSlug}, + * rewrite the wikilink to plain text via the parser, and persist the + * referrer with refreshed outgoing_links + broken_links. Returns the + * affected page ids so the caller can include them in the audit event. + *

    + * Candidate set comes from {@link WikiPageMapper#findReferrersByOutgoingLink} + * (a LIKE pre-filter on {@code outgoing_links}). Each candidate is then + * verified by re-extracting outlinks from its content — LIKE matches on + * the raw JSON column can include false positives if the slug happens + * to appear as a substring of another value, so we trust the parser as + * the final word. + */ + private List cascadeStripReferrers(Long kbId, Long deletedPageId, + String deletedSlug, String snapshotTitle) { + // outgoing_links is stored as a JSON array of lowercased strings, so + // we wrap with quotes to anchor the match to a full JSON element + // rather than any substring match. + String slugLower = deletedSlug.toLowerCase(Locale.ROOT); + String likePattern = "%\"" + slugLower + "\"%"; + List candidates = pageMapper.findReferrersByOutgoingLink( + kbId, deletedPageId, likePattern); + if (candidates.isEmpty()) return List.of(); + + // Pre-compute the active slug set ONCE for the recompute pass — every + // referrer's broken_links recompute would otherwise re-trigger the + // summary query. + Set activeSlugs; + try { + activeSlugs = linkService.lowercaseSlugSet(listSummaries(kbId)); + } catch (RuntimeException e) { + activeSlugs = java.util.Collections.emptySet(); + } + // The deleted page is, by construction, no longer "active" — remove + // its slug from the set so any referrers' broken_links recompute + // doesn't accidentally still resolve `[[deletedSlug]]` in their + // (now-rewritten) content. + if (!activeSlugs.contains(slugLower)) { + // already missing — common case + } else { + Set trimmed = new HashSet<>(activeSlugs); + trimmed.remove(slugLower); + activeSlugs = trimmed; + } + + List affected = new ArrayList<>(candidates.size()); + for (WikiPageEntity referrer : candidates) { + String originalContent = referrer.getContent(); + if (originalContent == null) continue; + String rewritten = linkService.stripDeletedLink(originalContent, deletedSlug, snapshotTitle); + if (rewritten.equals(originalContent)) { + // LIKE matched but parser found no real wikilink — pure + // false-positive (e.g. slug appeared as substring inside an + // alias of an unrelated link). Skip. + continue; + } + + // Recompute outgoing + broken from the rewritten content, including + // the referrer's own slug so any self-links remain non-broken. + Set activeForThisReferrer = activeSlugs; + if (referrer.getSlug() != null && !referrer.getSlug().isBlank()) { + Set withSelf = new HashSet<>(activeSlugs); + withSelf.add(referrer.getSlug().toLowerCase(Locale.ROOT)); + activeForThisReferrer = withSelf; + } + WikiLinkService.LinkAnalysis a = linkService.analyze(rewritten, activeForThisReferrer); + + // LambdaUpdateWrapper — content, summary, outgoing_links and + // broken_links all carry FieldStrategy.ALWAYS on WikiPageEntity, + // so a partial-entity updateById would generate SET summary=NULL + // (and clear any other ALWAYS column we didn't explicitly set). + // The wrapper-based update only writes the four columns we mean + // to touch, leaving summary and the rest intact. + pageMapper.update(null, + new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiPageEntity::getId, referrer.getId()) + .set(WikiPageEntity::getContent, rewritten) + .set(WikiPageEntity::getOutgoingLinks, linkService.toJsonArray(a.outgoingLinks())) + .set(WikiPageEntity::getBrokenLinks, linkService.toJsonArray(a.brokenLinks())) + .set(WikiPageEntity::getBrokenLinksScannedAt, LocalDateTime.now())); + affected.add(referrer.getId()); + } + return affected; + } + + /** + * Rename a page from {@code oldSlug} to {@code newSlug}. + *

    + * Updates the page row's slug AND rewrites every referrer's + * {@code [[oldSlug]]} (and {@code [[oldSlug|alias]]}) to point at the + * new slug, preserving aliases. Both pieces run in the same transaction + * so a partial rename can never leave a "page exists at new slug but + * referrers still point at old slug" inconsistency. + * + * @return the renamed page entity, or {@code null} if {@code oldSlug} + * didn't exist + * @throws IllegalArgumentException if {@code newSlug} is blank, equals + * the current slug, or collides with another page in the same KB + */ + @Transactional + public WikiPageEntity rename(Long kbId, String oldSlug, String newSlug) { + if (newSlug == null || newSlug.isBlank()) { + throw new IllegalArgumentException("new slug must not be blank"); + } + if (newSlug.equals(oldSlug)) { + throw new IllegalArgumentException("new slug equals old slug — no-op"); + } + WikiPageEntity existing = getBySlug(kbId, oldSlug); + if (existing == null) return null; + if (isProtected(existing)) { + throw new IllegalStateException("page is protected (system or locked), refusing to rename"); + } + WikiPageEntity collision = getBySlug(kbId, newSlug); + // The collision-check has to ignore "renaming yourself" — on + // case-insensitive DB collations (e.g. MySQL's default + // utf8mb4_unicode_ci), getBySlug returns the SAME row when + // newSlug differs from oldSlug only in case. Treating that as a + // collision would forbid case-only renames on MySQL while H2 + // (case-sensitive) silently allowed them, producing an + // environment-dependent error. Comparing ids makes the rule + // identical on both backends: only a row owned by a different + // page is a true collision. + if (collision != null && !existing.getId().equals(collision.getId())) { + throw new IllegalArgumentException("a page with slug '" + newSlug + "' already exists in this KB"); + } + + Long pageId = existing.getId(); + // Update the row's own slug first so referrer rewrites that include + // a self-link to the same page (rare but possible — e.g. a "see also" + // anchor) resolve to the new slug as well. + existing.setSlug(newSlug); + existing.setUpdateTime(LocalDateTime.now()); + pageMapper.updateById(existing); + evictSummaryCache(kbId); + + List affected = java.util.Collections.emptyList(); + boolean cascadeOn = wikiProperties == null || wikiProperties.isCascadeDeleteEnabled(); + if (cascadeOn) { + try { + affected = cascadeRenameReferrers(kbId, pageId, oldSlug, newSlug); + } catch (RuntimeException e) { + log.warn("[Wiki] Cascade rename failed for {}→{} (continuing): {}", + oldSlug, newSlug, e.toString()); + } + } + + if (auditEventService != null) { + try { + String detail = objectMapper.writeValueAsString(java.util.Map.of( + "kbId", kbId, + "oldSlug", oldSlug, + "newSlug", newSlug, + "affectedPageIds", affected, + "cascadeEnabled", cascadeOn)); + auditEventService.record("wiki.page.rename", "wiki_page", + String.valueOf(pageId), existing.getTitle(), detail); + } catch (Exception e) { + log.debug("[Wiki] Audit event emit failed for rename: {}", e.toString()); + } + } + + return existing; + } + + /** + * Mirror of {@link #cascadeStripReferrers} for the rename path — + * replaces {@code [[oldSlug]]} with {@code [[newSlug]]} (preserving the + * wikilink form and any alias) instead of demoting to plain text. + */ + private List cascadeRenameReferrers(Long kbId, Long renamedPageId, + String oldSlug, String newSlug) { + String slugLower = oldSlug.toLowerCase(Locale.ROOT); + String likePattern = "%\"" + slugLower + "\"%"; + List candidates = pageMapper.findReferrersByOutgoingLink( + kbId, renamedPageId, likePattern); + if (candidates.isEmpty()) return List.of(); + + Set activeSlugs; + try { + activeSlugs = linkService.lowercaseSlugSet(listSummaries(kbId)); + } catch (RuntimeException e) { + activeSlugs = java.util.Collections.emptySet(); + } + // The renamed page is now under newSlug; oldSlug is gone, newSlug + // should resolve. listSummaries has been evicted above so this picks + // up the new row when re-queried, but be defensive in case the cache + // hasn't repopulated yet. + Set activeBase = new HashSet<>(activeSlugs); + activeBase.remove(slugLower); + activeBase.add(newSlug.toLowerCase(Locale.ROOT)); + activeSlugs = activeBase; + + List affected = new ArrayList<>(candidates.size()); + for (WikiPageEntity referrer : candidates) { + String originalContent = referrer.getContent(); + if (originalContent == null) continue; + String rewritten = linkService.renameLink(originalContent, oldSlug, newSlug); + if (rewritten.equals(originalContent)) continue; + + Set activeForThisReferrer = activeSlugs; + if (referrer.getSlug() != null && !referrer.getSlug().isBlank()) { + Set withSelf = new HashSet<>(activeSlugs); + withSelf.add(referrer.getSlug().toLowerCase(Locale.ROOT)); + activeForThisReferrer = withSelf; + } + WikiLinkService.LinkAnalysis a = linkService.analyze(rewritten, activeForThisReferrer); + + // LambdaUpdateWrapper to avoid the FieldStrategy.ALWAYS-induced + // null overwrite on summary (and other ALWAYS columns we don't + // touch in a rename). + pageMapper.update(null, + new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiPageEntity::getId, referrer.getId()) + .set(WikiPageEntity::getContent, rewritten) + .set(WikiPageEntity::getOutgoingLinks, linkService.toJsonArray(a.outgoingLinks())) + .set(WikiPageEntity::getBrokenLinks, linkService.toJsonArray(a.brokenLinks())) + .set(WikiPageEntity::getBrokenLinksScannedAt, LocalDateTime.now())); + affected.add(referrer.getId()); + } + return affected; } /** @@ -572,31 +990,68 @@ public class WikiPageService { } /** - * Extract {@code [[links]]} (and {@code [[target|label]]} alias form, - * RFC-051 PR-5) from Markdown content and return them as a JSON array of - * canonical slugs. + * Extract {@code [[links]]} (and {@code [[target|label]]} alias form) + * from Markdown content and return them as a JSON array of lowercased + * target strings. Code blocks are skipped by {@link WikiLinkService}. *

    - * For aliased links the {@code label} part is purely display — only - * {@code target} feeds slug resolution. Without this split we'd canonicalize - * "Spring AI|Spring AI Alibaba" as a single slug, polluting outgoingLinks - * and breaking graph view / backlinks. + * Behaviour change vs. the historical implementation: previously every + * target was run through {@link #toSlug} (lowercase + strip + dash-collapse), + * which silently coerced {@code [[Transformer Architecture]]} into + * {@code transformer-architecture} regardless of whether such a page slug + * actually existed. The new implementation preserves what the author + * wrote (only lowercased + trimmed). The lint compares this against + * {@code page.slug.toLowerCase()} so any title-form legacy content is + * surfaced as broken — exactly the gap the wikilink overhaul exists to + * close. The frontend resolver keeps a title fallback so the visible + * link still navigates during the transition. + *

    + * Kept public for callers outside this service (e.g. enrichment) that + * still need the JSON-array serialisation; delegates to + * {@link WikiLinkService} so there is exactly one extraction code path. */ - String extractLinksAsJson(String content) { - if (content == null) return "[]"; - List links = new ArrayList<>(); - Matcher matcher = WIKI_LINK_PATTERN.matcher(content); - while (matcher.find()) { - String raw = matcher.group(1).trim(); - int pipe = raw.indexOf('|'); - String target = pipe >= 0 ? raw.substring(0, pipe).trim() : raw; - if (target.isEmpty()) continue; - String slug = toSlug(target); - if (slug.isEmpty()) continue; - if (!links.contains(slug)) { - links.add(slug); - } + public String extractLinksAsJson(String content) { + Set outlinks = linkService.extractOutlinks(content); + return linkService.toJsonArray(new ArrayList<>(outlinks)); + } + + /** + * Compute and apply {@code outgoing_links} + {@code broken_links} + + * {@code broken_links_scanned_at} fields on an entity from its content. + * Called from every save/update path so the lint state is always in sync + * with the content actually being persisted (same transaction). Excludes + * the entity itself from the active-slug set when an id is present, so + * self-links resolve correctly even when the entity is mid-update. + */ + private void applyLinkAnalysis(WikiPageEntity entity) { + if (entity == null || entity.getKbId() == null) return; + // Fetch the active slug set defensively — in fully-wired production + // context this never fails, but unit tests that mock the mapper can + // trip MyBatis-Plus's lambda-cache lookup (TableInfo isn't seeded + // outside a Spring context). Treating a fetch failure as "empty slug + // set" means link analysis still runs (so the test verifies the + // update path) and every extracted target is recorded as broken — + // which is harmless because tests don't assert on broken_links + // values, and production code paths never hit this branch. + Set activeSlugs; + try { + activeSlugs = linkService.lowercaseSlugSet(listSummaries(entity.getKbId())); + } catch (RuntimeException e) { + log.warn("[Wiki] applyLinkAnalysis: failed to load slug set for kbId={}, treating as empty: {}", + entity.getKbId(), e.toString()); + activeSlugs = java.util.Collections.emptySet(); } - return toJson(links); + // Include self-slug so [[my-own-slug]] doesn't appear as broken on the + // very save that creates the page (listSummaries may not see it yet + // depending on cache state). + if (entity.getSlug() != null && !entity.getSlug().isBlank()) { + Set withSelf = new HashSet<>(activeSlugs); + withSelf.add(entity.getSlug().toLowerCase(Locale.ROOT)); + activeSlugs = withSelf; + } + WikiLinkService.LinkAnalysis a = linkService.analyze(entity.getContent(), activeSlugs); + entity.setOutgoingLinks(linkService.toJsonArray(a.outgoingLinks())); + entity.setBrokenLinks(linkService.toJsonArray(a.brokenLinks())); + entity.setBrokenLinksScannedAt(LocalDateTime.now()); } /** diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageTypePermissionService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageTypePermissionService.java new file mode 100644 index 00000000..ad94c022 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiPageTypePermissionService.java @@ -0,0 +1,245 @@ +package vip.mate.wiki.service; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.fasterxml.jackson.databind.ObjectMapper; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import vip.mate.wiki.job.WikiKbConfig; +import vip.mate.wiki.job.WikiKbConfigParser; +import vip.mate.wiki.model.WikiAgentPageTypePermissionEntity; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.repository.WikiAgentPageTypePermissionMapper; + +import java.util.List; +import java.util.Locale; + +/** + * Resolves whether an agent may read or write wiki pages of a given pageType + * within a knowledge base. + * + *

    Matching precedence: an exact {@code page_type} row wins over the + * agent's {@code page_type='*'} default row. The unique key + * {@code (agent_id, kb_id, page_type, deleted)} guarantees at most one of each, + * so resolution is unambiguous without a same-level tie-break. + * + *

    Read default: when no row matches the pageType, read access falls + * back to the KB-level {@code defaultReadPolicy} ({@code allow_all} unless the + * KB config sets {@code deny_all}). This keeps existing KBs fully readable + * after upgrade. + * + *

    Write default: writes are gated opt-in. When an agent has no rows + * at all for a KB, writes are {@link WriteDecision#ALLOW}ed (preserving current + * behaviour). Once any row exists for that agent+KB, the KB is considered + * locked down: a pageType with no matching row resolves to + * {@link WriteDecision#DENY} (fail-safe). + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiPageTypePermissionService { + + /** Wildcard page_type for the agent's KB-wide default row. */ + public static final String WILDCARD = "*"; + + private final WikiAgentPageTypePermissionMapper permissionMapper; + private final WikiKnowledgeBaseService kbService; + private final ObjectMapper objectMapper; + + public WikiPageTypePermissionService(WikiAgentPageTypePermissionMapper permissionMapper, + WikiKnowledgeBaseService kbService, + ObjectMapper objectMapper) { + this.permissionMapper = permissionMapper; + this.kbService = kbService; + this.objectMapper = objectMapper; + } + + /** Write operations gated by {@link #resolveWrite}. */ + public enum WriteOp { CREATE, UPDATE, DELETE } + + /** Resolution of a write request. */ + public enum WriteDecision { ALLOW, APPROVAL_REQUIRED, DENY } + + /** + * Load the agent's permission view for a KB once, so a list of pages can be + * filtered without re-querying per row. {@code null} agentId yields an + * allow-all view (e.g. internal callers without an agent context). + */ + public Access resolve(Long agentId, Long kbId) { + if (agentId == null || kbId == null) { + return new Access(List.of(), false, false); + } + List rows = permissionMapper.selectList( + new LambdaQueryWrapper() + .eq(WikiAgentPageTypePermissionEntity::getAgentId, agentId) + .eq(WikiAgentPageTypePermissionEntity::getKbId, kbId)); + boolean denyByDefault = isDenyAll(kbId); + return new Access(rows, denyByDefault, !rows.isEmpty()); + } + + /** Convenience single-shot read check. */ + public boolean canRead(Long agentId, Long kbId, String pageType) { + return resolve(agentId, kbId).canRead(pageType); + } + + /** Convenience single-shot write resolution. */ + public WriteDecision resolveWrite(Long agentId, Long kbId, String pageType, WriteOp op) { + return resolve(agentId, kbId).resolveWrite(pageType, op); + } + + // ==================== Config CRUD (admin surface) ==================== + + /** All permission rows for an agent within a KB, ordered with the wildcard last. */ + public List listRows(Long agentId, Long kbId) { + if (agentId == null || kbId == null) { + return List.of(); + } + return permissionMapper.selectList( + new LambdaQueryWrapper() + .eq(WikiAgentPageTypePermissionEntity::getAgentId, agentId) + .eq(WikiAgentPageTypePermissionEntity::getKbId, kbId) + .orderByAsc(WikiAgentPageTypePermissionEntity::getPageType)); + } + + /** + * Upsert a permission row by the {@code (agent_id, kb_id, page_type)} natural + * key: an existing row for the same triple is updated in place, otherwise a + * new row is inserted. The pageType is normalized to lowercase (the wildcard + * {@code *} is preserved as-is). Returns the persisted row. + */ + public WikiAgentPageTypePermissionEntity saveRow(WikiAgentPageTypePermissionEntity row) { + if (row == null || row.getAgentId() == null || row.getKbId() == null) { + throw new IllegalArgumentException("agentId and kbId are required"); + } + String type = row.getPageType() == null || row.getPageType().isBlank() + ? WILDCARD + : (WILDCARD.equals(row.getPageType().trim()) + ? WILDCARD + : row.getPageType().trim().toLowerCase(Locale.ROOT)); + row.setPageType(type); + // Normalize the write policy so resolution never sees an unexpected token. + if (row.getWritePolicy() != null) { + String wp = row.getWritePolicy().trim().toLowerCase(Locale.ROOT); + row.setWritePolicy(switch (wp) { + case "allow", "deny", "approval_required" -> wp; + default -> "approval_required"; + }); + } + WikiAgentPageTypePermissionEntity existing = permissionMapper.selectOne( + new LambdaQueryWrapper() + .eq(WikiAgentPageTypePermissionEntity::getAgentId, row.getAgentId()) + .eq(WikiAgentPageTypePermissionEntity::getKbId, row.getKbId()) + .eq(WikiAgentPageTypePermissionEntity::getPageType, type) + .last("LIMIT 1")); + if (existing != null) { + row.setId(existing.getId()); + permissionMapper.updateById(row); + } else { + row.setId(null); + permissionMapper.insert(row); + } + return row; + } + + /** Logically delete a permission row by id. Returns true when a row was removed. */ + public boolean deleteRow(Long id) { + if (id == null) { + return false; + } + return permissionMapper.deleteById(id) > 0; + } + + private boolean isDenyAll(Long kbId) { + WikiKnowledgeBaseEntity kb = kbService.getById(kbId); + if (kb == null || kb.getConfigContent() == null) { + return false; + } + WikiKbConfig config = WikiKbConfigParser.parse(objectMapper, kb.getConfigContent()); + if (config == null || config.getDefaultReadPolicy() == null) { + return false; + } + return "deny_all".equalsIgnoreCase(config.getDefaultReadPolicy().trim()); + } + + /** + * A resolved per-(agent, KB) permission view. Holds the agent's rows so + * repeated pageType checks (e.g. filtering a page list) hit memory, not DB. + */ + public static final class Access { + + private final List rows; + private final boolean denyReadByDefault; + private final boolean hasAnyRow; + + Access(List rows, boolean denyReadByDefault, boolean hasAnyRow) { + this.rows = rows; + this.denyReadByDefault = denyReadByDefault; + this.hasAnyRow = hasAnyRow; + } + + /** + * Whether the agent may read pages of {@code pageType}. Exact row wins + * over {@code '*'}; absent a matching row, the KB default read policy + * decides. + */ + public boolean canRead(String pageType) { + WikiAgentPageTypePermissionEntity match = match(pageType); + if (match != null) { + return flag(match.getCanRead()); + } + return !denyReadByDefault; + } + + /** + * Resolve a write request. See class javadoc for the opt-in / + * fail-safe defaults. + */ + public WriteDecision resolveWrite(String pageType, WriteOp op) { + WikiAgentPageTypePermissionEntity match = match(pageType); + if (match == null) { + // No rows at all → not gated yet → preserve current behaviour. + // Some rows but none cover this type → KB is locked down. + return hasAnyRow ? WriteDecision.DENY : WriteDecision.ALLOW; + } + boolean opAllowed = switch (op) { + case CREATE -> flag(match.getCanCreate()); + case UPDATE -> flag(match.getCanUpdate()); + case DELETE -> flag(match.getCanDelete()); + }; + if (!opAllowed) { + return WriteDecision.DENY; + } + return mapPolicy(match.getWritePolicy()); + } + + /** Exact page_type row wins; otherwise the wildcard row; else null. */ + private WikiAgentPageTypePermissionEntity match(String pageType) { + String needle = pageType == null ? "" : pageType.trim().toLowerCase(Locale.ROOT); + WikiAgentPageTypePermissionEntity wildcard = null; + for (WikiAgentPageTypePermissionEntity row : rows) { + String type = row.getPageType() == null ? "" : row.getPageType().trim(); + if (WILDCARD.equals(type)) { + wildcard = row; + } else if (type.toLowerCase(Locale.ROOT).equals(needle)) { + return row; + } + } + return wildcard; + } + + private static WriteDecision mapPolicy(String writePolicy) { + if (writePolicy == null) { + return WriteDecision.APPROVAL_REQUIRED; + } + return switch (writePolicy.trim().toLowerCase(Locale.ROOT)) { + case "allow" -> WriteDecision.ALLOW; + case "deny" -> WriteDecision.DENY; + default -> WriteDecision.APPROVAL_REQUIRED; + }; + } + + private static boolean flag(Integer value) { + return value != null && value != 0; + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiProcessingService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiProcessingService.java index 981da91c..ab1ef38f 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiProcessingService.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiProcessingService.java @@ -2,6 +2,7 @@ package vip.mate.wiki.service; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; +import com.fasterxml.jackson.databind.node.ObjectNode; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.chat.messages.SystemMessage; @@ -52,6 +53,7 @@ public class WikiProcessingService { private final WikiPageService pageService; private final WikiChunkService chunkService; private final WikiEmbeddingService embeddingService; + private final WikiLinkService linkService; private final WikiProperties properties; private final ModelConfigService modelConfigService; private final AgentGraphBuilder agentGraphBuilder; @@ -60,6 +62,22 @@ public class WikiProcessingService { private final WikiCitationService citationService; private final org.springframework.context.ApplicationEventPublisher eventPublisher; + /** + * Optional KB pageType profile. Field-injected (not a constructor arg) so + * existing instantiations are unaffected; when absent the batch-create + * prompt falls back to the legacy hardcoded pageType enum. + */ + @org.springframework.beans.factory.annotation.Autowired(required = false) + private vip.mate.wiki.profile.WikiPageTypeProfileService pageTypeProfileService; + + /** Optional metadata validator, paired with {@link #pageTypeProfileService}. */ + @org.springframework.beans.factory.annotation.Autowired(required = false) + private vip.mate.wiki.profile.WikiMetadataValidator metadataValidator; + + /** Optional dependency/stale engine for layered-knowledge wiring. */ + @org.springframework.beans.factory.annotation.Autowired(required = false) + private vip.mate.wiki.service.WikiDependencyService dependencyService; + /** * Read-the-failover-chain handle. Optional so the existing constructors and * lazy-mode tests don't have to thread a new dependency. When null, the @@ -799,11 +817,10 @@ public class WikiProcessingService { // this picks up changes from sequential chunks without an extra DB hit when nothing changed. String freshIndex = buildExistingPagesIndex(kbId); - String routeSystem = PromptLoader.loadPrompt("wiki/route-system"); + String routeSystem = PromptLoader.loadPrompt("wiki/route-system") + .replace("{allowed_page_types}", allowedTypesFragment(kbId)); String routeUserTemplate = PromptLoader.loadPrompt("wiki/route-user"); - String documentMapSection = (documentMap != null && !documentMap.isBlank()) - ? "## 文档全局概念地图（预分析结果，供路由参考）\n\n```json\n" + documentMap + "\n```\n" - : ""; + String documentMapSection = buildDocumentMapSection(documentMap); String routeUser = routeUserTemplate .replace("{config}", configContent) .replace("{document_map_section}", documentMapSection) @@ -1065,10 +1082,21 @@ public class WikiProcessingService { metasJson.append("]"); String batchSystem = PromptLoader.loadPrompt("wiki/batch-create-system"); + if (pageTypeProfileService != null) { + // Inject the KB's allowed page types so the LLM only emits types + // the profile recognises. Default-profile KBs get the same list + // as the previous hardcoded enum, so behaviour is unchanged. + batchSystem = batchSystem.replace("{allowed_page_types}", + pageTypeProfileService.describeForPrompt(kbId)) + .replace("{page_type_templates}", + emptyOr(pageTypeProfileService.describeTemplatesForPrompt(kbId))); + } else { + batchSystem = batchSystem.replace("{allowed_page_types}", + "concept / person / place / event / technology / organization / product / term / process / other") + .replace("{page_type_templates}", "(无)"); + } String batchUserTemplate = PromptLoader.loadPrompt("wiki/batch-create-user"); - String docMapSection = (documentMap != null && !documentMap.isBlank()) - ? "## 文档全局概念地图（预分析结果，供页面内容生成参考）\n\n```json\n" + documentMap + "\n```\n" - : ""; + String docMapSection = buildDocumentMapSection(documentMap); String batchUser = batchUserTemplate .replace("{config}", configContent) .replace("{document_map_section}", docMapSection) @@ -1140,6 +1168,13 @@ public class WikiProcessingService { String content = pageJson.path("content").asText(""); String pageSummary = pageJson.path("summary").asText(""); String pageType = pageJson.path("page_type").asText(""); + // Downgrade an unrecognised type to the profile fallback so the + // stored page_type always belongs to the KB's profile. + if (pageTypeProfileService != null && !pageType.isBlank()) { + pageType = pageTypeProfileService.normalizePageType(kbId, pageType); + } + JsonNode metadataNode = pageJson.path("metadata"); + JsonNode dependsOnNode = pageJson.path("depends_on"); if (content.isBlank()) { log.info("[Wiki] BatchCreate: blank content for slug='{}', retrying individually", slug); final String blankSlug = slug; @@ -1168,14 +1203,24 @@ public class WikiProcessingService { boolean wasCreated = false; boolean ok = false; try { - wasCreated = savePageContent(kb, raw, slug, title, content, pageSummary, pageType); + wasCreated = savePageContent(kb, raw, slug, title, content, pageSummary, pageType, metadataNode, dependsOnNode); if (wasCreated) { created.incrementAndGet(); totalCreated++; - // Append to liveIndex so next sub-batch can link to this page + // Append to liveIndex so the NEXT sub-batch can link to this freshly + // created page. Mirrors the slug-first row format produced by + // {@link #buildExistingPagesIndex}: `[[slug]] — title — summary`. + // Keeps the LLM's view of the index uniformly slug-first across + // pre-existing rows and just-created rows. String briefSummary = pageSummary.length() > 100 ? pageSummary.substring(0, 100) : pageSummary; - liveIndex.append("\n- ").append(slug).append(": ").append(briefSummary); + liveIndex.append("\n- [[").append(slug).append("]]"); + if (title != null && !title.isBlank()) { + liveIndex.append(" — ").append(title); + } + if (briefSummary != null && !briefSummary.isBlank()) { + liveIndex.append(" — ").append(briefSummary); + } } ok = true; } catch (RuntimeException e) { @@ -1228,7 +1273,9 @@ public class WikiProcessingService { String title = pageMeta.path("title").asText(""); String summary = pageMeta.path("summary").asText(""); String configContent = kb.getConfigContent() != null ? kb.getConfigContent() : ""; - String createSystem = PromptLoader.loadPrompt("wiki/create-page-system"); + String createSystem = PromptLoader.loadPrompt("wiki/create-page-system") + .replace("{page_type_instructions}", + typeGuidance(kb.getId(), pageMeta.path("page_type").asText(""), "create")); String createUserTemplate = PromptLoader.loadPrompt("wiki/create-page-user"); String createUser = createUserTemplate .replace("{config}", configContent) @@ -1350,12 +1397,24 @@ public class WikiProcessingService { */ private boolean savePageContent(WikiKnowledgeBaseEntity kb, WikiRawMaterialEntity raw, String slug, String title, String content, String pageSummary) { - return savePageContent(kb, raw, slug, title, content, pageSummary, null); + return savePageContent(kb, raw, slug, title, content, pageSummary, null, null, null); } private boolean savePageContent(WikiKnowledgeBaseEntity kb, WikiRawMaterialEntity raw, String slug, String title, String content, String pageSummary, String pageType) { + return savePageContent(kb, raw, slug, title, content, pageSummary, pageType, null, null); + } + + private boolean savePageContent(WikiKnowledgeBaseEntity kb, WikiRawMaterialEntity raw, + String slug, String title, String content, String pageSummary, + String pageType, JsonNode metadataNode) { + return savePageContent(kb, raw, slug, title, content, pageSummary, pageType, metadataNode, null); + } + + private boolean savePageContent(WikiKnowledgeBaseEntity kb, WikiRawMaterialEntity raw, + String slug, String title, String content, String pageSummary, + String pageType, JsonNode metadataNode, JsonNode dependsOnNode) { Long kbId = kb.getId(); Long rawId = raw.getId(); @@ -1370,6 +1429,7 @@ public class WikiProcessingService { String actualSlug = existingByCanonical.getSlug(); pageService.updatePageByAi(kbId, actualSlug, content, pageSummary, rawId); pageService.mergeSourceLineage(existingByCanonical.getId(), rawId, raw.getTitle()); + afterPagePersisted(existingByCanonical.getId(), kbId, pageType, metadataNode, dependsOnNode, true); log.info("[Wiki] Phase B create slug='{}' canonical-matches existing '{}', updated", slug, actualSlug); return false; @@ -1386,6 +1446,7 @@ public class WikiProcessingService { if (winner != null) { pageService.updatePageByAi(kbId, winnerSlug, content, pageSummary, rawId); pageService.mergeSourceLineage(winner.getId(), rawId, raw.getTitle()); + afterPagePersisted(winner.getId(), kbId, pageType, metadataNode, dependsOnNode, true); log.info("[Wiki] Phase B create slug='{}' lost slug-claim race to '{}', updated", slug, winnerSlug); return false; @@ -1401,6 +1462,7 @@ public class WikiProcessingService { if (existing != null) { pageService.updatePageByAi(kbId, slug, content, pageSummary, rawId); pageService.mergeSourceLineage(existing.getId(), rawId, raw.getTitle()); + afterPagePersisted(existing.getId(), kbId, pageType, metadataNode, dependsOnNode, true); log.info("[Wiki] Phase B create page slug='{}' done (updated existing)", slug); return false; } @@ -1409,17 +1471,156 @@ public class WikiProcessingService { try { WikiPageEntity created = pageService.createPage(kbId, slug, title, content, pageSummary, sourceRawIds, pageType); pageService.mergeSourceLineage(created.getId(), rawId, raw.getTitle()); + afterPagePersisted(created.getId(), kbId, pageType, metadataNode, dependsOnNode, false); log.info("[Wiki] Phase B create page slug='{}' done (created)", slug); citationService.buildCitationsAsync(created.getId(), kbId); return true; } catch (org.springframework.dao.DuplicateKeyException e) { // Fallback 2: concurrent INSERT race — degrade to update pageService.updatePageByAi(kbId, slug, content, pageSummary, rawId); + WikiPageEntity raced = pageService.getBySlug(kbId, slug); + if (raced != null) { + afterPagePersisted(raced.getId(), kbId, pageType, metadataNode, dependsOnNode, true); + } log.info("[Wiki] Phase B create page slug='{}' lost INSERT race -> updated existing", slug); return false; } } + /** + * Validate the LLM-supplied metadata for a freshly created page against the + * KB profile's pageType schema and persist the cleaned result plus its + * validation outcome. No-op when the profile/validator beans are absent or + * no metadata was supplied — so default-profile KBs are unaffected. + */ + /** + * Common post-save outlet for every page create/update branch: validate & + * persist structured metadata and fire the pipeline trigger event. Sharing + * one outlet means the existing-page-update and race-arbitration paths get + * the same metadata and trigger handling as a clean create. + */ + private void afterPagePersisted(Long pageId, Long kbId, String pageType, + JsonNode metadataNode, JsonNode dependsOnNode, boolean isUpdate) { + applyValidatedMetadata(pageId, kbId, pageType, metadataNode); + deriveKnowledgeLayer(pageId, kbId, pageType); + applyDependencies(pageId, kbId, pageType, dependsOnNode); + // The page is committed (createPage / updatePageByAi are their own + // transactions), so the count is accurate. Idempotent + dedup-guarded + // downstream, so firing on update paths is safe. + if (eventPublisher != null && pageType != null && !pageType.isBlank()) { + eventPublisher.publishEvent(new vip.mate.wiki.event.WikiPageCreatedEvent(kbId, pageType, pageId)); + } + // When an existing fact page is updated, propagate staleness to the + // experience pages depending on it (async, off the ingest thread). + if (isUpdate && eventPublisher != null && dependencyService != null + && pageTypeProfileService != null && !pageTypeProfileService.isExperience(kbId, pageType)) { + eventPublisher.publishEvent(new vip.mate.wiki.event.WikiFactPageUpdatedEvent( + kbId, pageId, "fact page updated during ingest")); + } + } + + /** Stamp the page's knowledge layer (fact/experience) derived from its pageType profile. */ + private void deriveKnowledgeLayer(Long pageId, Long kbId, String pageType) { + if (pageTypeProfileService == null || pageType == null || pageType.isBlank()) { + return; + } + String layer = pageTypeProfileService.resolveLayer(kbId, pageType); + if (layer != null) { + pageService.setKnowledgeLayer(pageId, layer); + } + } + + /** + * Persist an experience page's fact dependencies declared by the LLM + * ({@code depends_on}: slugs). Resolves slugs to ids and delegates to the + * dependency engine, which rejects cross-KB / non-fact / missing targets; + * rejections are logged as a warning (non-blocking, MVP). + */ + private void applyDependencies(Long pageId, Long kbId, String pageType, JsonNode dependsOnNode) { + if (dependencyService == null || pageTypeProfileService == null + || dependsOnNode == null || !dependsOnNode.isArray() || dependsOnNode.isEmpty()) { + return; + } + if (!pageTypeProfileService.isExperience(kbId, pageType)) { + return; // only experience pages declare fact dependencies + } + java.util.List depIds = new java.util.ArrayList<>(); + for (JsonNode n : dependsOnNode) { + String slug = n.asText(""); + if (slug.isBlank()) continue; + WikiPageEntity dep = pageService.getBySlug(kbId, slug); + if (dep != null) { + depIds.add(dep.getId()); + } + } + try { + java.util.List rejected = dependencyService.setDependencies(kbId, pageId, depIds); + if (!rejected.isEmpty()) { + log.warn("[Wiki] page {} dependency warnings: {}", pageId, rejected); + } + } catch (Exception e) { + log.warn("[Wiki] dependency persistence failed for page {}: {}", pageId, e.getMessage()); + } + } + + private String emptyOr(String s) { + return (s == null || s.isBlank()) ? "(无)" : s; + } + + /** Allowed page types fragment for prompt injection (profile-driven; legacy fallback). */ + private String allowedTypesFragment(Long kbId) { + return pageTypeProfileService != null + ? pageTypeProfileService.describeForPrompt(kbId) + : "concept / person / place / event / technology / organization / product / term / process / other"; + } + + /** + * Per-type guidance for the create / merge prompts: the stage instruction + * plus, for the create stage, the Markdown template skeleton. Empty-safe. + */ + private String typeGuidance(Long kbId, String pageType, String stage) { + if (pageTypeProfileService == null || pageType == null || pageType.isBlank()) { + return "(无特定指引)"; + } + String instr = pageTypeProfileService.stageInstruction(kbId, pageType, stage); + String tpl = "create".equals(stage) ? pageTypeProfileService.templateMarkdown(kbId, pageType) : ""; + StringBuilder sb = new StringBuilder(); + if (instr != null && !instr.isBlank()) { + sb.append(instr); + } + if (tpl != null && !tpl.isBlank()) { + if (sb.length() > 0) sb.append("\n\n"); + sb.append("请按以下 Markdown 骨架组织正文:\n").append(tpl); + } + return sb.length() == 0 ? "(无特定指引)" : sb.toString(); + } + + private void applyValidatedMetadata(Long pageId, Long kbId, String pageType, + JsonNode metadataNode) { + if (pageId == null || pageTypeProfileService == null || metadataValidator == null) { + return; + } + if (metadataNode == null || metadataNode.isMissingNode() || metadataNode.isNull() + || !metadataNode.isObject() || metadataNode.isEmpty()) { + return; + } + try { + vip.mate.wiki.profile.WikiPageTypeProfile profile = pageTypeProfileService.resolveProfile(kbId); + vip.mate.wiki.profile.WikiPageTypeDef def = profile.get(pageType); + @SuppressWarnings("unchecked") + java.util.Map raw = objectMapper.convertValue(metadataNode, java.util.Map.class); + vip.mate.wiki.profile.WikiMetadataValidator.ValidationResult result = + metadataValidator.validate(def, raw, profile.isAllowAdditionalFields(), "create"); + String metadataJson = objectMapper.writeValueAsString(result.getCleaned()); + String validationJson = result.getWarnings().isEmpty() + ? null : objectMapper.writeValueAsString(result.getWarnings()); + pageService.applyMetadata(pageId, metadataJson, result.getStatus(), + validationJson, profile.getVersion()); + } catch (Exception e) { + log.warn("[Wiki] metadata validation failed for page {}: {}", pageId, e.getMessage()); + } + } + /** * RFC-012 M2 v2 — 阶段 B 单页 merge：把 chunk 文本合并进一个已有页面。 *

    @@ -1448,7 +1649,9 @@ public class WikiProcessingService { } String configContent = kb.getConfigContent() != null ? kb.getConfigContent() : ""; - String mergeSystem = PromptLoader.loadPrompt("wiki/merge-page-system"); + String mergeSystem = PromptLoader.loadPrompt("wiki/merge-page-system") + .replace("{page_type_merge_instruction}", + typeGuidance(kbId, existing.getPageType(), "merge")); // Trim existing content to prevent context overflow on small models (qwen-turbo: 4096 tokens). // Merging a 3000-char page + 30K chunk blows past the limit → truncated JSON → parse failure. // 1800 chars ≈ ~600 tokens, leaving ample room for the chunk and response. @@ -1584,10 +1787,16 @@ public class WikiProcessingService { String sample = textContent.length() > sampleChars ? textContent.substring(0, sampleChars) + "\n...[文档较长，以上为节选]" : textContent; + // Inject the existing-pages index so the LLM can pick a real `related_pages` + // whitelist of slugs that already exist in the KB. Generation prompts + // downstream see the validated whitelist via `documentMap`, which lets + // them link confidently instead of inventing targets. + String existingPagesIndex = buildExistingPagesIndex(kb.getId()); String system = PromptLoader.loadPrompt("wiki/analyze-system"); String userTemplate = PromptLoader.loadPrompt("wiki/analyze-user"); String user = userTemplate .replace("{raw_title}", raw.getTitle()) + .replace("{existing_pages}", existingPagesIndex) .replace("{text_sample}", sample); Prompt prompt = new Prompt(List.of( new SystemMessage(system), @@ -1599,11 +1808,17 @@ public class WikiProcessingService { kb.getId(), vip.mate.wiki.job.WikiJobStep.ROUTE); JsonNode json = parseJsonResponse(response); if (json != null) { - log.info("[Wiki] Document analysis done for raw={}: topics={}, concepts={}", + // Validate related_pages against the active KB slug set BEFORE + // letting it flow downstream. An LLM that ignores the "must + // come from the index" rule and invents slugs would otherwise + // pollute the generation prompt, undoing the work of Phase 3. + JsonNode validated = validateRelatedPages(kb.getId(), json); + log.info("[Wiki] Document analysis done for raw={}: topics={}, concepts={}, related_pages={}", raw.getId(), - json.path("topics").size(), - json.path("key_concepts").size()); - return json.toPrettyString(); + validated.path("topics").size(), + validated.path("key_concepts").size(), + validated.path("related_pages").size()); + return validated.toPrettyString(); } } catch (Exception e) { log.warn("[Wiki] Document analysis failed for raw={}, continuing without: {}", raw.getId(), e.getMessage()); @@ -1612,7 +1827,103 @@ public class WikiProcessingService { } /** - * 构建已有 Wiki 页面索引（供 LLM 参考） + * Render the analyze-stage output for inclusion in route / batch-create + * user prompts. The full JSON goes into a fenced code block, and any + * {@code related_pages} array is also surfaced as a plain "recommended + * link targets" section right above it so the LLM doesn't have to + * parse JSON to find the whitelist. + */ + private String buildDocumentMapSection(String documentMap) { + if (documentMap == null || documentMap.isBlank()) return ""; + StringBuilder sb = new StringBuilder(); + try { + JsonNode node = objectMapper.readTree(documentMap); + JsonNode related = node.path("related_pages"); + if (related.isArray() && related.size() > 0) { + sb.append("## 推荐链接到的页面（由分析阶段产出，已通过 slug 白名单校验，可优先使用）\n\n"); + for (JsonNode el : related) { + String slug = el.asText("").trim(); + if (slug.isEmpty()) continue; + sb.append("- [[").append(slug).append("]]\n"); + } + sb.append("\n"); + } + } catch (Exception ignored) { + // documentMap might not be parseable JSON (older runs, partial + // output) — fall through and emit the raw block below. + } + sb.append("## 文档全局概念地图（预分析结果，供页面内容生成参考）\n\n```json\n") + .append(documentMap).append("\n```\n"); + return sb.toString(); + } + + /** + * Drop any {@code related_pages} entry not in the KB's active slug set. + *

    + * The analyze-stage system prompt explicitly tells the LLM that every + * entry must come from the supplied index, but production LLMs are not + * 100% reliable on negative constraints. This server-side validator is + * the contract enforcement: invalid entries are silently dropped (with + * a single warning log per analyze call, batched), so the downstream + * generation prompt never sees an invented slug masquerading as a + * curated whitelist. + */ + private JsonNode validateRelatedPages(Long kbId, JsonNode analysisJson) { + JsonNode relatedNode = analysisJson.path("related_pages"); + if (!relatedNode.isArray() || relatedNode.size() == 0) return analysisJson; + + java.util.Set activeSlugs; + try { + activeSlugs = linkService.lowercaseSlugSet(pageService.listSummaries(kbId)); + } catch (RuntimeException e) { + // Without a slug set, no validation is possible. Drop the whole + // related_pages array — better than passing through unvalidated + // suggestions that could be hallucinated. + log.warn("[Wiki] Cannot validate related_pages for kbId={}, dropping array: {}", + kbId, e.toString()); + ObjectNode result = analysisJson.deepCopy(); + result.putArray("related_pages"); + return result; + } + + com.fasterxml.jackson.databind.node.ArrayNode keptArray = objectMapper.createArrayNode(); + java.util.List dropped = new java.util.ArrayList<>(); + for (JsonNode el : relatedNode) { + String slug = el.asText("").trim(); + if (slug.isEmpty()) continue; + if (activeSlugs.contains(slug.toLowerCase(java.util.Locale.ROOT))) { + keptArray.add(slug); + } else { + dropped.add(slug); + } + } + if (!dropped.isEmpty()) { + log.warn("[Wiki] Analyze dropped {} hallucinated related_pages entries for kbId={}: {}", + dropped.size(), kbId, dropped); + } + ObjectNode result = analysisJson.deepCopy(); + result.set("related_pages", keptArray); + return result; + } + + /** + * Build the "existing pages" index that the LLM consults when picking + * cross-references during page generation / merge / compile. + *

    + * Slug-first format — each line begins with {@code [[slug]]} so the + * model has exactly one syntactically-valid target shape to copy. Title + * and summary follow as semantic context, separated by em-dashes, so the + * model can pick a relevant target without being confused about whether + * to write the title or the slug. The earlier "**[[Title]]** (slug: `x`)" + * format exposed two candidate target strings on every row, which let + * the model write {@code [[Title]]} freely and produced the lint noise + * this RFC exists to close. + *

    + * Manual-edit and archived markers stay as plain-text trailing tags so + * they don't drift into the link form. The lint downstream treats a + * title-only match as a soft warning in v1; the long-term direction is + * to delete the title-fallback once content has been regenerated under + * the slug-first prompt. */ private String buildExistingPagesIndex(Long kbId) { List summaries = pageService.listSummaries(kbId); @@ -1622,12 +1933,17 @@ public class WikiProcessingService { StringBuilder sb = new StringBuilder(); for (WikiPageEntity page : summaries) { - sb.append("- **[[").append(page.getTitle()).append("]]** (slug: `").append(page.getSlug()).append("`"); - if ("manual".equals(page.getLastUpdatedBy())) { - sb.append(", 手动编辑"); + sb.append("- [[").append(page.getSlug()).append("]]"); + if (page.getTitle() != null && !page.getTitle().isBlank()) { + sb.append(" — ").append(page.getTitle()); + } + if ("manual".equals(page.getLastUpdatedBy())) { + sb.append(" (手动编辑)"); + } + String summary = page.getSummary(); + if (summary != null && !summary.isBlank()) { + sb.append(" — ").append(summary); } - sb.append("): "); - sb.append(page.getSummary() != null ? page.getSummary() : "无摘要"); sb.append("\n"); } return sb.toString().trim(); @@ -2137,7 +2453,9 @@ public class WikiProcessingService { // Use existing two-phase single-page create logic String existingPagesIndex = buildExistingPagesIndex(kb.getId()); String configContent = kb.getConfigContent() != null ? kb.getConfigContent() : ""; - String createSystem = PromptLoader.loadPrompt("wiki/create-page-system"); + String createSystem = PromptLoader.loadPrompt("wiki/create-page-system") + .replace("{page_type_instructions}", + typeGuidance(kb.getId(), page.getPageType(), "create")); String createUserTemplate = PromptLoader.loadPrompt("wiki/create-page-user"); String createUser = createUserTemplate .replace("{config}", configContent) diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiRawMaterialService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiRawMaterialService.java index ba2ea7b8..b9a6d697 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiRawMaterialService.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiRawMaterialService.java @@ -86,6 +86,81 @@ public class WikiRawMaterialService { .eq(WikiRawMaterialEntity::getSourcePath, sourcePath)); } + /** + * Import a text file discovered by a directory scan, detecting content + * changes by hash: unchanged content (a raw with the same hash already + * exists) is a no-op, while changed content creates a new raw and triggers + * processing — so a modified file is re-ingested rather than silently + * skipped. The originating path is recorded for diagnostics. + * + * @return {@code true} when the file was newly ingested (new or changed + * content), {@code false} when skipped as unchanged + */ + public boolean ingestTextFileFromScan(Long kbId, String fileName, String absolutePath, String content) { + String hash = computeHash(content); + WikiRawMaterialEntity sameContent = rawMapper.selectOne( + new LambdaQueryWrapper() + .eq(WikiRawMaterialEntity::getKbId, kbId) + .eq(WikiRawMaterialEntity::getContentHash, hash) + .last("LIMIT 1")); + // addText dedups internally by hash, so this reuses sameContent when + // unchanged and inserts + triggers processing when the content differs. + WikiRawMaterialEntity raw = addText(kbId, fileName, content); + // Only stamp the path on a genuinely new raw. When the content matched + // an existing raw (possibly a different file with identical content), + // overwriting its sourcePath would corrupt that raw's provenance. + if (raw != null && sameContent == null) { + updateSourcePath(raw.getId(), absolutePath); + } + return sameContent == null; + } + + /** + * Import a binary file discovered by a directory scan, detecting content + * changes by hashing the bytes: unchanged content (a raw with the same hash + * exists) is skipped, while changed content is re-ingested via + * {@link #addFile}. The unchanged case reads the file once; only a + * new/changed file is read again by addFile. + * + * @return {@code true} when newly ingested, {@code false} when unchanged + */ + public boolean ingestBinaryFileFromScan(Long kbId, String title, String sourceType, + String absolutePath, long fileSize) { + String hash = null; + try { + hash = computeHashOfBytes(java.nio.file.Files.readAllBytes(java.nio.file.Paths.get(absolutePath))); + } catch (Exception e) { + log.warn("[Wiki] Could not hash file for change detection: {}", e.getMessage()); + } + if (hash != null) { + WikiRawMaterialEntity sameContent = rawMapper.selectOne( + new LambdaQueryWrapper() + .eq(WikiRawMaterialEntity::getKbId, kbId) + .eq(WikiRawMaterialEntity::getContentHash, hash) + .last("LIMIT 1")); + if (sameContent != null) { + return false; // unchanged — addFile not called, avoids a second read + } + } + // Pass the hash we already computed so addFile does not re-read the file. + addFile(kbId, title, sourceType, null, absolutePath, fileSize, hash); + return true; + } + + /** + * Record the originating file path on a raw material via a partial update, + * so a later directory re-scan can dedup it by source path. Used for + * text-file imports, which otherwise carry no path. + */ + public void updateSourcePath(Long rawId, String sourcePath) { + if (rawId == null) { + return; + } + rawMapper.update(null, new com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper() + .eq(WikiRawMaterialEntity::getId, rawId) + .set(WikiRawMaterialEntity::getSourcePath, sourcePath)); + } + public List listPending(Long kbId) { return rawMapper.selectList( new LambdaQueryWrapper() @@ -153,6 +228,19 @@ public class WikiRawMaterialService { @Transactional public WikiRawMaterialEntity addFile(Long kbId, String title, String sourceType, String mimeType, String sourcePath, long fileSize) { + return addFile(kbId, title, sourceType, mimeType, sourcePath, fileSize, null); + } + + /** + * As {@link #addFile(Long, String, String, String, String, long)}, but with + * an optional precomputed content hash so a caller that already read the + * file (e.g. the directory scan's change detection) does not pay a second + * full-file read to dedup. + */ + @Transactional + public WikiRawMaterialEntity addFile(Long kbId, String title, String sourceType, + String mimeType, String sourcePath, long fileSize, + String precomputedHash) { WikiRawMaterialEntity entity = new WikiRawMaterialEntity(); entity.setKbId(kbId); entity.setTitle(title); @@ -166,11 +254,15 @@ public class WikiRawMaterialService { // directly — the previous `new String(bytes, UTF_8)` round-trip produced unstable // hashes for binary files (PDF/Office) because invalid UTF-8 sequences become // replacement characters, collapsing distinct files into the same hash. - try { - byte[] bytes = java.nio.file.Files.readAllBytes(java.nio.file.Paths.get(sourcePath)); - entity.setContentHash(computeHashOfBytes(bytes)); - } catch (Exception e) { - log.warn("[Wiki] Could not compute file hash for dedup: {}", e.getMessage()); + if (precomputedHash != null) { + entity.setContentHash(precomputedHash); + } else { + try { + byte[] bytes = java.nio.file.Files.readAllBytes(java.nio.file.Paths.get(sourcePath)); + entity.setContentHash(computeHashOfBytes(bytes)); + } catch (Exception e) { + log.warn("[Wiki] Could not compute file hash for dedup: {}", e.getMessage()); + } } // Dedup: reuse any existing row with the same hash in this KB (any status) @@ -449,7 +541,7 @@ public class WikiRawMaterialService { // 二进制文件：调用 DocumentExtractTool 提取 if (entity.getSourcePath() != null && !entity.getSourcePath().isBlank()) { try { - String result = documentExtractTool.extract_document_text(entity.getSourcePath(), null); + String result = documentExtractTool.extract_document_text(entity.getSourcePath(), null, null); JSONObject json = JSONUtil.parseObj(result); if (json.getBool("success", false)) { String text = json.getStr("text"); diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourcePathValidator.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourcePathValidator.java new file mode 100644 index 00000000..2400a88b --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourcePathValidator.java @@ -0,0 +1,91 @@ +package vip.mate.wiki.service; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import vip.mate.wiki.WikiProperties; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; +import java.util.List; + +/** + * Single point of truth for validating a KB source directory path, shared by + * the manual directory scan and the source-directory config endpoint (and the + * future filesystem watcher). + * + *

    The raw path is canonicalized with {@code toRealPath()} (resolving + * symlinks) when it exists, so a symlink cannot escape the allowed area. When + * {@code mate.wiki.allowed-source-roots} is configured, the resolved path must + * lie within one of those roots; when it is empty the path is only + * canonicalized (opt-in enforcement — existing single-tenant / desktop setups + * keep working, server operators can lock it down). + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiSourcePathValidator { + + private final WikiProperties properties; + + public WikiSourcePathValidator(WikiProperties properties) { + this.properties = properties; + } + + /** + * Canonicalize and authorize a source directory path. + * + * @return the resolved absolute path + * @throws IllegalArgumentException when blank or outside the allowed roots + */ + public Path validateDirectory(String rawPath) { + if (rawPath == null || rawPath.isBlank()) { + throw new IllegalArgumentException("Source directory path is required"); + } + Path resolved = canonicalize(Paths.get(rawPath)); + List roots = properties.getAllowedSourceRoots(); + if (roots == null || roots.isEmpty()) { + if (properties.isRequireAllowedRoots()) { + throw new IllegalArgumentException( + "No allowed source roots are configured; refusing the path (fail-closed). " + + "Set mate.wiki.allowed-source-roots to permit directories."); + } + return resolved; + } + for (String root : roots) { + if (root == null || root.isBlank()) { + continue; + } + Path rootPath = canonicalize(Paths.get(root)); + if (resolved.startsWith(rootPath)) { + return resolved; + } + } + throw new IllegalArgumentException( + "Path is outside the allowed source roots: " + resolved); + } + + /** Whether a path passes validation, without throwing. */ + public boolean isAllowed(String rawPath) { + try { + validateDirectory(rawPath); + return true; + } catch (IllegalArgumentException e) { + return false; + } + } + + private Path canonicalize(Path path) { + Path abs = path.toAbsolutePath().normalize(); + if (Files.exists(abs)) { + try { + return abs.toRealPath(); + } catch (IOException e) { + log.debug("[WikiPath] toRealPath failed for {}: {}", abs, e.getMessage()); + } + } + return abs; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourceWatcherService.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourceWatcherService.java new file mode 100644 index 00000000..2101a130 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiSourceWatcherService.java @@ -0,0 +1,94 @@ +package vip.mate.wiki.service; + +import lombok.extern.slf4j.Slf4j; +import net.javacrumbs.shedlock.spring.annotation.SchedulerLock; +import org.springframework.scheduling.annotation.Scheduled; +import org.springframework.stereotype.Service; +import vip.mate.wiki.WikiProperties; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; + +/** + * Watches each KB's configured source directory and auto-ingests new files. + * + *

    Implemented as a periodic, single-owner scan rather than per-node OS file + * watchers: {@link SchedulerLock} (ShedLock) ensures exactly one instance runs + * a cycle, so a multi-instance deployment never double-ingests, and a periodic + * scan is inherently restart-safe (it picks up anything missed while down). The + * underlying {@link WikiDirectoryScanService} dedups by source path, so a + * re-scan only ingests genuinely new files; deletes are never propagated. + * Path validation (symlink resolution + allowed roots) is enforced by the + * shared validator inside the scan. + * + * @author MateClaw Team + */ +@Slf4j +@Service +public class WikiSourceWatcherService { + + private final WikiKnowledgeBaseService kbService; + private final WikiProperties properties; + private final java.util.List sourceProviders; + + public WikiSourceWatcherService(WikiKnowledgeBaseService kbService, + WikiProperties properties, + java.util.List sourceProviders) { + this.kbService = kbService; + this.properties = properties; + this.sourceProviders = sourceProviders; + } + + /** The registered source-provider types (filesystem ships; api/mq pluggable later). */ + public java.util.List availableSourceTypes() { + return sourceProviders.stream().map(vip.mate.wiki.source.WikiIngestSourceProvider::sourceType).toList(); + } + + /** Scheduled entry point — gated by config, serialized across instances. */ + @Scheduled(fixedDelayString = "${mate.wiki.watcher-interval-ms:300000}", initialDelay = 60_000) + @SchedulerLock(name = "wiki-source-watcher", lockAtMostFor = "PT10M", lockAtLeastFor = "PT30S") + public void scheduledScan() { + if (!properties.isWatcherEnabled()) { + return; + } + int added = runScanCycle(); + if (added > 0) { + log.info("[WikiWatcher] scan cycle ingested {} new file(s)", added); + } + } + + /** + * Scan every KB that has a source directory configured and return the total + * number of new files ingested. Per-KB failures are logged and skipped so + * one bad directory cannot stall the others. + */ + public int runScanCycle() { + int totalAdded = 0; + for (WikiKnowledgeBaseEntity kb : kbService.listAll()) { + vip.mate.wiki.source.WikiIngestSourceProvider provider = providerFor(kb); + if (provider == null) { + continue; + } + try { + WikiDirectoryScanService.ScanResult result = provider.sync(kb); + totalAdded += result.added(); + if (!result.errors().isEmpty()) { + log.warn("[WikiWatcher] KB {} ({}) sync reported issues: {}", + kb.getId(), provider.sourceType(), result.errors()); + } + } catch (Exception e) { + log.warn("[WikiWatcher] sync failed for KB {} ({}): {}", + kb.getId(), provider.sourceType(), e.getMessage()); + } + } + return totalAdded; + } + + /** The first registered provider that supports the KB, or null. */ + public vip.mate.wiki.source.WikiIngestSourceProvider providerFor(WikiKnowledgeBaseEntity kb) { + for (vip.mate.wiki.source.WikiIngestSourceProvider p : sourceProviders) { + if (p.supports(kb)) { + return p; + } + } + return null; + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiStalePropagationListener.java b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiStalePropagationListener.java new file mode 100644 index 00000000..81ed2a92 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/service/WikiStalePropagationListener.java @@ -0,0 +1,37 @@ +package vip.mate.wiki.service; + +import lombok.extern.slf4j.Slf4j; +import org.springframework.context.event.EventListener; +import org.springframework.scheduling.annotation.Async; +import org.springframework.stereotype.Component; +import vip.mate.wiki.event.WikiFactPageUpdatedEvent; + +/** + * Propagates staleness asynchronously when a fact-layer page is updated: every + * experience page depending on it is marked stale. Runs off the ingest thread + * so a fan-out over many dependents never blocks ingest; the fact page is + * already committed when the event fires. Marking is idempotent, so repeated + * events for the same page are harmless. + * + * @author MateClaw Team + */ +@Slf4j +@Component +public class WikiStalePropagationListener { + + private final WikiDependencyService dependencyService; + + public WikiStalePropagationListener(WikiDependencyService dependencyService) { + this.dependencyService = dependencyService; + } + + @Async + @EventListener + public void onFactPageUpdated(WikiFactPageUpdatedEvent event) { + try { + dependencyService.markDependentsStale(event.kbId(), event.factPageId(), event.reason()); + } catch (Exception e) { + log.warn("[WikiStale] propagation failed for fact page {}: {}", event.factPageId(), e.getMessage()); + } + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/source/FilesystemSourceProvider.java b/mateclaw-server/src/main/java/vip/mate/wiki/source/FilesystemSourceProvider.java new file mode 100644 index 00000000..9fc6d393 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/source/FilesystemSourceProvider.java @@ -0,0 +1,37 @@ +package vip.mate.wiki.source; + +import org.springframework.stereotype.Component; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.service.WikiDirectoryScanService; + +/** + * The built-in filesystem source: syncs a KB by scanning its configured source + * directory (path validation, symlink resolution and content-hash change + * detection live in the scan service). + * + * @author MateClaw Team + */ +@Component +public class FilesystemSourceProvider implements WikiIngestSourceProvider { + + private final WikiDirectoryScanService scanService; + + public FilesystemSourceProvider(WikiDirectoryScanService scanService) { + this.scanService = scanService; + } + + @Override + public String sourceType() { + return "filesystem"; + } + + @Override + public boolean supports(WikiKnowledgeBaseEntity kb) { + return kb != null && kb.getSourceDirectory() != null && !kb.getSourceDirectory().isBlank(); + } + + @Override + public WikiDirectoryScanService.ScanResult sync(WikiKnowledgeBaseEntity kb) { + return scanService.scanDirectory(kb.getId(), kb.getSourceDirectory()); + } +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/source/WikiIngestSourceProvider.java b/mateclaw-server/src/main/java/vip/mate/wiki/source/WikiIngestSourceProvider.java new file mode 100644 index 00000000..d11d916e --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/wiki/source/WikiIngestSourceProvider.java @@ -0,0 +1,28 @@ +package vip.mate.wiki.source; + +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.service.WikiDirectoryScanService; + +/** + * Pluggable source of raw material for a knowledge base. The watcher iterates + * KBs and asks each registered provider whether it {@link #supports} the KB, + * then {@link #sync}s it. The filesystem implementation ships today; API / + * message-queue sources can be added later by implementing this interface + * without touching the watcher. + * + * @author MateClaw Team + */ +public interface WikiIngestSourceProvider { + + /** Stable source-type id, e.g. {@code filesystem} / {@code api} / {@code mq}. */ + String sourceType(); + + /** Whether this provider can sync the given KB (e.g. it has the relevant config). */ + boolean supports(WikiKnowledgeBaseEntity kb); + + /** + * Pull new / changed material for the KB and ingest it, returning the + * scan-style result (scanned / added / skipped / errors). + */ + WikiDirectoryScanService.ScanResult sync(WikiKnowledgeBaseEntity kb); +} diff --git a/mateclaw-server/src/main/java/vip/mate/wiki/tool/WikiTool.java b/mateclaw-server/src/main/java/vip/mate/wiki/tool/WikiTool.java index 93fea5d5..cff6f4ee 100644 --- a/mateclaw-server/src/main/java/vip/mate/wiki/tool/WikiTool.java +++ b/mateclaw-server/src/main/java/vip/mate/wiki/tool/WikiTool.java @@ -11,6 +11,9 @@ import org.springframework.context.ApplicationEventPublisher; import org.springframework.ai.tool.annotation.Tool; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.stereotype.Component; +import vip.mate.agent.context.ChatOrigin; +import vip.mate.agent.context.ChatOriginHolder; +import vip.mate.approval.ApprovalWorkflowService; import vip.mate.wiki.dto.*; import vip.mate.wiki.job.WikiProcessingJobService; import vip.mate.wiki.job.event.WikiJobCreatedEvent; @@ -31,7 +34,14 @@ import java.util.stream.Collectors; /** * Wiki knowledge base tools for agent conversations. *

    - * All tools auto-resolve kbId from agentId; LLM never needs to pass it directly. + * Every tool resolves its target KB through a small precedence ladder: + * an explicit {@code kbId} from {@code wiki_list_kbs} wins outright, then + * an explicit {@code kbName} (with fail-closed "ambiguous"/"not visible" + * errors when needed), and only when both are absent does the tool fall + * back to the agent's primary KB. The {@code kbId} surface is public so + * the LLM can disambiguate duplicate-named KBs — see + * {@link #wiki_list_kbs} and {@code WikiKnowledgeBaseService.findVisibleById} + * for the visibility gate. * * @author MateClaw Team */ @@ -71,16 +81,88 @@ public class WikiTool { @Autowired(required = false) private WikiTransformationAggregator transformationAggregator; + /** + * Optional approval workflow. When present, an {@code APPROVAL_REQUIRED} + * write records a real pending approval in the operator inbox (keyed to the + * current conversation via {@link ChatOriginHolder}), so the operation is + * visible and auditable rather than silently blocked. Absent in lightweight + * contexts (tests, headless tools) — the write still fails closed. + */ + @Autowired(required = false) + private ApprovalWorkflowService approvalWorkflowService; + + /** + * Per-agent pageType permission gate. Mandatory: this is a security control, + * so it is a required constructor dependency rather than an optional bean — + * a missing gate must fail loudly at startup, never silently fail open. + */ + private final WikiPageTypePermissionService pageTypePermissionService; + public WikiTool(WikiPageService pageService, WikiKnowledgeBaseService kbService, WikiRawMaterialService rawService, HybridRetriever hybridRetriever, - ObjectMapper objectMapper) { + ObjectMapper objectMapper, + WikiPageTypePermissionService pageTypePermissionService) { this.pageService = pageService; this.kbService = kbService; this.rawService = rawService; this.hybridRetriever = hybridRetriever; this.objectMapper = objectMapper; + this.pageTypePermissionService = pageTypePermissionService; + } + + // ==================== Knowledge-base discovery ==================== + + @Tool(description = """ + List every knowledge base visible to this agent — both KBs explicitly + bound to the agent and shared workspace-level KBs. + + Every other wiki tool (read / list / search / semantic search / …) + accepts two OPTIONAL routing arguments. Use them in this order: + 1. `kbName` — readable name from the output below. Easiest. + 2. `kbId` — numeric id from the output below. Use this when + two KBs share the same name and `kbName` returns + an "Ambiguous kbName" error. + Omit both and the tool falls back to the agent's primary KB, + which is fine when the agent only reaches one KB. + + Output fields per KB: + - kbId — string-encoded numeric id (use as `kbId` param) + - name — copy verbatim into `kbName` param + - description — operator-supplied summary + - pageCount — number of pages currently in the KB + - isPrimary — true for the KB used when both routing + arguments are omitted + - boundToAgent — true if the KB is explicitly bound to this agent + """) + public String wiki_list_kbs( + @ToolParam(description = "Agent ID") Long agentId) { + List kbs = kbService.listByAgentId(agentId); + WikiKnowledgeBaseEntity primary = kbService.resolvePrimaryKb(agentId); + Long primaryId = primary == null ? null : primary.getId(); + + JSONArray arr = new JSONArray(); + for (WikiKnowledgeBaseEntity kb : kbs) { + // kbId is rendered as a STRING per the workspace-wide Snowflake- + // precision rule: a 19-digit id round-tripped through a JSON + // number loses its last 2-3 digits whenever it touches a JS + // runtime. The LLM hands the value back to us through a Java + // Long @ToolParam, which is precision-safe, so the lossy hop + // is purely defensive. + arr.add(JSONUtil.createObj() + .set("kbId", String.valueOf(kb.getId())) + .set("name", kb.getName()) + .set("description", kb.getDescription()) + .set("pageCount", kb.getPageCount() == null ? 0 : kb.getPageCount()) + .set("isPrimary", kb.getId().equals(primaryId)) + .set("boundToAgent", kb.getAgentId() != null)); + } + return JSONUtil.createObj() + .set("kbCount", kbs.size()) + .set("primary", primary == null ? null : primary.getName()) + .set("kbs", arr) + .toString(); } // ==================== RFC-032: Enhanced wiki_read_page ==================== @@ -95,21 +177,26 @@ public class WikiTool { @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Page slug") String slug, @ToolParam(description = "Max characters to return (null = full page)", required = false) Integer maxChars, - @ToolParam(description = "Section heading to extract (null = all sections)", required = false) String sectionHeading) { + @ToolParam(description = "Section heading to extract (null = all sections)", required = false) String sectionHeading, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (slug == null || slug.isBlank()) { return error("slug is required"); } - Long kbId = resolveKbId(agentId); - if (kbId == null) { - return error("No wiki knowledge base found for this agent"); - } + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); WikiPageEntity page = pageService.getBySlug(kbId, slug); if (page == null) { return error("Page not found: " + slug); } + if (!canRead(pageTypeAccess(agentId, kbId), page)) { + // Page type not readable by this agent — do not leak its existence. + return error("Page not found: " + slug); + } pageService.trackReference(kbId, slug); @@ -140,23 +227,27 @@ public class WikiTool { """) public String wiki_list_pages( @ToolParam(description = "Agent ID") Long agentId, - @ToolParam(description = "Title keyword filter (optional)", required = false) String query) { + @ToolParam(description = "Title keyword filter (optional)", required = false) String query, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { - Long kbId = resolveKbId(agentId); - if (kbId == null) { - return error("No wiki knowledge base found for this agent"); - } + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); + WikiPageTypePermissionService.Access access = pageTypeAccess(agentId, kbId); List pages; if (query != null && !query.isBlank()) { List ids = pageService.searchPages(kbId, query).stream() .filter(p -> !"system".equals(p.getPageType())) + .filter(p -> canRead(access, p)) .map(WikiPageEntity::getId).limit(30).toList(); if (ids.isEmpty()) { pages = List.of(); } else { pages = pageService.listSummaries(kbId).stream() .filter(p -> !"system".equals(p.getPageType())) + .filter(p -> canRead(access, p)) .filter(p -> ids.stream().anyMatch(id -> Objects.equals(id, p.getId()))) .map(p -> new WikiPageLite(p.getId(), p.getSlug(), p.getTitle(), p.getSummary(), p.getPageType())) .toList(); @@ -166,6 +257,7 @@ public class WikiTool { // Agents can still wiki_read_page("overview") explicitly. pages = pageService.listSummaries(kbId).stream() .filter(p -> !"system".equals(p.getPageType())) + .filter(p -> canRead(access, p)) .map(p -> new WikiPageLite(p.getId(), p.getSlug(), p.getTitle(), p.getSummary(), p.getPageType())) .toList(); } @@ -197,20 +289,37 @@ public class WikiTool { @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Search query") String query, @ToolParam(description = "Mode: keyword|semantic|hybrid (default: hybrid)", required = false) String mode, - @ToolParam(description = "Max results (default 5, max 20)", required = false) Integer topK) { + @ToolParam(description = "Max results (default 5, max 20)", required = false) Integer topK, + @ToolParam(description = "Knowledge layer filter: fact | experience | all (default all). 'fact' = factual pages (and unlayered pages); 'experience' = synthesis/analysis pages.", required = false) String layer, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (query == null || query.isBlank()) { return error("query is required"); } - Long kbId = resolveKbId(agentId); - if (kbId == null) { - return error("No wiki knowledge base found for this agent"); - } + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); int k = (topK != null && topK > 0) ? Math.min(topK, 20) : 5; List results = hybridRetriever.search(kbId, query, mode, k); + // Drop hits this agent may not read (by page type) or that fall outside + // the requested knowledge layer. Both need the page, so fetch it once. + WikiPageTypePermissionService.Access access = pageTypeAccess(agentId, kbId); + boolean layerFilter = layer != null && !layer.isBlank() && !"all".equalsIgnoreCase(layer.trim()); + if (access != null || layerFilter) { + final Long resolvedKbId = kbId; + final String layerWanted = layer; + results = results.stream() + .filter(r -> { + WikiPageEntity p = pageService.getBySlug(resolvedKbId, r.slug()); + return canRead(access, p) && matchesLayer(p == null ? null : p.getKnowledgeLayer(), layerWanted); + }) + .toList(); + } + for (PageSearchResult r : results) { pageService.trackReference(kbId, r.slug()); } @@ -246,16 +355,17 @@ public class WikiTool { public String wiki_semantic_search( @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Natural language query") String query, - @ToolParam(description = "Max results (default 5)", required = false) Integer topK) { + @ToolParam(description = "Max results (default 5)", required = false) Integer topK, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (query == null || query.isBlank()) { return error("query is required"); } - Long kbId = resolveKbId(agentId); - if (kbId == null) { - return error("No wiki knowledge base found for this agent"); - } + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); int k = (topK != null && topK > 0) ? Math.min(topK, 20) : 5; List hits = hybridRetriever.searchChunks(kbId, query, k); @@ -309,21 +419,25 @@ public class WikiTool { """) public String wiki_trace_source( @ToolParam(description = "Agent ID") Long agentId, - @ToolParam(description = "Page slug") String slug) { + @ToolParam(description = "Page slug") String slug, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (slug == null || slug.isBlank()) { return error("slug is required"); } - Long kbId = resolveKbId(agentId); - if (kbId == null) { - return error("No wiki knowledge base found for this agent"); - } + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); WikiPageEntity page = pageService.getBySlug(kbId, slug); if (page == null) { return error("Page not found: " + slug); } + if (!canRead(pageTypeAccess(agentId, kbId), page)) { + return error("Page not found: " + slug); + } return JSONUtil.createObj() .set("pageTitle", page.getTitle()) @@ -339,7 +453,9 @@ public class WikiTool { public String wiki_create_page( @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Page title") String title, - @ToolParam(description = "Page content (Markdown)") String content) { + @ToolParam(description = "Page content (Markdown)") String content, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (title == null || title.isBlank()) { return error("title is required"); @@ -348,9 +464,16 @@ public class WikiTool { return error("content is required"); } - Long kbId = resolveKbId(agentId); - if (kbId == null) { - return error("No wiki knowledge base found for this agent. Create one first."); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); + + // wiki_create_page does not take an explicit pageType, so creation is + // governed by the agent's wildcard ('*') write rule for this KB. + String createErr = checkWrite(agentId, kbId, null, + WikiPageTypePermissionService.WriteOp.CREATE); + if (createErr != null) { + return createErr; } String slug = title.toLowerCase() @@ -392,15 +515,24 @@ public class WikiTool { @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Topic to compile a page about (natural language)") String topic, @ToolParam(description = "Optional explicit slug for the page", required = false) String slug, - @ToolParam(description = "Max evidence chunks (default 8, max 20)", required = false) Integer maxEvidenceChunks) { + @ToolParam(description = "Max evidence chunks (default 8, max 20)", required = false) Integer maxEvidenceChunks, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (topic == null || topic.isBlank()) { return error("topic is required"); } - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (compileService == null) return error("Compile service not available"); + String compileErr = checkWrite(agentId, kbId, null, + WikiPageTypePermissionService.WriteOp.CREATE); + if (compileErr != null) { + return compileErr; + } + try { WikiCompileService.CompileResult res = compileService.compilePage(kbId, topic, slug, maxEvidenceChunks); // RFC-051 follow-up: distinguish "no source material" from a hard error @@ -439,21 +571,27 @@ public class WikiTool { public String wiki_read_many( @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Comma-separated slugs (max 10)") String slugs, - @ToolParam(description = "Max chars returned per page (default 2000, max 8000)", required = false) Integer maxCharsPerPage) { + @ToolParam(description = "Max chars returned per page (default 2000, max 8000)", required = false) Integer maxCharsPerPage, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (slugs == null || slugs.isBlank()) return error("slugs is required"); - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); int cap = (maxCharsPerPage == null || maxCharsPerPage <= 0) ? 2000 : Math.min(8000, maxCharsPerPage); List slugList = Arrays.stream(slugs.split(",")) .map(String::trim).filter(s -> !s.isEmpty()).limit(10).toList(); if (slugList.isEmpty()) return error("No valid slugs supplied"); + WikiPageTypePermissionService.Access access = pageTypeAccess(agentId, kbId); JSONArray arr = new JSONArray(); for (String s : slugList) { WikiPageEntity page = pageService.getBySlug(kbId, s); - if (page == null) { + if (page == null || !canRead(access, page)) { + // Unreadable pageType is reported as not-found, same as a missing + // slug, so the agent cannot probe for hidden pages by slug. arr.add(JSONUtil.createObj().set("slug", s).set("found", false)); continue; } @@ -484,8 +622,10 @@ public class WikiTool { """) public String wiki_archive_page( @ToolParam(description = "Agent ID") Long agentId, - @ToolParam(description = "Page slug to archive") String slug) { - return setArchivedTool(agentId, slug, true, "archived"); + @ToolParam(description = "Page slug to archive") String slug, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { + return setArchivedTool(agentId, slug, true, "archived", kbName, kbId); } @Tool(description = """ @@ -494,14 +634,30 @@ public class WikiTool { """) public String wiki_unarchive_page( @ToolParam(description = "Agent ID") Long agentId, - @ToolParam(description = "Page slug to unarchive") String slug) { - return setArchivedTool(agentId, slug, false, "unarchived"); + @ToolParam(description = "Page slug to unarchive") String slug, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { + return setArchivedTool(agentId, slug, false, "unarchived", kbName, kbId); } - private String setArchivedTool(Long agentId, String slug, boolean archive, String verb) { + private String setArchivedTool(Long agentId, String slug, boolean archive, String verb, String kbName, Long kbId) { if (slug == null || slug.isBlank()) return error("slug is required"); - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); + // Archiving toggles visibility — gate it as an update, and hide pages + // whose type the agent cannot read. + WikiPageEntity target = pageService.getBySlug(kbId, slug); + if (target != null) { + if (!canRead(pageTypeAccess(agentId, kbId), target)) { + return error("Page not found: " + slug); + } + String writeErr = checkWrite(agentId, kbId, target.getPageType(), + WikiPageTypePermissionService.WriteOp.UPDATE); + if (writeErr != null) { + return writeErr; + } + } boolean changed; try { changed = pageService.setArchived(kbId, slug, archive); @@ -521,21 +677,31 @@ public class WikiTool { """) public String wiki_delete_page( @ToolParam(description = "Agent ID") Long agentId, - @ToolParam(description = "Page slug to delete") String slug) { + @ToolParam(description = "Page slug to delete") String slug, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (slug == null || slug.isBlank()) { return error("slug is required"); } - Long kbId = resolveKbId(agentId); - if (kbId == null) { - return error("No wiki knowledge base found for this agent"); - } + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); WikiPageEntity page = pageService.getBySlug(kbId, slug); if (page == null) { return error("Page not found: " + slug); } + // Unreadable page types must not even be discoverable as delete targets. + if (!canRead(pageTypeAccess(agentId, kbId), page)) { + return error("Page not found: " + slug); + } + String writeErr = checkWrite(agentId, kbId, page.getPageType(), + WikiPageTypePermissionService.WriteOp.DELETE); + if (writeErr != null) { + return writeErr; + } if ("manual".equals(page.getLastUpdatedBy())) { return error("Cannot delete manually curated page: " + page.getTitle() + ". Please manage via admin UI."); @@ -568,17 +734,24 @@ public class WikiTool { public String wiki_related_pages( @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Page slug") String slug, - @ToolParam(description = "Max results (default 5, max 10)", required = false) Integer topK) { + @ToolParam(description = "Max results (default 5, max 10)", required = false) Integer topK, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (relationService == null) return error("Relation service not available"); int k = (topK != null && topK > 0) ? Math.min(topK, 10) : 5; List results = relationService.relatedPages(kbId, slug, k); + WikiPageTypePermissionService.Access access = pageTypeAccess(agentId, kbId); JSONArray arr = new JSONArray(); for (RelatedPageResult r : results) { + if (access != null && !canRead(access, pageService.getBySlug(kbId, r.slug()))) { + continue; + } arr.add(JSONUtil.createObj() .set("slug", r.slug()) .set("title", r.title()) @@ -588,7 +761,7 @@ public class WikiTool { return JSONUtil.createObj() .set("slug", slug) - .set("relatedCount", results.size()) + .set("relatedCount", arr.size()) .set("pages", arr) .toString(); } @@ -599,12 +772,22 @@ public class WikiTool { public String wiki_explain_relation( @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "First page slug") String slugA, - @ToolParam(description = "Second page slug") String slugB) { + @ToolParam(description = "Second page slug") String slugB, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (relationService == null) return error("Relation service not available"); + WikiPageTypePermissionService.Access relAccess = pageTypeAccess(agentId, kbId); + if (relAccess != null + && (!canRead(relAccess, pageService.getBySlug(kbId, slugA)) + || !canRead(relAccess, pageService.getBySlug(kbId, slugB)))) { + return slugA + " and " + slugB + " have no detected relation."; + } + RelationExplanation ex = relationService.explain(kbId, slugA, slugB); if (ex.breakdown().isEmpty()) return slugA + " and " + slugB + " have no detected relation."; @@ -623,14 +806,25 @@ public class WikiTool { """) public String wiki_enrich_page( @ToolParam(description = "Agent ID") Long agentId, - @ToolParam(description = "Page slug") String slug) { + @ToolParam(description = "Page slug") String slug, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (jobService == null || eventPublisher == null) return error("Job service not available"); WikiPageEntity page = pageService.getBySlug(kbId, slug); if (page == null) return error("Page not found: " + slug); + if (!canRead(pageTypeAccess(agentId, kbId), page)) { + return error("Page not found: " + slug); + } + String enrichErr = checkWrite(agentId, kbId, page.getPageType(), + WikiPageTypePermissionService.WriteOp.UPDATE); + if (enrichErr != null) { + return enrichErr; + } Long rawId = 0L; try { @@ -645,6 +839,90 @@ public class WikiTool { return "Wikilink enrichment queued for: " + slug; } + // ==================== Page update / stale review ==================== + + @Tool(description = """ + Update an existing wiki page's Markdown body IN PLACE, by slug. This + preserves the page's identity, slug, backlinks and version history. + Use this to revise or extend a page — do NOT delete and recreate it + (that drops links and can leave duplicate pages behind). The summary + is re-derived from the new content unless you pass one explicitly. + """) + public String wiki_update_page( + @ToolParam(description = "Agent ID") Long agentId, + @ToolParam(description = "Slug of the page to update (from wiki_list_pages / wiki_read_page)") String slug, + @ToolParam(description = "New full Markdown content for the page body") String content, + @ToolParam(description = "New one-line summary (optional; omit to auto-derive from content)", required = false) String summary, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { + + if (slug == null || slug.isBlank()) { + return error("slug is required"); + } + if (content == null || content.isBlank()) { + return error("content is required"); + } + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); + + WikiPageEntity page = pageService.getBySlug(kbId, slug); + if (page == null) { + return error("Page not found: '" + slug + "'. Use wiki_list_pages to find the right slug."); + } + String writeErr = checkWrite(agentId, kbId, page.getPageType(), + WikiPageTypePermissionService.WriteOp.UPDATE); + if (writeErr != null) return writeErr; + + // summary == null → service re-derives it from the new content. + WikiPageEntity updated = pageService.updatePageManually( + kbId, slug, content, (summary == null || summary.isBlank()) ? null : summary); + return JSONUtil.createObj() + .set("ok", true) + .set("slug", updated.getSlug()) + .set("title", updated.getTitle()) + .set("version", updated.getVersion()) + .set("message", "Page updated in place (slug and backlinks preserved).") + .toString(); + } + + @Tool(description = """ + List wiki pages currently marked STALE (needing review) in a knowledge + base. A page goes stale when a fact page it depends on was updated, so + its synthesis/analysis content may now be out of date. Returns each + stale page's title, slug, pageType, knowledge layer and the reason it + was flagged. Use this to find what to re-check or re-summarize before + relying on experience/analysis pages. + """) + public String wiki_stale_pages( + @ToolParam(description = "Agent ID") Long agentId, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { + + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); + + WikiPageTypePermissionService.Access access = pageTypeAccess(agentId, kbId); + JSONArray arr = new JSONArray(); + for (WikiPageEntity p : pageService.listByKbId(kbId)) { + if (p.getStale() == null || p.getStale() == 0) continue; + if (p.getArchived() != null && p.getArchived() == 1) continue; + if (!canRead(access, p)) continue; // honour pageType read permissions + arr.add(JSONUtil.createObj() + .set("slug", p.getSlug()) + .set("title", p.getTitle()) + .set("pageType", p.getPageType()) + .set("knowledgeLayer", p.getKnowledgeLayer()) + .set("staleReason", p.getStaleReasonJson() == null ? "" : p.getStaleReasonJson())); + } + return JSONUtil.createObj() + .set("kbId", String.valueOf(kbId)) + .set("staleCount", arr.size()) + .set("pages", arr) + .toString(); + } + // ==================== Transformations ==================== @Tool(description = """ @@ -653,9 +931,12 @@ public class WikiTool { human title, and a description of what the prompt produces. """) public String wiki_list_transformations( - @ToolParam(description = "Agent ID") Long agentId) { - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + @ToolParam(description = "Agent ID") Long agentId, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (transformationService == null) return error("Transformations not available"); WikiKnowledgeBaseEntity kb = kbService.getById(kbId); @@ -682,15 +963,25 @@ public class WikiTool { public String wiki_apply_transformation( @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Transformation name (from wiki_list_transformations)") String name, - @ToolParam(description = "Raw material ID to run the transformation against") Long rawId) { + @ToolParam(description = "Raw material ID to run the transformation against") Long rawId, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (name == null || name.isBlank()) return error("name is required"); if (rawId == null) return error("rawId is required"); - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (transformationService == null || transformationExecutor == null) { return error("Transformations not available"); } + // A transformation persists a synthesis run/page — gate as a create. + String txErr = checkWrite(agentId, kbId, null, + WikiPageTypePermissionService.WriteOp.CREATE); + if (txErr != null) { + return txErr; + } + WikiKnowledgeBaseEntity kb = kbService.getById(kbId); Long wsId = (kb == null || kb.getWorkspaceId() == null) ? 1L : kb.getWorkspaceId(); @@ -727,17 +1018,29 @@ public class WikiTool { public String wiki_apply_transformation_to_page( @ToolParam(description = "Agent ID") Long agentId, @ToolParam(description = "Transformation name (from wiki_list_transformations)") String name, - @ToolParam(description = "Source wiki page slug to run the transformation against") String slug) { + @ToolParam(description = "Source wiki page slug to run the transformation against") String slug, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (name == null || name.isBlank()) return error("name is required"); if (slug == null || slug.isBlank()) return error("slug is required"); - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (transformationService == null || transformationExecutor == null) { return error("Transformations not available"); } WikiPageEntity page = pageService.getBySlug(kbId, slug); if (page == null) return error("Page not found: " + slug); + if (!canRead(pageTypeAccess(agentId, kbId), page)) { + return error("Page not found: " + slug); + } + // Reads the source page and persists a derived run — gate as a create. + String txErr = checkWrite(agentId, kbId, null, + WikiPageTypePermissionService.WriteOp.CREATE); + if (txErr != null) { + return txErr; + } WikiKnowledgeBaseEntity kb = kbService.getById(kbId); Long wsId = (kb == null || kb.getWorkspaceId() == null) ? 1L : kb.getWorkspaceId(); @@ -776,14 +1079,24 @@ public class WikiTool { """) public String wiki_aggregate_transformation( @ToolParam(description = "Agent ID") Long agentId, - @ToolParam(description = "Transformation name (from wiki_list_transformations)") String name) { + @ToolParam(description = "Transformation name (from wiki_list_transformations)") String name, + @ToolParam(description = "Target knowledge base name (from wiki_list_kbs). Omit to use the agent's primary KB; switch to `kbId` when two KBs share the name.", required = false) String kbName, + @ToolParam(description = "Numeric KB id from wiki_list_kbs. Use when `kbName` returns an ambiguous-name error.", required = false) Long kbId) { if (name == null || name.isBlank()) return error("name is required"); - Long kbId = resolveKbId(agentId); - if (kbId == null) return error("No wiki knowledge base found for this agent"); + KbResolution kbRes = resolveKb(agentId, kbName, kbId); + if (kbRes.hasError()) return kbRes.errorJson(); + kbId = kbRes.kbId(); if (transformationService == null || transformationAggregator == null) { return error("Transformations not available"); } + // Aggregation upserts a synthesis page — gate as a create. + String aggErr = checkWrite(agentId, kbId, null, + WikiPageTypePermissionService.WriteOp.CREATE); + if (aggErr != null) { + return aggErr; + } + WikiKnowledgeBaseEntity kb = kbService.getById(kbId); Long wsId = (kb == null || kb.getWorkspaceId() == null) ? 1L : kb.getWorkspaceId(); @@ -818,8 +1131,246 @@ public class WikiTool { // ==================== Helpers ==================== private Long resolveKbId(Long agentId) { - WikiKnowledgeBaseEntity kb = kbService.resolvePrimaryKb(agentId); - return kb == null ? null : kb.getId(); + return resolveKbId(agentId, null, null); + } + + /** + * Outcome of resolving a KB for a tool call. Exactly one of + * {@code kbId} / {@code errorJson} is non-null: + *

      + *
    • {@code kbId} present → caller proceeds with that KB.
      • + *
    • {@code errorJson} present → caller returns it as-is so the LLM + * sees an unambiguous error pointing at the next action + * (call {@code wiki_list_kbs} / pick a different name / pass + * {@code kbId}).
      • + *
    + */ + private record KbResolution(Long kbId, String errorJson) { + static KbResolution ok(Long id) { return new KbResolution(id, null); } + static KbResolution err(String json) { return new KbResolution(null, json); } + boolean hasError() { return errorJson != null; } + } + + /** + * Resolve the agent's pageType read/write permission view for a KB once, + * so a tool call can filter a whole result set without re-querying. Never + * null — the service is a mandatory dependency, so there is no fail-open + * path; an agent with no rows still resolves to the KB's default policy. + */ + private WikiPageTypePermissionService.Access pageTypeAccess(Long agentId, Long kbId) { + return pageTypePermissionService.resolve(agentId, kbId); + } + + /** Whether the resolved access permits reading {@code page}. Null-safe. */ + private boolean canRead(WikiPageTypePermissionService.Access access, WikiPageEntity page) { + return access == null || page == null || access.canRead(page.getPageType()); + } + + /** Whether the resolved access permits reading a page of {@code pageType}. Null-safe. */ + private boolean canRead(WikiPageTypePermissionService.Access access, String pageType) { + return access == null || access.canRead(pageType); + } + + /** + * Whether a page's knowledge layer matches a retrieval filter. A null/blank + * or {@code all} filter matches everything; an unlayered page counts as + * {@code fact} (the RFC default), so {@code layer=fact} includes legacy + * pages while {@code layer=experience} returns only experience pages. + */ + static boolean matchesLayer(String pageLayer, String filter) { + if (filter == null || filter.isBlank() || "all".equalsIgnoreCase(filter.trim())) { + return true; + } + String effective = (pageLayer == null || pageLayer.isBlank()) ? "fact" : pageLayer.trim().toLowerCase(); + return effective.equals(filter.trim().toLowerCase()); + } + + /** + * Gate a write/mutate operation by pageType permission. Returns an error + * JSON string to short-circuit the tool when the write is not permitted, or + * {@code null} when it may proceed. Null-safe: when the permission service + * is absent, every write is allowed (pre-permission behaviour). + * + *

    {@code APPROVAL_REQUIRED} records a pending approval in the operator + * inbox (when {@link #approvalWorkflowService} is wired) so the request is + * visible and auditable, then fails closed for this turn — the write is not + * performed inline. The approve-then-replay path is driven from the inbox, + * not from inside the tool body, which cannot pause and resume itself. + */ + private String checkWrite(Long agentId, Long kbId, String pageType, + WikiPageTypePermissionService.WriteOp op) { + WikiPageTypePermissionService.WriteDecision decision = + pageTypePermissionService.resolveWrite(agentId, kbId, pageType, op); + String typeLabel = (pageType == null || pageType.isBlank()) ? "(default)" : pageType; + return switch (decision) { + case ALLOW -> null; + case DENY -> { + log.info("[WikiTool] write denied by pageType permission: agent={} kb={} type={} op={}", + agentId, kbId, pageType, op); + yield error("Not permitted: this agent may not " + op.name().toLowerCase() + + " '" + typeLabel + "' pages in this knowledge base."); + } + case APPROVAL_REQUIRED -> { + boolean recorded = recordPendingApproval(agentId, kbId, pageType, op); + log.info("[WikiTool] write requires approval: agent={} kb={} type={} op={} recorded={}", + agentId, kbId, pageType, op, recorded); + yield error("Approval required: " + op.name().toLowerCase() + " of '" + typeLabel + + "' pages in this knowledge base needs administrator approval. " + + (recorded + ? "A pending approval was created for an administrator to review. " + : "") + + "The operation was NOT performed."); + } + }; + } + + /** + * Record a pending approval for an {@code APPROVAL_REQUIRED} wiki write, + * keyed to the current conversation via {@link ChatOriginHolder}. Best-effort: + * returns false (and never throws) when the workflow bean is absent or there + * is no conversation context, so the caller can still fail closed cleanly. + */ + private boolean recordPendingApproval(Long agentId, Long kbId, String pageType, + WikiPageTypePermissionService.WriteOp op) { + if (approvalWorkflowService == null) { + return false; + } + ChatOrigin origin = ChatOriginHolder.get(); + String conversationId = origin == null ? null : origin.conversationId(); + if (conversationId == null || conversationId.isBlank()) { + return false; // no conversation to attach the approval to + } + try { + String typeLabel = (pageType == null || pageType.isBlank()) ? "(default)" : pageType; + String args = objectMapper.createObjectNode() + .put("kbId", String.valueOf(kbId)) + .put("pageType", typeLabel) + .put("op", op.name()) + .toString(); + String reason = "Wiki " + op.name().toLowerCase() + " of '" + typeLabel + + "' pages requires administrator approval."; + String userId = origin.requesterId(); + approvalWorkflowService.createPending( + conversationId, + (userId == null || userId.isBlank()) ? null : userId, + "wiki_" + op.name().toLowerCase() + "_page", + args, + reason, + /* toolCallPayload */ null, + /* siblingToolCalls */ null, + agentId == null ? null : String.valueOf(agentId)); + return true; + } catch (Exception e) { + log.warn("[WikiTool] failed to record pending approval: {}", e.getMessage()); + return false; + } + } + + /** + * Single helper every wiki tool uses. Caller passes the agent id and at + * most one of {@code kbId} / {@code kbName}; the helper decides which + * KB the operation runs against and emits a uniform error when no + * unambiguous target can be picked. + * + *

    Resolution rules (in order): + *

      + *
    1. {@code kbId} non-null → resolve only via + * {@link WikiKnowledgeBaseService#findVisibleById}. Out-of-visibility + * ids fail closed — no silent fallback to the primary or to a + * same-name shared KB.
      2. + *
    2. {@code kbName} non-blank → look up every visible KB with that + * name. Single match → use it. Zero match → fail closed pointing + * at {@code wiki_list_kbs}. Multiple matches → fail closed with + * the list of candidate {@code kbId}s, telling the LLM to retry + * with {@code kbId}.
      3. + *
    3. Both blank → fall back to + * {@link WikiKnowledgeBaseService#resolvePrimaryKb} so single-KB + * agents keep their old zero-config behaviour.
      4. + *
    + */ + private KbResolution resolveKb(Long agentId, String kbName, Long kbId) { + // Treat kbId<=0 as "not supplied". Spring AI's @Tool JSON-schema + // generator doesn't carry the "optional, may be absent" semantic + // through to the LLM in the way Java would expect a nullable Long, + // so the model frequently fills unused numeric optionals with 0 + // ("openai-chatgpt" was observed doing this on every wiki call). + // Real Snowflake ids are always 19-digit positive longs, so + // {0, negative} can be safely treated as the empty case. + if (kbId != null && kbId > 0L) { + WikiKnowledgeBaseEntity byId = kbService.findVisibleById(agentId, kbId); + if (byId == null) { + return KbResolution.err(error( + "Knowledge base id=" + kbId + " not visible to this agent. " + + "Use wiki_list_kbs to see available KBs.")); + } + return KbResolution.ok(byId.getId()); + } + if (kbName != null && !kbName.isBlank()) { + List matches = kbService.findAllByName(agentId, kbName); + if (matches.isEmpty()) { + return KbResolution.err(error( + "Knowledge base '" + kbName + "' not visible to this agent. " + + "Use wiki_list_kbs to see available KBs.")); + } + if (matches.size() > 1) { + // Duplicate names exist (no DB unique constraint). The LLM + // cannot disambiguate from kbName alone — surface every + // candidate's id (as String per the Snowflake-precision + // contract) and demand a kbId retry. + JSONArray candidates = new JSONArray(); + for (WikiKnowledgeBaseEntity kb : matches) { + candidates.add(JSONUtil.createObj() + .set("kbId", String.valueOf(kb.getId())) + .set("name", kb.getName()) + .set("description", kb.getDescription()) + .set("boundToAgent", kb.getAgentId() != null)); + } + JSONObject obj = JSONUtil.createObj() + .set("error", "Ambiguous kbName '" + kbName + "' — " + + matches.size() + " visible KBs share this name. " + + "Retry with `kbId` from the candidates list below.") + .set("candidates", candidates); + return KbResolution.err(obj.toString()); + } + return KbResolution.ok(matches.get(0).getId()); + } + WikiKnowledgeBaseEntity primary = kbService.resolvePrimaryKb(agentId); + if (primary == null) { + return KbResolution.err(error("No wiki knowledge base found for this agent")); + } + return KbResolution.ok(primary.getId()); + } + + /** + * Legacy 2-arg routing kept for the tool methods that haven't been + * widened to accept {@code kbId} yet. Always returns null when the + * resolution would have surfaced an error — callers turn that into a + * {@link #noKbError(String)} message. + */ + private Long resolveKbId(Long agentId, String kbName) { + return resolveKbId(agentId, kbName, null); + } + + private Long resolveKbId(Long agentId, String kbName, Long kbId) { + KbResolution res = resolveKb(agentId, kbName, kbId); + return res.hasError() ? null : res.kbId(); + } + + /** + * Standardised "couldn't resolve KB" error. When the caller passed a + * non-blank {@code kbName} that didn't match, the message points them at + * {@code wiki_list_kbs} so the LLM has a clear next step. + * + *

    NOTE: ambiguous-kbName errors are emitted directly by + * {@link #resolveKb} so the LLM also gets the candidate list, not just + * a flat string. This helper handles the simpler "not visible" case. + */ + private String noKbError(String kbName) { + if (kbName != null && !kbName.isBlank()) { + return error("Knowledge base '" + kbName + + "' not visible to this agent. Use wiki_list_kbs to see available KBs."); + } + return error("No wiki knowledge base found for this agent"); } private JSONArray resolveSourceFiles(String sourceRawIdsJson) { diff --git a/mateclaw-server/src/main/java/vip/mate/workflow/service/WorkflowService.java b/mateclaw-server/src/main/java/vip/mate/workflow/service/WorkflowService.java index b0a2e9cd..2e8e1e20 100644 --- a/mateclaw-server/src/main/java/vip/mate/workflow/service/WorkflowService.java +++ b/mateclaw-server/src/main/java/vip/mate/workflow/service/WorkflowService.java @@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import lombok.RequiredArgsConstructor; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; +import vip.mate.exception.MateClawException; import vip.mate.workflow.compiler.PublishContext; import vip.mate.workflow.compiler.WorkflowAclPort; import vip.mate.workflow.compiler.WorkflowCompiler; @@ -112,6 +113,10 @@ public class WorkflowService { @Transactional public WorkflowEntity create(WorkflowEntity workflow) { if (workflow.getEnabled() == null) workflow.setEnabled(true); + // Pre-check name uniqueness so the duplicate path surfaces as a friendly + // 409 instead of an opaque 500 from the uk_workflow_workspace_name + // unique index hitting the catch-all handler. + requireUniqueName(workflow.getWorkspaceId(), workflow.getName(), null); workflowMapper.insert(workflow); return workflow; } @@ -128,7 +133,10 @@ public class WorkflowService { public WorkflowEntity updateMetadata(long id, long workspaceId, String name, String description, Boolean enabled) { WorkflowEntity existing = getOrThrow(id, workspaceId); - if (name != null) existing.setName(name); + if (name != null && !name.equals(existing.getName())) { + requireUniqueName(workspaceId, name, id); + existing.setName(name); + } if (description != null) existing.setDescription(description); if (enabled != null) existing.setEnabled(enabled); // draftJson / latest_revision_id / workspace_id are intentionally @@ -216,6 +224,35 @@ public class WorkflowService { return new PublishOutcome(workflow, revision); } + /** + * Reject a create / rename whose name already exists in the workspace. The + * underlying table carries a unique index on (workspace_id, name, deleted), + * so without this pre-check the duplicate insert would bubble up as a + * generic 500 with a database-level "duplicate entry" message. Pass a + * non-null {@code excludeId} on rename so the row doesn't see itself as a + * conflict. + */ + private void requireUniqueName(Long workspaceId, String name, Long excludeId) { + if (name == null || name.isBlank()) { + throw new MateClawException("err.workflow.name_required", 400, + "工作流名称不能为空"); + } + if (workspaceId == null) { + return; + } + LambdaQueryWrapper q = new LambdaQueryWrapper() + .eq(WorkflowEntity::getWorkspaceId, workspaceId) + .eq(WorkflowEntity::getName, name); + if (excludeId != null) { + q.ne(WorkflowEntity::getId, excludeId); + } + Long count = workflowMapper.selectCount(q); + if (count != null && count > 0) { + throw new MateClawException("err.workflow.duplicate_name", 409, + "工作区内已存在同名工作流: " + name); + } + } + private int nextRevisionNumber(long workflowId) { WorkflowRevisionEntity max = revisionMapper.selectOne(new LambdaQueryWrapper() .eq(WorkflowRevisionEntity::getWorkflowId, workflowId) diff --git a/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java b/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java index c1a4167e..1c71606e 100644 --- a/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java +++ b/mateclaw-server/src/main/java/vip/mate/workspace/conversation/ConversationService.java @@ -366,7 +366,24 @@ public class ConversationService { conv.setUsername(SYSTEM_USER); changed = true; } - if (conv.getAgentId() == null && agentId != null) { + // Shared conversations (IM channel sessions, cron job-specific rows) + // take their agent from the caller's current authoritative binding — + // the channel's bound agent for IM, the job's bound agent for cron. + // Sync so the admin sidebar / dashboard / context resolution all see + // the same agent the runtime is dispatching to; otherwise an admin + // who rebinds a channel from A to B leaves every existing + // conversation pointing at the old A. + // + // Exception: Web-origin cron uses {@code tasks_} as a + // single aggregate conversation for ALL of the workspace's web cron + // runs (see CronConversationResolver). Many jobs with different + // bound agents land in that same row; overwriting agentId per run + // would make the header / avatar / model selector flicker to + // whichever cron fired last. The aggregate has no single "owner + // agent" — leave its agentId alone (the original first-runner value + // is fine; UI treats this conversation specially anyway). + boolean isCronAggregate = conversationId != null && conversationId.startsWith("tasks_"); + if (!isCronAggregate && agentId != null && !agentId.equals(conv.getAgentId())) { conv.setAgentId(agentId); changed = true; } diff --git a/mateclaw-server/src/main/java/vip/mate/workspace/document/WorkspaceFileService.java b/mateclaw-server/src/main/java/vip/mate/workspace/document/WorkspaceFileService.java index 58b6c4fa..b9fa712f 100644 --- a/mateclaw-server/src/main/java/vip/mate/workspace/document/WorkspaceFileService.java +++ b/mateclaw-server/src/main/java/vip/mate/workspace/document/WorkspaceFileService.java @@ -3,8 +3,11 @@ package vip.mate.workspace.document; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; +import org.springframework.context.ApplicationEventPublisher; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; +import vip.mate.memory.identity.MemoryScope; +import vip.mate.workspace.document.event.WorkspaceFileChangedEvent; import vip.mate.workspace.document.model.WorkspaceFileEntity; import vip.mate.workspace.document.repository.WorkspaceFileMapper; @@ -31,6 +34,7 @@ import java.util.stream.Collectors; public class WorkspaceFileService { private final WorkspaceFileMapper fileMapper; + private final ApplicationEventPublisher eventPublisher; /** * 列出 Agent 的所有工作区文件（按排序 + 文件名排列） @@ -47,19 +51,39 @@ public class WorkspaceFileService { } /** - * 读取单个文件（含内容） + * Read a single shared (config / persona) file by name. + *

    + * Restricted to TEAM / GLOBAL scope so it never matches — or accidentally + * mutates — an owner's PERSONAL row that happens to share the same filename + * (e.g. MEMORY.md). Owner-scoped reads must use + * {@link #getMemoryFile(Long, String, String)}. Uses the non-throwing + * {@code selectOne(wrapper, false)} so duplicate rows can never surface a + * {@code TooManyResultsException}. */ public WorkspaceFileEntity getFile(Long agentId, String filename) { return fileMapper.selectOne( new LambdaQueryWrapper() .eq(WorkspaceFileEntity::getAgentId, agentId) - .eq(WorkspaceFileEntity::getFilename, filename)); + .eq(WorkspaceFileEntity::getFilename, filename) + .in(WorkspaceFileEntity::getScope, MemoryScope.TEAM, MemoryScope.GLOBAL) + .orderByAsc(WorkspaceFileEntity::getId), + false); } /** - * 创建或更新文件 + * 创建或更新文件（共享 / 配置文件路径） + *

    + * Used by the agent-config surface (AGENTS.md, SOUL.md, PROFILE.md …). + * Rows written here are TEAM-scoped and shared by everyone using the agent. + * Conversation-derived memory must go through + * {@link #saveMemoryFile(Long, String, String, String)} instead so it is + * attributed to a single owner. */ - @Transactional + // NOTE: intentionally NOT @Transactional. These are single-row upserts and + // the dup-key fallback below reselects+updates after a failed insert — under + // a transaction the failed insert would mark it rollback-only and poison the + // recovery update. WorkspaceFileChangedEvent uses a plain @EventListener + // (not @TransactionalEventListener), so event timing is unaffected. public WorkspaceFileEntity saveFile(Long agentId, String filename, String content) { WorkspaceFileEntity existing = getFile(agentId, filename); long size = content != null ? content.getBytes(StandardCharsets.UTF_8).length : 0; @@ -68,29 +92,203 @@ public class WorkspaceFileService { existing.setContent(content); existing.setFileSize(size); fileMapper.updateById(existing); + eventPublisher.publishEvent(new WorkspaceFileChangedEvent(agentId, filename)); return existing; - } else { - WorkspaceFileEntity entity = new WorkspaceFileEntity(); - entity.setAgentId(agentId); - entity.setFilename(filename); - entity.setContent(content); - entity.setFileSize(size); - entity.setEnabled(false); - entity.setSortOrder(0); - fileMapper.insert(entity); - return entity; } + WorkspaceFileEntity entity = new WorkspaceFileEntity(); + entity.setAgentId(agentId); + entity.setFilename(filename); + entity.setContent(content); + entity.setFileSize(size); + entity.setEnabled(false); + entity.setSortOrder(0); + entity.setScope(MemoryScope.TEAM); + // Shared rows use the empty-string sentinel (not NULL) so the + // (agent_id, filename, owner_key) unique index treats one shared + // row per filename as a single slot — NULLs are considered distinct + // by both H2 and MySQL unique indexes and would not be deduped. + entity.setOwnerKey(SHARED_OWNER_KEY); + WorkspaceFileEntity saved = insertOrUpdateOnConflict( + entity, () -> getFile(agentId, filename), content, size); + eventPublisher.publishEvent(new WorkspaceFileChangedEvent(agentId, filename)); + return saved; } /** - * 删除文件 + * Insert {@code entity}; if a concurrent writer already created the row + * (unique-index violation), reselect via {@code reselect} and update its + * content instead of throwing. Makes the check-then-insert in + * saveFile / saveMemoryFile safe under concurrent / multi-node first writes. + */ + private WorkspaceFileEntity insertOrUpdateOnConflict(WorkspaceFileEntity entity, + java.util.function.Supplier reselect, + String content, long size) { + try { + fileMapper.insert(entity); + return entity; + } catch (org.springframework.dao.DuplicateKeyException dup) { + // Only recover the specific concurrent first-write race on the + // owner-scope unique index. Any other duplicate (e.g. a primary-key + // collision, or a future unique constraint) must surface — silently + // reselecting+updating would mask a real bug. The driver message + // names the violated index on both MySQL and H2. + String msg = dup.getMessage(); + if (msg == null || !msg.toLowerCase().contains(UK_OWNER_INDEX)) { + throw dup; + } + WorkspaceFileEntity raced = reselect.get(); + if (raced != null) { + raced.setContent(content); + raced.setFileSize(size); + fileMapper.updateById(raced); + return raced; + } + throw dup; + } + } + + /** Name of the (agent_id, filename, owner_key) unique index — see V137 migration. */ + private static final String UK_OWNER_INDEX = "uk_workspace_file_owner"; + + /** Sentinel owner key for shared (TEAM / GLOBAL) rows — keeps the unique index effective. */ + static final String SHARED_OWNER_KEY = ""; + + /** A real, isolatable owner — not null/blank and not the system bucket. */ + private boolean isPersonalOwner(String ownerKey) { + return ownerKey != null && !ownerKey.isBlank() + && !vip.mate.memory.identity.MemoryOwnerResolver.SYSTEM_OWNER.equals(ownerKey); + } + + /** + * List files visible to {@code ownerKey}: shared (TEAM / GLOBAL) rows plus + * this owner's PERSONAL rows. A null/blank/system ownerKey lists shared + * only. Content is stripped (metadata listing). + */ + public List listVisibleFiles(Long agentId, String ownerKey) { + LambdaQueryWrapper wrapper = new LambdaQueryWrapper() + .eq(WorkspaceFileEntity::getAgentId, agentId); + applyScopeVisibility(wrapper, isPersonalOwner(ownerKey) ? ownerKey : null); + wrapper.orderByAsc(WorkspaceFileEntity::getSortOrder) + .orderByAsc(WorkspaceFileEntity::getFilename); + List files = fileMapper.selectList(wrapper); + files.forEach(f -> f.setContent(null)); + return files; + } + + /** + * Read a file visible to {@code ownerKey}: the owner's PERSONAL row when it + * exists, otherwise the shared row. Null when neither exists. + */ + public WorkspaceFileEntity getVisibleFile(Long agentId, String filename, String ownerKey) { + if (isPersonalOwner(ownerKey)) { + WorkspaceFileEntity personal = getMemoryFile(agentId, filename, ownerKey); + if (personal != null) { + return personal; + } + } + return getFile(agentId, filename); + } + + /** + * Save a file to the owner's PERSONAL bucket when {@code ownerKey} denotes a + * real owner, otherwise to the shared (TEAM) file. The single entry point + * tools should use so per-owner isolation and the shared fallback stay + * consistent. + */ + public WorkspaceFileEntity saveVisibleFile(Long agentId, String filename, String content, String ownerKey) { + return isPersonalOwner(ownerKey) + ? saveMemoryFile(agentId, filename, content, ownerKey) + : saveFile(agentId, filename, content); + } + + /** + * Read a memory file scoped to a single owner. + *

    + * Daily ledgers and consolidated memory share a filename across owners + * (e.g. {@code memory/2026-06-02.md}), so the lookup key is + * {@code (agentId, filename, ownerKey)} — otherwise two end-users sharing + * one agent would clobber each other's row. + */ + public WorkspaceFileEntity getMemoryFile(Long agentId, String filename, String ownerKey) { + return fileMapper.selectOne( + new LambdaQueryWrapper() + .eq(WorkspaceFileEntity::getAgentId, agentId) + .eq(WorkspaceFileEntity::getFilename, filename) + .eq(WorkspaceFileEntity::getScope, MemoryScope.PERSONAL) + .eq(WorkspaceFileEntity::getOwnerKey, ownerKey) + .orderByAsc(WorkspaceFileEntity::getId), + false); + } + + /** + * Create or update a PERSONAL, owner-scoped memory file. + *

    + * Rows written here carry {@code scope=PERSONAL} + {@code ownerKey} and are + * enabled so the per-turn memory injection ({@code prefetch}) picks them up + * for that owner only. + */ + // NOTE: intentionally NOT @Transactional — see saveFile for the dup-key + // recovery rationale. + public WorkspaceFileEntity saveMemoryFile(Long agentId, String filename, String content, String ownerKey) { + WorkspaceFileEntity existing = getMemoryFile(agentId, filename, ownerKey); + long size = content != null ? content.getBytes(StandardCharsets.UTF_8).length : 0; + + if (existing != null) { + existing.setContent(content); + existing.setFileSize(size); + fileMapper.updateById(existing); + eventPublisher.publishEvent(new WorkspaceFileChangedEvent(agentId, filename)); + return existing; + } + WorkspaceFileEntity entity = new WorkspaceFileEntity(); + entity.setAgentId(agentId); + entity.setFilename(filename); + entity.setContent(content); + entity.setFileSize(size); + entity.setEnabled(true); + entity.setSortOrder(0); + entity.setOwnerKey(ownerKey); + entity.setScope(MemoryScope.PERSONAL); + WorkspaceFileEntity saved = insertOrUpdateOnConflict( + entity, () -> getMemoryFile(agentId, filename, ownerKey), content, size); + eventPublisher.publishEvent(new WorkspaceFileChangedEvent(agentId, filename)); + return saved; + } + + /** + * Delete a shared (config / persona) file by name. + *

    + * Scoped to TEAM / GLOBAL so the config-editor surface can never wipe every + * owner's same-named PERSONAL row (e.g. all users' {@code MEMORY.md}). + * Owner-scoped deletion goes through + * {@link #deleteMemoryFile(Long, String, String)}. */ @Transactional public void deleteFile(Long agentId, String filename) { fileMapper.delete( new LambdaQueryWrapper() .eq(WorkspaceFileEntity::getAgentId, agentId) - .eq(WorkspaceFileEntity::getFilename, filename)); + .eq(WorkspaceFileEntity::getFilename, filename) + .in(WorkspaceFileEntity::getScope, MemoryScope.TEAM, MemoryScope.GLOBAL)); + eventPublisher.publishEvent(new WorkspaceFileChangedEvent(agentId, filename)); + } + + /** + * Delete a single owner's PERSONAL file by name. Only ever removes the row + * belonging to {@code ownerKey}, never another owner's or the shared row. + */ + @Transactional + public void deleteMemoryFile(Long agentId, String filename, String ownerKey) { + if (!isPersonalOwner(ownerKey)) { + return; + } + fileMapper.delete( + new LambdaQueryWrapper() + .eq(WorkspaceFileEntity::getAgentId, agentId) + .eq(WorkspaceFileEntity::getFilename, filename) + .eq(WorkspaceFileEntity::getScope, MemoryScope.PERSONAL) + .eq(WorkspaceFileEntity::getOwnerKey, ownerKey)); + eventPublisher.publishEvent(new WorkspaceFileChangedEvent(agentId, filename)); } /** @@ -101,6 +299,10 @@ public class WorkspaceFileService { new LambdaQueryWrapper() .eq(WorkspaceFileEntity::getAgentId, agentId) .eq(WorkspaceFileEntity::getEnabled, true) + // System-prompt file management operates on shared config + // files only; PERSONAL memory rows (enabled by default) + // must never appear in or be toggled by this surface. + .in(WorkspaceFileEntity::getScope, MemoryScope.TEAM, MemoryScope.GLOBAL) .orderByAsc(WorkspaceFileEntity::getSortOrder)) .stream() .map(WorkspaceFileEntity::getFilename) @@ -115,9 +317,14 @@ public class WorkspaceFileService { */ @Transactional public void setPromptFiles(Long agentId, List filenames) { + // Only shared config files participate in system-prompt enable/disable. + // PERSONAL memory rows are enabled per-owner by saveMemoryFile and must + // not be batch-toggled by filename here (that would flip every owner's + // row sharing that filename). List allFiles = fileMapper.selectList( new LambdaQueryWrapper() - .eq(WorkspaceFileEntity::getAgentId, agentId)); + .eq(WorkspaceFileEntity::getAgentId, agentId) + .in(WorkspaceFileEntity::getScope, MemoryScope.TEAM, MemoryScope.GLOBAL)); for (WorkspaceFileEntity file : allFiles) { int index = filenames.indexOf(file.getFilename()); @@ -202,6 +409,20 @@ public class WorkspaceFileService { */ public List searchSnippets(Long agentId, String query, Set filenamePrefixes, int limit) { + return searchSnippets(agentId, query, filenamePrefixes, limit, null); + } + + /** + * Owner-scoped overload of {@link #searchSnippets(Long, String, Set, int)}. + *

    + * Restricts candidates to memory the given {@code ownerKey} may see: + * shared rows (TEAM / GLOBAL) plus this owner's own PERSONAL rows. A null + * {@code ownerKey} means "shared only" — used by legacy call sites that + * have no requester identity in scope. + */ + public List searchSnippets(Long agentId, String query, + Set filenamePrefixes, int limit, + String ownerKey) { if (agentId == null || limit <= 0) { return List.of(); } @@ -215,6 +436,7 @@ public class WorkspaceFileService { LambdaQueryWrapper wrapper = new LambdaQueryWrapper<>(); wrapper.eq(WorkspaceFileEntity::getAgentId, agentId); + applyScopeVisibility(wrapper, ownerKey); if (filenamePrefixes != null && !filenamePrefixes.isEmpty()) { // Group prefix conditions inside a single AND-bracketed OR chain @@ -427,24 +649,71 @@ public class WorkspaceFileService { } /** - * 将启用的工作区文件拼接为系统提示词 + * Restrict a query to memory visible to {@code ownerKey}: shared rows + * (TEAM / GLOBAL) always, plus this owner's own PERSONAL rows. When + * {@code ownerKey} is null/blank only shared rows are returned. + */ + private void applyScopeVisibility(LambdaQueryWrapper wrapper, String ownerKey) { + if (ownerKey == null || ownerKey.isBlank()) { + wrapper.in(WorkspaceFileEntity::getScope, MemoryScope.TEAM, MemoryScope.GLOBAL); + return; + } + wrapper.and(w -> w + .in(WorkspaceFileEntity::getScope, MemoryScope.TEAM, MemoryScope.GLOBAL) + .or(p -> p.eq(WorkspaceFileEntity::getScope, MemoryScope.PERSONAL) + .eq(WorkspaceFileEntity::getOwnerKey, ownerKey))); + } + + /** + * 将启用的、共享（TEAM / GLOBAL）工作区文件拼接为系统提示词 *

    * 每个文件以 "--- {filename} ---\n{content}\n" 的格式拼接。 * 如果没有启用的文件，返回 null。 + *

    + * Baked once at agent build time and shared by every requester, so this + * deliberately excludes PERSONAL rows — per-owner memory is injected + * per-turn via {@link #buildOwnerMemoryBlock(Long, String)} instead. */ public String buildSystemPrompt(Long agentId) { List enabledFiles = fileMapper.selectList( new LambdaQueryWrapper() .eq(WorkspaceFileEntity::getAgentId, agentId) .eq(WorkspaceFileEntity::getEnabled, true) + .in(WorkspaceFileEntity::getScope, MemoryScope.TEAM, MemoryScope.GLOBAL) .orderByAsc(WorkspaceFileEntity::getSortOrder)); - if (enabledFiles.isEmpty()) { + return concatFiles(enabledFiles); + } + + /** + * Assemble the per-owner memory block injected before each LLM call. + *

    + * Returns the enabled PERSONAL files belonging to {@code ownerKey} (the + * owner's consolidated MEMORY.md / PROFILE.md and any enabled daily notes), + * concatenated in the same format as {@link #buildSystemPrompt(Long)}. + * Null when the owner has no personal memory yet. + */ + public String buildOwnerMemoryBlock(Long agentId, String ownerKey) { + if (agentId == null || ownerKey == null || ownerKey.isBlank()) { return null; } + List files = fileMapper.selectList( + new LambdaQueryWrapper() + .eq(WorkspaceFileEntity::getAgentId, agentId) + .eq(WorkspaceFileEntity::getEnabled, true) + .eq(WorkspaceFileEntity::getScope, MemoryScope.PERSONAL) + .eq(WorkspaceFileEntity::getOwnerKey, ownerKey) + .orderByAsc(WorkspaceFileEntity::getSortOrder)); + return concatFiles(files); + } + /** Concatenate file bodies in the "--- {filename} ---\n{content}" format. */ + private String concatFiles(List files) { + if (files == null || files.isEmpty()) { + return null; + } StringBuilder sb = new StringBuilder(); - for (WorkspaceFileEntity file : enabledFiles) { + for (WorkspaceFileEntity file : files) { if (file.getContent() != null && !file.getContent().isBlank()) { if (!sb.isEmpty()) { sb.append("\n\n"); diff --git a/mateclaw-server/src/main/java/vip/mate/workspace/document/controller/WorkspaceFileController.java b/mateclaw-server/src/main/java/vip/mate/workspace/document/controller/WorkspaceFileController.java index 0f049fb7..70bf6d57 100644 --- a/mateclaw-server/src/main/java/vip/mate/workspace/document/controller/WorkspaceFileController.java +++ b/mateclaw-server/src/main/java/vip/mate/workspace/document/controller/WorkspaceFileController.java @@ -42,7 +42,9 @@ public class WorkspaceFileController { @RequireWorkspaceRole("viewer") @GetMapping("/files") public R> listFiles(@PathVariable Long agentId) { - return R.ok(workspaceFileService.listFiles(agentId)); + // Config-editor surface: shared (TEAM/GLOBAL) files only. Per-owner + // PERSONAL memory rows are never exposed or managed through this REST API. + return R.ok(workspaceFileService.listVisibleFiles(agentId, null)); } /** diff --git a/mateclaw-server/src/main/java/vip/mate/workspace/document/event/WorkspaceFileChangedEvent.java b/mateclaw-server/src/main/java/vip/mate/workspace/document/event/WorkspaceFileChangedEvent.java new file mode 100644 index 00000000..ddaac410 --- /dev/null +++ b/mateclaw-server/src/main/java/vip/mate/workspace/document/event/WorkspaceFileChangedEvent.java @@ -0,0 +1,16 @@ +package vip.mate.workspace.document.event; + +/** + * Published whenever an agent's workspace file is created, updated, or deleted. + *

    + * Workspace files (AGENTS.md, SOUL.md, PROFILE.md, MEMORY.md, structured/*.md) + * are baked into the agent's system prompt when its runtime instance is built. + * Listeners use this to invalidate the cached agent instance so memory edits + * (tool writes, consolidation, cleanup) take effect on the next turn instead of + * only after an agent config change or restart. + * + * @param agentId the affected agent + * @param filename the workspace file that changed + */ +public record WorkspaceFileChangedEvent(Long agentId, String filename) { +} diff --git a/mateclaw-server/src/main/java/vip/mate/workspace/document/model/WorkspaceFileEntity.java b/mateclaw-server/src/main/java/vip/mate/workspace/document/model/WorkspaceFileEntity.java index 373dbc76..5fc2af37 100644 --- a/mateclaw-server/src/main/java/vip/mate/workspace/document/model/WorkspaceFileEntity.java +++ b/mateclaw-server/src/main/java/vip/mate/workspace/document/model/WorkspaceFileEntity.java @@ -36,6 +36,20 @@ public class WorkspaceFileEntity { /** 排序顺序（越小越靠前） */ private Integer sortOrder; + /** + * Memory subject this row belongs to, as a prefixed string + * ("user:42", "feishu:ou_xxx", "api:<endUserId>"). Null for shared + * config rows (AGENTS.md / SOUL.md / PROFILE.md) and legacy data. + */ + private String ownerKey; + + /** + * Visibility scope: PERSONAL (only the matching {@link #ownerKey} sees it), + * TEAM (everyone using the agent), or GLOBAL (always visible). Defaults to + * TEAM at the DB level so config files and legacy rows stay shared. + */ + private String scope; + @TableField(fill = FieldFill.INSERT) private LocalDateTime createTime; diff --git a/mateclaw-server/src/main/resources/application-mysql.yml b/mateclaw-server/src/main/resources/application-mysql.yml index 919d3d94..d7e0cafd 100644 --- a/mateclaw-server/src/main/resources/application-mysql.yml +++ b/mateclaw-server/src/main/resources/application-mysql.yml @@ -25,3 +25,13 @@ spring: h2: console: enabled: false + +# Production (multi-tenant server) hardening: fail closed on source-path +# validation. With no allowed-source-roots configured, every KB source +# directory is rejected rather than allowing full-filesystem reads — so a +# missing allow-list cannot silently re-open arbitrary directory scanning. +# Operators set mate.wiki.allowed-source-roots to permit specific roots. +# The default profile (H2 / desktop / single-tenant) leaves this off. +mate: + wiki: + require-allowed-roots: true diff --git a/mateclaw-server/src/main/resources/db/data-en.sql b/mateclaw-server/src/main/resources/db/data-en.sql index ecee62e0..752e1772 100644 --- a/mateclaw-server/src/main/resources/db/data-en.sql +++ b/mateclaw-server/src/main/resources/db/data-en.sql @@ -339,7 +339,15 @@ MERGE INTO mate_model_config (id, name, provider, model_name, description, tempe (1000000273, 'Claude Sonnet 4.6', 'openrouter', 'anthropic/claude-sonnet-4-6', 'Claude Sonnet 4.6 via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -- RFC-062: Claude 4.7 via Claude Code OAuth subscription (Pro/Max plan). (1000000280, 'Claude Opus 4.7', 'anthropic-claude-code', 'claude-opus-4-7', 'Claude Opus 4.7 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', 'Claude Sonnet 4.6 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0); +(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', 'Claude Sonnet 4.6 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- Claude 4.8 series (direct Anthropic + OpenRouter, including the -fast variant). +-- Shares 4.7's strict sampling contract (temperature/top_p/top_k must be NULL) +-- and the new xhigh thinking tier — handled in AnthropicChatModelBuilder. +(1000000290, 'Claude Opus 4.8', 'anthropic', 'claude-opus-4-8', 'Anthropic Claude Opus 4.8 (xhigh adaptive thinking)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000291, 'Claude Opus 4.8 Fast', 'anthropic', 'claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant (higher output speed, 2x pricing)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000292, 'Claude Opus 4.8', 'openrouter', 'anthropic/claude-opus-4-8', 'Claude Opus 4.8 via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000293, 'Claude Opus 4.8 Fast', 'openrouter', 'anthropic/claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000294, 'Claude Opus 4.8', 'anthropic-claude-code', 'claude-opus-4-8', 'Claude Opus 4.8 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0); -- Default system settings MERGE INTO mate_system_setting (id, setting_key, setting_value, description, create_time, update_time) @@ -539,7 +547,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -570,7 +578,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -1301,15 +1309,15 @@ VALUES (1000100002, 'Weekly Work Summary', '0 18 * * 5', 'Asia/Shanghai', 100000 -- Daily 2:00 AM: consolidate daily notes → MEMORY.md MERGE INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) KEY (id) -VALUES (1000100010, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0); +VALUES (1000100010, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0); MERGE INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) KEY (id) -VALUES (1000100011, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0); +VALUES (1000100011, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0); MERGE INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) KEY (id) -VALUES (1000100012, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0); +VALUES (1000100012, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0); -- ==================== Workspace File Seed Data ==================== -- Each Agent has its own workspace document collection: AGENTS.md / SOUL.md / PROFILE.md / MEMORY.md diff --git a/mateclaw-server/src/main/resources/db/data-mysql-en.sql b/mateclaw-server/src/main/resources/db/data-mysql-en.sql index 2d197d95..05d553a3 100644 --- a/mateclaw-server/src/main/resources/db/data-mysql-en.sql +++ b/mateclaw-server/src/main/resources/db/data-mysql-en.sql @@ -387,7 +387,15 @@ VALUES (1000000273, 'Claude Sonnet 4.6', 'openrouter', 'anthropic/claude-sonnet-4-6', 'Claude Sonnet 4.6 via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -- RFC-062: Claude 4.7 via Claude Code OAuth subscription (Pro/Max plan). (1000000280, 'Claude Opus 4.7', 'anthropic-claude-code', 'claude-opus-4-7', 'Claude Opus 4.7 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', 'Claude Sonnet 4.6 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0) +(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', 'Claude Sonnet 4.6 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- Claude 4.8 series (direct Anthropic + OpenRouter, including the -fast variant). +-- Shares 4.7's strict sampling contract (temperature/top_p/top_k must be NULL) +-- and the new xhigh thinking tier — handled in AnthropicChatModelBuilder. +(1000000290, 'Claude Opus 4.8', 'anthropic', 'claude-opus-4-8', 'Anthropic Claude Opus 4.8 (xhigh adaptive thinking)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000291, 'Claude Opus 4.8 Fast', 'anthropic', 'claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant (higher output speed, 2x pricing)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000292, 'Claude Opus 4.8', 'openrouter', 'anthropic/claude-opus-4-8', 'Claude Opus 4.8 via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000293, 'Claude Opus 4.8 Fast', 'openrouter', 'anthropic/claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000294, 'Claude Opus 4.8', 'anthropic-claude-code', 'claude-opus-4-8', 'Claude Opus 4.8 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), provider=VALUES(provider), model_name=VALUES(model_name), description=VALUES(description), temperature=VALUES(temperature), max_tokens=VALUES(max_tokens), top_p=VALUES(top_p), builtin=VALUES(builtin), enabled=VALUES(enabled), is_default=VALUES(is_default), update_time=VALUES(update_time), deleted=VALUES(deleted); -- Default system settings @@ -588,7 +596,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -619,7 +627,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -1345,15 +1353,15 @@ ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expressio -- ==================== Memory Emergence Cron Jobs ==================== -- Daily 2:00 AM: consolidate daily notes → MEMORY.md INSERT INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) -VALUES (1000100010, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0) +VALUES (1000100010, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expression), timezone=VALUES(timezone), agent_id=VALUES(agent_id), task_type=VALUES(task_type), trigger_message=VALUES(trigger_message), request_body=VALUES(request_body), enabled=VALUES(enabled), update_time=VALUES(update_time), deleted=VALUES(deleted); INSERT INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) -VALUES (1000100011, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0) +VALUES (1000100011, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expression), timezone=VALUES(timezone), agent_id=VALUES(agent_id), task_type=VALUES(task_type), trigger_message=VALUES(trigger_message), request_body=VALUES(request_body), enabled=VALUES(enabled), update_time=VALUES(update_time), deleted=VALUES(deleted); INSERT INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) -VALUES (1000100012, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0) +VALUES (1000100012, 'Memory Consolidation', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.', NULL, TRUE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expression), timezone=VALUES(timezone), agent_id=VALUES(agent_id), task_type=VALUES(task_type), trigger_message=VALUES(trigger_message), request_body=VALUES(request_body), enabled=VALUES(enabled), update_time=VALUES(update_time), deleted=VALUES(deleted); -- ==================== Workspace File Seed Data ==================== diff --git a/mateclaw-server/src/main/resources/db/data-mysql-zh.sql b/mateclaw-server/src/main/resources/db/data-mysql-zh.sql index b778b395..90252fb9 100644 --- a/mateclaw-server/src/main/resources/db/data-mysql-zh.sql +++ b/mateclaw-server/src/main/resources/db/data-mysql-zh.sql @@ -384,7 +384,14 @@ VALUES (1000000273, 'Claude Sonnet 4.6', 'openrouter', 'anthropic/claude-sonnet-4-6', 'OpenRouter 代理 Claude Sonnet 4.6', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -- RFC-062：通过 Claude Code Pro/Max 订阅调用 Claude 4.7 (1000000280, 'Claude Opus 4.7', 'anthropic-claude-code', 'claude-opus-4-7', '通过 Claude Code Pro/Max 订阅调用 Claude Opus 4.7', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', '通过 Claude Code Pro/Max 订阅调用 Claude Sonnet 4.6', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0) +(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', '通过 Claude Code Pro/Max 订阅调用 Claude Sonnet 4.6', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- Claude 4.8 系列（直连 Anthropic + OpenRouter，包含 -fast 高速变体） +-- 与 4.7 共享严格采样契约：temperature / top_p / top_k 必须为空，新增 xhigh 思考档位 +(1000000290, 'Claude Opus 4.8', 'anthropic', 'claude-opus-4-8', 'Anthropic Claude Opus 4.8（xhigh 自适应思考）', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000291, 'Claude Opus 4.8 Fast', 'anthropic', 'claude-opus-4-8-fast', 'Claude Opus 4.8 高速变体（输出更快、单价 2x）', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000292, 'Claude Opus 4.8', 'openrouter', 'anthropic/claude-opus-4-8', 'OpenRouter 代理 Claude Opus 4.8', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000293, 'Claude Opus 4.8 Fast', 'openrouter', 'anthropic/claude-opus-4-8-fast', 'OpenRouter 代理 Claude Opus 4.8 高速变体', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000294, 'Claude Opus 4.8', 'anthropic-claude-code', 'claude-opus-4-8', '通过 Claude Code Pro/Max 订阅调用 Claude Opus 4.8', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), provider=VALUES(provider), model_name=VALUES(model_name), description=VALUES(description), temperature=VALUES(temperature), max_tokens=VALUES(max_tokens), top_p=VALUES(top_p), builtin=VALUES(builtin), enabled=VALUES(enabled), is_default=VALUES(is_default), update_time=VALUES(update_time), deleted=VALUES(deleted); -- 默认系统设置 @@ -586,7 +593,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -617,7 +624,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -1343,15 +1350,15 @@ ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expressio -- ==================== 记忆整合定时任务 ==================== -- 每天凌晨 2:00 整合 daily notes → MEMORY.md INSERT INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) -VALUES (1000100010, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0) +VALUES (1000100010, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expression), timezone=VALUES(timezone), agent_id=VALUES(agent_id), task_type=VALUES(task_type), trigger_message=VALUES(trigger_message), request_body=VALUES(request_body), enabled=VALUES(enabled), update_time=VALUES(update_time), deleted=VALUES(deleted); INSERT INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) -VALUES (1000100011, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0) +VALUES (1000100011, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expression), timezone=VALUES(timezone), agent_id=VALUES(agent_id), task_type=VALUES(task_type), trigger_message=VALUES(trigger_message), request_body=VALUES(request_body), enabled=VALUES(enabled), update_time=VALUES(update_time), deleted=VALUES(deleted); INSERT INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) -VALUES (1000100012, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0) +VALUES (1000100012, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0) ON DUPLICATE KEY UPDATE name=VALUES(name), cron_expression=VALUES(cron_expression), timezone=VALUES(timezone), agent_id=VALUES(agent_id), task_type=VALUES(task_type), trigger_message=VALUES(trigger_message), request_body=VALUES(request_body), enabled=VALUES(enabled), update_time=VALUES(update_time), deleted=VALUES(deleted); -- ==================== 工作区文件种子数据（参考 MateClaw md_files/zh） ==================== diff --git a/mateclaw-server/src/main/resources/db/data-zh.sql b/mateclaw-server/src/main/resources/db/data-zh.sql index a663950d..c480a59a 100644 --- a/mateclaw-server/src/main/resources/db/data-zh.sql +++ b/mateclaw-server/src/main/resources/db/data-zh.sql @@ -341,7 +341,14 @@ MERGE INTO mate_model_config (id, name, provider, model_name, description, tempe (1000000273, 'Claude Sonnet 4.6', 'openrouter', 'anthropic/claude-sonnet-4-6', 'OpenRouter 代理 Claude Sonnet 4.6', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -- RFC-062：通过 Claude Code Pro/Max 订阅调用 Claude 4.7 (1000000280, 'Claude Opus 4.7', 'anthropic-claude-code', 'claude-opus-4-7', '通过 Claude Code Pro/Max 订阅调用 Claude Opus 4.7', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), -(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', '通过 Claude Code Pro/Max 订阅调用 Claude Sonnet 4.6', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0); +(1000000281, 'Claude Sonnet 4.6', 'anthropic-claude-code', 'claude-sonnet-4-6', '通过 Claude Code Pro/Max 订阅调用 Claude Sonnet 4.6', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- Claude 4.8 系列（直连 Anthropic + OpenRouter，包含 -fast 高速变体） +-- 与 4.7 共享严格采样契约：temperature / top_p / top_k 必须为空，新增 xhigh 思考档位 +(1000000290, 'Claude Opus 4.8', 'anthropic', 'claude-opus-4-8', 'Anthropic Claude Opus 4.8（xhigh 自适应思考）', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000291, 'Claude Opus 4.8 Fast', 'anthropic', 'claude-opus-4-8-fast', 'Claude Opus 4.8 高速变体（输出更快、单价 2x）', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000292, 'Claude Opus 4.8', 'openrouter', 'anthropic/claude-opus-4-8', 'OpenRouter 代理 Claude Opus 4.8', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000293, 'Claude Opus 4.8 Fast', 'openrouter', 'anthropic/claude-opus-4-8-fast', 'OpenRouter 代理 Claude Opus 4.8 高速变体', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000294, 'Claude Opus 4.8', 'anthropic-claude-code', 'claude-opus-4-8', '通过 Claude Code Pro/Max 订阅调用 Claude Opus 4.8', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0); -- 默认系统设置 MERGE INTO mate_system_setting (id, setting_key, setting_value, description, create_time, update_time) @@ -541,7 +548,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -572,7 +579,7 @@ VALUES ( NULL, FALSE, 30, - 30, + 60, 'disconnected', NULL, NULL, @@ -1303,15 +1310,15 @@ VALUES (1000100002, '每周工作总结', '0 18 * * 5', 'Asia/Shanghai', 1000000 -- 每天凌晨 2:00 整合 daily notes → MEMORY.md MERGE INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) KEY (id) -VALUES (1000100010, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0); +VALUES (1000100010, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000001, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0); MERGE INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) KEY (id) -VALUES (1000100011, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0); +VALUES (1000100011, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000002, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0); MERGE INTO mate_cron_job (id, name, cron_expression, timezone, agent_id, task_type, trigger_message, request_body, enabled, create_time, update_time, deleted) KEY (id) -VALUES (1000100012, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0); +VALUES (1000100012, '记忆整合', '0 2 * * *', 'Asia/Shanghai', 1000000003, 'text', '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。', NULL, TRUE, NOW(), NOW(), 0); -- ==================== 工作区文件种子数据（参考 MateClaw md_files/zh） ==================== -- 每个 Agent 拥有独立的工作区文档集合：AGENTS.md / SOUL.md / PROFILE.md / MEMORY.md diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V125__agent_workspace_base_path.sql b/mateclaw-server/src/main/resources/db/migration/h2/V125__agent_workspace_base_path.sql new file mode 100644 index 00000000..ff29de3d --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V125__agent_workspace_base_path.sql @@ -0,0 +1,3 @@ +-- V125: Add workspace_base_path column to mate_agent for agent-level directory override. +-- When set, this overrides the workspace-level basePath for this agent only. +ALTER TABLE mate_agent ADD COLUMN IF NOT EXISTS workspace_base_path VARCHAR(512) DEFAULT NULL; diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V126__agent_binding_disabled_flags.sql b/mateclaw-server/src/main/resources/db/migration/h2/V126__agent_binding_disabled_flags.sql new file mode 100644 index 00000000..f6f3a91c --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V126__agent_binding_disabled_flags.sql @@ -0,0 +1,12 @@ +-- V126: Two binding-mode flags on mate_agent. +-- +-- skills_disabled / tools_disabled flip the "zero binding rows" semantic from +-- "inherit every globally-enabled capability" to "this agent has explicitly +-- opted out". Without these columns, an operator who wanted an agent with no +-- skills had to bind a dummy skill — otherwise the runtime fell back to the +-- global default and every skill's catalog entry got injected into the system +-- prompt (issue #184). +-- +-- Both default to FALSE so legacy agents are bit-identical to pre-V126 behavior. +ALTER TABLE mate_agent ADD COLUMN IF NOT EXISTS skills_disabled BOOLEAN NOT NULL DEFAULT FALSE; +ALTER TABLE mate_agent ADD COLUMN IF NOT EXISTS tools_disabled BOOLEAN NOT NULL DEFAULT FALSE; diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V127__approval_auto_grant.sql b/mateclaw-server/src/main/resources/db/migration/h2/V127__approval_auto_grant.sql new file mode 100644 index 00000000..9b494243 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V127__approval_auto_grant.sql @@ -0,0 +1,29 @@ +-- V127: Approval auto-grant table. +-- Holds user-authorized rules that let ApprovalGrantResolver bypass createPending() +-- for matching tool calls. Each row is an explicit grant with a defined scope, +-- optional tool/rule filter, and a severity ceiling. Hard-floor patterns still +-- block irrespective of any grant. +CREATE TABLE IF NOT EXISTS mate_approval_grant ( + id BIGINT NOT NULL PRIMARY KEY, + workspace_id BIGINT NOT NULL, + scope_type VARCHAR(32) NOT NULL, -- USER | AGENT | CONVERSATION | WORKSPACE + scope_id VARCHAR(64) NOT NULL, -- snowflake string per CLAUDE.md precision convention + tool_name VARCHAR(128), -- NULL = any tool (UI requires password confirm) + rule_id VARCHAR(128), -- matches GuardFinding.ruleId; NULL = any rule + max_severity VARCHAR(16) NOT NULL, -- LOW | MEDIUM | HIGH (CRITICAL rejected by API/UI) + grant_kind VARCHAR(24) NOT NULL, -- ALWAYS | UNTIL_TIMESTAMP | UNTIL_CONVERSATION_END + expire_at DATETIME, -- only when grant_kind = UNTIL_TIMESTAMP + granted_by BIGINT NOT NULL, + granted_at DATETIME NOT NULL, + revoked TINYINT NOT NULL DEFAULT 0, + revoked_by BIGINT, + revoked_at DATETIME, + note VARCHAR(500), + create_time DATETIME NOT NULL, + update_time DATETIME NOT NULL, + deleted TINYINT NOT NULL DEFAULT 0 +); +CREATE INDEX IF NOT EXISTS idx_grant_scope + ON mate_approval_grant(workspace_id, scope_type, scope_id, tool_name, revoked, deleted); +CREATE INDEX IF NOT EXISTS idx_grant_expire + ON mate_approval_grant(expire_at, revoked, deleted); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V128__approval_resolution_log.sql b/mateclaw-server/src/main/resources/db/migration/h2/V128__approval_resolution_log.sql new file mode 100644 index 00000000..24a7e6c8 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V128__approval_resolution_log.sql @@ -0,0 +1,35 @@ +-- V128: Approval resolution log table. +-- Single source of truth for "approval-layer final decisions": +-- USER_MANUAL / AUTO_GRANT / HARD_BLOCK / TIMEOUT. Decoupled from the existing +-- mate_tool_guard_audit_log (which records guard evaluation facts), so Dashboard +-- decision-source charts can compute clean percentages without double-counting. +CREATE TABLE IF NOT EXISTS mate_approval_resolution_log ( + id BIGINT NOT NULL PRIMARY KEY, + -- Nullable: a HARD_BLOCK event can fire before WorkspaceLookupCache has + -- resolved a workspace (missing/deleted conversation, malformed context). + -- Recording the safety event itself is more important than tying it to a + -- workspace; per-workspace Dashboard panels filter with `workspace_id = ?` + -- and naturally skip these rows, while the global "recent HARD_BLOCKs" + -- panel still surfaces them. + workspace_id BIGINT, + conversation_id VARCHAR(128), + agent_id VARCHAR(64), + user_id VARCHAR(64), + tool_call_id VARCHAR(64), -- correlates to AssistantMessage.ToolCall.id when available + tool_name VARCHAR(128) NOT NULL, + max_severity VARCHAR(16), + rule_ids VARCHAR(512), -- comma-joined list of GuardFinding ruleIds + decision_source VARCHAR(24) NOT NULL, -- USER_MANUAL | AUTO_GRANT | HARD_BLOCK | TIMEOUT + grant_id BIGINT, -- non-null when decision_source = AUTO_GRANT + pending_id VARCHAR(32), -- non-null when path went through createPending() + args_preview VARCHAR(500), -- first 500 chars of rawArguments (WARN log prints 200) + note VARCHAR(500), + create_time DATETIME NOT NULL, + deleted TINYINT NOT NULL DEFAULT 0 +); +CREATE INDEX IF NOT EXISTS idx_resolution_workspace_time + ON mate_approval_resolution_log(workspace_id, create_time); +CREATE INDEX IF NOT EXISTS idx_resolution_grant + ON mate_approval_resolution_log(grant_id); +CREATE INDEX IF NOT EXISTS idx_resolution_pending + ON mate_approval_resolution_log(pending_id); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V129__wiki_page_broken_links.sql b/mateclaw-server/src/main/resources/db/migration/h2/V129__wiki_page_broken_links.sql new file mode 100644 index 00000000..0b874688 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V129__wiki_page_broken_links.sql @@ -0,0 +1,17 @@ +-- V129: Persisted wikilink lint state. +-- +-- broken_links JSON array of unresolved outlink targets for THIS +-- page. Derived from outgoing_links minus the active +-- KB slug set (case-insensitive). Empty array means +-- "scanned, all targets resolve"; NULL means +-- "never scanned". Kept separate from outgoing_links +-- (which records every [[...]] target written into +-- content, hit-or-miss) so backlinks / direct-link +-- signals are unaffected. +-- broken_links_scanned_at Timestamp of the most recent broken_links +-- recompute. UI surfaces this as "last scan" so +-- staleness is visible. Reset whenever the page is +-- re-saved (broken_links is recomputed in the same +-- transaction). +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS broken_links TEXT DEFAULT NULL; +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS broken_links_scanned_at TIMESTAMP DEFAULT NULL; diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V130__agent_primary_kb.sql b/mateclaw-server/src/main/resources/db/migration/h2/V130__agent_primary_kb.sql new file mode 100644 index 00000000..ab10c0b0 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V130__agent_primary_kb.sql @@ -0,0 +1,25 @@ +-- V129: Store the per-agent primary wiki KB on mate_agent. +-- +-- Knowledge bases remain workspace-shared; this field only chooses the +-- default KB for wiki tools when no kbName/kbId is specified. +ALTER TABLE mate_agent ADD COLUMN IF NOT EXISTS primary_kb_id BIGINT DEFAULT NULL; +CREATE INDEX IF NOT EXISTS idx_agent_primary_kb ON mate_agent(primary_kb_id); + +UPDATE mate_agent a +SET primary_kb_id = ( + SELECT kb.id + FROM mate_wiki_knowledge_base kb + WHERE kb.agent_id = a.id + AND (kb.workspace_id IS NULL OR kb.workspace_id = a.workspace_id) + AND kb.deleted = 0 + ORDER BY kb.update_time DESC + LIMIT 1 +) +WHERE a.primary_kb_id IS NULL + AND EXISTS ( + SELECT 1 + FROM mate_wiki_knowledge_base kb + WHERE kb.agent_id = a.id + AND (kb.workspace_id IS NULL OR kb.workspace_id = a.workspace_id) + AND kb.deleted = 0 + ); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V131__claude_48_models.sql b/mateclaw-server/src/main/resources/db/migration/h2/V131__claude_48_models.sql new file mode 100644 index 00000000..9705bafc --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V131__claude_48_models.sql @@ -0,0 +1,24 @@ +-- Add Claude Opus 4.8 (regular + -fast variant) model entries to +-- mate_model_config for existing deployments. New installs pick these up via +-- DatabaseBootstrapRunner from data-{en,zh}.sql; this migration covers +-- operators who already have V1 baseline + earlier versions applied. +-- +-- Claude 4.8 inherits 4.7's strict API contract: temperature / top_p / top_k +-- must be NULL (otherwise HTTP 400), and the "xhigh" thinking tier is +-- available. Both are handled in AnthropicChatModelBuilder via the +-- isClaude47OrLater() detector. +-- +-- MERGE INTO is the H2 idempotent upsert; running this twice is a no-op. +-- Same V number is used in mysql/ for cross-dialect parity. + +MERGE INTO mate_model_config (id, name, provider, model_name, description, temperature, max_tokens, top_p, builtin, enabled, is_default, create_time, update_time, deleted) +KEY (id) +VALUES +-- Direct Anthropic +(1000000290, 'Claude Opus 4.8', 'anthropic', 'claude-opus-4-8', 'Anthropic Claude Opus 4.8 (xhigh adaptive thinking)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000291, 'Claude Opus 4.8 Fast', 'anthropic', 'claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant (higher output speed, 2x pricing)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- OpenRouter passthrough +(1000000292, 'Claude Opus 4.8', 'openrouter', 'anthropic/claude-opus-4-8', 'Claude Opus 4.8 via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000293, 'Claude Opus 4.8 Fast', 'openrouter', 'anthropic/claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- Claude Code OAuth (Pro/Max subscription) +(1000000294, 'Claude Opus 4.8', 'anthropic-claude-code', 'claude-opus-4-8', 'Claude Opus 4.8 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V132__memory_consolidation_cron_tier_discipline.sql b/mateclaw-server/src/main/resources/db/migration/h2/V132__memory_consolidation_cron_tier_discipline.sql new file mode 100644 index 00000000..dc961ad0 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V132__memory_consolidation_cron_tier_discipline.sql @@ -0,0 +1,13 @@ +-- Update the daily "memory consolidation" cron prompt on existing databases so it +-- keeps project-specific volatile facts (codenames, tech stacks, per-project +-- decisions) out of the always-on MEMORY.md. Seed scripts only run on fresh +-- installs, so existing rows need this data migration to pick up the new wording. +-- Scoped to the original default text so user-edited prompts are left untouched. + +UPDATE mate_cron_job +SET trigger_message = '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。' +WHERE trigger_message = '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。'; + +UPDATE mate_cron_job +SET trigger_message = 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.' +WHERE trigger_message = 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.'; diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V133__wiki_agent_page_type_permission.sql b/mateclaw-server/src/main/resources/db/migration/h2/V133__wiki_agent_page_type_permission.sql new file mode 100644 index 00000000..a903e727 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V133__wiki_agent_page_type_permission.sql @@ -0,0 +1,25 @@ +-- V133: Per-agent, per-KB, per-pageType permission for wiki tools. +-- Read permission filters retrieval/listing; write permission gates the +-- create/compile/delete/archive/enrich/transformation tools. A row with +-- page_type='*' is the agent's KB-wide default; an exact page_type row is +-- more specific and wins over '*'. Unconfigured (no rows) falls back to the +-- KB-level defaultReadPolicy stored in the KB config. + +CREATE TABLE IF NOT EXISTS mate_wiki_agent_page_type_permission ( + id BIGINT NOT NULL PRIMARY KEY, + agent_id BIGINT NOT NULL, + kb_id BIGINT NOT NULL, + page_type VARCHAR(64) NOT NULL, + can_read TINYINT NOT NULL DEFAULT 1, + can_create TINYINT NOT NULL DEFAULT 0, + can_update TINYINT NOT NULL DEFAULT 0, + can_delete TINYINT NOT NULL DEFAULT 0, + write_policy VARCHAR(32) NOT NULL DEFAULT 'approval_required', + create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted INT NOT NULL DEFAULT 0 +); +CREATE UNIQUE INDEX IF NOT EXISTS uk_wiki_agent_ptperm + ON mate_wiki_agent_page_type_permission (agent_id, kb_id, page_type, deleted); +CREATE INDEX IF NOT EXISTS idx_wiki_ptperm_agent_kb + ON mate_wiki_agent_page_type_permission (agent_id, kb_id, deleted); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V134__wiki_page_type_profile.sql b/mateclaw-server/src/main/resources/db/migration/h2/V134__wiki_page_type_profile.sql new file mode 100644 index 00000000..5f2d55b2 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V134__wiki_page_type_profile.sql @@ -0,0 +1,43 @@ +-- V134: KB-scoped pageType profile + structured page metadata columns. +-- +-- A profile holds a KB's pageType definitions (field schema, per-stage LLM +-- instructions, Markdown template) as config_json. The built-in default +-- profile is NOT stored here — it lives as a code constant — so kb_id is +-- NOT NULL and every stored row belongs to a concrete KB. +-- +-- "At most one enabled profile per KB" is enforced at the DB level via a +-- virtual generated column that yields kb_id only for the live-enabled +-- subset (NULL otherwise) plus a plain UNIQUE constraint; NULLs are +-- non-comparable under UNIQUE, so disabled/deleted rows coexist. This avoids +-- a service-layer check-then-insert race across horizontally-scaled nodes. + +CREATE TABLE IF NOT EXISTS mate_wiki_page_type_profile ( + id BIGINT NOT NULL, + kb_id BIGINT NOT NULL, + name VARCHAR(128) NOT NULL, + version INT NOT NULL DEFAULT 1, + config_json CLOB NOT NULL, + enabled TINYINT NOT NULL DEFAULT 1, + create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted INT NOT NULL DEFAULT 0, + -- Yields kb_id only for the live-enabled row; NULL otherwise. The UNIQUE + -- constraint below then permits at most one enabled profile per KB. + enabled_kb BIGINT GENERATED ALWAYS AS ( + CASE WHEN enabled = 1 AND deleted = 0 THEN kb_id ELSE NULL END + ), + PRIMARY KEY (id), + CONSTRAINT uk_wiki_ptprofile_name UNIQUE (kb_id, name, deleted), + CONSTRAINT uk_wiki_ptprofile_enabled UNIQUE (enabled_kb) +); +CREATE INDEX IF NOT EXISTS idx_wiki_ptprofile_kb + ON mate_wiki_page_type_profile (kb_id, enabled, deleted); + +-- Structured page metadata: schema-validated pageType fields live in +-- metadata_json (not exploded into columns); validation status/details and +-- the generating profile/template are recorded alongside. +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS metadata_json CLOB; +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS metadata_validation_status VARCHAR(32); +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS metadata_validation_json CLOB; +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS template_key VARCHAR(128); +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS profile_version INT; diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V135__wiki_layered_knowledge.sql b/mateclaw-server/src/main/resources/db/migration/h2/V135__wiki_layered_knowledge.sql new file mode 100644 index 00000000..e8d81b5b --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V135__wiki_layered_knowledge.sql @@ -0,0 +1,29 @@ +-- V135: Layered knowledge (fact / experience) + page dependency graph. +-- +-- knowledge_layer is derived from the pageType profile (fact = "what is", +-- experience = "what it means"). Experience pages depend on fact pages; the +-- dependency table is the source of truth for stale propagation (reverse +-- lookup by depends_on_page_id), with the page-local depends_on_json kept as +-- a redundant copy. Stored by page id, never slug, so renames cannot break a +-- dependency. + +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS knowledge_layer VARCHAR(16); +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS depends_on_json CLOB; +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS stale TINYINT NOT NULL DEFAULT 0; +ALTER TABLE mate_wiki_page ADD COLUMN IF NOT EXISTS stale_reason_json CLOB; + +CREATE TABLE IF NOT EXISTS mate_wiki_page_dependency ( + id BIGINT NOT NULL PRIMARY KEY, + kb_id BIGINT NOT NULL, + page_id BIGINT NOT NULL, + depends_on_page_id BIGINT NOT NULL, + dependency_type VARCHAR(32) NOT NULL DEFAULT 'fact', + create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted INT NOT NULL DEFAULT 0 +); +CREATE UNIQUE INDEX IF NOT EXISTS uk_wiki_page_dep + ON mate_wiki_page_dependency (page_id, depends_on_page_id, dependency_type, deleted); +-- Reverse lookup for stale propagation: "who depends on this fact page". +CREATE INDEX IF NOT EXISTS idx_wiki_page_dep_reverse + ON mate_wiki_page_dependency (kb_id, depends_on_page_id, deleted); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V136__wiki_pipeline_runtime.sql b/mateclaw-server/src/main/resources/db/migration/h2/V136__wiki_pipeline_runtime.sql new file mode 100644 index 00000000..721ecf0e --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V136__wiki_pipeline_runtime.sql @@ -0,0 +1,68 @@ +-- V136: Wiki pipeline runtime — definitions, runs, and per-step runs. +-- +-- A definition is a KB-scoped processing chain triggered by a pageType event +-- (MVP: page_type_count threshold). It declares an owner_agent_id so steps run +-- under a concrete RFC-permissioned identity. A run is one execution instance; +-- its unique key (definition_id, trigger_type, trigger_subject, trigger_bucket) +-- absorbs duplicate triggers across multiple instances. Step runs record each +-- executor invocation (MVP executors: llm, skill). + +CREATE TABLE IF NOT EXISTS mate_wiki_pipeline_definition ( + id BIGINT NOT NULL PRIMARY KEY, + kb_id BIGINT NOT NULL, + name VARCHAR(128) NOT NULL, + owner_agent_id BIGINT NOT NULL, + trigger_type VARCHAR(32) NOT NULL, + trigger_config_json CLOB, + steps_json CLOB NOT NULL, + dedup_window_seconds INT NOT NULL DEFAULT 0, + enabled TINYINT NOT NULL DEFAULT 1, + create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted INT NOT NULL DEFAULT 0 +); +CREATE UNIQUE INDEX IF NOT EXISTS uk_wiki_pipeline_def_name + ON mate_wiki_pipeline_definition (kb_id, name, deleted); +CREATE INDEX IF NOT EXISTS idx_wiki_pipeline_def_trigger + ON mate_wiki_pipeline_definition (kb_id, trigger_type, enabled, deleted); + +CREATE TABLE IF NOT EXISTS mate_wiki_pipeline_run ( + id BIGINT NOT NULL PRIMARY KEY, + definition_id BIGINT NOT NULL, + kb_id BIGINT NOT NULL, + status VARCHAR(16) NOT NULL, + trigger_type VARCHAR(32) NOT NULL, + trigger_subject VARCHAR(128) NOT NULL, + trigger_bucket VARCHAR(64) NOT NULL, + trigger_payload_json CLOB, + input_json CLOB, + output_json CLOB, + error_message VARCHAR(2048), + started_at TIMESTAMP, + finished_at TIMESTAMP, + create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted INT NOT NULL DEFAULT 0 +); +-- Idempotency: one run per (definition, trigger envelope). Duplicate triggers +-- across instances collide here instead of spawning parallel runs. +CREATE UNIQUE INDEX IF NOT EXISTS uk_wiki_pipeline_run_dedup + ON mate_wiki_pipeline_run (definition_id, trigger_type, trigger_subject, trigger_bucket, deleted); +CREATE INDEX IF NOT EXISTS idx_wiki_pipeline_run_def + ON mate_wiki_pipeline_run (definition_id, status); + +CREATE TABLE IF NOT EXISTS mate_wiki_pipeline_step_run ( + id BIGINT NOT NULL PRIMARY KEY, + run_id BIGINT NOT NULL, + step_id VARCHAR(128) NOT NULL, + executor VARCHAR(32) NOT NULL, + status VARCHAR(16) NOT NULL, + input_json CLOB, + output_json CLOB, + error_message VARCHAR(2048), + started_at TIMESTAMP, + finished_at TIMESTAMP, + create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted INT NOT NULL DEFAULT 0 +); +CREATE INDEX IF NOT EXISTS idx_wiki_pipeline_step_run + ON mate_wiki_pipeline_step_run (run_id, status); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V137__memory_owner_scope.sql b/mateclaw-server/src/main/resources/db/migration/h2/V137__memory_owner_scope.sql new file mode 100644 index 00000000..5d616a4e --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V137__memory_owner_scope.sql @@ -0,0 +1,55 @@ +-- V137: Per-owner memory isolation with a three-state visibility scope. +-- +-- Adds owner_key + scope to the three memory-bearing tables so a single agent +-- shared across multiple end-users (web users, IM senders, third-party API +-- end-users) keeps each owner's memory separate. +-- +-- owner_key - the memory subject this row belongs to, as a prefixed string +-- ("user:42", "feishu:ou_xxx", "api:"). NULL means +-- "not owner-scoped" (legacy / shared config rows). +-- scope - PERSONAL (only the matching owner_key sees it), +-- TEAM (everyone using the agent sees it), +-- GLOBAL (always visible). +-- +-- Existing rows are backfilled to scope='TEAM' by the NOT NULL DEFAULT so that +-- upgrading does NOT hide previously-shared memory. New memory writes set +-- scope='PERSONAL' with the resolved owner_key; agent config files (AGENTS.md, +-- SOUL.md, PROFILE.md) keep the TEAM default and stay shared. + +ALTER TABLE mate_workspace_file ADD COLUMN IF NOT EXISTS owner_key VARCHAR(128) NULL; +ALTER TABLE mate_workspace_file ADD COLUMN IF NOT EXISTS scope VARCHAR(16) NOT NULL DEFAULT 'TEAM'; +CREATE INDEX IF NOT EXISTS idx_workspace_file_scope_owner ON mate_workspace_file(agent_id, scope, owner_key); +-- Shared rows use the '' sentinel (not NULL) so the unique index below treats +-- one shared row per filename as a single slot. +UPDATE mate_workspace_file SET owner_key = '' WHERE owner_key IS NULL; +-- De-duplicate before adding the unique index: the table never had a unique +-- constraint and the service layer was check-then-insert, so historical +-- duplicates may exist. Keep the most recently inserted row per +-- (agent_id, filename, owner_key); drop the rest so the index can be created. +-- +-- IRREVERSIBLE: this keeps MAX(id) (newest row) and PERMANENTLY deletes the +-- other rows in a duplicate group — their content / enabled / sort_order are +-- not preserved or merged. Duplicates are NOT expected (every write path is +-- check-then-insert), so this is a safety net to guarantee the index builds, +-- not a routine merge. If a deployment knowingly relies on duplicate rows, +-- reconcile them manually before upgrading. +DELETE FROM mate_workspace_file +WHERE id NOT IN ( + SELECT keep_id FROM ( + SELECT MAX(id) AS keep_id + FROM mate_workspace_file + GROUP BY agent_id, filename, owner_key + ) t +); +-- One row per (agent, filename, owner): one shared row + one row per PERSONAL +-- owner. Hardens the check-then-insert in saveFile/saveMemoryFile against +-- concurrent / multi-node duplicates. +CREATE UNIQUE INDEX IF NOT EXISTS uk_workspace_file_owner ON mate_workspace_file(agent_id, filename, owner_key); + +ALTER TABLE mate_memory_recall ADD COLUMN IF NOT EXISTS owner_key VARCHAR(128) NULL; +ALTER TABLE mate_memory_recall ADD COLUMN IF NOT EXISTS scope VARCHAR(16) NOT NULL DEFAULT 'TEAM'; +CREATE INDEX IF NOT EXISTS idx_memory_recall_scope_owner ON mate_memory_recall(agent_id, scope, owner_key); + +ALTER TABLE mate_fact ADD COLUMN IF NOT EXISTS owner_key VARCHAR(128) NULL; +ALTER TABLE mate_fact ADD COLUMN IF NOT EXISTS scope VARCHAR(16) NOT NULL DEFAULT 'TEAM'; +CREATE INDEX IF NOT EXISTS idx_fact_scope_owner ON mate_fact(agent_id, scope, owner_key); diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V138__rename_search_tool_to_web_search.sql b/mateclaw-server/src/main/resources/db/migration/h2/V138__rename_search_tool_to_web_search.sql new file mode 100644 index 00000000..835cf030 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V138__rename_search_tool_to_web_search.sql @@ -0,0 +1,7 @@ +-- Rename the built-in web-search tool from "search" to "web_search". +-- DashScope's native protocol reserves the function name "search" and rejects any +-- request that declares a tool with that name ("InvalidParameter: Tool names are not +-- allowed to be [search]"), which broke tool use for every qwen/DashScope-native model +-- that had this tool bound. Migrate existing agent bindings to the new name so they +-- keep resolving after the tool was renamed in code. Idempotent. +UPDATE mate_agent_tool SET tool_name = 'web_search' WHERE tool_name = 'search'; diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V139__mcp_default_read_timeout_60s.sql b/mateclaw-server/src/main/resources/db/migration/h2/V139__mcp_default_read_timeout_60s.sql new file mode 100644 index 00000000..541bc6dc --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V139__mcp_default_read_timeout_60s.sql @@ -0,0 +1,8 @@ +-- Raise the default per-request (read) timeout for MCP servers from 30s to 60s. +-- A 30s ceiling cut off MCP tools whose single callTool round-trip legitimately +-- runs longer (data-heavy or compute-heavy tools), surfacing as a request timeout +-- with no retry. The application layer already falls back to 60s when the column +-- is null; this aligns the schema default so the value is consistent everywhere. +-- Only changes the column default for newly inserted rows — existing rows keep +-- whatever value they were given. Idempotent. +ALTER TABLE mate_mcp_server ALTER COLUMN read_timeout_seconds SET DEFAULT 60; diff --git a/mateclaw-server/src/main/resources/db/migration/h2/V140__goal_criteria_checklist.sql b/mateclaw-server/src/main/resources/db/migration/h2/V140__goal_criteria_checklist.sql new file mode 100644 index 00000000..1999e67d --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/h2/V140__goal_criteria_checklist.sql @@ -0,0 +1,8 @@ +-- V140: Structured, checkable criteria for goals (H2). +-- +-- Adds a nullable JSON-text column holding the goal's checklist: +-- [{ "id": "C1", "text": "...", "passed": false, "evidence": "" }, ...] +-- Completion is derived from "all criteria passed" rather than a fuzzy +-- completion_score threshold. The column is additive and nullable, so +-- existing goals load unchanged (a NULL list bootstraps on first evaluation). +ALTER TABLE mate_agent_goal ADD COLUMN IF NOT EXISTS criteria CLOB; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V125__agent_workspace_base_path.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V125__agent_workspace_base_path.sql new file mode 100644 index 00000000..0e77dd4b --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V125__agent_workspace_base_path.sql @@ -0,0 +1,12 @@ +-- V125: Add workspace_base_path column to mate_agent for Agent-level directory override. +-- Idempotent: checks INFORMATION_SCHEMA before ADD COLUMN. +SET @col_exists := ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'mate_agent' + AND COLUMN_NAME = 'workspace_base_path' +); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_agent ADD COLUMN workspace_base_path VARCHAR(512) DEFAULT NULL', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V126__agent_binding_disabled_flags.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V126__agent_binding_disabled_flags.sql new file mode 100644 index 00000000..0c07b716 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V126__agent_binding_disabled_flags.sql @@ -0,0 +1,33 @@ +-- V126: Two binding-mode flags on mate_agent (MySQL). +-- +-- skills_disabled / tools_disabled flip the "zero binding rows" semantic from +-- "inherit every globally-enabled capability" to "this agent has explicitly +-- opted out". Without these columns, an operator who wanted an agent with no +-- skills had to bind a dummy skill — otherwise the runtime fell back to the +-- global default and every skill's catalog entry got injected into the system +-- prompt (issue #184). +-- +-- Idempotent: INFORMATION_SCHEMA guard for each column, since MySQL does not +-- support `ADD COLUMN IF NOT EXISTS`. + +SET @col_exists := ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'mate_agent' + AND COLUMN_NAME = 'skills_disabled' +); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_agent ADD COLUMN skills_disabled TINYINT(1) NOT NULL DEFAULT 0', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @col_exists := ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'mate_agent' + AND COLUMN_NAME = 'tools_disabled' +); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_agent ADD COLUMN tools_disabled TINYINT(1) NOT NULL DEFAULT 0', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V127__approval_auto_grant.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V127__approval_auto_grant.sql new file mode 100644 index 00000000..35bb0e1c --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V127__approval_auto_grant.sql @@ -0,0 +1,25 @@ +-- V127: Approval auto-grant table (MySQL dialect). +-- Idempotent: outer CREATE TABLE uses IF NOT EXISTS; inline KEY clauses +-- only execute on first creation, so re-running this migration is safe. +CREATE TABLE IF NOT EXISTS mate_approval_grant ( + id BIGINT NOT NULL PRIMARY KEY, + workspace_id BIGINT NOT NULL, + scope_type VARCHAR(32) NOT NULL, + scope_id VARCHAR(64) NOT NULL, + tool_name VARCHAR(128) DEFAULT NULL, + rule_id VARCHAR(128) DEFAULT NULL, + max_severity VARCHAR(16) NOT NULL, + grant_kind VARCHAR(24) NOT NULL, + expire_at DATETIME DEFAULT NULL, + granted_by BIGINT NOT NULL, + granted_at DATETIME NOT NULL, + revoked TINYINT NOT NULL DEFAULT 0, + revoked_by BIGINT DEFAULT NULL, + revoked_at DATETIME DEFAULT NULL, + note VARCHAR(500) DEFAULT NULL, + create_time DATETIME NOT NULL, + update_time DATETIME NOT NULL, + deleted TINYINT NOT NULL DEFAULT 0, + KEY idx_grant_scope (workspace_id, scope_type, scope_id, tool_name, revoked, deleted), + KEY idx_grant_expire (expire_at, revoked, deleted) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V128__approval_resolution_log.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V128__approval_resolution_log.sql new file mode 100644 index 00000000..8effe749 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V128__approval_resolution_log.sql @@ -0,0 +1,25 @@ +-- V128: Approval resolution log table (MySQL dialect). +CREATE TABLE IF NOT EXISTS mate_approval_resolution_log ( + id BIGINT NOT NULL PRIMARY KEY, + -- Nullable: HARD_BLOCK can fire before workspace resolution; see H2 migration + -- for full rationale. Per-workspace Dashboard queries filter on workspace_id + -- and skip null rows; the global HARD_BLOCK panel surfaces them. + workspace_id BIGINT DEFAULT NULL, + conversation_id VARCHAR(128) DEFAULT NULL, + agent_id VARCHAR(64) DEFAULT NULL, + user_id VARCHAR(64) DEFAULT NULL, + tool_call_id VARCHAR(64) DEFAULT NULL, + tool_name VARCHAR(128) NOT NULL, + max_severity VARCHAR(16) DEFAULT NULL, + rule_ids VARCHAR(512) DEFAULT NULL, + decision_source VARCHAR(24) NOT NULL, + grant_id BIGINT DEFAULT NULL, + pending_id VARCHAR(32) DEFAULT NULL, + args_preview VARCHAR(500) DEFAULT NULL, + note VARCHAR(500) DEFAULT NULL, + create_time DATETIME NOT NULL, + deleted TINYINT NOT NULL DEFAULT 0, + KEY idx_resolution_workspace_time (workspace_id, create_time), + KEY idx_resolution_grant (grant_id), + KEY idx_resolution_pending (pending_id) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V129__wiki_page_broken_links.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V129__wiki_page_broken_links.sql new file mode 100644 index 00000000..c9d2dcc6 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V129__wiki_page_broken_links.sql @@ -0,0 +1,27 @@ +-- V129: Persisted wikilink lint state — MySQL dialect. +-- +-- See h2/V129__wiki_page_broken_links.sql for column semantics. The MySQL +-- variant needs INFORMATION_SCHEMA guards because MySQL doesn't support +-- ADD COLUMN IF NOT EXISTS prior to 8.0.29 and the deploy targets older +-- supported versions. +SET @col_exists := ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'broken_links' +); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN broken_links JSON DEFAULT NULL COMMENT ''Outlink targets present in content but not in this KB''', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @col_exists := ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'broken_links_scanned_at' +); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN broken_links_scanned_at DATETIME(3) DEFAULT NULL COMMENT ''Timestamp of last broken_links recompute''', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V130__agent_primary_kb.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V130__agent_primary_kb.sql new file mode 100644 index 00000000..e08fa00e --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V130__agent_primary_kb.sql @@ -0,0 +1,45 @@ +-- V129: Store the per-agent primary wiki KB on mate_agent (MySQL). +-- +-- Knowledge bases remain workspace-shared; this field only chooses the +-- default KB for wiki tools when no kbName/kbId is specified. + +SET @col_exists := ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'mate_agent' + AND COLUMN_NAME = 'primary_kb_id' +); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_agent ADD COLUMN primary_kb_id BIGINT DEFAULT NULL', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @idx_exists := ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS + WHERE TABLE_SCHEMA = DATABASE() + AND TABLE_NAME = 'mate_agent' + AND INDEX_NAME = 'idx_agent_primary_kb' +); +SET @stmt := IF(@idx_exists = 0, + 'CREATE INDEX idx_agent_primary_kb ON mate_agent(primary_kb_id)', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +UPDATE mate_agent a +SET primary_kb_id = ( + SELECT kb.id + FROM mate_wiki_knowledge_base kb + WHERE kb.agent_id = a.id + AND (kb.workspace_id IS NULL OR kb.workspace_id = a.workspace_id) + AND kb.deleted = 0 + ORDER BY kb.update_time DESC + LIMIT 1 +) +WHERE a.primary_kb_id IS NULL + AND EXISTS ( + SELECT 1 + FROM mate_wiki_knowledge_base kb + WHERE kb.agent_id = a.id + AND (kb.workspace_id IS NULL OR kb.workspace_id = a.workspace_id) + AND kb.deleted = 0 + ); diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V131__claude_48_models.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V131__claude_48_models.sql new file mode 100644 index 00000000..4e8bc865 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V131__claude_48_models.sql @@ -0,0 +1,36 @@ +-- Add Claude Opus 4.8 (regular + -fast variant) model entries to +-- mate_model_config for existing deployments. New installs pick these up via +-- DatabaseBootstrapRunner from data-mysql-{en,zh}.sql; this migration covers +-- operators who already have earlier Flyway versions applied. +-- +-- Claude 4.8 inherits 4.7's strict API contract: temperature / top_p / top_k +-- must be NULL (otherwise HTTP 400), and the "xhigh" thinking tier is +-- available. Both are handled in AnthropicChatModelBuilder via the +-- isClaude47OrLater() detector. +-- +-- INSERT ... ON DUPLICATE KEY UPDATE is the MySQL idempotent upsert. +-- Same V number is used in h2/ for cross-dialect parity. + +INSERT INTO mate_model_config (id, name, provider, model_name, description, temperature, max_tokens, top_p, builtin, enabled, is_default, create_time, update_time, deleted) +VALUES +-- Direct Anthropic +(1000000290, 'Claude Opus 4.8', 'anthropic', 'claude-opus-4-8', 'Anthropic Claude Opus 4.8 (xhigh adaptive thinking)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000291, 'Claude Opus 4.8 Fast', 'anthropic', 'claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant (higher output speed, 2x pricing)', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- OpenRouter passthrough +(1000000292, 'Claude Opus 4.8', 'openrouter', 'anthropic/claude-opus-4-8', 'Claude Opus 4.8 via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +(1000000293, 'Claude Opus 4.8 Fast', 'openrouter', 'anthropic/claude-opus-4-8-fast', 'Claude Opus 4.8 fast variant via OpenRouter', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0), +-- Claude Code OAuth (Pro/Max subscription) +(1000000294, 'Claude Opus 4.8', 'anthropic-claude-code', 'claude-opus-4-8', 'Claude Opus 4.8 via Claude Code Pro/Max subscription', NULL, 4096, NULL, TRUE, TRUE, FALSE, NOW(), NOW(), 0) +ON DUPLICATE KEY UPDATE + name = VALUES(name), + provider = VALUES(provider), + model_name = VALUES(model_name), + description = VALUES(description), + temperature = VALUES(temperature), + max_tokens = VALUES(max_tokens), + top_p = VALUES(top_p), + builtin = VALUES(builtin), + enabled = VALUES(enabled), + is_default = VALUES(is_default), + update_time = VALUES(update_time), + deleted = VALUES(deleted); diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V132__memory_consolidation_cron_tier_discipline.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V132__memory_consolidation_cron_tier_discipline.sql new file mode 100644 index 00000000..dc961ad0 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V132__memory_consolidation_cron_tier_discipline.sql @@ -0,0 +1,13 @@ +-- Update the daily "memory consolidation" cron prompt on existing databases so it +-- keeps project-specific volatile facts (codenames, tech stacks, per-project +-- decisions) out of the always-on MEMORY.md. Seed scripts only run on fresh +-- installs, so existing rows need this data migration to pick up the new wording. +-- Scoped to the original default text so user-edited prompts are left untouched. + +UPDATE mate_cron_job +SET trigger_message = '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。注意：MEMORY.md 会被注入每一次对话，只整合跨项目长期稳定的信息；具体项目的代号、名称、技术栈、仓库、单项目的指标/预算/团队/上线日期或只对某个项目成立的决策等易变事实，不要写入 MEMORY.md（会随项目切换互相冲突、导致张冠李戴），应留在 daily note 或通过结构化 project 记忆维护。判定口诀：换一个项目后仍成立才进 MEMORY.md。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。' +WHERE trigger_message = '请回顾你最近的 memory/ 日记文件，将反复出现的重要信息（用户偏好、稳定事实、经验教训、工作流）提炼整合到 MEMORY.md 中。保留日记原文不动，只更新 MEMORY.md。完成后简要说明做了哪些整合。'; + +UPDATE mate_cron_job +SET trigger_message = 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Note: MEMORY.md is injected into every conversation, so only consolidate cross-project, long-term stable information; do NOT write project-specific volatile facts into MEMORY.md (project codenames, names, tech stacks, repos, a single project''s metrics/budget/team/launch date, or decisions that hold only for one project) — they conflict across projects and cause mix-ups. Keep those in the daily note or maintain them via structured project memory. Rule of thumb: only facts that still hold after switching projects belong in MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.' +WHERE trigger_message = 'Review your recent memory/ daily note files and consolidate recurring important information (user preferences, stable facts, lessons learned, workflows) into MEMORY.md. Keep the original daily notes intact, only update MEMORY.md. Briefly describe what consolidations were made.'; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V133__wiki_agent_page_type_permission.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V133__wiki_agent_page_type_permission.sql new file mode 100644 index 00000000..ebff5caf --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V133__wiki_agent_page_type_permission.sql @@ -0,0 +1,23 @@ +-- V133: Per-agent, per-KB, per-pageType permission for wiki tools. +-- Read permission filters retrieval/listing; write permission gates the +-- create/compile/delete/archive/enrich/transformation tools. A row with +-- page_type='*' is the agent's KB-wide default; an exact page_type row is +-- more specific and wins over '*'. Unconfigured (no rows) falls back to the +-- KB-level defaultReadPolicy stored in the KB config. + +CREATE TABLE IF NOT EXISTS mate_wiki_agent_page_type_permission ( + id BIGINT NOT NULL PRIMARY KEY, + agent_id BIGINT NOT NULL, + kb_id BIGINT NOT NULL, + page_type VARCHAR(64) NOT NULL, + can_read TINYINT NOT NULL DEFAULT 1, + can_create TINYINT NOT NULL DEFAULT 0, + can_update TINYINT NOT NULL DEFAULT 0, + can_delete TINYINT NOT NULL DEFAULT 0, + write_policy VARCHAR(32) NOT NULL DEFAULT 'approval_required', + create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + update_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + deleted INT NOT NULL DEFAULT 0, + UNIQUE KEY uk_wiki_agent_ptperm (agent_id, kb_id, page_type, deleted), + KEY idx_wiki_ptperm_agent_kb (agent_id, kb_id, deleted) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V134__wiki_page_type_profile.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V134__wiki_page_type_profile.sql new file mode 100644 index 00000000..f4f018ab --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V134__wiki_page_type_profile.sql @@ -0,0 +1,63 @@ +-- V134: KB-scoped pageType profile + structured page metadata columns. +-- See the H2 file for the design rationale. MySQL 8 uses a VIRTUAL generated +-- column for the "one enabled profile per KB" constraint, and an +-- INFORMATION_SCHEMA guard for each idempotent ADD COLUMN (MySQL has no +-- ADD COLUMN IF NOT EXISTS). + +CREATE TABLE IF NOT EXISTS mate_wiki_page_type_profile ( + id BIGINT NOT NULL, + kb_id BIGINT NOT NULL, + name VARCHAR(128) NOT NULL, + version INT NOT NULL DEFAULT 1, + config_json LONGTEXT NOT NULL, + enabled TINYINT(1) NOT NULL DEFAULT 1, + create_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + update_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + deleted INT NOT NULL DEFAULT 0, + -- Yields kb_id only for the live-enabled row; NULL otherwise. InnoDB + -- ignores NULL keys for uniqueness, giving "at most one enabled per KB". + enabled_kb BIGINT + GENERATED ALWAYS AS ( + CASE WHEN enabled = 1 AND deleted = 0 THEN kb_id ELSE NULL END + ) VIRTUAL, + PRIMARY KEY (id), + UNIQUE KEY uk_wiki_ptprofile_name (kb_id, name, deleted), + UNIQUE KEY uk_wiki_ptprofile_enabled (enabled_kb), + KEY idx_wiki_ptprofile_kb (kb_id, enabled, deleted) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; + +-- Structured page metadata columns (idempotent adds). +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'metadata_json'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN metadata_json LONGTEXT', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'metadata_validation_status'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN metadata_validation_status VARCHAR(32)', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'metadata_validation_json'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN metadata_validation_json LONGTEXT', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'template_key'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN template_key VARCHAR(128)', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'profile_version'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN profile_version INT', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V135__wiki_layered_knowledge.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V135__wiki_layered_knowledge.sql new file mode 100644 index 00000000..6c7ffb3c --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V135__wiki_layered_knowledge.sql @@ -0,0 +1,44 @@ +-- V135: Layered knowledge (fact / experience) + page dependency graph. +-- See the H2 file for rationale. MySQL uses INFORMATION_SCHEMA guards for the +-- idempotent column adds. + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'knowledge_layer'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN knowledge_layer VARCHAR(16)', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'depends_on_json'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN depends_on_json LONGTEXT', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'stale'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN stale TINYINT NOT NULL DEFAULT 0', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +SET @col_exists := (SELECT COUNT(*) FROM information_schema.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_wiki_page' + AND COLUMN_NAME = 'stale_reason_json'); +SET @ddl := IF(@col_exists = 0, + 'ALTER TABLE mate_wiki_page ADD COLUMN stale_reason_json LONGTEXT', 'SELECT 1'); +PREPARE stmt FROM @ddl; EXECUTE stmt; DEALLOCATE PREPARE stmt; + +CREATE TABLE IF NOT EXISTS mate_wiki_page_dependency ( + id BIGINT NOT NULL PRIMARY KEY, + kb_id BIGINT NOT NULL, + page_id BIGINT NOT NULL, + depends_on_page_id BIGINT NOT NULL, + dependency_type VARCHAR(32) NOT NULL DEFAULT 'fact', + create_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + update_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + deleted INT NOT NULL DEFAULT 0, + UNIQUE KEY uk_wiki_page_dep (page_id, depends_on_page_id, dependency_type, deleted), + KEY idx_wiki_page_dep_reverse (kb_id, depends_on_page_id, deleted) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V136__wiki_pipeline_runtime.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V136__wiki_pipeline_runtime.sql new file mode 100644 index 00000000..eb32f1fc --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V136__wiki_pipeline_runtime.sql @@ -0,0 +1,55 @@ +-- V136: Wiki pipeline runtime — definitions, runs, and per-step runs. +-- See the H2 file for design rationale. + +CREATE TABLE IF NOT EXISTS mate_wiki_pipeline_definition ( + id BIGINT NOT NULL PRIMARY KEY, + kb_id BIGINT NOT NULL, + name VARCHAR(128) NOT NULL, + owner_agent_id BIGINT NOT NULL, + trigger_type VARCHAR(32) NOT NULL, + trigger_config_json LONGTEXT, + steps_json LONGTEXT NOT NULL, + dedup_window_seconds INT NOT NULL DEFAULT 0, + enabled TINYINT NOT NULL DEFAULT 1, + create_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + update_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + deleted INT NOT NULL DEFAULT 0, + UNIQUE KEY uk_wiki_pipeline_def_name (kb_id, name, deleted), + KEY idx_wiki_pipeline_def_trigger (kb_id, trigger_type, enabled, deleted) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; + +CREATE TABLE IF NOT EXISTS mate_wiki_pipeline_run ( + id BIGINT NOT NULL PRIMARY KEY, + definition_id BIGINT NOT NULL, + kb_id BIGINT NOT NULL, + status VARCHAR(16) NOT NULL, + trigger_type VARCHAR(32) NOT NULL, + trigger_subject VARCHAR(128) NOT NULL, + trigger_bucket VARCHAR(64) NOT NULL, + trigger_payload_json LONGTEXT, + input_json LONGTEXT, + output_json LONGTEXT, + error_message VARCHAR(2048), + started_at DATETIME(3), + finished_at DATETIME(3), + create_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + deleted INT NOT NULL DEFAULT 0, + UNIQUE KEY uk_wiki_pipeline_run_dedup (definition_id, trigger_type, trigger_subject, trigger_bucket, deleted), + KEY idx_wiki_pipeline_run_def (definition_id, status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; + +CREATE TABLE IF NOT EXISTS mate_wiki_pipeline_step_run ( + id BIGINT NOT NULL PRIMARY KEY, + run_id BIGINT NOT NULL, + step_id VARCHAR(128) NOT NULL, + executor VARCHAR(32) NOT NULL, + status VARCHAR(16) NOT NULL, + input_json LONGTEXT, + output_json LONGTEXT, + error_message VARCHAR(2048), + started_at DATETIME(3), + finished_at DATETIME(3), + create_time DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), + deleted INT NOT NULL DEFAULT 0, + KEY idx_wiki_pipeline_step_run (run_id, status) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V137__memory_owner_scope.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V137__memory_owner_scope.sql new file mode 100644 index 00000000..92ecf77e --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V137__memory_owner_scope.sql @@ -0,0 +1,109 @@ +-- V137: Per-owner memory isolation with a three-state visibility scope (MySQL). +-- +-- See the H2 counterpart for the full rationale. MySQL has no +-- "ADD COLUMN IF NOT EXISTS", so each column/index is guarded with an +-- INFORMATION_SCHEMA existence check + prepared statement for idempotency. +-- +-- Existing rows are backfilled to scope='TEAM' by the NOT NULL DEFAULT so that +-- upgrading does NOT hide previously-shared memory. + +-- ---------- mate_workspace_file ---------- +SET @col_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_workspace_file' AND COLUMN_NAME = 'owner_key'); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_workspace_file ADD COLUMN owner_key VARCHAR(128) NULL', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @col_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_workspace_file' AND COLUMN_NAME = 'scope'); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_workspace_file ADD COLUMN scope VARCHAR(16) NOT NULL DEFAULT ''TEAM''', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @idx_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_workspace_file' AND INDEX_NAME = 'idx_workspace_file_scope_owner'); +SET @stmt := IF(@idx_exists = 0, + 'CREATE INDEX idx_workspace_file_scope_owner ON mate_workspace_file(agent_id, scope, owner_key)', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +-- Shared rows use the '' sentinel (not NULL) so the unique index below treats +-- one shared row per filename as a single slot (NULLs are distinct in unique indexes). +UPDATE mate_workspace_file SET owner_key = '' WHERE owner_key IS NULL; + +-- De-duplicate before adding the unique index: the table never had a unique +-- constraint and the service layer was check-then-insert, so historical +-- duplicates may exist. Keep the most recently inserted row per +-- (agent_id, filename, owner_key); drop the rest. The extra derived-table wrap +-- is required so MySQL doesn't reject selecting from the table being deleted. +-- +-- IRREVERSIBLE: this keeps MAX(id) (newest row) and PERMANENTLY deletes the +-- other rows in a duplicate group — their content / enabled / sort_order are +-- not preserved or merged. Duplicates are NOT expected (every write path is +-- check-then-insert), so this is a safety net to guarantee the index builds, +-- not a routine merge. If a deployment knowingly relies on duplicate rows, +-- reconcile them manually before upgrading. +DELETE FROM mate_workspace_file +WHERE id NOT IN ( + SELECT keep_id FROM ( + SELECT MAX(id) AS keep_id + FROM mate_workspace_file + GROUP BY agent_id, filename, owner_key + ) t +); + +-- One row per (agent, filename, owner): one shared row + one row per PERSONAL +-- owner. Hardens the check-then-insert in saveFile/saveMemoryFile against +-- concurrent / multi-node duplicates. +SET @idx_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_workspace_file' AND INDEX_NAME = 'uk_workspace_file_owner'); +SET @stmt := IF(@idx_exists = 0, + 'CREATE UNIQUE INDEX uk_workspace_file_owner ON mate_workspace_file(agent_id, filename, owner_key)', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +-- ---------- mate_memory_recall ---------- +SET @col_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_memory_recall' AND COLUMN_NAME = 'owner_key'); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_memory_recall ADD COLUMN owner_key VARCHAR(128) NULL', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @col_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_memory_recall' AND COLUMN_NAME = 'scope'); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_memory_recall ADD COLUMN scope VARCHAR(16) NOT NULL DEFAULT ''TEAM''', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @idx_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_memory_recall' AND INDEX_NAME = 'idx_memory_recall_scope_owner'); +SET @stmt := IF(@idx_exists = 0, + 'CREATE INDEX idx_memory_recall_scope_owner ON mate_memory_recall(agent_id, scope, owner_key)', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +-- ---------- mate_fact ---------- +SET @col_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_fact' AND COLUMN_NAME = 'owner_key'); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_fact ADD COLUMN owner_key VARCHAR(128) NULL', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @col_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_fact' AND COLUMN_NAME = 'scope'); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_fact ADD COLUMN scope VARCHAR(16) NOT NULL DEFAULT ''TEAM''', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; + +SET @idx_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.STATISTICS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_fact' AND INDEX_NAME = 'idx_fact_scope_owner'); +SET @stmt := IF(@idx_exists = 0, + 'CREATE INDEX idx_fact_scope_owner ON mate_fact(agent_id, scope, owner_key)', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V138__rename_search_tool_to_web_search.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V138__rename_search_tool_to_web_search.sql new file mode 100644 index 00000000..835cf030 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V138__rename_search_tool_to_web_search.sql @@ -0,0 +1,7 @@ +-- Rename the built-in web-search tool from "search" to "web_search". +-- DashScope's native protocol reserves the function name "search" and rejects any +-- request that declares a tool with that name ("InvalidParameter: Tool names are not +-- allowed to be [search]"), which broke tool use for every qwen/DashScope-native model +-- that had this tool bound. Migrate existing agent bindings to the new name so they +-- keep resolving after the tool was renamed in code. Idempotent. +UPDATE mate_agent_tool SET tool_name = 'web_search' WHERE tool_name = 'search'; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V139__mcp_default_read_timeout_60s.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V139__mcp_default_read_timeout_60s.sql new file mode 100644 index 00000000..541bc6dc --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V139__mcp_default_read_timeout_60s.sql @@ -0,0 +1,8 @@ +-- Raise the default per-request (read) timeout for MCP servers from 30s to 60s. +-- A 30s ceiling cut off MCP tools whose single callTool round-trip legitimately +-- runs longer (data-heavy or compute-heavy tools), surfacing as a request timeout +-- with no retry. The application layer already falls back to 60s when the column +-- is null; this aligns the schema default so the value is consistent everywhere. +-- Only changes the column default for newly inserted rows — existing rows keep +-- whatever value they were given. Idempotent. +ALTER TABLE mate_mcp_server ALTER COLUMN read_timeout_seconds SET DEFAULT 60; diff --git a/mateclaw-server/src/main/resources/db/migration/mysql/V140__goal_criteria_checklist.sql b/mateclaw-server/src/main/resources/db/migration/mysql/V140__goal_criteria_checklist.sql new file mode 100644 index 00000000..1ddf1da2 --- /dev/null +++ b/mateclaw-server/src/main/resources/db/migration/mysql/V140__goal_criteria_checklist.sql @@ -0,0 +1,16 @@ +-- V140: Structured, checkable criteria for goals (MySQL). +-- +-- See the H2 counterpart for the full rationale. MySQL has no +-- "ADD COLUMN IF NOT EXISTS", so the column is guarded with an +-- INFORMATION_SCHEMA existence check + prepared statement for idempotency. +-- +-- The column holds the goal's checklist as JSON: +-- [{ "id": "C1", "text": "...", "passed": false, "evidence": "" }, ...] +-- Additive and nullable, so existing goals load unchanged (a NULL list +-- bootstraps on first evaluation). +SET @col_exists := (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'mate_agent_goal' AND COLUMN_NAME = 'criteria'); +SET @stmt := IF(@col_exists = 0, + 'ALTER TABLE mate_agent_goal ADD COLUMN criteria JSON NULL', + 'SELECT 1'); +PREPARE s FROM @stmt; EXECUTE s; DEALLOCATE PREPARE s; diff --git a/mateclaw-server/src/main/resources/db/schema-mysql.sql b/mateclaw-server/src/main/resources/db/schema-mysql.sql index c00f11d0..7c864198 100644 --- a/mateclaw-server/src/main/resources/db/schema-mysql.sql +++ b/mateclaw-server/src/main/resources/db/schema-mysql.sql @@ -28,9 +28,11 @@ CREATE TABLE IF NOT EXISTS mate_agent ( icon VARCHAR(256), tags VARCHAR(256), workspace_id BIGINT NOT NULL DEFAULT 1, + primary_kb_id BIGINT DEFAULT NULL, create_time DATETIME NOT NULL, update_time DATETIME NOT NULL, - deleted INT NOT NULL DEFAULT 0 + deleted INT NOT NULL DEFAULT 0, + INDEX idx_agent_primary_kb (primary_kb_id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci; -- 模型配置表 diff --git a/mateclaw-server/src/main/resources/db/schema.sql b/mateclaw-server/src/main/resources/db/schema.sql index 664c80c0..5b8b277f 100644 --- a/mateclaw-server/src/main/resources/db/schema.sql +++ b/mateclaw-server/src/main/resources/db/schema.sql @@ -30,10 +30,12 @@ CREATE TABLE IF NOT EXISTS mate_agent ( tags VARCHAR(256), workspace_id BIGINT NOT NULL DEFAULT 1, default_thinking_level VARCHAR(32) DEFAULT NULL, + primary_kb_id BIGINT DEFAULT NULL, create_time DATETIME NOT NULL, update_time DATETIME NOT NULL, deleted INT NOT NULL DEFAULT 0 ); +CREATE INDEX IF NOT EXISTS idx_agent_primary_kb ON mate_agent(primary_kb_id); -- 模型配置表 CREATE TABLE IF NOT EXISTS mate_model_config ( diff --git a/mateclaw-server/src/main/resources/docs/en/agents.md b/mateclaw-server/src/main/resources/docs/en/agents.md index 93f847e4..f785ee94 100644 --- a/mateclaw-server/src/main/resources/docs/en/agents.md +++ b/mateclaw-server/src/main/resources/docs/en/agents.md @@ -215,6 +215,41 @@ UI: `Agents → pick employee → Tools`. Implementation details: see [MCP](./mcp#per-agent-tool-binding). +### Knowledge base binding (per-agent primary KB) + +::: tip New in 1.5.0 +The employee editor has a new "Knowledge Base" tab where you can pick a **primary KB** for each employee. Knowledge bases stay workspace-shared — binding only declares "this is the one I default to," it doesn't restrict other employees' access. +::: + +**Short version: each employee can pick one knowledge base as their "primary KB" — the default they query. Or pick none.** + +The model (worth reading once so it doesn't surprise you later): + +- **Knowledge bases are workspace-shared.** A KB belongs to the workspace it was created in; every employee in that workspace can see it. Binding a KB to an employee does **not** make it exclusive — other employees can still use it +- **The "primary KB" is just a default.** It tells the wiki tools (`wiki_search` / `wiki_read` / `wiki_backlinks` / ...): "when the caller doesn't specify `kbName` / `kbId`, use this one" +- **Multiple employees can pick the same KB as primary.** They don't interfere — each one's binding is its own, the KB itself isn't mutated +- **Not binding is fine.** With no primary set, the runtime falls back to the most-recently-updated KB in the workspace + +UI: `Employees → pick employee → Edit → Knowledge Base`. + +| Option | Behavior | +|--------|----------| +| **🚫 No primary KB** | Clear the binding; the next time the employee's wiki tools omit `kbName`, the runtime falls back to the workspace's most-recently-active KB | +| **📚 <KB name>** | Set this KB as primary; wiki tools default to it. The row also shows the KB's page count | + +Each row shows: icon, name, description, page count. The list is the **full set** of KBs in the current workspace — including ones already picked as primary by other employees. + +#### How the runtime decides "which KB to read" + +When an employee invokes a wiki tool, the resolution order is: + +1. The tool call explicitly carried `kbName` / `kbId` — use that +2. No explicit target → check the employee's `primaryKbId`; if it points to a workspace-visible KB, use that +3. No `primaryKbId` either → pick the most-recently-updated KB from the workspace's visible set +4. The workspace has zero KBs → tool returns empty, the LLM decides what to do next + +Migration note: early versions persisted the binding on `mate_wiki_knowledge_base.agent_id` (one-to-one, exclusive semantics). Starting with the V130 migration, every legacy `kb.agent_id` is backfilled into the corresponding `agent.primary_kb_id`; the old column stays around as a read-only fallback, but new writes only touch `agent.primary_kb_id`. If you relied on `kb.agent_id` to isolate a KB to a specific agent, revisit those bindings in the editor — KBs are now visible to every employee in the workspace. + ### System prompt best practices The system prompt is the employee's voice, priorities, and constraints. **Role / Goal / Backstory**, skill instructions, and workspace memory all get automatically appended to the final prompt — you don't write those yourself. diff --git a/mateclaw-server/src/main/resources/docs/en/ambient-ai.md b/mateclaw-server/src/main/resources/docs/en/ambient-ai.md index 891e2fa0..a9459bc3 100644 --- a/mateclaw-server/src/main/resources/docs/en/ambient-ai.md +++ b/mateclaw-server/src/main/resources/docs/en/ambient-ai.md @@ -153,11 +153,15 @@ curl http://localhost:18088/api/v1/cron-jobs \ -H "Authorization: Bearer " # Run once now (doesn't affect the next scheduled run) -curl -X POST http://localhost:18088/api/v1/cron-jobs/{id}/run-now \ +curl -X POST http://localhost:18088/api/v1/cron-jobs/{id}/run \ -H "Authorization: Bearer " -# View execution history -curl http://localhost:18088/api/v1/cron-jobs/{id}/runs \ +# View execution history for one cron job +curl http://localhost:18088/api/v1/dashboard/cron-runs/{id} \ + -H "Authorization: Bearer " + +# View recent execution history in the current workspace +curl http://localhost:18088/api/v1/dashboard/cron-runs \ -H "Authorization: Bearer " ``` diff --git a/mateclaw-server/src/main/resources/docs/en/api.md b/mateclaw-server/src/main/resources/docs/en/api.md index 8bd22fad..e3e01bf6 100644 --- a/mateclaw-server/src/main/resources/docs/en/api.md +++ b/mateclaw-server/src/main/resources/docs/en/api.md @@ -1,35 +1,42 @@ # API Reference -Every REST endpoint is prefixed `/api/v1/`. Every response follows the same envelope: +This page is source-aligned with the Spring MVC controllers under `mateclaw-server/src/main/java`. The route inventory below was rebuilt from controller annotations; when it conflicts with an older feature page, this page and the source code are the contract. + +## Contract + +All application REST endpoints use the `/api/v1` prefix unless explicitly noted. Most JSON responses use the project envelope: ```json { "code": 200, - "message": "success", - "data": { } + "msg": "success", + "data": {} } ``` -Every endpoint except `/api/v1/auth/login` requires a JWT in the `Authorization` header: +Important exceptions: -``` -Authorization: Bearer -``` +- Streaming endpoints (`text/event-stream`) send SSE frames instead of the JSON envelope. +- Download endpoints such as `/api/v1/files/generated/{id}`, chat uploads, and wiki raw downloads return bytes or `ResponseEntity` bodies. +- A few conflict/error flows may return a small structured object outside `R` when the client must branch on the HTTP status. -For deep behavior, read the feature page — [Chat & Messaging](./chat), [Agents](./agents), [Tools](./tools), [Security & Approval](./security), [LLM Wiki](./wiki), [Multimodal](./multimodal), [Memory](./memory), [Channels](./channels), [Models](./models), [Workspaces](./workspaces), [Goals](./goals), [Doctor](./doctor). - ---- +IDs are Snowflake `Long` values serialized as JSON strings by the backend. Frontends and third-party clients should keep IDs as strings. ## Authentication -``` -POST /api/v1/auth/login # Login, get JWT -GET /api/v1/users/me # Current user profile -PUT /api/v1/users/me # Update profile -PUT /api/v1/users/me/password # Change password +`POST /api/v1/auth/login` returns the JWT. Send protected requests with: + +```text +Authorization: Bearer ``` -**Login example:** +Public routes from `SecurityConfig` include login, first-run setup, webhook/webchat callbacks, chat stream/stop routes, agent stream route, talk WebSocket, `GET /api/v1/settings/language`, and `/api/v1/files/generated/**` one-time generated-file downloads. Role annotations such as `@RequireWorkspaceRole` and `@RequireGlobalAdmin` still apply after authentication. + +Workspace-scoped APIs usually accept `X-Workspace-Id`. If omitted, many handlers fall back to workspace `1` for desktop/local compatibility. + +## Frequently Used APIs + +### Login ```bash curl -X POST http://localhost:18088/api/v1/auth/login \ @@ -37,513 +44,640 @@ curl -X POST http://localhost:18088/api/v1/auth/login \ -d '{"username":"admin","password":"admin123"}' ``` -Response: - -```json -{ - "code": 200, - "data": { - "token": "eyJhbGciOiJIUzI1NiJ9...", - "tokenType": "Bearer", - "expiresIn": 86400 - } -} -``` - ---- - -## Chat - -``` -POST /api/v1/chat/{agentId}/message # Send a message -GET /api/v1/chat/{agentId}/stream?conversationId= # SSE streaming -POST /api/v1/chat/{conversationId}/stop # Stop an in-flight stream -GET /api/v1/chat/{conversationId}/pending-approvals # List waiting approvals -``` - -**Send message:** +### Chat ```bash -curl -X POST http://localhost:18088/api/v1/chat/1/message \ - -H "Authorization: Bearer YOUR_TOKEN" \ +curl -N -X POST http://localhost:18088/api/v1/chat/stream \ + -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"content":"Hello, what can you do?", "conversationId":"conv-abc123"}' + -H "Accept: text/event-stream" \ + -d '{"agentId":"1","message":"Hello","conversationId":"conv-abc123"}' ``` -**SSE stream example:** +Use `fetch()` with a streaming reader for `/chat/stream`; browser `EventSource` cannot send POST bodies. -```bash -curl -N http://localhost:18088/api/v1/chat/1/stream?conversationId=conv-abc123 \ - -H "Authorization: Bearer YOUR_TOKEN" -``` +### Tool Approval -Event types and schema are documented in [Chat & Messaging](./chat). +There is no `POST /api/v1/approvals/{id}/resolve` REST endpoint. Web approval and denial go through the chat stream by sending `/approve` or `/deny` in the waiting conversation. Read-only hydration remains `GET /api/v1/chat/{conversationId}/pending-approvals`. Auto-approval policies are managed under `/api/v1/approval/grants`. + +### Doctor / Health + +The current backend health surface is `GET /api/v1/system/health`. The old `/api/v1/doctor/*` endpoints are not implemented in the current source tree. + +### Multimodal Generation + +Image, video, music, and 3D generation are agent tools (`image_generate`, `video_generate`, `music_generate`, `model3d_generate`), not standalone `/api/v1/image`, `/api/v1/video`, or `/api/v1/music` REST controllers. REST surfaces that do exist here are TTS/STT and generated-file download. + +### Non-REST Endpoint + +`/api/v1/talk/ws` is registered by `WebSocketConfig` for Talk Mode. It is intentionally listed in `SecurityConfig` as a public WebSocket route, but it is not counted in the controller route inventory below. + +## Source-Aligned Route Inventory + +Total routes extracted: 406. + +### Authentication + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/auth/login` | `Login` | +| `GET` | `/api/v1/auth/tokens` | `List my PATs (metadata only — plaintext is never returned after creation)` | +| `POST` | `/api/v1/auth/tokens` | `Mint a new PAT — returned plaintext is shown once and cannot be recovered` | +| `DELETE` | `/api/v1/auth/tokens/{id}` | `Revoke a PAT — soft-delete; further auth attempts with this token will fail` | +| `GET` | `/api/v1/auth/users` | `List Users` | +| `POST` | `/api/v1/auth/users` | `Create User` | +| `PUT` | `/api/v1/auth/users/{id}/password` | `Change Password` | + +### Chat + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/chat` | `Chat` | +| `GET` | `/api/v1/chat/files/{conversationId}/{storedName:.+}` | `Read Uploaded File` | +| `POST` | `/api/v1/chat/stream` | `Chat Stream` | +| `POST` | `/api/v1/chat/upload` | `Upload` | +| `POST` | `/api/v1/chat/{conversationId}/interrupt` | `Interrupt Stream` | +| `GET` | `/api/v1/chat/{conversationId}/pending-approvals` | `Get Pending Approvals` | +| `POST` | `/api/v1/chat/{conversationId}/stop` | `Stop Stream` | ### Conversations -``` -GET /api/v1/conversations # List (?page&size&agentId) -GET /api/v1/conversations/page?page=&size=&keyword= # Paginated sessions (with keyword search) -GET /api/v1/conversations/{id}/messages # Get messages -PUT /api/v1/conversations/{id}/model # Set the model used by this conversation -DELETE /api/v1/conversations/{id} # Delete -DELETE /api/v1/conversations/{id}/messages # Clear messages -GET /api/v1/conversations/{id}/status # Conversation status -``` - ---- - -## Agents - -``` -GET /api/v1/agents # List (paginated) -GET /api/v1/agents/{id} # Get -POST /api/v1/agents # Create -PUT /api/v1/agents/{id} # Update (partial) -DELETE /api/v1/agents/{id} # Soft delete - -GET /api/v1/agents/{id}/chat/stream?message=...&conversationId=... # Streaming chat - -GET /api/v1/agents/{id}/workspace/files # List files -GET /api/v1/agents/{id}/workspace/files/{filename} # Get content -PUT /api/v1/agents/{id}/workspace/files/{filename} # Write -DELETE /api/v1/agents/{id}/workspace/files/{filename} # Delete -GET /api/v1/agents/{id}/workspace/prompt-files # Which files are injected -PUT /api/v1/agents/{id}/workspace/prompt-files # Set prompt file list - -GET /api/v1/agents/{agentId}/workspace/memory/export # Export memory snapshot -POST /api/v1/agents/{agentId}/workspace/memory/import/preview # Preview import (no writes) -POST /api/v1/agents/{agentId}/workspace/memory/import # Import memory snapshot - -GET /api/v1/agents/templates # List templates -POST /api/v1/agents/templates/{id} # Create from template -``` - ---- - -## Tools - -``` -GET /api/v1/tools # List -PUT /api/v1/tools/{id} # Update -PUT /api/v1/tools/{id}/toggle?enabled={bool} # Toggle -PUT /api/v1/tools/{id}/disclosure-tier # Set disclosure tier (core / extension) -POST /api/v1/tools/{name}/test # Test directly -``` - ---- - -## Skills - -``` -GET /api/v1/skills # List (?type=builtin|custom|mcp&tag=...) -GET /api/v1/skills/{id} # Get -POST /api/v1/skills # Create -PUT /api/v1/skills/{id} # Update -DELETE /api/v1/skills/{id} # Delete -PUT /api/v1/skills/{id}/toggle?enabled={bool} # Toggle -GET /api/v1/skills/runtime/active # Currently active skills -GET /api/v1/skills/runtime/status # Runtime status -POST /api/v1/skills/runtime/refresh # Reload runtime -``` - ---- - -## MCP Servers - -``` -GET /api/v1/mcp/servers # List -GET /api/v1/mcp/servers/{id} # Get -POST /api/v1/mcp/servers # Create -PUT /api/v1/mcp/servers/{id} # Update (PATCH semantics) -DELETE /api/v1/mcp/servers/{id} # Delete -PUT /api/v1/mcp/servers/{id}/toggle?enabled={bool} # Toggle -POST /api/v1/mcp/servers/{id}/test # Test connection -POST /api/v1/mcp/servers/refresh # Refresh all -``` - -See [MCP](./mcp) for body schemas and examples. - ---- - -## LLM Wiki - -``` -GET /api/v1/wiki/kbs # List knowledge bases -POST /api/v1/wiki/kbs # Create KB -GET /api/v1/wiki/kbs/{id} # Get KB detail -PUT /api/v1/wiki/kbs/{id} # Update KB -DELETE /api/v1/wiki/kbs/{id} # Delete KB - -POST /api/v1/wiki/kbs/{kbId}/raw # Upload raw material -GET /api/v1/wiki/kbs/{kbId}/raw # List raw materials -DELETE /api/v1/wiki/raw/{id} # Delete raw material -POST /api/v1/wiki/raw/{id}/reprocess # Re-digest - -GET /api/v1/wiki/kbs/{kbId}/pages # List pages -GET /api/v1/wiki/pages/{id} # Get page -PUT /api/v1/wiki/pages/{id} # Edit page -DELETE /api/v1/wiki/pages/{id} # Delete page -POST /api/v1/wiki/pages/{id}/lock # Lock page -POST /api/v1/wiki/pages/{id}/unlock # Unlock page - -GET /api/v1/wiki/kbs/{kbId}/search?q=... # Full-text search -GET /api/v1/wiki/pages/{id}/backlinks # Backlinks -``` - -Agent-callable wiki tools (`wiki_search`, `wiki_read`, `wiki_backlinks`) resolve `kbId` automatically. - ---- - -## Multimodal - -``` -POST /api/v1/image/generate # Generate image -POST /api/v1/image/edit # Edit image -POST /api/v1/video/generate # Generate video -POST /api/v1/video/from-image # Image-to-video -POST /api/v1/music/generate # Generate music -POST /api/v1/tts/synthesize # Text-to-speech -POST /api/v1/stt/transcribe # Speech-to-text - -GET /api/v1/image/jobs/{id} # Async image job status -GET /api/v1/video/jobs/{id} # Async video job status -``` - -See [Multimodal](./multimodal). - ---- - -## Memory - -``` -POST /api/v1/memory/{agentId}/emergence # Manually trigger consolidation -POST /api/v1/memory/{agentId}/summarize/{conversationId} # Trigger extraction -GET /api/v1/memory/{agentId}/dreaming/status # Last/next run + latest DREAMS.md entry -``` - ---- - -## Security & Approval - -### Tool Guard rules - -``` -GET /api/v1/security/guard/config # Global config -PUT /api/v1/security/guard/config # Update global config -GET /api/v1/security/guard/rules # List custom rules -GET /api/v1/security/guard/rules/builtin # List builtin rules -POST /api/v1/security/guard/rules # Create rule -PUT /api/v1/security/guard/rules/{id} # Update rule -DELETE /api/v1/security/guard/rules/{id} # Delete rule -PUT /api/v1/security/guard/rules/{id}/toggle?enabled={bool} # Toggle rule -``` - -### File Guard - -``` -GET /api/v1/security/guard/config/file-guard # Get config -PUT /api/v1/security/guard/config/file-guard # Update config -``` - -### Approvals - -``` -GET /api/v1/approvals?status=pending # List pending approvals -POST /api/v1/approvals/{id}/resolve # Approve or reject -``` - -Body: - -```json -{ "decision": "approved" } -``` - -or - -```json -{ "decision": "rejected", "notes": "Reason" } -``` - -### Audit log - -``` -GET /api/v1/security/audit/logs # Query (?toolName, ?decision, ?from, ?to) -GET /api/v1/security/audit/stats # Stats -GET /api/v1/audit/events # Full audit event query -``` - ---- - -## Models - -``` -GET /api/v1/models # List models -GET /api/v1/models/enabled # Enabled only -GET /api/v1/models/default # Default model -GET /api/v1/models/active # Active model -PUT /api/v1/models/active # Set active -POST /api/v1/models # Create model config -PUT /api/v1/models/{id} # Update -DELETE /api/v1/models/{id} # Delete -POST /api/v1/models/{id}/default # Set as default - -PUT /api/v1/models/{providerId}/config # Update provider config -POST /api/v1/models/custom-providers # Create custom provider -DELETE /api/v1/models/custom-providers/{providerId} # Delete custom provider - -POST /api/v1/models/{providerId}/models # Add model to provider -DELETE /api/v1/models/{providerId}/models/{modelId} # Remove model - -POST /api/v1/models/{providerId}/discover # Discover models -POST /api/v1/models/{providerId}/discover/apply # Apply discovered -POST /api/v1/models/{providerId}/test-connection # Test provider -POST /api/v1/models/{providerId}/models/{modelId}/test # Test a single model -``` - -### Legacy endpoints - -``` -GET /api/v1/model-providers # Legacy — prefer /api/v1/models -POST /api/v1/model-providers -PUT /api/v1/model-providers/{id} -DELETE /api/v1/model-providers/{id} - -GET /api/v1/model-configs # Legacy — prefer /api/v1/models -POST /api/v1/model-configs -PUT /api/v1/model-configs/{id} -DELETE /api/v1/model-configs/{id} -``` - ---- - -## Channels - -``` -GET /api/v1/channels # List -POST /api/v1/channels # Create -PUT /api/v1/channels/{id} # Update -DELETE /api/v1/channels/{id} # Delete -PUT /api/v1/channels/{id}/toggle?enabled={bool} # Toggle -GET /api/v1/channels/status # Per-channel connection status -GET /api/v1/channels/health # Aggregate health view - -GET /api/v1/channels/webhook/weixin/qrcode # WeChat iLink QR code -GET /api/v1/channels/webhook/weixin/qrcode/status # QR scan status - -POST /api/v1/channels/qrcode/qq/begin # Begin QQ scan-to-bind -GET /api/v1/channels/qrcode/qq/status # QQ scan-to-bind status -``` - -### Channel webhook callbacks - -| Channel | Callback URL | -|---------|--------------| -| DingTalk | `POST /api/v1/channels/webhook/dingtalk` | -| Feishu | `POST /api/v1/channels/webhook/feishu` | -| WeCom | `POST /api/v1/channels/webhook/wecom` | -| Telegram | `POST /api/v1/channels/webhook/telegram` | -| Discord | *(Gateway — no webhook)* | -| QQ | `POST /api/v1/channels/webhook/qq` | -| Slack | `POST /api/v1/channels/webhook/slack` | -| WeChat Personal | `POST /api/v1/channels/webhook/weixin` | - ---- - -## Cron jobs - -``` -GET /api/v1/cron-jobs # List -POST /api/v1/cron-jobs # Create -PUT /api/v1/cron-jobs/{id} # Update -DELETE /api/v1/cron-jobs/{id} # Delete -PUT /api/v1/cron-jobs/{id}/toggle?enabled={bool} # Toggle -POST /api/v1/cron-jobs/{id}/run # Run immediately -``` - ---- - -## Workflows (1.3.0+) - -Full field reference, step modes, and Pebble syntax in [Workflow](./workflow). - -``` -GET /api/v1/workflows # List -GET /api/v1/workflows/{id} # Fetch (published revision + draft) -POST /api/v1/workflows # Create -PUT /api/v1/workflows/{id}/draft # Save draft (graph_json) -POST /api/v1/workflows/{id}/publish # Publish draft as a new revision -DELETE /api/v1/workflows/{id} # Delete - -POST /api/v1/workflows/draft/generate # Natural-language → graph_json draft -POST /api/v1/workflows/{id}/preview-compile # Static checks + Pebble validation, no publish - -POST /api/v1/workflows/{id}/runs # Start a run (async) -GET /api/v1/workflows/{id}/runs # Run list -GET /api/v1/workflows/runs/{runId} # Run detail + per-step input/output/tokens/duration -POST /api/v1/workflows/runs/{runId}/resume # Resume after await_approval -POST /api/v1/workflows/runs/{runId}/cancel # Cancel in-flight -``` - ---- - -## Triggers (1.3.0+) - -Six pattern types, event governance, cross-instance consistency in [Triggers](./triggers). - -``` -GET /api/v1/triggers # List -GET /api/v1/triggers/{id} # Fetch -POST /api/v1/triggers # Create -PUT /api/v1/triggers/{id} # Update -DELETE /api/v1/triggers/{id} # Delete -PUT /api/v1/triggers/{id}/toggle?enabled={bool} # Toggle - -POST /api/v1/triggers/events # Generic event ingress (webhook / external bridge) - # ACKs 200 immediately, dispatches asynchronously -GET /api/v1/triggers/{id}/events # Event history for this trigger -``` - ---- - -## Goals (1.4.0+) - -Goal-completion scoring and auto-followup behavior in [Goals](./goals). - -``` -POST /api/v1/goals # Create goal -GET /api/v1/goals/{id} # Get goal -PATCH /api/v1/goals/{id} # Update goal (partial) -GET /api/v1/goals/{id}/events # Evaluation event history for this goal -``` - ---- - -## Token usage - -``` -GET /api/v1/token-usage?startDate=&endDate=&modelName=&providerId= -``` - ---- - -## System settings - -``` -GET /api/v1/settings # All settings -PUT /api/v1/settings # Update multiple -GET /api/v1/settings/language # Current language -PUT /api/v1/settings/language # Update language -PUT /api/v1/settings/{key} # Update a single key -``` - ---- - -## Dashboard - -``` -GET /api/v1/dashboard/summary # Usage summary cards -GET /api/v1/dashboard/trends # Trend charts (?range=7d|30d|90d) -GET /api/v1/dashboard/top-agents # Top-used agents -GET /api/v1/dashboard/top-tools # Top-used tools -``` - ---- - -## Workspaces - -``` -GET /api/v1/workspaces # List -GET /api/v1/workspaces/{id} # Get -POST /api/v1/workspaces # Create -PUT /api/v1/workspaces/{id} # Update -DELETE /api/v1/workspaces/{id} # Delete (owner only) -GET /api/v1/workspaces/{id}/access # Caller's access info (see below) -``` - -### Members & RBAC (1.4.0+) - -`/access` returns the caller's effective permissions in the workspace; the frontend uses it to render routes and menus: - -```json -{ - "memberRole": "editor", - "isGlobalAdmin": false, - "effectiveRole": "editor", - "capabilities": ["workspace.read", "conversation.write", "..."] -} -``` - -``` -GET /api/v1/workspaces/{id}/members # List members -POST /api/v1/workspaces/{id}/members # Add member -PUT /api/v1/workspaces/{id}/members/{memberId} # Update member (role, etc.) -DELETE /api/v1/workspaces/{id}/members/{memberId} # Remove member -``` - ---- - -## Doctor (health check) - -``` -GET /api/v1/doctor/run # Run all checks -GET /api/v1/doctor/checks # Cached check results -``` - ---- - -## Error responses - -```json -{ - "code": 400, - "message": "Validation failed: name is required" -} -``` - -### Common status codes - -| Code | Meaning | -|------|---------| -| 200 | Success | -| 400 | Bad request — validation failed or missing params | -| 401 | Unauthorized — token missing, expired, or invalid | -| 403 | Forbidden — insufficient permissions | -| 404 | Not found | -| 500 | Internal server error | - ---- - -## Pagination - -List endpoints return a consistent shape: - -```json -{ - "code": 200, - "data": { - "records": [ ], - "total": 42, - "current": 1, - "size": 20, - "pages": 3 - } -} -``` - -| Field | Purpose | -|-------|---------| -| `records` | Array of items on the current page | -| `total` | Total items | -| `current` | Current page (1-based) | -| `size` | Items per page | -| `pages` | Total pages | - ---- - -## Next - -- [Quick Start](./quickstart) — get the server running -- [Security & Approval](./security) — JWT + approval flow -- [Chat & Messaging](./chat) — SSE event format -- [LLM Wiki](./wiki) — wiki endpoint behaviors +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/conversations` | `List` | +| `POST` | `/api/v1/conversations/batch-delete` | `Batch Delete` | +| `GET` | `/api/v1/conversations/page` | `Page` | +| `DELETE` | `/api/v1/conversations/{conversationId}` | `Delete` | +| `DELETE` | `/api/v1/conversations/{conversationId}/messages` | `Clear Messages` | +| `GET` | `/api/v1/conversations/{conversationId}/messages` | `List Messages` | +| `PUT` | `/api/v1/conversations/{conversationId}/model` | `Set Model` | +| `PUT` | `/api/v1/conversations/{conversationId}/pin` | `Set Pinned` | +| `GET` | `/api/v1/conversations/{conversationId}/status` | `Get Stream Status` | +| `PUT` | `/api/v1/conversations/{conversationId}/title` | `Rename` | + +### Agents + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/agents` | `List` | +| `POST` | `/api/v1/agents` | `Create` | +| `GET` | `/api/v1/agents/{agentId}/provider-preferences` | `List Provider Preferences` | +| `PUT` | `/api/v1/agents/{agentId}/provider-preferences` | `Set Provider Preferences` | +| `GET` | `/api/v1/agents/{agentId}/skills` | `List Skills` | +| `PUT` | `/api/v1/agents/{agentId}/skills` | `Set Skills` | +| `DELETE` | `/api/v1/agents/{agentId}/skills/{skillId}` | `Unbind Skill` | +| `POST` | `/api/v1/agents/{agentId}/skills/{skillId}` | `Bind Skill` | +| `GET` | `/api/v1/agents/{agentId}/tools` | `List Tools` | +| `PUT` | `/api/v1/agents/{agentId}/tools` | `Set Tools` | +| `GET` | `/api/v1/agents/{agentId}/workspace/files` | `List Files` | +| `DELETE` | `/api/v1/agents/{agentId}/workspace/files/**` | `Delete File` | +| `GET` | `/api/v1/agents/{agentId}/workspace/files/**` | `Get File` | +| `PUT` | `/api/v1/agents/{agentId}/workspace/files/**` | `Save File` | +| `GET` | `/api/v1/agents/{agentId}/workspace/memory/export` | `Export Memory` | +| `POST` | `/api/v1/agents/{agentId}/workspace/memory/import` | `Import Memory` | +| `POST` | `/api/v1/agents/{agentId}/workspace/memory/import/preview` | `Preview Import Memory` | +| `GET` | `/api/v1/agents/{agentId}/workspace/prompt-files` | `Get Prompt Files` | +| `PUT` | `/api/v1/agents/{agentId}/workspace/prompt-files` | `Set Prompt Files` | +| `DELETE` | `/api/v1/agents/{id}` | `Delete` | +| `GET` | `/api/v1/agents/{id}` | `Get` | +| `PUT` | `/api/v1/agents/{id}` | `Update` | +| `GET` | `/api/v1/agents/{id}/capabilities` | `Capabilities` | +| `POST` | `/api/v1/agents/{id}/chat` | `Chat` | +| `GET` | `/api/v1/agents/{id}/chat/stream` | `Chat Stream` | +| `POST` | `/api/v1/agents/{id}/execute` | `Execute` | +| `GET` | `/api/v1/agents/{id}/state` | `Get State` | + +### Agent Templates + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/templates` | `List` | +| `POST` | `/api/v1/templates/{id}/apply` | `Apply` | + +### Sub-agents + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/subagents/active` | `List active sub-agents in a conversation's delegation tree` | +| `POST` | `/api/v1/subagents/spawn-pause` | `Set sub-agent spawn-pause for a conversation` | +| `POST` | `/api/v1/subagents/{subagentId}/interrupt` | `Interrupt a running sub-agent` | + +### Admin Runtime + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/admin/agent-runtime/runs/{conversationId}/recycle` | `Force recycle — dispose flux + drop RunState; use after friendly stop ignored` | +| `POST` | `/api/v1/admin/agent-runtime/runs/{conversationId}/stop` | `Friendly stop — request the run to wind down at its next checkpoint` | +| `GET` | `/api/v1/admin/agent-runtime/snapshot` | `Snapshot of every in-flight agent turn` | +| `POST` | `/api/v1/admin/agent-runtime/subagents/{subagentId}/interrupt` | `Interrupt one sub-agent (admin override of ownership check)` | +| `POST` | `/api/v1/admin/agent-runtime/sweep` | `Recycle every run currently flagged as stuck` | + +### Approval Grants + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/approval/grants` | `List` | +| `POST` | `/api/v1/approval/grants` | `Create` | +| `GET` | `/api/v1/approval/grants/active` | `Active Summary` | +| `DELETE` | `/api/v1/approval/grants/{id}` | `Revoke` | +| `GET` | `/api/v1/approval/resolutions` | `List Resolutions` | + +### Security and Tool Guard + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/security/approvals` | `List Approvals` | +| `GET` | `/api/v1/security/audit/logs` | `List Audit Logs` | +| `GET` | `/api/v1/security/audit/stats` | `Get Audit Stats` | +| `GET` | `/api/v1/security/guard/config` | `Get Guard Config` | +| `PUT` | `/api/v1/security/guard/config` | `Update Guard Config` | +| `GET` | `/api/v1/security/guard/config/file-guard` | `Get File Guard Config` | +| `PUT` | `/api/v1/security/guard/config/file-guard` | `Update File Guard Config` | +| `GET` | `/api/v1/security/guard/rules` | `List Rules` | +| `POST` | `/api/v1/security/guard/rules` | `Create Rule` | +| `GET` | `/api/v1/security/guard/rules/builtin` | `List Builtin Rules` | +| `DELETE` | `/api/v1/security/guard/rules/by-id/{id}` | `Delete Rule By Pk` | +| `GET` | `/api/v1/security/guard/rules/export` | `Export Rules` | +| `POST` | `/api/v1/security/guard/rules/import` | `Import Rules` | +| `DELETE` | `/api/v1/security/guard/rules/{ruleId}` | `Delete Rule` | +| `PUT` | `/api/v1/security/guard/rules/{ruleId}` | `Update Rule` | +| `PUT` | `/api/v1/security/guard/rules/{ruleId}/toggle` | `Toggle Rule` | + +### Audit + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/audit/events` | `List Events` | + +### Activity + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/activity/feed` | `Unified activity feed (audit + approval + tool calls)` | + +### Notifications + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/notifications/summary` | `Aggregated counts for the sidebar attention badges` | + +### Workspaces + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/workspaces` | `List` | +| `POST` | `/api/v1/workspaces` | `Create` | +| `DELETE` | `/api/v1/workspaces/{id}` | `Delete` | +| `GET` | `/api/v1/workspaces/{id}` | `Get` | +| `PUT` | `/api/v1/workspaces/{id}` | `Update` | +| `GET` | `/api/v1/workspaces/{id}/access` | `Get Access` | +| `GET` | `/api/v1/workspaces/{id}/members` | `List Members` | +| `POST` | `/api/v1/workspaces/{id}/members` | `Add Member` | +| `DELETE` | `/api/v1/workspaces/{id}/members/{targetUserId}` | `Remove Member` | +| `PUT` | `/api/v1/workspaces/{id}/members/{targetUserId}` | `Update Member Role` | + +### Settings + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/settings` | `Get Settings` | +| `PUT` | `/api/v1/settings` | `Save Settings` | +| `GET` | `/api/v1/settings/language` | `Get Language` | +| `PUT` | `/api/v1/settings/language` | `Save Language` | +| `PUT` | `/api/v1/settings/sidecar` | `Save Sidecar` | + +### First-run Setup + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/setup/init` | `Init` | +| `GET` | `/api/v1/setup/onboarding-status` | `Get Onboarding Status` | +| `GET` | `/api/v1/setup/status` | `Get Status` | + +### System Health + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/system/browser-health` | `Browser launch diagnostics` | +| `GET` | `/api/v1/system/health` | `System health check` | + +### Dashboard + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/dashboard/cron-runs` | `Recent Runs` | +| `GET` | `/api/v1/dashboard/cron-runs/{cronJobId}` | `Cron Job Runs` | +| `GET` | `/api/v1/dashboard/overview` | `Overview` | +| `GET` | `/api/v1/dashboard/trend` | `Trend` | + +### Token Usage + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/token-usage` | `Get Summary` | + +### Models + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/models` | `List` | +| `POST` | `/api/v1/models` | `Create` | +| `GET` | `/api/v1/models/active` | `Get Active Model` | +| `PUT` | `/api/v1/models/active` | `Set Active Model` | +| `GET` | `/api/v1/models/by-type` | `List By Type` | +| `GET` | `/api/v1/models/catalog` | `Catalog` | +| `DELETE` | `/api/v1/models/custom-providers` | `Delete Custom Provider By Query` | +| `POST` | `/api/v1/models/custom-providers` | `Create Custom Provider` | +| `DELETE` | `/api/v1/models/custom-providers/{providerId}` | `Delete Custom Provider` | +| `GET` | `/api/v1/models/default` | `Get Default Model` | +| `GET` | `/api/v1/models/embedding/default` | `Get Default Embedding` | +| `POST` | `/api/v1/models/embedding/default` | `Set Default Embedding` | +| `POST` | `/api/v1/models/embedding/{modelId}/test` | `Test Embedding` | +| `GET` | `/api/v1/models/enabled` | `List Enabled` | +| `DELETE` | `/api/v1/models/{id}` | `Delete` | +| `GET` | `/api/v1/models/{id}` | `Get` | +| `PUT` | `/api/v1/models/{id}` | `Update` | +| `POST` | `/api/v1/models/{id}/default` | `Set Default` | +| `PUT` | `/api/v1/models/{providerId}/config` | `Update Provider Config` | +| `POST` | `/api/v1/models/{providerId}/disable` | `Disable Provider` | +| `POST` | `/api/v1/models/{providerId}/discover` | `Discover Models` | +| `POST` | `/api/v1/models/{providerId}/discover/apply` | `Apply Discovered Models` | +| `POST` | `/api/v1/models/{providerId}/enable` | `Enable Provider` | +| `DELETE` | `/api/v1/models/{providerId}/models` | `Remove Provider Model` | +| `POST` | `/api/v1/models/{providerId}/models` | `Add Provider Model` | +| `POST` | `/api/v1/models/{providerId}/models/test` | `Test Model` | +| `POST` | `/api/v1/models/{providerId}/test-connection` | `Test Connection` | + +### OAuth + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/oauth/anthropic/reload` | `Force re-detect credentials and refresh if near expiry` | +| `GET` | `/api/v1/oauth/anthropic/status` | `Read current Claude Code OAuth credential status from local disk` | +| `GET` | `/api/v1/oauth/openai/authorize` | `Authorize` | +| `POST` | `/api/v1/oauth/openai/callback-paste` | `Callback Paste` | +| `POST` | `/api/v1/oauth/openai/device/cancel` | `Device flow: cancel a pending session` | +| `POST` | `/api/v1/oauth/openai/device/poll` | `Device flow: poll for completion` | +| `POST` | `/api/v1/oauth/openai/device/start` | `Device flow: start — request user_code` | +| `POST` | `/api/v1/oauth/openai/refresh` | `Refresh` | +| `DELETE` | `/api/v1/oauth/openai/revoke` | `Revoke` | +| `GET` | `/api/v1/oauth/openai/status` | `Status` | + +### LLM Runtime + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/llm/provider-pool` | `Snapshot` | +| `POST` | `/api/v1/llm/provider-pool/{providerId}/reprobe` | `Reprobe` | + +### Tools + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/tools` | `List` | +| `POST` | `/api/v1/tools` | `Create` | +| `GET` | `/api/v1/tools/available` | `List Available` | +| `GET` | `/api/v1/tools/enabled` | `List Enabled` | +| `DELETE` | `/api/v1/tools/{id}` | `Delete` | +| `GET` | `/api/v1/tools/{id}` | `Get` | +| `PUT` | `/api/v1/tools/{id}` | `Update` | +| `PUT` | `/api/v1/tools/{id}/disclosure-tier` | `Set Disclosure Tier` | +| `PUT` | `/api/v1/tools/{id}/toggle` | `Toggle` | + +### MCP Servers + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/mcp/servers` | `List` | +| `POST` | `/api/v1/mcp/servers` | `Create` | +| `POST` | `/api/v1/mcp/servers/refresh` | `Refresh` | +| `DELETE` | `/api/v1/mcp/servers/{id}` | `Delete` | +| `GET` | `/api/v1/mcp/servers/{id}` | `Get` | +| `PUT` | `/api/v1/mcp/servers/{id}` | `Update` | +| `PUT` | `/api/v1/mcp/servers/{id}/disclosure-tier` | `Set Disclosure Tier` | +| `POST` | `/api/v1/mcp/servers/{id}/test` | `Test` | +| `PUT` | `/api/v1/mcp/servers/{id}/toggle` | `Toggle` | +| `GET` | `/api/v1/mcp/servers/{id}/tools` | `List Tools` | + +### ACP Endpoints + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/acp/endpoints` | `List ACP endpoints` | +| `POST` | `/api/v1/acp/endpoints` | `Create a custom ACP endpoint` | +| `DELETE` | `/api/v1/acp/endpoints/{id}` | `Delete an ACP endpoint (builtins are protected)` | +| `GET` | `/api/v1/acp/endpoints/{id}` | `Get ACP endpoint by id` | +| `PUT` | `/api/v1/acp/endpoints/{id}` | `Update an ACP endpoint` | +| `POST` | `/api/v1/acp/endpoints/{id}/test` | `Test ACP endpoint connection (initialize handshake)` | +| `PUT` | `/api/v1/acp/endpoints/{id}/toggle` | `Enable / disable an ACP endpoint` | + +### Skills + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/skills` | `List` | +| `POST` | `/api/v1/skills` | `Create` | +| `GET` | `/api/v1/skills/counts` | `Counts` | +| `POST` | `/api/v1/skills/curator/activate` | `Curator Activate` | +| `POST` | `/api/v1/skills/curator/dry-run` | `Curator Dry Run` | +| `POST` | `/api/v1/skills/curator/pause` | `Curator Pause` | +| `GET` | `/api/v1/skills/curator/reports` | `Curator Reports` | +| `GET` | `/api/v1/skills/curator/reports/{runId}` | `Curator Report` | +| `POST` | `/api/v1/skills/curator/resume` | `Curator Resume` | +| `GET` | `/api/v1/skills/curator/status` | `Curator Status` | +| `GET` | `/api/v1/skills/enabled` | `List Enabled` | +| `POST` | `/api/v1/skills/install/cancel/{taskId}` | `Cancel` | +| `GET` | `/api/v1/skills/install/hub/search` | `Search Hub` | +| `POST` | `/api/v1/skills/install/start` | `Start Install` | +| `GET` | `/api/v1/skills/install/status/{taskId}` | `Get Status` | +| `POST` | `/api/v1/skills/install/upload` | `Upload Zip` | +| `DELETE` | `/api/v1/skills/install/{skillName}` | `Uninstall` | +| `GET` | `/api/v1/skills/prompt-preview` | `Prompt Preview` | +| `GET` | `/api/v1/skills/runtime/active` | `Get Active Skills` | +| `POST` | `/api/v1/skills/runtime/refresh` | `Refresh Runtime` | +| `GET` | `/api/v1/skills/runtime/status` | `Get Runtime Status` | +| `GET` | `/api/v1/skills/summary` | `Summary` | +| `POST` | `/api/v1/skills/sync-files` | `Re-sync every skill's bundle files (admin)` | +| `POST` | `/api/v1/skills/synthesize-from-conversation` | `Synthesize From Conversation` | +| `GET` | `/api/v1/skills/type/{skillType}` | `List By Type` | +| `DELETE` | `/api/v1/skills/{id}` | `Delete` | +| `GET` | `/api/v1/skills/{id}` | `Get` | +| `PUT` | `/api/v1/skills/{id}` | `Update` | +| `POST` | `/api/v1/skills/{id}/archive` | `Archive` | +| `GET` | `/api/v1/skills/{id}/employees` | `List agents that can use this skill (RFC-090 §14.2)` | +| `POST` | `/api/v1/skills/{id}/export-workspace` | `Export To Workspace` | +| `GET` | `/api/v1/skills/{id}/lessons` | `Read per-skill LESSONS.md (RFC-090 §11.4)` | +| `POST` | `/api/v1/skills/{id}/lessons/clear` | `Clear all lessons for a skill (RFC-090 §11.4)` | +| `POST` | `/api/v1/skills/{id}/pin` | `Pin` | +| `GET` | `/api/v1/skills/{id}/requirements` | `Pre-flight requirement statuses for a skill (RFC-090)` | +| `POST` | `/api/v1/skills/{id}/rescan` | `Rescan` | +| `POST` | `/api/v1/skills/{id}/restore` | `Restore` | +| `POST` | `/api/v1/skills/{id}/sync-files` | `Re-sync this skill's bundle files from DB → local workspace cache` | +| `PUT` | `/api/v1/skills/{id}/toggle` | `Toggle` | +| `GET` | `/api/v1/skills/{id}/workspace` | `Get Workspace Info` | +| `GET` | `/api/v1/skills/{skillId}/secrets` | `List secret keys + masked previews for a skill` | +| `POST` | `/api/v1/skills/{skillId}/secrets` | `Upsert a secret value (empty value deletes it)` | +| `DELETE` | `/api/v1/skills/{skillId}/secrets/{key}` | `Delete a single secret by key` | + +### Skill Templates + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/skill-templates` | `List skill templates (RFC-091)` | +| `GET` | `/api/v1/skill-templates/{id}` | `Get a single skill template` | +| `POST` | `/api/v1/skill-templates/{id}/instantiate` | `Instantiate a template into a skill` | + +### Plugins + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/plugins` | `List all plugins` | +| `GET` | `/api/v1/plugins/{name}` | `Get plugin detail` | +| `PUT` | `/api/v1/plugins/{name}/config` | `Update plugin configuration` | +| `POST` | `/api/v1/plugins/{name}/disable` | `Disable a plugin` | +| `POST` | `/api/v1/plugins/{name}/enable` | `Enable a plugin` | + +### LLM Wiki + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/wiki/admin/backfill-tokens` | `Force-run the token-count backfill batch now` | +| `POST` | `/api/v1/wiki/admin/kb/{kbId}/rebuild-overview` | `Ensure overview/log scaffold + rebuild overview stats now` | +| `GET` | `/api/v1/wiki/chunks/{chunkId}/pages` | `Pages By Chunk Id` | +| `DELETE` | `/api/v1/wiki/hot-cache/{kbId}` | `Soft-delete the hot cache row` | +| `GET` | `/api/v1/wiki/hot-cache/{kbId}` | `Get the current hot cache snapshot for a KB` | +| `POST` | `/api/v1/wiki/hot-cache/{kbId}/regenerate` | `Schedule a manual rebuild of the hot cache` | +| `GET` | `/api/v1/wiki/kb/{kbId}/jobs` | `Get Jobs` | +| `GET` | `/api/v1/wiki/kb/{kbId}/pages/{pageId}/citations` | `Page Citations` | +| `GET` | `/api/v1/wiki/kb/{kbId}/pages/{slugA}/relation/{slugB}` | `Explain Relation` | +| `POST` | `/api/v1/wiki/kb/{kbId}/pages/{slug}/enrich` | `Enrich Page` | +| `GET` | `/api/v1/wiki/kb/{kbId}/pages/{slug}/related` | `Related Pages` | +| `POST` | `/api/v1/wiki/kb/{kbId}/pages/{slug}/repair` | `Repair Page` | +| `POST` | `/api/v1/wiki/kb/{kbId}/search-preview` | `Search Preview` | +| `GET` | `/api/v1/wiki/kb/{kbId}/stats` | `Kb Stats` | +| `GET` | `/api/v1/wiki/knowledge-bases` | `List KBs` | +| `POST` | `/api/v1/wiki/knowledge-bases` | `Create KB` | +| `GET` | `/api/v1/wiki/knowledge-bases/agent/{agentId}` | `List KBs By Agent` | +| `GET` | `/api/v1/wiki/knowledge-bases/bindable` | `List Bindable KBs` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{id}` | `Delete KB` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}` | `Get KB` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}` | `Update KB` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}/config` | `Get Config` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}/config` | `Update Config` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile` | `Get Page Type Profile` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile` | `Save Page Type Profile` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile/reset-default` | `Reset Page Type Profile` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile/validate` | `Validate Page Type Profile` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/scan` | `Scan Directory` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}/source-directory` | `Set Source Directory` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}/source-watcher` | `Get Source Watcher` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/source-watcher/scan` | `Trigger Source Watcher` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions` | `List Page Type Permissions` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions` | `Save Page Type Permission` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions/{id}` | `Delete Page Type Permission` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links` | `Get Broken Links Report` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links` | `Start Broken Links Scan` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links/jobs/{jobId}` | `Get Broken Links Job` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages` | `List Pages` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/archived` | `List Archived Pages` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/batch` | `Batch Delete Pages` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/refs` | `List Page Refs` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}` | `Delete Page` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}` | `Get Page` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}` | `Update Page` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/archive` | `Archive Page` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/backlinks` | `Get Backlinks` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/rename` | `Rename Page` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/unarchive` | `Unarchive Page` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pipeline-runs/{runId}` | `Get Pipeline Run` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines` | `List Pipelines` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines` | `Save Pipeline` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines/validate` | `Validate Pipeline` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines/{id}` | `Delete Pipeline` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines/{id}/runs` | `List Pipeline Runs` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/process` | `Process KB` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/processing-status` | `Get Processing Status` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/progress` | `Subscribe Progress` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/raw` | `List Raw` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/text` | `Add Raw Text` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/upload` | `Upload Raw` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}` | `Delete Raw` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}/cancel` | `Cancel Raw` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}/download` | `Download Raw` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}/reprocess` | `Reprocess Raw` | +| `GET` | `/api/v1/wiki/pages/lookup` | `Lookup Pages` | +| `GET` | `/api/v1/wiki/raw/{rawId}/pages` | `Pages By Raw Id` | +| `POST` | `/api/v1/wiki/research/start` | `Start Research` | +| `GET` | `/api/v1/wiki/research/stream/{sessionId}` | `Stream` | +| `GET` | `/api/v1/wiki/transformations` | `List transformations available to a KB` | +| `POST` | `/api/v1/wiki/transformations` | `Create` | +| `GET` | `/api/v1/wiki/transformations/runs` | `List Runs` | +| `DELETE` | `/api/v1/wiki/transformations/runs/{runId}` | `Delete Run` | +| `GET` | `/api/v1/wiki/transformations/runs/{runId}` | `Get Run` | +| `POST` | `/api/v1/wiki/transformations/runs/{runId}/cancel` | `Cancel a still-running transformation run` | +| `POST` | `/api/v1/wiki/transformations/runs/{runId}/save-as-page` | `Save a completed run's output as a synthesis wiki page` | +| `DELETE` | `/api/v1/wiki/transformations/{id}` | `Delete` | +| `GET` | `/api/v1/wiki/transformations/{id}` | `Get` | +| `PUT` | `/api/v1/wiki/transformations/{id}` | `Update` | +| `POST` | `/api/v1/wiki/transformations/{id}/aggregate` | `Aggregate all completed runs of a template into one KB-level synthesis page` | +| `POST` | `/api/v1/wiki/transformations/{id}/apply` | `Run a transformation against a raw material or wiki page` | + +### Memory + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/memory/{agentId}/dream/events` | `Subscribe to dream events (SSE)` | +| `GET` | `/api/v1/memory/{agentId}/dream/morning-card` | `Get morning card for current user + agent` | +| `POST` | `/api/v1/memory/{agentId}/dream/morning-card/seen` | `Mark morning card as seen` | +| `GET` | `/api/v1/memory/{agentId}/dream/reports` | `List dream reports (paginated, newest first)` | +| `GET` | `/api/v1/memory/{agentId}/dream/reports/{reportId}` | `Get a single dream report by ID` | +| `POST` | `/api/v1/memory/{agentId}/dream/reports/{reportId}/entries/{key}/confirm` | `Confirm a memory entry (no-op acknowledgment)` | +| `POST` | `/api/v1/memory/{agentId}/dream/reports/{reportId}/entries/{key}/edit` | `Edit a memory entry — writes back to the target memory file with user-edited metadata` | +| `GET` | `/api/v1/memory/{agentId}/dreaming/candidates` | `Get Dreaming Candidates` | +| `GET` | `/api/v1/memory/{agentId}/dreaming/dreams` | `Get Dreams` | +| `POST` | `/api/v1/memory/{agentId}/dreaming/focused` | `Trigger Focused Dream` | +| `GET` | `/api/v1/memory/{agentId}/dreaming/status` | `Get Dreaming Status` | +| `POST` | `/api/v1/memory/{agentId}/emergence` | `Trigger Emergence` | +| `GET` | `/api/v1/memory/{agentId}/facts` | `List facts for an agent` | +| `GET` | `/api/v1/memory/{agentId}/facts/contradictions` | `List unresolved contradictions` | +| `POST` | `/api/v1/memory/{agentId}/facts/contradictions/{contradictionId}/resolve` | `Resolve a contradiction (KEEP_A / KEEP_B / MERGE / IGNORE)` | +| `POST` | `/api/v1/memory/{agentId}/facts/{factId}/feedback` | `Submit feedback on a fact (HELPFUL/UNHELPFUL)` | +| `POST` | `/api/v1/memory/{agentId}/facts/{factId}/forget` | `Forget a fact — writes canonical metadata, rebuilds projection` | +| `POST` | `/api/v1/memory/{agentId}/summarize/{conversationId}` | `Trigger Summarize` | + +### Goals + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/goals` | `List goals (optionally filtered by status)` | +| `POST` | `/api/v1/goals` | `Create a persistent goal for a conversation` | +| `GET` | `/api/v1/goals/by-conversation/{conversationId}` | `Get the active goal bound to a conversation (or null)` | +| `GET` | `/api/v1/goals/{id}` | `Get goal detail by id` | +| `PATCH` | `/api/v1/goals/{id}` | `Sparse update of a non-terminal goal` | +| `POST` | `/api/v1/goals/{id}/abandon` | `Abandon a goal (terminal)` | +| `POST` | `/api/v1/goals/{id}/criteria` | `Append a sub-criterion to an active goal` | +| `GET` | `/api/v1/goals/{id}/events` | `Get the event timeline for a goal` | +| `POST` | `/api/v1/goals/{id}/pause` | `Pause an active goal` | +| `POST` | `/api/v1/goals/{id}/resume` | `Resume a paused goal` | + +### Cron Jobs + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/cron-jobs` | `List` | +| `POST` | `/api/v1/cron-jobs` | `Create` | +| `GET` | `/api/v1/cron-jobs/active-runs` | `Active Runs` | +| `DELETE` | `/api/v1/cron-jobs/{id}` | `Delete` | +| `GET` | `/api/v1/cron-jobs/{id}` | `Get` | +| `PUT` | `/api/v1/cron-jobs/{id}` | `Update` | +| `POST` | `/api/v1/cron-jobs/{id}/run` | `Run Now` | +| `PUT` | `/api/v1/cron-jobs/{id}/toggle` | `Toggle` | + +### Triggers + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/triggers` | `List triggers in the caller's workspace.` | +| `POST` | `/api/v1/triggers` | `Create a trigger; if enabled, registers it with the scheduler.` | +| `POST` | `/api/v1/triggers/events` | `Ingest one event envelope; returns per-trigger fire / drop summary.` | +| `DELETE` | `/api/v1/triggers/{id}` | `Delete a trigger and unregister its schedule.` | +| `GET` | `/api/v1/triggers/{id}` | `Get a trigger by id, scoped to the caller's workspace.` | +| `PUT` | `/api/v1/triggers/{id}` | `Update a trigger; pattern_version bumps when the cron expression changes.` | + +### Workflows + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/workflows` | `List workflows in the workspace` | +| `POST` | `/api/v1/workflows` | `Create a workflow row (draft starts empty).` | +| `POST` | `/api/v1/workflows/draft/generate` | `Generate a workflow draft from a natural-language description.` | +| `POST` | `/api/v1/workflows/draft/preview-compile` | `Compile arbitrary draft JSON without persisting — used by the template picker / generator preview to surface real ACL + schema diagnostics before a workflow row exists.` | +| `GET` | `/api/v1/workflows/draft/templates` | `List the canonical workflow templates the generator can apply directly.` | +| `GET` | `/api/v1/workflows/runs/paused` | `List paused runs across the workspace so operators can resume them.` | +| `GET` | `/api/v1/workflows/runs/{runId}` | `Inspect a single run with its step rows for replay / debugging.` | +| `POST` | `/api/v1/workflows/runs/{runId}/resume` | `Resume a paused workflow run with the given outcome.` | +| `DELETE` | `/api/v1/workflows/{id}` | `Soft-delete a workflow row.` | +| `GET` | `/api/v1/workflows/{id}` | `Get a workflow by id (includes inline draft + latest published graph).` | +| `PUT` | `/api/v1/workflows/{id}` | `Update workflow metadata (name / description / enabled).` | +| `POST` | `/api/v1/workflows/{id}/compile` | `Compile the draft and surface diagnostics without persisting a revision.` | +| `PUT` | `/api/v1/workflows/{id}/draft` | `Save the inline draft graph_json without compiling.` | +| `POST` | `/api/v1/workflows/{id}/publish` | `Compile the draft and persist a new revision pointed at by latest_revision_id.` | +| `GET` | `/api/v1/workflows/{id}/runs` | `List the most recent runs for a workflow.` | + +### Channels + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/channels` | `List` | +| `POST` | `/api/v1/channels` | `Create` | +| `GET` | `/api/v1/channels/health` | `Health All` | +| `POST` | `/api/v1/channels/preflight` | `Pre-flight: validate draft channel config without persisting` | +| `POST` | `/api/v1/channels/qrcode/{channelType}/begin` | `Begin` | +| `GET` | `/api/v1/channels/qrcode/{channelType}/status` | `Status` | +| `GET` | `/api/v1/channels/status` | `Status` | +| `GET` | `/api/v1/channels/type/{channelType}` | `List By Type` | +| `GET` | `/api/v1/channels/webchat/config` | `Get Config` | +| `POST` | `/api/v1/channels/webchat/stream` | `Chat Stream` | +| `POST` | `/api/v1/channels/webhook/dingtalk` | `Dingtalk Webhook` | +| `POST` | `/api/v1/channels/webhook/dingtalk/register/begin` | `Dingtalk Register Begin` | +| `GET` | `/api/v1/channels/webhook/dingtalk/register/status` | `Dingtalk Register Status` | +| `POST` | `/api/v1/channels/webhook/discord` | `Discord Webhook` | +| `POST` | `/api/v1/channels/webhook/feishu` | `Feishu Webhook` | +| `POST` | `/api/v1/channels/webhook/feishu/register/begin` | `Feishu Register Begin` | +| `GET` | `/api/v1/channels/webhook/feishu/register/status` | `Feishu Register Status` | +| `POST` | `/api/v1/channels/webhook/slack` | `Slack Webhook` | +| `GET` | `/api/v1/channels/webhook/status` | `Status` | +| `POST` | `/api/v1/channels/webhook/telegram` | `Telegram Webhook` | +| `POST` | `/api/v1/channels/webhook/wecom` | `Wecom Webhook` | +| `GET` | `/api/v1/channels/webhook/weixin/qrcode` | `Weixin Qrcode` | +| `GET` | `/api/v1/channels/webhook/weixin/qrcode/status` | `Weixin Qrcode Status` | +| `DELETE` | `/api/v1/channels/{id}` | `Delete` | +| `GET` | `/api/v1/channels/{id}` | `Get` | +| `PUT` | `/api/v1/channels/{id}` | `Update` | +| `GET` | `/api/v1/channels/{id}/health` | `Health` | +| `PUT` | `/api/v1/channels/{id}/toggle` | `Toggle` | + +### Datasources + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/datasources` | `List` | +| `POST` | `/api/v1/datasources` | `Create` | +| `DELETE` | `/api/v1/datasources/{id}` | `Delete` | +| `GET` | `/api/v1/datasources/{id}` | `Get` | +| `PUT` | `/api/v1/datasources/{id}` | `Update` | +| `POST` | `/api/v1/datasources/{id}/test` | `Test Connection` | +| `PUT` | `/api/v1/datasources/{id}/toggle` | `Toggle` | + +### Speech to Text + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/stt/transcribe` | `Transcribe` | + +### Text to Speech + +| Method | Path | Purpose / handler | +|---|---|---| +| `POST` | `/api/v1/tts/synthesize` | `Synthesize` | +| `GET` | `/api/v1/tts/voices` | `List Voices` | + +### Generated Files + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/files/generated/{id}` | `Download a tool-generated file by its one-time id` | + +### Plans + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/plans` | `List By Agent` | +| `GET` | `/api/v1/plans/{id}` | `Get Plan` | + +### Feature Flags + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/feature-flags` | `List` | +| `PUT` | `/api/v1/feature-flags/{flagKey}` | `Update` | diff --git a/mateclaw-server/src/main/resources/docs/en/architecture.md b/mateclaw-server/src/main/resources/docs/en/architecture.md index 126fbcae..319f94ec 100644 --- a/mateclaw-server/src/main/resources/docs/en/architecture.md +++ b/mateclaw-server/src/main/resources/docs/en/architecture.md @@ -151,7 +151,7 @@ This is the most important thing to know if you're contributing to the backend. ### Goal-evaluation node (1.4.0+) -The graph (both ReAct and Plan-Execute) now runs a `GoalEvaluationNode` after `FinalAnswerNode` has streamed the final answer: it scores how completely the goal was met and can optionally inject an auto-followup message to keep pushing any unmet goals forward. +The graph (both ReAct and Plan-Execute) now runs a `GoalEvaluationNode` after `FinalAnswerNode` has streamed the final answer: since 1.5.0 it judges the goal's checklist criterion by criterion (bootstrap / verdict modes), treats the goal as complete **only when every criterion passes**, and can optionally inject an auto-followup message targeting the remaining criteria to keep pushing any unmet goal forward. ### Other 1.4.0 runtime changes @@ -179,7 +179,7 @@ The graph (both ReAct and Plan-Execute) now runs a `GoalEvaluationNode` after `F ## Data flow — a single turn ``` -1. POST /api/v1/chat/{agentId}/message +1. POST /api/v1/chat?agentId={id} (or POST /api/v1/chat/stream with agentId in the body) ↓ 2. ChatController.sendMessage() ↓ @@ -301,7 +301,7 @@ Why: Spring MVC + SSE is sufficient for streaming LLM responses to the frontend. Streaming flow: -1. Client opens `GET /api/v1/chat/{agentId}/stream` with `Accept: text/event-stream` +1. Client `POST /api/v1/chat/stream` with `agentId` / `message` / `conversationId` in the JSON body and `Accept: text/event-stream` in the headers 2. Controller returns `SseEmitter` 3. Agent graph runs on a worker thread; node execution emits events to `GraphEventPublisher` 4. Events serialize into SSE format and write to the emitter diff --git a/mateclaw-server/src/main/resources/docs/en/channels.md b/mateclaw-server/src/main/resources/docs/en/channels.md index 41cebae6..327536ea 100644 --- a/mateclaw-server/src/main/resources/docs/en/channels.md +++ b/mateclaw-server/src/main/resources/docs/en/channels.md @@ -35,6 +35,11 @@ v1.4.0 makes Feishu a first-class channel — interactive cards, streaming cards Feishu specifics are spelled out in the [Feishu](#feishu-lark) section below. ::: +::: tip 1.5.0 channel improvements +- **Shared inbound media pipeline** — **WeChat and WeCom** are currently wired onto a shared inbound-media downloader + magic-byte type detection + exponential-backoff retry (other IM channels to follow). File types are decided from content bytes (no more hardcoded `image/*`); HEIC / WEBP / DOCX / XLSX and friends are detected correctly, with automatic retry on download failure. +- **Feishu: follow-up text auto-carries recent files (#201)** — send a file in a Feishu chat first (even without @-mentioning the employee), then a text message, and the cached files are auto-attached as content parts for the employee — 5 files per chat, 60-minute TTL. +::: + --- ## The nine channels @@ -103,7 +108,11 @@ All credentials encrypted at rest. One agent can have many channels; different c Built in. No setup, no credentials. Uses Server-Sent Events for real-time streaming. ``` -GET /api/v1/chat/{agentId}/stream +POST /api/v1/chat/stream +Content-Type: application/json +Accept: text/event-stream + +{"agentId": 1, "message": "...", "conversationId": "..."} ``` Event format documented in [Chat & Messaging](./chat). diff --git a/mateclaw-server/src/main/resources/docs/en/chat.md b/mateclaw-server/src/main/resources/docs/en/chat.md index 0bd0b343..b7eb1a8c 100644 --- a/mateclaw-server/src/main/resources/docs/en/chat.md +++ b/mateclaw-server/src/main/resources/docs/en/chat.md @@ -50,6 +50,8 @@ One of the questions MateClaw tries to answer with its chat UI is: **should you Trust is earned by showing the work. MateClaw shows the work. +**Execution-plan & tool-call detail viewer (1.5.0).** Every plan step and every tool-call row gets a "view details" icon on the right. Click it for a frosted-glass dialog showing the **full request arguments and response output** — the parts the inline preview truncates — with copy buttons for request and response, and a status badge (in progress / completed / failed / pending). The data lives in message metadata, so plan steps and tool calls stay readable after a page reload. + --- ## Multi-channel realtime sync @@ -86,6 +88,10 @@ Upload limits, default: Images handed to a vision-capable model get attached for visual understanding. PDFs and DOCX files go through text extraction (with OCR fallback for scanned material). Everything the agent reads lands in its context for that turn. +::: tip Tool-generated files: download links survive restarts (1.5.0, #243) +Files a worker generates via tools (documents / images / audio…) are now **persisted to disk** under `data/generated-files/`, with a 7-day retention window + a 6-hour cleanup sweep and an in-memory LRU on top — download links keep working after a restart and are no longer bounded by the old 10-minute in-memory window. The frontend intercepts `/api/v1/files/generated/{id}` downloads via a global click delegator: success goes through an authenticated fetch → blob download; failure (404/410/expired) just shows a toast, **so a dead link no longer wedges the whole page**. +::: + ### Primary model can't see images? "Multimodal sidecar" routing ::: tip Added in 1.3.0 @@ -119,7 +125,7 @@ This is the thirty-second version. The ninety-second version is in [Agents](./ag You type │ ▼ -POST /api/v1/chat/{agentId}/message ← or SSE for streaming +POST /api/v1/chat?agentId={id} ← or SSE for streaming (POST /api/v1/chat/stream) │ ▼ Conversation Manager ← load/create conversation, append user message @@ -270,31 +276,49 @@ Go deeper in [Channels](./channels). ### Send a message ```bash -curl -X POST http://localhost:18088/api/v1/chat/1/message \ +curl -X POST 'http://localhost:18088/api/v1/chat?agentId=1' \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ - "content": "What is the current time in Tokyo?", + "message": "What is the current time in Tokyo?", "conversationId": "conv-abc123" }' ``` -Omit `conversationId` to start a new conversation. +Omit `conversationId` to start a new conversation. `agentId` is a query parameter, **not** a path segment. ### SSE streaming -```javascript -const eventSource = new EventSource( - '/api/v1/chat/1/stream?conversationId=conv-abc123', - { headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' } } -); +The SSE endpoint is `POST /api/v1/chat/stream` with `agentId` in the JSON body. Browser-native `EventSource` only supports GET, so integrators should use `fetch()` and read the response stream: -eventSource.onmessage = (event) => { - const data = JSON.parse(event.data); - // handle segment -}; +```javascript +const resp = await fetch('/api/v1/chat/stream', { + method: 'POST', + headers: { + 'Authorization': 'Bearer YOUR_JWT_TOKEN', + 'Content-Type': 'application/json', + 'Accept': 'text/event-stream', + }, + body: JSON.stringify({ + agentId: 1, + message: 'What is the current time in Tokyo?', + conversationId: 'conv-abc123', + }), +}); + +const reader = resp.body.getReader(); +const decoder = new TextDecoder(); +let buf = ''; +while (true) { + const { value, done } = await reader.read(); + if (done) break; + buf += decoder.decode(value, { stream: true }); + // Split on SSE `\n\n` event boundaries and dispatch segments +} ``` +See `mateclaw-ui/src/composables/chat/useChat.ts` for a full client implementation. + ### SSE event types | Event | Meaning | diff --git a/mateclaw-server/src/main/resources/docs/en/console.md b/mateclaw-server/src/main/resources/docs/en/console.md index 5bb80269..dbf072af 100644 --- a/mateclaw-server/src/main/resources/docs/en/console.md +++ b/mateclaw-server/src/main/resources/docs/en/console.md @@ -111,7 +111,7 @@ Features: - `POST /api/v1/chat/stream` — SSE streaming (native fetch) - `POST /api/v1/chat/upload` - `POST /api/v1/chat/{conversationId}/stop` -- `POST /api/v1/approvals/{id}/resolve` +- approval resolution is sent as `/approve` or `/deny` through `POST /api/v1/chat/stream` - `GET /api/v1/chat/{conversationId}/pending-approvals` - `GET /api/v1/conversations` — list - `GET /api/v1/conversations/{id}/messages` diff --git a/mateclaw-server/src/main/resources/docs/en/desktop.md b/mateclaw-server/src/main/resources/docs/en/desktop.md index 36565129..adcfc8a1 100644 --- a/mateclaw-server/src/main/resources/docs/en/desktop.md +++ b/mateclaw-server/src/main/resources/docs/en/desktop.md @@ -147,7 +147,8 @@ cd ../mateclaw-server mvn clean package -DskipTests # 3. Copy JAR to desktop resources -cp target/mateclaw-server.jar ../mateclaw-desktop/resources/app.jar +JAR_FILE=$(ls -1 target/mateclaw-server-*.jar | grep -v sources | head -n 1) +cp "$JAR_FILE" ../mateclaw-desktop/resources/app.jar # 4. Download platform-specific JRE cd ../mateclaw-desktop diff --git a/mateclaw-server/src/main/resources/docs/en/doctor.md b/mateclaw-server/src/main/resources/docs/en/doctor.md index 1b91c503..9d63152c 100644 --- a/mateclaw-server/src/main/resources/docs/en/doctor.md +++ b/mateclaw-server/src/main/resources/docs/en/doctor.md @@ -1,233 +1,71 @@ # Doctor -**The Doctor page answers one question: is this thing actually working right now?** +Doctor is the in-app health drawer. It reports the current local instance status from the backend health service; it is not a separate scheduled diagnostics subsystem. -MateClaw has a lot of moving parts — the backend, the database, model providers, MCP servers, IM channels, cron jobs, memory consolidation, wiki digestion. When something goes sideways, the symptom ("my agent isn't responding") usually has a specific cause ("the DashScope API key expired yesterday") buried several layers away from where you'd notice. Doctor is a single page that runs every check at once and tells you what's green, what's yellow, and what's red. +Open it from the layout status button / Settings area. The drawer calls the backend each time it opens or when you click refresh. -Open it with `Settings → Doctor` or just navigate to `/doctor`. +## Current Backend API ---- - -## What it checks - -Each check runs independently and reports one of three states: - -- **✅ OK** — everything is working as expected -- **⚠️ Warning** — working but degraded (e.g., using a fallback provider, nearing a quota, a non-critical cron job is paused) -- **❌ Error** — broken in a way you need to fix - -### Core infrastructure - -| Check | What it verifies | -|-------|-----------------| -| **Backend version** | MateClaw is running and reports its version | -| **Database connection** | The configured datasource is reachable and queries succeed | -| **Database schema** | All expected `mate_*` tables exist; migration state is clean | -| **Disk usage** | The data directory has enough free space (warns under 20%, errors under 5%) | -| **H2 console exposure** | Warns if the H2 console is enabled in production profile | -| **JWT secret strength** | Warns if the default JWT secret is still in use | - -### Models - -| Check | What it verifies | -|-------|-----------------| -| **Active model** | A default model config exists and is enabled | -| **Provider connectivity** | Each enabled provider has passed a recent connection test | -| **API key presence** | Keys are configured for every cloud provider marked enabled | -| **Ollama reachability** | If Ollama is configured, the local instance is reachable | - -### Agents & tools - -| Check | What it verifies | -|-------|-----------------| -| **Tool registry** | Built-in and MCP tools are loaded without errors | -| **Tool Guard config** | At least one Tool Guard rule exists (warns if `default-policy: allow` is used) | -| **Default agent** | The default agent exists and is enabled | -| **Agent templates** | Built-in templates are present and loadable | - -### Memory & wiki - -| Check | What it verifies | -|-------|-----------------| -| **Memory consolidation cron** | Per-agent consolidation cron jobs exist and are enabled | -| **Last consolidation run** | Warns if no consolidation has run in the past 7 days | -| **Wiki digestion queue** | No stuck `pending` or `processing` raw materials | -| **Wiki schema** | `mate_wiki_*` tables exist and are queryable | - -### Channels - -| Check | What it verifies | -|-------|-----------------| -| **Channel health monitor** | Every enabled channel reports `connected` or is actively reconnecting | -| **Per-channel status** | For each IM channel, connection state and last error | -| **Webhook URL reachability** | Warns if a webhook-mode channel has no public URL configured in production | - -### MCP - -| Check | What it verifies | -|-------|-----------------| -| **Enabled MCP servers** | Every enabled MCP server is `connected` | -| **Tool count** | Each connected server reports at least one tool | -| **Orphaned subprocesses** | No stdio subprocesses outlive their parent client | - -### Cron & async - -| Check | What it verifies | -|-------|-----------------| -| **Cron engine** | The scheduled-task executor is running | -| **Overdue jobs** | Warns if any job is more than 24 hours overdue | -| **Async task queue** | `mate_async_task` queue length is within normal bounds | - ---- - -## How checks run - -Doctor runs two ways: - -### On demand - -Click **Run All Checks** on the Doctor page. The button fires off every check in parallel; the UI streams results back as each finishes. Most checks complete in under a second; the slowest (MCP server connection tests) can take 10–30 seconds. - -### On a schedule - -Doctor also runs **automatically every 15 minutes** in the background. Results are cached in memory and persisted to `mate_doctor_check` so the page loads instantly when you open it — you're seeing the last cached state until you click **Run All Checks**. - -You can tune the schedule in `application.yml`: - -```yaml -mateclaw: - doctor: - enabled: true - schedule-minutes: 15 - cache-ttl-minutes: 10 +```bash +curl http://localhost:18088/api/v1/system/health \ + -H "Authorization: Bearer " ``` ---- - -## Reading results - -Each check returns: +Response shape: ```json { - "name": "DashScope Provider Connectivity", - "category": "Models", - "status": "ok", - "message": "Connection test succeeded (latency: 240ms)", - "lastChecked": "2026-04-11T14:30:22", - "details": { - "provider": "dashscope", - "baseUrl": "https://dashscope.aliyuncs.com", - "latencyMs": 240 - }, - "fixUrl": "/settings/models" + "code": 200, + "msg": "success", + "data": { + "overall": "healthy", + "checks": [ + { + "name": "default-model", + "status": "healthy", + "message": "Default model: qwen-plus", + "action": null + } + ] + } } ``` -The UI renders: +`overall` is one of `healthy`, `warning`, or `error`. Each check has: -- **Category tabs** at the top — Infrastructure, Models, Agents, Memory, Wiki, Channels, MCP, Cron -- **Status counters** — green / yellow / red -- **Check list** — name, status, message, time since last check, "View details" expand, optional "Fix" button that navigates to the relevant settings page -- **History graph** — (for each check) a sparkline of the last 50 runs so you can see flapping checks at a glance +| Field | Meaning | +|---|---| +| `name` | Stable check key such as `default-model`, `database`, `browser`, `provider:`, `mcp:` | +| `status` | `healthy`, `warning`, or `error` | +| `message` | Short diagnostic text shown in the drawer | +| `action` | Optional `{ label, route }` hint for where to fix the issue | ---- +## What It Checks Today -## Fix buttons +The current `SystemHealthService` checks: -For actionable checks, the Doctor row includes a **Fix** button that navigates directly to the relevant settings page: +| Check | What it verifies | Typical action | +|---|---|---| +| Default model | A default model is configured and loadable | `/settings/models` | +| Providers | API-key providers are configured when required | `/settings/models` | +| Enabled MCP servers | Enabled MCP servers have a successful connection result | `/settings/mcp-servers` | +| Database initialization | First-run bootstrap has completed | `/setup` | +| Browser diagnostics | Browser launch pre-flight for browser tooling | `/api/v1/system/browser-health` | -- Model provider failure → `Settings → Models` -- Tool Guard `default-policy: allow` → `Settings → Security & Approval` -- H2 console in production → `Settings → System` (or show a config snippet to copy) -- JWT default secret → `Settings → System` (or show a config snippet) -- MCP server disconnected → `Tools → MCP Servers` -- Stuck wiki digestion → `Wiki → [KB] → Raw Material` - -Clicking Fix takes you to the exact page where you can address the issue. When possible, the target page is pre-filtered to highlight the failing item. - ---- - -## Doctor API +There is also a direct browser diagnostics endpoint: ```bash -# Run all checks (synchronous) -curl http://localhost:18088/api/v1/doctor/run \ - -H "Authorization: Bearer " - -# Get the cached check results -curl http://localhost:18088/api/v1/doctor/checks \ - -H "Authorization: Bearer " - -# Run a specific category only -curl http://localhost:18088/api/v1/doctor/run?category=models \ - -H "Authorization: Bearer " - -# Historical results -curl "http://localhost:18088/api/v1/doctor/history?check=dashscope-connectivity&limit=50" \ +curl http://localhost:18088/api/v1/system/browser-health \ -H "Authorization: Bearer " ``` ---- +## Not Implemented In The Current Source Tree -## Using Doctor in operations +Older docs mentioned `/api/v1/doctor/run`, `/api/v1/doctor/checks`, `/api/v1/doctor/history`, scheduled background Doctor runs, `mate_doctor_check`, and `mate_doctor_check_history`. Those endpoints and tables are not present in the current backend source. Use `/api/v1/system/health` for the current health surface. -### As a health endpoint for uptime monitoring +## Related Pages -Point your external uptime monitor (UptimeRobot, Pingdom, internal Prometheus) at: - -``` -GET /api/v1/doctor/checks -``` - -The endpoint returns HTTP 200 with JSON summary — aggregate pass/fail counts and per-category breakdown. Your monitor should alert when `errorCount > 0`. - -For a simpler health check, use: - -``` -GET /actuator/health -``` - -which follows Spring Boot's standard format. - -### During upgrades - -After deploying a new MateClaw version, run Doctor to verify nothing regressed: - -1. Open `/doctor` -2. Click **Run All Checks** -3. Look for any yellows or reds that weren't there before -4. Pay special attention to **Database schema** — a mismatched schema after an upgrade usually means a migration didn't run - -### When something's broken - -Doctor is the first place to look when a user reports "it's not working". Open the page, see which check is red, click **Fix**, solve the problem. If no check is red but the user still has an issue, it's probably something Doctor doesn't cover yet — file it as a [GitHub issue](https://github.com/matevip/mateclaw/issues) so we can add a check. - ---- - -## Data model - -**`mate_doctor_check`** - -| Column | Purpose | -|--------|---------| -| `id` | Primary key | -| `name` | Check name | -| `category` | Check category | -| `status` | `ok` / `warning` / `error` | -| `message` | Human-readable message | -| `details` | JSON blob of extra detail | -| `last_checked` | When it last ran | -| `run_duration_ms` | How long the check took | -| `workspace_id` | Scoping (nullable for global checks) | - -Historical results go into `mate_doctor_check_history` with the same columns plus a retention cleanup job. - ---- - -## Next - -- [Admin Console](./console) — the UI Doctor lives in -- [Configuration](./config) — things you might configure based on Doctor warnings -- [Security & Approval](./security) — what Doctor checks in Tool Guard -- [Contributing](./contributing) — add a new Doctor check if something's missing +- [API Reference](./api) - source-aligned route inventory +- [Models](./models) - model/provider setup +- [MCP](./mcp) - MCP server setup +- [Security & Approval](./security) - Tool Guard and approval behavior diff --git a/mateclaw-server/src/main/resources/docs/en/faq.md b/mateclaw-server/src/main/resources/docs/en/faq.md index 1f09792f..a6e628e4 100644 --- a/mateclaw-server/src/main/resources/docs/en/faq.md +++ b/mateclaw-server/src/main/resources/docs/en/faq.md @@ -215,9 +215,10 @@ Edit `PROFILE.md` or `MEMORY.md` directly in the agent workspace view. Lock page ### I approved a tool call but the agent didn't resume 1. Is `AWAITING_APPROVAL` still set? (`GET /api/v1/agents/{id}`) -2. Did the approval actually persist? (`GET /api/v1/approvals/{id}`) +2. Does the waiting conversation still have a pending approval? (`GET /api/v1/chat/{conversationId}/pending-approvals`) 3. Are there errors in the agent log around the replay attempt? -4. If replay failed, the agent should surface an error in the chat +4. Did the approve/reject message go through the same conversation via `POST /api/v1/chat/stream`? +5. If replay failed, the agent should surface an error in the chat ### I want to batch-approve future tool calls from this agent @@ -381,8 +382,11 @@ mvn spring-boot:run -Dspring-boot.run.arguments="--logging.level.vip.mate=DEBUG" Browser DevTools → Network → filter `EventStream`. Or: ```bash -curl -N -H "Authorization: Bearer " \ - "http://localhost:18088/api/v1/chat/1/stream?conversationId=1" +curl -N -X POST 'http://localhost:18088/api/v1/chat/stream' \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -H "Accept: text/event-stream" \ + -d '{"agentId":1, "message":"test", "conversationId":"1"}' ``` --- diff --git a/mateclaw-server/src/main/resources/docs/en/goals.md b/mateclaw-server/src/main/resources/docs/en/goals.md index 73c5aa6c..5ded56fc 100644 --- a/mateclaw-server/src/main/resources/docs/en/goals.md +++ b/mateclaw-server/src/main/resources/docs/en/goals.md @@ -65,8 +65,6 @@ For automation and external scripts, the endpoint is direct: POST /api/v1/goals { "conversationId": "conv-xxx", - "agentId": "1000000001", - "workspaceId": 1, "title": "Deploy blog to fly.io", "description": "...", "exitCriteria": "DNS + SSL + healthcheck + tests pass", @@ -76,7 +74,7 @@ POST /api/v1/goals } ``` -Full surface in the [API reference](./api). +> `agentId` / `workspaceId` are derived server-side from `conversationId` — **don't send them** (they're ignored if you do). Full surface in the [API reference](./api). --- @@ -114,13 +112,59 @@ After every turn, a backend evaluator node runs: When `autoFollowupEnabled=true` and this turn's evaluator decision is "continue", the backend: 1. Writes a `followup_injected` event to the timeline -2. APPENDs a user message to the conversation: *"Continue working on the goal. Still missing: {gap}. Take the next concrete step."* +2. APPENDs a user message to the conversation. **Since 1.5.0, if the goal has a checklist, that message explicitly lists the criteria still open** — *"5/8 done, remaining: ① … ② …, take the next step on these"*; with no checklist it falls back to the generic *"Continue working on the goal. Still missing: {gap}."* 3. Re-enters the reasoning loop — the next assistant reply lands right after the first Feels like: the worker answers a segment → pauses a beat → **keeps going** — like a person who finished one step, thought for a second, and continued. --- +## A goal is a checklist (1.5.0+) + +In 1.4.0 the evaluator gave a completion score (0–1) and a one-line "what's missing" each turn. The problem: **what does 0.8 mean** — which boxes are done, which aren't? You couldn't see it. + +1.5.0 replaces that with a **checklist**: a goal = a set of **independently verifiable** criteria. + +**The evaluator has two modes:** + +| Mode | When | What it does | +|---|---|---| +| **bootstrap** | No criteria yet | Decomposes the goal into a checklist; each starts "not passed" | +| **verdict** | Criteria exist | Judges each one: satisfied? with evidence | + +Both modes use **structured output** — the evaluator returns a typed object (criterion `id` + `passed` + `evidence`), not free text we have to parse. + +**Completion is deterministic.** Only when **every criterion passes** is the goal done. 19 of 20 passed (a 0.95 score) is still "continue" — miss one and one is missing, no fuzzy threshold. + +**Three ways to add a checklist:** + +- **At creation** — pass `criteria: ["DNS resolves", "SSL valid", "tests green"]` to the `setGoal` tool, or `criteria` to `POST /api/v1/goals`. Skips the bootstrap round. +- **Let the evaluator decompose** — pass no criteria and the first evaluation bootstraps the checklist. +- **Append at runtime** — the `addGoalCriterion` tool or `POST /api/v1/goals/{id}/criteria` adds one to a live goal without restarting. + +**What a criterion looks like:** + +```json +{ "id": "C1", "text": "DNS resolves to fly.io", "passed": false, "evidence": "" } +``` + +`id` is server-assigned (C1, C2…), `text` is a sentence a human reads and an LLM judges, `passed` is the evaluator's verdict, `evidence` is the justification it gives. The checklist lives in the `mate_agent_goal.criteria` column (JSON) and is delivered parsed as `GoalResponse.criteria`, never as a raw JSON string. + +### The ring, on hover, is a checklist card + +- **No checklist** — a one-line tooltip: title + the gap text the evaluator wrote. +- **With a checklist** — a card: title + `X/Y` progress, then each criterion prefixed by `○` (open) or `✓` (green, done, struck through). + +While evaluating, a sand-gold breathing halo surrounds the avatar; on completion a green ring shows briefly then disappears; on budget exhaustion the ring turns rust. + +### Evaluator SPI + +The evaluation logic implements Spring AI's `Evaluator` interface: it does goal-specific checklist verdicts (bootstrap / verdict) and can be reused as a generic evaluator (wrapping a single objective as one criterion in verdict mode). Failed evaluator calls **still count against the LLM budget**, so the accounting stays honest. + +> The 1.4.0 goal was "the worker remembers what it's doing." The 1.5.0 goal is "the worker knows **exactly which boxes are still open**." From a score to a checklist you can tick. + +--- + ## Four built-in tools (worker-callable) These four ship as agent-wide system tools — no binding setup needed: @@ -132,7 +176,7 @@ These four ship as agent-wide system tools — no binding setup needed: | **completeGoal** | Explicitly mark done | "All items done — call completeGoal" | | **getGoalStatus** | Inspect current state | "How are we doing?" | -On completion (`completeGoal` or evaluator score ≥ 0.95), the worker forwards a summary to its [long-term memory](./memory) so future conversations can recall it. +On completion (`completeGoal`, or the evaluator judging **every criterion passed**), the worker forwards a summary to its [long-term memory](./memory) so future conversations can recall it. --- @@ -168,7 +212,7 @@ Your options: ↓ ↑ paused - active ──evaluator score≥0.95 / completeGoal──→ completed (terminal) + active ──all criteria passed / completeGoal──→ completed (terminal) ↓ active ──turns_used / llm_calls exhausted ────→ exhausted (terminal) ↓ @@ -188,7 +232,7 @@ A few deliberate non-features: - **No nested goals / goal trees** — one goal per conversation, no OKR stack - **No "goal templates"** — every goal is hand-written - **No cross-conversation goal migration** — use a [workflow](./workflow) for that -- **No completion score in the UI** — `completionScore` is an internal engineering protocol, not user vocabulary. The UI speaks via a ring; hover reveals the natural-language gap the evaluator wrote. The numeric score stays in logs and the API for debugging +- **No completion score in the UI** — `completionScore` is an internal engineering protocol, not user vocabulary. The UI speaks via a ring; on hover it shows the box-by-box checklist card when there's a checklist, or the natural-language gap text the evaluator wrote when there isn't. The numeric score stays in logs and the API for debugging --- @@ -219,12 +263,18 @@ mateclaw: goal: # Master switch; when off, the graph node passes through for every call. enabled: true + # Create-time default for autoFollowupEnabled when the caller leaves it unset. + default-auto-followup: true + # Runtime master switch; when off, no goal injects a followup regardless of its per-goal flag. + allow-auto-followup: true # Default turn budget when the user doesn't override. default-turn-budget: 20 # Default combined (agent + evaluator) LLM call budget. default-llm-call-budget: 200 # Minimum seconds between two consecutive auto-followups. auto-followup-cooldown-seconds: 0 + # Hard cap on auto-followups within a single graph run (per-message safety net; overall budget is turnBudget). + max-followups-per-run: 8 # Model used by the evaluator. Empty = same model as the chat agent. # Recommended: a cheap model like qwen-turbo / glm-4-flash. evaluator-model: "" diff --git a/mateclaw-server/src/main/resources/docs/en/mcp.md b/mateclaw-server/src/main/resources/docs/en/mcp.md index df8aff4a..19008718 100644 --- a/mateclaw-server/src/main/resources/docs/en/mcp.md +++ b/mateclaw-server/src/main/resources/docs/en/mcp.md @@ -101,7 +101,7 @@ Earlier HTTP transport using SSE for server-to-client push. Legacy compatibility - **URL** (streamable_http/sse) — server endpoint - **HTTP Headers** (streamable_http/sse) — JSON object (e.g., `{"Authorization": "Bearer token"}`) - **Connect timeout** — default 30s -- **Read timeout** — default 30s +- **Read timeout** — default **60s** (raised from 30s in 1.5.0, #247; a single callTool round-trip that legitimately runs longer no longer gets cut off. Each server is tunable 5–300s) Save. If enabled, MateClaw auto-attempts to connect and discover tools. @@ -361,7 +361,7 @@ After each connection operation, results persist: | `cwd` | VARCHAR(512) | NULL | Working directory | | `enabled` | BOOLEAN | TRUE | On/off | | `connect_timeout_seconds` | INT | 30 | HTTP connect timeout | -| `read_timeout_seconds` | INT | 30 | Request response timeout | +| `read_timeout_seconds` | INT | 60 | Request response timeout (default 60 since 1.5.0, was 30) | | `last_status` | VARCHAR(32) | `disconnected` | Last connection status | | `last_error` | TEXT | NULL | Last error message | | `last_connected_time` | DATETIME | NULL | Last successful connection | diff --git a/mateclaw-server/src/main/resources/docs/en/memory.md b/mateclaw-server/src/main/resources/docs/en/memory.md index 3c9ed46b..9e0911a7 100644 --- a/mateclaw-server/src/main/resources/docs/en/memory.md +++ b/mateclaw-server/src/main/resources/docs/en/memory.md @@ -65,6 +65,55 @@ Each layer operates at a different timescale. Short-term is *this turn*. Extract --- +## Memory knows who's who: per-owner isolation (1.5.0) + +Before, an employee's memory was **shared**: whether it was you logged into the web, a colleague in a Feishu group, or an end user coming in through a third-party API, the memory piled into the same `MEMORY.md`. One employee serving multiple people would cross wires. + +1.5.0 gives every memory an **owner** and a **visibility scope**. + +### A unified owner_key + +Whatever the identity source, it normalizes to one prefixed string: + +| Source | owner_key | +|---|---| +| Web console | `user:` | +| IM channel (Feishu / DingTalk / WeCom…) | `:` | +| Third-party API (with endUserId) | `api:` | +| System / cron | `system` | + +### Three visibility scopes + +| scope | Who reads it | Typical content | +|---|---|---| +| **PERSONAL** | Only the matching owner | Memory extracted from conversations defaults here | +| **TEAM** | Everyone using this employee | Agent config files (AGENTS.md / SOUL.md / PROFILE.md), backfilled legacy data | +| **GLOBAL** | Always visible across employees / workspaces | Preset facts, system reference material | + +### Recall prefers personal memory + +The system prompt bakes in only the shared TEAM/GLOBAL memory (cacheable); each turn then **prefetches** that owner's personal memory by owner_key. So when someone asks "what stack does my project use," the employee recalls *that person's* private memory files first, not generic KB material. + +> On the structured "fact" layer: the **fact recall query itself supports owner-visibility filtering** (PERSONAL is owner-only, TEAM/GLOBAL shared). But the current **automatic fact projection** is built mainly from shared memory files and doesn't set `ownerKey/scope` on insert — so personalization shows up more in the personal-memory-file prefetch; per-owner facts are still being filled in. + +### Third-party APIs pass through an end-user identity + +`/api/v1/chat` and `/api/v1/chat/stream` request bodies gain an optional **`endUserId`** field (a string, to preserve large-integer precision). One PAT-authenticated integration represents one MateClaw user but can pass a distinct `endUserId` per end user, and memory isolates per end user automatically. + +### It's a feature flag + +The master switch is `mate.memory.lifecycle-mediator-enabled`. + +::: warning Mind the default +The Java property's bare default is `false`, but the `application.yml` **shipped with the release sets it to `true`** — so per-owner isolation is **on by default in a default install**. To go back to the old shared behavior (all writes to TEAM), set it to `false` explicitly in your config. +::: + +When on: conversation extraction writes to the owner's PERSONAL memory and recall filters by owner_key; when off, all writes fall back to shared TEAM. Multi-tenant instances stay on; single-user deployments can turn it off. + +Under the hood: migration `V137` adds `owner_key` + `scope` columns to `mate_workspace_file` / `mate_memory_recall` / `mate_fact`, backfilling legacy rows as `TEAM` (so no memory gets hidden on upgrade). Memory tools like `remember` resolve owner_key from the current request context — when the flag is on they write to that owner's PERSONAL memory, when off they fall back to shared writes. + +--- + ## Multi-layer memory with pluggable providers The memory layer is not one hard-coded implementation. It's an **interface** — the multi-layer architecture lets you stack providers: @@ -415,6 +464,12 @@ mate: # --- Consolidation / dreaming --- emergence-enabled: true emergence-day-range: 7 + + # --- per-owner memory isolation (1.5.0) --- + # The value shipped with the release is true (on): conversation extraction writes to the owner's + # PERSONAL memory and recall filters by owner_key. Set false for the old shared behavior (all writes + # to TEAM). The bare Java-property default is false. + lifecycle-mediator-enabled: true ``` Prefix: `mate.memory`. diff --git a/mateclaw-server/src/main/resources/docs/en/models.md b/mateclaw-server/src/main/resources/docs/en/models.md index 2d036e52..9effb6f1 100644 --- a/mateclaw-server/src/main/resources/docs/en/models.md +++ b/mateclaw-server/src/main/resources/docs/en/models.md @@ -17,8 +17,8 @@ MateClaw doesn't care which LLM you use. It talks to every mainstream provider t | **Bailian Token Plan** | Bailian token-bundle plan | dashscope | 7 seeded models; long tokens supported | | **OpenAI** | GPT-4o, GPT-4o-mini, GPT-5.5, o1, o3, o4-mini | openai | Standard OpenAI API | | **OpenAI OAuth (ChatGPT Plus/Pro)** | GPT-4o, o3, o4-mini via subscription | openai | Browser-based OAuth — no API key | -| **Anthropic** | Claude 4.7, Claude 4.6 Sonnet, Claude 4.5 Haiku | anthropic | Native Messages API | -| **Anthropic Claude Code OAuth** | Claude 4.7 / 4.6 via Claude Pro/Max/Team subscription | anthropic | Browser OAuth + manual-paste flow — no API key | +| **Anthropic** | **Claude Opus 4.8 / 4.8 Fast** (1.5.0+), Claude 4.7, Claude 4.6 Sonnet, Claude 4.5 Haiku | anthropic | Native Messages API; both 4.8 variants support the `xhigh` thinking tier | +| **Anthropic Claude Code OAuth** | Claude Opus 4.8 / 4.7 / 4.6 via Claude Pro/Max/Team subscription | anthropic | Browser OAuth + manual-paste flow — no API key | | **Google Gemini** _(native)_ | gemini-2.5-flash, gemini-3-pro-image-preview, gemini-2.5-flash-image | gemini | Native `generateContent` API (not OpenAI-compatible) — see "Native Gemini" below | | **xAI / Grok** | Grok 3, Grok 4 | openai | OpenAI-compatible (base URL + API key); xAI brand icon in the UI | | **DeepSeek** | deepseek-chat, deepseek-coder, **DeepSeek V4 flash + pro** (thinking-mode) | openai | OpenAI-compatible | @@ -161,13 +161,13 @@ Enter the user code in your browser, authorize, and the dialog closes itself the If `local` mode can't bind a loopback port (port in use, sandbox refused), it falls through to `manual_paste` automatically. -**Backend endpoints** (`/api/v1/oauth/openai/device`): +**Backend endpoints:** | Method | Path | Purpose | |---|---|---| -| `POST` | `/start` | Begin a session — returns `deviceAuthId`, `userCode`, `verificationUrl`, `intervalSeconds`, `expiresInSeconds` | -| `POST` | `/poll` | Poll one session by `deviceAuthId` — returns `PENDING` / `COMPLETED` / `EXPIRED` | -| `POST` | `/cancel` | Drop the session (e.g. user closed the dialog) | +| `POST` | `/api/v1/oauth/openai/device/start` | Begin a session — returns `deviceAuthId`, `userCode`, `verificationUrl`, `intervalSeconds`, `expiresInSeconds` | +| `POST` | `/api/v1/oauth/openai/device/poll` | Poll one session by `deviceAuthId` — returns `PENDING` / `COMPLETED` / `EXPIRED` | +| `POST` | `/api/v1/oauth/openai/device/cancel` | Drop the session (e.g. user closed the dialog) | The frontend respects the `intervalSeconds` OpenAI returns (typically 5 s); the server enforces a min poll interval (default 3 s) to keep load bounded. Expired sessions are swept every 5 minutes. @@ -392,6 +392,17 @@ Every provider you add joins an `AvailableProviderPool` that's probed at startup - **Egress sanitizer** — provider-specific options (e.g., `reasoning_effort` for OpenAI reasoning models) are stripped at egress when failing over to a provider that doesn't support them, so leaked options can't 400 the fallback - **UI distinguishes 401 from session expiry** — provider auth errors and user session expiry now show different messages with different remediation +### Preferred provider drives the primary model (1.5.0) + +Before 1.5.0, "per-agent priority" only affected the **failover order** — the primary model was still the global default. 1.5.0 makes that preference **actually decide primary-model selection**. The full precedence is: + +1. **A conversation-pinned model wins** — the chat-header ModelSelector bound a model to this conversation, so it's used (see [per-conversation model selection](./chat#per-conversation-model-selection)) +2. **then the per-agent model override (`modelName`)** — the employee has a model pinned on it +3. **then the global default model** +4. **only when none of those are set does preferred-provider routing kick in** — picking the preferred provider's primary model + +Preferred-provider routing has a **capability gate**: if the employee's bound skills declare a need like `requires-model: vision`, routing first picks a provider that can satisfy those modalities; only if none can does it fall back unconstrained. Preferences are stored in `mate_agent_provider_preference` (ascending `sortOrder` = higher priority). + --- ## Configuration via API diff --git a/mateclaw-server/src/main/resources/docs/en/releases.md b/mateclaw-server/src/main/resources/docs/en/releases.md index d29afa68..e297cb4c 100644 --- a/mateclaw-server/src/main/resources/docs/en/releases.md +++ b/mateclaw-server/src/main/resources/docs/en/releases.md @@ -10,6 +10,7 @@ For historical diffs, check the corresponding git tag. For the "why" behind a fe | Version | Date | Highlights | |---------|------|------------| +| [v1.5.0](./releases/1.5.0) | 2026-06-04 | Goals grew a checklist — from "a score" to "ticked boxes" (checklist + Evaluator SPI + deterministic completion) · The Wiki learned to maintain itself (`[[wikilinks]]` + cascade rename/delete link-fix + broken-link lint · fact/experience layers + staleness propagation · pageType profiles & per-agent permissions · processing pipelines · local-directory knowledge source with scheduled incremental sync) · Per-owner memory isolation (owner_key + personal/team/global scopes + third-party endUserId passthrough) · Each employee binds a primary KB · Preferred provider drives the primary model + Claude Opus 4.8 | | [v1.4.0](./releases/1.4.0) | 2026-05-23 | Persistent Goals — an employee locks a goal and follows it to done on its own · Subagent delegation became a tree (recursive 3 levels + async + digital-employee builder) · Progressive tool/skill disclosure (`enable_tool` + `load_skill`) · Workspace RBAC (4 roles + capability gating) · Feishu as a first-class citizen (interactive / approval / streaming cards + voice / file / audio / video + channel-native tools) | | [v1.3.0](./releases/1.3.0) | 2026-05-13 | Year one of workflow — 7 step modes assemble employees into business processes · 6 trigger patterns make events drive workflows · Wiki promoted from search index to processing pipeline (user templates + cross-material aggregator + reverse citations) · Per-agent MCP tool binding + multimodal sidecar routing · 4 JVM-native document generation tools + image edit | | [v1.2.0](./releases/1.2.0) | 2026-05-05 | Agents renamed "digital employees" (role / goal / backstory + 5 career templates) · Skills became the skeleton (manifest + template wizard + LESSONS self-evolution) · ACP integration: Claude Code / Codex now show up as your employees · Admin Runtime Console lets you see every employee working in real time | diff --git a/mateclaw-server/src/main/resources/docs/en/security.md b/mateclaw-server/src/main/resources/docs/en/security.md index 4404f97c..b5a4ea32 100644 --- a/mateclaw-server/src/main/resources/docs/en/security.md +++ b/mateclaw-server/src/main/resources/docs/en/security.md @@ -88,8 +88,8 @@ mateclaw: | Code | Meaning | Response | |------|---------|----------| -| 401 | Token missing, expired, or invalid | `{"code": 401, "message": "Unauthorized"}` | -| 403 | Valid token but insufficient permissions | `{"code": 403, "message": "Forbidden"}` | +| 401 | Token missing, expired, or invalid | `{"code":401,"msg":"Token expired or invalid","data":null}` | +| 403 | Valid token but insufficient permissions | `{"code":403,"msg":"Forbidden","data":null}` | Frontend handles both uniformly — redirect to login, clear stored tokens. @@ -100,8 +100,8 @@ MateClaw ships with `admin` / `admin123`. **Change this immediately in any deplo ### Spring Security config - **Stateless sessions** — no server-side session; all state in the JWT -- **Public endpoints** — `/api/v1/auth/login`, `/h2-console/**`, `/swagger-ui/**` -- **Protected endpoints** — everything else under `/api/v1/**` +- **Public API endpoints** — `GET /api/v1/settings/language`, `/api/v1/auth/login`, `/api/v1/chat/stream`, `/api/v1/chat/*/stop`, `/api/v1/agents/*/chat/stream`, `/api/v1/setup/**`, `/api/v1/channels/webhook/**`, `/api/v1/channels/webchat/**`, `/api/v1/talk/ws`, `/api/v1/files/generated/**` +- **Protected endpoints** — everything else under `/api/**` - **CSRF disabled** — not needed for stateless JWT --- @@ -247,7 +247,7 @@ Frontend shows approval card User clicks Approve or Reject │ ▼ -POST /api/v1/approvals/{id}/resolve +POST /api/v1/chat/stream with /approve or /deny │ ├─ Approved → reload agent, replay tool call, continue reasoning └─ Rejected → send rejection as observation, continue reasoning @@ -255,6 +255,8 @@ POST /api/v1/approvals/{id}/resolve The "replay" mechanism is important. When the agent resumes, it **doesn't re-reason from scratch** — it skips straight to the approved tool call, executes it, and continues from the observation. No duplicate LLM calls, no wasted tokens. +The current web path has no write-style `POST /api/v1/approvals/{id}/resolve` endpoint. Approval and denial use the same SSE channel as normal chat so replay, persistence, and cancellation all stay on one lifecycle. + ### The `mate_tool_approval` table | Column | Purpose | @@ -283,24 +285,28 @@ Pending approvals expire after a configurable timeout (default: 10 minutes). Exp MateClaw can notify through `channel/notification/` adapters — email, in-app alert, DingTalk/Feishu push. Configure in `Settings → Security & Approval → Notifications`. -### Resolving via API +### Current API surface ```bash -# List pending -curl http://localhost:18088/api/v1/approvals?status=pending \ +# Hydrate pending approvals after a page refresh +curl http://localhost:18088/api/v1/chat/{conversationId}/pending-approvals \ -H "Authorization: Bearer " -# Approve -curl -X POST http://localhost:18088/api/v1/approvals/123/resolve \ +# Approve in the waiting conversation +curl -N -X POST http://localhost:18088/api/v1/chat/stream \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ - -d '{"decision": "approved"}' + -d '{"agentId":"1","conversationId":"conv-abc123","message":"/approve"}' -# Reject with reason -curl -X POST http://localhost:18088/api/v1/approvals/123/resolve \ +# Reject in the waiting conversation +curl -N -X POST http://localhost:18088/api/v1/chat/stream \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ - -d '{"decision": "rejected", "notes": "Not appropriate for this workspace"}' + -d '{"agentId":"1","conversationId":"conv-abc123","message":"/deny"}' + +# Manage auto-approval grants +curl http://localhost:18088/api/v1/approval/grants \ + -H "Authorization: Bearer " ``` --- diff --git a/mateclaw-server/src/main/resources/docs/en/skills.md b/mateclaw-server/src/main/resources/docs/en/skills.md index 6820b64b..71dbb98b 100644 --- a/mateclaw-server/src/main/resources/docs/en/skills.md +++ b/mateclaw-server/src/main/resources/docs/en/skills.md @@ -532,6 +532,18 @@ When disabled, the catalog guidance points at `readSkillFile` instead and `load_ --- +## The `/skill` slash menu in chat (new in 1.5.0) + +Don't want to prompt the employee in natural language about which skill to use? Type `/` in the chat composer to open a **searchable skill picker**: + +- ↑↓ to move, Enter/Tab to select, Esc to close; typing filters the enabled skills live (up to 8 shown). +- The list comes from `GET /api/v1/skills/enabled` — real skills plus MCP/ACP-derived virtual skills (a real skill shadows a same-named virtual one). Cached per workspace for 30 seconds so reopening doesn't re-fetch. +- Selecting a skill inserts a directive into the box: `Use the "skill name" skill: `, cursor at the end, ready for you to add context and send. The employee sees the directive in message history and runs `load_skill` to pull it. + +The menu shows whenever **an employee is selected and that employee hasn't disabled skills** (the frontend checks `currentAgent && !skillsDisabled`) — it is unrelated to the global progressive-disclosure switch. Setting `mateclaw.skill.disclosure.load-skill-tool.enabled` to `false` globally only stops the backend from registering the `load_skill` tool; the menu still opens (the employee just falls back to pulling skills via `readSkillFile` and similar). + +--- + ## Skill lifecycle curator (new in v1.4) Agents that synthesize skills accumulate cruft — a one-off skill from three weeks ago is still in the catalog, eating a slot. The **curator** is a daily sweep that ages idle, **agent-created** skills through `active → stale → archived` and gets them out of the way without deleting anything. diff --git a/mateclaw-server/src/main/resources/docs/en/tools.md b/mateclaw-server/src/main/resources/docs/en/tools.md index 7e3a8c43..c454cf51 100644 --- a/mateclaw-server/src/main/resources/docs/en/tools.md +++ b/mateclaw-server/src/main/resources/docs/en/tools.md @@ -324,14 +324,14 @@ curl -X PUT http://localhost:18088/api/v1/tools/1 \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{"enabled": false}' -# Test a tool directly -curl -X POST http://localhost:18088/api/v1/tools/WebSearchTool/test \ +# Set disclosure tier for a builtin or channel tool +curl -X PUT http://localhost:18088/api/v1/tools/1/disclosure-tier \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ - -d '{"query": "Spring AI"}' + -d '{"tier": "core"}' ``` -Every provider-backed tool has a test button in the Tools page so you can verify API keys before shipping. +The current REST API manages tool rows, enabled state, and disclosure tier. Direct execution of builtin tools happens through the agent runtime, not through a `/tools/{name}/test` endpoint. --- diff --git a/mateclaw-server/src/main/resources/docs/en/wiki.md b/mateclaw-server/src/main/resources/docs/en/wiki.md index 683024ce..2c1a90ee 100644 --- a/mateclaw-server/src/main/resources/docs/en/wiki.md +++ b/mateclaw-server/src/main/resources/docs/en/wiki.md @@ -258,6 +258,8 @@ Bind an agent to a knowledge base from `Agents → [your agent] → Knowledge`. | `wiki_related_pages` | Related-page discovery across four signals (shared chunks, shared raws, direct links, semantic neighbors). | | `wiki_explain_relation` | Score breakdown for the relationship between two pages. | | `wiki_create_page` / `wiki_delete_page` | Direct page management; deletion respects `locked` / `system`. | +| `wiki_update_page` | **1.5.0**: in-place edit of a page (keeps the slug), gated by the pageType "update" permission. | +| `wiki_stale_pages` | **1.5.0**: list every page currently flagged for review (`stale`). | | `wiki_archive_page` / `wiki_unarchive_page` | Soft-archive: hide a page from default list/search/related results without destroying it. Citations and source lineage survive; recoverable. System pages can't be archived. | | `wiki_list_transformations` | List the transformation templates available to this KB (name, intent, whether apply-default is on). | | `wiki_apply_transformation` | Run a template against one **raw material**; returns the output, run id, and saved-page info. | @@ -299,13 +301,11 @@ The injection is gated by the `wiki.hot_cache.enabled` feature flag (off → emp #### Operator endpoints -Base path `/api/v1/wiki/hot-cache`: - | Method | Path | What it does | |---|---|---| -| `GET` | `/{kbId}` | Current snapshot + meta | -| `POST` | `/{kbId}/regenerate` | Manual rebuild (async, ignores debounce) | -| `DELETE` | `/{kbId}` | Soft-delete; rebuilds on next event | +| `GET` | `/api/v1/wiki/hot-cache/{kbId}` | Current snapshot + meta | +| `POST` | `/api/v1/wiki/hot-cache/{kbId}/regenerate` | Manual rebuild (async, ignores debounce) | +| `DELETE` | `/api/v1/wiki/hot-cache/{kbId}` | Soft-delete; rebuilds on next event | The hot cache lives in `mate_wiki_hot_cache` — see the **Data model** section below for the exact columns. @@ -342,6 +342,211 @@ Edit when the AI got it wrong. Your edits survive the next ingest — `locked` t --- +## Wikilinks and broken-link care + +Cross-page references via `[[slug]]` are the connective tissue of a +long-lived knowledge asset. RFC 55 turns this layer from "writing +`[[Title]]` looked fine until you clicked and got a 404" into **lint on +write, cascade on delete, broken links visible everywhere**. + +### Wikilink syntax + +Exactly one contract is honoured: + +- `[[slug]]` — visible label defaults to the target page's title +- `[[slug|display text]]` — explicit label, the slug is still the + navigation target + +The slug must reference an existing page. The LLM page-generation +prompts give the model a slug-first index (`- [[slug]] — Title — Summary`), +forbid inventing slugs that aren't in the index, and explicitly warn +that older `[[Page Title]]` form will be flagged as a dead link by the +lint. + +Case-insensitive: `[[STATEGRAPH]]` and `[[stategraph]]` both resolve +via lowercased exact match against `page.slug`. + +### In-transaction lint: `outgoing_links` + `broken_links` + +Every page save (manual edit, AI generation, merge, cascade rewrite) +runs in one transaction: + +1. Extract every `[[...]]` from the body (skipping fenced and inline + code blocks) +2. Write `mate_wiki_page.outgoing_links` (deduped, lowercased string + array) +3. Diff against the KB's active slug set (archived pages excluded) + to produce `broken_links` +4. Stamp `broken_links_scanned_at` + +You see which `[[...]]` are dead the moment the page saves — no +batch scan required. Code blocks and inline `` `[[...]]` `` snippets +are preserved verbatim and never enter `outgoing_links` (so a page +that teaches wikilink syntax doesn't accidentally lint itself). + +### KB-wide broken-link scan + +Each KB shows a banner at the top of the workspace. Click "Scan dead +links" to start a job: + +| Method | Path | What it does | +|---|---|---| +| `POST /api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links` | Starts a job (async, job-based). Returns `{jobId, status, startedAt}`. Idempotent — repeat POSTs while a job is in flight return the same id | +| `GET .../lint/broken-links` | Returns the latest completed scan as a per-page aggregate | +| `GET .../lint/broken-links/jobs/{jobId}` | Status check for a specific job | + +The aggregate carries `pageId / slug / title / brokenRefs` for each +affected page. The banner distinguishes "scanned X pages, no broken +links" from "found N broken links in M pages". Clicking "view" opens +a panel listing each broken ref with a jump-to-source-page action. + +Performance: 100-page KB scans in well under a second; POST submit +latency under 200ms. + +### Cascade delete and rename + +**Delete a page**: every other page that linked to it gets its +`[[deleted-slug]]` rewritten to plain text (using the snapshot title +as the visible word). Aliased `[[deleted-slug|some alias]]` collapses +to just the alias. Referrers' `outgoing_links` and `broken_links` are +recomputed in the same transaction. + +**Rename a page**: `POST /api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/rename` +with `{"newSlug":"new"}`. In one transaction: + +- The page's own slug is updated +- Every referrer's `[[oldSlug]]` becomes `[[newSlug]]`, and + `[[oldSlug|alias]]` becomes `[[newSlug|alias]]` (alias preserved + byte-for-byte) +- Referrers' `outgoing_links` is updated + +Rejected: empty slug, slug equal to the current slug, slug already +owned by another page in the same KB, target page is protected +(system / locked). Case-only renames (`foo → FOO`) are allowed and +behave the same on H2 and MySQL. + +Each delete / rename writes an audit row to `mate_audit_event` with +`action=wiki.page.delete` or `wiki.page.rename`. `detailJson` carries +an `affectedPageIds` list so the cascade impact is queryable after +the fact. + +Emergency kill-switch: set `mate.wiki.cascade-delete-enabled=false` +to revert to the legacy row-only delete (the rewrite is bypassed, +referrer wikilinks dangle). Default-on is the intended steady state. + +### Click-through from chat + +When the chat renders an agent reply, `[[slug]]` and `[[slug|alias]]` +tokens in the content become `` +anchors. Clicking one: + +1. The app-level global click delegator catches the click +2. Calls `GET /api/v1/wiki/pages/lookup?title=X&slug=X` — searches + every KB visible to the user (slug match first, title fallback) +3. 1 hit → `router.push` into the wiki view, auto-selects the KB, + auto-opens the page +4. 0 hits → toast "未找到匹配的 wiki 页面：X" +5. >1 hits → picker offering to open the first match + +No more navigating to the wiki view, finding the KB, finding the +page — clicking a `[[link]]` in chat gets you there directly. The +lookup is strict case-insensitive exact (no canonical fuzzing), so +if the LLM wrote a slug that doesn't exist you see the toast rather +than getting silently redirected to a similarly-named page. + +### Phase roadmap (all phases landed) + +| Phase | Key changes | +|---|---| +| 1 | Frontend slug-first DOM postprocess; dangerous-char guard; full `pages/refs` index decoupled from raw-material filter | +| 2 | V129 migration adds `broken_links` and `broken_links_scanned_at`; save-path writes them in the same transaction; KB-wide async lint job + banner | +| 3 | All 9 wiki prompt templates unified on `[[slug]]` contract; existing-pages index reformatted slug-first; batch-create splits existing pages from same-batch planned pages | +| 4 | Cascade delete and rename rewrite referrers in-transaction; audit log; feature flag | +| 5 | Analyze stage emits a `related_pages` slug whitelist (validated server-side); enrich applier skips code blocks and gates on the whitelist | + +Full design and live verification live in the matching design doc and +end-to-end verification record in the repository. + +--- + +## The knowledge base maintains itself (1.5.0) + +1.5.0 pushes the Wiki from "a searchable knowledge base" into "a knowledge engine that maintains its own consistency, layers itself, runs its own pipelines, and can mount a local directory." The management surface for all of this is the **Wiki advanced panel** in the admin console (five sub-pages: page-type profile / layers & staleness / permissions / source watcher / pipelines). + +### Knowledge layers: fact vs experience + +Each page can carry a **knowledge layer**: + +- **`fact`** — "what is": foundational fact pages. Unlabeled defaults to fact. +- **`experience`** — "what it means": synthesis, analysis, insight, which **depends on** a set of fact pages. + +**Staleness propagates.** An experience page declares which fact pages it depends on (edges stored by page **id**, so renames don't break them). When a fact page is updated during ingest, every experience page depending on it is auto-marked `stale` (needs review) + a reason. The `wiki_stale_pages` tool lists everything currently flagged; search can **filter by knowledge layer** (facts only / experience only / all). + +Under the hood: `mate_wiki_page` gains `knowledge_layer` / `depends_on_json` / `stale` / `stale_reason_json` columns (migration V135), with dependency edges in `mate_wiki_page_dependency` and a reverse index dedicated to stale propagation. + +### Page-type profiles (pageType profile) + +Define which **page types** a KB has (e.g. "concept / tutorial / decision record"), each carrying: + +- A structured-field **schema** — page metadata is validated against it on save, with the validation status recorded (valid / invalid + details) +- **route / create / merge**-stage prompts — injected into the corresponding LLM call +- A **Markdown template** — the skeleton used when generating the page + +At most one **enabled** profile per KB; unconfigured KBs use a **built-in default**. Profiles are written in YAML or JSON, with "validate (no save)" and "reset to default" actions. Stored in `mate_wiki_page_type_profile` (migration V134); the page metadata columns (`metadata_json` / `metadata_validation_status` / `template_key` / `profile_version`) are added to `mate_wiki_page` in the same migration. + +### Page-type permissions (per-agent) + +For "**this agent + this KB + this page type**" you can set read / create / update / delete flags plus a **write policy**: + +| Write policy | Meaning | +|---|---| +| `allow` | Write immediately | +| `approval_required` | Write is held pending [approval](./security) | +| `deny` | Blocked | + +`page_type='*'` is the KB-wide default; **exact matches beat the wildcard**. + +**Read and write fall back differently** — keep them distinct: + +- **Read** — when no rule matches, read falls back to the **KB-level default read policy** `defaultReadPolicy` (`allow_all` unless the KB sets `deny_all`). So existing KBs stay fully readable after upgrade. Read gating filters lists and search results; an unreadable type is treated as nonexistent (no existence leak). +- **Write** — write is opt-in tightened. An agent with **no rules** for a KB writes `allow` (old behavior); add **any** rule and that KB enters "locked down" mode — page types with no matching rule resolve to `deny` (fail-safe). + +Stored in `mate_wiki_agent_page_type_permission` (migration V133). + +### Processing pipelines (Wiki Pipeline) + +Define a processing flow for a KB, fired automatically by **page events**: + +- **Triggers**: `page_type_count` (a page-type count crosses a threshold), `page_created` (a page of a given type is created), `stale_marked` (pages get flagged stale) +- **Step executors**: + - `llm` — run input through the model; the output becomes the step result + - `skill` — run a skill from a **restricted set**, as the owner agent + +Definitions are written in YAML or JSON, with CRUD + validate endpoints. Every run and every step is persisted and queryable, deduplicated by `(definition, trigger, subject, bucket)` for idempotency. Tables: `mate_wiki_pipeline_definition` / `mate_wiki_pipeline_run` / `mate_wiki_pipeline_step_run` (migration V136). + +### Mount a local directory as a knowledge source — pluggable + scheduled incremental + +Knowledge sources are a **pluggable SPI** (`WikiIngestSourceProvider`) with a built-in filesystem provider: give a KB a `source_directory` and files in it get ingested. + +- **Scheduled incremental sync** — a background scheduler (with a distributed lock so only one node runs per cycle) scans periodically, detects changes **by content hash**, and re-ingests only new/modified files (text and binary). +- **Fail-closed security** — paths are normalized then symlink-resolved (closing TOCTOU) and validated against an allowed-roots allowlist; under the production profile an empty allowlist rejects everything. Set the `mate.wiki.allowed-source-roots` allowlist. +- **Status + manual trigger** — `GET .../source-watcher` shows status, `POST .../source-watcher/scan` runs a scan immediately. + +Relevant config (`application.yml`): + +```yaml +mate: + wiki: + watcher-enabled: false # master switch for the source watcher + watcher-interval-ms: 300000 # scan interval (default 5 min) + allowed-source-roots: [] # allowed source-directory roots (allowlist) + require-allowed-roots: false # production: set true so an empty allowlist rejects everything +``` + +All new REST endpoints are in the [API Reference](./api#llm-wiki). + +--- + ## Search, source tracing, and semantic retrieval - **Semantic search** — ask "what did we decide about auth?" and get the decision, not pages containing "auth". Chunk-level embeddings with cosine retrieval — it understands what you mean. Hits now include `pageNumber` and `section`, so the agent can quote "page 12, Setup / Linux" instead of a free-floating snippet. diff --git a/mateclaw-server/src/main/resources/docs/en/workspaces.md b/mateclaw-server/src/main/resources/docs/en/workspaces.md index f0628f0b..8ff94ad4 100644 --- a/mateclaw-server/src/main/resources/docs/en/workspaces.md +++ b/mateclaw-server/src/main/resources/docs/en/workspaces.md @@ -261,7 +261,7 @@ curl -X POST http://localhost:18088/api/v1/workspaces/1/members \ curl -X DELETE http://localhost:18088/api/v1/workspaces/1/members/42 \ -H "Authorization: Bearer " -curl -X PUT http://localhost:18088/api/v1/workspaces/1/members/42/role \ +curl -X PUT http://localhost:18088/api/v1/workspaces/1/members/42 \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"role": "admin"}' diff --git a/mateclaw-server/src/main/resources/docs/zh/agents.md b/mateclaw-server/src/main/resources/docs/zh/agents.md index a2feb22c..d880e9bf 100644 --- a/mateclaw-server/src/main/resources/docs/zh/agents.md +++ b/mateclaw-server/src/main/resources/docs/zh/agents.md @@ -215,6 +215,41 @@ UI 入口：`Agents → 选员工 → 工具`。 技术细节见 [MCP](./mcp#per-agent-工具绑定)。 +### 知识库绑定（per-agent 主知识库） + +::: tip 1.5.0 新增 +员工编辑器新增"知识库"标签页，可以为每个员工指定一个**主知识库**。知识库本身仍是工作空间共享资源，绑定只是声明"我默认查哪一个"——不影响其他员工的访问。 +::: + +**简单版本：每个员工可以指定一个"主知识库"作为它默认查的 KB。可以不指定。** + +要点（这是设计模型，看完省得困惑）： + +- **知识库是工作空间共享的。** 一个 KB 创出来就归属当前 workspace，workspace 里所有员工都看得见。给员工"绑"一个 KB 不会把它变成专属——其他员工照样能调 +- **"主知识库"只是一个默认值。** 它告诉 wiki 工具（`wiki_search` / `wiki_read` / `wiki_backlinks` ...）："不显式说 `kbName` / `kbId` 时，默认去这个 KB" +- **多个员工可以选同一个 KB 作主库。** 互不影响，谁切谁的，KB 本身不动 +- **不绑也行。** 没指定主库时，运行时按 workspace 里最近更新的 KB 兜底 + +UI 入口：`员工 → 选员工 → 编辑 → 知识库`。 + +| 选项 | 行为 | +|------|------| +| **🚫 未指定主库** | 清空绑定；下次员工的 wiki 工具不带 `kbName` 时，按 workspace 最近活跃 KB 回退 | +| **📚 <KB 名>** | 设这个 KB 为主库；之后 wiki 工具默认查它，列表上同时显示页面数 | + +每个 KB 行展示：图标、名字、描述、页面数。列表内容就是当前 workspace 里所有 KB 的完整集合（包括已被其他员工选作主库的）。 + +#### 运行时怎么解析"该读哪个 KB" + +员工调 wiki 工具时，解析顺序如下： + +1. 工具调用显式带了 `kbName` / `kbId`——直接用那个 +2. 没显式说 → 看员工的 `primaryKbId`，命中则用它 +3. `primaryKbId` 也没有 → 在 workspace 可见 KB 集合里取最近更新的那个 +4. workspace 一个 KB 都没有 → 工具返回空，员工 LLM 自己判断要不要换思路 + +迁移备注：早期版本的"绑定"是写在 `mate_wiki_knowledge_base.agent_id` 上的（一对一独占语义）。从 V130 迁移开始，所有老的 `kb.agent_id` 都被回填到 `agent.primary_kb_id`，老字段保留作 fallback 读取，但新的写入只走 `agent.primary_kb_id`。如果你之前依赖"KB 只给某个 agent 看"的隔离，请到员工管理面板重新审视一遍——KB 现在对 workspace 内全员可见。 + ### System Prompt 最佳实践 System prompt 是数字员工的声音、优先级、约束的来源。**角色 / 目标 / 背景故事**和技能指令、工作空间记忆系统会自动拼接到最终 prompt 里——这些部分你不用自己写。 diff --git a/mateclaw-server/src/main/resources/docs/zh/ambient-ai.md b/mateclaw-server/src/main/resources/docs/zh/ambient-ai.md index ec7cf952..f5e8cdc9 100644 --- a/mateclaw-server/src/main/resources/docs/zh/ambient-ai.md +++ b/mateclaw-server/src/main/resources/docs/zh/ambient-ai.md @@ -153,11 +153,15 @@ curl http://localhost:18088/api/v1/cron-jobs \ -H "Authorization: Bearer " # 立刻试跑一次（不影响下次定时触发） -curl -X POST http://localhost:18088/api/v1/cron-jobs/{id}/run-now \ +curl -X POST http://localhost:18088/api/v1/cron-jobs/{id}/run \ -H "Authorization: Bearer " -# 看历史执行 -curl http://localhost:18088/api/v1/cron-jobs/{id}/runs \ +# 查看单个定时任务的执行历史 +curl http://localhost:18088/api/v1/dashboard/cron-runs/{id} \ + -H "Authorization: Bearer " + +# 查看当前工作区最近执行历史 +curl http://localhost:18088/api/v1/dashboard/cron-runs \ -H "Authorization: Bearer " ``` diff --git a/mateclaw-server/src/main/resources/docs/zh/api.md b/mateclaw-server/src/main/resources/docs/zh/api.md index f67c6c76..6f3cace5 100644 --- a/mateclaw-server/src/main/resources/docs/zh/api.md +++ b/mateclaw-server/src/main/resources/docs/zh/api.md @@ -1,35 +1,42 @@ # API 参考 -所有 REST 端点前缀 `/api/v1/`。所有响应遵循同一个信封格式： +本页以 `mateclaw-server/src/main/java` 下的 Spring MVC Controller 注解为准。下面的路由索引由源码注解重建；如果它和旧功能页冲突，以本页和源码为接口契约。 + +## 全局契约 + +应用 REST 端点默认使用 `/api/v1` 前缀。大多数 JSON 响应使用项目统一信封： ```json { "code": 200, - "message": "success", - "data": { } + "msg": "success", + "data": {} } ``` -除了 `/api/v1/auth/login`，所有端点都需要 `Authorization` header 里带 JWT： +例外： -``` -Authorization: Bearer -``` +- 流式端点（`text/event-stream`）返回 SSE frame，不走 JSON 信封。 +- 下载类端点，例如 `/api/v1/files/generated/{id}`、聊天附件、Wiki 原始材料下载，返回字节或 `ResponseEntity`。 +- 少量需要客户端按 HTTP 状态码分支的冲突/确认流程会返回独立结构体。 -深入的行为细节去读对应的功能页——[聊天与消息](./chat)、[Agent 引擎](./agents)、[工具系统](./tools)、[安全与审批](./security)、[LLM Wiki](./wiki)、[多模态创作](./multimodal)、[记忆系统](./memory)、[多渠道接入](./channels)、[模型配置](./models)、[工作空间](./workspaces)、[目标](./goals)、[Doctor](./doctor)。 - ---- +后端 Snowflake `Long` ID 会序列化成 JSON 字符串。前端和第三方客户端都应把 ID 全程当字符串处理。 ## 认证 -``` -POST /api/v1/auth/login # 登录，获取 JWT -GET /api/v1/users/me # 获取当前用户 -PUT /api/v1/users/me # 更新个人资料 -PUT /api/v1/users/me/password # 修改密码 +`POST /api/v1/auth/login` 返回 JWT。受保护接口请求头： + +```text +Authorization: Bearer ``` -**登录示例：** +`SecurityConfig` 中放行的公共路径包括登录、首次初始化、webhook/webchat 回调、chat stream/stop、agent stream、talk WebSocket、`GET /api/v1/settings/language`，以及 `/api/v1/files/generated/**` 一次性生成文件下载。认证通过后，`@RequireWorkspaceRole`、`@RequireGlobalAdmin` 等角色约束仍会继续生效。 + +工作空间接口通常接受 `X-Workspace-Id`。省略时，很多 handler 会为了桌面/本地兼容回退到 workspace `1`。 + +## 常用接口 + +### 登录 ```bash curl -X POST http://localhost:18088/api/v1/auth/login \ @@ -37,513 +44,640 @@ curl -X POST http://localhost:18088/api/v1/auth/login \ -d '{"username":"admin","password":"admin123"}' ``` -响应： - -```json -{ - "code": 200, - "data": { - "token": "eyJhbGciOiJIUzI1NiJ9...", - "tokenType": "Bearer", - "expiresIn": 86400 - } -} -``` - ---- - -## 聊天 - -``` -POST /api/v1/chat/{agentId}/message # 发送消息 -GET /api/v1/chat/{agentId}/stream?conversationId= # SSE 流式 -POST /api/v1/chat/{conversationId}/stop # 停止进行中的流 -GET /api/v1/chat/{conversationId}/pending-approvals # 列出等待的审批 -``` - -**发送消息：** +### 聊天 ```bash -curl -X POST http://localhost:18088/api/v1/chat/1/message \ - -H "Authorization: Bearer YOUR_TOKEN" \ +curl -N -X POST http://localhost:18088/api/v1/chat/stream \ + -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ - -d '{"content":"你好，你能做什么？", "conversationId":"conv-abc123"}' + -H "Accept: text/event-stream" \ + -d '{"agentId":"1","message":"你好","conversationId":"conv-abc123"}' ``` -**SSE 流式示例：** +`/chat/stream` 是 POST SSE；浏览器原生 `EventSource` 不能带 POST body，请用 `fetch()` 读取流。 -```bash -curl -N http://localhost:18088/api/v1/chat/1/stream?conversationId=conv-abc123 \ - -H "Authorization: Bearer YOUR_TOKEN" -``` +### 工具审批 -事件类型和 schema 在 [聊天与消息](./chat) 里。 +当前没有 `POST /api/v1/approvals/{id}/resolve` REST 端点。Web 端批准/拒绝通过等待中的会话发送 `/approve` 或 `/deny`，走 chat stream replay 流程。刷新页面后的只读补水接口仍是 `GET /api/v1/chat/{conversationId}/pending-approvals`。自动批准策略在 `/api/v1/approval/grants` 下管理。 + +### Doctor / 健康检查 + +当前后端健康接口是 `GET /api/v1/system/health`。旧文档里的 `/api/v1/doctor/*` 端点在当前源码中没有实现。 + +### 多模态生成 + +图片、视频、音乐、3D 生成是 Agent 工具（`image_generate`、`video_generate`、`music_generate`、`model3d_generate`），不是独立的 `/api/v1/image`、`/api/v1/video`、`/api/v1/music` REST Controller。当前存在的相关 REST 面是 TTS/STT 和生成文件下载。 + +### 非 REST 端点 + +`/api/v1/talk/ws` 由 `WebSocketConfig` 注册，用于 Talk Mode。它会出现在 `SecurityConfig` 的公共 WebSocket 路由里，但不计入下面的 controller 路由索引。 + +## 源码对齐路由索引 + +抽取到的路由总数：406。 + +### 认证 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/auth/login` | `用户登录` | +| `GET` | `/api/v1/auth/tokens` | `List my PATs (metadata only — plaintext is never returned after creation)` | +| `POST` | `/api/v1/auth/tokens` | `Mint a new PAT — returned plaintext is shown once and cannot be recovered` | +| `DELETE` | `/api/v1/auth/tokens/{id}` | `Revoke a PAT — soft-delete; further auth attempts with this token will fail` | +| `GET` | `/api/v1/auth/users` | `获取用户列表` | +| `POST` | `/api/v1/auth/users` | `创建用户` | +| `PUT` | `/api/v1/auth/users/{id}/password` | `修改密码` | + +### 聊天 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/chat` | `同步对话` | +| `GET` | `/api/v1/chat/files/{conversationId}/{storedName:.+}` | `读取聊天附件` | +| `POST` | `/api/v1/chat/stream` | `结构化 SSE 流式对话（支持重连）` | +| `POST` | `/api/v1/chat/upload` | `上传聊天附件` | +| `POST` | `/api/v1/chat/{conversationId}/interrupt` | `排队后续消息（不打断当前流）` | +| `GET` | `/api/v1/chat/{conversationId}/pending-approvals` | `查询待审批记录` | +| `POST` | `/api/v1/chat/{conversationId}/stop` | `停止流式生成` | ### 会话 -``` -GET /api/v1/conversations # 列表（?page&size&agentId） -GET /api/v1/conversations/page?page=&size=&keyword= # 分页会话（带关键词搜索） -GET /api/v1/conversations/{id}/messages # 取消息 -PUT /api/v1/conversations/{id}/model # 设置该会话使用的模型 -DELETE /api/v1/conversations/{id} # 删除 -DELETE /api/v1/conversations/{id}/messages # 清空消息 -GET /api/v1/conversations/{id}/status # 会话状态 -``` - ---- - -## Agent - -``` -GET /api/v1/agents # 列表（分页） -GET /api/v1/agents/{id} # 获取 -POST /api/v1/agents # 创建 -PUT /api/v1/agents/{id} # 更新（部分） -DELETE /api/v1/agents/{id} # 软删除 - -GET /api/v1/agents/{id}/chat/stream?message=...&conversationId=... # 流式对话 - -GET /api/v1/agents/{id}/workspace/files # 列文件 -GET /api/v1/agents/{id}/workspace/files/{filename} # 取内容 -PUT /api/v1/agents/{id}/workspace/files/{filename} # 写入 -DELETE /api/v1/agents/{id}/workspace/files/{filename} # 删除 -GET /api/v1/agents/{id}/workspace/prompt-files # 哪些文件被注入 -PUT /api/v1/agents/{id}/workspace/prompt-files # 设置注入的文件列表 - -GET /api/v1/agents/{agentId}/workspace/memory/export # 导出记忆快照 -POST /api/v1/agents/{agentId}/workspace/memory/import/preview # 预览导入（不落库） -POST /api/v1/agents/{agentId}/workspace/memory/import # 导入记忆快照 - -GET /api/v1/agents/templates # 列出模板 -POST /api/v1/agents/templates/{id} # 从模板创建 -``` - ---- - -## 工具 - -``` -GET /api/v1/tools # 列表 -PUT /api/v1/tools/{id} # 更新 -PUT /api/v1/tools/{id}/toggle?enabled={bool} # 开关 -PUT /api/v1/tools/{id}/disclosure-tier # 设置披露层级（core / extension） -POST /api/v1/tools/{name}/test # 直接测试 -``` - ---- - -## 技能 - -``` -GET /api/v1/skills # 列表（?type=builtin|custom|mcp&tag=...） -GET /api/v1/skills/{id} # 获取 -POST /api/v1/skills # 创建 -PUT /api/v1/skills/{id} # 更新 -DELETE /api/v1/skills/{id} # 删除 -PUT /api/v1/skills/{id}/toggle?enabled={bool} # 开关 -GET /api/v1/skills/runtime/active # 当前活跃的技能 -GET /api/v1/skills/runtime/status # 运行时状态 -POST /api/v1/skills/runtime/refresh # 重载运行时 -``` - ---- - -## MCP 服务 - -``` -GET /api/v1/mcp/servers # 列表 -GET /api/v1/mcp/servers/{id} # 获取 -POST /api/v1/mcp/servers # 创建 -PUT /api/v1/mcp/servers/{id} # 更新（PATCH 语义） -DELETE /api/v1/mcp/servers/{id} # 删除 -PUT /api/v1/mcp/servers/{id}/toggle?enabled={bool} # 开关 -POST /api/v1/mcp/servers/{id}/test # 测试连接 -POST /api/v1/mcp/servers/refresh # 刷新所有 -``` - -请求体 schema 见 [MCP 协议](./mcp)。 - ---- - -## LLM Wiki - -``` -GET /api/v1/wiki/kbs # 列知识库 -POST /api/v1/wiki/kbs # 创建 KB -GET /api/v1/wiki/kbs/{id} # 获取 KB 详情 -PUT /api/v1/wiki/kbs/{id} # 更新 KB -DELETE /api/v1/wiki/kbs/{id} # 删除 KB - -POST /api/v1/wiki/kbs/{kbId}/raw # 上传原始材料 -GET /api/v1/wiki/kbs/{kbId}/raw # 列原始材料 -DELETE /api/v1/wiki/raw/{id} # 删除原始材料 -POST /api/v1/wiki/raw/{id}/reprocess # 重新消化 - -GET /api/v1/wiki/kbs/{kbId}/pages # 列页面 -GET /api/v1/wiki/pages/{id} # 获取页面 -PUT /api/v1/wiki/pages/{id} # 编辑页面 -DELETE /api/v1/wiki/pages/{id} # 删除页面 -POST /api/v1/wiki/pages/{id}/lock # 锁定页面 -POST /api/v1/wiki/pages/{id}/unlock # 解锁 - -GET /api/v1/wiki/kbs/{kbId}/search?q=... # 全文搜索 -GET /api/v1/wiki/pages/{id}/backlinks # 反向链接 -``` - -Agent 可调的 wiki 工具（`wiki_search`、`wiki_read`、`wiki_backlinks`）自动解析 `kbId`。 - ---- - -## 多模态 - -``` -POST /api/v1/image/generate # 生成图像 -POST /api/v1/image/edit # 编辑图像 -POST /api/v1/video/generate # 生成视频 -POST /api/v1/video/from-image # 图生视频 -POST /api/v1/music/generate # 生成音乐 -POST /api/v1/tts/synthesize # 文本转语音 -POST /api/v1/stt/transcribe # 语音转文本 - -GET /api/v1/image/jobs/{id} # 查异步图像任务状态 -GET /api/v1/video/jobs/{id} # 查异步视频任务状态 -``` - -见 [多模态创作](./multimodal)。 - ---- - -## 记忆 - -``` -POST /api/v1/memory/{agentId}/emergence # 手动触发整合 -POST /api/v1/memory/{agentId}/summarize/{conversationId} # 手动触发提取 -GET /api/v1/memory/{agentId}/dreaming/status # 上次/下次运行 + 最新 DREAMS.md 条目 -``` - ---- - -## 安全与审批 - -### Tool Guard 规则 - -``` -GET /api/v1/security/guard/config # 全局配置 -PUT /api/v1/security/guard/config # 更新全局配置 -GET /api/v1/security/guard/rules # 列自定义规则 -GET /api/v1/security/guard/rules/builtin # 列内置规则 -POST /api/v1/security/guard/rules # 创建规则 -PUT /api/v1/security/guard/rules/{id} # 更新规则 -DELETE /api/v1/security/guard/rules/{id} # 删除规则 -PUT /api/v1/security/guard/rules/{id}/toggle?enabled={bool} # 开关规则 -``` - -### File Guard - -``` -GET /api/v1/security/guard/config/file-guard # 获取配置 -PUT /api/v1/security/guard/config/file-guard # 更新配置 -``` - -### 审批 - -``` -GET /api/v1/approvals?status=pending # 列 pending 审批 -POST /api/v1/approvals/{id}/resolve # 批准或拒绝 -``` - -请求体： - -```json -{ "decision": "approved" } -``` - -或 - -```json -{ "decision": "rejected", "notes": "原因" } -``` - -### 审计日志 - -``` -GET /api/v1/security/audit/logs # 查询（?toolName, ?decision, ?from, ?to） -GET /api/v1/security/audit/stats # 统计 -GET /api/v1/audit/events # 完整审计事件查询 -``` - ---- - -## 模型 - -``` -GET /api/v1/models # 列出模型 -GET /api/v1/models/enabled # 仅列已启用 -GET /api/v1/models/default # 默认模型 -GET /api/v1/models/active # 活跃模型 -PUT /api/v1/models/active # 设置活跃 -POST /api/v1/models # 创建模型配置 -PUT /api/v1/models/{id} # 更新 -DELETE /api/v1/models/{id} # 删除 -POST /api/v1/models/{id}/default # 设为默认 - -PUT /api/v1/models/{providerId}/config # 更新供应商配置 -POST /api/v1/models/custom-providers # 创建自定义供应商 -DELETE /api/v1/models/custom-providers/{providerId} # 删除自定义供应商 - -POST /api/v1/models/{providerId}/models # 往供应商加模型 -DELETE /api/v1/models/{providerId}/models/{modelId} # 移除模型 - -POST /api/v1/models/{providerId}/discover # 发现模型 -POST /api/v1/models/{providerId}/discover/apply # 应用已发现 -POST /api/v1/models/{providerId}/test-connection # 测试供应商连接 -POST /api/v1/models/{providerId}/models/{modelId}/test # 测试单个模型 -``` - -### 遗留端点 - -``` -GET /api/v1/model-providers # 遗留——优先用 /api/v1/models -POST /api/v1/model-providers -PUT /api/v1/model-providers/{id} -DELETE /api/v1/model-providers/{id} - -GET /api/v1/model-configs # 遗留——优先用 /api/v1/models -POST /api/v1/model-configs -PUT /api/v1/model-configs/{id} -DELETE /api/v1/model-configs/{id} -``` - ---- - -## 渠道 - -``` -GET /api/v1/channels # 列表 -POST /api/v1/channels # 创建 -PUT /api/v1/channels/{id} # 更新 -DELETE /api/v1/channels/{id} # 删除 -PUT /api/v1/channels/{id}/toggle?enabled={bool} # 开关 -GET /api/v1/channels/status # 每个渠道的连接状态 -GET /api/v1/channels/health # 聚合健康视图 - -GET /api/v1/channels/webhook/weixin/qrcode # 微信 iLink 二维码 -GET /api/v1/channels/webhook/weixin/qrcode/status # 扫码状态 - -POST /api/v1/channels/qrcode/qq/begin # 发起 QQ 扫码绑定 -GET /api/v1/channels/qrcode/qq/status # QQ 扫码绑定状态 -``` - -### 渠道 webhook 回调 - -| 渠道 | 回调 URL | -|------|----------| -| 钉钉 | `POST /api/v1/channels/webhook/dingtalk` | -| 飞书 | `POST /api/v1/channels/webhook/feishu` | -| 企业微信 | `POST /api/v1/channels/webhook/wecom` | -| Telegram | `POST /api/v1/channels/webhook/telegram` | -| Discord | *（Gateway——无 webhook）* | -| QQ | `POST /api/v1/channels/webhook/qq` | -| Slack | `POST /api/v1/channels/webhook/slack` | -| 微信 | `POST /api/v1/channels/webhook/weixin` | - ---- - -## 定时任务 - -``` -GET /api/v1/cron-jobs # 列表 -POST /api/v1/cron-jobs # 创建 -PUT /api/v1/cron-jobs/{id} # 更新 -DELETE /api/v1/cron-jobs/{id} # 删除 -PUT /api/v1/cron-jobs/{id}/toggle?enabled={bool} # 开关 -POST /api/v1/cron-jobs/{id}/run # 立即执行 -``` - ---- - -## 工作流（1.3.0+） - -完整字段、step mode、Pebble 语法见 [工作流](./workflow)。 - -``` -GET /api/v1/workflows # 列表 -GET /api/v1/workflows/{id} # 获取（含已发布 revision + 草稿） -POST /api/v1/workflows # 新建 -PUT /api/v1/workflows/{id}/draft # 保存草稿（graph_json） -POST /api/v1/workflows/{id}/publish # 发布草稿为新 revision -DELETE /api/v1/workflows/{id} # 删除 - -POST /api/v1/workflows/draft/generate # 自然语言生成 graph_json 草稿 -POST /api/v1/workflows/{id}/preview-compile # 静态检查 + Pebble 校验，不发布 - -POST /api/v1/workflows/{id}/runs # 起一个 run（异步） -GET /api/v1/workflows/{id}/runs # run 列表 -GET /api/v1/workflows/runs/{runId} # run 详情 + 每步 input/output/token/duration -POST /api/v1/workflows/runs/{runId}/resume # await_approval 后恢复 -POST /api/v1/workflows/runs/{runId}/cancel # 取消运行中 -``` - ---- - -## 触发器（1.3.0+） - -6 种 pattern type、事件治理、跨实例一致性见 [触发器](./triggers)。 - -``` -GET /api/v1/triggers # 列表 -GET /api/v1/triggers/{id} # 获取 -POST /api/v1/triggers # 新建 -PUT /api/v1/triggers/{id} # 更新 -DELETE /api/v1/triggers/{id} # 删除 -PUT /api/v1/triggers/{id}/toggle?enabled={bool} # 开关 - -POST /api/v1/triggers/events # 通用事件入口（webhook / 桥接外部系统） - # 立即 ACK 200，异步派发 -GET /api/v1/triggers/{id}/events # 该 trigger 的事件历史 -``` - ---- - -## 目标（1.4.0+） - -目标完成评分、自动跟进的行为细节见 [目标](./goals)。 - -``` -POST /api/v1/goals # 新建目标 -GET /api/v1/goals/{id} # 获取目标 -PATCH /api/v1/goals/{id} # 更新目标（部分） -GET /api/v1/goals/{id}/events # 该目标的评估事件历史 -``` - ---- - -## Token 用量 - -``` -GET /api/v1/token-usage?startDate=&endDate=&modelName=&providerId= -``` - ---- - -## 系统设置 - -``` -GET /api/v1/settings # 所有设置 -PUT /api/v1/settings # 更新多个 -GET /api/v1/settings/language # 当前语言 -PUT /api/v1/settings/language # 更新语言 -PUT /api/v1/settings/{key} # 更新单个 key -``` - ---- - -## 仪表盘 - -``` -GET /api/v1/dashboard/summary # 用量汇总卡片 -GET /api/v1/dashboard/trends # 趋势图（?range=7d|30d|90d） -GET /api/v1/dashboard/top-agents # 最常用 Agent -GET /api/v1/dashboard/top-tools # 最常用工具 -``` - ---- - -## 工作空间 - -``` -GET /api/v1/workspaces # 列表 -GET /api/v1/workspaces/{id} # 获取 -POST /api/v1/workspaces # 创建 -PUT /api/v1/workspaces/{id} # 更新 -DELETE /api/v1/workspaces/{id} # 删除（仅 owner） -GET /api/v1/workspaces/{id}/access # 当前用户访问信息（见下） -``` - -### 成员与 RBAC（1.4.0+） - -`/access` 返回调用者在该工作空间内的有效权限，前端据此渲染路由和菜单： - -```json -{ - "memberRole": "editor", - "isGlobalAdmin": false, - "effectiveRole": "editor", - "capabilities": ["workspace.read", "conversation.write", "..."] -} -``` - -``` -GET /api/v1/workspaces/{id}/members # 列成员 -POST /api/v1/workspaces/{id}/members # 添加成员 -PUT /api/v1/workspaces/{id}/members/{memberId} # 更新成员（角色等） -DELETE /api/v1/workspaces/{id}/members/{memberId} # 移除成员 -``` - ---- - -## Doctor（健康检查） - -``` -GET /api/v1/doctor/run # 运行所有检查 -GET /api/v1/doctor/checks # 缓存的检查结果 -``` - ---- - -## 错误响应 - -```json -{ - "code": 400, - "message": "Validation failed: name is required" -} -``` - -### 常见状态码 - -| 状态码 | 含义 | -|--------|------| -| 200 | 成功 | -| 400 | 错误请求 | -| 401 | 未授权 | -| 403 | 禁止 | -| 404 | 未找到 | -| 500 | 服务端错误 | - ---- - -## 分页 - -列表端点按一致的 shape 返回分页结果： - -```json -{ - "code": 200, - "data": { - "records": [ ], - "total": 42, - "current": 1, - "size": 20, - "pages": 3 - } -} -``` - -| 字段 | 用途 | -|------|------| -| `records` | 当前页的条目数组 | -| `total` | 总条数 | -| `current` | 当前页（从 1 开始） | -| `size` | 每页条数 | -| `pages` | 总页数 | - ---- - -## 下一步 - -- [快速开始](./quickstart)——让服务器跑起来 -- [安全与审批](./security)——JWT + 审批流程 -- [聊天与消息](./chat)——SSE 事件格式 -- [LLM Wiki](./wiki)——Wiki 端点行为 +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/conversations` | `获取会话列表` | +| `POST` | `/api/v1/conversations/batch-delete` | `批量删除会话` | +| `GET` | `/api/v1/conversations/page` | `分页查询会话列表` | +| `DELETE` | `/api/v1/conversations/{conversationId}` | `删除会话` | +| `DELETE` | `/api/v1/conversations/{conversationId}/messages` | `清空会话消息` | +| `GET` | `/api/v1/conversations/{conversationId}/messages` | `获取会话消息历史（支持分页）` | +| `PUT` | `/api/v1/conversations/{conversationId}/model` | `切换会话使用的模型 (provider + model name)` | +| `PUT` | `/api/v1/conversations/{conversationId}/pin` | `置顶或取消置顶会话` | +| `GET` | `/api/v1/conversations/{conversationId}/status` | `获取会话流状态` | +| `PUT` | `/api/v1/conversations/{conversationId}/title` | `重命名会话` | + +### Agent + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/agents` | `获取Agent列表` | +| `POST` | `/api/v1/agents` | `创建Agent` | +| `GET` | `/api/v1/agents/{agentId}/provider-preferences` | `获取 Agent 的偏好 Provider 顺序` | +| `PUT` | `/api/v1/agents/{agentId}/provider-preferences` | `批量设置 Agent 的偏好 Provider 顺序（替换模式）` | +| `GET` | `/api/v1/agents/{agentId}/skills` | `获取 Agent 已绑定的 Skills` | +| `PUT` | `/api/v1/agents/{agentId}/skills` | `批量设置 Agent 的 Skill 绑定` | +| `DELETE` | `/api/v1/agents/{agentId}/skills/{skillId}` | `解绑单个 Skill` | +| `POST` | `/api/v1/agents/{agentId}/skills/{skillId}` | `绑定单个 Skill` | +| `GET` | `/api/v1/agents/{agentId}/tools` | `获取 Agent 已绑定的 Tools` | +| `PUT` | `/api/v1/agents/{agentId}/tools` | `批量设置 Agent 的 Tool 绑定` | +| `GET` | `/api/v1/agents/{agentId}/workspace/files` | `列出工作区文件` | +| `DELETE` | `/api/v1/agents/{agentId}/workspace/files/**` | `删除工作区文件` | +| `GET` | `/api/v1/agents/{agentId}/workspace/files/**` | `读取工作区文件` | +| `PUT` | `/api/v1/agents/{agentId}/workspace/files/**` | `保存工作区文件` | +| `GET` | `/api/v1/agents/{agentId}/workspace/memory/export` | `导出 Agent 记忆快照（ZIP）` | +| `POST` | `/api/v1/agents/{agentId}/workspace/memory/import` | `导入 Agent 记忆快照（写入）` | +| `POST` | `/api/v1/agents/{agentId}/workspace/memory/import/preview` | `预览导入 Agent 记忆快照（不写入）` | +| `GET` | `/api/v1/agents/{agentId}/workspace/prompt-files` | `获取系统提示文件列表` | +| `PUT` | `/api/v1/agents/{agentId}/workspace/prompt-files` | `设置系统提示文件列表` | +| `DELETE` | `/api/v1/agents/{id}` | `删除Agent` | +| `GET` | `/api/v1/agents/{id}` | `获取Agent详情` | +| `PUT` | `/api/v1/agents/{id}` | `更新Agent` | +| `GET` | `/api/v1/agents/{id}/capabilities` | `获取Agent当前能力（modality 集合 + sidecar 配置），用于聊天页提示条` | +| `POST` | `/api/v1/agents/{id}/chat` | `同步对话` | +| `GET` | `/api/v1/agents/{id}/chat/stream` | `流式对话（SSE）` | +| `POST` | `/api/v1/agents/{id}/execute` | `执行复杂任务（Plan-Execute）` | +| `GET` | `/api/v1/agents/{id}/state` | `获取Agent运行状态` | + +### Agent 模板 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/templates` | `获取模板列表` | +| `POST` | `/api/v1/templates/{id}/apply` | `应用模板创建Agent` | + +### 子 Agent + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/subagents/active` | `List active sub-agents in a conversation's delegation tree` | +| `POST` | `/api/v1/subagents/spawn-pause` | `Set sub-agent spawn-pause for a conversation` | +| `POST` | `/api/v1/subagents/{subagentId}/interrupt` | `Interrupt a running sub-agent` | + +### 运行时管理 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/admin/agent-runtime/runs/{conversationId}/recycle` | `Force recycle — dispose flux + drop RunState; use after friendly stop ignored` | +| `POST` | `/api/v1/admin/agent-runtime/runs/{conversationId}/stop` | `Friendly stop — request the run to wind down at its next checkpoint` | +| `GET` | `/api/v1/admin/agent-runtime/snapshot` | `Snapshot of every in-flight agent turn` | +| `POST` | `/api/v1/admin/agent-runtime/subagents/{subagentId}/interrupt` | `Interrupt one sub-agent (admin override of ownership check)` | +| `POST` | `/api/v1/admin/agent-runtime/sweep` | `Recycle every run currently flagged as stuck` | + +### 自动批准策略 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/approval/grants` | `列出当前 workspace 的自动批准策略（分页）` | +| `POST` | `/api/v1/approval/grants` | `创建自动批准策略` | +| `GET` | `/api/v1/approval/grants/active` | `当前 workspace 的活跃策略数量摘要` | +| `DELETE` | `/api/v1/approval/grants/{id}` | `撤销自动批准策略` | +| `GET` | `/api/v1/approval/resolutions` | `查询审批最终决策日志（按 grantId 或 conversationId 过滤）` | + +### 安全与 Tool Guard + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/security/approvals` | `审批记录（管理视角）` | +| `GET` | `/api/v1/security/audit/logs` | `审计日志` | +| `GET` | `/api/v1/security/audit/stats` | `审计统计` | +| `GET` | `/api/v1/security/guard/config` | `获取 Guard 配置` | +| `PUT` | `/api/v1/security/guard/config` | `更新 Guard 配置` | +| `GET` | `/api/v1/security/guard/config/file-guard` | `获取 File Guard 配置` | +| `PUT` | `/api/v1/security/guard/config/file-guard` | `更新 File Guard 配置` | +| `GET` | `/api/v1/security/guard/rules` | `规则列表` | +| `POST` | `/api/v1/security/guard/rules` | `新增自定义规则` | +| `GET` | `/api/v1/security/guard/rules/builtin` | `内置规则列表` | +| `DELETE` | `/api/v1/security/guard/rules/by-id/{id}` | `按主键 ID 删除自定义规则（兜底，rule_id 异常时使用）` | +| `GET` | `/api/v1/security/guard/rules/export` | `导出全部规则为 JSON` | +| `POST` | `/api/v1/security/guard/rules/import` | `从 JSON 批量导入规则（upsert 语义）` | +| `DELETE` | `/api/v1/security/guard/rules/{ruleId}` | `删除自定义规则` | +| `PUT` | `/api/v1/security/guard/rules/{ruleId}` | `更新规则` | +| `PUT` | `/api/v1/security/guard/rules/{ruleId}/toggle` | `启用/禁用规则` | + +### 审计 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/audit/events` | `分页查询审计事件` | + +### 活动流 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/activity/feed` | `Unified activity feed (audit + approval + tool calls)` | + +### 通知 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/notifications/summary` | `Aggregated counts for the sidebar attention badges` | + +### 工作空间 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/workspaces` | `获取当前用户的工作区列表（含 memberRole 与 effectiveRole）` | +| `POST` | `/api/v1/workspaces` | `创建工作区` | +| `DELETE` | `/api/v1/workspaces/{id}` | `删除工作区` | +| `GET` | `/api/v1/workspaces/{id}` | `获取工作区详情` | +| `PUT` | `/api/v1/workspaces/{id}` | `更新工作区` | +| `GET` | `/api/v1/workspaces/{id}/access` | `获取当前用户在指定工作区的访问能力（路由守卫消费）` | +| `GET` | `/api/v1/workspaces/{id}/members` | `获取工作区成员列表` | +| `POST` | `/api/v1/workspaces/{id}/members` | `添加工作区成员` | +| `DELETE` | `/api/v1/workspaces/{id}/members/{targetUserId}` | `移除工作区成员` | +| `PUT` | `/api/v1/workspaces/{id}/members/{targetUserId}` | `更新成员角色` | + +### 系统设置 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/settings` | `获取系统设置` | +| `PUT` | `/api/v1/settings` | `保存系统设置` | +| `GET` | `/api/v1/settings/language` | `获取当前语言` | +| `PUT` | `/api/v1/settings/language` | `更新当前语言` | +| `PUT` | `/api/v1/settings/sidecar` | `更新多模态 sidecar 配置` | + +### 首次初始化 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/setup/init` | `Init` | +| `GET` | `/api/v1/setup/onboarding-status` | `Get Onboarding Status` | +| `GET` | `/api/v1/setup/status` | `Get Status` | + +### 系统健康 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/system/browser-health` | `Browser launch diagnostics` | +| `GET` | `/api/v1/system/health` | `System health check` | + +### 仪表盘 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/dashboard/cron-runs` | `获取最近执行记录（当前 workspace 关联的 CronJob）` | +| `GET` | `/api/v1/dashboard/cron-runs/{cronJobId}` | `获取 CronJob 执行历史` | +| `GET` | `/api/v1/dashboard/overview` | `获取概览统计` | +| `GET` | `/api/v1/dashboard/trend` | `获取日用量趋势` | + +### Token 用量 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/token-usage` | `获取 Token 使用统计` | + +### 模型 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/models` | `获取 Provider 列表（仅 enabled）` | +| `POST` | `/api/v1/models` | `创建模型` | +| `GET` | `/api/v1/models/active` | `获取当前激活模型` | +| `PUT` | `/api/v1/models/active` | `设置当前激活模型` | +| `GET` | `/api/v1/models/by-type` | `按类型筛选模型（chat / embedding），可选 modality 过滤` | +| `GET` | `/api/v1/models/catalog` | `RFC-074: 获取 Provider 全量目录（含未启用），供 Add Provider 抽屉使用` | +| `DELETE` | `/api/v1/models/custom-providers` | `删除自定义 Provider（查询参数变体，兼容含特殊字符的旧 ID）` | +| `POST` | `/api/v1/models/custom-providers` | `创建自定义 Provider` | +| `DELETE` | `/api/v1/models/custom-providers/{providerId}` | `删除自定义 Provider` | +| `GET` | `/api/v1/models/default` | `获取默认模型` | +| `GET` | `/api/v1/models/embedding/default` | `获取系统默认 Embedding 模型 ID` | +| `POST` | `/api/v1/models/embedding/default` | `设置系统默认 Embedding 模型` | +| `POST` | `/api/v1/models/embedding/{modelId}/test` | `测试 Embedding 模型连通性（嵌入一个短文本验证 API key）` | +| `GET` | `/api/v1/models/enabled` | `获取启用模型列表` | +| `DELETE` | `/api/v1/models/{id}` | `删除模型` | +| `GET` | `/api/v1/models/{id}` | `获取模型详情` | +| `PUT` | `/api/v1/models/{id}` | `更新模型` | +| `POST` | `/api/v1/models/{id}/default` | `设置默认模型` | +| `PUT` | `/api/v1/models/{providerId}/config` | `更新 Provider 配置` | +| `POST` | `/api/v1/models/{providerId}/disable` | `RFC-074: 禁用 Provider（如其下模型为当前默认会自动切换）` | +| `POST` | `/api/v1/models/{providerId}/discover` | `发现远端模型` | +| `POST` | `/api/v1/models/{providerId}/discover/apply` | `批量添加发现的模型` | +| `POST` | `/api/v1/models/{providerId}/enable` | `RFC-074: 启用 Provider` | +| `DELETE` | `/api/v1/models/{providerId}/models` | `从 Provider 删除模型` | +| `POST` | `/api/v1/models/{providerId}/models` | `向 Provider 添加模型` | +| `POST` | `/api/v1/models/{providerId}/models/test` | `测试单个模型可用性` | +| `POST` | `/api/v1/models/{providerId}/test-connection` | `测试供应商连接` | + +### OAuth + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/oauth/anthropic/reload` | `Force re-detect credentials and refresh if near expiry` | +| `GET` | `/api/v1/oauth/anthropic/status` | `Read current Claude Code OAuth credential status from local disk` | +| `GET` | `/api/v1/oauth/openai/authorize` | `获取 OAuth 授权 URL（自动选 LOCAL / MANUAL_PASTE 模式）` | +| `POST` | `/api/v1/oauth/openai/callback-paste` | `MANUAL_PASTE 模式：用户粘贴浏览器回调 URL 完成 OAuth` | +| `POST` | `/api/v1/oauth/openai/device/cancel` | `Device flow: cancel a pending session` | +| `POST` | `/api/v1/oauth/openai/device/poll` | `Device flow: poll for completion` | +| `POST` | `/api/v1/oauth/openai/device/start` | `Device flow: start — request user_code` | +| `POST` | `/api/v1/oauth/openai/refresh` | `手动刷新 Token` | +| `DELETE` | `/api/v1/oauth/openai/revoke` | `清除 OAuth 凭证` | +| `GET` | `/api/v1/oauth/openai/status` | `获取 OAuth 连接状态` | + +### LLM 运行时 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/llm/provider-pool` | `查询所有 provider 的池状态 + 冷却信息` | +| `POST` | `/api/v1/llm/provider-pool/{providerId}/reprobe` | `手动重新探测某个 provider，立即更新池状态` | + +### 工具 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/tools` | `获取工具列表` | +| `POST` | `/api/v1/tools` | `创建工具（MCP）` | +| `GET` | `/api/v1/tools/available` | `获取员工可绑定的全部原子工具（含 MCP）` | +| `GET` | `/api/v1/tools/enabled` | `获取已启用工具列表` | +| `DELETE` | `/api/v1/tools/{id}` | `删除工具` | +| `GET` | `/api/v1/tools/{id}` | `获取工具详情` | +| `PUT` | `/api/v1/tools/{id}` | `更新工具` | +| `PUT` | `/api/v1/tools/{id}/disclosure-tier` | `设置工具披露分级（core / extension）` | +| `PUT` | `/api/v1/tools/{id}/toggle` | `启用/禁用工具` | + +### MCP 服务 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/mcp/servers` | `获取 MCP Server 列表` | +| `POST` | `/api/v1/mcp/servers` | `创建 MCP Server` | +| `POST` | `/api/v1/mcp/servers/refresh` | `刷新所有 MCP Server 连接` | +| `DELETE` | `/api/v1/mcp/servers/{id}` | `删除 MCP Server` | +| `GET` | `/api/v1/mcp/servers/{id}` | `获取 MCP Server 详情` | +| `PUT` | `/api/v1/mcp/servers/{id}` | `更新 MCP Server` | +| `PUT` | `/api/v1/mcp/servers/{id}/disclosure-tier` | `设置 MCP Server 披露分级（core / extension），整组工具跟随` | +| `POST` | `/api/v1/mcp/servers/{id}/test` | `测试 MCP Server 连接` | +| `PUT` | `/api/v1/mcp/servers/{id}/toggle` | `启用/禁用 MCP Server` | +| `GET` | `/api/v1/mcp/servers/{id}/tools` | `列出 MCP Server 已发现的工具` | + +### ACP 端点 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/acp/endpoints` | `List ACP endpoints` | +| `POST` | `/api/v1/acp/endpoints` | `Create a custom ACP endpoint` | +| `DELETE` | `/api/v1/acp/endpoints/{id}` | `Delete an ACP endpoint (builtins are protected)` | +| `GET` | `/api/v1/acp/endpoints/{id}` | `Get ACP endpoint by id` | +| `PUT` | `/api/v1/acp/endpoints/{id}` | `Update an ACP endpoint` | +| `POST` | `/api/v1/acp/endpoints/{id}/test` | `Test ACP endpoint connection (initialize handshake)` | +| `PUT` | `/api/v1/acp/endpoints/{id}/toggle` | `Enable / disable an ACP endpoint` | + +### 技能 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/skills` | `获取技能分页列表（RFC-042 §2.1）` | +| `POST` | `/api/v1/skills` | `创建技能` | +| `GET` | `/api/v1/skills/counts` | `获取各类型技能计数（tab 徽章用）` | +| `POST` | `/api/v1/skills/curator/activate` | `激活/取消激活 curator（真正归档 vs 仅预览）` | +| `POST` | `/api/v1/skills/curator/dry-run` | `立即运行一次 curator 预览（dry-run）` | +| `POST` | `/api/v1/skills/curator/pause` | `暂停 curator 定时扫描` | +| `GET` | `/api/v1/skills/curator/reports` | `列出最近的 curator 运行报告` | +| `GET` | `/api/v1/skills/curator/reports/{runId}` | `读取某次 curator 运行报告` | +| `POST` | `/api/v1/skills/curator/resume` | `恢复 curator 定时扫描` | +| `GET` | `/api/v1/skills/curator/status` | `curator 控制面状态` | +| `GET` | `/api/v1/skills/enabled` | `获取已启用技能列表` | +| `POST` | `/api/v1/skills/install/cancel/{taskId}` | `取消安装任务` | +| `GET` | `/api/v1/skills/install/hub/search` | `搜索 ClawHub 市场` | +| `POST` | `/api/v1/skills/install/start` | `开始异步安装 skill` | +| `GET` | `/api/v1/skills/install/status/{taskId}` | `查询安装任务状态` | +| `POST` | `/api/v1/skills/install/upload` | `上传 ZIP 安装 skill` | +| `DELETE` | `/api/v1/skills/install/{skillName}` | `卸载 skill` | +| `GET` | `/api/v1/skills/prompt-preview` | `预览技能 Prompt 增强效果（调试用，与 Agent 真实运行时一致）` | +| `GET` | `/api/v1/skills/runtime/active` | `获取 active skills 运行时视图` | +| `POST` | `/api/v1/skills/runtime/refresh` | `刷新 active skills 缓存，resync=true 时同步内置技能到 workspace` | +| `GET` | `/api/v1/skills/runtime/status` | `获取所有技能的运行时解析状态（管理页面使用）` | +| `GET` | `/api/v1/skills/summary` | `获取已启用技能摘要（按类型分组）` | +| `POST` | `/api/v1/skills/sync-files` | `Re-sync every skill's bundle files (admin)` | +| `POST` | `/api/v1/skills/synthesize-from-conversation` | `从对话历史合成 Skill（RFC-023）` | +| `GET` | `/api/v1/skills/type/{skillType}` | `按类型获取技能列表` | +| `DELETE` | `/api/v1/skills/{id}` | `硬删除技能 (admin only — 物理删除 + 工作区清空)` | +| `GET` | `/api/v1/skills/{id}` | `获取技能详情` | +| `PUT` | `/api/v1/skills/{id}` | `更新技能` | +| `POST` | `/api/v1/skills/{id}/archive` | `手动归档技能` | +| `GET` | `/api/v1/skills/{id}/employees` | `List agents that can use this skill (RFC-090 §14.2)` | +| `POST` | `/api/v1/skills/{id}/export-workspace` | `将 skill 导出到工作区目录` | +| `GET` | `/api/v1/skills/{id}/lessons` | `Read per-skill LESSONS.md (RFC-090 §11.4)` | +| `POST` | `/api/v1/skills/{id}/lessons/clear` | `Clear all lessons for a skill (RFC-090 §11.4)` | +| `POST` | `/api/v1/skills/{id}/pin` | `钉住/取消钉住技能（钉住的技能不会被自动归档）` | +| `GET` | `/api/v1/skills/{id}/requirements` | `Pre-flight requirement statuses for a skill (RFC-090)` | +| `POST` | `/api/v1/skills/{id}/rescan` | `重新扫描单个技能（RFC-042 §2.3.4）` | +| `POST` | `/api/v1/skills/{id}/restore` | `恢复已归档的技能` | +| `POST` | `/api/v1/skills/{id}/sync-files` | `Re-sync this skill's bundle files from DB → local workspace cache` | +| `PUT` | `/api/v1/skills/{id}/toggle` | `启用/禁用技能` | +| `GET` | `/api/v1/skills/{id}/workspace` | `获取 skill 工作区信息` | +| `GET` | `/api/v1/skills/{skillId}/secrets` | `List secret keys + masked previews for a skill` | +| `POST` | `/api/v1/skills/{skillId}/secrets` | `Upsert a secret value (empty value deletes it)` | +| `DELETE` | `/api/v1/skills/{skillId}/secrets/{key}` | `Delete a single secret by key` | + +### 技能模板 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/skill-templates` | `List skill templates (RFC-091)` | +| `GET` | `/api/v1/skill-templates/{id}` | `Get a single skill template` | +| `POST` | `/api/v1/skill-templates/{id}/instantiate` | `Instantiate a template into a skill` | + +### 插件 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/plugins` | `List all plugins` | +| `GET` | `/api/v1/plugins/{name}` | `Get plugin detail` | +| `PUT` | `/api/v1/plugins/{name}/config` | `Update plugin configuration` | +| `POST` | `/api/v1/plugins/{name}/disable` | `Disable a plugin` | +| `POST` | `/api/v1/plugins/{name}/enable` | `Enable a plugin` | + +### LLM Wiki + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/wiki/admin/backfill-tokens` | `Force-run the token-count backfill batch now` | +| `POST` | `/api/v1/wiki/admin/kb/{kbId}/rebuild-overview` | `Ensure overview/log scaffold + rebuild overview stats now` | +| `GET` | `/api/v1/wiki/chunks/{chunkId}/pages` | `Pages By Chunk Id` | +| `DELETE` | `/api/v1/wiki/hot-cache/{kbId}` | `Soft-delete the hot cache row` | +| `GET` | `/api/v1/wiki/hot-cache/{kbId}` | `Get the current hot cache snapshot for a KB` | +| `POST` | `/api/v1/wiki/hot-cache/{kbId}/regenerate` | `Schedule a manual rebuild of the hot cache` | +| `GET` | `/api/v1/wiki/kb/{kbId}/jobs` | `Get Jobs` | +| `GET` | `/api/v1/wiki/kb/{kbId}/pages/{pageId}/citations` | `Page Citations` | +| `GET` | `/api/v1/wiki/kb/{kbId}/pages/{slugA}/relation/{slugB}` | `Explain Relation` | +| `POST` | `/api/v1/wiki/kb/{kbId}/pages/{slug}/enrich` | `Enrich Page` | +| `GET` | `/api/v1/wiki/kb/{kbId}/pages/{slug}/related` | `Related Pages` | +| `POST` | `/api/v1/wiki/kb/{kbId}/pages/{slug}/repair` | `Repair Page` | +| `POST` | `/api/v1/wiki/kb/{kbId}/search-preview` | `Search Preview` | +| `GET` | `/api/v1/wiki/kb/{kbId}/stats` | `Kb Stats` | +| `GET` | `/api/v1/wiki/knowledge-bases` | `获取所有知识库` | +| `POST` | `/api/v1/wiki/knowledge-bases` | `创建知识库` | +| `GET` | `/api/v1/wiki/knowledge-bases/agent/{agentId}` | `按 Agent 获取知识库` | +| `GET` | `/api/v1/wiki/knowledge-bases/bindable` | `列出可绑定到指定 Agent 的知识库` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{id}` | `删除知识库` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}` | `获取知识库详情` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}` | `更新知识库` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}/config` | `获取知识库配置` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}/config` | `更新知识库配置` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile` | `获取知识库 pageType profile（未配置则返回内置默认）` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile` | `保存知识库 pageType profile` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile/reset-default` | `重置 pageType profile 为内置默认` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/page-type-profile/validate` | `校验 pageType profile JSON（不保存）` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/scan` | `扫描关联目录导入文件` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{id}/source-directory` | `设置知识库关联目录` | +| `GET` | `/api/v1/wiki/knowledge-bases/{id}/source-watcher` | `查看知识库源监听状态` | +| `POST` | `/api/v1/wiki/knowledge-bases/{id}/source-watcher/scan` | `手动触发一次源监听扫描` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions` | `列出某 Agent 在知识库下的 pageType 权限规则` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions` | `新增或更新 Agent 的 pageType 权限规则（按 agent+kb+pageType 去重）` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/agents/{agentId}/page-type-permissions/{id}` | `删除一条 Agent pageType 权限规则` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links` | `读取最近一次死链扫描的聚合结果` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links` | `启动 Wiki 死链扫描 job（异步）` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links/jobs/{jobId}` | `查询 Wiki 死链扫描 job 状态` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages` | `获取 Wiki 页面列表（可按原始材料过滤）` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/archived` | `列出知识库中所有 archived=1 的页面（不含 content）` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/batch` | `批量删除 Wiki 页面` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/refs` | `获取 Wiki 页面引用索引（slug/title/archived，供 wikilink 解析）` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}` | `删除 Wiki 页面` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}` | `获取 Wiki 页面内容` | +| `PUT` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}` | `手动编辑 Wiki 页面` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/archive` | `归档单个页面（软归档；可恢复）` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/backlinks` | `获取反向链接` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/rename` | `重命名 Wiki 页面，并级联更新所有引用方` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/unarchive` | `取消归档` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pipeline-runs/{runId}` | `查询单次 run 的步骤明细` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines` | `列出知识库的 pipeline 定义` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines` | `保存(创建/更新)pipeline 定义(YAML/JSON)` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines/validate` | `校验 pipeline 配置(不保存)` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines/{id}` | `删除 pipeline 定义` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/pipelines/{id}/runs` | `查询 pipeline 运行记录` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/process` | `触发知识库处理（异步）；force=true 时清空所有 last_processed_hash 并重新入队全部材料` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/processing-status` | `获取处理状态` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/progress` | `订阅处理进度 SSE` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/raw` | `获取原始材料列表（含每条材料生成的页面数）` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/text` | `添加文本材料` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/upload` | `上传文件材料` | +| `DELETE` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}` | `删除原始材料` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}/cancel` | `请求取消正在进行的处理（仅在 processing 状态有效）` | +| `GET` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}/download` | `下载原始材料` | +| `POST` | `/api/v1/wiki/knowledge-bases/{kbId}/raw/{rawId}/reprocess` | `重新处理原始材料（force=true 时绕过 content_hash 短路）` | +| `GET` | `/api/v1/wiki/pages/lookup` | `跨 KB 按 title 或 slug 查找页面（chat 端 wikilink 跳转用）` | +| `GET` | `/api/v1/wiki/raw/{rawId}/pages` | `Pages By Raw Id` | +| `POST` | `/api/v1/wiki/research/start` | `启动 Deep Research，返回 SSE sessionId` | +| `GET` | `/api/v1/wiki/research/stream/{sessionId}` | `订阅 Deep Research SSE 事件流` | +| `GET` | `/api/v1/wiki/transformations` | `List transformations available to a KB` | +| `POST` | `/api/v1/wiki/transformations` | `Create` | +| `GET` | `/api/v1/wiki/transformations/runs` | `List Runs` | +| `DELETE` | `/api/v1/wiki/transformations/runs/{runId}` | `Delete Run` | +| `GET` | `/api/v1/wiki/transformations/runs/{runId}` | `Get Run` | +| `POST` | `/api/v1/wiki/transformations/runs/{runId}/cancel` | `Cancel a still-running transformation run` | +| `POST` | `/api/v1/wiki/transformations/runs/{runId}/save-as-page` | `Save a completed run's output as a synthesis wiki page` | +| `DELETE` | `/api/v1/wiki/transformations/{id}` | `Delete` | +| `GET` | `/api/v1/wiki/transformations/{id}` | `Get` | +| `PUT` | `/api/v1/wiki/transformations/{id}` | `Update` | +| `POST` | `/api/v1/wiki/transformations/{id}/aggregate` | `Aggregate all completed runs of a template into one KB-level synthesis page` | +| `POST` | `/api/v1/wiki/transformations/{id}/apply` | `Run a transformation against a raw material or wiki page` | + +### 记忆 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/memory/{agentId}/dream/events` | `Subscribe to dream events (SSE)` | +| `GET` | `/api/v1/memory/{agentId}/dream/morning-card` | `Get morning card for current user + agent` | +| `POST` | `/api/v1/memory/{agentId}/dream/morning-card/seen` | `Mark morning card as seen` | +| `GET` | `/api/v1/memory/{agentId}/dream/reports` | `List dream reports (paginated, newest first)` | +| `GET` | `/api/v1/memory/{agentId}/dream/reports/{reportId}` | `Get a single dream report by ID` | +| `POST` | `/api/v1/memory/{agentId}/dream/reports/{reportId}/entries/{key}/confirm` | `Confirm a memory entry (no-op acknowledgment)` | +| `POST` | `/api/v1/memory/{agentId}/dream/reports/{reportId}/entries/{key}/edit` | `Edit a memory entry — writes back to the target memory file with user-edited metadata` | +| `GET` | `/api/v1/memory/{agentId}/dreaming/candidates` | `查询召回候选列表（含评分详情）` | +| `GET` | `/api/v1/memory/{agentId}/dreaming/dreams` | `查询 DREAMS.md 整合日记` | +| `POST` | `/api/v1/memory/{agentId}/dreaming/focused` | `Focused Dream — 围绕指定主题触发记忆整合` | +| `GET` | `/api/v1/memory/{agentId}/dreaming/status` | `查询 Dreaming 状态（配置、统计、上次运行时间）` | +| `POST` | `/api/v1/memory/{agentId}/emergence` | `手动触发记忆整合（daily notes → MEMORY.md，NIGHTLY 模式）` | +| `GET` | `/api/v1/memory/{agentId}/facts` | `List facts for an agent` | +| `GET` | `/api/v1/memory/{agentId}/facts/contradictions` | `List unresolved contradictions` | +| `POST` | `/api/v1/memory/{agentId}/facts/contradictions/{contradictionId}/resolve` | `Resolve a contradiction (KEEP_A / KEEP_B / MERGE / IGNORE)` | +| `POST` | `/api/v1/memory/{agentId}/facts/{factId}/feedback` | `Submit feedback on a fact (HELPFUL/UNHELPFUL)` | +| `POST` | `/api/v1/memory/{agentId}/facts/{factId}/forget` | `Forget a fact — writes canonical metadata, rebuilds projection` | +| `POST` | `/api/v1/memory/{agentId}/summarize/{conversationId}` | `手动触发对话记忆提取` | + +### 目标 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/goals` | `List goals (optionally filtered by status)` | +| `POST` | `/api/v1/goals` | `Create a persistent goal for a conversation` | +| `GET` | `/api/v1/goals/by-conversation/{conversationId}` | `Get the active goal bound to a conversation (or null)` | +| `GET` | `/api/v1/goals/{id}` | `Get goal detail by id` | +| `PATCH` | `/api/v1/goals/{id}` | `Sparse update of a non-terminal goal` | +| `POST` | `/api/v1/goals/{id}/abandon` | `Abandon a goal (terminal)` | +| `POST` | `/api/v1/goals/{id}/criteria` | `Append a sub-criterion to an active goal` | +| `GET` | `/api/v1/goals/{id}/events` | `Get the event timeline for a goal` | +| `POST` | `/api/v1/goals/{id}/pause` | `Pause an active goal` | +| `POST` | `/api/v1/goals/{id}/resume` | `Resume a paused goal` | + +### 定时任务 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/cron-jobs` | `获取定时任务列表` | +| `POST` | `/api/v1/cron-jobs` | `创建定时任务` | +| `GET` | `/api/v1/cron-jobs/active-runs` | `查询会话下正在执行的定时任务运行` | +| `DELETE` | `/api/v1/cron-jobs/{id}` | `删除定时任务` | +| `GET` | `/api/v1/cron-jobs/{id}` | `获取定时任务详情` | +| `PUT` | `/api/v1/cron-jobs/{id}` | `更新定时任务` | +| `POST` | `/api/v1/cron-jobs/{id}/run` | `立即执行定时任务` | +| `PUT` | `/api/v1/cron-jobs/{id}/toggle` | `启用/禁用定时任务` | + +### 触发器 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/triggers` | `List triggers in the caller's workspace.` | +| `POST` | `/api/v1/triggers` | `Create a trigger; if enabled, registers it with the scheduler.` | +| `POST` | `/api/v1/triggers/events` | `Ingest one event envelope; returns per-trigger fire / drop summary.` | +| `DELETE` | `/api/v1/triggers/{id}` | `Delete a trigger and unregister its schedule.` | +| `GET` | `/api/v1/triggers/{id}` | `Get a trigger by id, scoped to the caller's workspace.` | +| `PUT` | `/api/v1/triggers/{id}` | `Update a trigger; pattern_version bumps when the cron expression changes.` | + +### 工作流 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/workflows` | `List workflows in the workspace` | +| `POST` | `/api/v1/workflows` | `Create a workflow row (draft starts empty).` | +| `POST` | `/api/v1/workflows/draft/generate` | `Generate a workflow draft from a natural-language description.` | +| `POST` | `/api/v1/workflows/draft/preview-compile` | `Compile arbitrary draft JSON without persisting — used by the template picker / generator preview to surface real ACL + schema diagnostics before a workflow row exists.` | +| `GET` | `/api/v1/workflows/draft/templates` | `List the canonical workflow templates the generator can apply directly.` | +| `GET` | `/api/v1/workflows/runs/paused` | `List paused runs across the workspace so operators can resume them.` | +| `GET` | `/api/v1/workflows/runs/{runId}` | `Inspect a single run with its step rows for replay / debugging.` | +| `POST` | `/api/v1/workflows/runs/{runId}/resume` | `Resume a paused workflow run with the given outcome.` | +| `DELETE` | `/api/v1/workflows/{id}` | `Soft-delete a workflow row.` | +| `GET` | `/api/v1/workflows/{id}` | `Get a workflow by id (includes inline draft + latest published graph).` | +| `PUT` | `/api/v1/workflows/{id}` | `Update workflow metadata (name / description / enabled).` | +| `POST` | `/api/v1/workflows/{id}/compile` | `Compile the draft and surface diagnostics without persisting a revision.` | +| `PUT` | `/api/v1/workflows/{id}/draft` | `Save the inline draft graph_json without compiling.` | +| `POST` | `/api/v1/workflows/{id}/publish` | `Compile the draft and persist a new revision pointed at by latest_revision_id.` | +| `GET` | `/api/v1/workflows/{id}/runs` | `List the most recent runs for a workflow.` | + +### 渠道 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/channels` | `获取渠道列表` | +| `POST` | `/api/v1/channels` | `创建渠道` | +| `GET` | `/api/v1/channels/health` | `批量获取所有渠道健康状态` | +| `POST` | `/api/v1/channels/preflight` | `Pre-flight: validate draft channel config without persisting` | +| `POST` | `/api/v1/channels/qrcode/{channelType}/begin` | `启动指定渠道的扫码授权流程` | +| `GET` | `/api/v1/channels/qrcode/{channelType}/status` | `查询指定渠道的扫码授权状态` | +| `GET` | `/api/v1/channels/status` | `获取渠道运行状态（全局系统视图，仅管理员可见）` | +| `GET` | `/api/v1/channels/type/{channelType}` | `按类型获取渠道列表` | +| `GET` | `/api/v1/channels/webchat/config` | `获取 WebChat 配置` | +| `POST` | `/api/v1/channels/webchat/stream` | `WebChat SSE 流式对话` | +| `POST` | `/api/v1/channels/webhook/dingtalk` | `钉钉消息回调` | +| `POST` | `/api/v1/channels/webhook/dingtalk/register/begin` | `启动钉钉扫码注册应用流程` | +| `GET` | `/api/v1/channels/webhook/dingtalk/register/status` | `查询钉钉扫码注册状态` | +| `POST` | `/api/v1/channels/webhook/discord` | `Discord 消息回调（已废弃：Discord 已切换为 Gateway WebSocket 模式）` | +| `POST` | `/api/v1/channels/webhook/feishu` | `飞书消息回调` | +| `POST` | `/api/v1/channels/webhook/feishu/register/begin` | `启动飞书扫码注册应用流程` | +| `GET` | `/api/v1/channels/webhook/feishu/register/status` | `查询飞书扫码注册状态` | +| `POST` | `/api/v1/channels/webhook/slack` | `Slack Events API 回调` | +| `GET` | `/api/v1/channels/webhook/status` | `获取渠道运行状态` | +| `POST` | `/api/v1/channels/webhook/telegram` | `Telegram 消息回调` | +| `POST` | `/api/v1/channels/webhook/wecom` | `企业微信消息回调（智能机器人模式不使用，保留兼容）` | +| `GET` | `/api/v1/channels/webhook/weixin/qrcode` | `获取微信登录二维码` | +| `GET` | `/api/v1/channels/webhook/weixin/qrcode/status` | `查询微信二维码扫码状态` | +| `DELETE` | `/api/v1/channels/{id}` | `删除渠道` | +| `GET` | `/api/v1/channels/{id}` | `获取渠道详情` | +| `PUT` | `/api/v1/channels/{id}` | `更新渠道` | +| `GET` | `/api/v1/channels/{id}/health` | `获取指定渠道的实时健康状态（真连接状态，前端绿点应该绑这个）` | +| `PUT` | `/api/v1/channels/{id}/toggle` | `启用/禁用渠道` | + +### 数据源 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/datasources` | `获取数据源列表` | +| `POST` | `/api/v1/datasources` | `创建数据源` | +| `DELETE` | `/api/v1/datasources/{id}` | `删除数据源` | +| `GET` | `/api/v1/datasources/{id}` | `获取数据源详情` | +| `PUT` | `/api/v1/datasources/{id}` | `更新数据源` | +| `POST` | `/api/v1/datasources/{id}/test` | `测试数据源连接` | +| `PUT` | `/api/v1/datasources/{id}/toggle` | `启用/禁用数据源` | + +### 语音转文本 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/stt/transcribe` | `Transcribe` | + +### 文本转语音 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `POST` | `/api/v1/tts/synthesize` | `Synthesize` | +| `GET` | `/api/v1/tts/voices` | `List Voices` | + +### 生成文件 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/files/generated/{id}` | `Download a tool-generated file by its one-time id` | + +### 计划 + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/plans` | `获取 Agent 的计划列表` | +| `GET` | `/api/v1/plans/{id}` | `获取计划详情（含步骤）` | + +### Feature Flags + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/feature-flags` | `List` | +| `PUT` | `/api/v1/feature-flags/{flagKey}` | `Update` | diff --git a/mateclaw-server/src/main/resources/docs/zh/architecture.md b/mateclaw-server/src/main/resources/docs/zh/architecture.md index 75bfc597..977f4fd8 100644 --- a/mateclaw-server/src/main/resources/docs/zh/architecture.md +++ b/mateclaw-server/src/main/resources/docs/zh/architecture.md @@ -151,7 +151,7 @@ mateclaw/ ### 目标评估节点（1.4.0+） -图（ReAct 和 Plan-Execute 都有）现在在 `FinalAnswerNode` 把最终答案流式输出之后再跑一个 `GoalEvaluationNode`：它给目标完成度打分，并可选地注入一条自动跟进消息，把没达成的目标继续推进。 +图（ReAct 和 Plan-Execute 都有）现在在 `FinalAnswerNode` 把最终答案流式输出之后再跑一个 `GoalEvaluationNode`：1.5.0 起它逐条裁决目标的 checklist 准则（bootstrap / verdict 两模式），**全部准则通过才算完成**，并可选地注入一条针对剩余准则的自动跟进消息，把没达成的目标继续推进。 ### 其他 1.4.0 运行时变化 @@ -179,7 +179,7 @@ mateclaw/ ## 数据流 —— 单次回合 ``` -1. POST /api/v1/chat/{agentId}/message +1. POST /api/v1/chat?agentId={id} （或 POST /api/v1/chat/stream，agentId 在 body 里） ↓ 2. ChatController.sendMessage() ↓ @@ -301,7 +301,7 @@ MateClaw 用 **Spring MVC**，不是 Spring WebFlux。**WebFlux 在依赖图里 流式流程： -1. 客户端打开 `GET /api/v1/chat/{agentId}/stream`，带 `Accept: text/event-stream` +1. 客户端 `POST /api/v1/chat/stream`，body 里带 `agentId` / `message` / `conversationId`，请求头加 `Accept: text/event-stream` 2. Controller 返回 `SseEmitter` 3. Agent 图在工作线程上运行；节点执行把事件发给 `GraphEventPublisher` 4. 事件序列化成 SSE 格式写进 emitter diff --git a/mateclaw-server/src/main/resources/docs/zh/channels.md b/mateclaw-server/src/main/resources/docs/zh/channels.md index accf2aea..b3e3ab08 100644 --- a/mateclaw-server/src/main/resources/docs/zh/channels.md +++ b/mateclaw-server/src/main/resources/docs/zh/channels.md @@ -35,6 +35,11 @@ v1.4.0 把飞书做成了"一等公民"渠道——交互卡片、流式卡片 飞书的细节全部在下面[飞书](#飞书)一节里展开。 ::: +::: tip 1.5.0 渠道改进 +- **统一的入站媒体管线**：目前**微信和企业微信**已接入这层共用的入站媒体下载器 + 魔数（magic-byte）类型识别 + 指数退避重试（其它 IM 渠道后续接入）。文件类型从内容字节判定（不再硬编码 `image/*`），HEIC / WEBP / DOCX / XLSX 等都能正确识别，下载失败自动重试。 +- **飞书：跟进文本自动带上最近的文件（#201）**：飞书群里先发一个文件（哪怕没 @ 员工），再发一句文字，缓存的文件会自动作为内容片段塞给员工——每群 5 个文件、60 分钟 TTL。 +::: + --- ## 九个渠道 @@ -103,7 +108,11 @@ v1.4.0 把飞书做成了"一等公民"渠道——交互卡片、流式卡片 内置。没有外部配置，没有凭证。用 Server-Sent Events 做实时流式。 ``` -GET /api/v1/chat/{agentId}/stream +POST /api/v1/chat/stream +Content-Type: application/json +Accept: text/event-stream + +{"agentId": 1, "message": "...", "conversationId": "..."} ``` 事件格式在 [聊天与消息](./chat) 里。 diff --git a/mateclaw-server/src/main/resources/docs/zh/chat.md b/mateclaw-server/src/main/resources/docs/zh/chat.md index 8eefbdda..f5ec2a05 100644 --- a/mateclaw-server/src/main/resources/docs/zh/chat.md +++ b/mateclaw-server/src/main/resources/docs/zh/chat.md @@ -50,6 +50,8 @@ MateClaw 的聊天 UI 在试着回答一个问题：**AI 刚刚告诉你的事 信任是靠"把过程摊开"挣来的。MateClaw 把过程摊开。 +**执行计划 & 工具调用详情查看器（1.5.0）。** 计划面板每个步骤、每个工具调用行，右侧多了一个"查看详情"图标。点开是一个带毛玻璃背景的弹窗，显示**完整的请求参数和响应输出**——内联预览会截断的部分这里都在，带请求/响应各自的复制按钮，状态徽标标"进行中 / 已完成 / 失败 / 等待中"。这些数据存在消息元数据里，所以刷新页面后计划步骤和工具调用照样可读。 + --- ## 多渠道实时同步 @@ -86,6 +88,10 @@ ChatConsole 不只是你自己聊天的地方。它是一个**运营控制台** 图片递交给支持视觉的模型做视觉理解。PDF 和 DOCX 走文本抽取（扫描件自动降级到 OCR）。Agent 在本回合读到的所有内容，都会进它的上下文。 +::: tip 工具生成的文件：下载链接扛得住重启（1.5.0，#243） +员工调工具生成的文件（文档 / 图片 / 音频…）现在**落盘**到 `data/generated-files/`，带 7 天保留窗口 + 6 小时定时清理，内存里再放一层 LRU——下载链接重启后依然有效，不再受原来 10 分钟内存窗口限制。前端用一个全局点击代理拦截 `/api/v1/files/generated/{id}` 下载：成功走鉴权 fetch → blob 下载，失败（404/410/过期）只弹一个 toast，**不再因为一个失效链接把整个页面卡死**。 +::: + ### 主模型不支持图片？走"多模态旁路" ::: tip 1.3.0 新增 @@ -119,7 +125,7 @@ ChatConsole 不只是你自己聊天的地方。它是一个**运营控制台** 你输入 │ ▼ -POST /api/v1/chat/{agentId}/message ← 或走 SSE 流式 +POST /api/v1/chat?agentId={id} ← 或走 SSE 流式（POST /api/v1/chat/stream） │ ▼ Conversation Manager ← 加载/创建会话，追加用户消息 @@ -270,31 +276,49 @@ Segment 的结构是渐进展示的底层。它也让**数据库成为单一事 ### 发送消息 ```bash -curl -X POST http://localhost:18088/api/v1/chat/1/message \ +curl -X POST 'http://localhost:18088/api/v1/chat?agentId=1' \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ - "content": "东京现在几点？", + "message": "东京现在几点？", "conversationId": "conv-abc123" }' ``` -省略 `conversationId` 就会开一个新会话。 +省略 `conversationId` 就会开一个新会话。`agentId` 是 query 参数，**不是**路径段。 ### SSE 流式 -```javascript -const eventSource = new EventSource( - '/api/v1/chat/1/stream?conversationId=conv-abc123', - { headers: { 'Authorization': 'Bearer YOUR_JWT_TOKEN' } } -); +SSE 端点是 `POST /api/v1/chat/stream`，请求体里带 `agentId`。浏览器原生 `EventSource` 只支持 GET，所以集成时用 `fetch()` 读流： -eventSource.onmessage = (event) => { - const data = JSON.parse(event.data); - // 处理 segment -}; +```javascript +const resp = await fetch('/api/v1/chat/stream', { + method: 'POST', + headers: { + 'Authorization': 'Bearer YOUR_JWT_TOKEN', + 'Content-Type': 'application/json', + 'Accept': 'text/event-stream', + }, + body: JSON.stringify({ + agentId: 1, + message: '东京现在几点？', + conversationId: 'conv-abc123', + }), +}); + +const reader = resp.body.getReader(); +const decoder = new TextDecoder(); +let buf = ''; +while (true) { + const { value, done } = await reader.read(); + if (done) break; + buf += decoder.decode(value, { stream: true }); + // 按 SSE 协议拆 `\n\n` 边界，逐事件处理 segment +} ``` +完整客户端实现可以参考 `mateclaw-ui/src/composables/chat/useChat.ts`。 + ### SSE 事件类型 | 事件 | 含义 | diff --git a/mateclaw-server/src/main/resources/docs/zh/console.md b/mateclaw-server/src/main/resources/docs/zh/console.md index 8a68eb69..0e0261f9 100644 --- a/mateclaw-server/src/main/resources/docs/zh/console.md +++ b/mateclaw-server/src/main/resources/docs/zh/console.md @@ -111,7 +111,7 @@ - `POST /api/v1/chat/stream`——SSE 流式（原生 fetch） - `POST /api/v1/chat/upload` - `POST /api/v1/chat/{conversationId}/stop` -- `POST /api/v1/approvals/{id}/resolve` +- 审批结果通过 `POST /api/v1/chat/stream` 发送 `/approve` 或 `/deny` - `GET /api/v1/chat/{conversationId}/pending-approvals` - `GET /api/v1/conversations`——列表 - `GET /api/v1/conversations/{id}/messages` diff --git a/mateclaw-server/src/main/resources/docs/zh/desktop-ui-hot-update.md b/mateclaw-server/src/main/resources/docs/zh/desktop-ui-hot-update.md index 3d13d1e8..f7d2d7a4 100644 --- a/mateclaw-server/src/main/resources/docs/zh/desktop-ui-hot-update.md +++ b/mateclaw-server/src/main/resources/docs/zh/desktop-ui-hot-update.md @@ -262,7 +262,7 @@ Manifest 最好放在稳定的静态地址，不要依赖 GitHub API 动态查 建议机制： - `current.json` 记录当前版本、上一版本、状态 -- UI 启动成功后，前端调用 `/api/v1/system/ui/boot-ok` 或通过 preload IPC 上报“本次版本已健康启动” +- UI 启动成功后，通过 preload IPC 上报“本次版本已健康启动”；如果后续选择 REST 方案，可新增 `/api/v1/system/ui/boot-ok`（当前源码尚未提供该端点） - 若启动后短时间内崩溃或白屏，下次启动自动回滚上一版本 ### 7. 安全要求 @@ -437,9 +437,9 @@ UI 热更新本质上是在本地执行新的前端资源，必须做完整校 - `uiUpdater.download()` - `uiUpdater.applyOnRestart()` -后端接口建议新增： +后端接口建议新增（当前源码尚未提供）： -- `GET /api/v1/runtime/version` +- 建议新增：`GET /api/v1/runtime/version`（当前源码尚未提供） 返回示例： diff --git a/mateclaw-server/src/main/resources/docs/zh/desktop.md b/mateclaw-server/src/main/resources/docs/zh/desktop.md index 93dc4a31..8ba6b142 100644 --- a/mateclaw-server/src/main/resources/docs/zh/desktop.md +++ b/mateclaw-server/src/main/resources/docs/zh/desktop.md @@ -147,7 +147,8 @@ cd ../mateclaw-server mvn clean package -DskipTests # 3. 把 JAR 拷到桌面项目 -cp target/mateclaw-server.jar ../mateclaw-desktop/resources/app.jar +JAR_FILE=$(ls -1 target/mateclaw-server-*.jar | grep -v sources | head -n 1) +cp "$JAR_FILE" ../mateclaw-desktop/resources/app.jar # 4. 下载平台特定的 JRE cd ../mateclaw-desktop diff --git a/mateclaw-server/src/main/resources/docs/zh/doctor.md b/mateclaw-server/src/main/resources/docs/zh/doctor.md index 96ad4abd..100d0c03 100644 --- a/mateclaw-server/src/main/resources/docs/zh/doctor.md +++ b/mateclaw-server/src/main/resources/docs/zh/doctor.md @@ -1,233 +1,71 @@ # Doctor -**Doctor 页面回答一个问题：这个东西现在是不是真的在正常工作？** +Doctor 是应用内的健康抽屉。它从后端健康服务读取当前本机实例状态；当前实现不是一个独立的定时诊断系统。 -MateClaw 有很多活动部件——后端、数据库、模型供应商、MCP 服务、IM 渠道、cron 任务、记忆整合、wiki 消化。出问题时，**症状**（"我的 Agent 不响应"）通常有一个**具体的原因**（"DashScope API Key 昨天过期了"）埋在离你能看到的地方好几层远的地方。Doctor 是一个单页，**一次性跑所有检查**，告诉你哪些是绿的、哪些是黄的、哪些是红的。 +可以从布局里的状态按钮 / 设置区域打开。抽屉每次打开或点击刷新时都会请求后端。 -通过 `设置 → Doctor` 打开，或者直接跳 `/doctor`。 +## 当前后端 API ---- - -## 它检查什么 - -每一项检查独立运行，报告三种状态之一： - -- **✅ OK**——一切按预期工作 -- **⚠️ 警告**——在工作但降级了（例如在用 fallback provider、接近配额、一个非关键的 cron 任务暂停了） -- **❌ 错误**——以一种你需要修的方式坏了 - -### 核心基础设施 - -| 检查 | 验证什么 | -|------|----------| -| **后端版本** | MateClaw 在跑，报告它的版本 | -| **数据库连接** | 配置的数据源可达，查询成功 | -| **数据库 schema** | 所有预期的 `mate_*` 表存在；迁移状态干净 | -| **磁盘使用** | 数据目录有足够空闲空间（低于 20% 警告，低于 5% 错误） | -| **H2 console 暴露** | 生产 profile 里启用了 H2 console 会警告 | -| **JWT secret 强度** | 还在用默认 JWT secret 会警告 | - -### 模型 - -| 检查 | 验证什么 | -|------|----------| -| **活跃模型** | 默认模型配置存在且启用 | -| **供应商连通性** | 每个启用的供应商最近通过了连接测试 | -| **API Key 存在** | 每个标记为启用的云供应商都配了 key | -| **Ollama 可达** | 如果配了 Ollama，本地实例可达 | - -### Agent 和工具 - -| 检查 | 验证什么 | -|------|----------| -| **工具注册表** | 内置工具和 MCP 工具加载无错 | -| **Tool Guard 配置** | 至少存在一条 Tool Guard 规则（用 `default-policy: allow` 会警告） | -| **默认 Agent** | 默认 Agent 存在且启用 | -| **Agent 模板** | 内置模板存在且可加载 | - -### 记忆和 Wiki - -| 检查 | 验证什么 | -|------|----------| -| **记忆整合 cron** | 每个 Agent 的整合 cron 任务存在且启用 | -| **上次整合运行** | 过去 7 天没有跑过整合会警告 | -| **Wiki 消化队列** | 没有卡住的 `pending` 或 `processing` 原始材料 | -| **Wiki schema** | `mate_wiki_*` 表存在且可查询 | - -### 渠道 - -| 检查 | 验证什么 | -|------|----------| -| **渠道健康监控** | 每个启用的渠道报告 `connected` 或正在主动重连 | -| **每渠道状态** | 每个 IM 渠道的连接状态和上次错误 | -| **Webhook URL 可达** | 生产环境下 webhook 模式的渠道没配公网 URL 会警告 | - -### MCP - -| 检查 | 验证什么 | -|------|----------| -| **启用的 MCP 服务** | 每个启用的 MCP 服务是 `connected` | -| **工具数** | 每个连接成功的服务报告至少一个工具 | -| **孤儿子进程** | 没有超过它父 client 存活的 stdio 子进程 | - -### Cron 和异步 - -| 检查 | 验证什么 | -|------|----------| -| **Cron 引擎** | 计划任务执行器在运行 | -| **过期任务** | 任何任务超时超过 24 小时会警告 | -| **异步任务队列** | `mate_async_task` 队列长度在正常范围 | - ---- - -## 检查怎么跑 - -Doctor 两种方式跑： - -### 按需 - -点 Doctor 页面上的**运行所有检查**。按钮并行触发所有检查；UI 在每项检查完成时流式返回结果。大多数检查在一秒内完成；最慢的（MCP 服务连接测试）可能要 10–30 秒。 - -### 按计划 - -Doctor 也在后台**每 15 分钟自动跑一次**。结果缓存在内存里并持久化到 `mate_doctor_check`，这样打开页面时它**立刻加载**——你看到的是上次缓存的状态，直到你点**运行所有检查**。 - -在 `application.yml` 里调整计划： - -```yaml -mateclaw: - doctor: - enabled: true - schedule-minutes: 15 - cache-ttl-minutes: 10 +```bash +curl http://localhost:18088/api/v1/system/health \ + -H "Authorization: Bearer " ``` ---- - -## 读结果 - -每个检查返回： +响应结构： ```json { - "name": "DashScope 供应商连通性", - "category": "Models", - "status": "ok", - "message": "连接测试成功（延迟：240ms）", - "lastChecked": "2026-04-11T14:30:22", - "details": { - "provider": "dashscope", - "baseUrl": "https://dashscope.aliyuncs.com", - "latencyMs": 240 - }, - "fixUrl": "/settings/models" + "code": 200, + "msg": "success", + "data": { + "overall": "healthy", + "checks": [ + { + "name": "default-model", + "status": "healthy", + "message": "Default model: qwen-plus", + "action": null + } + ] + } } ``` -UI 渲染： +`overall` 取值为 `healthy`、`warning`、`error`。每个检查项包含： -- 顶部的**分类 tab**——基础设施、模型、Agent、记忆、Wiki、渠道、MCP、Cron -- **状态计数器**——绿 / 黄 / 红 -- **检查列表**——名字、状态、消息、距上次检查的时间、"查看详情"展开、可选的"修复"按钮跳到相关设置页 -- **历史图**——（每个检查）最近 50 次运行的 sparkline，一眼看出抖动的检查 +| 字段 | 含义 | +|---|---| +| `name` | 稳定检查 key，例如 `default-model`、`database`、`browser`、`provider:`、`mcp:` | +| `status` | `healthy`、`warning` 或 `error` | +| `message` | 抽屉里展示的简短诊断信息 | +| `action` | 可选 `{ label, route }`，提示去哪里修 | ---- +## 当前检查项 -## 修复按钮 +当前 `SystemHealthService` 检查： -对可操作的检查，Doctor 行包含一个**修复**按钮，直接跳到相关的设置页面： +| 检查 | 验证什么 | 常见修复入口 | +|---|---|---| +| 默认模型 | 是否配置并能加载默认模型 | `/settings/models` | +| Provider 配置 | 需要 API key 的 provider 是否已配置 | `/settings/models` | +| 已启用 MCP 服务 | 已启用 MCP 服务是否有成功连接结果 | `/settings/mcp-servers` | +| 数据库初始化 | 首次启动 bootstrap 是否完成 | `/setup` | +| 浏览器诊断 | 浏览器工具启动前置条件 | `/api/v1/system/browser-health` | -- 模型供应商失败 → `设置 → 模型` -- Tool Guard `default-policy: allow` → `设置 → 安全与审批` -- 生产环境的 H2 console → `设置 → 系统`（或显示一个可复制的配置片段） -- JWT 默认 secret → `设置 → 系统`（或显示一个配置片段） -- MCP 服务断开 → `工具 → MCP 服务` -- 卡住的 wiki 消化 → `Wiki → [KB] → 原始材料` - -点修复带你到**你能解决问题的那个具体页面**。可能的话，目标页面会预过滤高亮失败的条目。 - ---- - -## Doctor API +浏览器诊断也有独立接口： ```bash -# 跑所有检查（同步） -curl http://localhost:18088/api/v1/doctor/run \ - -H "Authorization: Bearer " - -# 获取缓存的检查结果 -curl http://localhost:18088/api/v1/doctor/checks \ - -H "Authorization: Bearer " - -# 只跑特定分类 -curl http://localhost:18088/api/v1/doctor/run?category=models \ - -H "Authorization: Bearer " - -# 历史结果 -curl "http://localhost:18088/api/v1/doctor/history?check=dashscope-connectivity&limit=50" \ +curl http://localhost:18088/api/v1/system/browser-health \ -H "Authorization: Bearer " ``` ---- +## 当前源码没有实现的旧内容 -## 在运维中使用 Doctor +旧文档曾提到 `/api/v1/doctor/run`、`/api/v1/doctor/checks`、`/api/v1/doctor/history`、Doctor 定时后台运行、`mate_doctor_check`、`mate_doctor_check_history`。这些端点和表在当前后端源码中不存在。当前健康检查请使用 `/api/v1/system/health`。 -### 作为 uptime 监控的健康端点 +## 相关页面 -把你的外部 uptime 监控（UptimeRobot、Pingdom、内部 Prometheus）指向： - -``` -GET /api/v1/doctor/checks -``` - -端点返回 HTTP 200 带 JSON 汇总——聚合的通过/失败计数和按分类细分。你的监控应该在 `errorCount > 0` 时报警。 - -要更简单的健康检查，用： - -``` -GET /actuator/health -``` - -这遵循 Spring Boot 的标准格式。 - -### 升级时 - -部署新 MateClaw 版本之后跑 Doctor 验证没有回归： - -1. 打开 `/doctor` -2. 点**运行所有检查** -3. 看有没有之前没有的黄或红 -4. **特别注意数据库 schema**——升级后 schema 不匹配通常意味着某个迁移没跑 - -### 出问题时 - -用户报告"它不工作"时 Doctor 是第一个去看的地方。打开页面，看哪个检查是红的，点**修复**，解决问题。**如果没有检查是红的但用户仍然有问题**，大概率是 Doctor 还没覆盖的东西——开一个 [GitHub issue](https://github.com/matevip/mateclaw/issues) 让我们加一个检查。 - ---- - -## 数据模型 - -**`mate_doctor_check`** - -| 列 | 用途 | -|----|------| -| `id` | 主键 | -| `name` | 检查名字 | -| `category` | 检查分类 | -| `status` | `ok` / `warning` / `error` | -| `message` | 人类可读的消息 | -| `details` | 额外细节的 JSON | -| `last_checked` | 上次运行时间 | -| `run_duration_ms` | 检查耗时 | -| `workspace_id` | 范围（全局检查为 null） | - -历史结果进 `mate_doctor_check_history`，同样的列加上一个保留期清理任务。 - ---- - -## 下一步 - -- [控制台](./console)——Doctor 所在的 UI -- [配置说明](./config)——你可能基于 Doctor 警告配置的东西 -- [安全与审批](./security)——Doctor 在 Tool Guard 里检查什么 -- [贡献指南](./contributing)——缺了什么就加一个 Doctor 检查 +- [API 参考](./api) —— 源码对齐的路由索引 +- [模型配置](./models) —— 模型 / provider 设置 +- [MCP 协议](./mcp) —— MCP 服务配置 +- [安全与审批](./security) —— Tool Guard 和审批行为 diff --git a/mateclaw-server/src/main/resources/docs/zh/faq.md b/mateclaw-server/src/main/resources/docs/zh/faq.md index 205c82aa..d2edbce3 100644 --- a/mateclaw-server/src/main/resources/docs/zh/faq.md +++ b/mateclaw-server/src/main/resources/docs/zh/faq.md @@ -215,9 +215,10 @@ UI 里用 `工具 → MCP 服务`。三种传输模式：stdio、streamable_http ### 我批准了一个工具调用但 Agent 没恢复 1. `AWAITING_APPROVAL` 还是 true 吗？（`GET /api/v1/agents/{id}`） -2. 审批真的持久化了吗？（`GET /api/v1/approvals/{id}`） +2. 等待中的会话还有 pending 审批吗？（`GET /api/v1/chat/{conversationId}/pending-approvals`） 3. Agent 日志里 replay 尝试附近有错误吗？ -4. Replay 失败的话，Agent 应该在聊天里暴露一个错误 +4. 批准/拒绝消息是否通过同一个会话的 `POST /api/v1/chat/stream` 发送？ +5. Replay 失败的话，Agent 应该在聊天里暴露一个错误 ### 我想批量批准这个 Agent 未来的工具调用 @@ -381,8 +382,11 @@ mvn spring-boot:run -Dspring-boot.run.arguments="--logging.level.vip.mate=DEBUG" 浏览器 DevTools → Network → 筛选 `EventStream`。或： ```bash -curl -N -H "Authorization: Bearer " \ - "http://localhost:18088/api/v1/chat/1/stream?conversationId=1" +curl -N -X POST 'http://localhost:18088/api/v1/chat/stream' \ + -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -H "Accept: text/event-stream" \ + -d '{"agentId":1, "message":"测试", "conversationId":"1"}' ``` --- diff --git a/mateclaw-server/src/main/resources/docs/zh/goals.md b/mateclaw-server/src/main/resources/docs/zh/goals.md index 553672f5..52de7e2a 100644 --- a/mateclaw-server/src/main/resources/docs/zh/goals.md +++ b/mateclaw-server/src/main/resources/docs/zh/goals.md @@ -65,8 +65,6 @@ Goal 把这件事翻过来。**你说一次，员工锁住目标，自己每轮 POST /api/v1/goals { "conversationId": "conv-xxx", - "agentId": "1000000001", - "workspaceId": 1, "title": "部署博客到 fly.io", "description": "...", "exitCriteria": "DNS+SSL+健康检查+测试通过", @@ -76,7 +74,7 @@ POST /api/v1/goals } ``` -完整接口列表见 [API 参考](./api)。 +> `agentId` / `workspaceId` 由 `conversationId` 在服务端派生，**请求体里不用传**（传了也会被忽略）。完整接口列表见 [API 参考](./api)。 --- @@ -114,13 +112,59 @@ POST /api/v1/goals 如果 `autoFollowupEnabled=true` 且这一轮 evaluator 判 "continue"，后台会： 1. 写一条 `followup_injected` 事件到时间线 -2. 给对话末尾 APPEND 一条用户消息："Continue working on the goal. Still missing: {gap}. Take the next concrete step." +2. 给对话末尾 APPEND 一条用户消息。**1.5.0 起，如果目标有清单，这条消息会明确列出还没通过的那几条准则**——"5/8 已完成，剩余：① …… ② ……，去做剩下的"；没有清单时回退到笼统的 "Continue working on the goal. Still missing: {gap}." 3. 让员工再跑一轮 reasoning，**这一轮的回答就直接接在第一轮后面** 你的体感是：员工答完一段 → 停半拍 → **继续往下做** — 就像一个人做完一步停了一下想了想然后继续。 --- +## 目标是一份清单（checklist，1.5.0+） + +1.4.0 里 evaluator 每轮给一个完成度分数（0~1）和一句"还差什么"。问题是 **0.8 到底是什么意思**——哪几条做完了、哪几条没做，你看不清。 + +1.5.0 把它换成**清单**：目标 = 一组**可以逐条独立验证**的准则。 + +**evaluator 有两种模式：** + +| 模式 | 什么时候跑 | 干什么 | +|---|---|---| +| **bootstrap（拆解）** | 还没有准则时 | 把目标拆成清单，每条初始为"未通过" | +| **verdict（裁决）** | 已有准则时 | 逐条判：这条满足了吗？给出证据 | + +两种模式都用**结构化输出**——evaluator 必须返回带类型的对象（准则 `id` + `passed` + `evidence`），而不是一段自由文本让我们去猜。 + +**完成判定是确定性的。** 只有当**每一条准则都通过**，才判完成。20 条里过了 19 条（0.95 分）依然是"继续"——差一条就还差一条，没有模糊阈值。 + +**怎么给目标加清单——三种途径：** + +- **创建时直接带**——`setGoal` 工具传 `criteria: ["DNS 解析正确", "SSL 有效", "测试全绿"]`，或 `POST /api/v1/goals` 传 `criteria`。省去 bootstrap 那一轮。 +- **让 evaluator 自己拆**——不传 criteria，第一轮评估时 bootstrap 模式自动拆解。 +- **运行中追加**——`addGoalCriterion` 工具或 `POST /api/v1/goals/{id}/criteria`，往进行中的目标补一条，不用重开。 + +**一条准则长什么样：** + +```json +{ "id": "C1", "text": "DNS 解析指向 fly.io", "passed": false, "evidence": "" } +``` + +`id` 由服务端分配（C1、C2…），`text` 是人能看懂、LLM 能判的一句话，`passed` 是 evaluator 的裁决，`evidence` 是它给的依据（输出片段、文件摘录等）。清单存在 `mate_agent_goal.criteria` 列（JSON），通过 `GoalResponse.criteria` 解析后下发，从不以裸 JSON 字符串暴露。 + +### 头像旁的光，hover 出来是一张清单卡 + +- **没有清单**时——一句话 tooltip：标题 + evaluator 写的 gap 文本。 +- **有清单**时——一张卡片：标题 + `X/Y` 进度，下面每条准则前一个 `○`（未完成）或 `✓`（绿色已完成，文字带删除线）。 + +评估中头像周围是沙金色呼吸光晕；完成短暂显示绿色环后消失；预算耗尽变红橙色环。 + +### Evaluator SPI + +评估逻辑实现了 Spring AI 的 `Evaluator` 接口：既能做目标专用的 checklist 裁决（bootstrap / verdict），也能被当成通用评估器复用（把单个目标包成一条准则跑 verdict）。失败的 evaluator 调用**照样计入 LLM 预算**，所以预算账目是准的。 + +> 1.4.0 的目标是"员工记住它在干什么"。1.5.0 的目标是"员工知道**具体还差哪几条**"。从一个分数，到一份能逐条勾的清单。 + +--- + ## 4 个内置工具（员工可用） 员工的工具集里默认包含这 4 个（无需手动绑定，是 agent-wide 系统级工具）： @@ -132,7 +176,7 @@ POST /api/v1/goals | **completeGoal** | 显式标记完成 | "所有事项已做完，请 completeGoal" | | **getGoalStatus** | 查询当前 goal 状态 | "我们现在进展到哪了？" | -完成时 (`completeGoal` 或 evaluator 判 score≥0.95)，员工会把这个目标的总结同步到[长期记忆](./memory)，后续对话能查得回来。 +完成时（`completeGoal`，或 evaluator 判定**每一条准则都通过**），员工会把这个目标的总结同步到[长期记忆](./memory)，后续对话能查得回来。 --- @@ -168,7 +212,7 @@ turnsUsed >= turnBudget 或 (agentLlmCallsUsed + evalLlmCallsUsed) >= llmCallB ↓ ↑ paused - active ──evaluator score≥0.95 / completeGoal──→ completed (终态) + active ──evaluator 全部准则通过 / completeGoal──→ completed (终态) ↓ active ──turns_used/llm_calls 用完 ─────────→ exhausted (终态) ↓ @@ -188,7 +232,7 @@ turnsUsed >= turnBudget 或 (agentLlmCallsUsed + evalLlmCallsUsed) >= llmCallB - **不做嵌套目标 / 目标树** — 一个 conversation 一个目标，不堆 OKR - **不做"目标模板"** — 每个目标是手写的，不是从库里挑的 - **不做跨 conversation 迁移目标** — 想要那效果，请用[工作流](./workflow) -- **不暴露评估分数给用户** — 那个 `completionScore` 是工程内部协议，不是用户语言。UI 用一圈光说话，hover 显示 evaluator 写的 gap 文本（自然语言）。后端日志和 API 里仍可见数值，方便调试 +- **不暴露评估分数给用户** — 那个 `completionScore` 是工程内部协议，不是用户语言。UI 用一圈光说话，hover 出来：有清单时是逐条勾的清单卡，没清单时是 evaluator 写的 gap 文本（自然语言）。后端日志和 API 里仍可见数值，方便调试 --- @@ -219,12 +263,18 @@ mateclaw: goal: # 主开关；关闭后图节点对所有调用 pass-through enabled: true + # 创建目标时 autoFollowupEnabled 的默认值（调用方未指定时） + default-auto-followup: true + # 运行期总开关；关掉则无论 per-goal 标志如何，都不注入自动延续 + allow-auto-followup: true # 默认 turn 预算 default-turn-budget: 20 # 默认 LLM 调用预算（agent + evaluator 之和） default-llm-call-budget: 200 # 自动延续之间至少隔多久（秒） auto-followup-cooldown-seconds: 0 + # 单次 graph 运行内自动延续的硬上限（每条消息的安全网；总预算仍由 turnBudget 管） + max-followups-per-run: 8 # 评估器使用的模型；空字符串 = 沿用对话当前模型（便宜的小模型推荐：qwen-turbo / glm-4-flash） evaluator-model: "" # 评估 prompt 携带的历史消息条数上限 diff --git a/mateclaw-server/src/main/resources/docs/zh/mcp.md b/mateclaw-server/src/main/resources/docs/zh/mcp.md index 9274cb24..72a38b02 100644 --- a/mateclaw-server/src/main/resources/docs/zh/mcp.md +++ b/mateclaw-server/src/main/resources/docs/zh/mcp.md @@ -99,7 +99,7 @@ MateClaw ── HTTP POST ──► 远程 MCP 服务 - **URL**（streamable_http / sse）——服务端点 - **HTTP Headers**（streamable_http / sse）——JSON 对象 - **连接超时**——默认 30 秒 -- **读取超时**——默认 30 秒 +- **读取超时**——默认 **60 秒**（1.5.0 起从 30s 提到 60s，#247；单次 callTool 往返合法地跑久一点的工具不再被掐断。每台服务可单独调 5–300s） 保存。启用状态时 MateClaw 自动尝试连接并发现工具。 @@ -357,7 +357,7 @@ stdio 服务：禁用/删除、配置替换、应用关闭（`@PreDestroy`）、 | `cwd` | VARCHAR(512) | NULL | 工作目录 | | `enabled` | BOOLEAN | TRUE | 开关 | | `connect_timeout_seconds` | INT | 30 | HTTP 连接超时 | -| `read_timeout_seconds` | INT | 30 | 请求响应超时 | +| `read_timeout_seconds` | INT | 60 | 请求响应超时（1.5.0 起默认 60，旧为 30） | | `last_status` | VARCHAR(32) | `disconnected` | 上次连接状态 | | `last_error` | TEXT | NULL | 上次错误消息 | | `last_connected_time` | DATETIME | NULL | 上次成功连接时间 | diff --git a/mateclaw-server/src/main/resources/docs/zh/memory.md b/mateclaw-server/src/main/resources/docs/zh/memory.md index d0a10750..77ca4000 100644 --- a/mateclaw-server/src/main/resources/docs/zh/memory.md +++ b/mateclaw-server/src/main/resources/docs/zh/memory.md @@ -64,6 +64,55 @@ MateClaw 里其他所有东西，在你配置完之后就静止了。Agent、工 --- +## 记忆认人：per-owner 隔离（1.5.0） + +以前一个员工的记忆是**共享**的：不管是网页登录的你、还是飞书群里的同事、还是第三方 API 接进来的终端用户，聊出来的记忆都堆进同一个 `MEMORY.md`。一个员工服务多个人时，记忆会串台。 + +1.5.0 给每条记忆加了**主人（owner）**和**可见范围（scope）**。 + +### 统一的 owner_key + +不管身份从哪来，都归一成一个带前缀的字符串： + +| 来源 | owner_key | +|---|---| +| 网页控制台 | `user:<用户id>` | +| IM 渠道（飞书 / 钉钉 / 企微…） | `<渠道>:<发送者id>` | +| 第三方 API（带 endUserId） | `api:` | +| 系统 / cron | `system` | + +### 三档可见性 + +| scope | 谁能读 | 典型内容 | +|---|---|---| +| **PERSONAL（个人）** | 只有匹配的 owner | 对话里抽取出来的记忆默认进这档 | +| **TEAM（团队）** | 用这个员工的人都能读 | 员工配置文件（AGENTS.md / SOUL.md / PROFILE.md）、历史回填的数据 | +| **GLOBAL（全局）** | 跨员工 / 工作空间始终可见 | 预置事实、系统参考资料 | + +### 召回偏好个人记忆 + +system prompt 里只烤进 TEAM/GLOBAL 的共享记忆（可缓存）；每轮再按当前 owner_key **预取**他个人的记忆注入。所以问"我的项目用什么栈"时，员工优先回忆**这个人**的私人记忆文件，而不是知识库里的泛泛资料。 + +> 关于结构化"事实"层：**事实召回查询本身支持 owner 可见性过滤**（PERSONAL 仅 owner 可见，TEAM/GLOBAL 共享）。但当前的**自动事实投影**主要从共享记忆文件构建、插入时不写 `ownerKey/scope`——也就是说个人化更多体现在个人记忆文件的预取上，事实层的 per-owner 化还在补齐中。 + +### 第三方 API 透传终端用户身份 + +`/api/v1/chat` 和 `/api/v1/chat/stream` 的请求体新增可选字段 **`endUserId`**（字符串，保大整数精度）。一个 PAT 认证的接入方代表一个 MateClaw 用户，但可以为每个终端用户传不同的 `endUserId`，记忆按终端用户自动隔离。 + +### 这是一个可开关的特性 + +总开关是 `mate.memory.lifecycle-mediator-enabled`。 + +::: warning 默认值要看清楚 +Java 属性的裸默认值是 `false`，但**随发行版打包的 `application.yml` 把它设成了 `true`**——也就是说**默认安装下 per-owner 隔离是开着的**。要回到旧的共享行为（所有写入走 TEAM），在你的配置里显式设为 `false`。 +::: + +打开后：对话抽取写入 owner 的 PERSONAL 记忆，召回按 owner_key 过滤；关闭后所有写入回退到共享 TEAM。多租户实例保持开启，单人部署可以关掉。 + +底层：迁移 `V137` 给 `mate_workspace_file` / `mate_memory_recall` / `mate_fact` 三张表加了 `owner_key` + `scope` 列，历史行回填为 `TEAM`（保证升级后没有记忆被藏起来）。`remember` 等记忆工具会按当前请求上下文解析 owner_key，开关打开时写进该 owner 的 PERSONAL 记忆，关闭时回退共享写入。 + +--- + ## 多层记忆 + 可插拔 Provider 记忆这一层不是一个硬编码的实现。它是一个**接口**——多层架构允许你**堆叠 provider**： @@ -414,6 +463,11 @@ mate: # --- 整合 / dreaming --- emergence-enabled: true emergence-day-range: 7 + + # --- per-owner 记忆隔离（1.5.0）--- + # 随发行版打包的默认值是 true（开）：对话抽取写入 owner 的 PERSONAL 记忆，召回按 owner_key 过滤。 + # 设为 false 回到旧的共享行为（所有写入走 TEAM）。Java 属性裸默认值为 false。 + lifecycle-mediator-enabled: true ``` 配置前缀：`mate.memory`。 diff --git a/mateclaw-server/src/main/resources/docs/zh/models.md b/mateclaw-server/src/main/resources/docs/zh/models.md index db649f09..2202c769 100644 --- a/mateclaw-server/src/main/resources/docs/zh/models.md +++ b/mateclaw-server/src/main/resources/docs/zh/models.md @@ -17,8 +17,8 @@ MateClaw 不关心你用哪个 LLM。它通过五个协议适配器跟所有主 | **百炼 Token Plan** | 阿里百炼 token 包月套餐 | dashscope | 7 个种子模型；支持长 token | | **OpenAI** | GPT-4o、GPT-4o-mini、GPT-5.5、o1、o3、o4-mini | openai | 标准 OpenAI API | | **OpenAI OAuth（ChatGPT Plus/Pro）** | 通过订阅用 GPT-4o、o3、o4-mini | openai | 浏览器 OAuth，**不需要 API Key** | -| **Anthropic** | Claude 4.7、Claude 4.6 Sonnet、Claude 4.5 Haiku | anthropic | 原生 Messages API | -| **Anthropic Claude Code OAuth** | 通过 Claude Pro/Max/Team 订阅用 Claude 4.7 / 4.6 | anthropic | 浏览器 OAuth + 手动粘贴流，**不需要 API Key** | +| **Anthropic** | **Claude Opus 4.8 / 4.8 Fast**（1.5.0+）、Claude 4.7、Claude 4.6 Sonnet、Claude 4.5 Haiku | anthropic | 原生 Messages API；4.8 两个变体都支持 `xhigh` 思考档 | +| **Anthropic Claude Code OAuth** | 通过 Claude Pro/Max/Team 订阅用 Claude Opus 4.8 / 4.7 / 4.6 | anthropic | 浏览器 OAuth + 手动粘贴流，**不需要 API Key** | | **Google Gemini** _(原生)_ | gemini-2.5-flash、gemini-3-pro-image-preview、gemini-2.5-flash-image | gemini | 原生 `generateContent` API（非 OpenAI 兼容）——见下方"原生 Gemini" | | **xAI / Grok** | Grok 3、Grok 4 | openai | OpenAI 兼容（base URL + API Key）；UI 带 xAI 品牌图标 | | **DeepSeek** | deepseek-chat、deepseek-coder、**DeepSeek V4 flash + pro**（支持思考模式） | openai | OpenAI 兼容 | @@ -162,13 +162,13 @@ Gemini 不再走 OpenAI 兼容层——MateClaw 直接对接 Google 的**原生 如果 `local` 模式起不来 loopback 端口（端口被占、沙箱拒绝），会自动降级到 `manual_paste`。 -**后端端点**（`/api/v1/oauth/openai/device`）： +**后端端点：** | Method | Path | 用途 | |---|---|---| -| `POST` | `/start` | 开一个会话，返回 `deviceAuthId` / `userCode` / `verificationUrl` / `intervalSeconds` / `expiresInSeconds` | -| `POST` | `/poll` | 按 `deviceAuthId` 轮询，返回 `PENDING` / `COMPLETED` / `EXPIRED` | -| `POST` | `/cancel` | 丢弃会话（比如用户关了对话框） | +| `POST` | `/api/v1/oauth/openai/device/start` | 开一个会话，返回 `deviceAuthId` / `userCode` / `verificationUrl` / `intervalSeconds` / `expiresInSeconds` | +| `POST` | `/api/v1/oauth/openai/device/poll` | 按 `deviceAuthId` 轮询，返回 `PENDING` / `COMPLETED` / `EXPIRED` | +| `POST` | `/api/v1/oauth/openai/device/cancel` | 丢弃会话（比如用户关了对话框） | 前端按 OpenAI 返回的 `intervalSeconds`（一般 5 秒）轮询；服务端再设一个最小轮询间隔（默认 3 秒）兜底，避免被打。过期的会话每 5 分钟扫一次清掉。 @@ -393,6 +393,17 @@ MateClaw 用一个**活跃模型**作为全局默认。没有指定自己模型 - **出口 sanitizer** —— provider 专属选项（如 OpenAI 推理模型的 `reasoning_effort`）在 failover 到不支持的 provider 时被剥离，泄漏的选项不会让 fallback 报 400 - **UI 区分 401 与会话过期** —— provider 认证错误和用户会话过期现在显示不同消息、不同处置 +### 偏好提供商决定主模型（1.5.0） + +1.5.0 之前，"每个 agent 自定义优先级"只影响 **failover 顺序**——主模型仍是全局默认。1.5.0 让这个偏好**真的决定主模型选择**。完整优先级链是： + +1. **会话钉选模型最高优先**——聊天头部 ModelSelector 给这个会话单独绑了模型，就用它（见[按会话选模型](./chat#按会话选模型)） +2. **其次是 per-agent 的模型覆盖（`modelName`）**——员工自己钉死了某个模型 +3. **再次是全局默认模型** +4. **以上都没有时，才进入偏好提供商路由**——按偏好挑提供商的主模型 + +偏好提供商路由里有一道**能力门禁**：如果员工绑定的技能声明了 `requires-model: vision` 这类需求，路由会先挑能满足这些模态的提供商；满足不了再无约束回退。偏好存在 `mate_agent_provider_preference` 表（按 `sortOrder` 升序，越小优先级越高）。 + --- ## API 配置 diff --git a/mateclaw-server/src/main/resources/docs/zh/releases.md b/mateclaw-server/src/main/resources/docs/zh/releases.md index 0e63f1a7..7ceaf4dc 100644 --- a/mateclaw-server/src/main/resources/docs/zh/releases.md +++ b/mateclaw-server/src/main/resources/docs/zh/releases.md @@ -10,6 +10,7 @@ | 版本 | 日期 | 亮点 | |------|------|------| +| [v1.5.0](./releases/1.5.0) | 2026-06-04 | 目标长出清单——从"打个分"到"逐条勾"（checklist + Evaluator SPI + 确定性完成判定） · Wiki 学会自维护（`[[wikilink]]` 互联 + 改名/删页级联修链 + 坏链体检 · 事实/经验分层 + 失效传播 · pageType 档案与 per-agent 权限 · 处理流水线 · 本地目录知识源定时增量同步） · 记忆按主人隔离（owner_key + 个人/团队/全局可见性 + 第三方 endUserId 透传） · 每个员工绑主知识库 · 偏好提供商决定主模型 + Claude Opus 4.8 | | [v1.4.0](./releases/1.4.0) | 2026-05-23 | 持久化目标——员工锁住目标自己跟到完成 · 子员工委派变成一棵树（递归 3 层 + 异步 + 数字员工构建器） · 渐进式工具/技能披露（`enable_tool` + `load_skill`） · 工作空间 RBAC（四级角色 + 能力门禁） · 飞书做成一等公民（互动/审批/流式卡片 + 语音/文件音视频 + 渠道原生工具） | | [v1.3.0](./releases/1.3.0) | 2026-05-13 | 工作流元年——7 种 step mode 把员工组装成业务流程 · 触发器 6 种 pattern 让事件自动启动流程 · Wiki 从搜索索引升级为处理流水线（用户模板 + 跨材料聚合 + reverse-citation） · MCP per-agent 工具绑定 + 多模态旁路路由 · 4 个 JVM 原生文档生成工具 + 图像编辑 | | [v1.2.0](./releases/1.2.0) | 2026-05-05 | 智能体改名"数字员工"（角色 / 目标 / 背景故事 + 5 职业模板） · 技能成了骨架（manifest + 模板向导 + LESSONS 自我进化） · ACP 接入：Claude Code / Codex 变成你的员工 · Admin 运行时控制台让你看见每个员工正在干什么 | diff --git a/mateclaw-server/src/main/resources/docs/zh/security.md b/mateclaw-server/src/main/resources/docs/zh/security.md index bce775c2..97dd903f 100644 --- a/mateclaw-server/src/main/resources/docs/zh/security.md +++ b/mateclaw-server/src/main/resources/docs/zh/security.md @@ -88,8 +88,8 @@ mateclaw: | 状态码 | 含义 | 响应 | |--------|------|------| -| 401 | Token 缺失、过期或无效 | `{"code": 401, "message": "Unauthorized"}` | -| 403 | Token 有效但权限不足 | `{"code": 403, "message": "Forbidden"}` | +| 401 | Token 缺失、过期或无效 | `{"code":401,"msg":"Token expired or invalid","data":null}` | +| 403 | Token 有效但权限不足 | `{"code":403,"msg":"Forbidden","data":null}` | 前端统一处理——跳登录页、清空存储的 token。 @@ -100,8 +100,8 @@ MateClaw 出厂带 `admin` / `admin123`。**除了你自己笔记本之外的任 ### Spring Security 配置 - **无状态会话**——服务端不存 session；所有状态都在 JWT 里 -- **公共端点**——`/api/v1/auth/login`、`/h2-console/**`、`/swagger-ui/**` -- **受保护端点**——`/api/v1/**` 下的其他所有路径 +- **公共 API 端点**——`GET /api/v1/settings/language`、`/api/v1/auth/login`、`/api/v1/chat/stream`、`/api/v1/chat/*/stop`、`/api/v1/agents/*/chat/stream`、`/api/v1/setup/**`、`/api/v1/channels/webhook/**`、`/api/v1/channels/webchat/**`、`/api/v1/talk/ws`、`/api/v1/files/generated/**` +- **受保护端点**——`/api/**` 下的其他所有路径 - **CSRF 关闭**——无状态 JWT 不需要 --- @@ -247,7 +247,7 @@ Tool Guard：require_approval 用户点 Approve 或 Reject │ ▼ -POST /api/v1/approvals/{id}/resolve +POST /api/v1/chat/stream，消息为 /approve 或 /deny │ ├─ Approved → 重新加载 Agent，replay 工具调用，继续推理 └─ Rejected → 把拒绝作为 observation 返回，继续推理 @@ -255,6 +255,8 @@ POST /api/v1/approvals/{id}/resolve "replay" 机制很重要。Agent 恢复时**不会从头重新推理**——它直接跳到已经批准的工具调用、执行、从观察继续。**没有重复的 LLM 调用，没有浪费的 token。** +当前 Web 路径没有写入型 `POST /api/v1/approvals/{id}/resolve` 端点。批准和拒绝走普通聊天同一条 SSE 通道，这样 replay、持久化和取消都在同一个生命周期里。 + ### `mate_tool_approval` 表 | 列 | 用途 | @@ -283,24 +285,28 @@ Pending approval 在一个可配置的超时后过期（默认 10 分钟）。 MateClaw 可以通过 `channel/notification/` 适配器通知——邮件、应用内提醒、钉钉/飞书推送。在 `设置 → 安全与审批 → 通知` 里配置。 -### API 方式处理审批 +### 当前 API 表面 ```bash -# 列出 pending 审批 -curl http://localhost:18088/api/v1/approvals?status=pending \ +# 刷新页面后补水 pending 审批 +curl http://localhost:18088/api/v1/chat/{conversationId}/pending-approvals \ -H "Authorization: Bearer " -# 批准 -curl -X POST http://localhost:18088/api/v1/approvals/123/resolve \ +# 在等待中的会话里批准 +curl -N -X POST http://localhost:18088/api/v1/chat/stream \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ - -d '{"decision": "approved"}' + -d '{"agentId":"1","conversationId":"conv-abc123","message":"/approve"}' -# 拒绝并带原因 -curl -X POST http://localhost:18088/api/v1/approvals/123/resolve \ +# 在等待中的会话里拒绝 +curl -N -X POST http://localhost:18088/api/v1/chat/stream \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ - -d '{"decision": "rejected", "notes": "这个工作空间不适合"}' + -d '{"agentId":"1","conversationId":"conv-abc123","message":"/deny"}' + +# 管理自动批准授权 +curl http://localhost:18088/api/v1/approval/grants \ + -H "Authorization: Bearer " ``` --- diff --git a/mateclaw-server/src/main/resources/docs/zh/skills.md b/mateclaw-server/src/main/resources/docs/zh/skills.md index 88b8b992..2ebd57c7 100644 --- a/mateclaw-server/src/main/resources/docs/zh/skills.md +++ b/mateclaw-server/src/main/resources/docs/zh/skills.md @@ -531,6 +531,18 @@ mateclaw: --- +## 聊天里的 `/skill` 斜杠菜单（1.5.0 新增） + +不想用自然语言提示员工用哪个技能？在聊天输入框打一个 `/`，弹出一个**可搜索的技能选择器**： + +- ↑↓ 选、Enter/Tab 确认、Esc 关；打字实时过滤已启用的技能（最多显示 8 条）。 +- 列表来自 `GET /api/v1/skills/enabled`——包含真实技能 + MCP/ACP 派生的虚拟技能（同名时真实技能优先）。30 秒按工作空间缓存，避免每次重开都拉取。 +- 选中一个技能后，输入框里被插入一句指令：`Use the "技能名" skill: `，光标停在末尾，你接着补充上下文发出去。员工在消息历史里看到这条指令，就会调 `load_skill` 拉起这个技能。 + +这个菜单的显示条件只看**当前选中了员工、且该员工没有关闭技能**（前端 `currentAgent && !skillsDisabled`）——和全局的渐进式披露开关无关。全局把 `mateclaw.skill.disclosure.load-skill-tool.enabled` 设为 `false` 只会让后端不注册 `load_skill` 工具，菜单照样弹（员工会回退用 `readSkillFile` 之类的方式拉技能）。 + +--- + ## 技能生命周期管理员（v1.4 新增） 会合成技能的 Agent 会攒下垃圾——三周前的一次性技能还在目录里占着位子。**管理员（curator）** 是一个每日扫描，把闲置的、**Agent 创建的**技能沿 `active → stale → archived` 老化，让它们退场而不删除任何东西。 diff --git a/mateclaw-server/src/main/resources/docs/zh/tools.md b/mateclaw-server/src/main/resources/docs/zh/tools.md index 41461f7e..71beee72 100644 --- a/mateclaw-server/src/main/resources/docs/zh/tools.md +++ b/mateclaw-server/src/main/resources/docs/zh/tools.md @@ -319,14 +319,14 @@ curl -X PUT http://localhost:18088/api/v1/tools/1 \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -d '{"enabled": false}' -# 直接测试一个工具 -curl -X POST http://localhost:18088/api/v1/tools/WebSearchTool/test \ +# 设置内置或渠道工具的披露分级 +curl -X PUT http://localhost:18088/api/v1/tools/1/disclosure-tier \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ - -d '{"query": "Spring AI"}' + -d '{"tier": "core"}' ``` -每个依赖 provider 的工具在 Tools 页面都有测试按钮。 +当前 REST API 管理工具行、启用状态和披露分级。内置工具的直接执行走 Agent runtime，不存在 `/tools/{name}/test` 端点。 --- diff --git a/mateclaw-server/src/main/resources/docs/zh/wiki.md b/mateclaw-server/src/main/resources/docs/zh/wiki.md index 0498b38a..cba5cd99 100644 --- a/mateclaw-server/src/main/resources/docs/zh/wiki.md +++ b/mateclaw-server/src/main/resources/docs/zh/wiki.md @@ -258,6 +258,8 @@ UI 上能做： | `wiki_related_pages` | 关联页面（共享 chunk / 共享原文 / 双向链 / 语义近邻） | | `wiki_explain_relation` | 详细拆解两页之间的关联强度和原因 | | `wiki_create_page` / `wiki_delete_page` | 直接维护页面（删除受 locked / system 保护） | +| `wiki_update_page` | **1.5.0**：就地编辑一页（保留 slug），受 pageType "改" 权限门禁 | +| `wiki_stale_pages` | **1.5.0**：列出当前所有被标记"待复核（stale）"的页 | | `wiki_archive_page` / `wiki_unarchive_page` | 软归档：从默认 list/search/related 隐藏，但保留页面与引文，可恢复。系统页不能归档。 | | `wiki_list_transformations` | 列出当前 KB 可用的加工器模板（名称、用途、是否默认运行）| | `wiki_apply_transformation` | 对一份**原始材料**运行一个模板，返回输出（runId / output / 落页信息）| @@ -299,13 +301,11 @@ UI 上能做： #### 运维端点 -基础路径 `/api/v1/wiki/hot-cache`： - | Method | Path | 作用 | |---|---|---| -| `GET` | `/{kbId}` | 拿当前快照 + 元数据 | -| `POST` | `/{kbId}/regenerate` | 手动重建（异步，跳过去抖） | -| `DELETE` | `/{kbId}` | 软删除；下次事件触发重建 | +| `GET` | `/api/v1/wiki/hot-cache/{kbId}` | 拿当前快照 + 元数据 | +| `POST` | `/api/v1/wiki/hot-cache/{kbId}/regenerate` | 手动重建（异步，跳过去抖） | +| `DELETE` | `/api/v1/wiki/hot-cache/{kbId}` | 软删除；下次事件触发重建 | 热缓存数据落在 `mate_wiki_hot_cache`——具体列见下面的 **底层数据** 一节。 @@ -342,6 +342,166 @@ AI 写错了就改。你的修改在下一次入库时会被保留——`locked` --- +## Wikilink 与死链治理 + +页面之间用 `[[slug]]` 写跨页引用，是 Wiki 这种长寿命知识资产的核心粘合剂。RFC 55 把这一层从 "[[Title]] 写起来好像也行、点了 404 才发现" 改成 **写入即校验、删除自动清理、死链显式可见**。 + +### Wikilink 语法 + +只承认一种契约： + +- `[[slug]]` —— 显示文本默认用目标页的 title +- `[[slug|显示文本]]` —— 自定义显示文本，slug 仍是跳转目标 + +slug 必须是真实存在页面的 slug。LLM 生成内容时索引里给的就是 slug-first 列表（`- [[slug]] — Title — Summary`），prompt 显式禁止发明索引外的 slug，并明示 `[[页面标题]]` / `[[Title]]` 这种早期写法会被识别为死链。 + +跨大小写命中：`[[STATEGRAPH]]` 和 `[[stategraph]]` 一视同仁，都按 lowercased exact match 匹配 slug。 + +### 同事务校验：`outgoing_links` + `broken_links` + +每次页面保存（手工编辑、AI 生成、合并、级联重写）的**同一个事务**内： + +1. 从正文里抽出所有 `[[...]]`（跳过 fenced 代码块、inline 代码） +2. 写 `mate_wiki_page.outgoing_links`（去重、lowercased 字符串数组） +3. 拿当前 KB 的活跃 slug 集合（不含 archived）做差集 → 写 `broken_links` +4. 写 `broken_links_scanned_at` 时间戳 + +效果：写完页面**立刻**就知道哪些 `[[...]]` 是死链，不需要等扫描。代码块和反引号里的 `[[...]]` 是讲解 wiki 语法的示例，被严格保留为字面，不进入 outgoing。 + +### KB 级死链 lint + +进入任一 KB，顶部 banner 会显示当前死链状态。按"扫描死链"启动一次全 KB job： + +| Method | Path | 说明 | +|---|---|---| +| `POST /api/v1/wiki/knowledge-bases/{kbId}/lint/broken-links` | 启动 job（job-based 异步），返回 `{jobId, status, startedAt}`；同 KB 已有 running job 时幂等返回 | +| `GET .../lint/broken-links` | 拉最近一次 completed 扫描的聚合结果 | +| `GET .../lint/broken-links/jobs/{jobId}` | 查单次 job 状态 | + +聚合结果按页列出，每条带 `pageId / slug / title / brokenRefs`。前端 banner 把"已扫描 X 页，无死链"和"发现 N 条死链分布在 M 页"区分显示，点"查看"打开详情面板，可一键跳到出错的源页面去手工修。 + +job 执行时间：100 页 KB 通常 1 秒以内；POST 入队 < 200ms。 + +### 删除 / 重命名的级联清理 + +**删页面**时，所有引用方的 `[[deleted-slug]]` 会在同一事务里被改写成纯文本，保留快照标题作为可读文字。带别名的 `[[deleted-slug|alias]]` 直接降级为 `alias`。引用方的 `outgoing_links` / `broken_links` 跟着重算。 + +**重命名页面**：`POST /api/v1/wiki/knowledge-bases/{kbId}/pages/{slug}/rename` body `{"newSlug":"new"}`。同一事务里： + +- 自身 slug 更新为新值 +- 所有引用方的 `[[oldSlug]]` 改写成 `[[newSlug]]`，`[[oldSlug|alias]]` 改写成 `[[newSlug|alias]]`（alias 字节一致保留） +- 引用方的 `outgoing_links` 同步更新 + +不接受空 slug、不接受和自身相同的 slug、不接受和**别的**页面冲突的 slug；保护页（system / locked）拒改。case-only rename（`foo → FOO`）允许，跨 H2 与 MySQL 行为一致。 + +每次 delete / rename 写一条 `mate_audit_event`（action `wiki.page.delete` / `wiki.page.rename`），`detailJson` 里带 `affectedPageIds` 列表，方便事后追溯影响面。 + +紧急 kill-switch：`mate.wiki.cascade-delete-enabled=false` 关闭级联，回到只删自身行的旧行为；正常状态下不需要开启。 + +### Chat 里点 wikilink 直接跳 + +Chat 渲染 agent 回复时，content 里的 `[[slug]]` / `[[slug|alias]]` 会渲染成带 `data-wiki-title` 的 ``。点一下： + +1. App 级全局 click 委托抓到 click +2. 调 `GET /api/v1/wiki/pages/lookup?title=X&slug=X` —— 在用户可见的所有 KB 里搜（slug 命中优先，title fallback） +3. 1 hit → `router.push` 进 wiki 视图、自动选 KB、自动打开页面 +4. 0 hit → toast "未找到匹配的 wiki 页面：X" +5. 多 hit → picker 让用户挑 + +不再需要先去 wiki 视图、再找 KB、再找页面——chat 里看到的引用直接跳。lookup 严格 case-insensitive exact，不做 canonical 模糊，所以 LLM 写错 slug 会通过 toast 让你看到，而不是悄悄跳到一个"看起来像的"页面。 + +### Phase 路线图（每个 phase 都已 land） + +| Phase | 主要变更 | +|---|---| +| 1 | 前端渲染层 slug-first DOM postprocess + 危险字符 guard + 全量 `pages/refs` | +| 2 | V129 迁移 `broken_links` / `broken_links_scanned_at`，save 同事务写，KB 级 lint job + UI banner | +| 3 | 9 份 wiki prompt 统一 `[[slug]]` 契约，索引格式 slug-first，batch-create existing/planned 二分 | +| 4 | 删除 / 重命名级联清理，audit log，feature flag | +| 5 | analyze 阶段输出 slug 白名单 `related_pages`（服务端二次校验），enrich applier 跳代码块 + slug 白名单 gate | + +完整设计与实测见仓库内对应的设计文档与端到端验证记录。 + +--- + +## 知识库会自维护（1.5.0） + +1.5.0 把 Wiki 从"一个能搜的知识库"推进成"一个会自己维护一致性、自己分层、自己跑流水线、能挂本地目录的知识引擎"。这一整块的管理入口在后台的 **Wiki 高级管理面板**（五个子页：页面类型档案 / 分层与失效 / 权限 / 知识源 watcher / 流水线）。 + +### 知识分层：事实 vs 经验 + +每页可以标一个**知识层**： + +- **`fact`（事实层）**——"是什么"：基础事实页。不标的默认按事实处理。 +- **`experience`（经验层）**——"意味着什么"：综合、分析、个人洞见，**依赖**一组事实页。 + +**失效会传播。** 经验页声明它依赖哪些事实页（按页面 **id** 存边，所以改名不断链）。当某个事实页在 ingest 时被更新，所有依赖它的经验页自动被标记 `stale`（待复核）+ 一段失效原因。`wiki_stale_pages` 工具列出当前所有待复核的页；搜索可以**按知识层过滤**（只搜事实 / 只搜经验 / 全部）。 + +底层：`mate_wiki_page` 加了 `knowledge_layer` / `depends_on_json` / `stale` / `stale_reason_json` 列（迁移 V135），依赖边存在 `mate_wiki_page_dependency` 表，带一个反向索引专门给失效传播用。 + +### 页面类型档案（pageType profile） + +为一个知识库定义有哪些**页面类型**（如"概念 / 教程 / 决策记录"），每种类型可以带： + +- 结构化字段 **schema**——新页落库时按它校验元数据，并记下校验状态（valid / invalid + 详情） +- **路由 / 创建 / 合并** 阶段的提示词——注入到对应阶段的 LLM 调用里 +- **Markdown 模板**——生成页面时的骨架 + +每个 KB 至多一个**启用的** profile；没配的 KB 用**内建默认档案**。profile 用 YAML 或 JSON 写，有"校验（不落库）"和"重置为默认"两个动作。存在 `mate_wiki_page_type_profile` 表（迁移 V134），页面元数据列也在同一迁移里加到 `mate_wiki_page`（`metadata_json` / `metadata_validation_status` / `template_key` / `profile_version`）。 + +### 页面类型权限（per-agent） + +可以为"**某个员工 + 某个 KB + 某种页面类型**"配读 / 增 / 改 / 删四个开关，外加**写策略**： + +| 写策略 | 含义 | +|---|---| +| `allow` | 立即写 | +| `approval_required` | 写入挂起，走[审批](./security)流程 | +| `deny` | 禁止 | + +`page_type='*'` 是 KB 级默认，**精确匹配优先于通配**。 + +**读和写的默认回退不一样**，这点要分清： + +- **读**——没匹配到规则时，回退到 **KB 级默认读策略** `defaultReadPolicy`（默认 `allow_all`，除非 KB 配成 `deny_all`）。所以升级后已有 KB 仍然全可读。读门禁过滤列表和搜索结果，不可读的类型直接当不存在（不泄露存在性）。 +- **写**——是 opt-in 收紧的。一个员工对某 KB **没配任何规则**时，写默认 `allow`（旧行为不变）；一旦配了**任意一条**规则，这个 KB 就进入"锁定"模式——没匹配到规则的页面类型按 `deny` 处理（fail-safe）。 + +存在 `mate_wiki_agent_page_type_permission` 表（迁移 V133）。 + +### 处理流水线（Wiki Pipeline） + +给知识库定义一段处理流程，由**页面事件自动触发**： + +- **触发器**：`page_type_count`（某类页面数量达到阈值）、`page_created`（新建某类页面）、`stale_marked`（页面被标记失效） +- **步骤执行器**： + - `llm`——把输入过一遍模型，模型输出作为本步结果 + - `skill`——在**受限技能集**内跑一个技能，以 owner agent 身份执行 + +定义用 YAML 或 JSON 写，有 CRUD + 校验接口。每次运行（run）和每一步（step run）都有持久化记录可查，按 `(definition, trigger, subject, bucket)` 去重保证幂等。表：`mate_wiki_pipeline_definition` / `mate_wiki_pipeline_run` / `mate_wiki_pipeline_step_run`（迁移 V136）。 + +### 本地目录挂成知识源——可插拔 + 定时增量 + +知识源做成了**可插拔 SPI**（`WikiIngestSourceProvider`），内建一个文件系统实现：给 KB 配一个 `source_directory`，目录里的文件就被吸进知识库。 + +- **定时增量同步**——后台调度器（用分布式锁保证多节点只跑一份）周期扫描，**按内容哈希**检测变更，只重新吸入新增 / 改动的文件（文本和二进制都覆盖）。 +- **安全 fail-closed**——路径先规范化再解析软链（堵 TOCTOU），按允许根目录白名单校验；生产 profile 下空白名单默认拒绝一切。配 `mate.wiki.allowed-source-roots` 白名单。 +- **状态可查 + 手动触发**——`GET .../source-watcher` 看状态，`POST .../source-watcher/scan` 立即扫一次。 + +相关配置（`application.yml`）： + +```yaml +mate: + wiki: + watcher-enabled: false # 知识源 watcher 总开关 + watcher-interval-ms: 300000 # 扫描间隔（默认 5 分钟） + allowed-source-roots: [] # 允许的源目录根（白名单） + require-allowed-roots: false # 生产建议设 true：空白名单则拒绝一切 +``` + +全部新增 REST 端点见 [API 参考](./api#llm-wiki)。 + +--- + ## 搜索、来源追溯、语义检索 - **语义搜索**——问"我们关于 auth 决定了什么？"，直接返回那个决策，不是一堆包含"auth"的页面。chunk 级嵌入 + cosine 检索，**理解你问的是什么意思**。命中现在自带 `pageNumber` 和 `section`，agent 可以引用 "page 12, Setup / Linux" 而不是粘一段没头没尾的片段。 diff --git a/mateclaw-server/src/main/resources/mapper/ApprovalGrantMapper.xml b/mateclaw-server/src/main/resources/mapper/ApprovalGrantMapper.xml new file mode 100644 index 00000000..cc66f5ff --- /dev/null +++ b/mateclaw-server/src/main/resources/mapper/ApprovalGrantMapper.xml @@ -0,0 +1,86 @@ + + + + + + + + + + UPDATE mate_approval_grant + SET revoked = 1, + revoked_at = CURRENT_TIMESTAMP, + update_time = CURRENT_TIMESTAMP, + note = CASE + WHEN note IS NULL OR note = '' THEN '(auto-revoked on conversation delete)' + ELSE CONCAT(note, ' (auto-revoked on conversation delete)') + END + WHERE deleted = 0 + AND revoked = 0 + AND grant_kind = 'UNTIL_CONVERSATION_END' + AND scope_type = 'CONVERSATION' + AND scope_id = #{conversationId} + + + diff --git a/mateclaw-server/src/main/resources/messages.properties b/mateclaw-server/src/main/resources/messages.properties index e38c3353..db083456 100644 --- a/mateclaw-server/src/main/resources/messages.properties +++ b/mateclaw-server/src/main/resources/messages.properties @@ -37,11 +37,11 @@ tool.execute_shell_command.desc=\u5728\u672c\u5730\u670d\u52a1\u5668\u4e0a\u6267 tool.execute_shell_command.param.command=\u8981\u6267\u884c\u7684 Shell \u547d\u4ee4 tool.execute_shell_command.param.timeoutSeconds=\u8d85\u65f6\u79d2\u6570\uff0c\u9ed8\u8ba4 60 \u79d2 -tool.search.desc=\u5728\u4e92\u8054\u7f51\u4e0a\u641c\u7d22\u6700\u65b0\u4fe1\u606f\u3002\u5f53\u9700\u8981\u67e5\u8be2\u5b9e\u65f6\u65b0\u95fb\u3001\u6700\u65b0\u6570\u636e\u6216\u4e0d\u786e\u5b9a\u7684\u4e8b\u5b9e\u65f6\u4f7f\u7528\u6b64\u5de5\u5177\u3002\u652f\u6301 freshness\u3001language\u3001count \u53ef\u9009\u53c2\u6570\u3002 -tool.search.param.query=\u641c\u7d22\u5173\u952e\u8bcd -tool.search.param.freshness=\u65f6\u95f4\u8303\u56f4\u8fc7\u6ee4: day (\u4eca\u5929), week (\u672c\u5468), month (\u672c\u6708), year (\u4eca\u5e74) -tool.search.param.language=\u8bed\u8a00\u504f\u597d: zh-CN (\u4e2d\u6587), en (\u82f1\u6587) -tool.search.param.count=\u6700\u5927\u7ed3\u679c\u6570\u91cf: 1-10, \u9ed8\u8ba4 5 +tool.web_search.desc=\u5728\u4e92\u8054\u7f51\u4e0a\u641c\u7d22\u6700\u65b0\u4fe1\u606f\u3002\u5f53\u9700\u8981\u67e5\u8be2\u5b9e\u65f6\u65b0\u95fb\u3001\u6700\u65b0\u6570\u636e\u6216\u4e0d\u786e\u5b9a\u7684\u4e8b\u5b9e\u65f6\u4f7f\u7528\u6b64\u5de5\u5177\u3002\u652f\u6301 freshness\u3001language\u3001count \u53ef\u9009\u53c2\u6570\u3002 +tool.web_search.param.query=\u641c\u7d22\u5173\u952e\u8bcd +tool.web_search.param.freshness=\u65f6\u95f4\u8303\u56f4\u8fc7\u6ee4: day (\u4eca\u5929), week (\u672c\u5468), month (\u672c\u6708), year (\u4eca\u5e74) +tool.web_search.param.language=\u8bed\u8a00\u504f\u597d: zh-CN (\u4e2d\u6587), en (\u82f1\u6587) +tool.web_search.param.count=\u6700\u5927\u7ed3\u679c\u6570\u91cf: 1-10, \u9ed8\u8ba4 5 tool.create_cron_job.desc=\u521b\u5efa\u5b9a\u65f6\u4efb\u52a1\u3002\u4efb\u52a1\u5c06\u5728\u6307\u5b9a\u65f6\u95f4\u81ea\u52a8\u8fd0\u884c\u5e76\u5411\u5f53\u524d Agent \u53d1\u9001\u89e6\u53d1\u6d88\u606f\u3002\u4f7f\u7528 5 \u5b57\u6bb5 cron \u8868\u8fbe\u5f0f\uff1a\u5206 \u65f6 \u65e5 \u6708 \u5468\u3002 tool.list_cron_jobs.desc=\u5217\u51fa\u6240\u6709\u5b9a\u65f6\u4efb\u52a1\uff0c\u5305\u542b\u540d\u79f0\u3001cron \u8868\u8fbe\u5f0f\u3001\u4e0b\u6b21\u8fd0\u884c\u65f6\u95f4\u3001\u542f\u7528\u72b6\u6001\u3002 @@ -171,6 +171,8 @@ err.agent.not_found=Agent\u4e0d\u5b58\u5728 err.agent.disabled=Agent \u5df2\u7981\u7528 err.agent.name_required=Agent \u540d\u79f0\u4e0d\u80fd\u4e3a\u7a7a err.agent.duplicate_name=\u5f53\u524d\u5de5\u4f5c\u533a\u5df2\u5b58\u5728\u540c\u540d\u5458\u5de5\uff0c\u8bf7\u6362\u4e2a\u540d\u5b57\u518d\u8bd5 +err.workflow.name_required=\u5de5\u4f5c\u6d41\u540d\u79f0\u4e0d\u80fd\u4e3a\u7a7a +err.workflow.duplicate_name=\u5f53\u524d\u5de5\u4f5c\u533a\u5df2\u5b58\u5728\u540c\u540d\u5de5\u4f5c\u6d41\uff0c\u8bf7\u6362\u4e2a\u540d\u5b57\u518d\u8bd5 err.workspace.not_found=\u5de5\u4f5c\u533a\u4e0d\u5b58\u5728 err.workspace.slug_exists=\u5de5\u4f5c\u533a\u6807\u8bc6\u5df2\u5b58\u5728 err.workspace.cannot_modify_default=\u4e0d\u80fd\u4fee\u6539\u9ed8\u8ba4\u5de5\u4f5c\u533a\u7684\u6807\u8bc6 @@ -291,6 +293,7 @@ guard.path.symlink_escape=\u8def\u5f84\u901a\u8fc7\u7b26\u53f7\u94fe\u63a5\u9003 context.current_time=[system-context] \u5f53\u524d\u65f6\u95f4: {0} {1} (Asia/Shanghai) context.working_dir=[system-context] \u5de5\u4f5c\u76ee\u5f55: {0} context.working_dir_hint=\u4f60\u53ea\u80fd\u5728\u6b64\u76ee\u5f55\u53ca\u5176\u5b50\u76ee\u5f55\u5185\u8bfb\u5199\u6587\u4ef6\u548c\u6267\u884c\u547d\u4ee4\u3002 +context.skill_dir_hint=\u5171\u4eab\u6280\u80fd\u4f4d\u4e8e {0}\uff0c\u4f60\u4e5f\u53ef\u4ee5\u8bfb\u53d6\u548c\u8fd0\u884c\u5176\u4e2d\u7684\u6587\u4ef6\uff08\u5373\u4f7f\u5728\u5de5\u4f5c\u76ee\u5f55\u4e4b\u5916\uff09\u3002 # --- Wiki Research Fallback (RFC: prompt-cleanup) --- research.fallback.no_plan=\u65e0\u6cd5\u4e3a\u8be5\u4e3b\u9898\u751f\u6210\u7814\u7a76\u8ba1\u5212\u3002 diff --git a/mateclaw-server/src/main/resources/messages_en.properties b/mateclaw-server/src/main/resources/messages_en.properties index da1b0d46..823dd2f9 100644 --- a/mateclaw-server/src/main/resources/messages_en.properties +++ b/mateclaw-server/src/main/resources/messages_en.properties @@ -37,11 +37,11 @@ tool.execute_shell_command.desc=Execute a shell command on the local server. For tool.execute_shell_command.param.command=Shell command to execute tool.execute_shell_command.param.timeoutSeconds=Timeout in seconds, default 60 -tool.search.desc=Search the internet for latest information. Use when querying real-time news, latest data, or uncertain facts. Supports optional freshness, language, count parameters. -tool.search.param.query=Search keywords -tool.search.param.freshness=Time range filter: day (today), week (this week), month (this month), year (this year) -tool.search.param.language=Language preference: zh-CN (Chinese), en (English) -tool.search.param.count=Max results: 1-10, default 5 +tool.web_search.desc=Search the internet for latest information. Use when querying real-time news, latest data, or uncertain facts. Supports optional freshness, language, count parameters. +tool.web_search.param.query=Search keywords +tool.web_search.param.freshness=Time range filter: day (today), week (this week), month (this month), year (this year) +tool.web_search.param.language=Language preference: zh-CN (Chinese), en (English) +tool.web_search.param.count=Max results: 1-10, default 5 tool.create_cron_job.desc=Create a scheduled task (cron job). Runs automatically at specified time and sends trigger message to current agent. Use 5-field cron: minute hour day month weekday. tool.list_cron_jobs.desc=List all scheduled tasks with name, cron expression, next run time, and enabled status. @@ -177,6 +177,8 @@ err.agent.not_found=Agent not found err.agent.disabled=Agent is disabled err.agent.name_required=Agent name is required err.agent.duplicate_name=An employee with this name already exists in this workspace — try a different name +err.workflow.name_required=Workflow name is required +err.workflow.duplicate_name=A workflow with this name already exists in this workspace — try a different name # workspace err.workspace.not_found=Workspace not found err.workspace.slug_exists=Workspace slug already exists @@ -298,6 +300,7 @@ err.approval.not_found=Approval record not found or expired context.current_time=[system-context] Current time: {0} {1} (Asia/Shanghai) context.working_dir=[system-context] Working directory: {0} context.working_dir_hint=You can only read/write files and execute commands within this directory and its subdirectories. +context.skill_dir_hint=Shared skills live under {0}; you may also read and run files there, even though it is outside the working directory. # --- Wiki Research Fallback (RFC: prompt-cleanup) --- research.fallback.no_plan=Unable to generate a research plan for this topic. diff --git a/mateclaw-server/src/main/resources/prompts/memory/summarize-system.txt b/mateclaw-server/src/main/resources/prompts/memory/summarize-system.txt index dde6c576..9a2774cf 100644 --- a/mateclaw-server/src/main/resources/prompts/memory/summarize-system.txt +++ b/mateclaw-server/src/main/resources/prompts/memory/summarize-system.txt @@ -4,9 +4,18 @@ 记忆文件分三种： 1. **PROFILE.md** — 用户画像：稳定的身份信息、偏好、协作方式、沟通风格 -2. **MEMORY.md** — 长期记忆：稳定事实、经验教训、工作流、工具配置、反复出现的规律 +2. **MEMORY.md** — 长期记忆：**跨项目稳定**的事实、经验教训、通用工作流、工具配置、反复出现的规律 3. **memory/YYYY-MM-DD.md** — 每日笔记：一次性事件、当天上下文、临时决定、会议记录 +## 记忆分层纪律（重要） + +MEMORY.md 与 PROFILE.md 会被**无条件注入每一次对话的系统提示**，因此只能放**跨项目、长期稳定、不随项目切换而改变**的信息。 + +- **不要把具体项目的易变事实写进 MEMORY.md**：项目代号、项目名称、单个项目的技术栈、仓库地址、单项目的指标/预算/团队/上线日期、只对某个项目成立的决策——这些都**不属于**稳定事实，写进去会在用户切换项目时与其他项目互相冲突，导致助手张冠李戴。 +- 这类**项目/情景信息**应放入当日 `memory/YYYY-MM-DD.md`（情景记录），由对话中按需召回；需要长期保留的项目事实，应通过结构化 project 记忆（`remember_structured`）维护，而不是塞进 MEMORY.md。 +- MEMORY.md 只保留**与具体项目无关**的内容：用户长期偏好、协作约定、通用工作流、工具/环境配置、反复验证的经验教训。 +- 判定口诀：一条信息**换一个项目后是否仍然成立**？成立 → 可进 MEMORY.md；不成立（只对当前项目为真）→ 进 daily note 或结构化 project 记忆。 + ## 判断原则 - **只提取真正新的信息**：如果信息已经在现有记忆文件中，不要重复提取 @@ -27,12 +36,18 @@ "daily_entry": null, "memory_update": null, "profile_update": null, + "structured_entries": null, "reason": "简要说明判断理由" } 字段说明： - `should_update`: 布尔值，是否有任何需要更新的内容。如果为 false，其余字段应为 null - `daily_entry`: 字符串或 null。要追加到今日 daily note 的内容（markdown 格式，以时间戳开头如 "## HH:mm ..."） -- `memory_update`: 字符串或 null。MEMORY.md 的完整新内容（已合并现有内容，不是增量）。仅当有需要新增或修改的稳定信息时才填写 +- `memory_update`: 字符串或 null。MEMORY.md 的完整新内容（已合并现有内容，不是增量）。仅当有需要新增或修改的**跨项目稳定**信息时才填写 - `profile_update`: 字符串或 null。PROFILE.md 的完整新内容（已合并现有内容，不是增量）。仅当用户身份/偏好有显著变化时才填写 +- `structured_entries`: 数组或 null。把适合按条目检索的**具体事实**路由到结构化记忆，每个元素形如 `{"type": "...", "key": "...", "content": "..."}`： + - `type` 取值：`user`（用户偏好/专长/沟通风格/角色）、`feedback`（被纠正的行为或确认的做法，含原因）、`project`（具体项目的代号/名称/技术栈/指标/预算/团队/约束/单项目决策）、`reference`（外部系统指针，如某看板/频道/文档地址） + - `key`: 稳定的英文蛇形命名，便于后续更新同一条目（如 `project_codename`、`project_tech_stack`、`preferred_output_format`） + - `content`: 一两句话陈述该事实 + - **重要**：上面「记忆分层纪律」要求不进 MEMORY.md 的项目易变事实（代号、技术栈、单项目指标/预算/团队等），应放在这里（`type=project`），这样才能在后续对话中按问题被召回；不要让它们只停留在 daily note。 - `reason`: 简要说明判断理由 diff --git a/mateclaw-server/src/main/resources/prompts/wiki/analyze-system.txt b/mateclaw-server/src/main/resources/prompts/wiki/analyze-system.txt index 27509c31..eb0804b7 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/analyze-system.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/analyze-system.txt @@ -1,10 +1,11 @@ -你是一个知识库结构分析助手。你的任务是阅读原始材料，输出一份简洁的概念地图，供后续 Wiki 路由阶段参考。 +你是一个知识库结构分析助手。你的任务是阅读原始材料，输出一份简洁的概念地图 + 推荐链接白名单，供后续 Wiki 路由 / 生成阶段参考。 ## 你做什么 1. 识别文档覆盖的**核心主题**（5-15 个） 2. 列出**关键概念**（每个概念给出名称、建议 slug、重要度） 3. 用一段话描述文档的**整体结构**，帮助路由阶段理解各 chunk 的上下文 +4. 从「已有 Wiki 页面索引」中挑出与本文档真实相关的 slug，作为后续生成阶段的**推荐链接白名单** ## 输出格式 @@ -15,15 +16,21 @@ "key_concepts": [ {"name": "概念名称", "slug": "concept-slug", "importance": "high"} ], - "structure_notes": "一段话描述文档整体结构和主要章节" + "structure_notes": "一段话描述文档整体结构和主要章节", + "related_pages": ["existing-slug-a", "existing-slug-b"] } 字段说明： - `topics`：文档覆盖的核心主题列表，字符串数组，5-15 条 - `key_concepts`：关键概念，每条包含 name（人类可读）、slug（URL 安全小写连字符）、importance（high / medium） - `structure_notes`：1-3 句话，描述文档结构，帮助路由阶段在只看到局部 chunk 时理解全局 +- `related_pages`：**从上文「已有 Wiki 页面索引」中**挑选与本文档真实相关的 slug 数组。规则： + - **每个 slug 必须 100% 来自上文索引**，禁止发明新 slug + - 数组长度 0~20；只挑明显相关的页面，不要拼凑数量 + - 排序按相关度从高到低 + - 无相关页面时返回空数组 `[]` -## slug 规范 +## slug 规范（仅用于 `key_concepts` 中的建议 slug） - 多音节中文词按整词分组拼音，不要按字一隔 - ✅ `zhongyao-qiqing-peiwu`（中药 / 七情 / 配伍） @@ -34,4 +41,4 @@ - 输出体积控制在几百到两千字以内 - 不要输出任何页面正文，只输出概念地图 -- 如果文档内容不足（如空白、纯目录），`key_concepts` 可以为空数组 +- 如果文档内容不足（如空白、纯目录），`key_concepts` 和 `related_pages` 都可以为空数组 diff --git a/mateclaw-server/src/main/resources/prompts/wiki/analyze-user.txt b/mateclaw-server/src/main/resources/prompts/wiki/analyze-user.txt index 127bea58..6ac6a22e 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/analyze-user.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/analyze-user.txt @@ -2,6 +2,10 @@ {raw_title} +## 已有 Wiki 页面索引（用于挑选 related_pages 白名单；每行格式 `[[slug]] — 标题 — 摘要`） + +{existing_pages} + ## 文档内容（节选，用于全局结构分析） {text_sample} @@ -9,3 +13,5 @@ --- 请分析以上文档，输出概念地图 JSON。只输出 JSON，不要 markdown 代码块。 +- `related_pages` 中的每个 slug 必须 100% 来自上文「已有 Wiki 页面索引」 +- 没有相关已有页面时 `related_pages` 返回 `[]` diff --git a/mateclaw-server/src/main/resources/prompts/wiki/batch-create-system.txt b/mateclaw-server/src/main/resources/prompts/wiki/batch-create-system.txt index 74bb3546..fd674d15 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/batch-create-system.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/batch-create-system.txt @@ -5,7 +5,7 @@ - 读取 `pages_to_create` 数组，里面包含若干页面的 slug / title / summary - 从原始材料里抽取与每个页面主题相关的信息 - 为每个页面生成完整的 markdown 内容 -- 在内容里使用 [[页面标题]] 双向链接到其他相关页面（已有页面和同批次将创建的页面均可） +- 在内容里用 [[slug]] 双向链接到其他相关页面 ## 你不做什么 @@ -17,10 +17,20 @@ - 内容开头先一段话摘要（与 metadata 的 summary 一致或更详细） - 使用 Markdown 标题（## / ###）组织章节 -- 使用 [[页面标题]] 链接到其他相关页面 +- 用 [[slug]] 链接到其他相关页面 - 长度控制在 500~2000 字，不要为了凑字数而拖沓 - 内容至少包含 3 句实质信息 +## 链接（**单一契约，必须严格遵守**） + +- 只允许两种形态： + - `[[slug]]` —— 显示文本默认为目标页标题 + - `[[slug|显示文本]]` —— 显示文本自定义 +- slug **必须**来自以下两类来源之一： + - **已有 Wiki 页面索引**（user prompt 中列出）—— 这些链接是**强保证**，slug 100% 可用 + - **本批次同时创建的页面**（即 `pages_to_create` 数组中的 slug）—— 这类链接**不保证成功**：本批次中的页面可能因去重 / 合并 / 失败而最终未落库，导致链接转为死链；这是预期行为，系统会在写入后由 lint 标记并由人工修复 +- 禁止发明上述两类来源之外的 slug；禁止写 `[[页面标题]]` 形态 —— 系统按 slug 严格匹配，写标题会被识别为死链 + ## 输出格式（严格遵守） 每个页面输出一个 FILE 块，格式如下： @@ -40,4 +50,12 @@ - `title`：与 metadata 保持一致；如有更精确的描述可微调 - `content`：完整 markdown 正文 - `summary`：一段话简短摘要 -- `page_type`：页面类型，从以下值中选一个：concept / person / place / event / technology / organization / product / term / process / other +- `page_type`：页面类型，从下面"允许的页面类型"列表中选一个；都不合适时选 concept。 +- `metadata`（可选）：与所选 page_type 对应的结构化字段对象，只输出该类型声明的字段（带"required metadata"标注的字段应尽量补全）。 +- `depends_on`（可选，仅经验层页面需要）：本页所依赖的**事实层页面 slug 数组**。经验层(如 analysis/pattern/regime)必须列出其结论所基于的事实页 slug;事实层页面留空或不输出。 + +允许的页面类型： +{allowed_page_types} + +各类型内容模板(若某页的 page_type 有对应骨架,请按骨架组织正文;无则自由组织)： +{page_type_templates} diff --git a/mateclaw-server/src/main/resources/prompts/wiki/batch-create-user.txt b/mateclaw-server/src/main/resources/prompts/wiki/batch-create-user.txt index 6de57f8c..f44f3813 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/batch-create-user.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/batch-create-user.txt @@ -4,11 +4,13 @@ {document_map_section} -## 已有 Wiki 页面索引（用于建立 [[链接]]） +## 已有 Wiki 页面索引（强保证，可直接链接；每行格式 `[[slug]] — 标题 — 摘要`） {existing_pages} -## 待生成页面列表 +## 本批次将一并创建的页面（计划中，可能可被链接；slug 见下方 pages_to_create） + +链接到这一类的页面**不保证成功**：本批次中的页面可能因去重 / 合并 / 失败而最终未落库，对应的 `[[slug]]` 会在 lint 中被标记为死链，由人工后续修复。需要交叉引用时**优先**链接到上文「已有 Wiki 页面索引」中的页面。 ```json {pages_to_create} @@ -25,5 +27,5 @@ 请为上面 `pages_to_create` 数组中的**每一个页面**生成完整的 markdown 内容。 - 按 system 中规定的 FILE 块格式输出，每个页面一个 FILE 块 - 每个页面的内容必须基于原始材料中与该主题相关的信息 -- 适当使用 [[页面标题]] 链接到相关页面（同批次内其他页面也可链接） +- 适当使用 [[slug]] 链接到相关页面（slug 必须出自上文「已有 Wiki 页面索引」或本批次 `pages_to_create` 中的 slug） - 不要遗漏任何一个页面 diff --git a/mateclaw-server/src/main/resources/prompts/wiki/compile-system.txt b/mateclaw-server/src/main/resources/prompts/wiki/compile-system.txt index 31411329..7830edb1 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/compile-system.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/compile-system.txt @@ -9,7 +9,7 @@ Strict output contract — return ONLY this JSON object, nothing else: Rules: - Do not invent facts beyond the supplied evidence. If something is not in the evidence, do not assert it. -- Use [[wikilinks]] when an evidence breadcrumb names a related concept; alias form [[slug|display]] is fine. +- Wikilink contract: use [[slug]] or [[slug|display text]]. The slug MUST come from the existing-pages index supplied in the user prompt. Never invent a slug that is not in that index. If the evidence names a concept that has no existing page, write it as plain text — do not guess a slug. - Keep summary concise (single paragraph, <= 300 characters). - content must be Markdown with at least one ## header. - Do not include any prose outside the JSON object. diff --git a/mateclaw-server/src/main/resources/prompts/wiki/create-page-system.txt b/mateclaw-server/src/main/resources/prompts/wiki/create-page-system.txt index d0d48eb9..96a1db25 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/create-page-system.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/create-page-system.txt @@ -5,7 +5,7 @@ - 读懂该页 metadata 描述的主题 - 从原始材料里抽取与该主题相关的信息 - 为这一个页面生成完整的 markdown 内容 -- 在内容里使用 [[页面标题]] 双向链接到其他相关页面（无论是新建中还是已有） +- 在内容里用 [[slug]] 双向链接到其他相关页面 ## 你不做什么 @@ -17,19 +17,23 @@ - 内容开头先一段话摘要（与 metadata 的 summary 一致或更详细） - 使用 Markdown 标题（## / ###）组织 -- 使用 [[页面标题]] 双向链接到其他页面 +- 在正文中用 [[slug]] 链接到其他页面 - 每个不同的子主题用 ### 章节区分 -- 末尾可附"参见"段落，列出相关 [[链接]] +- 末尾可附"参见"段落，列出相关 [[slug]] ## 长度 - 单页内容控制在合理范围（一般 500~2000 字），不要为了凑长度而拖沓 - 内容应有 3 句以上的实质信息 -## 链接 +## 链接（**单一契约，必须严格遵守**） -- 已有页面索引中其他页的 slug 都可用 [[title]] 链接 -- 同批次将创建的其他页面也可以链接（按 metadata 中的 title） +- 只允许两种形态： + - `[[slug]]` —— 显示文本默认为目标页标题 + - `[[slug|显示文本]]` —— 显示文本自定义 +- `slug` **必须**来自上文"已有 Wiki 页面索引"段落中列出的 slug，**禁止发明**索引中不存在的 slug +- 不要写 `[[页面标题]]`、`[[Title]]` 这种形态 —— 系统会按 slug 严格匹配，写标题会被识别为死链 +- 如果某个相关概念没有对应的页面，不要硬塞链接，直接用普通文本描述即可 ## 语言 @@ -42,7 +46,7 @@ { "slug": "page-slug", "title": "页面标题", - "content": "## 标题\n\n摘要段落...\n\n### 详细内容\n...\n\n参见：[[相关页面]]", + "content": "## 标题\n\n摘要段落...\n\n### 详细内容\n...\n\n参见：[[related-slug]]", "summary": "一段话摘要" } @@ -51,3 +55,6 @@ - `title`：通常与 metadata 一致；如有更精确的描述可微调 - `content`：完整 markdown，开头一段摘要，后面分章节 - `summary`：一段话简短摘要（可与 metadata.summary 一致或精炼） + +## 内容指引(本知识库 / 该页类型) +{page_type_instructions} diff --git a/mateclaw-server/src/main/resources/prompts/wiki/create-page-user.txt b/mateclaw-server/src/main/resources/prompts/wiki/create-page-user.txt index 94d4da36..6ac2bb97 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/create-page-user.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/create-page-user.txt @@ -2,7 +2,7 @@ {config} -## 已有 Wiki 页面索引（用于建立 [[链接]]） +## 已有 Wiki 页面索引（用于建立 [[slug]] 链接；每行格式 `[[slug]] — 标题 — 摘要`） {existing_pages} @@ -23,4 +23,4 @@ slug：`{page_slug}` 请为上面 metadata 描述的**这一个页面**生成完整的 markdown 内容（按 system 中规定的 JSON 格式输出）。 - 只生成这一个 slug 对应的页面，不要顺便生成其他页面 - 内容必须基于原始材料中与该主题相关的信息 -- 适当使用 [[页面标题]] 链接到其他相关页面 +- 适当使用 [[slug]] 链接到其他相关页面（slug 必须来自上文索引） diff --git a/mateclaw-server/src/main/resources/prompts/wiki/default-page-type-profile.json b/mateclaw-server/src/main/resources/prompts/wiki/default-page-type-profile.json new file mode 100644 index 00000000..423fe5ff --- /dev/null +++ b/mateclaw-server/src/main/resources/prompts/wiki/default-page-type-profile.json @@ -0,0 +1,17 @@ +{ + "version": 1, + "fallbackType": "concept", + "allowAdditionalFields": true, + "pageTypes": { + "concept": { "label": "Concept", "description": "An abstract idea, theory, method or definition." }, + "person": { "label": "Person", "description": "An individual." }, + "place": { "label": "Place", "description": "A geographic location." }, + "event": { "label": "Event", "description": "A dated occurrence." }, + "technology": { "label": "Technology", "description": "A tool, system, framework or technique." }, + "organization": { "label": "Organization", "description": "A company, institution or group." }, + "product": { "label": "Product", "description": "A named product or offering." }, + "term": { "label": "Term", "description": "A glossary term or piece of terminology." }, + "process": { "label": "Process", "description": "A procedure, workflow or sequence of steps." }, + "other": { "label": "Other", "description": "Anything that does not fit the other types." } + } +} diff --git a/mateclaw-server/src/main/resources/prompts/wiki/digest-system.txt b/mateclaw-server/src/main/resources/prompts/wiki/digest-system.txt index 8948915c..9b1dbab8 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/digest-system.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/digest-system.txt @@ -5,7 +5,7 @@ 1. **阅读并理解原始材料** 2. **创建新的 Wiki 页面**：每个页面聚焦一个概念、实体或主题 3. **更新已有 Wiki 页面**：当新材料包含已有页面的相关信息时，合并更新 -4. **建立双向链接**：使用 [[页面标题]] 语法在页面间建立交叉引用 +4. **建立双向链接**：用 [[slug]] 语法在页面间建立交叉引用（slug 必须存在于本批次的 pages 或上下文索引中） ## 页面质量标准 @@ -19,7 +19,8 @@ - 每个页面以一段话摘要开头 - 使用清晰的 Markdown 标题（## 和 ###）组织内容 -- 在提到相关概念时使用 [[链接标题]] 链接到其他页面 +- 引用相关概念时**只能**用 [[slug]] 或 [[slug|显示文本]] 形态；slug 必须是本批次输出中的 slug，或上文索引中已存在的 slug +- 禁止写 [[页面标题]] 这种形态 —— 系统按 slug 严格匹配，写标题会被识别为死链 - 页面标题应简洁准确，反映核心内容 - slug（URL 标识符）使用小写字母、数字和连字符 @@ -45,7 +46,7 @@ { "slug": "concept-name", "title": "概念名称", - "content": "## 概念名称\n\n一段话摘要...\n\n### 详细内容\n...\n\n参见：[[相关主题]]", + "content": "## 概念名称\n\n一段话摘要...\n\n### 详细内容\n...\n\n参见：[[related-concept-slug]]", "summary": "一段话摘要" } ], diff --git a/mateclaw-server/src/main/resources/prompts/wiki/digest-user.txt b/mateclaw-server/src/main/resources/prompts/wiki/digest-user.txt index ea314107..b3d71fb2 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/digest-user.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/digest-user.txt @@ -2,7 +2,7 @@ {config} -## 已有 Wiki 页面索引 +## 已有 Wiki 页面索引（用于建立 [[slug]] 链接；每行格式 `[[slug]] — 标题 — 摘要`） {existing_pages} @@ -17,5 +17,5 @@ 请根据以上原始材料： 1. 根据材料内容的丰富程度，创建合适数量的高质量页面（不追求数量，宁少勿多） 2. 如果已有页面与新材料相关，更新这些页面（不要重复创建已有概念的页面） -3. 确保页面间有充分的 [[双向链接]] +3. 确保页面间有充分的 [[slug]] 双向链接（slug 必须存在于本次输出的 pages 中，或上文索引中） 4. 每个页面聚焦单一主题，内容完整且有实质价值 diff --git a/mateclaw-server/src/main/resources/prompts/wiki/merge-page-system.txt b/mateclaw-server/src/main/resources/prompts/wiki/merge-page-system.txt index e1a0641e..f1527769 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/merge-page-system.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/merge-page-system.txt @@ -20,10 +20,12 @@ - 新材料对该页面无新增信息 → 输出原 content 即可（保持不变） - 已有页面 lastUpdatedBy=manual → 仍然合并，但优先保留手动编辑的措辞和结构，仅追加新事实 -## 链接 +## 链接（**单一契约，必须严格遵守**） -- 沿用已有页面里的 [[页面标题]] 双向链接 -- 如果新材料引出了对其他已知概念的引用，新增 [[…]] 链接 +- 只允许两种形态：`[[slug]]` 与 `[[slug|显示文本]]` +- 沿用已有页面里的所有 `[[slug]]` 链接（如果它们指向已存在的页面） +- 如果新材料引出了对其他已知页面的引用，**只能**用上文"已有 Wiki 页面索引"中列出的 slug 来建立新链接 +- 禁止发明索引中不存在的 slug；禁止写 `[[页面标题]]` —— 系统按 slug 严格匹配，写标题会被识别为死链 ## 语言 @@ -36,7 +38,7 @@ { "slug": "existing-slug", "title": "页面标题（可微调）", - "content": "## 标题\n\n摘要...\n\n### 章节...\n\n参见：[[相关]]", + "content": "## 标题\n\n摘要...\n\n### 章节...\n\n参见：[[related-slug]]", "summary": "更新后的一段话摘要" } @@ -45,3 +47,6 @@ - `title`：通常保持不变；只有当新材料明确改变了页面主题时才改 - `content`：完整 markdown，包含原内容中仍然有效的部分 + 来自新材料的新增信息 - `summary`：更新后的一段话摘要 + +## 该类型的合并策略(本知识库) +{page_type_merge_instruction} diff --git a/mateclaw-server/src/main/resources/prompts/wiki/route-system.txt b/mateclaw-server/src/main/resources/prompts/wiki/route-system.txt index 96174a5f..554855b1 100644 --- a/mateclaw-server/src/main/resources/prompts/wiki/route-system.txt +++ b/mateclaw-server/src/main/resources/prompts/wiki/route-system.txt @@ -68,6 +68,12 @@ - `update`：已存在但需要根据本材料合并更新的页面，**只列 slug 字符串数组，最多 5 条** - 两个数组合计通常至少 1 条（材料完全无价值——如空白页、纯目录——才允许全空） +## 允许的页面类型（本知识库） + +为每个 create 项判断最贴切的类型;不确定时按默认处理。可在 create 项加 `page_type` 字段。 + +{allowed_page_types} + ## 关键纪律 - 输出体积应该是几百到几千字，**不要超过几 KB**。如果你发现自己在写正文，立刻停下 —— 那是下一阶段的工作。 diff --git a/mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderBasePathResolutionTest.java b/mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderBasePathResolutionTest.java new file mode 100644 index 00000000..5af64342 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderBasePathResolutionTest.java @@ -0,0 +1,122 @@ +package vip.mate.agent; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.DisabledOnOs; +import org.junit.jupiter.api.condition.EnabledOnOs; +import org.junit.jupiter.api.condition.OS; + +import java.nio.file.Paths; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; + +/** + * Verifies the agent-vs-workspace basePath precedence rules used by + * {@link AgentGraphBuilder#resolveAgentBasePath(String, String)}. + * + *

    The UI advertises agent-level paths as "relative to the workspace root", + * so a relative agent override must compose with the workspace basePath rather + * than fall through to the JVM working directory. + */ +class AgentGraphBuilderBasePathResolutionTest { + + @Test + @DisplayName("Both null/blank → null (no working directory configured)") + void noOverrideNoWorkspace_returnsNull() { + assertNull(AgentGraphBuilder.resolveAgentBasePath(null, null)); + assertNull(AgentGraphBuilder.resolveAgentBasePath("", "")); + assertNull(AgentGraphBuilder.resolveAgentBasePath(" ", null)); + } + + @Test + @DisplayName("No agent override → workspace basePath inherited verbatim") + void noOverride_inheritsWorkspace() { + assertEquals("/srv/ws-root", + AgentGraphBuilder.resolveAgentBasePath(null, "/srv/ws-root")); + assertEquals("/srv/ws-root", + AgentGraphBuilder.resolveAgentBasePath("", "/srv/ws-root")); + } + + @Test + @DisplayName("Agent override is absolute and inside workspace → used verbatim") + @DisabledOnOs(OS.WINDOWS) + void absoluteOverride_insideWs_usedAsIs_unix() { + assertEquals("/srv/ws-root/agents/code-review", + AgentGraphBuilder.resolveAgentBasePath("/srv/ws-root/agents/code-review", "/srv/ws-root")); + assertEquals("/opt/agents/code-review", + AgentGraphBuilder.resolveAgentBasePath("/opt/agents/code-review", null)); + } + + @Test + @DisplayName("Agent override is absolute (Windows) and inside workspace → used verbatim") + @EnabledOnOs(OS.WINDOWS) + void absoluteOverride_insideWs_usedAsIs_windows() { + assertEquals("C:\\ws-root\\agents\\code-review", + AgentGraphBuilder.resolveAgentBasePath("C:\\ws-root\\agents\\code-review", "C:\\ws-root")); + } + + @Test + @DisplayName("Relative agent override + workspace basePath → resolved under workspace") + void relativeOverride_resolvedUnderWorkspace() { + String expected = Paths.get("/srv/ws-root").resolve("projects/code-review").toString(); + assertEquals(expected, + AgentGraphBuilder.resolveAgentBasePath("projects/code-review", "/srv/ws-root")); + } + + @Test + @DisplayName("Relative agent override with no workspace → used verbatim (legacy fallback)") + void relativeOverride_noWorkspace_usedAsIs() { + assertEquals("projects/code-review", + AgentGraphBuilder.resolveAgentBasePath("projects/code-review", null)); + assertEquals("projects/code-review", + AgentGraphBuilder.resolveAgentBasePath("projects/code-review", "")); + } + + @Test + @DisplayName("Blank workspace basePath treated like null when override is relative") + void relativeOverride_blankWorkspace_usedAsIs() { + assertEquals("agent-dir", + AgentGraphBuilder.resolveAgentBasePath("agent-dir", " ")); + } + + // ==================== Absolute override scoped to workspace root ==================== + + @Test + @DisplayName("Absolute override inside workspace root → allowed verbatim") + @DisabledOnOs(OS.WINDOWS) + void absoluteOverride_insideWorkspace_allowed() { + // /srv/ws-root/agents/code-review starts with /srv/ws-root → fine. + assertEquals("/srv/ws-root/agents/code-review", + AgentGraphBuilder.resolveAgentBasePath("/srv/ws-root/agents/code-review", "/srv/ws-root")); + // Identical to workspace root → trivially allowed. + assertEquals("/srv/ws-root", + AgentGraphBuilder.resolveAgentBasePath("/srv/ws-root", "/srv/ws-root")); + } + + @Test + @DisplayName("Absolute override outside workspace root → rejected (workspace-scoping bypass)") + @DisabledOnOs(OS.WINDOWS) + void absoluteOverride_outsideWorkspace_rejected() { + // A less-trusted admin could set / or another repo and bypass scoping — + // reject it so the override stays inside the team workspace. + org.junit.jupiter.api.Assertions.assertThrows(IllegalArgumentException.class, () -> + AgentGraphBuilder.resolveAgentBasePath("/etc", "/srv/ws-root")); + org.junit.jupiter.api.Assertions.assertThrows(IllegalArgumentException.class, () -> + AgentGraphBuilder.resolveAgentBasePath("/", "/srv/ws-root")); + org.junit.jupiter.api.Assertions.assertThrows(IllegalArgumentException.class, () -> + AgentGraphBuilder.resolveAgentBasePath("/Users/admin/other-project", + "/srv/ws-root")); + } + + @Test + @DisplayName("Absolute override with no workspace basePath → used verbatim (legacy)") + @DisabledOnOs(OS.WINDOWS) + void absoluteOverride_noWorkspace_allowed() { + // No workspace boundary to enforce — fall back to legacy behavior. + assertEquals("/Users/admin/scratch", + AgentGraphBuilder.resolveAgentBasePath("/Users/admin/scratch", null)); + assertEquals("/Users/admin/scratch", + AgentGraphBuilder.resolveAgentBasePath("/Users/admin/scratch", "")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderIT.java b/mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderIT.java new file mode 100644 index 00000000..b8e00e73 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/agent/AgentGraphBuilderIT.java @@ -0,0 +1,80 @@ +package vip.mate.agent; + +import org.junit.jupiter.api.Test; +import vip.mate.agent.graph.executor.ToolExecutionExecutor; +import vip.mate.approval.grant.WorkspaceLookupCache; +import vip.mate.approval.grant.service.ApprovalGrantResolver; + +import java.lang.reflect.Constructor; +import java.lang.reflect.Field; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * Static-shape wiring check for the PR-1 integration points. + *

    + * Earlier drafts used {@code @SpringBootTest} here, but that boots the full + * application context (failing on the missing WebSocket {@code ServerContainer} + * in the test classpath) and runs Flyway against the local dev file H2 — a + * destructive side effect for a test whose only job is to verify that two fields + * exist and one constructor signature is present. + *

    + * Reflection covers exactly that: if anyone deletes a field on + * {@code AgentGraphBuilder}, changes its type, or removes the new 9-arg + * {@code ToolExecutionExecutor} constructor, this test fails immediately. No + * Spring, no database, no provider keys required. + *

    + * The "does Spring actually inject these beans at runtime" check moves to + * PR-2's integration test, which already brings up the full context for the + * conversation-lifecycle event listener. + */ +class AgentGraphBuilderIT { + + @Test + void agent_graph_builder_declares_auto_grant_fields() throws NoSuchFieldException { + Field resolverField = AgentGraphBuilder.class.getDeclaredField("approvalGrantResolver"); + Field cacheField = AgentGraphBuilder.class.getDeclaredField("workspaceLookupCache"); + + assertThat(resolverField.getType()).isEqualTo(ApprovalGrantResolver.class); + assertThat(cacheField.getType()).isEqualTo(WorkspaceLookupCache.class); + } + + @Test + void tool_execution_executor_has_constructor_that_accepts_auto_grant_deps() { + boolean found = false; + for (Constructor c : ToolExecutionExecutor.class.getConstructors()) { + Class[] types = c.getParameterTypes(); + if (types.length >= 2 + && types[types.length - 2] == WorkspaceLookupCache.class + && types[types.length - 1] == ApprovalGrantResolver.class) { + found = true; + break; + } + } + assertThat(found) + .as("ToolExecutionExecutor must expose a public constructor whose last two " + + "parameters are WorkspaceLookupCache + ApprovalGrantResolver; otherwise " + + "AgentGraphBuilder's `new ToolExecutionExecutor(...)` call sites won't compile.") + .isTrue(); + } + + @Test + void tool_execution_executor_keeps_legacy_constructors() { + // Five legacy public constructors stay so that legacy callers and tests + // that don't know about auto-grant continue to compile and run. + long legacyCount = 0; + for (Constructor c : ToolExecutionExecutor.class.getConstructors()) { + Class[] types = c.getParameterTypes(); + boolean isAutoGrantCtor = types.length >= 2 + && types[types.length - 2] == WorkspaceLookupCache.class + && types[types.length - 1] == ApprovalGrantResolver.class; + if (!isAutoGrantCtor) { + legacyCount++; + } + } + assertThat(legacyCount) + .as("Removing legacy ToolExecutionExecutor constructors would break " + + "existing call sites and tests; keep all 5 in place.") + .isGreaterThanOrEqualTo(5); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/agent/binding/AgentBindingServiceTest.java b/mateclaw-server/src/test/java/vip/mate/agent/binding/AgentBindingServiceTest.java index 73f1d5aa..0f3dc8ff 100644 --- a/mateclaw-server/src/test/java/vip/mate/agent/binding/AgentBindingServiceTest.java +++ b/mateclaw-server/src/test/java/vip/mate/agent/binding/AgentBindingServiceTest.java @@ -431,4 +431,276 @@ class AgentBindingServiceTest { assertNotNull(count); assertEquals(0, count, "unbind 应该物理删除，而不是软删（软删会留 deleted=1 行，占用唯一索引槽位导致 rebind 失败）"); } + + // ==================== V126 binding-mode flags (issue #184) ==================== + + /** + * Flip the {@code skills_disabled} column on the seeded agent row. + * Tests need a direct lever because {@link AgentBindingService} only + * exposes the auto-clear side; setting the flag is the controller's job. + */ + private void setSkillsDisabledFlag(boolean value) { + jdbcTemplate.update( + "UPDATE mate_agent SET skills_disabled = ? WHERE id = ?", + value, agentId); + } + + /** Mirror of {@link #setSkillsDisabledFlag} for the tools toggle. */ + private void setToolsDisabledFlag(boolean value) { + jdbcTemplate.update( + "UPDATE mate_agent SET tools_disabled = ? WHERE id = ?", + value, agentId); + } + + /** Boolean column readback so the auto-clear assertions don't lie. */ + private boolean readSkillsDisabledFlag() { + Boolean v = jdbcTemplate.queryForObject( + "SELECT skills_disabled FROM mate_agent WHERE id = ?", + Boolean.class, agentId); + return Boolean.TRUE.equals(v); + } + + private boolean readToolsDisabledFlag() { + Boolean v = jdbcTemplate.queryForObject( + "SELECT tools_disabled FROM mate_agent WHERE id = ?", + Boolean.class, agentId); + return Boolean.TRUE.equals(v); + } + + @Test + @DisplayName("issue #184: skills_disabled=true → getBoundSkillIds 返回 emptySet（不是 null）") + void getBoundSkillIdsReturnsEmptyWhenSkillsDisabled() { + // No binding rows at all + flag on. Pre-V126 contract returned null + // (= inherit global default); the new flag flips the read to an + // explicit "no skills" so SKILL.md catalog injection stays off. + setSkillsDisabledFlag(true); + + Set result = bindingService.getBoundSkillIds(agentId); + assertNotNull(result, "skills_disabled=true 时绝不能返回 null —— 否则下游会把它当作 'inherit global default'"); + assertTrue(result.isEmpty(), "应当是显式的空 set"); + } + + @Test + @DisplayName("issue #184: tools_disabled=true → getBoundToolNames 返回 emptySet（不是 null）") + void getBoundToolNamesReturnsEmptyWhenToolsDisabled() { + setToolsDisabledFlag(true); + + Set result = bindingService.getBoundToolNames(agentId); + assertNotNull(result, "tools_disabled=true 时绝不能返回 null"); + assertTrue(result.isEmpty(), "应当是显式的空 set"); + } + + @Test + @DisplayName("issue #184 matrix (T,F,*,0): skillsDisabled 但无 tool 绑定 → effective 返回 null（工具继承全局默认）") + void skillsDisabledNoToolBindingsStillInheritsDefaultTools() { + // This is the critical case the design review caught: silently + // returning {SYSTEM + MCP} here would strip every non-MCP global + // built-in tool just because the user said "no skills". The fix + // returns null so AgentToolSet.withAllowedToolsOnly(null) → no + // restriction → global default tools flow through. + setSkillsDisabledFlag(true); + + Set effective = bindingService.getEffectiveToolNames(agentId); + assertNull(effective, + "skillsDisabled=true 但用户没主动限制工具时，effective 必须返回 null —— " + + "否则非 MCP 的全局工具会被悄悄收窄掉"); + } + + @Test + @DisplayName("issue #184 matrix (T,F,*,>0): skillsDisabled + 显式 tool 绑定 → 仅这些 tool + SYSTEM + MCP-rule") + void skillsDisabledWithToolBindingsScopesToTools() { + seedBuiltinTool("scoped_tool_probe"); + setSkillsDisabledFlag(true); + bindingService.setToolBindings(agentId, List.of("scoped_tool_probe")); + + // Auto-clear is opt-in: we want to verify the matrix when both states + // coexist transiently (i.e. a client wrote tool bindings without + // touching the flag through the UI). bindSkill/setSkillBindings only + // clears its own flag; setToolBindings clears tools_disabled, not + // skills_disabled — so skills_disabled survives here. + Set effective = bindingService.getEffectiveToolNames(agentId); + assertNotNull(effective, "存在显式 tool 绑定时不能返回 null"); + assertTrue(effective.contains("scoped_tool_probe"), "用户勾选的工具必须在 allowlist"); + assertTrue(effective.contains("record_lesson"), "system-level 内核工具必须保留"); + assertFalse(effective.isEmpty()); + } + + @Test + @DisplayName("issue #184 matrix (F,T,0,*): toolsDisabled 无 skill 绑定 → 仅 system-level（不并入 MCP，不继承默认）") + void toolsDisabledReturnsSystemOnlyAndSkipsMcp() { + seedMcpServerWithOneTool(8_888_201L, "issue184-mcp", "leaked_probe"); + setToolsDisabledFlag(true); + + Set effective = bindingService.getEffectiveToolNames(agentId); + assertNotNull(effective, "toolsDisabled=true 时绝不能返回 null（那会让全局默认工具又流回来）"); + assertTrue(effective.contains("record_lesson"), "system-level memory 工具必须保留"); + boolean hasMcp = effective.stream().anyMatch(n -> n != null && n.startsWith("mcp_")); + assertFalse(hasMcp, + "toolsDisabled=true 时 enabled MCP 工具绝不能自动并入 —— 否则用户的 '禁用所有工具' 意图被违背。" + + "实际 allowlist: " + effective); + } + + @Test + @DisplayName("issue #184 matrix (F,T,>0,*): toolsDisabled + skill 绑定 → skill 扩展 + SYSTEM（不并入 MCP）") + void toolsDisabledKeepsSkillExpansionButSkipsMcp() { + long skillId = 7_777_801L; + seedSkill(skillId); + bindingService.bindSkill(agentId, skillId); + seedMcpServerWithOneTool(8_888_202L, "issue184-mcp-b", "mcp_should_be_hidden"); + setToolsDisabledFlag(true); + + Set effective = bindingService.getEffectiveToolNames(agentId); + assertNotNull(effective); + // Skill expansion is contingent on the resolved manifest declaring + // allowed_tools, which test fixtures don't seed; the contract we + // verify here is the MCP suppression + SYSTEM survival. (Skill + // expansion correctness is exercised in other tests / by the runtime.) + assertTrue(effective.contains("record_lesson"), "system-level 必须保留"); + boolean hasMcp = effective.stream().anyMatch(n -> n != null && n.startsWith("mcp_")); + assertFalse(hasMcp, "toolsDisabled=true 即使有 skill 绑定也不能自动并入 MCP"); + } + + @Test + @DisplayName("issue #184 matrix (T,T,*,*): 两 flag 都开 → 仅 system-level，无 MCP，无默认") + void bothDisabledReturnsSystemOnly() { + seedMcpServerWithOneTool(8_888_203L, "issue184-mcp-c", "should_be_hidden"); + setSkillsDisabledFlag(true); + setToolsDisabledFlag(true); + + Set effective = bindingService.getEffectiveToolNames(agentId); + assertNotNull(effective); + assertTrue(effective.contains("record_lesson"), "system-level 必须保留"); + boolean hasMcp = effective.stream().anyMatch(n -> n != null && n.startsWith("mcp_")); + assertFalse(hasMcp, "两 flag 全开时 MCP 必须完全隐藏"); + // Sanity: the set should be roughly the SYSTEM_LEVEL_TOOLS list — + // we don't enforce equality (the constant evolves) but it should be + // substantially smaller than the catalog of every enabled tool. + assertTrue(effective.size() < 100, + "两 flag 全开时返回的应该只是 system-level 内核工具，体积明显小于完整默认集。" + + "实际大小: " + effective.size()); + } + + @Test + @DisplayName("issue #184: setSkillBindings 非空保存自动清掉 skills_disabled（数据层不留矛盾态）") + void setSkillBindingsNonEmptyAutoClearsSkillsDisabledFlag() { + long skillId = 7_777_802L; + seedSkill(skillId); + setSkillsDisabledFlag(true); + assertTrue(readSkillsDisabledFlag(), "前置：flag 应为 true"); + + bindingService.setSkillBindings(agentId, List.of(skillId)); + + assertFalse(readSkillsDisabledFlag(), + "写入非空 skill 绑定应当自动清掉 skills_disabled —— " + + "否则 DB 会出现 'disabled=true + 有绑定行' 的矛盾态"); + } + + @Test + @DisplayName("issue #184: setSkillBindings 空保存不动 flag（toggle 自己拥有该位）") + void setSkillBindingsEmptySaveDoesNotTouchFlag() { + // Empty save is ambiguous: it might be "uncheck everything" from the + // UI that owns skills_disabled separately, or just "no rows". Letting + // the writer of the flag own it (agent PUT) keeps the toggle the + // single source of truth. + setSkillsDisabledFlag(true); + bindingService.setSkillBindings(agentId, List.of()); + + assertTrue(readSkillsDisabledFlag(), + "空保存不应清掉 flag —— 否则 UI 的'禁用所有技能' toggle 在用户'取消所有勾选'后会被悄悄翻掉"); + } + + @Test + @DisplayName("issue #184: bindSkill 单次绑定自动清掉 skills_disabled") + void bindSkillSingleAutoClearsSkillsDisabledFlag() { + long skillId = 7_777_803L; + seedSkill(skillId); + setSkillsDisabledFlag(true); + + bindingService.bindSkill(agentId, skillId); + + assertFalse(readSkillsDisabledFlag(), + "单条 bindSkill 也算明确的承诺，应当自动清掉 flag"); + } + + @Test + @DisplayName("issue #184: setToolBindings 非空保存自动清掉 tools_disabled") + void setToolBindingsNonEmptyAutoClearsToolsDisabledFlag() { + seedBuiltinTool("autoclear_probe"); + setToolsDisabledFlag(true); + assertTrue(readToolsDisabledFlag(), "前置：flag 应为 true"); + + bindingService.setToolBindings(agentId, List.of("autoclear_probe")); + + assertFalse(readToolsDisabledFlag(), + "写入非空 tool 绑定应当自动清掉 tools_disabled"); + } + + @Test + @DisplayName("issue #184: bindTool 单次绑定自动清掉 tools_disabled") + void bindToolSingleAutoClearsToolsDisabledFlag() { + setToolsDisabledFlag(true); + + bindingService.bindTool(agentId, "autoclear_single_probe"); + + assertFalse(readToolsDisabledFlag(), + "单条 bindTool 也算明确的承诺，应当自动清掉 flag"); + } + + // ==================== Issue #184 follow-up: skill-discovery deny ==================== + + @Test + @DisplayName("issue #184 follow-up: skills_disabled=true → 屏蔽 listAvailableSkills / load_skill / readSkillFile / runSkillScript / listSkillFiles") + void skillsDisabledDeniesAllSkillDiscoveryTools() { + // Verified during smoke test: even with skillsDisabled=true the LLM + // could call listAvailableSkills and discover the full catalog. The + // deny layer below subtracts the 5 skill-discovery tools so the opt-out + // is honored end-to-end, not just in the SKILL.md catalog injection. + setSkillsDisabledFlag(true); + + Set denied = bindingService.getSkillDiscoveryDeniedTools(agentId); + assertEquals(5, denied.size(), "应当返回 5 个 skill-discovery 工具名"); + assertTrue(denied.contains("listAvailableSkills")); + assertTrue(denied.contains("load_skill")); + assertTrue(denied.contains("readSkillFile")); + assertTrue(denied.contains("runSkillScript")); + assertTrue(denied.contains("listSkillFiles")); + } + + @Test + @DisplayName("issue #184 follow-up: skills_disabled=false → 不屏蔽任何工具（保留向后兼容）") + void skillsEnabledReturnsEmptyDenySet() { + // Default state — no flag, no rows. The deny layer must be a no-op + // so a legacy agent keeps every skill-discovery tool it had before. + Set denied = bindingService.getSkillDiscoveryDeniedTools(agentId); + assertNotNull(denied); + assertTrue(denied.isEmpty(), + "skillsDisabled=false 时 deny 集必须为空，否则会误伤未禁用技能的 agent"); + } + + @Test + @DisplayName("issue #184 follow-up: setSkillBindings 非空时 auto-clear flag → deny 也回到空集") + void skillDiscoveryDenyTracksAutoClearOfFlag() { + // Auto-clear contract from the main PR: writing a non-empty binding + // clears skills_disabled. The deny set must follow — it reads the + // same flag at call time, so after auto-clear it should be empty. + long skillId = 7_777_901L; + seedSkill(skillId); + setSkillsDisabledFlag(true); + assertEquals(5, bindingService.getSkillDiscoveryDeniedTools(agentId).size(), + "前置：flag 开启时 deny 应为 5 个"); + + bindingService.setSkillBindings(agentId, List.of(skillId)); + + assertTrue(bindingService.getSkillDiscoveryDeniedTools(agentId).isEmpty(), + "auto-clear 后 deny 必须回到空集，否则用户重新绑定技能后仍然看不到 listAvailableSkills"); + } + + @Test + @DisplayName("issue #184 follow-up: missing agent → deny 空集（防御性）") + void skillDiscoveryDenyHandlesMissingAgent() { + Set denied = bindingService.getSkillDiscoveryDeniedTools(999_999_999L); + assertNotNull(denied); + assertTrue(denied.isEmpty(), + "agent 不存在时 deny 集应为空 —— 严格但不抛错，与 isSkillsDisabled 的契约一致"); + } } diff --git a/mateclaw-server/src/test/java/vip/mate/agent/context/LoopMessageBudgeterTest.java b/mateclaw-server/src/test/java/vip/mate/agent/context/LoopMessageBudgeterTest.java new file mode 100644 index 00000000..116e8d8b --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/agent/context/LoopMessageBudgeterTest.java @@ -0,0 +1,468 @@ +package vip.mate.agent.context; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.ai.chat.messages.AssistantMessage; +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.chat.messages.SystemMessage; +import org.springframework.ai.chat.messages.ToolResponseMessage; +import org.springframework.ai.chat.messages.UserMessage; + +import java.util.ArrayList; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Behaviour of {@link LoopMessageBudgeter} — the per-ReAct-loop trim that + * replaces the previous fixed head-4 / tail-36 cut. + * + *

    The single load-bearing invariant is the anchor: the latest + * {@link UserMessage} must always survive into the LLM-bound list, even when + * the token-budgeted tail would have dropped it. Losing that message is what + * made the agent answer "I am an AI assistant" to a question about Qwen 3.7. + */ +class LoopMessageBudgeterTest { + + private final LoopMessageBudgeter budgeter = new LoopMessageBudgeter(); + + // ---- baselines --------------------------------------------------------- + + @Test + @DisplayName("empty list returns untouched") + void empty_noOp() { + LoopMessageBudgeter.Result r = budgeter.budget(List.of(), defaultCfg()); + assertEquals(0, r.messages().size()); + assertFalse(r.trace().modified()); + } + + @Test + @DisplayName("below trigger thresholds: list is forwarded unchanged") + void belowTrigger_passthrough() { + List input = new ArrayList<>(); + input.add(new SystemMessage("you are a tester")); + input.add(new UserMessage("hi")); + input.add(new AssistantMessage("hello")); + + LoopMessageBudgeter.Result r = budgeter.budget(input, defaultCfg()); + + assertSame(input, r.messages(), "untouched fast-path must return the same list reference"); + assertFalse(r.trace().modified()); + assertEquals(3, r.trace().finalCount()); + assertEquals(1, r.trace().headKept()); + } + + // ---- anchor enforcement (the regression we're fixing) ------------------ + + @Test + @DisplayName("anchor: latest UserMessage is never dropped, tail pulled back to keep it") + void anchor_preventsLatestUserMessageDrop() { + // Simulate the Qwen-3.7 failure shape: one system prompt, the user + // question at index 4, then a flood of tool spam that fills the + // entire token-budgeted tail. The latest UserMessage lives at the + // "middle" of the list and a naive token-budget tail cut drops it. + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("system")); // 0 + msgs.add(new UserMessage("old turn")); // 1 + msgs.add(new AssistantMessage("old reply")); // 2 + for (int i = 0; i < 10; i++) { + // 10 fat noise messages between old turn and the new user turn + msgs.add(new AssistantMessage(fat("noise-pre-" + i))); + } + msgs.add(new UserMessage("查下 qwen 3.7")); // anchor — must survive + for (int i = 0; i < 100; i++) { + // 100 fat tool observations after the new user message + msgs.add(new AssistantMessage(fat("tool-obs-" + i))); + } + int anchorIdx = 13; + assertTrue(msgs.get(anchorIdx) instanceof UserMessage + && ((UserMessage) msgs.get(anchorIdx)).getText().contains("qwen 3.7")); + + // Tail budget intentionally tight so the naive cut would drop the anchor. + LoopBudgetConfig cfg = new LoopBudgetConfig(50_000, 10_000, 4, 1.5, 0, 200); + + LoopMessageBudgeter.Result r = budgeter.budget(msgs, cfg); + + assertTrue(r.trace().modified(), "budget should have triggered"); + assertTrue(r.trace().anchorEnforced(), + "tail cut had to be pulled back to keep the anchor — that's the whole point"); + assertTrue(containsExact(r.messages(), "查下 qwen 3.7"), + "the user's question MUST remain in the LLM-bound message list"); + // Head must still carry the system prompt. + assertTrue(r.messages().get(0) instanceof SystemMessage); + } + + // ---- token-budget tail vs old fixed-count tail ------------------------- + + @Test + @DisplayName("tail is sized by token estimate, not message count") + void tail_sizedByTokens() { + // Tail of mostly tiny messages can grow to many entries; tail of a + // few huge messages stays small. The same config should produce + // tails of very different message counts. + LoopBudgetConfig cfg = new LoopBudgetConfig(50_000, 8_000, 4, 1.5, 0, 500); + + // Case A: 200 tiny assistant messages — many should survive in tail. + List tiny = new ArrayList<>(); + tiny.add(new SystemMessage("sys")); + tiny.add(new UserMessage("anchor")); + for (int i = 0; i < 200; i++) tiny.add(new AssistantMessage("x" + i)); + // Force trigger by adding bulk to original token total. + for (int i = 0; i < 60; i++) tiny.add(new AssistantMessage(fat("bulk" + i))); + int finalTiny = budgeter.budget(tiny, cfg).trace().finalCount(); + + // Case B: only fat messages. + List big = new ArrayList<>(); + big.add(new SystemMessage("sys")); + big.add(new UserMessage("anchor")); + for (int i = 0; i < 60; i++) big.add(new AssistantMessage(fat("big" + i))); + int finalBig = budgeter.budget(big, cfg).trace().finalCount(); + + assertTrue(finalTiny > finalBig, + "tail with tiny messages should keep more entries than tail with fat ones " + + "(tiny=" + finalTiny + ", big=" + finalBig + ")"); + } + + // ---- head detection ---------------------------------------------------- + + @Test + @DisplayName("head: every consecutive SystemMessage is preserved (not just first 4)") + void head_acceptsManySystemMessages() { + List msgs = new ArrayList<>(); + // 6 system messages: SOUL, AGENTS, runtime context, wiki, tool prompt, + // skill catalog — realistic for production agents. + for (int i = 0; i < 6; i++) msgs.add(new SystemMessage("system-" + i)); + msgs.add(new UserMessage("anchor")); + for (int i = 0; i < 80; i++) msgs.add(new AssistantMessage(fat("obs-" + i))); + + LoopBudgetConfig cfg = new LoopBudgetConfig(20_000, 5_000, 4, 1.5, 0, 200); + LoopMessageBudgeter.Result r = budgeter.budget(msgs, cfg); + + assertTrue(r.trace().triggered(), "token total exceeds trigger; main path must run"); + assertEquals(6, r.trace().headKept(), + "all six system messages must survive — not the legacy hard-coded 4"); + for (int i = 0; i < 6; i++) { + assertTrue(r.messages().get(i) instanceof SystemMessage, + "head slot " + i + " should be SystemMessage"); + } + } + + // ---- tool-pair integrity ---------------------------------------------- + + @Test + @DisplayName("tool-pair: Assistant(tool_calls) and ToolResponseMessage at boundary stay paired") + void toolPair_pulledBackTogether() { + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(new UserMessage("anchor")); + // A long head of fat messages that pushes the tail boundary. + for (int i = 0; i < 50; i++) msgs.add(new AssistantMessage(fat("head-" + i))); + // Tool-pair right at the would-be cut boundary. + msgs.add(asst("call-A")); + msgs.add(resp("call-A")); + // Tail of recent assistant chatter after the pair. + for (int i = 0; i < 5; i++) msgs.add(new AssistantMessage("tail-" + i)); + + LoopBudgetConfig cfg = new LoopBudgetConfig(10_000, 3_000, 4, 1.5, 0, 200); + LoopMessageBudgeter.Result r = budgeter.budget(msgs, cfg); + + // Both members of the pair survive together; never one without the other. + boolean hasCall = r.messages().stream().anyMatch(m -> m instanceof AssistantMessage am + && am.getToolCalls() != null && am.getToolCalls().stream().anyMatch(tc -> "call-A".equals(tc.id()))); + boolean hasResp = r.messages().stream().anyMatch(m -> m instanceof ToolResponseMessage trm + && trm.getResponses().stream().anyMatch(rr -> "call-A".equals(rr.id()))); + assertEquals(hasCall, hasResp, + "tool_call and its response must both survive or both be removed — never one without the other"); + assertEquals(0, r.trace().orphansRemoved(), + "pull-back at boundary should have prevented any orphan from being produced"); + } + + @Test + @DisplayName("integrity invariant: call-X and resp-X either both survive or both are removed") + void toolPair_integrityInvariant() { + // The pull-back at the boundary normally keeps pairs together, and + // the bidirectional orphan pass catches cross-boundary leftovers. + // The invariant we care about is the post-condition: the final list + // never contains a response without its matching call (or vice versa). + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(new UserMessage("anchor")); + for (int i = 0; i < 100; i++) msgs.add(new AssistantMessage(fat("mid-" + i))); + msgs.add(asst("call-X")); + msgs.add(new AssistantMessage(fat("tail-fill-1"))); + msgs.add(resp("call-X")); + msgs.add(new AssistantMessage("tail-fill-2")); + + LoopBudgetConfig cfg = new LoopBudgetConfig(10_000, 2_000, 4, 1.5, 0, 200); + LoopMessageBudgeter.Result r = budgeter.budget(msgs, cfg); + + boolean hasCall = r.messages().stream().anyMatch(m -> m instanceof AssistantMessage am + && am.getToolCalls() != null + && am.getToolCalls().stream().anyMatch(tc -> "call-X".equals(tc.id()))); + boolean hasResp = r.messages().stream().anyMatch(m -> m instanceof ToolResponseMessage trm + && trm.getResponses().stream().anyMatch(rr -> "call-X".equals(rr.id()))); + assertEquals(hasCall, hasResp, + "tool_call and matching response must both survive or both be dropped — " + + "orphan removal + pull-back guarantee this post-condition " + + "(hasCall=" + hasCall + ", hasResp=" + hasResp + ")"); + } + + // ---- absolute max safety net ------------------------------------------ + + @Test + @DisplayName("absoluteMax: pathological count is capped even when token budget allowed more") + void absoluteMax_caps() { + // 500 tiny messages — each ~5 chars; total tokens well under the + // budget so the token cut allows everything, but message count is + // pathological and must be capped. Anchor is at index 1 (right after + // the system header), so the cap would drop it without the stitch. + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(new UserMessage("ANCHOR")); + for (int i = 0; i < 500; i++) msgs.add(new AssistantMessage("x")); + + // Larger minTailMessages floor not relevant here — we want to verify + // the hard count cap, which dominates over the floor in this case. + LoopBudgetConfig cfg = new LoopBudgetConfig(50_000, 30_000, 4, 1.5, 0, 50); + + LoopMessageBudgeter.Result r = budgeter.budget(msgs, cfg); + + assertTrue(r.trace().modified()); + assertTrue(r.trace().finalCount() <= 50, + "target max should cap the count regardless of token budget (got " + + r.trace().finalCount() + ")"); + assertTrue(r.trace().targetMaxTripped(), "trace should record the trip"); + assertTrue(containsExact(r.messages(), "ANCHOR"), + "even when absoluteMax forces a hard drop, the latest UserMessage must " + + "remain — stitched in if necessary"); + } + + // ---- config validation -------------------------------------------------- + + @Test + @DisplayName("LoopBudgetConfig.forContext picks sensible ratios from a context window") + void forContext_ratios() { + LoopBudgetConfig c = LoopBudgetConfig.forContext(128_000); + assertEquals(64_000, c.triggerTokens()); + assertEquals(38_400, c.keepTailTokens()); + assertEquals(4, c.minTailMessages()); + assertEquals(1.5, c.tailSoftCeilingRatio(), 0.001); + assertEquals(0, c.reservedPrefixTokens()); + assertEquals(200, c.targetMaxMessages()); + } + + @Test + @DisplayName("LoopBudgetConfig rejects degenerate values") + void config_rejectsBadValues() { + assertThrows(IllegalArgumentException.class, + () -> new LoopBudgetConfig(5_000, 6_000, 4, 1.5, 0, 200), + "tail must be strictly less than trigger"); + assertThrows(IllegalArgumentException.class, + () -> new LoopBudgetConfig(100, 50, 4, 1.5, 0, 200), + "trigger below MIN_TRIGGER_TOKENS rejected"); + assertThrows(IllegalArgumentException.class, + () -> new LoopBudgetConfig(50_000, 10_000, 1, 1.5, 0, 200), + "minTailMessages below floor rejected"); + assertThrows(IllegalArgumentException.class, + () -> new LoopBudgetConfig(50_000, 10_000, 4, 0.5, 0, 200), + "tailSoftCeilingRatio below 1.0 rejected"); + assertThrows(IllegalArgumentException.class, + () -> new LoopBudgetConfig(50_000, 10_000, 4, 1.5, -1, 200), + "negative reservedPrefixTokens rejected"); + } + + // ---- prefix-token accounting ------------------------------------------- + + @Test + @DisplayName("reservedPrefixTokens: trigger fires earlier when prefix is heavy") + void reservedPrefix_triggersBudgetWithSmallerHistory() { + // Build a moderate history that would NOT trigger on its own (~6K + // tokens), but combined with a 60K prefix reservation pushes the + // total over the 50K trigger. + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(new UserMessage("anchor")); + for (int i = 0; i < 10; i++) msgs.add(new AssistantMessage(fat("obs-" + i))); + + // Without prefix accounting: well under 50K trigger. + LoopBudgetConfig noPrefix = new LoopBudgetConfig(50_000, 10_000, 4, 1.5, 0, 500); + assertFalse(budgeter.budget(msgs, noPrefix).trace().triggered(), + "without prefix reservation, this history must not trigger"); + + // With 60K prefix: should fire. + LoopBudgetConfig withPrefix = new LoopBudgetConfig(50_000, 10_000, 4, 1.5, 60_000, 500); + LoopMessageBudgeter.Result r = budgeter.budget(msgs, withPrefix); + assertTrue(r.trace().triggered(), + "with 60K reserved prefix, the same history must trip the trigger"); + assertEquals(60_000, r.trace().reservedPrefixTokens()); + } + + // ---- min-tail floor ---------------------------------------------------- + + @Test + @DisplayName("minTailMessages: a single huge tool output doesn't collapse the tail") + void minTail_floorPreservesRecentContext() { + // 50 fat history messages + an extremely fat last tool output that + // alone exceeds the hard tail budget. Without the floor, the + // backward walk in findTailCutByTokens would stop at just that one + // message, losing all recent reasoning. + // Anchor at the END so anchor enforcement doesn't paper over the + // floor — anchor-near-head would pull the cut back to include + // everything, masking the floor's structural effect. + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + for (int i = 0; i < 50; i++) msgs.add(new AssistantMessage(fat("head-fill-" + i))); + // The last assistant dwarfs the hard 5K tail budget. + msgs.add(new AssistantMessage(huge("monster-last"))); + msgs.add(new UserMessage("tail anchor")); + + LoopBudgetConfig cfg = new LoopBudgetConfig(30_000, 5_000, 4, 1.5, 0, 200); + + LoopMessageBudgeter.Result r = budgeter.budget(msgs, cfg); + + assertTrue(r.trace().triggered(), "token total exceeds trigger"); + assertTrue(r.trace().minTailFloorApplied(), + "the floor must have engaged — last message alone exceeds hard tail budget"); + assertTrue(r.trace().tailKept() >= 4, + "at least minTailMessages (4) entries should survive — got " + r.trace().tailKept()); + assertTrue(containsExact(r.messages(), "tail anchor"), + "anchor at the end must remain"); + } + + // ---- pair-integrity-vs-cap reporting ----------------------------------- + + @Test + @DisplayName("capExceededForPairIntegrity: cap is exceeded when pair pull-back wins") + void capExceeded_whenPairIntegrityForcesEarlierCut() { + // Setup: configure a targetMaxMessages cap such that the natural + // cap-driven cut lands inside a multi-response pair. Pair pull-back + // has to drag the boundary back across the entire pair → final + // count exceeds the cap, and the trace records the trade-off. + // Layout (idx): 0=sys, 1=anchor, 2-87=head fillers (86), + // 88=asst(c1..c5), 89-93=resp(c1..c5), 94-110=tail fillers (17). + // Total 111 messages. + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(new UserMessage("anchor")); + for (int i = 0; i < 86; i++) msgs.add(new AssistantMessage(fat("head-" + i))); + msgs.add(asstMulti("c1", "c2", "c3", "c4", "c5")); + for (int i = 1; i <= 5; i++) msgs.add(resp("c" + i)); + for (int i = 0; i < 17; i++) msgs.add(new AssistantMessage("tail-" + i)); + + // Cap of 20 → tail cap = 19. provisionalTailStart = 111-19 = 92 + // (lands inside the responses). Pair pull-back drags it to 88. + // Final tail = 111-88 = 23, +head 1 = 24 > 20 cap → integrity wins. + LoopBudgetConfig cfg = new LoopBudgetConfig(20_000, 5_000, 4, 1.5, 0, 20); + + LoopMessageBudgeter.Result r = budgeter.budget(msgs, cfg); + + assertTrue(r.trace().targetMaxTripped()); + assertTrue(r.trace().capExceededForPairIntegrity(), + "pair pull-back forced final count above targetMaxMessages — " + + "trace must surface this so observers can react"); + assertTrue(r.trace().finalCount() > cfg.targetMaxMessages(), + "final count must actually exceed the cap (got " + r.trace().finalCount() + + ", cap=" + cfg.targetMaxMessages() + ")"); + // Pair integrity still held: every response has its call. + assertTrue(ToolPairSanitizer.isPaired(r.messages()), + "tool-pair invariant must hold post-budget"); + } + + // ---- ToolPairSanitizer post-condition ---------------------------------- + + @Test + @DisplayName("ToolPairSanitizer.isPaired: post-condition holds across all trim paths") + void sanitizer_postConditionAlwaysHolds() { + // Run several scenarios and assert the sanitizer post-condition. + // Building a quick matrix is cheaper than convincing ourselves the + // budgeter never produces an orphan, ever. + List> scenarios = new ArrayList<>(); + + // (a) clean history, no trim needed + List a = new ArrayList<>(); + a.add(new SystemMessage("sys")); + a.add(new UserMessage("u")); + a.add(asst("c1")); + a.add(resp("c1")); + a.add(new AssistantMessage("done")); + scenarios.add(a); + + // (b) trim with pair at boundary + List b = new ArrayList<>(); + b.add(new SystemMessage("sys")); + b.add(new UserMessage("u")); + for (int i = 0; i < 60; i++) b.add(new AssistantMessage(fat("h" + i))); + b.add(asst("c1")); + b.add(resp("c1")); + b.add(new AssistantMessage("tail")); + scenarios.add(b); + + // (c) cap-driven cut deep inside pair territory + List c = new ArrayList<>(); + c.add(new SystemMessage("sys")); + c.add(new UserMessage("u")); + for (int i = 0; i < 100; i++) c.add(new AssistantMessage("tiny" + i)); + c.add(asst("cx")); + for (int i = 0; i < 100; i++) c.add(new AssistantMessage("tiny-mid" + i)); + c.add(resp("cx")); + scenarios.add(c); + + for (int idx = 0; idx < scenarios.size(); idx++) { + LoopBudgetConfig cfg = new LoopBudgetConfig(8_000, 2_500, 4, 1.5, 0, 30); + LoopMessageBudgeter.Result r = budgeter.budget(scenarios.get(idx), cfg); + assertTrue(ToolPairSanitizer.isPaired(r.messages()), + "scenario " + idx + " produced an unpaired list: " + r.trace()); + } + } + + // ---- helpers ----------------------------------------------------------- + + private static LoopBudgetConfig defaultCfg() { + return LoopBudgetConfig.forContext(128_000); + } + + /** Produce a ~2KB string so token-budget tests cross thresholds with few entries. */ + private static String fat(String tag) { + StringBuilder sb = new StringBuilder(2000); + sb.append(tag).append(": "); + while (sb.length() < 2000) sb.append("lorem ipsum dolor sit amet "); + return sb.toString(); + } + + /** Produce a ~30KB string — bigger than typical tail budgets so it forces the floor. */ + private static String huge(String tag) { + StringBuilder sb = new StringBuilder(30_000); + sb.append(tag).append(": "); + while (sb.length() < 30_000) sb.append("lorem ipsum dolor sit amet consectetur "); + return sb.toString(); + } + + private static AssistantMessage asst(String callId) { + return AssistantMessage.builder().content("") + .toolCalls(List.of( + new AssistantMessage.ToolCall(callId, "function", "tool_" + callId, "{}"))) + .build(); + } + + private static AssistantMessage asstMulti(String... callIds) { + List calls = new ArrayList<>(); + for (String id : callIds) { + calls.add(new AssistantMessage.ToolCall(id, "function", "tool_" + id, "{}")); + } + return AssistantMessage.builder().content("").toolCalls(calls).build(); + } + + private static ToolResponseMessage resp(String callId) { + return ToolResponseMessage.builder().responses(List.of( + new ToolResponseMessage.ToolResponse(callId, "tool_" + callId, "ok"))).build(); + } + + /** Returns true if any UserMessage in {@code list} has text containing the given substring. */ + private static boolean containsExact(List list, String substring) { + return list.stream().anyMatch(m -> m instanceof UserMessage u && u.getText().contains(substring)); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/agent/context/ToolPairSanitizerTest.java b/mateclaw-server/src/test/java/vip/mate/agent/context/ToolPairSanitizerTest.java new file mode 100644 index 00000000..99a46598 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/agent/context/ToolPairSanitizerTest.java @@ -0,0 +1,231 @@ +package vip.mate.agent.context; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.ai.chat.messages.AssistantMessage; +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.chat.messages.SystemMessage; +import org.springframework.ai.chat.messages.ToolResponseMessage; +import org.springframework.ai.chat.messages.UserMessage; + +import java.util.ArrayList; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * {@link ToolPairSanitizer} is the single source of truth for the + * tool_call ↔ tool_response pairing invariant. These tests exercise the + * three public methods directly against constructed message lists — the + * sanitizer is a pure-function utility, so there is no Spring context + * involved. + */ +class ToolPairSanitizerTest { + + // ---- isPaired() -------------------------------------------------------- + + @Test + @DisplayName("isPaired: empty list is trivially paired") + void isPaired_empty() { + assertTrue(ToolPairSanitizer.isPaired(List.of())); + assertTrue(ToolPairSanitizer.isPaired(null)); + } + + @Test + @DisplayName("isPaired: matched call and response are paired") + void isPaired_matched() { + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(new UserMessage("u")); + msgs.add(asst("c1")); + msgs.add(resp("c1")); + assertTrue(ToolPairSanitizer.isPaired(msgs)); + } + + @Test + @DisplayName("isPaired: orphan response detected") + void isPaired_orphanResponse() { + List msgs = new ArrayList<>(); + msgs.add(new UserMessage("u")); + msgs.add(resp("c1")); // no preceding call + assertFalse(ToolPairSanitizer.isPaired(msgs)); + } + + @Test + @DisplayName("isPaired: orphan call detected") + void isPaired_orphanCall() { + List msgs = new ArrayList<>(); + msgs.add(asst("c1")); // no following response + assertFalse(ToolPairSanitizer.isPaired(msgs)); + } + + @Test + @DisplayName("isPaired: null/empty id rejected as unpaired") + void isPaired_nullId() { + List msgs = new ArrayList<>(); + msgs.add(AssistantMessage.builder().content("") + .toolCalls(List.of(new AssistantMessage.ToolCall(null, "function", "t", "{}"))) + .build()); + assertFalse(ToolPairSanitizer.isPaired(msgs), + "an assistant tool_call with a null id can never be paired"); + + msgs.clear(); + msgs.add(ToolResponseMessage.builder().responses(List.of( + new ToolResponseMessage.ToolResponse("", "tool_x", "ok"))).build()); + assertFalse(ToolPairSanitizer.isPaired(msgs), + "a tool_response with an empty id can never be paired"); + } + + // ---- pullBackToToolPairBoundary() -------------------------------------- + + @Test + @DisplayName("pullBack: boundary inside a pair is moved before the assistant") + void pullBack_pairAtBoundary() { + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); // 0 + msgs.add(new AssistantMessage("pre")); // 1 + msgs.add(asst("c1")); // 2 — assistant tool_call + msgs.add(resp("c1")); // 3 — its response + msgs.add(new AssistantMessage("post")); // 4 + + // Proposed boundary at idx 3 would drop the assistant (idx 2) and + // keep the response (idx 3) → orphan. Pull-back should move the + // boundary back to idx 2 so the pair survives whole. + int adjusted = ToolPairSanitizer.pullBackToToolPairBoundary(msgs, 1, 3); + assertEquals(2, adjusted); + } + + @Test + @DisplayName("pullBack: boundary clear of any pair stays put") + void pullBack_noPairOverlap() { + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(new AssistantMessage("a")); + msgs.add(new AssistantMessage("b")); + msgs.add(new AssistantMessage("c")); + int adjusted = ToolPairSanitizer.pullBackToToolPairBoundary(msgs, 1, 2); + assertEquals(2, adjusted, "no tool pairs → boundary unchanged"); + } + + @Test + @DisplayName("pullBack: multi-call assistant with split responses pulls back across all of them") + void pullBack_multiCallAssistant() { + List msgs = new ArrayList<>(); + msgs.add(new SystemMessage("sys")); + msgs.add(asstMulti("c1", "c2", "c3")); // idx 1 — three calls + msgs.add(resp("c1")); // idx 2 + msgs.add(resp("c2")); // idx 3 + msgs.add(resp("c3")); // idx 4 + + // Boundary at idx 3 would keep c2 and c3 responses, orphaning them + // because their assistant (idx 1) would be dropped. + int adjusted = ToolPairSanitizer.pullBackToToolPairBoundary(msgs, 0, 3); + assertEquals(1, adjusted, + "boundary pulled to idx 1 so the multi-call assistant + all its responses survive"); + } + + // ---- removeOrphans() --------------------------------------------------- + + @Test + @DisplayName("removeOrphans: orphan response with no matching call is removed") + void removeOrphans_orphanResponse() { + List msgs = new ArrayList<>(); + msgs.add(new UserMessage("u")); + msgs.add(resp("c1")); // orphan — no preceding call + + int removed = ToolPairSanitizer.removeOrphans(msgs); + + assertEquals(1, removed); + assertEquals(1, msgs.size()); + assertTrue(ToolPairSanitizer.isPaired(msgs)); + } + + @Test + @DisplayName("removeOrphans: assistant with NO matching responses removed") + void removeOrphans_orphanAssistant() { + List msgs = new ArrayList<>(); + msgs.add(new UserMessage("u")); + msgs.add(asst("c1")); // orphan — no following response + + int removed = ToolPairSanitizer.removeOrphans(msgs); + + assertEquals(1, removed); + assertTrue(ToolPairSanitizer.isPaired(msgs)); + } + + @Test + @DisplayName("removeOrphans: assistant with PARTIAL matches is kept (lenient policy)") + void removeOrphans_partialMatchKept() { + // Lenient: assistant has c1 (matched) and c2 (orphan). Keep the + // whole assistant to preserve the matched pair; let strict provider + // dedup-handle the extra call rather than risking dropping useful + // history. + List msgs = new ArrayList<>(); + msgs.add(new UserMessage("u")); + msgs.add(asstMulti("c1", "c2")); + msgs.add(resp("c1")); + + int removed = ToolPairSanitizer.removeOrphans(msgs); + + assertEquals(0, removed, + "an assistant with at least one matched call survives — partial-match lenient policy"); + assertEquals(3, msgs.size()); + } + + @Test + @DisplayName("removeOrphans: iterative — removing P1 reveals P0, both cleared") + void removeOrphans_iterativeConvergence() { + // Build a list where removing an orphan assistant (P1) leaves a now- + // dangling response (P0) that the next pass must also remove. + List msgs = new ArrayList<>(); + msgs.add(new UserMessage("u")); + msgs.add(asst("c1")); // P1 — no response + msgs.add(resp("c2")); // P0 — no call (independent of c1) + + int removed = ToolPairSanitizer.removeOrphans(msgs); + + assertEquals(2, removed); + assertTrue(ToolPairSanitizer.isPaired(msgs)); + assertEquals(1, msgs.size()); + } + + @Test + @DisplayName("removeOrphans: matched pair untouched") + void removeOrphans_noOpOnCleanList() { + List msgs = new ArrayList<>(); + msgs.add(new UserMessage("u")); + msgs.add(asst("c1")); + msgs.add(resp("c1")); + msgs.add(new AssistantMessage("final")); + + int removed = ToolPairSanitizer.removeOrphans(msgs); + + assertEquals(0, removed); + assertEquals(4, msgs.size()); + assertTrue(ToolPairSanitizer.isPaired(msgs)); + } + + // ---- helpers ----------------------------------------------------------- + + private static AssistantMessage asst(String callId) { + return AssistantMessage.builder().content("") + .toolCalls(List.of( + new AssistantMessage.ToolCall(callId, "function", "tool_" + callId, "{}"))) + .build(); + } + + private static AssistantMessage asstMulti(String... callIds) { + List calls = new ArrayList<>(); + for (String id : callIds) { + calls.add(new AssistantMessage.ToolCall(id, "function", "tool_" + id, "{}")); + } + return AssistantMessage.builder().content("").toolCalls(calls).build(); + } + + private static ToolResponseMessage resp(String callId) { + return ToolResponseMessage.builder().responses(List.of( + new ToolResponseMessage.ToolResponse(callId, "tool_" + callId, "ok"))).build(); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/agent/graph/MessageNormalizerTest.java b/mateclaw-server/src/test/java/vip/mate/agent/graph/MessageNormalizerTest.java new file mode 100644 index 00000000..6af60b54 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/agent/graph/MessageNormalizerTest.java @@ -0,0 +1,267 @@ +package vip.mate.agent.graph; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.ai.chat.messages.AssistantMessage; +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.chat.messages.SystemMessage; +import org.springframework.ai.chat.messages.ToolResponseMessage; +import org.springframework.ai.chat.messages.UserMessage; +import org.springframework.ai.chat.prompt.Prompt; + +import java.util.ArrayList; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * Contract tests for {@link MessageNormalizer}. + * + *

    Pins the invariants that make the normalizer safe to apply unconditionally + * before every LLM call: + *

    + */ +class MessageNormalizerTest { + + @BeforeEach + void enableNormalizer() { + MessageNormalizer.setEnabledForTesting(true); + } + + @AfterEach + void resetNormalizer() { + MessageNormalizer.setEnabledForTesting(true); + } + + // ---------- Fast paths ---------- + + @Test + @DisplayName("null and empty inputs pass through unchanged") + void nullAndEmpty_passThrough() { + assertThat(MessageNormalizer.normalize((Prompt) null)).isNull(); + assertThat(MessageNormalizer.normalize((List) null)).isNull(); + List empty = List.of(); + assertThat(MessageNormalizer.normalize(empty)).isSameAs(empty); + } + + @Test + @DisplayName("no SystemMessage at all → input list returned by reference") + void noSystem_passThrough() { + List in = List.of( + new UserMessage("hello"), + AssistantMessage.builder().content("hi").build(), + new UserMessage("follow-up") + ); + assertThat(MessageNormalizer.normalize(in)).isSameAs(in); + } + + @Test + @DisplayName("single non-blank SystemMessage at index 0 → input returned by reference") + void canonicalShape_passThrough() { + List in = List.of( + new SystemMessage("you are a helpful assistant"), + new UserMessage("hi") + ); + assertThat(MessageNormalizer.normalize(in)).isSameAs(in); + } + + // ---------- The bug case: SystemMessage after UserMessage ---------- + + @Test + @DisplayName("SystemMessage at tail (ReasoningNode ledger-snapshot pattern) → merged to head") + void systemAtTail_movedToHead() { + // Mirrors the exact shape ReasoningNode produces today: + // [system(main), system(skillCatalog), user(runtime), user(wiki), + // system(ledger snapshot), system(stale reminder), + // ...history user/assistant messages...] + List in = new ArrayList<>(List.of( + new SystemMessage("MAIN_PROMPT"), + new SystemMessage("SKILL_CATALOG"), + new UserMessage("RUNTIME_CTX"), + new UserMessage("WIKI_SNIPPET"), + new SystemMessage("LEDGER_SNAPSHOT"), + new SystemMessage("STALE_REMINDER"), + new UserMessage("user question"), + AssistantMessage.builder().content("answer").build() + )); + + List out = MessageNormalizer.normalize(in); + + // Exactly one SystemMessage, at index 0, containing all four segments + // joined by the canonical separator and in original encounter order. + assertThat(out.stream().filter(m -> m instanceof SystemMessage)).hasSize(1); + assertThat(out.get(0)).isInstanceOf(SystemMessage.class); + assertThat(out.get(0).getText()).isEqualTo( + "MAIN_PROMPT" + MessageNormalizer.SEPARATOR + + "SKILL_CATALOG" + MessageNormalizer.SEPARATOR + + "LEDGER_SNAPSHOT" + MessageNormalizer.SEPARATOR + + "STALE_REMINDER"); + + // Non-system messages preserve their original relative order. + assertThat(out.subList(1, out.size())) + .extracting(Message::getText) + .containsExactly("RUNTIME_CTX", "WIKI_SNIPPET", "user question", "answer"); + } + + // ---------- Blanks ---------- + + @Test + @DisplayName("blank SystemMessages are skipped during merge") + void blankSystemsDropped() { + List in = List.of( + new SystemMessage("MAIN"), + new SystemMessage(" "), + new SystemMessage(""), + new UserMessage("hi"), + new SystemMessage("\n\t \n") + ); + List out = MessageNormalizer.normalize(in); + + assertThat(out).hasSize(2); + assertThat(out.get(0)).isInstanceOf(SystemMessage.class); + assertThat(out.get(0).getText()).isEqualTo("MAIN"); + assertThat(out.get(1)).isInstanceOf(UserMessage.class); + } + + @Test + @DisplayName("all SystemMessages blank → SystemMessage dropped entirely") + void allBlankSystems_allDropped() { + List in = List.of( + new SystemMessage(""), + new SystemMessage(" "), + new UserMessage("hi") + ); + List out = MessageNormalizer.normalize(in); + + assertThat(out).hasSize(1); + assertThat(out.get(0)).isInstanceOf(UserMessage.class); + } + + @Test + @DisplayName("single blank SystemMessage at index 0 → dropped (not preserved by fast path)") + void singleBlankAtHead_dropped() { + // Fast-path guard: a single SystemMessage at [0] is canonical only when + // it has text. A blank one at [0] should still be dropped so we don't + // send providers an empty system slot. + List in = List.of( + new SystemMessage(" "), + new UserMessage("hi") + ); + List out = MessageNormalizer.normalize(in); + + assertThat(out).hasSize(1); + assertThat(out.get(0)).isInstanceOf(UserMessage.class); + } + + // ---------- Tool-call pairing preservation ---------- + + @Test + @DisplayName("tool_call ↔ tool_response pairing survives normalization") + void toolCallPairingPreserved() { + // Build a realistic ReAct history fragment with a system mid-stream + // (the bug case) and a tool-call/tool-response pair that must stay + // adjacent and in-order. + AssistantMessage assistantWithToolCall = AssistantMessage.builder() + .content("") + .toolCalls(List.of(new AssistantMessage.ToolCall( + "call-abc", "function", "read_file", "{\"path\":\"x\"}"))) + .build(); + ToolResponseMessage toolResponse = ToolResponseMessage.builder() + .responses(List.of(new ToolResponseMessage.ToolResponse( + "call-abc", "read_file", "file body"))) + .build(); + + List in = List.of( + new SystemMessage("MAIN"), + new UserMessage("first turn"), + new SystemMessage("LATE_SYSTEM"), + assistantWithToolCall, + toolResponse, + new UserMessage("second turn") + ); + + List out = MessageNormalizer.normalize(in); + + // System at [0] only; everything else in original order. + assertThat(out.get(0)).isInstanceOf(SystemMessage.class); + assertThat(out.get(0).getText()).isEqualTo("MAIN" + MessageNormalizer.SEPARATOR + "LATE_SYSTEM"); + assertThat(out.get(1)).isInstanceOf(UserMessage.class); + assertThat(out.get(2)).isSameAs(assistantWithToolCall); + assertThat(out.get(3)).isSameAs(toolResponse); + assertThat(out.get(4)).isInstanceOf(UserMessage.class); + + // The AssistantMessage(tool_calls) → ToolResponseMessage adjacency is + // critical: providers that strictly validate pairing (kimi-code, some + // OpenAI-compat layers) reject a 400 if these are reordered or split + // by another message. + int assistantIdx = out.indexOf(assistantWithToolCall); + int responseIdx = out.indexOf(toolResponse); + assertThat(responseIdx).isEqualTo(assistantIdx + 1); + } + + // ---------- Prompt overload ---------- + + @Test + @DisplayName("Prompt overload preserves options by reference") + void promptOverloadPreservesOptions() { + Prompt in = new Prompt(List.of( + new SystemMessage("a"), + new UserMessage("u"), + new SystemMessage("b") + )); + Prompt out = MessageNormalizer.normalize(in); + + // Different Prompt instance (because messages changed)… + assertThat(out).isNotSameAs(in); + // …but the options reference is preserved verbatim, which matters + // because doStreamCall mutates options.user via AssistantThinkingRelay + // and we cannot break that chain. + assertThat(out.getOptions()).isSameAs(in.getOptions()); + + assertThat(out.getInstructions()).hasSize(2); + assertThat(out.getInstructions().get(0).getText()) + .isEqualTo("a" + MessageNormalizer.SEPARATOR + "b"); + } + + @Test + @DisplayName("Prompt overload returns same reference on canonical input") + void promptOverloadFastPath() { + Prompt in = new Prompt(List.of( + new SystemMessage("only one"), + new UserMessage("u") + )); + assertThat(MessageNormalizer.normalize(in)).isSameAs(in); + } + + // ---------- Kill switch ---------- + + @Test + @DisplayName("kill switch off → normalize is a no-op (input returned by reference)") + void killSwitchOff_isNoOp() { + MessageNormalizer.setEnabledForTesting(false); + try { + List in = List.of( + new SystemMessage("MAIN"), + new UserMessage("u"), + new SystemMessage("LATE_SYSTEM") // would normally be merged + ); + assertThat(MessageNormalizer.normalize(in)).isSameAs(in); + + Prompt p = new Prompt(in); + assertThat(MessageNormalizer.normalize(p)).isSameAs(p); + } finally { + MessageNormalizer.setEnabledForTesting(true); + } + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/agent/graph/NodeStreamingChatHelperNormalizerWiringTest.java b/mateclaw-server/src/test/java/vip/mate/agent/graph/NodeStreamingChatHelperNormalizerWiringTest.java new file mode 100644 index 00000000..4223fa86 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/agent/graph/NodeStreamingChatHelperNormalizerWiringTest.java @@ -0,0 +1,98 @@ +package vip.mate.agent.graph; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.mockito.ArgumentCaptor; +import org.springframework.ai.chat.messages.AssistantMessage; +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.chat.messages.SystemMessage; +import org.springframework.ai.chat.messages.UserMessage; +import org.springframework.ai.chat.metadata.ChatGenerationMetadata; +import org.springframework.ai.chat.model.ChatModel; +import org.springframework.ai.chat.model.ChatResponse; +import org.springframework.ai.chat.model.Generation; +import org.springframework.ai.chat.prompt.Prompt; +import reactor.core.publisher.Flux; +import vip.mate.channel.web.ChatStreamTracker; + +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Pins the wiring: {@link NodeStreamingChatHelper#streamCall} must apply + * {@link MessageNormalizer#normalize} before handing the prompt off to + * {@link ChatModel#stream}. + * + *

    The pure {@code MessageNormalizer} contract is covered by + * {@code MessageNormalizerTest}. This test guards against a refactor that + * accidentally drops the call site at the top of {@code doStreamCall} — + * which is the only thing standing between MateClaw and the LM Studio + * {@code 400 "System message must be at the beginning"} regression. + */ +class NodeStreamingChatHelperNormalizerWiringTest { + + private ChatStreamTracker streamTracker; + + @BeforeEach + void setUp() { + streamTracker = mock(ChatStreamTracker.class); + when(streamTracker.isStopRequested(any())).thenReturn(false); + } + + /** Mock that emits one successful chunk with the given text. */ + private static ChatModel successModel(String text) { + ChatModel m = mock(ChatModel.class); + Generation gen = new Generation(new AssistantMessage(text), ChatGenerationMetadata.NULL); + ChatResponse resp = mock(ChatResponse.class); + when(resp.getResults()).thenReturn(List.of(gen)); + when(resp.getResult()).thenReturn(gen); + when(resp.getMetadata()).thenReturn(null); + when(m.stream(any(Prompt.class))).thenReturn(Flux.just(resp)); + return m; + } + + @Test + @DisplayName("streamCall normalizes SystemMessages before invoking ChatModel.stream") + void streamCallNormalizes() { + ChatModel chatModel = successModel("hi"); + NodeStreamingChatHelper helper = new NodeStreamingChatHelper(streamTracker); + + // Build the exact problematic shape ReasoningNode produces today: + // SystemMessages sprinkled around UserMessages — would 400 on LM Studio. + Prompt prompt = new Prompt(List.of( + new SystemMessage("MAIN_PROMPT"), + new SystemMessage("SKILL_CATALOG"), + new UserMessage("RUNTIME_CTX"), + new SystemMessage("LEDGER_SNAPSHOT"), + new UserMessage("user question") + )); + + helper.streamCall(chatModel, prompt, "conv-1", "reasoning"); + + // Capture the Prompt that actually reached ChatModel.stream. + ArgumentCaptor captor = ArgumentCaptor.forClass(Prompt.class); + verify(chatModel).stream(captor.capture()); + Prompt outbound = captor.getValue(); + List sent = outbound.getInstructions(); + + // Exactly one SystemMessage, at index 0, containing all three system + // segments in encounter order. + assertThat(sent.stream().filter(m -> m instanceof SystemMessage)).hasSize(1); + assertThat(sent.get(0)).isInstanceOf(SystemMessage.class); + assertThat(sent.get(0).getText()).isEqualTo( + "MAIN_PROMPT" + MessageNormalizer.SEPARATOR + + "SKILL_CATALOG" + MessageNormalizer.SEPARATOR + + "LEDGER_SNAPSHOT"); + + // Non-system relative order preserved. + assertThat(sent.subList(1, sent.size())) + .extracting(Message::getText) + .containsExactly("RUNTIME_CTX", "user question"); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/agent/graph/executor/ToolExecutionExecutorNonInteractiveApprovalTest.java b/mateclaw-server/src/test/java/vip/mate/agent/graph/executor/ToolExecutionExecutorNonInteractiveApprovalTest.java new file mode 100644 index 00000000..976dbe5d --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/agent/graph/executor/ToolExecutionExecutorNonInteractiveApprovalTest.java @@ -0,0 +1,70 @@ +package vip.mate.agent.graph.executor; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.ai.chat.messages.AssistantMessage; +import org.springframework.ai.chat.messages.ToolResponseMessage; +import org.springframework.ai.chat.model.ToolContext; +import org.springframework.ai.tool.ToolCallback; +import org.springframework.ai.tool.definition.ToolDefinition; +import org.springframework.ai.tool.metadata.ToolMetadata; +import vip.mate.agent.AgentToolSet; +import vip.mate.agent.context.ChatOrigin; +import vip.mate.tool.guard.ToolGuard; +import vip.mate.tool.guard.ToolGuardResult; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * A tool that requires human approval cannot be resolved in a non-interactive + * (scheduled-job) run — a pending request would hang the turn until it times out + * with no answer. The executor must deny such a tool immediately for a cron-origin + * invocation while still gating it normally for an interactive (web) origin. + */ +class ToolExecutionExecutorNonInteractiveApprovalTest { + + private ToolExecutionExecutor executorRequiringApproval(ToolCallback cb) { + AgentToolSet toolSet = AgentToolSet.fromCallbacks(List.of(), List.of(cb)); + ToolGuard needsApproval = (name, args) -> + ToolGuardResult.needsApproval("shell command execution requires approval", "shell_tool_default"); + return new ToolExecutionExecutor(toolSet, needsApproval, null, null); + } + + @Test + @DisplayName("cron origin denies an approval-required tool instead of creating an unresolvable pending") + void cronOriginDeniesApprovalRequiredTool() { + ToolExecutionExecutor executor = executorRequiringApproval( + stub("execute_shell_command", args -> "ran")); + AssistantMessage.ToolCall call = new AssistantMessage.ToolCall( + "c1", "function", "execute_shell_command", "{\"command\":\"ls\"}"); + + ChatOrigin cron = ChatOrigin.cron("conv_cron", null, null, null, null); + ToolExecutionExecutor.ToolExecutionResult result = + executor.execute(List.of(call), "conv_cron", "agent_x", false, "system", null, cron); + + assertFalse(result.awaitingApproval(), + "non-interactive origin must not create a pending approval"); + ToolResponseMessage.ToolResponse resp = result.responses().get(0); + assertTrue(resp.responseData().contains("[审批不可用]"), + "cron-origin approval-required tool should be denied with guidance, got: " + resp.responseData()); + } + + private static ToolCallback stub(String name, java.util.function.Function handler) { + ToolDefinition def = ToolDefinition.builder() + .name(name) + .description("test tool " + name) + .inputSchema("{\"type\":\"object\",\"properties\":{}}") + .build(); + ToolMetadata md = ToolMetadata.builder().returnDirect(false).build(); + return new ToolCallback() { + @Override public ToolDefinition getToolDefinition() { return def; } + @Override public ToolMetadata getToolMetadata() { return md; } + @Override public String call(String arguments) { return handler.apply(arguments); } + @Override public String call(String arguments, ToolContext toolContext) { + return handler.apply(arguments); + } + }; + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantPr2IT.java b/mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantPr2IT.java new file mode 100644 index 00000000..84da957c --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantPr2IT.java @@ -0,0 +1,127 @@ +package vip.mate.approval.grant; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.context.ApplicationEventPublisher; +import org.springframework.context.annotation.Import; +import org.springframework.test.context.TestPropertySource; +import vip.mate.MateClawApplication; +import vip.mate.approval.event.ApprovalResolutionEvent; +import vip.mate.approval.grant.entity.ApprovalGrant; +import vip.mate.approval.grant.entity.ApprovalResolutionLog; +import vip.mate.approval.grant.repository.ApprovalGrantMapper; +import vip.mate.approval.grant.repository.ApprovalResolutionLogMapper; +import vip.mate.workflow.runtime.StubAgentInvokerConfig; +import vip.mate.workspace.conversation.event.ConversationDeletedEvent; + +import java.time.LocalDateTime; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; + +/** + * End-to-end wiring test for PR-2: publishing a generic approval resolution event + * lands one row in {@code mate_approval_resolution_log}, and publishing a + * {@code ConversationDeletedEvent} soft-revokes UNTIL_CONVERSATION_END grants + * (leaving other-scope grants alone). + *

    + * Reuses the same test profile shape as {@code AgentLifecycleTriggerTest}: + * isolated in-memory H2 per test (no dev DB file), {@code webEnvironment=NONE} + * (no WebSocket container), and the workflow stub configs so the workflow + * trigger bridge doesn't pull in real graph dependencies. + */ +@SpringBootTest( + classes = MateClawApplication.class, + webEnvironment = SpringBootTest.WebEnvironment.NONE +) +@TestPropertySource(properties = { + "spring.datasource.url=jdbc:h2:mem:approval_pr2_${random.uuid};MODE=MySQL;DATABASE_TO_LOWER=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE;DB_CLOSE_DELAY=-1", + "spring.ai.dashscope.api-key=test-key", + "spring.main.web-application-type=none", + "mateclaw.workflow.trigger.async-dispatch=false" +}) +@Import(StubAgentInvokerConfig.class) +class ApprovalGrantPr2IT { + + @Autowired private ApplicationEventPublisher publisher; + @Autowired private ApprovalResolutionLogMapper resolutionMapper; + @Autowired private ApprovalGrantMapper grantMapper; + + @Test + @DisplayName("USER_MANUAL ApprovalResolutionEvent → one resolution_log row written by the listener.") + void userManualEventLandsRow() { + long before = resolutionMapper.selectCount(null); + + publisher.publishEvent(new ApprovalResolutionEvent( + "pid-it-1", "conv-it-1", "agent-it-1", "user-it-1", + "read_file", "{\"path\":\"a.txt\"}", "LOW", + "[{\"ruleId\":\"shell.read\",\"severity\":\"LOW\"}]", + "USER_MANUAL", null)); + + List rows = resolutionMapper.selectList( + Wrappers.lambdaQuery() + .eq(ApprovalResolutionLog::getPendingId, "pid-it-1")); + assertThat(rows).hasSize(1); + assertThat(rows.get(0).getDecisionSource()).isEqualTo("USER_MANUAL"); + assertThat(rows.get(0).getRuleIds()).isEqualTo("shell.read"); + assertThat(resolutionMapper.selectCount(null)).isEqualTo(before + 1); + } + + @Test + @DisplayName("TIMEOUT ApprovalResolutionEvent → resolution_log row carries decision_source=TIMEOUT.") + void timeoutEventLandsRow() { + publisher.publishEvent(new ApprovalResolutionEvent( + "pid-it-timeout", "conv-it-timeout", "agent-it-timeout", null, + "execute_shell_command", "ls /tmp", "MEDIUM", null, + "TIMEOUT", null)); + + ApprovalResolutionLog row = resolutionMapper.selectOne( + Wrappers.lambdaQuery() + .eq(ApprovalResolutionLog::getPendingId, "pid-it-timeout")); + assertThat(row).isNotNull(); + assertThat(row.getDecisionSource()).isEqualTo("TIMEOUT"); + } + + @Test + @DisplayName("ConversationDeletedEvent → UNTIL_CONVERSATION_END grant revoked, ALWAYS grant untouched.") + void conversationDeleteRevokesScopedGrantOnly() { + String conversationId = "conv-it-delete"; + long workspaceId = 555L; + + ApprovalGrant conversationGrant = newGrant(workspaceId, "CONVERSATION", + conversationId, "read_file", "ALWAYS", "UNTIL_CONVERSATION_END"); + ApprovalGrant agentGrant = newGrant(workspaceId, "AGENT", + "agent-it-delete", "read_file", "ALWAYS", "ALWAYS"); + grantMapper.insert(conversationGrant); + grantMapper.insert(agentGrant); + + publisher.publishEvent(new ConversationDeletedEvent(conversationId)); + + ApprovalGrant convAfter = grantMapper.selectById(conversationGrant.getId()); + ApprovalGrant agentAfter = grantMapper.selectById(agentGrant.getId()); + assertThat(convAfter.getRevoked()).isEqualTo(1); + assertThat(agentAfter.getRevoked()).isEqualTo(0); + } + + /** Builds a minimal grant row; create/update timestamps default in the DB. */ + private ApprovalGrant newGrant(long workspaceId, String scopeType, String scopeId, + String toolName, String maxSeverity, String grantKind) { + ApprovalGrant g = new ApprovalGrant(); + g.setWorkspaceId(workspaceId); + g.setScopeType(scopeType); + g.setScopeId(scopeId); + g.setToolName(toolName); + g.setRuleId(null); + g.setMaxSeverity(maxSeverity); + g.setGrantKind(grantKind); + g.setGrantedBy(1L); + g.setGrantedAt(LocalDateTime.now()); + g.setRevoked(0); + g.setDeleted(0); + return g; + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantResolverTest.java b/mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantResolverTest.java new file mode 100644 index 00000000..a880e418 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/approval/grant/ApprovalGrantResolverTest.java @@ -0,0 +1,254 @@ +package vip.mate.approval.grant; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import vip.mate.approval.grant.AutoApproveAuditLogger; +import vip.mate.approval.grant.AutoApproveResult; +import vip.mate.approval.grant.AutoGrantSafetyFloor; +import vip.mate.approval.grant.entity.ApprovalGrant; +import vip.mate.approval.grant.entity.ApprovalResolutionLog; +import vip.mate.approval.grant.repository.ApprovalGrantMapper; +import vip.mate.approval.grant.repository.ApprovalResolutionLogMapper; +import vip.mate.approval.grant.service.ApprovalGrantResolver; +import vip.mate.tool.guard.model.GuardEvaluation; +import vip.mate.tool.guard.model.GuardFinding; +import vip.mate.tool.guard.model.GuardSeverity; +import vip.mate.tool.guard.model.ToolInvocationContext; + +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyList; +import static org.mockito.ArgumentMatchers.anyLong; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link ApprovalGrantResolver}. + *

    + * Coverage targets (≥ 16 cases) — see RFC 54 §8: + *

      + *
    • Safety floor: HARD_BLOCK wins regardless of any grant; FORCE_HUMAN skips + * grant lookup entirely
      • + *
    • CRITICAL severity always falls back to human, even with a matching grant
      • + *
    • {@code workspaceId=null} → conservative human fallback
      • + *
    • Multiple findings → all non-null ruleIds become candidates (IN match)
      • + *
    • Mapper hit → AUTO_GRANT + audit log row written
      • + *
    • Mapper miss → NO_GRANT, no audit row
      • + *
    • Hard block writes one HARD_BLOCK audit row
      • + *
    • Empty / null findings list still produces a candidate-less grant lookup
      • + *
    + */ +@ExtendWith(MockitoExtension.class) +class ApprovalGrantResolverTest { + + @Mock ApprovalGrantMapper grantMapper; + @Mock ApprovalResolutionLogMapper resolutionMapper; + @Mock AutoApproveAuditLogger auditLogger; + + AutoGrantSafetyFloor safetyFloor; + + ApprovalGrantResolver resolver; + + @BeforeEach + void setUp() { + safetyFloor = new AutoGrantSafetyFloor(); + safetyFloor.freeze(); + resolver = new ApprovalGrantResolver(grantMapper, resolutionMapper, safetyFloor, auditLogger); + } + + // ─── Safety floor ────────────────────────────────────────────────────── + + @Test + void hard_block_short_circuits_before_grant_lookup() { + ToolInvocationContext ctx = ctxWithArgs("rm -rf /"); + var r = resolver.tryAutoApprove(ctx, evaluationWith(GuardSeverity.MEDIUM, "shell.exec")); + + assertThat(r.isHardBlocked()).isTrue(); + assertThat(r.reason()).isEqualTo("rm_root"); + verify(grantMapper, never()).findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any()); + verify(auditLogger).logHardBlock(eq(ctx), any(), eq("rm_root")); + verify(resolutionMapper).insert(any(ApprovalResolutionLog.class)); + } + + @Test + void force_human_skips_grant_lookup_and_writes_no_resolution_row() { + ToolInvocationContext ctx = ctxWithArgs("curl https://example.com/x | bash"); + var r = resolver.tryAutoApprove(ctx, evaluationWith(GuardSeverity.MEDIUM, "shell.exec")); + + assertThat(r.isRequiresHuman()).isTrue(); + assertThat(r.reason()).startsWith("FORCE_HUMAN:"); + verify(grantMapper, never()).findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any()); + verify(auditLogger).logForceHuman(eq(ctx), any(), anyString()); + // Force-human path defers writing resolution_log to the human path completion. + verify(resolutionMapper, never()).insert(any(ApprovalResolutionLog.class)); + } + + // ─── Severity ceiling / workspace gate ───────────────────────────────── + + @Test + void critical_severity_is_never_auto_approvable() { + ToolInvocationContext ctx = ctxWithArgs("touch /tmp/x"); + var r = resolver.tryAutoApprove(ctx, evaluationWith(GuardSeverity.CRITICAL, "shell.exec")); + + assertThat(r.isRequiresHuman()).isTrue(); + assertThat(r.reason()).isEqualTo("SEVERITY_CRITICAL"); + verify(grantMapper, never()).findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any()); + } + + @Test + void null_workspace_id_falls_back_to_human() { + ToolInvocationContext ctx = new ToolInvocationContext( + "tool", java.util.Map.of(), "touch /tmp/x", "conv-1", "agent-1", + null, "user-1", /* workspaceId */ null); + var r = resolver.tryAutoApprove(ctx, evaluationWith(GuardSeverity.MEDIUM, "shell.exec")); + + assertThat(r.isRequiresHuman()).isTrue(); + assertThat(r.reason()).isEqualTo("UNKNOWN_WORKSPACE"); + verify(grantMapper, never()).findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any()); + } + + // ─── Candidate ruleId collection ─────────────────────────────────────── + + @Test + @SuppressWarnings("unchecked") + void all_distinct_non_null_rule_ids_become_candidates() { + ToolInvocationContext ctx = ctxWithArgs("touch /tmp/x"); + GuardEvaluation eval = new GuardEvaluation( + "execute_shell_command", + List.of( + finding("rule.a", GuardSeverity.LOW), + finding("rule.b", GuardSeverity.MEDIUM), + finding("rule.a", GuardSeverity.MEDIUM), + finding(null, GuardSeverity.LOW) + ), + GuardSeverity.MEDIUM, + vip.mate.tool.guard.model.GuardDecision.NEEDS_APPROVAL, null); + when(grantMapper.findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any())) + .thenReturn(null); + + resolver.tryAutoApprove(ctx, eval); + + ArgumentCaptor> captor = ArgumentCaptor.forClass(List.class); + verify(grantMapper).findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), captor.capture(), any()); + assertThat(captor.getValue()).containsExactlyInAnyOrder("rule.a", "rule.b"); + } + + @Test + @SuppressWarnings("unchecked") + void empty_findings_results_in_empty_candidate_list() { + ToolInvocationContext ctx = ctxWithArgs("touch /tmp/x"); + GuardEvaluation eval = new GuardEvaluation( + "execute_shell_command", List.of(), GuardSeverity.MEDIUM, + vip.mate.tool.guard.model.GuardDecision.NEEDS_APPROVAL, null); + when(grantMapper.findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any())) + .thenReturn(null); + + resolver.tryAutoApprove(ctx, eval); + + ArgumentCaptor> captor = ArgumentCaptor.forClass(List.class); + verify(grantMapper).findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), captor.capture(), any()); + assertThat(captor.getValue()).isEmpty(); + } + + // ─── Mapper hit / miss outcomes ──────────────────────────────────────── + + @Test + void mapper_hit_returns_approved_and_writes_resolution_row() { + ToolInvocationContext ctx = ctxWithArgs("touch /tmp/x"); + ApprovalGrant grant = new ApprovalGrant(); + grant.setId(9999L); + grant.setScopeType("AGENT"); + grant.setScopeId("agent-1"); + grant.setMaxSeverity("HIGH"); + grant.setNote("test"); + when(grantMapper.findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any())) + .thenReturn(grant); + + var r = resolver.tryAutoApprove(ctx, evaluationWith(GuardSeverity.MEDIUM, "shell.exec")); + + assertThat(r.isApproved()).isTrue(); + assertThat(r.grantId()).isEqualTo(9999L); + verify(auditLogger).logAutoGrant(eq(grant), eq(ctx), any()); + verify(resolutionMapper).insert(any(ApprovalResolutionLog.class)); + } + + @Test + void mapper_miss_returns_no_grant_without_audit_row() { + ToolInvocationContext ctx = ctxWithArgs("touch /tmp/x"); + when(grantMapper.findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any())) + .thenReturn(null); + + var r = resolver.tryAutoApprove(ctx, evaluationWith(GuardSeverity.MEDIUM, "shell.exec")); + + assertThat(r.isRequiresHuman()).isTrue(); + assertThat(r.reason()).isEqualTo("NO_GRANT"); + verify(resolutionMapper, never()).insert(any(ApprovalResolutionLog.class)); + } + + @Test + void approved_path_emits_correct_audit_log_decision_source() { + ToolInvocationContext ctx = ctxWithArgs("touch /tmp/x"); + ApprovalGrant grant = new ApprovalGrant(); + grant.setId(1L); + grant.setMaxSeverity("HIGH"); + grant.setNote("ok"); + when(grantMapper.findFirstMatching( + anyLong(), any(), any(), any(), any(), any(), anyList(), any())) + .thenReturn(grant); + + resolver.tryAutoApprove(ctx, evaluationWith(GuardSeverity.MEDIUM, "shell.exec")); + + ArgumentCaptor cap = ArgumentCaptor.forClass(ApprovalResolutionLog.class); + verify(resolutionMapper).insert(cap.capture()); + assertThat(cap.getValue().getDecisionSource()).isEqualTo("AUTO_GRANT"); + assertThat(cap.getValue().getGrantId()).isEqualTo(1L); + } + + // ─── Helpers ─────────────────────────────────────────────────────────── + + private static ToolInvocationContext ctxWithArgs(String args) { + return new ToolInvocationContext( + "execute_shell_command", java.util.Map.of(), args, + "conv-1", "agent-1", null, "user-1", /* workspaceId */ 100L); + } + + /** Builds a minimal GuardFinding using the 10-arg constructor (no decision / metadata). */ + private static GuardFinding finding(String ruleId, GuardSeverity sev) { + return new GuardFinding( + ruleId, sev, null, + /*title*/ ruleId == null ? "anon" : ruleId, + /*description*/ "", /*remediation*/ "", + /*toolName*/ "execute_shell_command", + /*paramName*/ null, /*matchedPattern*/ null, /*snippet*/ null); + } + + private static GuardEvaluation evaluationWith(GuardSeverity sev, String ruleId) { + GuardFinding f = new GuardFinding( + ruleId, sev, null, ruleId, "", "", + /*toolName*/ "execute_shell_command", /*paramName*/ null, + /*matchedPattern*/ null, /*snippet*/ null); + return new GuardEvaluation( + "execute_shell_command", List.of(f), sev, + vip.mate.tool.guard.model.GuardDecision.NEEDS_APPROVAL, null); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/approval/grant/AutoGrantSafetyFloorTest.java b/mateclaw-server/src/test/java/vip/mate/approval/grant/AutoGrantSafetyFloorTest.java new file mode 100644 index 0000000000000000000000000000000000000000..648a24244b923e063f4b7ddec8926f8bf9a1a34d GIT binary patch literal 8034 zcmd5>&2AgX5zbk!u$PK}Sfnit?OiVr&_6LPQ)^>o+0hRIWDkSZOq0{r%=DzYN0jUp zkkbNt$YqgN2=Wwr$)orM_7(C~4@VqQByH|0V0hrqu)DhcyXvb#L}y|s>0A{-CY%gJ zQ5bzL(qL#r?jCJysI1V&kv7BNU70I~_d+>ouu=uj%Kn>);tR;v~AD*QuKcimh^f#=uBQcQf zaxc}|Tm`)Taq*NtcJ;Y5tZXODP-1iIfVbTQQVxC6?3R&~anHj&&(%1q>4DpVnNoZhjCOw$H^TgIAp zj~6x=X!- zqgRmO;A9`~P;;bXNe6r1?#}G)XN9}OlDq^*DlbZC^WzUc(c9k95w&tn1Cd%ug|>>h zYR_!ntsN@5>=IT-Mq9h%5+g-S@HQthl~W`a=6%P0$G(n4 zIyvHTr!rS(BT6CET)$vXrw2a5j>9B zyo6tV3q7G+j^@&AwI5Bd4F*Qa_p*L|H9oBhS--RrgdOj>_q#FYeA+V><(i&n$z)+H zY!aG5XrX~5R5nboH}pQ!;%5Np6@^+_mogaYqR#~%?7``eiD%_Bq4a6&Rgwv zplttdrAUu;YhEA*J-;w`**km@KHq<{`|UESg>Z$UVfVrq&zeOdV6v_I*Q3C{6VT!mGVUquAo9KbstQU{wm zHWm-oC`ufMPKUUzeuX4)Olt7NOYvSBO?vzTBCSy(zHURlZdWl%x7GeY-S4}1=;~2- zjm+1TK`0ytIx2xUtnO3Jw~hOT)6J4luj$ZEf-7^hMu~<-7Gcd!n3dLrxpoU~rA`O8 zJ68}RX+k|1kjSG1#U5`%J@5_*12?xukhjOp+T6DAd^)(~Z!Lm-Ohn-AX zreT|x%ZzeYzwo#sYFu?!p23Azys!ISa@ki`C(OW{YmI9{4p(0jhNr@+=!R1)5+AjE zN{MrY?RGlyLS#iMQF~_{m7^$6)4(S5J=x?|^|1HmaJL`6JbB$am{P~J!IlU)K$RJy zCP-M&%SdqHyRRyxXBW((4o?Ho6F%I89M=etvp=arovf9rvE^_mP3n39eHDG=X`9 z+I@8?jt@@`c6(?U|4$@|Whx=ZxPe9OE{)_i1~)qDci$JUWTdJe-aCBrdi_>v$Tk*? zdvCc?{XTB+CjwPHKB@T0t(B0g-CWan!tw@{^Z7`{$mg&!!zUr&m@prlMJNa=SVG1( z?2C%veu2m=58e&#_#BN?>S+ z__>}`Z-g$t;3I1A<%{p`XP@m%V{1l8iTU+;xtaQ;tdoJrN{8JAVb&o3~XNtiFX;2~3H7?nvVJR5qm+&%|sQH=MbLtb*7?!_thpw9ebOE26pP5cOxJ5j2 zGD`_-kwPO~X>tqKie(}3mODIS$eY6gu(%#s;sJ^=Wq~nH|00rw$L%MmGlwO#3S@nt zOlD`$arDt?idhbzex7nj*#43UGv3Z`7Am)dImEU9kLfjLDX)3rgVoF{K;yKOe!x)g zq=u5FjjeJ(_x>zDJ;HtQ;Qsw-15A&V2>k#?UKNBs{a5QjqkCi?r~jr{=W_nW1_v`F zrUq1$DT_f|l)$^j7=Ckp#UTBZjt~pfVhI(N-+zRU$4z1J;NHF2c7pjHV8D?gpmZwH z?AL=N&}b?81EIzNwHZEn+c+Y962ju^eShLRczgv@mo^vsdV`9*C;+3pt-$sh)GDBz ziFvTWBMmcg!?bwJaqO+zg0t>CMds(nvo8mSoBt25^ac;aNGMm2L1qc??*)j4*Tx)W z)g;t_TECwXHjq54uoz%8ycVN|d6ufF@aM!i0+mNbW(d_@9)Ba3vR#2bO*;Jj3Ufz} zsMg%bmdjYF^c}#+Jd_=4A9IpAMJ&?cRpoZ+GE;B_0Sy|Dc^6W;VdSfJ;H@~jV_Nvi g&)F@c;k- literal 0 HcmV?d00001 diff --git a/mateclaw-server/src/test/java/vip/mate/approval/grant/WorkspaceLookupCacheTest.java b/mateclaw-server/src/test/java/vip/mate/approval/grant/WorkspaceLookupCacheTest.java new file mode 100644 index 00000000..b5566515 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/approval/grant/WorkspaceLookupCacheTest.java @@ -0,0 +1,111 @@ +package vip.mate.approval.grant; + +import com.baomidou.mybatisplus.core.conditions.Wrapper; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import vip.mate.workspace.conversation.model.ConversationEntity; +import vip.mate.workspace.conversation.repository.ConversationMapper; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.times; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link WorkspaceLookupCache}. + *

    + * Verifies that: + *

      + *
    • The lookup uses {@code LambdaQueryWrapper} on the {@code conversation_id} + * business column — not {@code selectById}, which would silently miss every + * row and disable auto-grant entirely.
      • + *
    • The Caffeine LRU caches positive lookups (a second call doesn't hit the mapper).
      • + *
    • {@code invalidate(conversationId)} drops the cached entry so a re-lookup + * goes back to the mapper (used by the lifecycle listener in PR-2).
      • + *
    • Missing conversation / deleted conversation / blank input all return {@code null} + * without throwing.
      • + *
    + */ +@ExtendWith(MockitoExtension.class) +class WorkspaceLookupCacheTest { + + @Mock + ConversationMapper conversationMapper; + + @InjectMocks + WorkspaceLookupCache cache; + + @BeforeEach + void setUp() { + // InjectMocks builds the instance via constructor; ensure cache state is clean. + // (Caffeine cache is instance-scoped, so a fresh cache instance per test is enough.) + } + + @Test + void uses_lambda_query_not_select_by_id() { + ConversationEntity conv = new ConversationEntity(); + conv.setConversationId("conv-abc"); + conv.setWorkspaceId(42L); + when(conversationMapper.selectOne(any(Wrapper.class))).thenReturn(conv); + + Long ws = cache.resolveByConversation("conv-abc"); + + assertThat(ws).isEqualTo(42L); + // The critical assertion: selectOne(LambdaQueryWrapper) was used, not selectById(...). + verify(conversationMapper, never()).selectById(any()); + verify(conversationMapper, times(1)).selectOne(any(Wrapper.class)); + } + + @Test + void second_call_hits_cache_not_mapper() { + ConversationEntity conv = new ConversationEntity(); + conv.setConversationId("conv-xyz"); + conv.setWorkspaceId(7L); + when(conversationMapper.selectOne(any(Wrapper.class))).thenReturn(conv); + + cache.resolveByConversation("conv-xyz"); + cache.resolveByConversation("conv-xyz"); + cache.resolveByConversation("conv-xyz"); + + verify(conversationMapper, times(1)).selectOne(any(Wrapper.class)); + } + + @Test + void invalidate_forces_remap() { + ConversationEntity conv = new ConversationEntity(); + conv.setConversationId("conv-1"); + conv.setWorkspaceId(1L); + when(conversationMapper.selectOne(any(Wrapper.class))).thenReturn(conv); + + cache.resolveByConversation("conv-1"); + cache.invalidate("conv-1"); + cache.resolveByConversation("conv-1"); + + verify(conversationMapper, times(2)).selectOne(any(Wrapper.class)); + } + + @Test + void missing_conversation_returns_null() { + when(conversationMapper.selectOne(any(Wrapper.class))).thenReturn(null); + assertThat(cache.resolveByConversation("does-not-exist")).isNull(); + } + + @Test + void null_or_blank_id_returns_null_without_query() { + assertThat(cache.resolveByConversation(null)).isNull(); + assertThat(cache.resolveByConversation("")).isNull(); + verify(conversationMapper, never()).selectOne(any(Wrapper.class)); + } + + @Test + void invalidate_on_null_id_is_noop() { + cache.invalidate(null); // must not throw + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/approval/grant/controller/ApprovalGrantControllerTest.java b/mateclaw-server/src/test/java/vip/mate/approval/grant/controller/ApprovalGrantControllerTest.java new file mode 100644 index 00000000..1085efab --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/approval/grant/controller/ApprovalGrantControllerTest.java @@ -0,0 +1,325 @@ +package vip.mate.approval.grant.controller; + +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import org.springframework.security.authentication.UsernamePasswordAuthenticationToken; +import org.springframework.security.core.Authentication; +import vip.mate.approval.grant.entity.ApprovalGrant; +import vip.mate.approval.grant.repository.ApprovalGrantMapper; +import vip.mate.approval.grant.repository.ApprovalResolutionLogMapper; +import vip.mate.approval.grant.service.ApprovalGrantService; +import vip.mate.auth.model.UserEntity; +import vip.mate.auth.service.AuthService; +import vip.mate.exception.MateClawException; +import vip.mate.workspace.core.service.WorkspaceService; + +import java.time.LocalDateTime; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyLong; +import static org.mockito.ArgumentMatchers.anyString; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.doThrow; +import static org.mockito.Mockito.lenient; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Plain controller tests for {@link ApprovalGrantController} — matches the + * mateclaw house style (see {@code WikiHotCacheControllerTest}, + * {@code WorkflowControllerTest}): no MockMvc, no Spring boot context, just + * direct method calls with mocked dependencies. + *

    + * The {@code @RequireWorkspaceRole("member")} HTTP gate is enforced by the + * shared {@code WorkspaceAccessInterceptor} and is exercised by its own tests; + * here we cover the in-method §2.4.5 6-cell matrix and the password second + * factor. + */ +@ExtendWith(MockitoExtension.class) +class ApprovalGrantControllerTest { + + private static final long WORKSPACE_ID = 100L; + private static final long MEMBER_ID = 1001L; + private static final long ADMIN_ID = 2002L; + + @Mock ApprovalGrantService grantService; + @Mock ApprovalGrantMapper grantMapper; + @Mock ApprovalResolutionLogMapper resolutionMapper; + @Mock AuthService authService; + @Mock WorkspaceService workspaceService; + + @InjectMocks + ApprovalGrantController controller; + + private Authentication memberAuth; + private Authentication adminAuth; + + @BeforeEach + void setUp() { + memberAuth = new UsernamePasswordAuthenticationToken("member-user", null); + adminAuth = new UsernamePasswordAuthenticationToken("admin-user", null); + + UserEntity member = new UserEntity(); + member.setId(MEMBER_ID); + member.setUsername("member-user"); + UserEntity admin = new UserEntity(); + admin.setId(ADMIN_ID); + admin.setUsername("admin-user"); + // Lenient: each test only uses one of the two users; strict mode would + // flag the unused one. Using lenient here keeps setUp shared. + lenient().when(authService.findByUsername("member-user")).thenReturn(member); + lenient().when(authService.findByUsername("admin-user")).thenReturn(admin); + } + + @Nested + class CreateAuthorizationMatrix { + + @Test + void conversation_scope_any_member_can_create() { + ApprovalGrantController.CreateGrantRequest body = baseBody("CONVERSATION", "conv-1", "read_file"); + + controller.create(body, WORKSPACE_ID, memberAuth); + + // No admin check, no password check; grant inserted. + verify(workspaceService, never()).requirePermission(anyLong(), anyLong(), anyString()); + verify(authService, never()).verifyCurrentUserPassword(anyLong(), anyString()); + verify(grantMapper).insert(any(ApprovalGrant.class)); + } + + @Test + void user_scope_only_targets_self() { + ApprovalGrantController.CreateGrantRequest body = baseBody("USER", "9999", "read_file"); + + assertThatThrownBy(() -> controller.create(body, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class) + .hasMessageContaining("USER-scope"); + verify(grantMapper, never()).insert(any(ApprovalGrant.class)); + } + + @Test + void user_scope_self_succeeds() { + ApprovalGrantController.CreateGrantRequest body = baseBody("USER", + String.valueOf(MEMBER_ID), "read_file"); + + controller.create(body, WORKSPACE_ID, memberAuth); + + verify(grantMapper).insert(any(ApprovalGrant.class)); + } + + @Test + void agent_scope_explicit_tool_requires_admin() { + ApprovalGrantController.CreateGrantRequest body = baseBody("AGENT", "agent-1", "read_file"); + doThrow(new MateClawException("err.workspace.insufficient_permission", 403, "admin required")) + .when(workspaceService).requirePermission(WORKSPACE_ID, MEMBER_ID, "admin"); + + assertThatThrownBy(() -> controller.create(body, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class); + } + + @Test + void agent_scope_null_tool_requires_admin_plus_password() { + ApprovalGrantController.CreateGrantRequest body = baseBody("AGENT", "agent-1", null); + // admin true; missing password → 403 + when(workspaceService.hasPermission(WORKSPACE_ID, ADMIN_ID, "admin")).thenReturn(true); + body.password = null; + + assertThatThrownBy(() -> controller.create(body, WORKSPACE_ID, adminAuth)) + .isInstanceOf(MateClawException.class) + .hasMessageContaining("password"); + } + + @Test + void agent_scope_null_tool_admin_with_password_passes() { + ApprovalGrantController.CreateGrantRequest body = baseBody("AGENT", "agent-1", null); + body.password = "correct-password"; + when(workspaceService.hasPermission(WORKSPACE_ID, ADMIN_ID, "admin")).thenReturn(true); + // verifyCurrentUserPassword passes silently when correct. + + controller.create(body, WORKSPACE_ID, adminAuth); + + verify(authService).verifyCurrentUserPassword(ADMIN_ID, "correct-password"); + verify(grantMapper).insert(any(ApprovalGrant.class)); + } + + @Test + void workspace_scope_explicit_tool_requires_admin_only() { + ApprovalGrantController.CreateGrantRequest body = baseBody("WORKSPACE", + String.valueOf(WORKSPACE_ID), "read_file"); + doThrow(new MateClawException("err.workspace.insufficient_permission", 403, "admin required")) + .when(workspaceService).requirePermission(WORKSPACE_ID, MEMBER_ID, "admin"); + + assertThatThrownBy(() -> controller.create(body, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class); + } + + @Test + void workspace_scope_null_tool_requires_admin_plus_password_red_button() { + ApprovalGrantController.CreateGrantRequest body = baseBody("WORKSPACE", + String.valueOf(WORKSPACE_ID), null); + body.password = "correct-password"; + when(workspaceService.hasPermission(WORKSPACE_ID, ADMIN_ID, "admin")).thenReturn(true); + + controller.create(body, WORKSPACE_ID, adminAuth); + + verify(workspaceService).requirePermission(WORKSPACE_ID, ADMIN_ID, "admin"); + verify(authService).verifyCurrentUserPassword(ADMIN_ID, "correct-password"); + verify(grantMapper).insert(any(ApprovalGrant.class)); + } + + @Test + void critical_severity_is_rejected() { + ApprovalGrantController.CreateGrantRequest body = baseBody("CONVERSATION", "conv-1", "read_file"); + body.maxSeverity = "CRITICAL"; + + assertThatThrownBy(() -> controller.create(body, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class) + .hasMessageContaining("CRITICAL is not auto-approvable"); + } + + @Test + void until_conversation_end_requires_conversation_scope() { + ApprovalGrantController.CreateGrantRequest body = baseBody("AGENT", "agent-1", "read_file"); + body.grantKind = "UNTIL_CONVERSATION_END"; + + assertThatThrownBy(() -> controller.create(body, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class) + .hasMessageContaining("UNTIL_CONVERSATION_END"); + } + } + + @Nested + class ListRevoke { + + @Test + void list_mine_does_not_require_admin() { + // selectPage returns a Page object; the test only cares about the auth + // path, so the mapper stub just needs to not NPE. + when(grantMapper.selectPage(any(), any())).thenReturn(new com.baomidou.mybatisplus.extension.plugins.pagination.Page<>()); + + controller.list(null, null, null, /*mine*/ true, 1L, 20L, WORKSPACE_ID, memberAuth); + + verify(workspaceService, never()).requirePermission(anyLong(), anyLong(), anyString()); + } + + @Test + void list_all_requires_admin() { + doThrow(new MateClawException("err.workspace.insufficient_permission", 403, "")) + .when(workspaceService).requirePermission(WORKSPACE_ID, MEMBER_ID, "admin"); + + assertThatThrownBy(() -> + controller.list(null, null, null, /*mine*/ false, 1L, 20L, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class); + } + + @Test + void revoke_owner_succeeds_without_admin() { + ApprovalGrant g = newGrant(123L, MEMBER_ID); + when(grantMapper.selectById(123L)).thenReturn(g); + when(workspaceService.hasPermission(anyLong(), anyLong(), anyString())).thenReturn(false); + when(grantService.revoke(eq(123L), eq(MEMBER_ID))).thenReturn(true); + + controller.revoke(123L, WORKSPACE_ID, memberAuth); + + verify(grantService).revoke(123L, MEMBER_ID); + } + + @Test + void revoke_non_owner_non_admin_forbidden() { + ApprovalGrant g = newGrant(123L, /* grantedBy */ 5555L); + when(grantMapper.selectById(123L)).thenReturn(g); + when(workspaceService.hasPermission(WORKSPACE_ID, MEMBER_ID, "admin")).thenReturn(false); + + assertThatThrownBy(() -> controller.revoke(123L, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class) + .hasMessageContaining("only the grant owner or a workspace admin"); + verify(grantService, never()).revoke(anyLong(), anyLong()); + } + + @Test + void revoke_admin_succeeds_for_other_users_grant() { + ApprovalGrant g = newGrant(123L, /* grantedBy */ 5555L); + when(grantMapper.selectById(123L)).thenReturn(g); + when(workspaceService.hasPermission(WORKSPACE_ID, ADMIN_ID, "admin")).thenReturn(true); + when(grantService.revoke(eq(123L), eq(ADMIN_ID))).thenReturn(true); + + controller.revoke(123L, WORKSPACE_ID, adminAuth); + + verify(grantService).revoke(123L, ADMIN_ID); + } + + @Test + void revoke_cross_workspace_returns_not_found() { + ApprovalGrant g = newGrant(123L, MEMBER_ID); + g.setWorkspaceId(999L); // different workspace + when(grantMapper.selectById(123L)).thenReturn(g); + + assertThatThrownBy(() -> controller.revoke(123L, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class) + .hasMessageContaining("grant not found"); + } + } + + @Nested + class Resolutions { + + @Test + void grant_id_query_requires_admin() { + doThrow(new MateClawException("err.workspace.insufficient_permission", 403, "")) + .when(workspaceService).requirePermission(WORKSPACE_ID, MEMBER_ID, "admin"); + + assertThatThrownBy(() -> + controller.listResolutions(7777L, null, 100, WORKSPACE_ID, memberAuth)) + .isInstanceOf(MateClawException.class); + } + + @Test + void conversation_query_does_not_require_admin() { + when(resolutionMapper.selectList(any())).thenReturn(List.of()); + + controller.listResolutions(null, "conv-1", 100, WORKSPACE_ID, memberAuth); + + verify(workspaceService, never()).requirePermission(anyLong(), anyLong(), anyString()); + } + } + + // ─── Helpers ──────────────────────────────────────────────────────── + + private static ApprovalGrantController.CreateGrantRequest baseBody( + String scopeType, String scopeId, String toolName) { + ApprovalGrantController.CreateGrantRequest b = new ApprovalGrantController.CreateGrantRequest(); + b.scopeType = scopeType; + b.scopeId = scopeId; + b.toolName = toolName; + b.ruleId = null; + b.maxSeverity = "MEDIUM"; + b.grantKind = "ALWAYS"; + b.note = "test"; + return b; + } + + private static ApprovalGrant newGrant(long id, long grantedBy) { + ApprovalGrant g = new ApprovalGrant(); + g.setId(id); + g.setWorkspaceId(WORKSPACE_ID); + g.setScopeType("CONVERSATION"); + g.setScopeId("conv-1"); + g.setToolName("read_file"); + g.setMaxSeverity("MEDIUM"); + g.setGrantKind("ALWAYS"); + g.setGrantedBy(grantedBy); + g.setGrantedAt(LocalDateTime.now()); + g.setRevoked(0); + g.setDeleted(0); + return g; + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListenerTest.java b/mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListenerTest.java new file mode 100644 index 00000000..7979f694 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ApprovalResolutionLogListenerTest.java @@ -0,0 +1,159 @@ +package vip.mate.approval.grant.listener; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import vip.mate.approval.event.ApprovalResolutionEvent; +import vip.mate.approval.grant.WorkspaceLookupCache; +import vip.mate.approval.grant.entity.ApprovalResolutionLog; +import vip.mate.approval.grant.repository.ApprovalResolutionLogMapper; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link ApprovalResolutionLogListener}. + *

    + * Coverage targets: + *

      + *
    • USER_MANUAL approval event → resolution_log row with correct fields.
      • + *
    • TIMEOUT event → row with decision_source = TIMEOUT.
      • + *
    • findingsJson with multiple ruleIds → comma-joined, deduplicated rule_ids.
      • + *
    • workspace_id resolution goes through the cache (so deleted conversations + * produce a null workspace, allowed by V128 schema).
      • + *
    • Mapper failure does not propagate (the listener swallows so the resolved + * approval commit isn't endangered).
      • + *
    + */ +@ExtendWith(MockitoExtension.class) +class ApprovalResolutionLogListenerTest { + + @Mock ApprovalResolutionLogMapper resolutionMapper; + @Mock WorkspaceLookupCache workspaceLookupCache; + + @InjectMocks + ApprovalResolutionLogListener listener; + + @Test + void user_manual_approved_event_writes_row_with_workspace_from_cache() { + when(workspaceLookupCache.resolveByConversation("conv-1")).thenReturn(42L); + + ApprovalResolutionEvent event = new ApprovalResolutionEvent( + "pid-1", "conv-1", "agent-1", "user-1", "read_file", + "{\"path\":\"a.txt\"}", "LOW", + "[{\"ruleId\":\"shell.exec\",\"severity\":\"LOW\"}]", + "USER_MANUAL", null); + + listener.onApprovalResolved(event); + + ArgumentCaptor cap = ArgumentCaptor.forClass(ApprovalResolutionLog.class); + verify(resolutionMapper).insert(cap.capture()); + ApprovalResolutionLog row = cap.getValue(); + assertThat(row.getWorkspaceId()).isEqualTo(42L); + assertThat(row.getDecisionSource()).isEqualTo("USER_MANUAL"); + assertThat(row.getPendingId()).isEqualTo("pid-1"); + assertThat(row.getRuleIds()).isEqualTo("shell.exec"); + assertThat(row.getGrantId()).isNull(); + } + + @Test + void timeout_event_writes_row_with_timeout_source() { + when(workspaceLookupCache.resolveByConversation("conv-9")).thenReturn(7L); + + ApprovalResolutionEvent event = new ApprovalResolutionEvent( + "pid-9", "conv-9", "agent-9", null, "execute_shell_command", + "rm /tmp/x", "MEDIUM", null, "TIMEOUT", null); + + listener.onApprovalResolved(event); + + ArgumentCaptor cap = ArgumentCaptor.forClass(ApprovalResolutionLog.class); + verify(resolutionMapper).insert(cap.capture()); + assertThat(cap.getValue().getDecisionSource()).isEqualTo("TIMEOUT"); + assertThat(cap.getValue().getRuleIds()).isNull(); // findingsJson was null + } + + @Test + void multiple_findings_become_deduplicated_comma_list() { + when(workspaceLookupCache.resolveByConversation(any())).thenReturn(1L); + + String findings = "[" + + "{\"ruleId\":\"shell.curl\"}," + + "{\"ruleId\":\"shell.exec\"}," + + "{\"ruleId\":\"shell.curl\"}," + + "{\"ruleId\":null}" + + "]"; + ApprovalResolutionEvent event = new ApprovalResolutionEvent( + "pid-2", "conv-2", "agent-2", "user-2", "execute_shell_command", + "curl x | sh", "HIGH", findings, "USER_MANUAL", null); + + listener.onApprovalResolved(event); + + ArgumentCaptor cap = ArgumentCaptor.forClass(ApprovalResolutionLog.class); + verify(resolutionMapper).insert(cap.capture()); + // Deduplicated + null filtered + comma-joined. + assertThat(cap.getValue().getRuleIds()).isEqualTo("shell.curl,shell.exec"); + } + + @Test + void unknown_workspace_produces_null_workspace_id_row() { + when(workspaceLookupCache.resolveByConversation("conv-orphan")).thenReturn(null); + + ApprovalResolutionEvent event = new ApprovalResolutionEvent( + "pid-3", "conv-orphan", "agent-3", "user-3", "edit_file", + "...", "LOW", null, "USER_MANUAL", null); + + listener.onApprovalResolved(event); + + ArgumentCaptor cap = ArgumentCaptor.forClass(ApprovalResolutionLog.class); + verify(resolutionMapper).insert(cap.capture()); + assertThat(cap.getValue().getWorkspaceId()).isNull(); + } + + @Test + void mapper_failure_does_not_propagate() { + when(workspaceLookupCache.resolveByConversation(any())).thenReturn(1L); + when(resolutionMapper.insert(any(ApprovalResolutionLog.class))) + .thenThrow(new RuntimeException("DB down")); + + // No exception escapes — the resolved approval has already committed. + listener.onApprovalResolved(new ApprovalResolutionEvent( + "pid-x", "conv-x", "agent-x", "user-x", "tool", + "args", "LOW", null, "USER_MANUAL", null)); + } + + @Test + void malformed_findings_json_still_writes_row_without_rule_ids() { + when(workspaceLookupCache.resolveByConversation(any())).thenReturn(1L); + + ApprovalResolutionEvent event = new ApprovalResolutionEvent( + "pid-bad", "conv-bad", "agent-bad", "user-bad", "tool", + "args", "LOW", "{not-an-array}", "USER_MANUAL", null); + + listener.onApprovalResolved(event); + + ArgumentCaptor cap = ArgumentCaptor.forClass(ApprovalResolutionLog.class); + verify(resolutionMapper).insert(cap.capture()); + assertThat(cap.getValue().getRuleIds()).isNull(); + assertThat(cap.getValue().getDecisionSource()).isEqualTo("USER_MANUAL"); + } + + @Test + void long_args_are_truncated_to_500_chars() { + when(workspaceLookupCache.resolveByConversation(any())).thenReturn(1L); + + String longArgs = "x".repeat(800); + listener.onApprovalResolved(new ApprovalResolutionEvent( + "pid-long", "conv-long", "agent-long", "user-long", "tool", + longArgs, "LOW", null, "USER_MANUAL", null)); + + ArgumentCaptor cap = ArgumentCaptor.forClass(ApprovalResolutionLog.class); + verify(resolutionMapper).insert(cap.capture()); + assertThat(cap.getValue().getArgsPreview()).hasSize(500); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ConversationLifecycleListenerTest.java b/mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ConversationLifecycleListenerTest.java new file mode 100644 index 00000000..84136a1d --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/approval/grant/listener/ConversationLifecycleListenerTest.java @@ -0,0 +1,69 @@ +package vip.mate.approval.grant.listener; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import vip.mate.approval.grant.WorkspaceLookupCache; +import vip.mate.approval.grant.service.ApprovalGrantService; +import vip.mate.workspace.conversation.event.ConversationDeletedEvent; + +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link ConversationLifecycleListener}. + */ +@ExtendWith(MockitoExtension.class) +class ConversationLifecycleListenerTest { + + @Mock ApprovalGrantService grantService; + @Mock WorkspaceLookupCache workspaceLookupCache; + + @InjectMocks + ConversationLifecycleListener listener; + + @Test + void delete_revokes_grants_and_invalidates_cache() { + when(grantService.revokeConversationScopedGrants("conv-1")).thenReturn(2); + + listener.onConversationDeleted(new ConversationDeletedEvent("conv-1")); + + verify(grantService).revokeConversationScopedGrants("conv-1"); + verify(workspaceLookupCache).invalidate("conv-1"); + } + + @Test + void delete_with_no_active_grants_still_invalidates_cache() { + when(grantService.revokeConversationScopedGrants("conv-2")).thenReturn(0); + + listener.onConversationDeleted(new ConversationDeletedEvent("conv-2")); + + verify(workspaceLookupCache).invalidate("conv-2"); + } + + @Test + void grant_service_failure_still_invalidates_cache() { + // A stale workspace mapping is more dangerous than a missed revoke + // (the grant can no longer match its conversation anyway), so the + // finally-block invalidation runs even if revocation throws. + when(grantService.revokeConversationScopedGrants("conv-3")) + .thenThrow(new RuntimeException("DB down")); + + listener.onConversationDeleted(new ConversationDeletedEvent("conv-3")); + + verify(workspaceLookupCache).invalidate("conv-3"); + } + + @Test + void blank_or_null_conversation_id_is_no_op() { + listener.onConversationDeleted(new ConversationDeletedEvent("")); + listener.onConversationDeleted(new ConversationDeletedEvent(null)); + + verify(grantService, never()).revokeConversationScopedGrants(eq("")); + verify(workspaceLookupCache, never()).invalidate(eq("")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/channel/feishu/FeishuConversationIdAlignmentTest.java b/mateclaw-server/src/test/java/vip/mate/channel/feishu/FeishuConversationIdAlignmentTest.java new file mode 100644 index 00000000..ec7812b0 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/channel/feishu/FeishuConversationIdAlignmentTest.java @@ -0,0 +1,74 @@ +package vip.mate.channel.feishu; + +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * Locks the invariant that {@link FeishuChannelAdapter#buildConversationId} produces + * exactly the id {@code ChannelMessageRouter} derives for the same chat. + * + *

    The recent-file cache saves inbound attachments under + * {@code data/chat-uploads/{conversationId}/}; the prompt only exposes a file's + * name (not its path) to the model, so {@code ReadFileTool}/{@code DocumentExtractTool} + * resolve it through {@code ChatUploadResolver} under the runtime conversationId. + * If the storage id and the runtime id diverge, those tools cannot find the file + * and document reads silently fail — which is precisely the regression these tests + * guard against. + * + *

    The router derives its id from the routed {@code ChannelMessage}, whose + * {@code chatId} is {@code (isGroup ? shortSuffix : null)} and whose {@code senderId} + * is the full open id, via {@code feishu:{chatId != null ? chatId : senderId}}. + */ +class FeishuConversationIdAlignmentTest { + + private static final String CHANNEL = FeishuChannelAdapter.CHANNEL_TYPE; // "feishu" + private static final String SHORT_SUFFIX = "cli2_abcd1234"; + private static final String SENDER = "ou_user0123456789"; + + /** Mirror of ChannelMessageRouter#buildConversationId against the routed message. */ + private static String routerConversationId(String shortSuffix, String senderId, boolean isGroup) { + String routedChatId = isGroup ? shortSuffix : null; + String identifier = routedChatId != null ? routedChatId : senderId; + return identifier != null ? CHANNEL + ":" + identifier : null; + } + + @Test + void group_usesShortSuffix() { + assertEquals(CHANNEL + ":" + SHORT_SUFFIX, + FeishuChannelAdapter.buildConversationId(SHORT_SUFFIX, SENDER, true)); + } + + @Test + void dm_usesSenderOpenIdAndIgnoresShortSuffix() { + assertEquals(CHANNEL + ":" + SENDER, + FeishuChannelAdapter.buildConversationId(SHORT_SUFFIX, SENDER, false)); + } + + @Test + void group_nullShortSuffix_fallsBackToSender() { + // Degenerate group path: routed chatId is null, so the router (and this helper) + // fall back to the sender open id — never null when a sender is present. + assertEquals(CHANNEL + ":" + SENDER, + FeishuChannelAdapter.buildConversationId(null, SENDER, true)); + } + + @Test + void dm_nullSender_returnsNull() { + assertNull(FeishuChannelAdapter.buildConversationId(SHORT_SUFFIX, null, false)); + } + + @Test + void matchesRouterFormula_acrossCases() { + // Group and DM, with and without a short suffix — the storage id must equal + // the id the router computes for the routed ChannelMessage in every case. + assertEquals(routerConversationId(SHORT_SUFFIX, SENDER, true), + FeishuChannelAdapter.buildConversationId(SHORT_SUFFIX, SENDER, true)); + assertEquals(routerConversationId(SHORT_SUFFIX, SENDER, false), + FeishuChannelAdapter.buildConversationId(SHORT_SUFFIX, SENDER, false)); + assertEquals(routerConversationId(null, SENDER, true), + FeishuChannelAdapter.buildConversationId(null, SENDER, true)); + assertEquals(routerConversationId(SHORT_SUFFIX, null, false), + FeishuChannelAdapter.buildConversationId(SHORT_SUFFIX, null, false)); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/channel/media/InboundMediaDownloaderTest.java b/mateclaw-server/src/test/java/vip/mate/channel/media/InboundMediaDownloaderTest.java new file mode 100644 index 00000000..999cf98b --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/channel/media/InboundMediaDownloaderTest.java @@ -0,0 +1,135 @@ +package vip.mate.channel.media; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +import java.nio.file.Path; +import java.util.Optional; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +class InboundMediaDownloaderTest { + + /** PNG header followed by filler. */ + private static byte[] pngBytes() { + byte[] data = new byte[32]; + data[0] = (byte) 0x89; + data[1] = 0x50; + data[2] = 0x4E; + data[3] = 0x47; + return data; + } + + @Test + @DisplayName("Null hint + PNG bytes → synthesized name and accurate MIME") + void synthesizesNameFromSniff(@TempDir Path dir) { + Optional result = InboundMediaDownloader.download( + InboundMediaDownloaderTest::pngBytes, null, dir, "weixin", "seed-1"); + + assertTrue(result.isPresent()); + InboundMediaDownloader.DownloadedMedia m = result.get(); + assertEquals("image/png", m.contentType()); + assertTrue(m.isImage()); + assertTrue(m.fileName().endsWith(".png"), "synthesized name should carry sniffed ext"); + assertTrue(m.storedName().startsWith("weixin_"), "stored name should carry channel prefix"); + assertTrue(m.localPath().toFile().exists()); + assertEquals(32, m.fileSize()); + } + + @Test + @DisplayName("Wrong .jpg extension on PNG bytes is NOT corrected (real names respected)") + void keepsAuthoritativeName(@TempDir Path dir) { + // A meaningful, user-supplied extension is kept verbatim — only the + // MIME comes from sniffing. This is the documented contract: pass null + // for placeholders, a real name only when it is real. + Optional result = InboundMediaDownloader.download( + InboundMediaDownloaderTest::pngBytes, "report.jpg", dir, "weixin", "seed-2"); + + assertTrue(result.isPresent()); + InboundMediaDownloader.DownloadedMedia m = result.get(); + assertEquals("report.jpg", m.fileName()); + assertEquals("image/png", m.contentType(), "MIME still comes from magic bytes"); + } + + @Test + @DisplayName(".bin hint is treated as generic and replaced with sniffed ext") + void binHintIsGeneric(@TempDir Path dir) { + Optional result = InboundMediaDownloader.download( + InboundMediaDownloaderTest::pngBytes, "file.bin", dir, "wecom", "seed-3"); + + assertTrue(result.isPresent()); + assertTrue(result.get().fileName().endsWith(".png")); + } + + @Test + @DisplayName("Transient failures are retried, then succeed") + void retriesThenSucceeds(@TempDir Path dir) { + AtomicInteger calls = new AtomicInteger(); + InboundMediaDownloader.ByteSource flaky = () -> { + if (calls.incrementAndGet() < 3) { + throw new RuntimeException("transient"); + } + return pngBytes(); + }; + + Optional result = InboundMediaDownloader.download( + flaky, null, dir, "weixin", "seed-4", 3); + + assertTrue(result.isPresent()); + assertEquals(3, calls.get(), "should have retried up to the 3rd attempt"); + } + + @Test + @DisplayName("fileUrlBuilder maps storedName to a servable URL") + void buildsFileUrl(@TempDir Path dir) { + Optional result = InboundMediaDownloader.download( + InboundMediaDownloaderTest::pngBytes, null, dir, "weixin", "seed-url", + storedName -> "/api/v1/chat/files/weixin:bob/" + storedName); + + assertTrue(result.isPresent()); + InboundMediaDownloader.DownloadedMedia m = result.get(); + assertEquals("/api/v1/chat/files/weixin:bob/" + m.storedName(), m.fileUrl()); + } + + @Test + @DisplayName("A throwing fileUrlBuilder degrades to null fileUrl, file still saved") + void fileUrlBuilderFailureDegrades(@TempDir Path dir) { + Optional result = InboundMediaDownloader.download( + InboundMediaDownloaderTest::pngBytes, null, dir, "weixin", "seed-url-fail", + storedName -> { + throw new RuntimeException("url build boom"); + }); + + assertTrue(result.isPresent(), "a broken URL builder must not fail the download"); + InboundMediaDownloader.DownloadedMedia m = result.get(); + assertNull(m.fileUrl()); + assertTrue(m.localPath().toFile().exists(), "file should still be persisted"); + } + + @Test + @DisplayName("No builder → null fileUrl") + void noBuilderLeavesNullUrl(@TempDir Path dir) { + Optional result = InboundMediaDownloader.download( + InboundMediaDownloaderTest::pngBytes, null, dir, "weixin", "seed-no-url"); + + assertTrue(result.isPresent()); + assertNull(result.get().fileUrl()); + } + + @Test + @DisplayName("Exhausted retries return empty, no file written") + void exhaustedReturnsEmpty(@TempDir Path dir) { + InboundMediaDownloader.ByteSource always = () -> { + throw new RuntimeException("down"); + }; + Optional result = InboundMediaDownloader.download( + always, null, dir, "weixin", "seed-5", 2); + + assertTrue(result.isEmpty()); + assertEquals(0, dir.toFile().listFiles().length, "no partial file should remain"); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/channel/media/MediaTypeSnifferTest.java b/mateclaw-server/src/test/java/vip/mate/channel/media/MediaTypeSnifferTest.java new file mode 100644 index 00000000..851b3825 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/channel/media/MediaTypeSnifferTest.java @@ -0,0 +1,151 @@ +package vip.mate.channel.media; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import java.io.ByteArrayOutputStream; +import java.nio.charset.StandardCharsets; +import java.util.zip.ZipEntry; +import java.util.zip.ZipOutputStream; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Magic-byte detection tests. The cases that matter most for IM image + * reception are PNG / WEBP / HEIC: phone photos and screenshots are routinely + * not JPEG, and a wrong Content-Type makes multimodal gateways reject them. + */ +class MediaTypeSnifferTest { + + private static byte[] bytes(int... values) { + byte[] out = new byte[values.length]; + for (int i = 0; i < values.length; i++) { + out[i] = (byte) values[i]; + } + return out; + } + + /** Build an ISO-BMFF header: [size][ftyp][brand]. */ + private static byte[] ftyp(String brand) { + byte[] brandBytes = brand.getBytes(StandardCharsets.US_ASCII); + byte[] head = new byte[12]; + head[0] = 0x00; + head[1] = 0x00; + head[2] = 0x00; + head[3] = 0x18; + head[4] = 'f'; + head[5] = 't'; + head[6] = 'y'; + head[7] = 'p'; + System.arraycopy(brandBytes, 0, head, 8, 4); + return head; + } + + @Test + @DisplayName("PNG signature → image/png") + void detectsPng() { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(bytes(0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A)); + assertEquals("image/png", s.contentType()); + assertEquals(".png", s.extension()); + assertTrue(s.isImage()); + } + + @Test + @DisplayName("JPEG signature → image/jpeg") + void detectsJpeg() { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(bytes(0xFF, 0xD8, 0xFF, 0xE0)); + assertEquals("image/jpeg", s.contentType()); + assertEquals(".jpg", s.extension()); + } + + @Test + @DisplayName("RIFF…WEBP → image/webp (common for screenshots)") + void detectsWebp() { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff( + bytes(0x52, 0x49, 0x46, 0x46, 0x00, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50)); + assertEquals("image/webp", s.contentType()); + assertEquals(".webp", s.extension()); + assertTrue(s.isImage()); + } + + @Test + @DisplayName("HEIC ftyp brand → image/heic, NOT video/mp4 (iPhone photos)") + void detectsHeicNotMp4() { + for (String brand : new String[]{"heic", "heix", "mif1", "heim"}) { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(ftyp(brand)); + assertEquals("image/heic", s.contentType(), "brand=" + brand); + assertTrue(s.isImage(), "brand=" + brand + " should be an image"); + assertFalse(s.isVideo(), "brand=" + brand + " must not be classified as video"); + } + } + + @Test + @DisplayName("Plain MP4 ftyp brand → video/mp4") + void detectsMp4() { + for (String brand : new String[]{"isom", "mp41", "mp42", "avc1"}) { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(ftyp(brand)); + assertEquals("video/mp4", s.contentType(), "brand=" + brand); + assertTrue(s.isVideo(), "brand=" + brand); + } + } + + @Test + @DisplayName("QuickTime ftyp brand → video/quicktime") + void detectsQuickTime() { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(ftyp("qt ")); + assertEquals("video/quicktime", s.contentType()); + assertEquals(".mov", s.extension()); + } + + @Test + @DisplayName("PDF signature → application/pdf") + void detectsPdf() { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(bytes(0x25, 0x50, 0x44, 0x46, 0x2D)); + assertEquals("application/pdf", s.contentType()); + assertEquals(".pdf", s.extension()); + } + + @Test + @DisplayName("GIF signature → image/gif") + void detectsGif() { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(bytes(0x47, 0x49, 0x46, 0x38, 0x39, 0x61)); + assertEquals("image/gif", s.contentType()); + } + + @Test + @DisplayName("AMR voice signature → audio/amr") + void detectsAmr() { + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(bytes(0x23, 0x21, 0x41, 0x4D, 0x52, 0x0A)); + assertEquals("audio/amr", s.contentType()); + assertTrue(s.isAudio()); + } + + @Test + @DisplayName("DOCX (zip container) refined from plain zip") + void refinesDocx() throws Exception { + ByteArrayOutputStream baos = new ByteArrayOutputStream(); + try (ZipOutputStream zos = new ZipOutputStream(baos)) { + zos.putNextEntry(new ZipEntry("[Content_Types].xml")); + zos.write("".getBytes(StandardCharsets.UTF_8)); + zos.closeEntry(); + zos.putNextEntry(new ZipEntry("word/document.xml")); + zos.write("".getBytes(StandardCharsets.UTF_8)); + zos.closeEntry(); + } + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(baos.toByteArray()); + assertEquals(".docx", s.extension()); + assertTrue(s.contentType().contains("wordprocessingml")); + } + + @Test + @DisplayName("Unknown / too-short bytes → octet-stream, not crash") + void handlesUnknownAndShort() { + assertEquals(MediaTypeSniffer.Sniffed.UNKNOWN, MediaTypeSniffer.sniff(null)); + assertEquals(MediaTypeSniffer.Sniffed.UNKNOWN, MediaTypeSniffer.sniff(bytes(0x01))); + MediaTypeSniffer.Sniffed s = MediaTypeSniffer.sniff(bytes(0x01, 0x02, 0x03, 0x04, 0x05)); + assertFalse(s.isKnown()); + assertEquals("application/octet-stream", s.contentType()); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/goal/controller/GoalControllerTest.java b/mateclaw-server/src/test/java/vip/mate/goal/controller/GoalControllerTest.java index f08fcc83..c8df2206 100644 --- a/mateclaw-server/src/test/java/vip/mate/goal/controller/GoalControllerTest.java +++ b/mateclaw-server/src/test/java/vip/mate/goal/controller/GoalControllerTest.java @@ -10,6 +10,7 @@ import vip.mate.common.result.R; import vip.mate.exception.MateClawException; import vip.mate.goal.model.GoalCreateRequest; import vip.mate.goal.model.GoalEntity; +import vip.mate.goal.model.GoalResponse; import vip.mate.goal.model.GoalStatus; import vip.mate.goal.model.GoalUpdateRequest; import vip.mate.goal.service.GoalService; @@ -64,6 +65,13 @@ class GoalControllerTest { return g; } + private GoalResponse resp(Long id, GoalStatus status) { + GoalResponse r = new GoalResponse(); + r.setId(id); + r.setStatus(status); + return r; + } + private GoalCreateRequest req(String convId) { GoalCreateRequest r = new GoalCreateRequest(); r.setConversationId(convId); @@ -90,7 +98,8 @@ class GoalControllerTest { when(conversationService.findByConversationId("conv-1")).thenReturn(conv("conv-1", 10L, 1L)); when(goalService.create(any(), eq("alice"))) .thenReturn(goal(1L, "conv-1", GoalStatus.ACTIVE)); - R result = controller.create(req("conv-1"), auth); + when(goalService.toResponse(any())).thenReturn(resp(1L, GoalStatus.ACTIVE)); + R result = controller.create(req("conv-1"), auth); assertNotNull(result.getData()); assertEquals(1L, result.getData().getId()); } @@ -177,8 +186,9 @@ class GoalControllerTest { when(goalService.getById(1L)).thenReturn(g); when(conversationService.isConversationOwner("conv-1", "alice")).thenReturn(true); when(goalService.pause(1L, "alice")).thenReturn(goal(1L, "conv-1", GoalStatus.PAUSED)); + when(goalService.toResponse(any())).thenReturn(resp(1L, GoalStatus.PAUSED)); - R result = controller.pause(1L, auth); + R result = controller.pause(1L, auth); assertEquals(GoalStatus.PAUSED, result.getData().getStatus()); } diff --git a/mateclaw-server/src/test/java/vip/mate/goal/model/GoalCriteriaCodecTest.java b/mateclaw-server/src/test/java/vip/mate/goal/model/GoalCriteriaCodecTest.java new file mode 100644 index 00000000..48f82af2 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/goal/model/GoalCriteriaCodecTest.java @@ -0,0 +1,113 @@ +package vip.mate.goal.model; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.Test; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pure unit tests for the checklist (de)serialization + merge helpers. + */ +class GoalCriteriaCodecTest { + + private final ObjectMapper mapper = new ObjectMapper(); + + private static GoalCriterion c(String id, String text, boolean passed) { + return new GoalCriterion(id, text, passed, passed ? "ok" : ""); + } + + // ---------- parse ---------- + + @Test + void parse_nullOrBlankOrCorrupt_returnsEmptyMutableList() { + assertTrue(GoalCriteriaCodec.parse(null, mapper).isEmpty()); + assertTrue(GoalCriteriaCodec.parse("", mapper).isEmpty()); + assertTrue(GoalCriteriaCodec.parse(" ", mapper).isEmpty()); + assertTrue(GoalCriteriaCodec.parse("{not valid json", mapper).isEmpty()); + // mutable: callers append during bootstrap/append paths + GoalCriteriaCodec.parse(null, mapper).add(c("C1", "x", false)); + } + + @Test + void parse_roundTrip() { + String json = GoalCriteriaCodec.serialize(List.of(c("C1", "tests pass", true)), mapper); + List back = GoalCriteriaCodec.parse(json, mapper); + assertEquals(1, back.size()); + assertEquals("C1", back.get(0).id()); + assertEquals("tests pass", back.get(0).text()); + assertTrue(back.get(0).passed()); + } + + @Test + void serialize_null_returnsNull() { + assertNull(GoalCriteriaCodec.serialize(null, mapper)); + } + + // ---------- merge ---------- + + @Test + void merge_appliesVerdictById_preservesTextAndUntouched() { + List existing = List.of( + c("C1", "first", false), + c("C2", "second", false)); + List delta = List.of( + new GoalChecklistVerdict.CriterionVerdict("C1", true, "did it")); + + List merged = GoalCriteriaCodec.merge(existing, delta); + + assertEquals(2, merged.size()); + assertTrue(merged.get(0).passed()); + assertEquals("did it", merged.get(0).evidence()); + assertEquals("first", merged.get(0).text()); // text preserved + assertFalse(merged.get(1).passed()); // untouched stays + assertEquals("second", merged.get(1).text()); + } + + @Test + void merge_unknownVerdictId_isIgnored() { + List existing = List.of(c("C1", "first", false)); + List delta = List.of( + new GoalChecklistVerdict.CriterionVerdict("C9", true, "nope")); + List merged = GoalCriteriaCodec.merge(existing, delta); + assertFalse(merged.get(0).passed()); + } + + // ---------- allPassed / remaining ---------- + + @Test + void allPassed_emptyIsFalse() { + assertFalse(GoalCriteriaCodec.allPassed(List.of())); + } + + @Test + void allPassed_trueOnlyWhenEveryPassed() { + assertTrue(GoalCriteriaCodec.allPassed(List.of(c("C1", "a", true), c("C2", "b", true)))); + assertFalse(GoalCriteriaCodec.allPassed(List.of(c("C1", "a", true), c("C2", "b", false)))); + } + + @Test + void remaining_returnsOnlyUnpassed() { + List rem = GoalCriteriaCodec.remaining( + List.of(c("C1", "a", true), c("C2", "b", false), c("C3", "c", false))); + assertEquals(2, rem.size()); + assertEquals("C2", rem.get(0).id()); + assertEquals("C3", rem.get(1).id()); + } + + // ---------- reindex ---------- + + @Test + void reindex_assignsSequentialIds() { + List out = GoalCriteriaCodec.reindex(List.of( + c("", "a", false), c("zzz", "b", false), c("C99", "c", false))); + assertEquals("C1", out.get(0).id()); + assertEquals("C2", out.get(1).id()); + assertEquals("C3", out.get(2).id()); + assertEquals("a", out.get(0).text()); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalEvaluationServiceTest.java b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalEvaluationServiceTest.java index ff5c6809..0a4cd348 100644 --- a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalEvaluationServiceTest.java +++ b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalEvaluationServiceTest.java @@ -12,6 +12,8 @@ import org.springframework.ai.chat.model.ChatModel; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.chat.model.Generation; import org.springframework.ai.chat.prompt.Prompt; +import org.springframework.ai.evaluation.EvaluationRequest; +import org.springframework.ai.evaluation.EvaluationResponse; import org.springframework.retry.support.RetryTemplate; import vip.mate.goal.config.GoalProperties; import vip.mate.goal.model.GoalEntity; @@ -67,6 +69,14 @@ class GoalEvaluationServiceTest { return g; } + /** Goal that already has a 2-item checklist — drives verdict mode. */ + private GoalEntity goalWithCriteria() { + GoalEntity g = goal(); + g.setCriteria("[{\"id\":\"C1\",\"text\":\"DNS configured\",\"passed\":false,\"evidence\":\"\"}," + + "{\"id\":\"C2\",\"text\":\"TLS enabled\",\"passed\":false,\"evidence\":\"\"}]"); + return g; + } + private ModelConfigEntity model(String name) { ModelConfigEntity m = new ModelConfigEntity(); m.setProvider("dashscope"); @@ -111,88 +121,82 @@ class GoalEvaluationServiceTest { verify(chatModelFactory, never()).buildFor(any(), any()); } - // ==================== Happy paths ==================== + // ==================== Bootstrap mode (no criteria yet) ==================== @Test - void continueDecision_whenScoreBelowOne() { - stubChatResponse("{\"score\": 0.6, \"gap\": \"DNS not configured yet\", \"completed\": false}"); + void bootstrap_createsChecklist_fromDraftJson() { + stubChatResponse("{\"criteria\":[" + + "{\"text\":\"DNS configured\"}," + + "{\"text\":\"TLS enabled\"}]}"); GoalEvaluationResult r = svc.evaluate(goal(), - List.of(new UserMessage("status?")), - "DNS configured, still need TLS"); + List.of(new UserMessage("status?")), "working on it"); assertEquals(GoalEvaluationResult.DECISION_CONTINUE, r.decision()); - assertFalse(r.completed()); - assertEquals(0.6, r.score(), 1e-9); - assertEquals("DNS not configured yet", r.gap()); + assertFalse(r.completed(), "bootstrap round never completes"); + assertNotNull(r.bootstrapCriteria()); + assertEquals(2, r.bootstrapCriteria().size()); + assertEquals("C1", r.bootstrapCriteria().get(0).id()); + assertFalse(r.bootstrapCriteria().get(0).passed()); assertEquals(1, r.llmCallsConsumed()); assertEquals("qwen-turbo", r.evaluatorModel()); } @Test - void completedDecision_whenJsonSaysCompleted() { - stubChatResponse("{\"score\": 0.95, \"gap\": \"\", \"completed\": true}"); - GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "all green"); + void bootstrap_parsesMarkdownFences() { + stubChatResponse("```json\n{\"criteria\":[{\"text\":\"only one\"}]}\n```"); + GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); + assertNotNull(r.bootstrapCriteria()); + assertEquals(1, r.bootstrapCriteria().size()); + assertEquals("only one", r.bootstrapCriteria().get(0).text()); + } + + @Test + void bootstrap_emptyDraft_returnsFallback() { + stubChatResponse("{\"criteria\":[]}"); + GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); + assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision()); + } + + // ==================== Verdict mode (criteria exist) ==================== + + @Test + void verdict_partial_continues() { + stubChatResponse("{\"criterionVerdicts\":[" + + "{\"id\":\"C1\",\"passed\":true,\"evidence\":\"page returns 200\"}]," + + "\"summary\":\"1 of 2\"}"); + GoalEvaluationResult r = svc.evaluate(goalWithCriteria(), List.of(), "DNS done"); + assertEquals(GoalEvaluationResult.DECISION_CONTINUE, r.decision()); + assertFalse(r.completed()); + assertEquals(0.5, r.score(), 1e-9); // 1 of 2 merged criteria passed + assertEquals(1, r.criterionVerdicts().size()); + assertEquals(1, r.llmCallsConsumed()); + } + + @Test + void verdict_allPassed_completes() { + stubChatResponse("{\"criterionVerdicts\":[" + + "{\"id\":\"C1\",\"passed\":true,\"evidence\":\"200\"}," + + "{\"id\":\"C2\",\"passed\":true,\"evidence\":\"tls ok\"}]," + + "\"summary\":\"done\"}"); + GoalEvaluationResult r = svc.evaluate(goalWithCriteria(), List.of(), "all green"); assertEquals(GoalEvaluationResult.DECISION_COMPLETED, r.decision()); assertTrue(r.completed()); - } - - @Test - void scoreOfOne_implicitlyCompletes_evenWhenJsonSaysFalse() { - stubChatResponse("{\"score\": 1.0, \"gap\": \"\", \"completed\": false}"); - GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "perfect answer"); - assertTrue(r.completed(), "score=1.0 must imply completed regardless of the bool field"); - assertEquals(GoalEvaluationResult.DECISION_COMPLETED, r.decision()); - } - - @Test - void score_clampedTo01_whenModelReturnsOutOfRange() { - stubChatResponse("{\"score\": 1.7, \"gap\": \"\", \"completed\": true}"); - GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "answer"); assertEquals(1.0, r.score(), 1e-9); } - @Test - void negativeScore_clampedToZero() { - stubChatResponse("{\"score\": -0.2, \"gap\": \"x\", \"completed\": false}"); - GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "answer"); - assertEquals(0.0, r.score(), 1e-9); - } - // ==================== Parser tolerance ==================== - @Test - void parsesEvenWhenWrappedInMarkdownFences() { - // Lenient stub: parser tolerance shouldn't depend on a specific code path. - stubChatResponse("```json\n" - + "{\"score\": 0.4, \"gap\": \"still need TLS\", \"completed\": false}\n" - + "```"); - GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "DNS set up"); - assertEquals(GoalEvaluationResult.DECISION_CONTINUE, r.decision()); - assertEquals(0.4, r.score(), 1e-9); - assertEquals("still need TLS", r.gap()); - } - @Test void parseFails_whenNoJsonObjectInOutput() { stubChatResponse("I think it's about 60% done."); GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision()); - assertEquals(0, r.llmCallsConsumed()); - } - - @Test - void parseFails_whenScoreFieldMissing() { - stubChatResponse("{\"gap\": \"missing\", \"completed\": false}"); - GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); - assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision()); - assertTrue(r.gap().contains("parse_missing_score")); + // The call was made and returned garbage — it still spends one call. + assertEquals(1, r.llmCallsConsumed()); } @Test void parseFails_whenJsonMalformed() { - // Closing brace present but interior is invalid — exercises the - // ObjectMapper.readTree exception path rather than the cheaper - // "no object found" pre-check. - stubChatResponse("{\"score\": 0.5, \"gap\": }"); + stubChatResponse("{\"criteria\": }"); GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision()); assertTrue(r.gap().contains("parse_failed")); @@ -229,7 +233,7 @@ class GoalEvaluationServiceTest { when(chatModelFactory.buildFor(eq(named), any())).thenReturn(chatModel); ChatResponse response = new ChatResponse(List.of( new Generation(new AssistantMessage( - "{\"score\":0.5,\"gap\":\"\",\"completed\":false}")))); + "{\"criteria\":[{\"text\":\"works\"}]}")))); when(chatModel.call(any(Prompt.class))).thenReturn(response); // Default lookup is never consulted when an override is configured. lenient().when(modelConfigService.getDefaultModel()).thenReturn(null); @@ -248,4 +252,54 @@ class GoalEvaluationServiceTest { assertFalse(r.completed()); assertTrue(r.gap().contains("evaluator unavailable")); } + + // ==================== Post-call billing (failed output still spends a call) ==================== + + @Test + void emptyResponseAfterCall_billsOneLlmCall() { + stubChatResponse(" "); + GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); + assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision()); + assertEquals(1, r.llmCallsConsumed(), "a spent-but-empty evaluator call must charge 1"); + assertEquals("qwen-turbo", r.evaluatorModel()); + } + + @Test + void parseFailureAfterCall_billsOneLlmCall() { + stubChatResponse("{\"criteria\": }"); // malformed -> parse fail (call already spent) + GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); + assertEquals(GoalEvaluationResult.DECISION_FALLBACK, r.decision()); + assertEquals(1, r.llmCallsConsumed()); + } + + // ==================== Bootstrap criteria cap ==================== + + @Test + void bootstrap_capsCriteriaAtMax() { + StringBuilder sb = new StringBuilder("{\"criteria\":["); + for (int i = 0; i < 12; i++) { + if (i > 0) sb.append(','); + sb.append("{\"text\":\"criterion ").append(i).append("\"}"); + } + sb.append("]}"); + stubChatResponse(sb.toString()); + GoalEvaluationResult r = svc.evaluate(goal(), List.of(), "x"); + assertNotNull(r.bootstrapCriteria()); + assertTrue(r.bootstrapCriteria().size() <= 8, + "bootstrap must cap criteria at MAX_BOOTSTRAP_CRITERIA; got " + r.bootstrapCriteria().size()); + } + + // ==================== Evaluator SPI ==================== + + @Test + void evaluatorSpi_judgesResponseInVerdictMode() { + // The objective is wrapped as criterion C1; a verdict JSON marking C1 + // passed must surface as isPass()=true with score 1.0 — NOT a bootstrap. + stubChatResponse("{\"criterionVerdicts\":[{\"id\":\"C1\",\"passed\":true,\"evidence\":\"matches\"}],\"summary\":\"ok\"}"); + EvaluationResponse resp = svc.evaluate( + new EvaluationRequest("Return a greeting", "Hello, world!")); + assertTrue(resp.isPass()); + assertEquals(1.0f, resp.getScore(), 1e-6); + assertTrue(resp.getMetadata().containsKey("criterionVerdicts")); + } } diff --git a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalFollowupServiceTest.java b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalFollowupServiceTest.java index 3082e49b..a9fc0f91 100644 --- a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalFollowupServiceTest.java +++ b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalFollowupServiceTest.java @@ -1,6 +1,8 @@ package vip.mate.goal.service; +import com.fasterxml.jackson.databind.ObjectMapper; import org.junit.jupiter.api.Test; +import vip.mate.goal.config.GoalProperties; import vip.mate.goal.model.GoalEntity; import vip.mate.goal.model.GoalEvaluationResult; import vip.mate.goal.model.GoalStatus; @@ -8,16 +10,16 @@ import vip.mate.goal.model.GoalStatus; import java.time.LocalDateTime; import java.util.Optional; -import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; /** - * Covers the five follow-up gating conditions from RFC 48 §3.10. Every - * negative case must independently block the follow-up. + * Covers the follow-up gating conditions. Every negative case must + * independently block the follow-up. */ class GoalFollowupServiceTest { - private final GoalFollowupService svc = new GoalFollowupService(); + private final GoalProperties properties = new GoalProperties(); + private final GoalFollowupService svc = new GoalFollowupService(properties, new ObjectMapper()); private GoalEntity goal(boolean autoEnabled) { GoalEntity g = new GoalEntity(); @@ -38,7 +40,8 @@ class GoalFollowupServiceTest { return new GoalEvaluationResult( score, "missing X", decision, false, - "stub", 0, 0L); + "stub", 0, 0L, + java.util.List.of(), null); } @Test @@ -49,6 +52,20 @@ class GoalFollowupServiceTest { assertTrue(out.isEmpty()); } + @Test + void allowAutoFollowupGate_overridesPerGoalFlag() { + properties.setAllowAutoFollowup(false); + try { + // per-goal flag on + budget healthy, yet the runtime hard gate wins. + Optional out = svc.maybeBuildFollowup( + goal(true), + res(0.6, GoalEvaluationResult.DECISION_CONTINUE)); + assertTrue(out.isEmpty()); + } finally { + properties.setAllowAutoFollowup(true); + } + } + @Test void completedDecision_returnsEmpty() { Optional out = svc.maybeBuildFollowup( @@ -58,11 +75,14 @@ class GoalFollowupServiceTest { } @Test - void highScore_returnsEmpty() { + void highScoreButStillContinue_followsUp() { + // No score gate: completion is decided by decision==completed, not a + // numeric threshold. A 20/21 goal (score ~0.95) that is still "continue" + // has remaining criteria and MUST follow up. Optional out = svc.maybeBuildFollowup( goal(true), res(0.96, GoalEvaluationResult.DECISION_CONTINUE)); - assertTrue(out.isEmpty()); + assertTrue(out.isPresent()); } @Test diff --git a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalServiceTest.java b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalServiceTest.java index a39cfc9d..ee39d3cd 100644 --- a/mateclaw-server/src/test/java/vip/mate/goal/service/GoalServiceTest.java +++ b/mateclaw-server/src/test/java/vip/mate/goal/service/GoalServiceTest.java @@ -241,7 +241,8 @@ class GoalServiceTest { GoalEvaluationResult r = new GoalEvaluationResult( 0.62, "DNS still missing", "continue", false, - "qwen-turbo", 1, 800L); + "qwen-turbo", 1, 800L, + java.util.List.of(), null); service.recordEvaluation(1L, r, 3, 1); ArgumentCaptor evCaptor = ArgumentCaptor.forClass(GoalEventEntity.class); @@ -313,6 +314,70 @@ class GoalServiceTest { verify(goalMapper, never()).selectById(any()); } + // ==================== criteria checklist ==================== + + @Test + void create_normalizesInitialCriteria_assignsIdsForcesUnpassed() { + when(goalMapper.selectOne(any())).thenReturn(null); + when(goalMapper.insert(any(GoalEntity.class))).thenReturn(1); + + GoalCreateRequest r = validReq(); + r.setCriteria(java.util.List.of( + new vip.mate.goal.model.GoalCriterion("ignored", "tests pass", true, "x"), + new vip.mate.goal.model.GoalCriterion("", " ", false, ""), // blank dropped + new vip.mate.goal.model.GoalCriterion("", "deployed", false, ""))); + + ArgumentCaptor captor = ArgumentCaptor.forClass(GoalEntity.class); + service.create(r, "alice"); + verify(goalMapper).insert(captor.capture()); + + java.util.List parsed = + vip.mate.goal.model.GoalCriteriaCodec.parse(captor.getValue().getCriteria(), new ObjectMapper()); + assertEquals(2, parsed.size()); + assertEquals("C1", parsed.get(0).id()); + assertEquals("tests pass", parsed.get(0).text()); + assertFalse(parsed.get(0).passed()); // forced false even though caller said true + assertEquals("C2", parsed.get(1).id()); + assertEquals("deployed", parsed.get(1).text()); + } + + @Test + void create_emptyCriteria_leavesColumnNull_forBootstrap() { + when(goalMapper.selectOne(any())).thenReturn(null); + when(goalMapper.insert(any(GoalEntity.class))).thenReturn(1); + ArgumentCaptor captor = ArgumentCaptor.forClass(GoalEntity.class); + service.create(validReq(), "alice"); + verify(goalMapper).insert(captor.capture()); + assertNull(captor.getValue().getCriteria()); + } + + @Test + void create_autoFollowup_threeState() { + when(goalMapper.selectOne(any())).thenReturn(null); + when(goalMapper.insert(any(GoalEntity.class))).thenReturn(1); + + // null -> config default (true by default) + assertTrue(service.create(validReq(), "alice").getAutoFollowupEnabled()); + + // explicit false is honored + GoalCreateRequest off = validReq(); + off.setAutoFollowupEnabled(false); + assertFalse(service.create(off, "alice").getAutoFollowupEnabled()); + } + + @Test + void toResponse_parsesCriteriaArray_nullBecomesEmpty() { + GoalEntity g = persisted(1L, GoalStatus.ACTIVE); + g.setCriteria("[{\"id\":\"C1\",\"text\":\"a\",\"passed\":true,\"evidence\":\"ok\"}]"); + var resp = service.toResponse(g); + assertEquals(1, resp.getCriteria().size()); + assertTrue(resp.getCriteria().get(0).passed()); + + GoalEntity bare = persisted(2L, GoalStatus.ACTIVE); // criteria == null + assertNotNull(service.toResponse(bare).getCriteria()); + assertTrue(service.toResponse(bare).getCriteria().isEmpty()); + } + // ==================== optimistic lock retry ==================== @Test diff --git a/mateclaw-server/src/test/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilderClaude48Test.java b/mateclaw-server/src/test/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilderClaude48Test.java new file mode 100644 index 00000000..c5a8f57e --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/llm/chatmodel/AnthropicChatModelBuilderClaude48Test.java @@ -0,0 +1,88 @@ +package vip.mate.llm.chatmodel; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * {@link AnthropicChatModelBuilder#isClaude48} must correctly classify the + * Claude 4.8 model variants we'll see in production — including the + * higher-priced {@code -fast} sibling. + * + *

    Claude 4.8 inherits 4.7's strict API contract: temperature / top_p / + * top_k must be unset, and the "xhigh" thinking tier is available. The + * builder uses {@link AnthropicChatModelBuilder#isClaude47OrLater} to share + * the gating logic across both generations.

    + */ +class AnthropicChatModelBuilderClaude48Test { + + @Test + @DisplayName("isClaude48 detects hyphenated direct-API model names") + void detect_hyphenated() { + assertTrue(AnthropicChatModelBuilder.isClaude48("claude-opus-4-8")); + assertTrue(AnthropicChatModelBuilder.isClaude48("claude-opus-4-8-fast")); + } + + @Test + @DisplayName("isClaude48 detects dotted variants (e.g. OpenRouter / mixed dialects)") + void detect_dotted() { + assertTrue(AnthropicChatModelBuilder.isClaude48("claude-opus-4.8")); + assertTrue(AnthropicChatModelBuilder.isClaude48("claude-opus-4.8-fast")); + } + + @Test + @DisplayName("isClaude48 detects OpenRouter-style prefixed model ids") + void detect_openrouterPrefix() { + assertTrue(AnthropicChatModelBuilder.isClaude48("anthropic/claude-opus-4-8")); + assertTrue(AnthropicChatModelBuilder.isClaude48("anthropic/claude-opus-4-8-fast")); + assertTrue(AnthropicChatModelBuilder.isClaude48("anthropic/claude-opus-4.8")); + assertTrue(AnthropicChatModelBuilder.isClaude48("anthropic/claude-opus-4.8-fast")); + } + + @Test + @DisplayName("isClaude48 ignores 4.5 / 4.6 / 4.7 / 3.x and unrelated names") + void detect_negatives() { + assertFalse(AnthropicChatModelBuilder.isClaude48("claude-opus-4-7")); + assertFalse(AnthropicChatModelBuilder.isClaude48("claude-opus-4-6")); + assertFalse(AnthropicChatModelBuilder.isClaude48("claude-sonnet-4-5")); + assertFalse(AnthropicChatModelBuilder.isClaude48("claude-3-7-sonnet")); + // The "claude" prefix guard prevents non-Anthropic models from spuriously + // matching even if they contain "4-8" / "4.8" substrings. + assertFalse(AnthropicChatModelBuilder.isClaude48("gpt-4-8"), + "Non-Claude models must NOT match — claude prefix guard active"); + assertFalse(AnthropicChatModelBuilder.isClaude48("nemotron-4-8-instruct")); + } + + @Test + @DisplayName("isClaude48 null-safe") + void detect_nullSafe() { + assertFalse(AnthropicChatModelBuilder.isClaude48(null)); + assertFalse(AnthropicChatModelBuilder.isClaude48("")); + } + + @Test + @DisplayName("isClaude48 tolerates date-stamped variants") + void detect_dateStamped() { + assertTrue(AnthropicChatModelBuilder.isClaude48("claude-opus-4-8-20260601")); + assertTrue(AnthropicChatModelBuilder.isClaude48("claude-opus-4-8-fast-20260601")); + } + + @Test + @DisplayName("isClaude47OrLater unifies the 4.7 + 4.8 sampling-forbidden contract") + void claude47OrLater_unifiesGenerations() { + // 4.7 still matches via the legacy detector + assertTrue(AnthropicChatModelBuilder.isClaude47OrLater("claude-opus-4-7")); + assertTrue(AnthropicChatModelBuilder.isClaude47OrLater("anthropic/claude-opus-4.7")); + // 4.8 (regular + -fast) matches via the new detector + assertTrue(AnthropicChatModelBuilder.isClaude47OrLater("claude-opus-4-8")); + assertTrue(AnthropicChatModelBuilder.isClaude47OrLater("claude-opus-4-8-fast")); + assertTrue(AnthropicChatModelBuilder.isClaude47OrLater("anthropic/claude-opus-4.8-fast")); + // Older Claude generations fall through + assertFalse(AnthropicChatModelBuilder.isClaude47OrLater("claude-opus-4-6")); + assertFalse(AnthropicChatModelBuilder.isClaude47OrLater("claude-sonnet-4-5")); + assertFalse(AnthropicChatModelBuilder.isClaude47OrLater("claude-3-7-sonnet")); + // Null-safe + assertFalse(AnthropicChatModelBuilder.isClaude47OrLater(null)); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/llm/routing/ProviderRouterSelectPrimaryTest.java b/mateclaw-server/src/test/java/vip/mate/llm/routing/ProviderRouterSelectPrimaryTest.java new file mode 100644 index 00000000..f373ba81 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/llm/routing/ProviderRouterSelectPrimaryTest.java @@ -0,0 +1,214 @@ +package vip.mate.llm.routing; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import vip.mate.llm.model.ModelConfigEntity; +import vip.mate.llm.service.ModelCapabilityService; +import vip.mate.llm.service.ModelCapabilityService.Modality; +import vip.mate.llm.service.ModelConfigService; +import vip.mate.llm.service.ModelProviderService; +import vip.mate.skill.manifest.SkillManifest; +import vip.mate.skill.runtime.SkillRuntimeService; +import vip.mate.skill.runtime.model.ResolvedSkill; + +import java.util.EnumSet; +import java.util.List; +import java.util.Set; + +import static org.junit.jupiter.api.Assertions.*; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.*; + +@ExtendWith(MockitoExtension.class) +class ProviderRouterSelectPrimaryTest { + + @Mock private SkillRuntimeService skillRuntimeService; + @Mock private AgentBindingResolver bindingService; + @Mock private ModelCapabilityService capabilityService; + @Mock private ModelConfigService modelConfigService; + @Mock private ModelProviderService modelProviderService; + + @InjectMocks private ProviderRouter router; + + private static final Long AGENT_ID = 42L; + + // ---- helpers ---- + + private static ModelConfigEntity model(String provider, String name) { + ModelConfigEntity m = new ModelConfigEntity(); + m.setProvider(provider); + m.setModelName(name); + return m; + } + + private void stubNoCapabilities() { + when(bindingService.getBoundSkillIds(AGENT_ID)).thenReturn(Set.of()); + } + + /** + * Bind a single skill that declares the given {@code requires-model} + * tokens, so {@code aggregateModelNeeds} resolves a non-empty capability + * set and the capability-gated Pass 1 of {@code selectPrimary} runs. + */ + private void bindSkillRequiring(String... needs) { + when(bindingService.getBoundSkillIds(AGENT_ID)).thenReturn(Set.of(1L)); + SkillManifest manifest = mock(SkillManifest.class); + when(manifest.getRequiresModel()).thenReturn(List.of(needs)); + ResolvedSkill skill = mock(ResolvedSkill.class); + when(skill.getId()).thenReturn(1L); + when(skill.getManifest()).thenReturn(manifest); + when(skillRuntimeService.resolveAllSkillsStatus()).thenReturn(List.of(skill)); + } + + /** + * Stub a preferred provider as configured (has usable credentials) and + * resolving to the given primary chat model. Mirrors the runtime path + * {@code pickProviderDefault} takes: a provider must be configured before + * its primary chat model is considered. + */ + private void stubConfiguredProvider(String providerId, ModelConfigEntity primaryModel) { + when(modelProviderService.isProviderConfigured(providerId)).thenReturn(true); + when(modelConfigService.getPrimaryChatModelByProvider(providerId)).thenReturn(primaryModel); + } + + // ---- tests ---- + + @Test + @DisplayName("1. Preferred provider wins when no capability requirements") + void preferredWinsWithoutCapabilities() { + stubNoCapabilities(); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of("deepseek")); + stubConfiguredProvider("deepseek", model("deepseek", "deepseek-chat")); + + ModelConfigEntity global = model("openai", "gpt-4o"); + ModelConfigEntity result = router.selectPrimary(AGENT_ID, global); + + assertNotNull(result); + assertEquals("deepseek", result.getProvider()); + assertEquals("deepseek-chat", result.getModelName()); + } + + @Test + @DisplayName("2. Preferred provider satisfying the required capability wins in pass 1") + void preferredSatisfyingCapabilityWins() { + bindSkillRequiring("vision"); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of("deepseek")); + stubConfiguredProvider("deepseek", model("deepseek", "deepseek-vl")); + when(capabilityService.resolve(eq("deepseek-vl"), any())) + .thenReturn(EnumSet.of(Modality.VISION)); + + ModelConfigEntity global = model("openai", "gpt-4o"); + ModelConfigEntity result = router.selectPrimary(AGENT_ID, global); + + assertNotNull(result); + assertEquals("deepseek", result.getProvider()); + assertEquals("deepseek-vl", result.getModelName()); + } + + @Test + @DisplayName("3. No preferred providers → global default") + void noPreferredFallsBackToGlobal() { + stubNoCapabilities(); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of()); + + ModelConfigEntity global = model("openai", "gpt-4o"); + ModelConfigEntity result = router.selectPrimary(AGENT_ID, global); + + assertNotNull(result); + assertEquals("openai", result.getProvider()); + assertEquals("gpt-4o", result.getModelName()); + } + + @Test + @DisplayName("4. Unconfigured first preferred is skipped → second preferred wins") + void firstPreferredUnavailableSecondWins() { + stubNoCapabilities(); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of("deepseek", "dashscope")); + // deepseek has no usable credentials → must be skipped, not selected + // and then bounced to the global default. + when(modelProviderService.isProviderConfigured("deepseek")).thenReturn(false); + stubConfiguredProvider("dashscope", model("dashscope", "qwen-max")); + + ModelConfigEntity global = model("openai", "gpt-4o"); + ModelConfigEntity result = router.selectPrimary(AGENT_ID, global); + + assertNotNull(result); + assertEquals("dashscope", result.getProvider()); + assertEquals("qwen-max", result.getModelName()); + } + + @Test + @DisplayName("5. All preferred unconfigured → global default") + void allPreferredUnavailableFallsBackToGlobal() { + stubNoCapabilities(); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of("deepseek")); + when(modelProviderService.isProviderConfigured("deepseek")).thenReturn(false); + + ModelConfigEntity global = model("openai", "gpt-4o"); + ModelConfigEntity result = router.selectPrimary(AGENT_ID, global); + + assertNotNull(result); + assertEquals("openai", result.getProvider()); + } + + @Test + @DisplayName("6. No agent ID → returns global default") + void nullAgentIdReturnsGlobal() { + ModelConfigEntity global = model("openai", "gpt-4o"); + ModelConfigEntity result = router.selectPrimary(null, global); + assertSame(global, result); + } + + @Test + @DisplayName("7. Both preferred and global null → returns null") + void allNullReturnsNull() { + stubNoCapabilities(); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of()); + + ModelConfigEntity result = router.selectPrimary(AGENT_ID, null); + assertNull(result); + } + + @Test + @DisplayName("8. Preferred misses required capability but global satisfies → global wins in pass 1") + void preferredMissesCapabilityGlobalSatisfies() { + bindSkillRequiring("vision"); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of("deepseek")); + stubConfiguredProvider("deepseek", model("deepseek", "deepseek-chat")); + when(capabilityService.resolve(eq("deepseek-chat"), any())) + .thenReturn(EnumSet.noneOf(Modality.class)); + + ModelConfigEntity global = model("openai", "gpt-4o"); + when(capabilityService.resolve(eq("gpt-4o"), any())) + .thenReturn(EnumSet.of(Modality.VISION)); + + ModelConfigEntity result = router.selectPrimary(AGENT_ID, global); + + assertNotNull(result); + assertEquals("openai", result.getProvider()); + assertEquals("gpt-4o", result.getModelName()); + } + + @Test + @DisplayName("9. Configured preferred provider without a system-default model still resolves") + void preferredResolvesViaPerProviderFallback() { + stubNoCapabilities(); + when(bindingService.getPreferredProviderIds(AGENT_ID)).thenReturn(List.of("deepseek")); + // getPrimaryChatModelByProvider encapsulates the system-default → + // first-enabled-chat fallback, so a preferred provider that does not + // hold the single global default still contributes a primary model. + stubConfiguredProvider("deepseek", model("deepseek", "deepseek-chat")); + + ModelConfigEntity global = model("volcengine-plan", "doubao-seed"); + ModelConfigEntity result = router.selectPrimary(AGENT_ID, global); + + assertNotNull(result); + assertEquals("deepseek", result.getProvider()); + assertEquals("deepseek-chat", result.getModelName()); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleFlagGuardTest.java b/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleFlagGuardTest.java index df3a354d..b35e115f 100644 --- a/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleFlagGuardTest.java +++ b/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleFlagGuardTest.java @@ -56,7 +56,7 @@ class LifecycleFlagGuardTest { new ConversationCompletedEvent(1L, "conv-" + i, "hello", "reply", 5, "web")); } - verify(memoryManager, never()).prefetchAll(any(), any()); + verify(memoryManager, never()).prefetchAll(any(), any(), any()); verify(memoryManager, never()).syncAll(any(), any(), any(), any()); verify(memoryManager, never()).onSessionEnd(any(), any()); } @@ -68,11 +68,11 @@ class LifecycleFlagGuardTest { // But MemoryLifecycleEventListener guards onSessionEnd. props.setLifecycleMediatorEnabled(false); - when(memoryManager.prefetchAll(eq(1L), eq("q"))).thenReturn(""); + when(memoryManager.prefetchAll(eq(1L), eq("q"), any())).thenReturn(""); // Direct mediator call works (AgentService would not call this when flag is off) mediator.beforeLlmCall(new TurnContext(1L, "c1", "s1", 1, "q")); - verify(memoryManager, times(1)).prefetchAll(1L, "q"); + verify(memoryManager, times(1)).prefetchAll(eq(1L), eq("q"), any()); } // ==================== Flag ON ==================== @@ -81,13 +81,13 @@ class LifecycleFlagGuardTest { @DisplayName("Flag ON: beforeLlmCall invokes prefetchAll") void flagOn_prefetchAll() { props.setLifecycleMediatorEnabled(true); - when(memoryManager.prefetchAll(eq(1L), eq("hello"))).thenReturn(""); + when(memoryManager.prefetchAll(eq(1L), eq("hello"), any())).thenReturn(""); for (int i = 0; i < 10; i++) { mediator.beforeLlmCall(new TurnContext(1L, "c1", "s1", i, "hello")); } - verify(memoryManager, times(10)).prefetchAll(1L, "hello"); + verify(memoryManager, times(10)).prefetchAll(eq(1L), eq("hello"), any()); } @Test @@ -131,7 +131,7 @@ class LifecycleFlagGuardTest { @Test @DisplayName("Provider exception in prefetchAll degrades gracefully (returns empty)") void prefetchException_graceful() { - when(memoryManager.prefetchAll(any(), any())).thenThrow(new RuntimeException("boom")); + when(memoryManager.prefetchAll(any(), any(), any())).thenThrow(new RuntimeException("boom")); String result = mediator.beforeLlmCall(new TurnContext(1L, "c1", "s1", 1, "q")); diff --git a/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleRecallCountIT.java b/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleRecallCountIT.java index bb411525..62995d9d 100644 --- a/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleRecallCountIT.java +++ b/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/LifecycleRecallCountIT.java @@ -52,7 +52,8 @@ class LifecycleRecallCountIT { props = new MemoryProperties(); MemoryLifecycleMediator mediator = new MemoryLifecycleMediator(memoryManager, eventPublisher); agentService = new AgentService(agentMapper, agentGraphBuilder, - memoryRecallTracker, mediator, props, conversationMapper); + memoryRecallTracker, mediator, props, + new vip.mate.memory.identity.MemoryOwnerResolver(), conversationMapper); // Stub agent resolution (lenient for structural-only tests) AgentEntity entity = new AgentEntity(); @@ -76,7 +77,7 @@ class LifecycleRecallCountIT { verify(memoryRecallTracker, times(10)).trackRecalls(eq(1L), any()); // Mediator is not invoked when flag is off - verify(memoryManager, never()).prefetchAll(any(), any()); + verify(memoryManager, never()).prefetchAll(any(), any(), any()); verify(memoryManager, never()).syncAll(any(), any(), any(), any()); } @@ -84,7 +85,7 @@ class LifecycleRecallCountIT { @DisplayName("F4 regression: flag ON — trackRecalls still called exactly once per chat (not doubled)") void flagOn_trackRecallsStillOncePerChat() { props.setLifecycleMediatorEnabled(true); - when(memoryManager.prefetchAll(any(), any())).thenReturn(""); + when(memoryManager.prefetchAll(any(), any(), any())).thenReturn(""); for (int i = 0; i < 10; i++) { agentService.chat(1L, "msg-" + i, "conv-1"); @@ -94,7 +95,7 @@ class LifecycleRecallCountIT { verify(memoryRecallTracker, times(10)).trackRecalls(eq(1L), any()); // Mediator IS invoked - verify(memoryManager, times(10)).prefetchAll(eq(1L), any()); + verify(memoryManager, times(10)).prefetchAll(eq(1L), any(), any()); verify(memoryManager, times(10)).syncAll(eq(1L), eq("conv-1"), any(), any()); } @@ -109,7 +110,7 @@ class LifecycleRecallCountIT { // 5 rounds with flag ON props.setLifecycleMediatorEnabled(true); - when(memoryManager.prefetchAll(any(), any())).thenReturn(""); + when(memoryManager.prefetchAll(any(), any(), any())).thenReturn(""); for (int i = 0; i < 5; i++) { agentService.chat(1L, "on-" + i, "conv-1"); } @@ -118,7 +119,7 @@ class LifecycleRecallCountIT { verify(memoryRecallTracker, times(10)).trackRecalls(eq(1L), any()); // Mediator only called for the ON rounds - verify(memoryManager, times(5)).prefetchAll(eq(1L), any()); + verify(memoryManager, times(5)).prefetchAll(eq(1L), any(), any()); } @Test diff --git a/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/MemoryLifecycleMediatorTest.java b/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/MemoryLifecycleMediatorTest.java index db7a07c7..f74049f8 100644 --- a/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/MemoryLifecycleMediatorTest.java +++ b/mateclaw-server/src/test/java/vip/mate/memory/lifecycle/MemoryLifecycleMediatorTest.java @@ -41,14 +41,14 @@ class MemoryLifecycleMediatorTest { @Test @DisplayName("beforeLlmCall returns prefetchAll result and publishes TurnStartedEvent") void beforeLlmCall_normalPath() { - when(memoryManager.prefetchAll(eq(1L), eq("hello"))) + when(memoryManager.prefetchAll(eq(1L), eq("hello"), any())) .thenReturn("some context"); TurnContext ctx = new TurnContext(1L, "c1", "s1", 1, "hello"); String result = mediator.beforeLlmCall(ctx); assertEquals("some context", result); - verify(memoryManager).prefetchAll(1L, "hello"); + verify(memoryManager).prefetchAll(eq(1L), eq("hello"), any()); ArgumentCaptor eventCaptor = ArgumentCaptor.forClass(Object.class); verify(eventPublisher).publishEvent(eventCaptor.capture()); @@ -59,7 +59,7 @@ class MemoryLifecycleMediatorTest { @Test @DisplayName("beforeLlmCall returns empty string when prefetchAll returns empty") void beforeLlmCall_emptyPrefetch() { - when(memoryManager.prefetchAll(any(), any())).thenReturn(""); + when(memoryManager.prefetchAll(any(), any(), any())).thenReturn(""); String result = mediator.beforeLlmCall(new TurnContext(1L, "c1", "s1", 1, "q")); @@ -95,7 +95,7 @@ class MemoryLifecycleMediatorTest { @Test @DisplayName("beforeLlmCall degrades to empty string when prefetchAll throws") void beforeLlmCall_exceptionDegrades() { - when(memoryManager.prefetchAll(any(), any())) + when(memoryManager.prefetchAll(any(), any(), any())) .thenThrow(new RuntimeException("provider down")); String result = mediator.beforeLlmCall(new TurnContext(1L, "c1", "s1", 1, "q")); @@ -141,7 +141,7 @@ class MemoryLifecycleMediatorTest { @Test @DisplayName("Multiple sequential turns do not interfere (Mediator is stateless)") void multipleTurns_noInterference() { - when(memoryManager.prefetchAll(any(), any())).thenReturn(""); + when(memoryManager.prefetchAll(any(), any(), any())).thenReturn(""); for (int i = 0; i < 5; i++) { TurnContext ctx = new TurnContext(1L, "c1", "s1", i, "msg-" + i); @@ -149,7 +149,7 @@ class MemoryLifecycleMediatorTest { mediator.afterLlmCall(ctx, "reply-" + i); } - verify(memoryManager, times(5)).prefetchAll(eq(1L), any()); + verify(memoryManager, times(5)).prefetchAll(eq(1L), any(), any()); verify(memoryManager, times(5)).syncAll(eq(1L), eq("c1"), any(), any()); } } diff --git a/mateclaw-server/src/test/java/vip/mate/memory/service/MemorySummarizationStructuredRoutingTest.java b/mateclaw-server/src/test/java/vip/mate/memory/service/MemorySummarizationStructuredRoutingTest.java new file mode 100644 index 00000000..92714ce5 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/memory/service/MemorySummarizationStructuredRoutingTest.java @@ -0,0 +1,97 @@ +package vip.mate.memory.service; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import vip.mate.agent.AgentGraphBuilder; +import vip.mate.llm.service.ModelConfigService; +import vip.mate.memory.MemoryProperties; +import vip.mate.workspace.conversation.ConversationService; +import vip.mate.workspace.document.WorkspaceFileService; + +import java.lang.reflect.Method; + +import static org.mockito.ArgumentMatchers.*; +import static org.mockito.Mockito.*; + +/** + * The conversation summarizer routes typed facts it extracts into structured + * memory (the query-conditioned recall channel), so project/reference facts kept + * out of the always-on MEMORY.md still become recallable instead of being + * stranded in daily notes. Valid entries are written; malformed ones are skipped. + */ +class MemorySummarizationStructuredRoutingTest { + + private final ObjectMapper mapper = new ObjectMapper(); + + private MemorySummarizationService newService(StructuredMemoryService structured) { + return new MemorySummarizationService( + mock(ConversationService.class), + mock(WorkspaceFileService.class), + mock(ModelConfigService.class), + mock(AgentGraphBuilder.class), + mock(MemoryProperties.class), + mapper, + structured); + } + + private void invokeApply(MemorySummarizationService svc, long agentId, String entriesJson) throws Exception { + JsonNode node = mapper.readTree(entriesJson); + Method m = MemorySummarizationService.class + .getDeclaredMethod("applyStructuredEntries", Long.class, JsonNode.class); + m.setAccessible(true); + m.invoke(svc, agentId, node); + } + + @Test + @DisplayName("valid typed entries are routed to structured memory") + void routesValidEntries() throws Exception { + StructuredMemoryService structured = mock(StructuredMemoryService.class); + MemorySummarizationService svc = newService(structured); + + invokeApply(svc, 1000000001L, """ + [ + {"type": "project", "key": "project_codename", "content": "项目代号：云梯计划"}, + {"type": "user", "key": "preferred_output_format", "content": "偏好表格输出"} + ] + """); + + verify(structured).remember(1000000001L, "project", "project_codename", "项目代号：云梯计划", "auto-summary"); + verify(structured).remember(1000000001L, "user", "preferred_output_format", "偏好表格输出", "auto-summary"); + verifyNoMoreInteractions(structured); + } + + @Test + @DisplayName("malformed or unknown-type entries are skipped") + void skipsInvalidEntries() throws Exception { + StructuredMemoryService structured = mock(StructuredMemoryService.class); + MemorySummarizationService svc = newService(structured); + + invokeApply(svc, 1000000001L, """ + [ + {"type": "secret", "key": "k", "content": "bad type"}, + {"type": "project", "key": "", "content": "missing key"}, + {"type": "project", "key": "ok_key", "content": ""}, + {"type": "project", "key": "good", "content": "kept"} + ] + """); + + // Only the last, fully-valid entry is written. + verify(structured).remember(1000000001L, "project", "good", "kept", "auto-summary"); + verifyNoMoreInteractions(structured); + } + + @Test + @DisplayName("null / non-array structured_entries is a no-op") + void noopForNullOrNonArray() throws Exception { + StructuredMemoryService structured = mock(StructuredMemoryService.class); + MemorySummarizationService svc = newService(structured); + + invokeApply(svc, 1000000001L, "null"); + invokeApply(svc, 1000000001L, "\"not-an-array\""); + invokeApply(svc, 1000000001L, "[]"); + + verifyNoInteractions(structured); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/memory/service/StructuredMemoryPrefetchTest.java b/mateclaw-server/src/test/java/vip/mate/memory/service/StructuredMemoryPrefetchTest.java new file mode 100644 index 00000000..7992911a --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/memory/service/StructuredMemoryPrefetchTest.java @@ -0,0 +1,143 @@ +package vip.mate.memory.service; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.context.ApplicationEventPublisher; +import vip.mate.workspace.document.WorkspaceFileService; +import vip.mate.workspace.document.model.WorkspaceFileEntity; + +import static org.junit.jupiter.api.Assertions.*; +import static org.mockito.Mockito.*; + +/** + * Verifies the structured-memory split between always-on system prompt injection + * (stable types) and query-conditioned prefetch (growing/specific types), plus + * the relevance scoring that lets a natural-language question surface the right + * stored fact instead of letting it lose salience in an always-on dump. + */ +class StructuredMemoryPrefetchTest { + + private static final long AGENT_ID = 1000000001L; + + private StructuredMemoryService newService(String projectMd, String userMd) { + WorkspaceFileService files = mock(WorkspaceFileService.class); + when(files.getFile(eq(AGENT_ID), anyString())).thenReturn(null); + if (projectMd != null) { + when(files.getFile(AGENT_ID, "structured/project.md")).thenReturn(fileWith(projectMd)); + } + if (userMd != null) { + when(files.getFile(AGENT_ID, "structured/user.md")).thenReturn(fileWith(userMd)); + } + return new StructuredMemoryService(files, mock(ApplicationEventPublisher.class)); + } + + private WorkspaceFileEntity fileWith(String content) { + WorkspaceFileEntity e = new WorkspaceFileEntity(); + e.setContent(content); + return e; + } + + @Test + @DisplayName("system prompt block excludes growing project entries") + void systemPromptBlockExcludesProject() { + StructuredMemoryService svc = newService( + "## project_codename\n用户的项目代号叫\"天枢\"。\n> Source: agent | Updated: 2026-05-29", + "## reply_style\n偏好简洁直接的回答风格。\n> Source: agent | Updated: 2026-05-29"); + + String block = svc.buildMemoryBlock(AGENT_ID); + + // Stable user profile stays in the system prompt... + assertTrue(block.contains("reply_style"), "stable user entry should be in system prompt"); + // ...but specific project facts must not be dumped always-on. + assertFalse(block.contains("天枢"), "project codename must not be in system prompt block"); + } + + @Test + @DisplayName("prefetch surfaces the project codename for a Chinese question about it") + void prefetchSurfacesCodename() { + StructuredMemoryService svc = newService( + "## project_codename\n用户的项目代号叫\"天枢\"。\n> Source: agent | Updated: 2026-05-29\n\n" + + "## project_tech_stack\nRust + Postgres\n> Source: agent | Updated: 2026-05-29", + null); + + String block = svc.buildPrefetchBlock(AGENT_ID, + "我之前告诉过你我的项目代号,你还记得吗?"); + + assertTrue(block.contains("天枢"), "codename should be recalled by a codename question"); + } + + @Test + @DisplayName("prefetch surfaces tech stack via cross-language alias (技术栈 -> tech_stack)") + void prefetchSurfacesTechStackViaAlias() { + StructuredMemoryService svc = newService( + "## project_tech_stack\nRust + Postgres\n> Source: agent | Updated: 2026-05-29", + null); + + String block = svc.buildPrefetchBlock(AGENT_ID, "我的技术栈是什么?"); + + assertNotNull(block); + assertTrue(block.contains("Rust") && block.contains("Postgres"), + "tech stack should be recalled even though the key is English and the question is Chinese"); + } + + @Test + @DisplayName("prefetch orders conflicting entries newest-first and annotates the update date") + void prefetchOrdersByRecency() { + StructuredMemoryService svc = newService( + "## project_old_codename\n旧项目代号叫\"天枢\"。\n> Source: agent | Updated: 2026-05-01\n\n" + + "## project_new_codename\n新项目代号叫\"云梯计划\"。\n> Source: agent | Updated: 2026-05-29", + null); + + String block = svc.buildPrefetchBlock(AGENT_ID, "我的项目代号是什么?"); + + // Both surface, but the most recently updated one ranks first... + int newIdx = block.indexOf("云梯计划"); + int oldIdx = block.indexOf("天枢"); + assertTrue(newIdx >= 0 && oldIdx >= 0, "both conflicting entries should be recalled"); + assertTrue(newIdx < oldIdx, "the most recently updated entry should rank first"); + // ...and the update date is exposed so the model can resolve the conflict. + assertTrue(block.contains("updated 2026-05-29"), "recency hint should be present"); + } + + @Test + @DisplayName("prefetch marks the block when the user's own project is recalled (project type)") + void prefetchMarksProjectRecall() { + StructuredMemoryService svc = newService( + "## project_codename\n用户的项目代号叫\"天枢\"。\n> Source: agent | Updated: 2026-05-29", + null); + + String block = svc.buildPrefetchBlock(AGENT_ID, "我的项目代号是什么?"); + + assertTrue(block.contains(StructuredMemoryService.PROJECT_RECALLED_MARKER), + "a project-type recall should carry the marker so wiki injection can be suppressed"); + } + + @Test + @DisplayName("prefetch does NOT mark the block for reference-only recall") + void prefetchNoMarkerForReferenceOnly() { + // Only a reference-type file is present; the project file is absent. + WorkspaceFileService files = mock(WorkspaceFileService.class); + when(files.getFile(eq(AGENT_ID), anyString())).thenReturn(null); + WorkspaceFileEntity ref = new WorkspaceFileEntity(); + ref.setContent("## api_endpoint\n参考:订单查询接口 /api/orders。\n> Source: agent | Updated: 2026-05-29"); + when(files.getFile(AGENT_ID, "structured/reference.md")).thenReturn(ref); + StructuredMemoryService svc = new StructuredMemoryService(files, mock(ApplicationEventPublisher.class)); + + String block = svc.buildPrefetchBlock(AGENT_ID, "订单查询接口参考是什么?"); + + assertFalse(block.contains(StructuredMemoryService.PROJECT_RECALLED_MARKER), + "reference-only recall must not claim a project so wiki context stays available"); + } + + @Test + @DisplayName("prefetch returns empty for an unrelated question") + void prefetchEmptyForUnrelatedQuery() { + StructuredMemoryService svc = newService( + "## project_codename\n用户的项目代号叫\"天枢\"。\n> Source: agent | Updated: 2026-05-29", + null); + + assertEquals("", svc.buildPrefetchBlock(AGENT_ID, "今天天气怎么样?")); + assertEquals("", svc.buildPrefetchBlock(AGENT_ID, "")); + assertEquals("", svc.buildPrefetchBlock(AGENT_ID, null)); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/tool/builtin/GoalManagementToolTest.java b/mateclaw-server/src/test/java/vip/mate/tool/builtin/GoalManagementToolTest.java index 800ab397..d98653d6 100644 --- a/mateclaw-server/src/test/java/vip/mate/tool/builtin/GoalManagementToolTest.java +++ b/mateclaw-server/src/test/java/vip/mate/tool/builtin/GoalManagementToolTest.java @@ -75,7 +75,7 @@ class GoalManagementToolTest { @Test void setGoal_disabledFlag_returnsError() { properties.setEnabled(false); - String result = tool.setGoal("title", null, null, null, null, + String result = tool.setGoal("title", null, null, null, null, null, ctxWith("conv-1", 10L, "alice")); assertTrue(result.contains("disabled")); verify(goalService, never()).create(any(), anyString()); @@ -83,7 +83,7 @@ class GoalManagementToolTest { @Test void setGoal_blankTitle_returnsError() { - String result = tool.setGoal(" ", null, null, null, null, + String result = tool.setGoal(" ", null, null, null, null, null, ctxWith("conv-1", 10L, "alice")); assertTrue(result.contains("title is required")); } @@ -95,7 +95,7 @@ class GoalManagementToolTest { String result = tool.setGoal("ship the blog", "deploy to fly.io", "tests pass + deployed", - 15, true, + 15, true, null, ctxWith("conv-1", 10L, "alice")); assertTrue(result.contains("\"goalId\":\"123\"")); assertTrue(result.contains("\"status\":\"active\"")); @@ -103,7 +103,7 @@ class GoalManagementToolTest { @Test void setGoal_missingConversationContext_returnsError() { - String result = tool.setGoal("title", null, null, null, null, null); + String result = tool.setGoal("title", null, null, null, null, null, null); assertTrue(result.contains("requires a bound conversation")); } @@ -151,6 +151,7 @@ class GoalManagementToolTest { GoalEntity completed = goal(GoalStatus.COMPLETED); when(goalService.markCompleted(eq(123L), any(GoalEvaluationResult.class))) .thenReturn(completed); + when(goalService.toResponse(any())).thenReturn(new vip.mate.goal.model.GoalResponse()); String result = tool.completeGoal(ctxWith("conv-1", 10L, "alice")); assertTrue(result.contains("\"status\":\"completed\"")); } diff --git a/mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCachePersistenceTest.java b/mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCachePersistenceTest.java new file mode 100644 index 00000000..f929f1d9 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCachePersistenceTest.java @@ -0,0 +1,83 @@ +package vip.mate.tool.document; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +import java.nio.charset.StandardCharsets; +import java.nio.file.Path; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * Pin the persistence contract that keeps download links durable: bytes are + * written to disk so a link still resolves after the in-memory entry is gone + * or the JVM has restarted. A regression here reintroduces the + * "File not found or expired" page that a user hits minutes after generating + * a document. + */ +class GeneratedFileCachePersistenceTest { + + @Test + @DisplayName("a link survives a 'restart' — a fresh cache over the same dir still serves it") + void survivesRestart(@TempDir Path dir) { + GeneratedFileCache first = new GeneratedFileCache(dir); + byte[] bytes = "report-body".getBytes(StandardCharsets.UTF_8); + String id = first.put(bytes, "季度报表.docx", + "application/vnd.openxmlformats-officedocument.wordprocessingml.document"); + + // Simulate a JVM restart: a brand-new instance with an empty memory map, + // pointing at the same storage directory. + GeneratedFileCache afterRestart = new GeneratedFileCache(dir); + GeneratedFileCache.Entry entry = afterRestart.get(id).orElse(null); + + assertNotNull(entry, "persisted entry must be reloaded from disk after restart"); + assertArrayEquals(bytes, entry.bytes(), "reloaded bytes must match the original"); + assertEquals("季度报表.docx", entry.filename(), "unicode filename must round-trip"); + assertEquals("application/vnd.openxmlformats-officedocument.wordprocessingml.document", + entry.mimeType()); + } + + @Test + @DisplayName("unknown id returns empty") + void unknownIdEmpty(@TempDir Path dir) { + GeneratedFileCache cache = new GeneratedFileCache(dir); + assertTrue(cache.get("00000000-0000-0000-0000-000000000000").isEmpty()); + } + + @Test + @DisplayName("malformed / path-traversal ids are rejected without touching disk") + void traversalRejected(@TempDir Path dir) { + GeneratedFileCache cache = new GeneratedFileCache(dir); + assertTrue(cache.get("../secret").isEmpty()); + assertTrue(cache.get("a/b").isEmpty()); + assertTrue(cache.get("").isEmpty()); + assertTrue(cache.get(null).isEmpty()); + } + + @Test + @DisplayName("memory LRU eviction never loses downloadability — old ids reload from disk") + void lruEvictionFallsBackToDisk(@TempDir Path dir) { + GeneratedFileCache cache = new GeneratedFileCache(dir); + // Far exceed the in-memory cap so the first id is evicted from memory. + String firstId = cache.put("first".getBytes(StandardCharsets.UTF_8), "first.txt", "text/plain"); + for (int i = 0; i < 400; i++) { + cache.put(("f" + i).getBytes(StandardCharsets.UTF_8), "f" + i + ".txt", "text/plain"); + } + GeneratedFileCache.Entry entry = cache.get(firstId).orElse(null); + assertNotNull(entry, "an id evicted from the memory cache must still resolve from disk"); + assertArrayEquals("first".getBytes(StandardCharsets.UTF_8), entry.bytes()); + } + + @Test + @DisplayName("scrub treats a persisted-but-evicted id as live (reloads from disk)") + void scrubReloadsPersisted(@TempDir Path dir) { + GeneratedFileCache first = new GeneratedFileCache(dir); + String id = first.put("x".getBytes(StandardCharsets.UTF_8), "a.pdf", "application/pdf"); + + GeneratedFileCache afterRestart = new GeneratedFileCache(dir); + String text = "下载: /api/v1/files/generated/" + id; + assertEquals(text, afterRestart.scrubMissingReferences(text), + "a still-persisted link must not be scrubbed as missing after restart"); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCacheScrubTest.java b/mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCacheScrubTest.java index 0aac0356..330622d3 100644 --- a/mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCacheScrubTest.java +++ b/mateclaw-server/src/test/java/vip/mate/tool/document/GeneratedFileCacheScrubTest.java @@ -3,6 +3,9 @@ package vip.mate.tool.document; import org.junit.jupiter.api.BeforeEach; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; + +import java.nio.file.Path; import static org.junit.jupiter.api.Assertions.*; @@ -21,8 +24,9 @@ class GeneratedFileCacheScrubTest { private GeneratedFileCache cache; @BeforeEach - void setUp() { - cache = new GeneratedFileCache(); + void setUp(@TempDir Path tempDir) { + // Hermetic storage so put() does not litter the real data/ dir. + cache = new GeneratedFileCache(tempDir); } @Test diff --git a/mateclaw-server/src/test/java/vip/mate/tool/guard/WorkspacePathGuardShellTest.java b/mateclaw-server/src/test/java/vip/mate/tool/guard/WorkspacePathGuardShellTest.java new file mode 100644 index 00000000..218d9018 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/tool/guard/WorkspacePathGuardShellTest.java @@ -0,0 +1,318 @@ +package vip.mate.tool.guard; + +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.DisabledOnOs; +import org.junit.jupiter.api.condition.OS; +import vip.mate.tool.builtin.ToolExecutionContext; + +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; +import static org.junit.jupiter.api.Assertions.assertThrows; + +/** + * Exercises {@link WorkspacePathGuard#validateShellCommand(String)} — the + * static command-string scan that backstops {@code ShellExecuteTool} so an + * absolute-path reference in the shell command cannot reach outside the + * configured workspace boundary, even though the shell process itself has + * full filesystem permissions. + * + *

    The boundary is read via {@link ToolExecutionContext#workspaceBasePath()}. + */ +@DisabledOnOs(OS.WINDOWS) // POSIX-style absolute paths in these cases +class WorkspacePathGuardShellTest { + + private static final String WORKSPACE = "/tmp/ws-guard-shell-test"; + private static final String SKILL_ROOT = "/tmp/ws-guard-skill-root"; + + @BeforeEach + void setup() { + ToolExecutionContext.set("conv-test", "test-user", WORKSPACE); + } + + @AfterEach + void teardown() { + ToolExecutionContext.clear(); + WorkspacePathGuard.setSkillRoot(null); + } + + // ==================== No-op when sandbox absent ==================== + + @Test + @DisplayName("No workspace configured → all commands pass") + void noWorkspace_noop() { + ToolExecutionContext.clear(); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand("cat /etc/passwd")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand("rm -rf /")); + } + + @Test + @DisplayName("Null or empty command → no-op") + void nullOrEmpty_noop() { + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand(null)); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand("")); + } + + // ==================== In-boundary commands pass ==================== + + @Test + @DisplayName("Relative paths and in-workspace absolute paths pass") + void inBoundary_pass() { + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand("ls -la")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand("cat foo.txt")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand("cat subdir/bar.txt")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "cat " + WORKSPACE + "/foo.txt")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "cd " + WORKSPACE + "/subdir && ls")); + } + + @Test + @DisplayName("URLs are not mistaken for filesystem paths") + void urls_pass() { + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "curl -s https://example.com/api/data")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "wget -O out.txt http://host:8080/path/to/file")); + } + + // ==================== Out-of-boundary absolute paths blocked ==================== + + @Test + @DisplayName("Absolute path outside workspace → rejected") + void absoluteOutside_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat /etc/passwd")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("head -3 /Users/someone/code/secret.md")); + } + + @Test + @DisplayName("Output redirection to outside path → rejected") + void redirection_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("echo evil > /tmp/leak.txt")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("ls >> /var/log/sneak.log")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("grep foo < /etc/hosts")); + } + + @Test + @DisplayName("cd / pushd to outside path → rejected") + void cdOutside_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cd /etc && ls")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("pushd /var/spool")); + } + + @Test + @DisplayName("ln -s to an outside target → rejected") + void symlinkCreate_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("ln -sf /etc/passwd alias")); + } + + @Test + @DisplayName("Pipe with outside path on either side → rejected") + void pipeOutside_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat /etc/passwd | grep root")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("env | tee /tmp/dump.txt")); + } + + @Test + @DisplayName("Quoted absolute path → rejected") + void quotedAbsolute_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat \"/etc/passwd\"")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat '/etc/passwd'")); + } + + @Test + @DisplayName("Command substitution $(...) with outside path → rejected") + void commandSubstOutside_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("echo $(cat /etc/passwd)")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("X=`head /etc/hostname`; echo $X")); + } + + // ==================== Tilde + env-var rejection ==================== + + @Test + @DisplayName("Tilde expansion → rejected") + void tilde_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat ~/.zshrc")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cd ~ && ls")); + } + + @Test + @DisplayName("$HOME / ${HOME} / $TMPDIR / $PATH → rejected") + void envVarOutside_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat $HOME/.zshrc")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("ls ${HOME}/Documents")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("touch $TMPDIR/leak")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("echo bad > $PATH/evil")); + } + + @Test + @DisplayName("Other env vars not on the deny list are allowed") + void unrelatedEnvVar_pass() { + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("echo $LANG")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("printf '%s\\n' \"$MY_FLAG\"")); + } + + // ==================== Device-node allowlist ==================== + + @Test + @DisplayName("/dev/null and other standard device nodes are allowed") + void deviceNodes_pass() { + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("find . -name '*.md' 2>/dev/null")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("ls -la > /dev/null")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("cat /dev/urandom | head -c 16")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("dd if=/dev/zero of=zeros.bin bs=1024 count=1")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("read line < /dev/stdin")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("echo hi > /dev/stderr")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("tty < /dev/tty")); + } + + @Test + @DisplayName("/dev/fd/N (process substitution) is allowed") + void devFd_pass() { + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("diff <(sort file_a.txt) <(sort file_b.txt)")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("cat /dev/fd/0")); + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("read line < /dev/fd/3")); + } + + // ==================== Relative parent-directory traversal ==================== + + @Test + @DisplayName("Bare `cd ..` → rejected") + void cdDotDot_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cd .. && ls")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cd ..")); + } + + @Test + @DisplayName("Relative parent traversal `../foo` → rejected") + void relativeParentTraversal_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat ../mateclaw/CLAUDE.md")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("head -3 ../README.md")); + } + + @Test + @DisplayName("Symlink creation with relative outside-pointing target → rejected") + void relativeSymlinkEscape_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("ln -sf ../mateclaw breakout")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("ln -s ../../etc shortcut")); + } + + @Test + @DisplayName("Deeper relative traversal `foo/../../bar` → rejected") + void deepRelativeTraversal_blocked() { + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat subdir/../../other/file.txt")); + } + + @Test + @DisplayName("In-workspace `..` traversal that normalizes back inside → allowed") + void inWorkspaceTraversal_pass() { + // subdir/../sibling → workspace/sibling, still inside. + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("cat subdir/../sibling.txt")); + // ./.. is at workspace root after normalize — still inside? No: ./.. is parent of cwd. + // We do want to reject that, which the regex will catch as escape. + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("ls foo/..")); // resolves to workspace root + } + + @Test + @DisplayName("Identifier with double-dot but no slash (e.g. `abc..xyz`) is not a path → allowed") + void doubleDotInIdentifier_pass() { + // "..foo" / "abc..xyz" should not be confused with parent traversal. + // These appear in version strings, env var values, etc. + assertDoesNotThrow(() -> + WorkspacePathGuard.validateShellCommand("echo version=1.2..3")); + } + + // ==================== Shared skill root allowance ==================== + + @Test + @DisplayName("Skill root is trusted in addition to the workspace") + void skillRoot_pass() { + WorkspacePathGuard.setSkillRoot(SKILL_ROOT); + // Reading and running a shared skill's files from a workspace elsewhere. + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "cat " + SKILL_ROOT + "/zclt-toolkit/SKILL.md")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "bash " + SKILL_ROOT + "/zclt-toolkit/scripts/run.sh")); + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "cd " + SKILL_ROOT + "/zclt-toolkit && ls")); + // The workspace itself still passes. + assertDoesNotThrow(() -> WorkspacePathGuard.validateShellCommand( + "cat " + WORKSPACE + "/foo.txt")); + } + + @Test + @DisplayName("Without a skill root, the same skill path is still blocked") + void skillRoot_unset_blocked() { + // No skill root registered → skill path is just another outside path. + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat " + SKILL_ROOT + "/zclt-toolkit/SKILL.md")); + } + + @Test + @DisplayName("A skill root does not widen the boundary to unrelated outside paths") + void skillRoot_doesNotWidenOtherPaths() { + WorkspacePathGuard.setSkillRoot(SKILL_ROOT); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat /etc/passwd")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("echo evil > /tmp/leak.txt")); + } + + // ==================== Device-node negative cases ==================== + + @Test + @DisplayName("Non-allowlisted /dev/* paths still rejected") + void devOther_blocked() { + // Block-device-like paths must not be allowed by the allowlist. + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("dd if=/dev/disk0 of=image.bin")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat /dev/loop0")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("ls /dev/null/sneak")); + assertThrows(IllegalArgumentException.class, () -> + WorkspacePathGuard.validateShellCommand("cat /dev/fd/notanumber")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/WikiDomainIntegrationE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/WikiDomainIntegrationE2ETest.java new file mode 100644 index 00000000..9c988c58 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/WikiDomainIntegrationE2ETest.java @@ -0,0 +1,153 @@ +package vip.mate.wiki; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiAgentPageTypePermissionEntity; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; +import vip.mate.wiki.pipeline.WikiPipelineService; +import vip.mate.wiki.pipeline.WikiPipelineTriggerService; +import vip.mate.wiki.pipeline.WikiStepContext; +import vip.mate.wiki.pipeline.WikiStepExecutor; +import vip.mate.wiki.profile.WikiPageTypeProfile; +import vip.mate.wiki.profile.WikiPageTypeProfileService; +import vip.mate.wiki.repository.WikiAgentPageTypePermissionMapper; +import vip.mate.wiki.repository.WikiPageMapper; +import vip.mate.wiki.repository.WikiPipelineDefinitionMapper; +import vip.mate.wiki.repository.WikiPipelineRunMapper; +import vip.mate.wiki.repository.WikiPipelineStepRunMapper; +import vip.mate.wiki.service.WikiDependencyService; +import vip.mate.wiki.service.WikiPageService; +import vip.mate.wiki.service.WikiPageTypePermissionService; + +import java.time.LocalDateTime; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Cross-RFC end-to-end scenario exercised against H2 with no external model: + * a KB defines a custom pageType profile (layered fact/experience), pages are + * created, an agent's pageType read permission filters them, an experience + * page depends on a fact page and goes stale when the fact changes, and a + * count-threshold pipeline fires once the fact pages accumulate. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiDomainIntegrationE2ETest { + + private static final WikiStepExecutor NOOP = new WikiStepExecutor() { + public String type() { return "noop"; } + public String execute(WikiStepContext c) { return "ok"; } + }; + + @Autowired private WikiPageTypeProfileService profileService; + @Autowired private WikiPageService pageService; + @Autowired private WikiPageTypePermissionService permissionService; + @Autowired private WikiAgentPageTypePermissionMapper permissionMapper; + @Autowired private WikiDependencyService dependencyService; + @Autowired private WikiPipelineDefinitionMapper definitionMapper; + @Autowired private WikiPipelineRunMapper runMapper; + @Autowired private WikiPipelineStepRunMapper stepRunMapper; + @Autowired private WikiPageMapper pageMapper; + @Autowired private ObjectMapper objectMapper; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + @Test + void fullDomainFlow() { + long kb = SEQ.incrementAndGet(); + long agent = SEQ.incrementAndGet(); + + // --- RFC-56: a custom KB profile with layered page types --- + profileService.saveProfile(kb, "liquidity", + "{\"version\":1,\"pageTypes\":{" + + "\"episode\":{\"label\":\"Episode\",\"layer\":\"fact\"}," + + "\"pattern\":{\"label\":\"Pattern\",\"layer\":\"experience\"}}}"); + WikiPageTypeProfile profile = profileService.resolveProfile(kb); + assertTrue(profile.hasPageType("episode")); + assertTrue(profile.hasPageType("pattern")); + + // --- create pages: two fact episodes + one experience pattern --- + WikiPageEntity ep1 = createPage(kb, "ep1-" + kb, "episode", "fact"); + WikiPageEntity ep2 = createPage(kb, "ep2-" + kb, "episode", "fact"); + WikiPageEntity pat = createPage(kb, "pat-" + kb, "pattern", "experience"); + + // --- RFC-58: agent may read episode (fact) but not pattern --- + permissionMapper.insert(perm(agent, kb, "episode", 1)); + permissionMapper.insert(perm(agent, kb, "pattern", 0)); + WikiPageTypePermissionService.Access access = permissionService.resolve(agent, kb); + assertTrue(access.canRead("episode")); + assertFalse(access.canRead("pattern")); + + // --- RFC-57: pattern depends on the episodes; updating one marks it stale --- + List rejected = dependencyService.setDependencies(kb, pat.getId(), + List.of(ep1.getId(), ep2.getId())); + assertTrue(rejected.isEmpty(), () -> "unexpected rejections: " + rejected); + int marked = dependencyService.markDependentsStale(kb, ep1.getId(), "episode revised"); + assertEquals(1, marked); + assertEquals(1, pageService.getBySlug(kb, "pat-" + kb).getStale()); + + // --- RFC-60: a pipeline fires once 2 episodes exist (threshold 2) --- + long defId = seedPipeline(kb); + WikiPipelineService pipelineService = new WikiPipelineService( + runMapper, stepRunMapper, objectMapper, List.of(NOOP)); + WikiPipelineTriggerService trigger = new WikiPipelineTriggerService( + definitionMapper, pipelineService, pageMapper, objectMapper); + + int started = trigger.onPageTypeCount(kb, "episode"); + assertEquals(1, started, "pipeline should fire once the episode count reaches the threshold"); + long runs = runMapper.selectCount(com.baomidou.mybatisplus.core.toolkit.Wrappers + .lambdaQuery() + .eq(vip.mate.wiki.model.WikiPipelineRunEntity::getDefinitionId, defId)); + assertEquals(1, runs); + + // Re-evaluating in the same bucket does not double-fire (idempotent). + assertEquals(0, trigger.onPageTypeCount(kb, "episode")); + } + + private WikiPageEntity createPage(long kb, String slug, String pageType, String layer) { + WikiPageEntity p = pageService.createPage(kb, slug, slug, "body", "s", "[1]", pageType); + pageService.setLayerAndDependencies(p.getId(), layer, null); + return pageService.getBySlug(kb, slug); + } + + private WikiAgentPageTypePermissionEntity perm(long agent, long kb, String type, int canRead) { + WikiAgentPageTypePermissionEntity e = new WikiAgentPageTypePermissionEntity(); + e.setAgentId(agent); + e.setKbId(kb); + e.setPageType(type); + e.setCanRead(canRead); + e.setCanCreate(0); + e.setCanUpdate(0); + e.setCanDelete(0); + e.setWritePolicy("deny"); + return e; + } + + private long seedPipeline(long kb) { + WikiPipelineDefinitionEntity d = new WikiPipelineDefinitionEntity(); + d.setKbId(kb); + d.setName("episode-to-pattern-" + SEQ.incrementAndGet()); + d.setOwnerAgentId(99L); + d.setTriggerType("page_type_count"); + d.setTriggerConfigJson("{\"page_type\":\"episode\",\"threshold\":2}"); + d.setStepsJson("[{\"id\":\"s\",\"executor\":\"noop\"}]"); + d.setEnabled(1); + d.setCreateTime(LocalDateTime.now()); + d.setUpdateTime(LocalDateTime.now()); + definitionMapper.insert(d); + return d.getId(); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiLlmStepExecutorTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiLlmStepExecutorTest.java new file mode 100644 index 00000000..1c09da30 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiLlmStepExecutorTest.java @@ -0,0 +1,56 @@ +package vip.mate.wiki.pipeline; + +import org.junit.jupiter.api.Test; +import org.springframework.ai.chat.messages.AssistantMessage; +import org.springframework.ai.chat.model.ChatModel; +import org.springframework.ai.chat.model.ChatResponse; +import org.springframework.ai.chat.model.Generation; +import org.springframework.ai.chat.prompt.Prompt; +import vip.mate.wiki.job.WikiModelRoutingService; + +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link WikiLlmStepExecutor}: it builds a prompt from the step + * config and previous output, calls the routed model, and returns its text. + * Model routing is mocked to return a fixed-response ChatModel. + */ +class WikiLlmStepExecutorTest { + + private WikiLlmStepExecutor executor(String modelReply) { + WikiModelRoutingService routing = mock(WikiModelRoutingService.class); + ChatModel chat = prompt -> new ChatResponse(List.of(new Generation(new AssistantMessage(modelReply)))); + when(routing.buildChatModel(any())).thenReturn(chat); + return new WikiLlmStepExecutor(routing); + } + + private WikiStepContext ctx(Map config, String previousOutput) { + return new WikiStepContext(1L, 42L, "s1", config, previousOutput); + } + + @Test + void callsModelAndReturnsText() throws Exception { + WikiLlmStepExecutor e = executor("pattern summary"); + String out = e.execute(ctx(Map.of("prompt", "Summarize the episodes"), "ep1, ep2")); + assertEquals("pattern summary", out); + } + + @Test + void missingPrompt_throws() { + WikiLlmStepExecutor e = executor("x"); + assertThrows(IllegalArgumentException.class, () -> e.execute(ctx(Map.of(), "prior"))); + } + + @Test + void typeIsLlm() { + assertTrue("llm".equals(executor("x").type())); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionServiceE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionServiceE2ETest.java new file mode 100644 index 00000000..6032b517 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineDefinitionServiceE2ETest.java @@ -0,0 +1,103 @@ +package vip.mate.wiki.pipeline; + +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * E2E for {@link WikiPipelineDefinitionService}: YAML/JSON parsing, structural + * validation, and upsert/list/delete against H2. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPipelineDefinitionServiceE2ETest { + + @Autowired + private WikiPipelineDefinitionService service; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + private static final String YAML = """ + name: episode-to-pattern + owner_agent: 2055137662148763649 + trigger: + type: page_type_count + page_type: episode + threshold: 20 + dedup_window_seconds: 3600 + steps: + - id: summarize + executor: llm + prompt: pattern-analysis + - id: enrich + executor: skill + skill: wiki-link-enrich + """; + + @Test + void parsesYamlAndUpserts() { + long kb = SEQ.incrementAndGet(); + WikiPipelineDefinitionEntity def = service.saveFromConfig(kb, YAML, true); + assertNotNull(def.getId()); + assertEquals("episode-to-pattern", def.getName()); + assertEquals(2055137662148763649L, def.getOwnerAgentId()); + assertEquals("page_type_count", def.getTriggerType()); + assertEquals(3600, def.getDedupWindowSeconds()); + assertTrue(def.getTriggerConfigJson().contains("episode")); + assertTrue(def.getStepsJson().contains("wiki-link-enrich")); + + // upsert: same name → update in place, not a second row + service.saveFromConfig(kb, YAML.replace("threshold: 20", "threshold: 40"), true); + List all = service.list(kb); + assertEquals(1, all.size()); + assertTrue(all.get(0).getTriggerConfigJson().contains("40")); + + service.delete(def.getId()); + assertNull(service.get(def.getId())); + } + + @Test + void parsesJson() { + long kb = SEQ.incrementAndGet(); + String json = "{\"name\":\"p\",\"owner_agent\":42,\"trigger\":{\"type\":\"page_created\"}," + + "\"steps\":[{\"id\":\"s\",\"executor\":\"llm\",\"prompt\":\"x\"}]}"; + WikiPipelineDefinitionEntity def = service.saveFromConfig(kb, json, false); + assertEquals("page_created", def.getTriggerType()); + } + + @Test + void validation_reportsIssues() { + assertTrue(service.validateConfig(YAML, true).isEmpty()); + + // missing name + unknown trigger + python step + String bad = """ + owner_agent: 1 + trigger: + type: nope + steps: + - id: x + executor: python + """; + List issues = service.validateConfig(bad, true); + assertFalse(issues.isEmpty()); + assertTrue(issues.stream().anyMatch(s -> s.contains("name"))); + assertTrue(issues.stream().anyMatch(s -> s.contains("trigger type"))); + assertTrue(issues.stream().anyMatch(s -> s.contains("python"))); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineServiceE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineServiceE2ETest.java new file mode 100644 index 00000000..a14567b9 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineServiceE2ETest.java @@ -0,0 +1,134 @@ +package vip.mate.wiki.pipeline; + +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; +import vip.mate.wiki.model.WikiPipelineStepRunEntity; +import vip.mate.wiki.repository.WikiPipelineRunMapper; +import vip.mate.wiki.repository.WikiPipelineStepRunMapper; + +import java.time.LocalDateTime; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Orchestration test for {@link WikiPipelineService} against H2 with stub + * executors: success path records succeeded run + steps, a failing step fails + * the run and stops, and a duplicate trigger envelope is skipped. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPipelineServiceE2ETest { + + // Stub executors: 'echo' returns a marker; 'boom' always throws. Built + // here (not via @TestConfiguration) so the test uses the shared default + // context and does not fork a separate datasource that @DirtiesContext + // would close out from under sibling tests. + private static final WikiStepExecutor ECHO = new WikiStepExecutor() { + public String type() { return "echo"; } + public String execute(WikiStepContext c) { + return "echo:" + c.stepId() + ":" + (c.previousOutput() == null ? "" : c.previousOutput()); + } + }; + private static final WikiStepExecutor BOOM = new WikiStepExecutor() { + public String type() { return "boom"; } + public String execute(WikiStepContext c) { throw new RuntimeException("kaboom"); } + }; + + @Autowired + private WikiPipelineRunMapper runMapper; + @Autowired + private WikiPipelineStepRunMapper stepRunMapper; + @Autowired + private ObjectMapper objectMapper; + + private WikiPipelineService pipelineService; + + @BeforeEach + void setUp() { + pipelineService = new WikiPipelineService(runMapper, stepRunMapper, objectMapper, List.of(ECHO, BOOM)); + } + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + private WikiPipelineDefinitionEntity def(String stepsJson) { + WikiPipelineDefinitionEntity d = new WikiPipelineDefinitionEntity(); + d.setId(SEQ.incrementAndGet()); + d.setKbId(1L); + d.setName("p" + d.getId()); + d.setOwnerAgentId(42L); + d.setTriggerType("page_type_count"); + d.setStepsJson(stepsJson); + d.setEnabled(1); + return d; + } + + @Test + void successPath_runsAllSteps_chainingOutput() { + WikiPipelineDefinitionEntity d = def( + "[{\"id\":\"a\",\"executor\":\"echo\"},{\"id\":\"b\",\"executor\":\"echo\"}]"); + WikiPipelineService.RunOutcome outcome = pipelineService.execute(d, "episode", "20", null); + + assertFalse(outcome.duplicate()); + assertNotNull(outcome.run()); + assertEquals("succeeded", outcome.run().getStatus()); + // step b sees step a's output (chaining) + assertEquals("echo:b:echo:a:", outcome.run().getOutputJson()); + + List steps = stepRunMapper.selectList( + Wrappers.lambdaQuery() + .eq(WikiPipelineStepRunEntity::getRunId, outcome.run().getId())); + assertEquals(2, steps.size()); + assertTrue(steps.stream().allMatch(s -> s.getStatus().equals("succeeded"))); + } + + @Test + void failingStep_failsRun_andStops() { + WikiPipelineDefinitionEntity d = def( + "[{\"id\":\"a\",\"executor\":\"echo\"},{\"id\":\"b\",\"executor\":\"boom\"},{\"id\":\"c\",\"executor\":\"echo\"}]"); + WikiPipelineService.RunOutcome outcome = pipelineService.execute(d, "episode", "20", null); + + assertEquals("failed", outcome.run().getStatus()); + assertTrue(outcome.run().getErrorMessage().contains("kaboom")); + // step c must NOT have run (pipeline stopped at b) + List steps = stepRunMapper.selectList( + Wrappers.lambdaQuery() + .eq(WikiPipelineStepRunEntity::getRunId, outcome.run().getId())); + assertEquals(2, steps.size()); + } + + @Test + void duplicateTrigger_isSkipped() { + WikiPipelineDefinitionEntity d = def("[{\"id\":\"a\",\"executor\":\"echo\"}]"); + WikiPipelineService.RunOutcome first = pipelineService.execute(d, "episode", "20", null); + assertFalse(first.duplicate()); + + WikiPipelineService.RunOutcome second = pipelineService.execute(d, "episode", "20", null); + assertTrue(second.duplicate()); + assertNull(second.run()); + } + + @Test + void unknownExecutor_failsRun() { + WikiPipelineDefinitionEntity d = def("[{\"id\":\"a\",\"executor\":\"nope\"}]"); + WikiPipelineService.RunOutcome outcome = pipelineService.execute(d, "episode", "20", null); + assertEquals("failed", outcome.run().getStatus()); + assertTrue(outcome.run().getErrorMessage().contains("No executor")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListenerTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListenerTest.java new file mode 100644 index 00000000..be9efbd8 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerListenerTest.java @@ -0,0 +1,36 @@ +package vip.mate.wiki.pipeline; + +import org.junit.jupiter.api.Test; +import vip.mate.wiki.event.WikiPageCreatedEvent; + +import static org.mockito.Mockito.doThrow; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link WikiPipelineTriggerListener}: it forwards the event to + * the trigger service and never lets a trigger failure escape (so a broken + * pipeline cannot disturb ingest). + */ +class WikiPipelineTriggerListenerTest { + + @Test + void forwardsEventToTriggerService() { + WikiPipelineTriggerService trigger = mock(WikiPipelineTriggerService.class); + when(trigger.onPageTypeCount(7L, "episode")).thenReturn(1); + + new WikiPipelineTriggerListener(trigger).onPageCreated(new WikiPageCreatedEvent(7L, "episode", 100L)); + + verify(trigger).onPageTypeCount(7L, "episode"); + } + + @Test + void swallowsTriggerFailure() { + WikiPipelineTriggerService trigger = mock(WikiPipelineTriggerService.class); + doThrow(new RuntimeException("boom")).when(trigger).onPageTypeCount(7L, "episode"); + + // Must not throw — ingest must be unaffected by a pipeline failure. + new WikiPipelineTriggerListener(trigger).onPageCreated(new WikiPageCreatedEvent(7L, "episode", 100L)); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerServiceE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerServiceE2ETest.java new file mode 100644 index 00000000..bb52f312 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiPipelineTriggerServiceE2ETest.java @@ -0,0 +1,123 @@ +package vip.mate.wiki.pipeline; + +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPipelineDefinitionEntity; +import vip.mate.wiki.model.WikiPipelineRunEntity; +import vip.mate.wiki.repository.WikiPageMapper; +import vip.mate.wiki.repository.WikiPipelineDefinitionMapper; +import vip.mate.wiki.repository.WikiPipelineRunMapper; +import vip.mate.wiki.repository.WikiPipelineStepRunMapper; +import vip.mate.wiki.service.WikiPageService; + +import java.time.LocalDateTime; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +/** + * End-to-end test of the count-threshold trigger against H2: a pipeline fires + * once the page count reaches the threshold, is deduplicated within the same + * threshold bucket, and fires again at the next bucket. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPipelineTriggerServiceE2ETest { + + private static final WikiStepExecutor NOOP = new WikiStepExecutor() { + public String type() { return "noop"; } + public String execute(WikiStepContext c) { return "ok"; } + }; + + @Autowired private WikiPipelineDefinitionMapper definitionMapper; + @Autowired private WikiPipelineRunMapper runMapper; + @Autowired private WikiPipelineStepRunMapper stepRunMapper; + @Autowired private WikiPageMapper pageMapper; + @Autowired private WikiPageService pageService; + @Autowired private ObjectMapper objectMapper; + + private WikiPipelineTriggerService triggerService; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + @BeforeEach + void setUp() { + WikiPipelineService pipelineService = new WikiPipelineService( + runMapper, stepRunMapper, objectMapper, List.of(NOOP)); + triggerService = new WikiPipelineTriggerService( + definitionMapper, pipelineService, pageMapper, objectMapper); + } + + private long seedDefinition(long kb, int threshold) { + WikiPipelineDefinitionEntity d = new WikiPipelineDefinitionEntity(); + d.setKbId(kb); + d.setName("episode-to-pattern-" + SEQ.incrementAndGet()); + d.setOwnerAgentId(42L); + d.setTriggerType("page_type_count"); + d.setTriggerConfigJson("{\"page_type\":\"episode\",\"threshold\":" + threshold + "}"); + d.setStepsJson("[{\"id\":\"s\",\"executor\":\"noop\"}]"); + d.setEnabled(1); + d.setCreateTime(LocalDateTime.now()); + d.setUpdateTime(LocalDateTime.now()); + definitionMapper.insert(d); + return d.getId(); + } + + private void addEpisodes(long kb, int n) { + for (int i = 0; i < n; i++) { + pageService.createPage(kb, "ep-" + kb + "-" + SEQ.incrementAndGet(), + "Episode", "body", "s", "[1]", "episode"); + } + } + + private long runCount(long defId) { + return runMapper.selectCount(Wrappers.lambdaQuery() + .eq(WikiPipelineRunEntity::getDefinitionId, defId)); + } + + @Test + void firesAtThreshold_dedupsWithinBucket_firesAtNextBucket() { + long kb = SEQ.incrementAndGet(); + long defId = seedDefinition(kb, 3); + + // Below threshold: no run. + addEpisodes(kb, 2); + assertEquals(0, triggerService.onPageTypeCount(kb, "episode")); + assertEquals(0, runCount(defId)); + + // Reaching threshold (3) fires one run (bucket 1). + addEpisodes(kb, 1); + assertEquals(1, triggerService.onPageTypeCount(kb, "episode")); + assertEquals(1, runCount(defId)); + + // Still in bucket 1 (count 4): deduped, no new run. + addEpisodes(kb, 1); + assertEquals(0, triggerService.onPageTypeCount(kb, "episode")); + assertEquals(1, runCount(defId)); + + // Crossing into bucket 2 (count 6) fires again. + addEpisodes(kb, 2); + assertEquals(1, triggerService.onPageTypeCount(kb, "episode")); + assertEquals(2, runCount(defId)); + } + + @Test + void nonMatchingPageType_doesNotFire() { + long kb = SEQ.incrementAndGet(); + long defId = seedDefinition(kb, 1); + // A different pageType event must not trigger the episode pipeline. + assertEquals(0, triggerService.onPageTypeCount(kb, "concept")); + assertEquals(0, runCount(defId)); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiSkillStepExecutorTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiSkillStepExecutorTest.java new file mode 100644 index 00000000..2ea48913 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/pipeline/WikiSkillStepExecutorTest.java @@ -0,0 +1,81 @@ +package vip.mate.wiki.pipeline; + +import org.junit.jupiter.api.Test; +import vip.mate.skill.model.SkillEntity; +import vip.mate.skill.service.SkillService; + +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link WikiSkillStepExecutor}: returns the skill's content + * when allowed, and refuses disabled / scan-failed skills and script execution. + */ +class WikiSkillStepExecutorTest { + + private SkillEntity skill(String name, Boolean enabled, String scan, String content) { + SkillEntity s = new SkillEntity(); + s.setName(name); + s.setEnabled(enabled); + s.setSecurityScanStatus(scan); + s.setSkillContent(content); + return s; + } + + private WikiSkillStepExecutor executor(SkillEntity skill) { + SkillService service = mock(SkillService.class); + when(service.findByName("wiki-link-enrich")).thenReturn(skill); + return new WikiSkillStepExecutor(service); + } + + private WikiStepContext ctx(Map config) { + return new WikiStepContext(1L, 42L, "s1", config, "prior"); + } + + @Test + void returnsSkillContent_whenAllowed() throws Exception { + WikiSkillStepExecutor e = executor(skill("wiki-link-enrich", true, "PASSED", "do the thing")); + assertEquals("do the thing", e.execute(ctx(Map.of("skill", "wiki-link-enrich")))); + } + + @Test + void missingSkillName_throws() { + WikiSkillStepExecutor e = executor(skill("wiki-link-enrich", true, "PASSED", "x")); + assertThrows(IllegalArgumentException.class, () -> e.execute(ctx(Map.of()))); + } + + @Test + void unknownSkill_throws() { + WikiSkillStepExecutor e = executor(skill("wiki-link-enrich", true, "PASSED", "x")); + assertThrows(IllegalArgumentException.class, + () -> e.execute(ctx(Map.of("skill", "does-not-exist")))); + } + + @Test + void disabledSkill_throws() { + WikiSkillStepExecutor e = executor(skill("wiki-link-enrich", false, "PASSED", "x")); + assertThrows(IllegalStateException.class, + () -> e.execute(ctx(Map.of("skill", "wiki-link-enrich")))); + } + + @Test + void scanFailedSkill_throws() { + WikiSkillStepExecutor e = executor(skill("wiki-link-enrich", true, "FAILED", "x")); + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> e.execute(ctx(Map.of("skill", "wiki-link-enrich")))); + assertTrue(ex.getMessage().contains("security scan")); + } + + @Test + void scriptExecutionRequest_isRefused() { + WikiSkillStepExecutor e = executor(skill("wiki-link-enrich", true, "PASSED", "x")); + IllegalStateException ex = assertThrows(IllegalStateException.class, + () -> e.execute(ctx(Map.of("skill", "wiki-link-enrich", "run_script", true)))); + assertTrue(ex.getMessage().contains("Script execution is not permitted")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiMetadataValidatorTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiMetadataValidatorTest.java new file mode 100644 index 00000000..da81b857 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiMetadataValidatorTest.java @@ -0,0 +1,137 @@ +package vip.mate.wiki.profile; + +import org.junit.jupiter.api.Test; + +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Unit tests for {@link WikiMetadataValidator} covering required/type/enum/date + * rules, coercion, and undeclared-field handling. + */ +class WikiMetadataValidatorTest { + + private final WikiMetadataValidator validator = new WikiMetadataValidator(); + + private WikiPageTypeDef episodeDef() { + WikiPageTypeDef def = new WikiPageTypeDef(); + Map schema = new LinkedHashMap<>(); + schema.put("event_type", field("string", true, null)); + schema.put("event_date", field("date", true, null)); + schema.put("significance", field("enum", false, List.of("low", "medium", "high"))); + schema.put("cited_count", field("number", false, null)); + def.setSchema(schema); + return def; + } + + private WikiFieldSchema field(String type, boolean required, List values) { + WikiFieldSchema f = new WikiFieldSchema(); + f.setType(type); + f.setRequired(required); + f.setValues(values); + return f; + } + + @Test + void validMetadata_isOk() { + Map raw = new LinkedHashMap<>(); + raw.put("event_type", "liquidity_shock"); + raw.put("event_date", "2024-09-18"); + raw.put("significance", "high"); + raw.put("cited_count", 12); + + WikiMetadataValidator.ValidationResult r = validator.validate(episodeDef(), raw, false, "create"); + + assertEquals(WikiMetadataValidator.OK, r.getStatus()); + assertTrue(r.getWarnings().isEmpty()); + assertEquals("liquidity_shock", r.getCleaned().get("event_type")); + } + + @Test + void requiredMissing_warnsButKeepsGoing() { + Map raw = new LinkedHashMap<>(); + raw.put("event_type", "x"); + // event_date missing + WikiMetadataValidator.ValidationResult r = validator.validate(episodeDef(), raw, false, "create"); + + assertEquals(WikiMetadataValidator.WARNING, r.getStatus()); + assertTrue(r.getWarnings().stream().anyMatch(w -> + w.getField().equals("event_date") && w.getReason().contains("required"))); + } + + @Test + void numberCoercedFromString() { + Map raw = new LinkedHashMap<>(); + raw.put("event_type", "x"); + raw.put("event_date", "2024-01-01"); + raw.put("cited_count", "42"); + WikiMetadataValidator.ValidationResult r = validator.validate(episodeDef(), raw, false, "create"); + + assertEquals(42L, r.getCleaned().get("cited_count")); + assertEquals(WikiMetadataValidator.OK, r.getStatus()); + } + + @Test + void badDate_warns() { + Map raw = new LinkedHashMap<>(); + raw.put("event_type", "x"); + raw.put("event_date", "Sept 2024"); + WikiMetadataValidator.ValidationResult r = validator.validate(episodeDef(), raw, false, "create"); + + assertTrue(r.getWarnings().stream().anyMatch(w -> + w.getField().equals("event_date") && w.getReason().contains("ISO date"))); + } + + @Test + void enumOutOfRange_warns() { + Map raw = new LinkedHashMap<>(); + raw.put("event_type", "x"); + raw.put("event_date", "2024-01-01"); + raw.put("significance", "catastrophic"); + WikiMetadataValidator.ValidationResult r = validator.validate(episodeDef(), raw, false, "create"); + + assertTrue(r.getWarnings().stream().anyMatch(w -> + w.getField().equals("significance") && w.getReason().contains("enum"))); + } + + @Test + void undeclaredField_droppedWithWarning_whenNotAllowed() { + Map raw = new LinkedHashMap<>(); + raw.put("event_type", "x"); + raw.put("event_date", "2024-01-01"); + raw.put("rogue", "surprise"); + WikiMetadataValidator.ValidationResult r = validator.validate(episodeDef(), raw, false, "route"); + + assertFalse(r.getCleaned().containsKey("rogue")); + WikiMetadataValidator.FieldWarning w = r.getWarnings().stream() + .filter(x -> x.getField().equals("rogue")).findFirst().orElseThrow(); + assertTrue(w.getReason().contains("dropped")); + assertEquals("route", w.getSource()); + assertEquals("surprise", w.getRawValuePreview()); + } + + @Test + void undeclaredField_keptWhenAllowed() { + Map raw = new LinkedHashMap<>(); + raw.put("event_type", "x"); + raw.put("event_date", "2024-01-01"); + raw.put("extra", "kept"); + WikiMetadataValidator.ValidationResult r = validator.validate(episodeDef(), raw, true, "create"); + + assertEquals("kept", r.getCleaned().get("extra")); + } + + @Test + void nullDef_keepsAllFields() { + Map raw = new LinkedHashMap<>(); + raw.put("anything", "goes"); + WikiMetadataValidator.ValidationResult r = validator.validate(null, raw, false, "create"); + // No schema → additional fields dropped (allowAdditional=false) with warning + assertTrue(r.getWarnings().stream().anyMatch(w -> w.getField().equals("anything"))); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceE2ETest.java new file mode 100644 index 00000000..51a97209 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceE2ETest.java @@ -0,0 +1,106 @@ +package vip.mate.wiki.profile; + +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPageTypeProfileEntity; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Integration tests for {@link WikiPageTypeProfileService} CRUD against H2: + * upsert keeps a single enabled row (no generated-column violation), reset + * falls back to the default, and JSON validation reports structural issues. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPageTypeProfileServiceE2ETest { + + @Autowired + private WikiPageTypeProfileService service; + + // Persistent file-DB isolation: fresh kb ids per test. + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + private static final String EPISODE_JSON = + "{\"version\":1,\"pageTypes\":{\"episode\":{\"label\":\"Episode\"}}}"; + + @Test + void saveThenResolve_roundTrips() { + long kb = SEQ.incrementAndGet(); + service.saveProfile(kb, "liquidity", EPISODE_JSON); + + WikiPageTypeProfileEntity row = service.findEnabledRow(kb); + assertNotNull(row); + assertEquals("liquidity", row.getName()); + assertEquals(1, row.getVersion()); + assertTrue(service.resolveProfile(kb).hasPageType("episode")); + } + + @Test + void saveTwice_upsertsInPlaceAndBumpsVersion() { + long kb = SEQ.incrementAndGet(); + service.saveProfile(kb, "v1", EPISODE_JSON); + // Saving again must update the single enabled row, not insert a second + // (which would violate the one-enabled-per-KB generated-column UNIQUE). + service.saveProfile(kb, "v1", + "{\"version\":1,\"pageTypes\":{\"episode\":{\"label\":\"E\"},\"pattern\":{\"label\":\"P\"}}}"); + + WikiPageTypeProfileEntity row = service.findEnabledRow(kb); + assertEquals(2, row.getVersion()); + assertTrue(service.resolveProfile(kb).hasPageType("pattern")); + } + + @Test + void resetToDefault_removesRowAndFallsBack() { + long kb = SEQ.incrementAndGet(); + service.saveProfile(kb, "custom", EPISODE_JSON); + assertNotNull(service.findEnabledRow(kb)); + + service.resetToDefault(kb); + + assertNull(service.findEnabledRow(kb)); + // Resolution now returns the built-in default. + assertTrue(service.resolveProfile(kb).hasPageType("concept")); + assertFalse(service.resolveProfile(kb).hasPageType("episode")); + } + + @Test + void invalidConfig_isRejectedOnSave() { + try { + service.saveProfile(SEQ.incrementAndGet(), "bad", "{ not json"); + org.junit.jupiter.api.Assertions.fail("expected IllegalArgumentException"); + } catch (IllegalArgumentException expected) { + // ok + } + } + + @Test + void validateProfileJson_reportsIssues() { + assertTrue(service.validateProfileJson(EPISODE_JSON).isEmpty()); + + List noTypes = service.validateProfileJson("{\"pageTypes\":{}}"); + assertFalse(noTypes.isEmpty()); + + List badEnum = service.validateProfileJson( + "{\"pageTypes\":{\"x\":{\"schema\":{\"f\":{\"type\":\"enum\"}}}}}"); + assertTrue(badEnum.stream().anyMatch(s -> s.contains("enum"))); + + List badType = service.validateProfileJson( + "{\"pageTypes\":{\"x\":{\"schema\":{\"f\":{\"type\":\"banana\"}}}}}"); + assertTrue(badType.stream().anyMatch(s -> s.contains("unknown field type"))); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceTest.java new file mode 100644 index 00000000..2bebde45 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/profile/WikiPageTypeProfileServiceTest.java @@ -0,0 +1,149 @@ +package vip.mate.wiki.profile; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import vip.mate.wiki.model.WikiPageTypeProfileEntity; +import vip.mate.wiki.repository.WikiPageTypeProfileMapper; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link WikiPageTypeProfileService}: default profile loading, + * KB profile resolution and fallback behaviour. The default profile is loaded + * from the real classpath resource; the mapper is mocked. + */ +class WikiPageTypeProfileServiceTest { + + private WikiPageTypeProfileMapper mapper; + private WikiPageTypeProfileService service; + + @BeforeEach + void setUp() { + mapper = mock(WikiPageTypeProfileMapper.class); + service = new WikiPageTypeProfileService(mapper, new ObjectMapper()); + service.loadDefault(); + } + + @Test + void defaultProfileReproducesBuiltInPageTypes() { + WikiPageTypeProfile def = service.getDefaultProfile(); + assertTrue(def.hasPageType("concept")); + assertTrue(def.hasPageType("person")); + assertTrue(def.hasPageType("process")); + assertTrue(def.hasPageType("other")); + assertEquals(10, def.getPageTypes().size()); + } + + @Test + void noConfiguredProfile_resolvesToDefault() { + when(mapper.selectOne(any())).thenReturn(null); + assertTrue(service.allowedPageTypes(42L).contains("concept")); + } + + @Test + void configuredProfile_isParsedAndVersionStamped() { + WikiPageTypeProfileEntity row = new WikiPageTypeProfileEntity(); + row.setKbId(42L); + row.setVersion(5); + row.setEnabled(1); + row.setConfigJson("{\"version\":1,\"pageTypes\":{\"episode\":{\"label\":\"Episode\"}}}"); + when(mapper.selectOne(any())).thenReturn(row); + + WikiPageTypeProfile resolved = service.resolveProfile(42L); + assertTrue(resolved.hasPageType("episode")); + assertFalse(resolved.hasPageType("concept")); + assertEquals(5, resolved.getVersion()); // stamped from the row + } + + @Test + void unparseableConfig_fallsBackToDefault() { + WikiPageTypeProfileEntity row = new WikiPageTypeProfileEntity(); + row.setKbId(42L); + row.setEnabled(1); + row.setConfigJson("{ not valid json"); + when(mapper.selectOne(any())).thenReturn(row); + + assertTrue(service.resolveProfile(42L).hasPageType("concept")); + } + + @Test + void normalizePageType_keepsKnown_downgradesUnknown() { + when(mapper.selectOne(any())).thenReturn(null); // default profile + assertEquals("person", service.normalizePageType(1L, "Person")); + assertEquals("concept", service.normalizePageType(1L, "made-up-type")); + assertEquals("concept", service.normalizePageType(1L, null)); + } + + @Test + void describeForPrompt_defaultProfile_listsBuiltInTypes() { + when(mapper.selectOne(any())).thenReturn(null); + String fragment = service.describeForPrompt(1L); + assertTrue(fragment.contains("- concept"), fragment); + assertTrue(fragment.contains("- person"), fragment); + assertTrue(fragment.contains("- other"), fragment); + } + + @Test + void resolveLayer_defaultsKnownTypesToFact_experienceWhenDeclared() { + WikiPageTypeProfileEntity row = new WikiPageTypeProfileEntity(); + row.setKbId(1L); + row.setEnabled(1); + row.setConfigJson("{\"pageTypes\":{" + + "\"episode\":{\"layer\":\"fact\"}," + + "\"concept\":{}," // known type, no layer → defaults to fact + + "\"pattern\":{\"layer\":\"experience\"}}}"); + when(mapper.selectOne(any())).thenReturn(row); + + assertEquals("fact", service.resolveLayer(1L, "episode")); + assertEquals("fact", service.resolveLayer(1L, "concept")); + assertEquals("experience", service.resolveLayer(1L, "pattern")); + assertTrue(service.isExperience(1L, "pattern")); + assertFalse(service.isExperience(1L, "episode")); + // unknown type → null (caller leaves layer untouched) + assertNull(service.resolveLayer(1L, "made-up")); + } + + @Test + void stageInstructionAndTemplate_areResolvedPerType() { + WikiPageTypeProfileEntity row = new WikiPageTypeProfileEntity(); + row.setKbId(1L); + row.setEnabled(1); + row.setConfigJson("{\"pageTypes\":{\"episode\":{" + + "\"route\":{\"instructions\":\"仅当有明确日期时路由为 episode\"}," + + "\"merge\":{\"instructions\":\"保留已审阅分析,追加新证据\"}," + + "\"create\":{\"instructions\":\"抽取 event_date\"}," + + "\"template\":{\"markdown\":\"## Summary\\n{{summary}}\\n## 事件\"}}}}"); + when(mapper.selectOne(any())).thenReturn(row); + + assertTrue(service.stageInstruction(1L, "episode", "route").contains("明确日期")); + assertTrue(service.stageInstruction(1L, "episode", "merge").contains("已审阅")); + assertTrue(service.stageInstruction(1L, "episode", "create").contains("event_date")); + assertTrue(service.templateMarkdown(1L, "episode").contains("## Summary")); + // unknown type / stage → empty, never null + assertEquals("", service.stageInstruction(1L, "nope", "route")); + assertEquals("", service.templateMarkdown(1L, "nope")); + } + + @Test + void describeForPrompt_customProfile_showsRequiredMetadata() { + WikiPageTypeProfileEntity row = new WikiPageTypeProfileEntity(); + row.setKbId(1L); + row.setEnabled(1); + row.setConfigJson("{\"pageTypes\":{\"episode\":{\"description\":\"a dated event\"," + + "\"schema\":{\"event_date\":{\"type\":\"date\",\"required\":true}," + + "\"note\":{\"type\":\"string\",\"required\":false}}}}}"); + when(mapper.selectOne(any())).thenReturn(row); + + String fragment = service.describeForPrompt(1L); + assertTrue(fragment.contains("- episode: a dated event"), fragment); + assertTrue(fragment.contains("required metadata: event_date"), fragment); + assertFalse(fragment.contains("note"), fragment); // optional field not listed as required + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageDependencyMapperE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageDependencyMapperE2ETest.java new file mode 100644 index 00000000..059df830 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageDependencyMapperE2ETest.java @@ -0,0 +1,71 @@ +package vip.mate.wiki.repository; + +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import vip.mate.wiki.model.WikiPageDependencyEntity; + +import java.time.LocalDateTime; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +/** + * Validates the page dependency table against H2: reverse lookup by + * depends_on_page_id finds dependents, and the unique key prevents duplicate + * edges. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPageDependencyMapperE2ETest { + + @Autowired + private WikiPageDependencyMapper mapper; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + private WikiPageDependencyEntity edge(long kb, long page, long dependsOn) { + WikiPageDependencyEntity e = new WikiPageDependencyEntity(); + e.setKbId(kb); + e.setPageId(page); + e.setDependsOnPageId(dependsOn); + e.setDependencyType("fact"); + e.setCreateTime(LocalDateTime.now()); + e.setUpdateTime(LocalDateTime.now()); + return e; + } + + @Test + void reverseLookupFindsDependents() { + long kb = SEQ.incrementAndGet(); + long fact = SEQ.incrementAndGet(); + long expA = SEQ.incrementAndGet(); + long expB = SEQ.incrementAndGet(); + mapper.insert(edge(kb, expA, fact)); + mapper.insert(edge(kb, expB, fact)); + + List dependents = mapper.selectList( + Wrappers.lambdaQuery() + .eq(WikiPageDependencyEntity::getKbId, kb) + .eq(WikiPageDependencyEntity::getDependsOnPageId, fact)); + assertEquals(2, dependents.size()); + } + + @Test + void duplicateEdgeRejected() { + long kb = SEQ.incrementAndGet(); + long page = SEQ.incrementAndGet(); + long fact = SEQ.incrementAndGet(); + mapper.insert(edge(kb, page, fact)); + assertThrows(Exception.class, () -> mapper.insert(edge(kb, page, fact))); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageTypeProfileMapperE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageTypeProfileMapperE2ETest.java new file mode 100644 index 00000000..0480a2bf --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPageTypeProfileMapperE2ETest.java @@ -0,0 +1,95 @@ +package vip.mate.wiki.repository; + +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPageTypeProfileEntity; + +import java.time.LocalDateTime; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Validates the DB-level invariants of the pageType profile table against H2: + * the V134 generated-column UNIQUE permits at most one enabled profile per KB, + * while disabled rows coexist freely. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPageTypeProfileMapperE2ETest { + + @Autowired + private WikiPageTypeProfileMapper mapper; + + // The test H2 is a persistent file DB shared across runs, so each test + // uses fresh kb ids to stay isolated from earlier runs' rows. + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + private long uniqueKb() { + return SEQ.incrementAndGet(); + } + + private WikiPageTypeProfileEntity profile(long kbId, String name, int enabled) { + WikiPageTypeProfileEntity p = new WikiPageTypeProfileEntity(); + p.setKbId(kbId); + p.setName(name); + p.setVersion(1); + p.setConfigJson("{\"version\":1,\"pageTypes\":{}}"); + p.setEnabled(enabled); + p.setCreateTime(LocalDateTime.now()); + p.setUpdateTime(LocalDateTime.now()); + return p; + } + + @Test + void insertsAndReadsBack() { + long kb = uniqueKb(); + WikiPageTypeProfileEntity p = profile(kb, "default", 1); + mapper.insert(p); + assertNotNull(p.getId()); + WikiPageTypeProfileEntity loaded = mapper.selectById(p.getId()); + assertEquals("default", loaded.getName()); + assertEquals(kb, loaded.getKbId()); + } + + @Test + void secondEnabledProfileForSameKb_isRejected() { + long kb = uniqueKb(); + mapper.insert(profile(kb, "default", 1)); + // A different name but also enabled for the same KB must violate the + // generated-column UNIQUE (one enabled profile per KB). + assertThrows(Exception.class, () -> mapper.insert(profile(kb, "regulation", 1))); + } + + @Test + void multipleDisabledProfilesForSameKb_coexist() { + long kb = uniqueKb(); + mapper.insert(profile(kb, "default", 1)); + // enabled=0 rows yield NULL in the generated column and are exempt from + // the unique check, so several may coexist. + mapper.insert(profile(kb, "draft-a", 0)); + mapper.insert(profile(kb, "draft-b", 0)); + long count = mapper.selectCount( + com.baomidou.mybatisplus.core.toolkit.Wrappers + .lambdaQuery() + .eq(WikiPageTypeProfileEntity::getKbId, kb)); + assertEquals(3, count); + } + + @Test + void enabledProfilesInDifferentKbs_coexist() { + mapper.insert(profile(uniqueKb(), "default", 1)); + mapper.insert(profile(uniqueKb(), "default", 1)); + assertTrue(true); // no exception thrown — different KBs are independent + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPipelineRunMapperE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPipelineRunMapperE2ETest.java new file mode 100644 index 00000000..fd350550 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/repository/WikiPipelineRunMapperE2ETest.java @@ -0,0 +1,62 @@ +package vip.mate.wiki.repository; + +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPipelineRunEntity; + +import java.time.LocalDateTime; + +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertThrows; + +/** + * Validates the pipeline run dedup invariant against H2: two runs sharing the + * same (definition, trigger envelope) collide on the unique key, so duplicate + * triggers cannot spawn parallel runs. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPipelineRunMapperE2ETest { + + @Autowired + private WikiPipelineRunMapper mapper; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + private WikiPipelineRunEntity run(long defId, String bucket) { + WikiPipelineRunEntity r = new WikiPipelineRunEntity(); + r.setDefinitionId(defId); + r.setKbId(1L); + r.setStatus("pending"); + r.setTriggerType("page_type_count"); + r.setTriggerSubject("episode"); + r.setTriggerBucket(bucket); + r.setCreateTime(LocalDateTime.now()); + return r; + } + + @Test + void duplicateTriggerEnvelope_isRejected() { + long defId = SEQ.incrementAndGet(); + WikiPipelineRunEntity first = run(defId, "20"); + mapper.insert(first); + assertNotNull(first.getId()); + + assertThrows(Exception.class, () -> mapper.insert(run(defId, "20"))); + } + + @Test + void differentBucket_isAllowed() { + long defId = SEQ.incrementAndGet(); + mapper.insert(run(defId, "20")); + mapper.insert(run(defId, "40")); // next threshold bucket — distinct run + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiCascadeRegressionE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiCascadeRegressionE2ETest.java new file mode 100644 index 00000000..3e40b612 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiCascadeRegressionE2ETest.java @@ -0,0 +1,230 @@ +package vip.mate.wiki.service; + +import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.annotation.DirtiesContext; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.repository.WikiKnowledgeBaseMapper; +import vip.mate.wiki.repository.WikiPageMapper; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +/** + * Regression suite for the cascade / scan write paths. + * + *

    Boots the full Spring context with the H2 + Flyway test profile so the + * V129 broken_links migration is in place and MyBatis-Plus's lambda cache + * for {@link WikiPageEntity} is fully primed. That priming is what + * distinguishes this suite from the existing mock-mapper tests in + * {@link WikiPageServiceTest} — only the real Spring + MP wiring exposes + * the {@code FieldStrategy.ALWAYS} + partial-entity-update interaction + * that the §8 incident exposed. + * + *

    Three classes of guard, one per case: + *

      + *
    • Scan must leave {@code content} and {@code summary} byte-identical.
      • + *
    • Cascade delete must leave the referrer's {@code summary} byte-identical + * (and its {@code content} only modified by the wikilink demotion).
      • + *
    • Cascade rename must leave the referrer's {@code summary} byte-identical + * (and its {@code content} only modified by the wikilink target swap).
      • + *
    + * + *

    Plus a small portability check around the case-only rename path (R4-G). + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS) +class WikiCascadeRegressionE2ETest { + + @Autowired private WikiPageService pageService; + @Autowired private WikiLintJobService lintJobService; + @Autowired private WikiKnowledgeBaseService kbService; + @Autowired private WikiPageMapper pageMapper; + @Autowired private WikiKnowledgeBaseMapper kbMapper; + + private Long kbId; + + @AfterEach + void cleanup() { + if (kbId != null) { + pageMapper.delete(new LambdaQueryWrapper().eq(WikiPageEntity::getKbId, kbId)); + kbMapper.deleteById(kbId); + pageService.evictSummaryCache(kbId); + kbId = null; + } + } + + private void seedKb() { + WikiKnowledgeBaseEntity kb = kbService.create("cascade-regress-" + System.nanoTime(), "regression test", null); + kbId = kb.getId(); + // Purge whatever the bootstrap may have auto-inserted so we own the page set. + pageMapper.delete(new LambdaQueryWrapper().eq(WikiPageEntity::getKbId, kbId)); + pageService.evictSummaryCache(kbId); + } + + // ---------------------------------------------------------------- + // §8 regression — scan / cascade must not null content + summary + // ---------------------------------------------------------------- + + @Test + @DisplayName("scan x N leaves content + summary byte-identical") + void scanPreservesContentAndSummary() throws Exception { + seedKb(); + String content = "## Heading\n\nThis page has a [[ghost]] broken ref and prose body."; + String summary = "summary that must survive every scan"; + WikiPageEntity created = pageService.createPage(kbId, "alpha", "Alpha", + content, summary, "[]"); + + // Round-trip through the DB so we read what was actually persisted. + WikiPageEntity beforeScan = pageMapper.selectById(created.getId()); + assertThat(beforeScan.getContent()).isEqualTo(content); + assertThat(beforeScan.getSummary()).isEqualTo(summary); + + // Run KB-wide scan three times in a row. With the bug present, each + // pass would re-issue `UPDATE ... SET content=NULL, summary=NULL` + // for every page in the KB. + for (int i = 0; i < 3; i++) { + lintJobService.startOrGetRunning(kbId); + waitForJobCompletion(20); + } + + WikiPageEntity afterScan = pageMapper.selectById(created.getId()); + assertThat(afterScan.getContent()) + .as("content must not be NULL'd by scan") + .isEqualTo(content); + assertThat(afterScan.getSummary()) + .as("summary must not be NULL'd by scan") + .isEqualTo(summary); + // Broken-link state still computed correctly. + assertThat(afterScan.getBrokenLinks()).contains("ghost"); + assertThat(afterScan.getBrokenLinksScannedAt()).isNotNull(); + } + + @Test + @DisplayName("cascade delete preserves referrer's summary; content reduced only by wikilink demotion") + void cascadeDeletePreservesReferrerSummary() { + seedKb(); + pageService.createPage(kbId, "alice", "Alice", + "Alice is the team lead.", + "Senior engineer, leads search.", + "[]"); + WikiPageEntity bob = pageService.createPage(kbId, "bob", "Bob", + "Bob reports to [[alice]] and pairs with [[alice|her]].", + "Junior engineer mentored by Alice.", + "[]"); + int bobLenBefore = bob.getContent().length(); + String bobSummary = bob.getSummary(); + + pageService.delete(kbId, "alice"); + + WikiPageEntity bobAfter = pageMapper.selectById(bob.getId()); + assertThat(bobAfter.getSummary()) + .as("referrer's summary must not be null'd by cascade delete") + .isEqualTo(bobSummary); + assertThat(bobAfter.getContent()).doesNotContain("[[alice]]"); + assertThat(bobAfter.getContent()).doesNotContain("[[alice|"); + // Snapshot title + alias preserved as visible text. + assertThat(bobAfter.getContent()).contains("Alice").contains("her"); + // Length should shrink (the wikilink syntax overhead goes away) but not zero. + assertThat(bobAfter.getContent().length()) + .isGreaterThan(0) + .isLessThan(bobLenBefore); + // outgoing_links should be empty now that the only target was removed. + assertThat(bobAfter.getOutgoingLinks()).isEqualTo("[]"); + } + + @Test + @DisplayName("cascade rename preserves referrer's summary; alias preserved") + void cascadeRenamePreservesReferrerSummary() { + seedKb(); + pageService.createPage(kbId, "old-slug", "Old Title", + "stub", "stub summary", "[]"); + WikiPageEntity referrer = pageService.createPage(kbId, "ref", "Ref", + "Links: [[old-slug]] and [[old-slug|displayed text]].", + "Referrer summary that must survive rename.", + "[]"); + String summaryBefore = referrer.getSummary(); + + WikiPageEntity renamed = pageService.rename(kbId, "old-slug", "new-slug"); + assertThat(renamed).isNotNull(); + assertThat(renamed.getSlug()).isEqualTo("new-slug"); + + WikiPageEntity refAfter = pageMapper.selectById(referrer.getId()); + assertThat(refAfter.getSummary()) + .as("referrer's summary must not be null'd by cascade rename") + .isEqualTo(summaryBefore); + assertThat(refAfter.getContent()).doesNotContain("[[old-slug]]"); + assertThat(refAfter.getContent()).doesNotContain("[[old-slug|"); + assertThat(refAfter.getContent()).contains("[[new-slug]]"); + assertThat(refAfter.getContent()).contains("[[new-slug|displayed text]]"); + assertThat(refAfter.getOutgoingLinks()).contains("new-slug"); + } + + // ---------------------------------------------------------------- + // R4-G regression — case-only rename portability + // ---------------------------------------------------------------- + + @Test + @DisplayName("case-only rename (foo → FOO) is allowed: collision check ignores same row") + void caseOnlyRenameIsAllowed() { + seedKb(); + WikiPageEntity p = pageService.createPage(kbId, "foo", "Foo", "body", "sum", "[]"); + + // Without the same-id collision-check escape, this would throw on + // MySQL because getBySlug("FOO") returns the same row (case-insensitive + // collation). The fix lets it through. + WikiPageEntity renamed = pageService.rename(kbId, "foo", "FOO"); + assertThat(renamed).isNotNull(); + assertThat(renamed.getId()).isEqualTo(p.getId()); + assertThat(renamed.getSlug()).isEqualTo("FOO"); + } + + @Test + @DisplayName("rename to a slug already owned by a DIFFERENT page still rejects with 400-equivalent") + void renameRejectsRealCollision() { + seedKb(); + pageService.createPage(kbId, "first", "First", "x", "x", "[]"); + pageService.createPage(kbId, "second", "Second", "y", "y", "[]"); + + // first → second is a real collision (different existing page); the + // same-id escape must NOT swallow this. + assertThatThrownBy(() -> pageService.rename(kbId, "first", "second")) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("already exists"); + } + + // ---------------------------------------------------------------- + // Helpers + // ---------------------------------------------------------------- + + /** + * Spin for at most {@code timeoutSec} waiting for the latest job on + * {@link #kbId} to leave the queued/running state. The lint executor is + * single-threaded and per-page work is sub-ms, so this returns almost + * immediately in practice. + */ + private void waitForJobCompletion(int timeoutSec) throws InterruptedException { + long deadline = System.currentTimeMillis() + timeoutSec * 1000L; + while (System.currentTimeMillis() < deadline) { + WikiLintJobService.LintJob job = lintJobService.getLatestJob(kbId); + if (job == null) return; + if (job.status() == WikiLintJobService.JobStatus.COMPLETED + || job.status() == WikiLintJobService.JobStatus.FAILED) { + return; + } + Thread.sleep(25); + } + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiContextServiceTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiContextServiceTest.java index 547d15ad..635ac044 100644 --- a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiContextServiceTest.java +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiContextServiceTest.java @@ -6,6 +6,7 @@ import org.junit.jupiter.api.Test; import vip.mate.wiki.WikiProperties; import vip.mate.wiki.dto.PageSearchResult; import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.model.WikiPageEntity; import java.util.List; @@ -127,4 +128,85 @@ class WikiContextServiceTest { return PageSearchResult.of(slug, slug, snippet, snippet, List.of("keyword"), null, score); } + + // ==================== buildWikiContext heading + hint format ==================== + // + // These tests lock in the unambiguous heading layout: heading text after + // `### ` MUST equal the KB name verbatim and nothing more, so the LLM + // can safely copy it into the `kbName` tool argument. The previous form + // "### {name} — {description} ({N} pages)" let the LLM paste the entire + // row and break findByName's exact-match lookup. The multi-KB hint must + // also call out kbId as the disambiguator for duplicate names. + + private static WikiKnowledgeBaseEntity kbWithName(long id, String name, String description, Long agentId) { + WikiKnowledgeBaseEntity kb = new WikiKnowledgeBaseEntity(); + kb.setId(id); + kb.setName(name); + kb.setDescription(description); + kb.setAgentId(agentId); + kb.setPageCount(0); + return kb; + } + + private static WikiPageEntity simplePage(String slug, String title, String summary) { + WikiPageEntity p = new WikiPageEntity(); + p.setSlug(slug); + p.setTitle(title); + p.setSummary(summary); + p.setPageType("user"); + return p; + } + + @Test + @DisplayName("buildWikiContext heading is JUST the KB name — no description, no page count") + void buildWikiContextHeadingIsBareName() { + WikiKnowledgeBaseEntity kb = kbWithName(100L, "QA-Bug-Test KB", + "A KB created via UI E2E test to surface wiki bugs", null); + when(kbService.listByAgentId(1L)).thenReturn(List.of(kb)); + when(pageService.listSummaries(100L)).thenReturn(List.of( + simplePage("mateclaw", "MateClaw", "Entry page"))); + + String out = service.buildWikiContext(1L); + + // Heading line is exact — pasting this into kbName must work without trim/strip. + assertThat(out).contains("### QA-Bug-Test KB\n"); + // Description and page count live on the next line, not in the heading. + assertThat(out).doesNotContain("### QA-Bug-Test KB —"); + assertThat(out).doesNotContain("### QA-Bug-Test KB ("); + assertThat(out).contains("1 pages — A KB created via UI E2E test"); + } + + @Test + @DisplayName("buildWikiContext multi-KB hint mentions kbName + kbId + wiki_list_kbs") + void buildWikiContextMultiKbHint() { + when(kbService.listByAgentId(1L)).thenReturn(List.of( + kbWithName(100L, "Alpha", null, null), + kbWithName(200L, "Beta", null, null))); + when(pageService.listSummaries(100L)).thenReturn(List.of(simplePage("a", "A", null))); + when(pageService.listSummaries(200L)).thenReturn(List.of(simplePage("b", "B", null))); + + String out = service.buildWikiContext(1L); + + // Hint must point the LLM at the right argument and at the + // disambiguator for duplicate names. + assertThat(out) + .contains("kbName") + .contains("kbId") + .contains("wiki_list_kbs") + .contains("EXACT text after `### `"); + } + + @Test + @DisplayName("buildWikiContext single-KB output omits the multi-KB hint") + void buildWikiContextSingleKbSkipsHint() { + WikiKnowledgeBaseEntity kb = kbWithName(100L, "Solo", null, null); + when(kbService.listByAgentId(1L)).thenReturn(List.of(kb)); + when(pageService.listSummaries(100L)).thenReturn(List.of(simplePage("a", "A", null))); + + String out = service.buildWikiContext(1L); + + // The "multiple knowledge bases" hint is wasted prompt budget when + // there's only one KB; it must stay off. + assertThat(out).doesNotContain("Multiple knowledge bases visible"); + } } diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiDependencyServiceE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiDependencyServiceE2ETest.java new file mode 100644 index 00000000..625cba42 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiDependencyServiceE2ETest.java @@ -0,0 +1,97 @@ +package vip.mate.wiki.service; + +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPageEntity; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * End-to-end test of the dependency graph and stale propagation against H2: + * valid fact dependencies are recorded, illegal ones rejected, and updating a + * fact page marks its dependents stale. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiDependencyServiceE2ETest { + + @Autowired + private WikiDependencyService dependencyService; + @Autowired + private WikiPageService pageService; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + private WikiPageEntity factPage(long kb, String slug) { + WikiPageEntity p = pageService.createPage(kb, slug, "Fact " + slug, "body", "s", "[1]", "episode"); + pageService.setLayerAndDependencies(p.getId(), "fact", null); + return pageService.getBySlug(kb, slug); + } + + private WikiPageEntity experiencePage(long kb, String slug) { + WikiPageEntity p = pageService.createPage(kb, slug, "Exp " + slug, "body", "s", "[1]", "analysis"); + pageService.setLayerAndDependencies(p.getId(), "experience", null); + return pageService.getBySlug(kb, slug); + } + + @Test + void validFactDependency_isRecorded_andStalePropagates() { + long kb = SEQ.incrementAndGet(); + WikiPageEntity fact = factPage(kb, "fact-" + kb); + WikiPageEntity exp = experiencePage(kb, "exp-" + kb); + + List rejected = dependencyService.setDependencies(kb, exp.getId(), List.of(fact.getId())); + assertTrue(rejected.isEmpty(), () -> "unexpected rejections: " + rejected); + + // Fact page changes -> dependent experience page goes stale. + int marked = dependencyService.markDependentsStale(kb, fact.getId(), "fact body changed"); + assertEquals(1, marked); + + WikiPageEntity reloaded = pageService.getBySlug(kb, "exp-" + kb); + assertEquals(1, reloaded.getStale()); + assertTrue(reloaded.getStaleReasonJson().contains(String.valueOf(fact.getId()))); + + // Regenerating clears the flag. + pageService.clearStale(reloaded.getId()); + assertEquals(0, pageService.getBySlug(kb, "exp-" + kb).getStale()); + } + + @Test + void experienceTargetDependency_isRejected() { + long kb = SEQ.incrementAndGet(); + WikiPageEntity expA = experiencePage(kb, "expA-" + kb); + WikiPageEntity expB = experiencePage(kb, "expB-" + kb); + + // Depending on an experience page (not a fact) must be rejected. + List rejected = dependencyService.setDependencies(kb, expA.getId(), List.of(expB.getId())); + assertFalse(rejected.isEmpty()); + assertTrue(rejected.get(0).contains("not a fact-layer")); + + // No stale propagation since no edge was created. + assertEquals(0, dependencyService.markDependentsStale(kb, expB.getId(), "x")); + } + + @Test + void crossKbDependency_isRejected() { + long kbA = SEQ.incrementAndGet(); + long kbB = SEQ.incrementAndGet(); + WikiPageEntity factOther = factPage(kbB, "factB-" + kbB); + WikiPageEntity exp = experiencePage(kbA, "expA2-" + kbA); + + List rejected = dependencyService.setDependencies(kbA, exp.getId(), List.of(factOther.getId())); + assertFalse(rejected.isEmpty()); + assertTrue(rejected.get(0).contains("not found in this KB")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiEnrichmentApplierPhase5Test.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiEnrichmentApplierPhase5Test.java new file mode 100644 index 00000000..0201f86a --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiEnrichmentApplierPhase5Test.java @@ -0,0 +1,129 @@ +package vip.mate.wiki.service; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import vip.mate.wiki.dto.EnrichmentPlan; +import vip.mate.wiki.dto.EnrichmentReplacement; + +import java.util.List; +import java.util.Set; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * RFC §4 Phase 5 additions to {@link WikiEnrichmentApplier}: + *

      + *
    1. do not wrap text that already sits inside a fenced code block
      2. + *
    2. do not wrap text inside an inline {@code `code`} span
      3. + *
    3. when an allowed-slug whitelist is supplied, drop patches that + * target a slug outside the set (instead of failing the whole plan)
      4. + *
    + * These complement the existing PR-5b coverage; new tests live in a separate + * class so the originally-passing assertions stay independent. + */ +class WikiEnrichmentApplierPhase5Test { + + private static EnrichmentPlan plan(EnrichmentReplacement... rs) { + return new EnrichmentPlan(List.of(rs)); + } + + @Test + @DisplayName("does not wrap occurrences inside a fenced code block") + void skipsFencedCode() { + String src = "First, mention kubernetes in prose.\n\n" + + "```\n" + + "Then kubernetes inside a fence stays literal.\n" + + "```\n" + + "Closing kubernetes here too."; + WikiEnrichmentApplier.Result r = WikiEnrichmentApplier.apply(src, + plan(new EnrichmentReplacement("kubernetes", "[[kubernetes]]", 1))); + assertInstanceOf(WikiEnrichmentApplier.Result.Applied.class, r); + String out = r.content(); + // First prose occurrence: wrapped. + assertTrue(out.startsWith("First, mention [[kubernetes]] in prose."), + "first prose occurrence must wrap, got: " + out); + // Inside fence: unchanged. + assertTrue(out.contains("Then kubernetes inside a fence stays literal."), + "fenced occurrence must remain literal, got: " + out); + // Closing prose: NOT wrapped (occurrence=1 only). + assertTrue(out.endsWith("Closing kubernetes here too."), + "second prose occurrence not asked for, must remain literal, got: " + out); + } + + @Test + @DisplayName("wrap targets second prose occurrence when the first sits inside a fence") + void firstWrapTargetsFirstNonCodeOccurrence() { + String src = "```\nThe first kubernetes is in code.\n```\nThen kubernetes in prose."; + WikiEnrichmentApplier.Result r = WikiEnrichmentApplier.apply(src, + plan(new EnrichmentReplacement("kubernetes", "[[kubernetes]]", 1))); + assertInstanceOf(WikiEnrichmentApplier.Result.Applied.class, r); + String out = r.content(); + assertTrue(out.contains("The first kubernetes is in code."), + "fenced occurrence remains literal, got: " + out); + assertTrue(out.endsWith("Then [[kubernetes]] in prose."), + "prose occurrence (the first non-code one) is what gets wrapped, got: " + out); + } + + @Test + @DisplayName("does not wrap inside inline `code` spans") + void skipsInlineCode() { + String src = "Show `kubernetes` as inline code; mention kubernetes in prose."; + WikiEnrichmentApplier.Result r = WikiEnrichmentApplier.apply(src, + plan(new EnrichmentReplacement("kubernetes", "[[kubernetes]]", 1))); + assertInstanceOf(WikiEnrichmentApplier.Result.Applied.class, r); + String out = r.content(); + assertTrue(out.contains("`kubernetes`"), "inline code must stay literal: " + out); + assertTrue(out.contains("mention [[kubernetes]] in prose"), "prose wrapped: " + out); + } + + @Test + @DisplayName("whitelist drops patches whose target slug isn't allowed") + void whitelistDropsUnknownSlugs() { + String src = "Spring AI rocks; Linux too."; + Set allowed = Set.of("spring-ai"); + WikiEnrichmentApplier.Result r = WikiEnrichmentApplier.apply( + src, + plan( + new EnrichmentReplacement("Spring AI", "[[spring-ai|Spring AI]]", 1), + new EnrichmentReplacement("Linux", "[[linux|Linux]]", 1) + ), + WikiEnrichmentApplier.DEFAULT_MAX_REPLACEMENTS, + allowed); + assertInstanceOf(WikiEnrichmentApplier.Result.Applied.class, r); + String out = r.content(); + // spring-ai is in the whitelist → wrapped. + assertTrue(out.contains("[[spring-ai|Spring AI]]"), + "whitelisted slug must wrap, got: " + out); + // linux is NOT in the whitelist → silently dropped, original text intact. + assertTrue(out.contains("Linux too"), "dropped patch must leave text untouched, got: " + out); + assertTrue(!out.contains("[[linux"), "dropped patch must not produce a [[linux...]], got: " + out); + } + + @Test + @DisplayName("whitelist null disables the gate (legacy callers keep working)") + void whitelistNullDisablesGate() { + String src = "Linux is fine."; + WikiEnrichmentApplier.Result r = WikiEnrichmentApplier.apply( + src, + plan(new EnrichmentReplacement("Linux", "[[linux|Linux]]", 1)), + WikiEnrichmentApplier.DEFAULT_MAX_REPLACEMENTS, + null); + assertInstanceOf(WikiEnrichmentApplier.Result.Applied.class, r); + assertEquals("[[linux|Linux]] is fine.", r.content()); + } + + @Test + @DisplayName("whitelist empty drops every patch but keeps original content") + void whitelistEmptyDropsAll() { + String src = "Linux is fine."; + WikiEnrichmentApplier.Result r = WikiEnrichmentApplier.apply( + src, + plan(new EnrichmentReplacement("Linux", "[[linux|Linux]]", 1)), + WikiEnrichmentApplier.DEFAULT_MAX_REPLACEMENTS, + Set.of()); + assertInstanceOf(WikiEnrichmentApplier.Result.Unchanged.class, r); + assertEquals(src, r.content()); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiKnowledgeBaseServiceTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiKnowledgeBaseServiceTest.java index a012823c..6e445242 100644 --- a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiKnowledgeBaseServiceTest.java +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiKnowledgeBaseServiceTest.java @@ -2,6 +2,8 @@ package vip.mate.wiki.service; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; +import vip.mate.agent.model.AgentEntity; +import vip.mate.agent.repository.AgentMapper; import vip.mate.wiki.model.WikiKnowledgeBaseEntity; import vip.mate.wiki.repository.WikiKnowledgeBaseMapper; @@ -10,6 +12,7 @@ import java.util.List; import static org.assertj.core.api.Assertions.assertThat; import static org.mockito.ArgumentMatchers.any; import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; import static org.mockito.Mockito.when; /** @@ -24,24 +27,45 @@ import static org.mockito.Mockito.when; class WikiKnowledgeBaseServiceTest { private final WikiKnowledgeBaseMapper kbMapper = mock(WikiKnowledgeBaseMapper.class); + private final AgentMapper agentMapper = mock(AgentMapper.class); private final WikiKnowledgeBaseService service = new WikiKnowledgeBaseService( - kbMapper, null, null, null, null, null); + kbMapper, null, null, null, null, null, agentMapper); private static WikiKnowledgeBaseEntity kb(long id, Long agentId) { + return kb(id, agentId, null); + } + + private static WikiKnowledgeBaseEntity kb(long id, Long agentId, String name) { WikiKnowledgeBaseEntity entity = new WikiKnowledgeBaseEntity(); entity.setId(id); entity.setAgentId(agentId); + entity.setName(name); + return entity; + } + + private static WikiKnowledgeBaseEntity kb(long id, Long agentId, Long workspaceId, String name) { + WikiKnowledgeBaseEntity entity = kb(id, agentId, name); + entity.setWorkspaceId(workspaceId); + return entity; + } + + private static AgentEntity agent(long id, Long workspaceId, Long primaryKbId) { + AgentEntity entity = new AgentEntity(); + entity.setId(id); + entity.setWorkspaceId(workspaceId); + entity.setPrimaryKbId(primaryKbId); return entity; } @Test @DisplayName("prefers the agent's bound KB even when a shared KB was updated more recently") void prefersBoundKbOverNewerSharedKb() { + when(agentMapper.selectById(7L)).thenReturn(agent(7L, 1L, 100L)); // listByAgentId order is update_time DESC: two shared KBs precede the bound one. when(kbMapper.selectList(any())).thenReturn(List.of( - kb(900L, null), - kb(800L, null), - kb(100L, 7L))); + kb(900L, null, 1L, "Shared"), + kb(800L, 8L, 1L, "Legacy Other"), + kb(100L, null, 1L, "Primary"))); assertThat(service.resolvePrimaryKb(7L)).isNotNull(); assertThat(service.resolvePrimaryKb(7L).getId()).isEqualTo(100L); @@ -50,9 +74,34 @@ class WikiKnowledgeBaseServiceTest { @Test @DisplayName("falls back to the most recent shared KB when the agent has no bound KB") void fallsBackToSharedKbWhenNoneBound() { + when(agentMapper.selectById(7L)).thenReturn(agent(7L, 1L, null)); when(kbMapper.selectList(any())).thenReturn(List.of( - kb(900L, null), - kb(800L, null))); + kb(900L, 8L, 1L, "Most Recent"), + kb(800L, null, 1L, "Older"))); + + assertThat(service.resolvePrimaryKb(7L).getId()).isEqualTo(900L); + } + + @Test + @DisplayName("two agents can share the same primary KB") + void twoAgentsCanSharePrimaryKb() { + when(agentMapper.selectById(7L)).thenReturn(agent(7L, 1L, 100L)); + when(agentMapper.selectById(8L)).thenReturn(agent(8L, 1L, 100L)); + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(100L, null, 1L, "Shared Primary"), + kb(900L, null, 1L, "Fallback"))); + + assertThat(service.resolvePrimaryKb(7L).getId()).isEqualTo(100L); + assertThat(service.resolvePrimaryKb(8L).getId()).isEqualTo(100L); + } + + @Test + @DisplayName("primary KB pointing outside the agent workspace falls back") + void primaryKbOutsideWorkspaceFallsBack() { + when(agentMapper.selectById(7L)).thenReturn(agent(7L, 1L, 200L)); + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(900L, null, 1L, "Workspace Fallback"), + kb(200L, null, 2L, "Wrong Workspace"))); assertThat(service.resolvePrimaryKb(7L).getId()).isEqualTo(900L); } @@ -64,4 +113,118 @@ class WikiKnowledgeBaseServiceTest { assertThat(service.resolvePrimaryKb(7L)).isNull(); } + + // ==================== findByName ==================== + // + // The wiki tools added a kbName parameter so the LLM can target a + // non-primary KB. findByName is the resolution layer behind that + // parameter — it must restrict the match to KBs visible to the agent + // and refuse to silently fall through to the primary on a miss, so a + // bad pick surfaces as a clear "use wiki_list_kbs" hint instead of + // routing to the wrong KB. + + @Test + @DisplayName("findByName matches by exact name within the agent's visible set") + void findByNameMatchesVisibleKb() { + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(900L, null, "Shared Docs"), + kb(100L, 7L, "Agent Personal KB"))); + + WikiKnowledgeBaseEntity hit = service.findByName(7L, "Agent Personal KB"); + assertThat(hit).isNotNull(); + assertThat(hit.getId()).isEqualTo(100L); + + WikiKnowledgeBaseEntity sharedHit = service.findByName(7L, "Shared Docs"); + assertThat(sharedHit).isNotNull(); + assertThat(sharedHit.getId()).isEqualTo(900L); + } + + @Test + @DisplayName("findByName returns null when name does not match any visible KB") + void findByNameMissReturnsNull() { + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(900L, null, "Shared Docs"), + kb(100L, 7L, "Agent Personal KB"))); + + assertThat(service.findByName(7L, "Nonexistent KB")).isNull(); + } + + @Test + @DisplayName("findByName is case-sensitive — LLM must copy the name verbatim") + void findByNameIsCaseSensitive() { + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(100L, 7L, "Agent Personal KB"))); + + assertThat(service.findByName(7L, "agent personal kb")).isNull(); + assertThat(service.findByName(7L, "Agent Personal KB")).isNotNull(); + } + + @Test + @DisplayName("findByName returns null for blank / null kbName") + void findByNameBlankReturnsNull() { + assertThat(service.findByName(7L, null)).isNull(); + assertThat(service.findByName(7L, "")).isNull(); + assertThat(service.findByName(7L, " ")).isNull(); + } + + // ==================== findByName ambiguity + findAllByName + findVisibleById ==================== + // + // mate_wiki_knowledge_base has no unique constraint on name (one DB row + // per workspace + (name nullable + duplicates allowed) by design), so + // a non-blank kbName can match more than one visible KB. The single- + // result findByName must not silently pick "the first one" in that + // case — callers route through findAllByName + an ambiguous-error + // surface so the LLM is forced to disambiguate by kbId. + + @Test + @DisplayName("findByName returns null when more than one visible KB shares the name") + void findByNameAmbiguousReturnsNull() { + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(100L, 7L, "Docs"), + kb(900L, null, "Docs"))); + + assertThat(service.findByName(7L, "Docs")) + .as("ambiguous matches collapse to null — caller must use findAllByName") + .isNull(); + } + + @Test + @DisplayName("findAllByName returns every visible KB sharing the name") + void findAllByNameReturnsAllMatches() { + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(100L, 7L, "Docs"), + kb(900L, null, "Docs"), + kb(800L, null, "Other"))); + + List hits = service.findAllByName(7L, "Docs"); + assertThat(hits).hasSize(2); + assertThat(hits).extracting(WikiKnowledgeBaseEntity::getId).containsExactly(100L, 900L); + } + + @Test + @DisplayName("findAllByName returns empty for blank kbName") + void findAllByNameBlankReturnsEmpty() { + assertThat(service.findAllByName(7L, null)).isEmpty(); + assertThat(service.findAllByName(7L, " ")).isEmpty(); + } + + @Test + @DisplayName("findVisibleById returns the KB only when it is in the agent's visibility set") + void findVisibleByIdGate() { + when(agentMapper.selectById(7L)).thenReturn(agent(7L, 1L, null)); + when(kbMapper.selectList(any())).thenReturn(List.of( + kb(100L, 7L, "Bound KB"), + kb(900L, null, "Shared KB"), + kb(800L, 8L, "Other Agent Primary KB"))); + + // Visible: returned. + assertThat(service.findVisibleById(7L, 100L)).isNotNull(); + assertThat(service.findVisibleById(7L, 900L)).isNotNull(); + assertThat(service.findVisibleById(7L, 800L)).isNotNull(); + + // Not in visibility set: deliberate fail-closed gate so an LLM + // can't pivot to an arbitrary KB by guessing an id. + assertThat(service.findVisibleById(7L, 99999L)).isNull(); + assertThat(service.findVisibleById(7L, null)).isNull(); + } } diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiLinkServiceCascadeTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiLinkServiceCascadeTest.java new file mode 100644 index 00000000..a38e9df2 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiLinkServiceCascadeTest.java @@ -0,0 +1,120 @@ +package vip.mate.wiki.service; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Behavioural coverage for the cascade-rewrite helpers in + * {@link WikiLinkService}. Each test pins down one of the protective rules + * the cascade delete/rename pipeline depends on: + * + *
      + *
    • bare {@code [[slug]]} demotes to the snapshot title, alias form + * keeps the alias text, miss-slugs untouched
      • + *
    • case-insensitive on the slug part only — aliases are display text + * and must not be matched against
      • + *
    • code fences and inline code are preserved literally — a doc that + * teaches wikilink syntax must not be rewritten on delete
      • + *
    • rename rewrites {@code [[a]]} → {@code [[b]]} and + * {@code [[a|alias]]} → {@code [[b|alias]]}
      • + *
    + */ +class WikiLinkServiceCascadeTest { + + private final WikiLinkService svc = new WikiLinkService(new ObjectMapper()); + + @Test + void stripBareWikilinkUsesSnapshotTitle() { + String out = svc.stripDeletedLink( + "See [[deprecated-concept]] for context.", + "deprecated-concept", "Deprecated Concept"); + assertEquals("See Deprecated Concept for context.", out); + } + + @Test + void stripAliasedWikilinkKeepsAlias() { + String out = svc.stripDeletedLink( + "More on [[deprecated-concept|that old idea]] later.", + "deprecated-concept", "Deprecated Concept"); + assertEquals("More on that old idea later.", out); + } + + @Test + void stripIsCaseInsensitiveOnSlug() { + String out = svc.stripDeletedLink( + "Both [[Foo]] and [[FOO]] go away.", + "foo", "Foo Page"); + assertEquals("Both Foo Page and Foo Page go away.", out); + } + + @Test + void stripLeavesUnrelatedWikilinksAlone() { + String input = "[[keep-me]] stays; [[delete-me]] does not."; + String out = svc.stripDeletedLink(input, "delete-me", "Delete Me"); + assertEquals("[[keep-me]] stays; Delete Me does not.", out); + } + + @Test + void stripSkipsFencedCodeBlocks() { + String input = "Outside [[a]] gone.\n\n```\nInside [[a]] stays.\n```\n"; + String out = svc.stripDeletedLink(input, "a", "A Page"); + // outside replaced, inside literal + assertTrue(out.startsWith("Outside A Page gone."), + "outside should be replaced, got: " + out); + assertTrue(out.contains("Inside [[a]] stays."), + "fenced [[a]] must be preserved, got: " + out); + } + + @Test + void stripSkipsInlineCodeSpans() { + String input = "Use `[[a]]` to link, e.g. [[a]] in prose."; + String out = svc.stripDeletedLink(input, "a", "A Page"); + // inline-code [[a]] preserved, prose [[a]] demoted + assertTrue(out.contains("`[[a]]`"), + "inline code must be preserved, got: " + out); + assertTrue(out.contains("A Page in prose"), + "prose occurrence must be replaced, got: " + out); + } + + @Test + void stripFallsBackToSlugWhenSnapshotMissing() { + String out = svc.stripDeletedLink("See [[a]] here.", "a", null); + assertEquals("See a here.", out); + } + + @Test + void renameRewritesBareWikilink() { + String out = svc.renameLink("Link to [[old-slug]].", "old-slug", "new-slug"); + assertEquals("Link to [[new-slug]].", out); + } + + @Test + void renameRewritesAliasedWikilink() { + String out = svc.renameLink("Read [[old-slug|the manifesto]].", "old-slug", "new-slug"); + assertEquals("Read [[new-slug|the manifesto]].", out); + } + + @Test + void renameIsCaseInsensitiveOnSlug() { + String out = svc.renameLink("Both [[OLD-slug]] and [[Old-Slug|x]] should move.", + "old-slug", "new-slug"); + assertEquals("Both [[new-slug]] and [[new-slug|x]] should move.", out); + } + + @Test + void renameSkipsCodeBlocks() { + String input = "Outside [[old]] moves.\n\n```\nInside [[old]] does not.\n```\n"; + String out = svc.renameLink(input, "old", "new"); + assertTrue(out.contains("Outside [[new]] moves.")); + assertTrue(out.contains("Inside [[old]] does not.")); + } + + @Test + void renameLeavesUnrelatedWikilinksAlone() { + String out = svc.renameLink("[[a]] and [[b]] are friends.", "a", "x"); + assertEquals("[[x]] and [[b]] are friends.", out); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageMetadataE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageMetadataE2ETest.java new file mode 100644 index 00000000..ef89ed38 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageMetadataE2ETest.java @@ -0,0 +1,66 @@ +package vip.mate.wiki.service; + +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiPageEntity; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; + +/** + * Verifies the structured-metadata persistence path against H2: applyMetadata + * writes the metadata columns without disturbing the page content (partial + * column update). + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999" + } +) +class WikiPageMetadataE2ETest { + + @Autowired + private WikiPageService pageService; + + // Persistent file-DB isolation: fresh kb ids per test. + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + @Test + void applyMetadata_persistsColumns_withoutTouchingContent() { + long kb = SEQ.incrementAndGet(); + WikiPageEntity page = pageService.createPage(kb, "episode-x", "Episode X", + "## Body\n\noriginal content", "summary", "[1]", "episode"); + assertNotNull(page.getId()); + + pageService.applyMetadata(page.getId(), + "{\"event_date\":\"2024-09-18\"}", "ok", null, 3); + + WikiPageEntity loaded = pageService.getBySlug(kb, "episode-x"); + assertEquals("{\"event_date\":\"2024-09-18\"}", loaded.getMetadataJson()); + assertEquals("ok", loaded.getMetadataValidationStatus()); + assertEquals(3, loaded.getProfileVersion()); + // Partial update must not have wiped content / summary. + assertEquals("## Body\n\noriginal content", loaded.getContent()); + assertEquals("summary", loaded.getSummary()); + } + + @Test + void applyMetadata_warningStatusAndJson() { + long kb = SEQ.incrementAndGet(); + WikiPageEntity page = pageService.createPage(kb, "episode-y", "Episode Y", + "body", "summary", "[1]", "episode"); + + pageService.applyMetadata(page.getId(), + "{\"event_date\":\"bad\"}", "warning", + "[{\"field\":\"event_date\",\"reason\":\"expected ISO date YYYY-MM-DD\"}]", 1); + + WikiPageEntity loaded = pageService.getBySlug(kb, "episode-y"); + assertEquals("warning", loaded.getMetadataValidationStatus()); + assertNotNull(loaded.getMetadataValidationJson()); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageServiceTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageServiceTest.java index 1ea7a81f..4288363f 100644 --- a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageServiceTest.java +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageServiceTest.java @@ -31,7 +31,9 @@ class WikiPageServiceTest { when(mapper.selectOne(any())).thenReturn(page); when(mapper.updateById(any(WikiPageEntity.class))).thenReturn(1); - new WikiPageService(mapper, new ObjectMapper()) + ObjectMapper om = new ObjectMapper(); + WikiLinkService link = new WikiLinkService(om); + new WikiPageService(mapper, om, link) .updatePageManually(7L, "page", "new body", null); assertTrue(page.getUpdateTime().isAfter(oldUpdateTime)); diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageTypePermissionServiceTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageTypePermissionServiceTest.java new file mode 100644 index 00000000..637b4cc2 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiPageTypePermissionServiceTest.java @@ -0,0 +1,192 @@ +package vip.mate.wiki.service; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.Test; +import vip.mate.wiki.model.WikiAgentPageTypePermissionEntity; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.repository.WikiAgentPageTypePermissionMapper; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link WikiPageTypePermissionService} precedence and default + * policy resolution. Mapper and KB service are mocked so no Spring context or + * DB is needed. + */ +class WikiPageTypePermissionServiceTest { + + private static final long AGENT = 1L; + private static final long KB = 7L; + + private WikiPageTypePermissionService service(List rows, String configJson) { + WikiAgentPageTypePermissionMapper mapper = mock(WikiAgentPageTypePermissionMapper.class); + when(mapper.selectList(any())).thenReturn(rows); + WikiKnowledgeBaseService kbService = mock(WikiKnowledgeBaseService.class); + WikiKnowledgeBaseEntity kb = new WikiKnowledgeBaseEntity(); + kb.setId(KB); + kb.setConfigContent(configJson); + when(kbService.getById(KB)).thenReturn(kb); + return new WikiPageTypePermissionService(mapper, kbService, new ObjectMapper()); + } + + private WikiAgentPageTypePermissionEntity row(String type, int read, int create, int update, + int delete, String writePolicy) { + WikiAgentPageTypePermissionEntity e = new WikiAgentPageTypePermissionEntity(); + e.setAgentId(AGENT); + e.setKbId(KB); + e.setPageType(type); + e.setCanRead(read); + e.setCanCreate(create); + e.setCanUpdate(update); + e.setCanDelete(delete); + e.setWritePolicy(writePolicy); + return e; + } + + @Test + void noRowsNoConfig_readsAllowed_writesAllowedOptIn() { + WikiPageTypePermissionService s = service(List.of(), null); + assertTrue(s.canRead(AGENT, KB, "concept")); + assertEquals(WikiPageTypePermissionService.WriteDecision.ALLOW, + s.resolveWrite(AGENT, KB, "concept", WikiPageTypePermissionService.WriteOp.CREATE)); + } + + @Test + void noRows_denyAllConfig_readsDenied() { + WikiPageTypePermissionService s = service(List.of(), "{\"defaultReadPolicy\":\"deny_all\"}"); + assertFalse(s.canRead(AGENT, KB, "concept")); + } + + @Test + void exactRowWinsOverWildcard_forRead() { + // wildcard allows read, but the exact 'analysis' row forbids it + List rows = List.of( + row("*", 1, 0, 0, 0, "deny"), + row("analysis", 0, 0, 0, 0, "deny")); + WikiPageTypePermissionService s = service(rows, null); + assertFalse(s.canRead(AGENT, KB, "analysis")); // exact row forbids + assertTrue(s.canRead(AGENT, KB, "concept")); // falls to wildcard allow + } + + @Test + void wildcardAppliesWhenNoExactMatch() { + WikiPageTypePermissionService s = service(List.of(row("*", 0, 0, 0, 0, "deny")), null); + assertFalse(s.canRead(AGENT, KB, "anything")); + } + + @Test + void readIsCaseInsensitiveOnPageType() { + WikiPageTypePermissionService s = service(List.of(row("Episode", 0, 0, 0, 0, "deny")), null); + assertFalse(s.canRead(AGENT, KB, "episode")); + } + + @Test + void writeResolution_perOperationFlagAndPolicy() { + // create allowed but gated by approval; delete flag off → denied + WikiPageTypePermissionService s = service( + List.of(row("episode", 1, 1, 0, 0, "approval_required")), null); + assertEquals(WikiPageTypePermissionService.WriteDecision.APPROVAL_REQUIRED, + s.resolveWrite(AGENT, KB, "episode", WikiPageTypePermissionService.WriteOp.CREATE)); + assertEquals(WikiPageTypePermissionService.WriteDecision.DENY, + s.resolveWrite(AGENT, KB, "episode", WikiPageTypePermissionService.WriteOp.DELETE)); + } + + @Test + void writeAllowPolicyResolvesToAllow() { + WikiPageTypePermissionService s = service( + List.of(row("episode", 1, 1, 1, 1, "allow")), null); + assertEquals(WikiPageTypePermissionService.WriteDecision.ALLOW, + s.resolveWrite(AGENT, KB, "episode", WikiPageTypePermissionService.WriteOp.UPDATE)); + } + + @Test + void rowsExistButTypeUncovered_writeIsFailSafeDeny() { + // KB is gated (a row exists) but no row covers 'concept' and no wildcard + WikiPageTypePermissionService s = service( + List.of(row("episode", 1, 1, 1, 1, "allow")), null); + assertEquals(WikiPageTypePermissionService.WriteDecision.DENY, + s.resolveWrite(AGENT, KB, "concept", WikiPageTypePermissionService.WriteOp.CREATE)); + } + + @Test + void rowsExistButTypeUncovered_readFallsToDefaultPolicy() { + // a row exists for 'episode' only; 'concept' read falls to KB default (allow_all) + WikiPageTypePermissionService s = service( + List.of(row("episode", 0, 0, 0, 0, "deny")), null); + assertTrue(s.canRead(AGENT, KB, "concept")); + } + + @Test + void nullAgent_isAllowAll() { + WikiPageTypePermissionService s = service(List.of(), "{\"defaultReadPolicy\":\"deny_all\"}"); + assertTrue(s.canRead(null, KB, "concept")); + } + + // ==================== CRUD ==================== + + @Test + void saveRow_insertsWhenAbsent_normalizesTypeAndPolicy() { + WikiAgentPageTypePermissionMapper mapper = mock(WikiAgentPageTypePermissionMapper.class); + when(mapper.selectOne(any())).thenReturn(null); // no existing row + WikiPageTypePermissionService s = new WikiPageTypePermissionService( + mapper, mock(WikiKnowledgeBaseService.class), new ObjectMapper()); + + WikiAgentPageTypePermissionEntity in = row("Episode", 1, 1, 0, 0, "BOGUS"); + in.setId(999L); // must be cleared on insert + WikiAgentPageTypePermissionEntity saved = s.saveRow(in); + + assertEquals("episode", saved.getPageType()); // lowercased + assertEquals("approval_required", saved.getWritePolicy()); // unknown → safe default + assertNull(saved.getId()); // id cleared for insert + verify(mapper).insert((WikiAgentPageTypePermissionEntity) saved); + verify(mapper, never()).updateById((WikiAgentPageTypePermissionEntity) any()); + } + + @Test + void saveRow_updatesInPlaceWhenExisting() { + WikiAgentPageTypePermissionMapper mapper = mock(WikiAgentPageTypePermissionMapper.class); + WikiAgentPageTypePermissionEntity existing = row("episode", 0, 0, 0, 0, "deny"); + existing.setId(42L); + when(mapper.selectOne(any())).thenReturn(existing); + WikiPageTypePermissionService s = new WikiPageTypePermissionService( + mapper, mock(WikiKnowledgeBaseService.class), new ObjectMapper()); + + WikiAgentPageTypePermissionEntity in = row("episode", 1, 1, 1, 1, "allow"); + WikiAgentPageTypePermissionEntity saved = s.saveRow(in); + + assertEquals(42L, saved.getId()); // adopts existing id + verify(mapper).updateById((WikiAgentPageTypePermissionEntity) saved); + verify(mapper, never()).insert((WikiAgentPageTypePermissionEntity) any()); + } + + @Test + void saveRow_blankPageTypeBecomesWildcard() { + WikiAgentPageTypePermissionMapper mapper = mock(WikiAgentPageTypePermissionMapper.class); + when(mapper.selectOne(any())).thenReturn(null); + WikiPageTypePermissionService s = new WikiPageTypePermissionService( + mapper, mock(WikiKnowledgeBaseService.class), new ObjectMapper()); + + WikiAgentPageTypePermissionEntity in = row(" ", 1, 0, 0, 0, "allow"); + assertEquals(WikiPageTypePermissionService.WILDCARD, s.saveRow(in).getPageType()); + } + + @Test + void deleteRow_returnsTrueWhenRowRemoved() { + WikiAgentPageTypePermissionMapper mapper = mock(WikiAgentPageTypePermissionMapper.class); + when(mapper.deleteById(5L)).thenReturn(1); + WikiPageTypePermissionService s = new WikiPageTypePermissionService( + mapper, mock(WikiKnowledgeBaseService.class), new ObjectMapper()); + assertTrue(s.deleteRow(5L)); + assertFalse(s.deleteRow(null)); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingFallbackTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingFallbackTest.java index 1994e8cf..0dce5681 100644 --- a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingFallbackTest.java +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingFallbackTest.java @@ -54,16 +54,18 @@ class WikiProcessingFallbackTest { modelProviderService = mock(ModelProviderService.class); healthTracker = mock(ProviderHealthTracker.class); + ObjectMapper om = new ObjectMapper(); service = new WikiProcessingService( mock(WikiKnowledgeBaseService.class), mock(WikiRawMaterialService.class), mock(WikiPageService.class), mock(WikiChunkService.class), mock(WikiEmbeddingService.class), + new WikiLinkService(om), new WikiProperties(), modelConfigService, agentGraphBuilder, - new ObjectMapper(), + om, mock(WikiProgressBus.class), mock(WikiCitationService.class), mock(ApplicationEventPublisher.class)); diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingServiceLazyTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingServiceLazyTest.java index f17a8b69..f49591a0 100644 --- a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingServiceLazyTest.java +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiProcessingServiceLazyTest.java @@ -61,9 +61,11 @@ class WikiProcessingServiceLazyTest { progressBus = mock(WikiProgressBus.class); citationService = mock(WikiCitationService.class); + ObjectMapper om = new ObjectMapper(); service = new WikiProcessingService( kbService, rawService, pageService, chunkService, embeddingService, - properties, modelConfigService, agentGraphBuilder, new ObjectMapper(), + new WikiLinkService(om), + properties, modelConfigService, agentGraphBuilder, om, progressBus, citationService, mock(org.springframework.context.ApplicationEventPublisher.class)); } diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiScanSizeGuardE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiScanSizeGuardE2ETest.java new file mode 100644 index 00000000..775422c3 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiScanSizeGuardE2ETest.java @@ -0,0 +1,60 @@ +package vip.mate.wiki.service; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Verifies the scan re-checks the resolved target's size, so an oversized file + * reached through a symlink (whose own attribute size is just the link length) + * cannot slip past the max-scan-file-size gate. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999", + "mate.wiki.auto-process-on-upload=false", + "mate.wiki.max-scan-file-size=200" + } +) +class WikiScanSizeGuardE2ETest { + + @Autowired + private WikiDirectoryScanService scanService; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + @Test + void oversizedTargetReachedViaSymlink_isSkipped(@TempDir Path dir) throws IOException { + // 5000-byte file far exceeds the 200-byte cap; a RELATIVE symlink to it + // has a tiny attribute size (the short link path) that passes the + // visitFile gate, so only the resolved-target re-check can stop it. + Path big = dir.resolve("big.pdf"); + Files.write(big, new byte[5000]); + Path link = dir.resolve("link.pdf"); + try { + Files.createSymbolicLink(link, big.getFileName()); // relative -> "big.pdf" + } catch (UnsupportedOperationException | IOException e) { + return; // no symlink support — skip + } + + WikiDirectoryScanService.ScanResult result = + scanService.scanDirectory(SEQ.incrementAndGet(), dir.toString()); + + // Neither the oversized file nor the symlink to it is ingested. + assertEquals(0, result.added(), "oversized target must not be ingested via a symlink"); + assertTrue(result.errors().stream().anyMatch(e -> e.contains("oversized")), + "the resolved-target size check should report the oversized skip"); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourcePathValidatorTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourcePathValidatorTest.java new file mode 100644 index 00000000..df7eaee6 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourcePathValidatorTest.java @@ -0,0 +1,81 @@ +package vip.mate.wiki.service; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import vip.mate.wiki.WikiProperties; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Unit tests for {@link WikiSourcePathValidator}: empty roots allow anything + * (opt-in), configured roots enforce containment, and symlinks are resolved so + * they cannot escape an allowed root. + */ +class WikiSourcePathValidatorTest { + + private WikiSourcePathValidator validator(List roots) { + WikiProperties props = new WikiProperties(); + props.setAllowedSourceRoots(roots); + return new WikiSourcePathValidator(props); + } + + private WikiSourcePathValidator failClosedValidator() { + WikiProperties props = new WikiProperties(); + props.setRequireAllowedRoots(true); + return new WikiSourcePathValidator(props); + } + + @Test + void blankPath_rejected() { + assertThrows(IllegalArgumentException.class, () -> validator(List.of()).validateDirectory(" ")); + } + + @Test + void emptyRoots_allowAnyPath(@TempDir Path tmp) throws IOException { + Path resolved = validator(List.of()).validateDirectory(tmp.toString()); + assertEquals(tmp.toRealPath(), resolved); + } + + @Test + void emptyRoots_failClosed_rejectsEverything(@TempDir Path tmp) { + // With require-allowed-roots enabled, an empty allow-list denies all. + assertThrows(IllegalArgumentException.class, + () -> failClosedValidator().validateDirectory(tmp.toString())); + } + + @Test + void insideAllowedRoot_isAccepted(@TempDir Path root) throws IOException { + Path sub = Files.createDirectory(root.resolve("kb-source")); + WikiSourcePathValidator v = validator(List.of(root.toString())); + assertTrue(v.isAllowed(sub.toString())); + } + + @Test + void outsideAllowedRoot_isRejected(@TempDir Path root, @TempDir Path other) { + WikiSourcePathValidator v = validator(List.of(root.toString())); + assertFalse(v.isAllowed(other.toString())); + assertThrows(IllegalArgumentException.class, () -> v.validateDirectory(other.toString())); + } + + @Test + void symlinkEscapingRoot_isRejected(@TempDir Path root, @TempDir Path secret) throws IOException { + // A symlink inside the allowed root that points outside must be rejected + // because validation resolves the real path first. + Path link = root.resolve("escape"); + try { + Files.createSymbolicLink(link, secret); + } catch (UnsupportedOperationException | IOException e) { + return; // filesystem without symlink support — skip + } + WikiSourcePathValidator v = validator(List.of(root.toString())); + assertFalse(v.isAllowed(link.toString())); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourceWatcherServiceE2ETest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourceWatcherServiceE2ETest.java new file mode 100644 index 00000000..d669117b --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiSourceWatcherServiceE2ETest.java @@ -0,0 +1,112 @@ +package vip.mate.wiki.service; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * End-to-end test of the source watcher's scan cycle against H2: new files in a + * KB's source directory are auto-ingested, and a re-scan is idempotent (dedup + * by source path). Auto-processing is disabled so the test stays model-free. + */ +@SpringBootTest( + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "spring.flyway.enabled=true", + "spring.flyway.locations=classpath:db/migration/h2", + "mateclaw.feature-flag.refresh-ms=999999", + "mate.wiki.auto-process-on-upload=false" + } +) +class WikiSourceWatcherServiceE2ETest { + + @Autowired + private WikiSourceWatcherService watcherService; + @Autowired + private WikiKnowledgeBaseService kbService; + @Autowired + private WikiDirectoryScanService scanService; + + private static final java.util.concurrent.atomic.AtomicLong SEQ = + new java.util.concurrent.atomic.AtomicLong(System.nanoTime()); + + @Test + void scanCycleIngestsNewFiles_thenDedups(@TempDir Path sourceDir) throws IOException { + Files.writeString(sourceDir.resolve("note-a.md"), "# Note A\n\ncontent a"); + Files.writeString(sourceDir.resolve("note-b.md"), "# Note B\n\ncontent b"); + + WikiKnowledgeBaseEntity kb = kbService.create( + "watcher-" + SEQ.incrementAndGet(), "test", null); + kbService.updateSourceDirectory(kb.getId(), sourceDir.toString()); + + // First cycle ingests both new files. + int firstAdded = watcherService.runScanCycle(); + assertTrue(firstAdded >= 2, "expected >= 2 new files, got " + firstAdded); + + // A new file appears; the next cycle ingests only it (existing files dedup). + Files.writeString(sourceDir.resolve("note-c.md"), "# Note C\n\ncontent c"); + int secondAdded = watcherService.runScanCycle(); + assertEquals(1, secondAdded, "only the newly added file should ingest"); + + // Re-scanning with no changes ingests nothing. + assertEquals(0, watcherService.runScanCycle(), "unchanged files must not re-ingest"); + + // Modifying an existing file's content re-ingests it (content hash changed). + Files.writeString(sourceDir.resolve("note-a.md"), "# Note A\n\nEDITED content a"); + int afterEdit = watcherService.runScanCycle(); + assertEquals(1, afterEdit, "a modified file must be re-ingested"); + } + + @Test + void symlinkFileEscapingScanRoot_isNotIngested(@TempDir Path sourceDir, @TempDir Path outside) + throws java.io.IOException { + Files.writeString(sourceDir.resolve("real.md"), "# Real\n\nlocal content"); + Path secret = Files.writeString(outside.resolve("secret.md"), "TOP SECRET OUTSIDE"); + Path link = sourceDir.resolve("leak.md"); + try { + Files.createSymbolicLink(link, secret); + } catch (UnsupportedOperationException | java.io.IOException e) { + return; // filesystem without symlink support — skip + } + + long kb = SEQ.incrementAndGet(); + WikiDirectoryScanService.ScanResult result = scanService.scanDirectory(kb, sourceDir.toString()); + + // Only the real file is ingested; the symlink escaping the root is skipped. + assertEquals(1, result.added(), "symlinked file pointing outside the root must not be ingested"); + assertTrue(result.skipped() >= 1 || !result.errors().isEmpty(), + "the escaping symlink should be reported as skipped"); + } + + @Test + void modifiedBinaryFile_isReingested(@TempDir Path sourceDir) throws java.io.IOException { + Path pdf = sourceDir.resolve("doc.pdf"); + Files.write(pdf, "PDF-VERSION-ONE-bytes".getBytes()); + long kb = SEQ.incrementAndGet(); + + assertEquals(1, scanService.scanDirectory(kb, sourceDir.toString()).added()); + // Unchanged binary re-scan ingests nothing. + assertEquals(0, scanService.scanDirectory(kb, sourceDir.toString()).added()); + // Changed bytes -> different content hash -> re-ingested. + Files.write(pdf, "PDF-VERSION-TWO-different-bytes".getBytes()); + assertEquals(1, scanService.scanDirectory(kb, sourceDir.toString()).added(), + "a modified binary file must be re-ingested"); + } + + @Test + void kbsWithoutSourceDirectory_areSkipped() { + // A KB with no source directory must not cause errors in the cycle. + kbService.create("nodir-" + SEQ.incrementAndGet(), "test", null); + // Should complete without throwing (count is non-negative). + assertTrue(watcherService.runScanCycle() >= 0); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiStalePropagationListenerTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiStalePropagationListenerTest.java new file mode 100644 index 00000000..23ee3664 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/service/WikiStalePropagationListenerTest.java @@ -0,0 +1,38 @@ +package vip.mate.wiki.service; + +import org.junit.jupiter.api.Test; +import vip.mate.wiki.event.WikiFactPageUpdatedEvent; + +import static org.mockito.Mockito.doThrow; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Unit tests for {@link WikiStalePropagationListener}: it forwards a fact-page + * update to the dependency engine and never lets a failure escape (so a broken + * propagation cannot disturb ingest). + */ +class WikiStalePropagationListenerTest { + + @Test + void forwardsToMarkDependentsStale() { + WikiDependencyService dep = mock(WikiDependencyService.class); + when(dep.markDependentsStale(7L, 100L, "r")).thenReturn(2); + + new WikiStalePropagationListener(dep) + .onFactPageUpdated(new WikiFactPageUpdatedEvent(7L, 100L, "r")); + + verify(dep).markDependentsStale(7L, 100L, "r"); + } + + @Test + void swallowsFailure() { + WikiDependencyService dep = mock(WikiDependencyService.class); + doThrow(new RuntimeException("boom")).when(dep).markDependentsStale(7L, 100L, "r"); + + // Must not throw. + new WikiStalePropagationListener(dep) + .onFactPageUpdated(new WikiFactPageUpdatedEvent(7L, 100L, "r")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolKbNameRoutingTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolKbNameRoutingTest.java new file mode 100644 index 00000000..bde61503 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolKbNameRoutingTest.java @@ -0,0 +1,290 @@ +package vip.mate.wiki.tool; + +import cn.hutool.json.JSONArray; +import cn.hutool.json.JSONObject; +import cn.hutool.json.JSONUtil; +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.service.HybridRetriever; +import vip.mate.wiki.service.WikiKnowledgeBaseService; +import vip.mate.wiki.service.WikiPageService; +import vip.mate.wiki.service.WikiRawMaterialService; + +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +/** + * Routing-level coverage for the {@code kbName} / {@code kbId} resolver + * shared by every wiki tool (exercised through {@code wiki_list_pages} and + * {@code wiki_list_kbs}). + * + *

    The behaviour these tests pin in place is the fix for the upstream + * "single-KB collapse" bug: when an agent reaches more than one knowledge + * base, every wiki tool used to silently operate on whichever KB the + * primary-fallback picked, with no way for the LLM to target a different + * one. The fix shipped in three layers: + *

      + *
    1. blank {@code kbName} + blank {@code kbId} → still routes to the + * primary KB so the single-KB UX stays zero-config;
      2. + *
    2. named {@code kbName} that matches exactly one visible KB → routes + * to that KB, not the primary;
      3. + *
    3. named {@code kbName} that doesn't match any visible KB → fail-closed + * error naming the bad pick and pointing at {@code wiki_list_kbs};
      4. + *
    4. named {@code kbName} that matches MORE than one visible KB (the + * schema has no unique constraint on KB name) → fail-closed error + * listing every candidate's {@code kbId} so the LLM can retry via + * {@code kbId} instead;
      5. + *
    5. {@code kbId} provided → uses {@link WikiKnowledgeBaseService#findVisibleById} + * (visibility gate enforced; out-of-set ids fail closed);
      6. + *
    6. {@code wiki_list_kbs} surfaces every visible KB with {@code kbId} + * rendered as a String (workspace-wide Snowflake-precision rule), + * plus {@code isPrimary} / {@code boundToAgent} flags.
      7. + *
    + */ +class WikiToolKbNameRoutingTest { + + private static final Long AGENT = 7L; + private static final long PRIMARY_KB = 100L; + private static final long OTHER_KB = 200L; + private static final long DUP_BOUND_KB = 300L; + private static final long DUP_SHARED_KB = 400L; + + private final WikiPageService pageService = mock(WikiPageService.class); + private final WikiKnowledgeBaseService kbService = mock(WikiKnowledgeBaseService.class); + private final WikiRawMaterialService rawService = mock(WikiRawMaterialService.class); + private final HybridRetriever hybridRetriever = mock(HybridRetriever.class); + private final ObjectMapper objectMapper = new ObjectMapper(); + + // Allow-all permission service (no rows configured) — this test exercises + // KB-name routing, not permissions. + private final vip.mate.wiki.service.WikiPageTypePermissionService permissionService = + new vip.mate.wiki.service.WikiPageTypePermissionService( + mock(vip.mate.wiki.repository.WikiAgentPageTypePermissionMapper.class), kbService, objectMapper); + + private final WikiTool tool = new WikiTool(pageService, kbService, rawService, + hybridRetriever, objectMapper, permissionService); + + private static WikiKnowledgeBaseEntity kb(long id, String name, Long agentId) { + WikiKnowledgeBaseEntity entity = new WikiKnowledgeBaseEntity(); + entity.setId(id); + entity.setName(name); + entity.setAgentId(agentId); + entity.setPageCount(0); + return entity; + } + + private static WikiPageEntity page(String slug, String title) { + WikiPageEntity entity = new WikiPageEntity(); + entity.setSlug(slug); + entity.setTitle(title); + entity.setPageType("user"); + return entity; + } + + /** Mock listSummaries to return KB-specific page slugs so the test can + * prove which KB the tool actually queried. */ + private void wirePages() { + when(pageService.listSummaries(eq(PRIMARY_KB))).thenReturn(List.of( + page("primary-only-slug", "Primary KB Page"))); + when(pageService.listSummaries(eq(OTHER_KB))).thenReturn(List.of( + page("other-only-slug", "Other KB Page"))); + when(pageService.listSummaries(eq(DUP_BOUND_KB))).thenReturn(List.of( + page("dup-bound-slug", "Bound Docs Page"))); + when(pageService.listSummaries(eq(DUP_SHARED_KB))).thenReturn(List.of( + page("dup-shared-slug", "Shared Docs Page"))); + } + + // ==================== wiki_list_pages routing — happy paths ==================== + + @Test + @DisplayName("blank kbName + blank kbId routes to the primary KB") + void blankRoutesToPrimary() { + wirePages(); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + + String json = tool.wiki_list_pages(AGENT, null, null, null); + JSONObject obj = JSONUtil.parseObj(json); + + JSONArray pages = obj.getJSONArray("pages"); + assertThat(pages).hasSize(1); + assertThat(pages.getJSONObject(0).getStr("slug")).isEqualTo("primary-only-slug"); + } + + @Test + @DisplayName("known kbName routes to that KB instead of the primary") + void namedKbNameRoutesToNamedKb() { + wirePages(); + // Primary fallback still wired so the test would fail loudly if the + // tool silently used it despite a non-blank kbName. + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + when(kbService.findAllByName(AGENT, "Other")).thenReturn(List.of(kb(OTHER_KB, "Other", null))); + + String json = tool.wiki_list_pages(AGENT, null, "Other", null); + JSONObject obj = JSONUtil.parseObj(json); + + JSONArray pages = obj.getJSONArray("pages"); + assertThat(pages).hasSize(1); + assertThat(pages.getJSONObject(0).getStr("slug")).isEqualTo("other-only-slug"); + } + + @Test + @DisplayName("kbId routes through the visibility gate to that KB") + void kbIdRoutesViaVisibilityGate() { + wirePages(); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + when(kbService.findVisibleById(AGENT, OTHER_KB)).thenReturn(kb(OTHER_KB, "Other", null)); + + String json = tool.wiki_list_pages(AGENT, null, null, OTHER_KB); + JSONObject obj = JSONUtil.parseObj(json); + + assertThat(obj.getJSONArray("pages").getJSONObject(0).getStr("slug")) + .isEqualTo("other-only-slug"); + } + + @Test + @DisplayName("kbId wins when both kbName and kbId are supplied") + void kbIdWinsOverKbName() { + wirePages(); + when(kbService.findVisibleById(AGENT, OTHER_KB)).thenReturn(kb(OTHER_KB, "Other", null)); + // Deliberately do NOT stub findAllByName — if the tool consulted + // kbName at all (or fell back to primary), the call would NPE. + + String json = tool.wiki_list_pages(AGENT, null, "anything", OTHER_KB); + JSONObject obj = JSONUtil.parseObj(json); + assertThat(obj.getJSONArray("pages").getJSONObject(0).getStr("slug")) + .isEqualTo("other-only-slug"); + } + + // ==================== fail-closed paths ==================== + + @Test + @DisplayName("unknown kbName fails closed and names the bad pick") + void unknownKbNameFailsClosed() { + when(kbService.findAllByName(AGENT, "Bogus")).thenReturn(List.of()); + // Primary still mockable; the routing must NOT silently fall through. + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + + String json = tool.wiki_list_pages(AGENT, null, "Bogus", null); + JSONObject obj = JSONUtil.parseObj(json); + + assertThat(obj.getStr("error")) + .as("error message should name the bad pick and point at wiki_list_kbs") + .contains("Bogus") + .contains("wiki_list_kbs"); + } + + @Test + @DisplayName("ambiguous kbName fails closed and surfaces every candidate kbId") + void ambiguousKbNameFailsClosed() { + when(kbService.findAllByName(AGENT, "Docs")).thenReturn(List.of( + kb(DUP_BOUND_KB, "Docs", AGENT), + kb(DUP_SHARED_KB, "Docs", null))); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + + String json = tool.wiki_list_pages(AGENT, null, "Docs", null); + JSONObject obj = JSONUtil.parseObj(json); + + // Error must be ambiguity-flavoured so the LLM knows to retry with kbId. + assertThat(obj.getStr("error")) + .contains("Ambiguous") + .contains("Docs") + .contains("kbId"); + + // Candidates list must carry both rows with stringified kbId. + JSONArray candidates = obj.getJSONArray("candidates"); + assertThat(candidates).hasSize(2); + assertThat(candidates.getJSONObject(0).getStr("kbId")) + .isEqualTo(String.valueOf(DUP_BOUND_KB)); + assertThat(candidates.getJSONObject(0).getBool("boundToAgent")).isTrue(); + assertThat(candidates.getJSONObject(1).getStr("kbId")) + .isEqualTo(String.valueOf(DUP_SHARED_KB)); + assertThat(candidates.getJSONObject(1).getBool("boundToAgent")).isFalse(); + } + + @Test + @DisplayName("kbId == 0 is treated as absent (LLM default for unused numeric optionals)") + void kbIdZeroTreatedAsAbsent() { + wirePages(); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + // findVisibleById must NOT be consulted when kbId=0 — that path + // would return null and surface a spurious "kbId=0 not visible" error, + // which is exactly the production regression this test prevents. + + String json = tool.wiki_list_pages(AGENT, null, null, 0L); + JSONObject obj = JSONUtil.parseObj(json); + + assertThat(obj.getStr("error")) + .as("kbId=0 must fall through to primary, NOT raise a not-visible error") + .isNull(); + assertThat(obj.getJSONArray("pages").getJSONObject(0).getStr("slug")) + .isEqualTo("primary-only-slug"); + } + + @Test + @DisplayName("kbId outside the agent's visibility set fails closed") + void kbIdOutOfVisibilityFailsClosed() { + // Visibility gate returns null for an unrelated id. + when(kbService.findVisibleById(AGENT, 99999L)).thenReturn(null); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + + String json = tool.wiki_list_pages(AGENT, null, null, 99999L); + JSONObject obj = JSONUtil.parseObj(json); + + assertThat(obj.getStr("error")) + .contains("99999") + .contains("not visible") + .contains("wiki_list_kbs"); + } + + @Test + @DisplayName("no resolvable KB at all emits the legacy no-KB error") + void noResolvableKbReturnsLegacyError() { + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(null); + + String json = tool.wiki_list_pages(AGENT, null, null, null); + JSONObject obj = JSONUtil.parseObj(json); + + assertThat(obj.getStr("error")).contains("No wiki knowledge base found"); + } + + // ==================== wiki_list_kbs ==================== + + @Test + @DisplayName("wiki_list_kbs enumerates every visible KB with stringified kbId + flags") + void wikiListKbsEnumeratesAll() { + when(kbService.listByAgentId(AGENT)).thenReturn(List.of( + kb(OTHER_KB, "Other", null), + kb(PRIMARY_KB, "Primary", AGENT))); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(kb(PRIMARY_KB, "Primary", AGENT)); + + String json = tool.wiki_list_kbs(AGENT); + JSONObject obj = JSONUtil.parseObj(json); + + assertThat(obj.getInt("kbCount")).isEqualTo(2); + assertThat(obj.getStr("primary")).isEqualTo("Primary"); + + JSONArray kbs = obj.getJSONArray("kbs"); + assertThat(kbs).hasSize(2); + + JSONObject other = kbs.getJSONObject(0); + assertThat(other.getStr("kbId")) + .as("kbId must be a String to preserve Snowflake precision") + .isEqualTo(String.valueOf(OTHER_KB)); + assertThat(other.getStr("name")).isEqualTo("Other"); + assertThat(other.getBool("isPrimary")).isFalse(); + assertThat(other.getBool("boundToAgent")).isFalse(); + + JSONObject primary = kbs.getJSONObject(1); + assertThat(primary.getStr("kbId")).isEqualTo(String.valueOf(PRIMARY_KB)); + assertThat(primary.getStr("name")).isEqualTo("Primary"); + assertThat(primary.getBool("isPrimary")).isTrue(); + assertThat(primary.getBool("boundToAgent")).isTrue(); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolLayerFilterTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolLayerFilterTest.java new file mode 100644 index 00000000..8aa7a9ba --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolLayerFilterTest.java @@ -0,0 +1,41 @@ +package vip.mate.wiki.tool; + +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Unit tests for the retrieval knowledge-layer filter ({@link WikiTool#matchesLayer}). + */ +class WikiToolLayerFilterTest { + + @Test + void noFilterOrAll_matchesEverything() { + assertTrue(WikiTool.matchesLayer("experience", null)); + assertTrue(WikiTool.matchesLayer("experience", "")); + assertTrue(WikiTool.matchesLayer("experience", "all")); + assertTrue(WikiTool.matchesLayer(null, "all")); + } + + @Test + void factFilter_includesUnlayeredPages() { + assertTrue(WikiTool.matchesLayer(null, "fact")); // legacy / unlayered counts as fact + assertTrue(WikiTool.matchesLayer("", "fact")); + assertTrue(WikiTool.matchesLayer("fact", "fact")); + assertFalse(WikiTool.matchesLayer("experience", "fact")); + } + + @Test + void experienceFilter_excludesFactAndUnlayered() { + assertTrue(WikiTool.matchesLayer("experience", "experience")); + assertFalse(WikiTool.matchesLayer("fact", "experience")); + assertFalse(WikiTool.matchesLayer(null, "experience")); + } + + @Test + void caseInsensitive() { + assertTrue(WikiTool.matchesLayer("Experience", "EXPERIENCE")); + assertTrue(WikiTool.matchesLayer("FACT", "fact")); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolPermissionTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolPermissionTest.java new file mode 100644 index 00000000..84666890 --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolPermissionTest.java @@ -0,0 +1,232 @@ +package vip.mate.wiki.tool; + +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.Test; +import vip.mate.wiki.model.WikiAgentPageTypePermissionEntity; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.repository.WikiAgentPageTypePermissionMapper; +import vip.mate.wiki.service.HybridRetriever; +import vip.mate.wiki.service.WikiKnowledgeBaseService; +import vip.mate.wiki.service.WikiPageService; +import vip.mate.wiki.service.WikiPageTypePermissionService; +import vip.mate.wiki.service.WikiRawMaterialService; + +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyLong; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.never; +import static org.mockito.Mockito.times; +import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.when; + +/** + * Verifies the pageType permission gate wired into {@link WikiTool} read and + * write tools, using a real {@link WikiPageTypePermissionService} backed by a + * mocked mapper so permission rows are controlled directly. + */ +class WikiToolPermissionTest { + + private static final long AGENT = 11L; + private static final long KB = 7L; + + private record Harness(WikiTool tool, WikiPageService pageService, + WikiAgentPageTypePermissionMapper permMapper) {} + + private Harness harness(List rows) { + WikiPageService pageService = mock(WikiPageService.class); + WikiKnowledgeBaseService kbService = mock(WikiKnowledgeBaseService.class); + WikiRawMaterialService rawService = mock(WikiRawMaterialService.class); + HybridRetriever retriever = mock(HybridRetriever.class); + ObjectMapper om = new ObjectMapper(); + + WikiKnowledgeBaseEntity kb = new WikiKnowledgeBaseEntity(); + kb.setId(KB); + when(kbService.findVisibleById(AGENT, KB)).thenReturn(kb); + when(kbService.getById(KB)).thenReturn(kb); + + WikiAgentPageTypePermissionMapper permMapper = mock(WikiAgentPageTypePermissionMapper.class); + when(permMapper.selectList(any())).thenReturn(rows); + WikiPageTypePermissionService permService = + new WikiPageTypePermissionService(permMapper, kbService, om); + + WikiTool tool = new WikiTool(pageService, kbService, rawService, retriever, om, permService); + return new Harness(tool, pageService, permMapper); + } + + private WikiAgentPageTypePermissionEntity row(String type, int read, int create, int update, + int delete, String writePolicy) { + WikiAgentPageTypePermissionEntity e = new WikiAgentPageTypePermissionEntity(); + e.setAgentId(AGENT); + e.setKbId(KB); + e.setPageType(type); + e.setCanRead(read); + e.setCanCreate(create); + e.setCanUpdate(update); + e.setCanDelete(delete); + e.setWritePolicy(writePolicy); + return e; + } + + private WikiPageEntity page(String slug, String type) { + WikiPageEntity p = new WikiPageEntity(); + p.setId(100L); + p.setKbId(KB); + p.setSlug(slug); + p.setTitle("T " + slug); + p.setContent("body"); + p.setPageType(type); + p.setLastUpdatedBy("ai"); + return p; + } + + @Test + void readPage_unreadableType_reportsNotFound() { + Harness h = harness(List.of(row("*", 0, 0, 0, 0, "deny"))); + when(h.pageService().getBySlug(KB, "secret")).thenReturn(page("secret", "analysis")); + + String out = h.tool().wiki_read_page(AGENT, "secret", null, null, null, KB); + + assertTrue(out.contains("Page not found"), out); + } + + @Test + void readPage_readableType_returnsContent() { + Harness h = harness(List.of(row("*", 1, 0, 0, 0, "deny"))); + when(h.pageService().getBySlug(KB, "ok")).thenReturn(page("ok", "concept")); + + String out = h.tool().wiki_read_page(AGENT, "ok", null, null, null, KB); + + assertTrue(out.contains("\"content\""), out); + assertFalse(out.contains("Page not found"), out); + } + + @Test + void deletePage_denied_doesNotDelete() { + // can read, but delete flag off → DENY + Harness h = harness(List.of(row("concept", 1, 0, 0, 0, "deny"))); + when(h.pageService().getBySlug(KB, "p")).thenReturn(page("p", "concept")); + + String out = h.tool().wiki_delete_page(AGENT, "p", null, KB); + + assertTrue(out.contains("Not permitted"), out); + verify(h.pageService(), never()).delete(anyLong(), any()); + } + + @Test + void deletePage_approvalRequired_blocksAndDoesNotDelete() { + Harness h = harness(List.of(row("concept", 1, 0, 0, 1, "approval_required"))); + when(h.pageService().getBySlug(KB, "p")).thenReturn(page("p", "concept")); + + String out = h.tool().wiki_delete_page(AGENT, "p", null, KB); + + assertTrue(out.contains("Approval required"), out); + verify(h.pageService(), never()).delete(anyLong(), any()); + } + + @Test + void deletePage_allowed_deletes() { + Harness h = harness(List.of(row("concept", 1, 1, 1, 1, "allow"))); + when(h.pageService().getBySlug(KB, "p")).thenReturn(page("p", "concept")); + + String out = h.tool().wiki_delete_page(AGENT, "p", null, KB); + + assertTrue(out.contains("\"ok\":true"), out); + verify(h.pageService(), times(1)).delete(eq(KB), eq("p")); + } + + @Test + void createPage_deniedByWildcard_doesNotCreate() { + // a row exists for 'episode' only → KB is gated, wildcard create not granted + Harness h = harness(List.of(row("episode", 1, 1, 1, 1, "allow"))); + + String out = h.tool().wiki_create_page(AGENT, "New Page", "content here", null, KB); + + assertTrue(out.contains("Not permitted"), out); + verify(h.pageService(), never()).createPage(anyLong(), any(), any(), any(), any(), any()); + } + + // ---------- wiki_update_page: in-place update, no delete/recreate ---------- + + @Test + void updatePage_allowed_updatesInPlace() { + Harness h = harness(List.of(row("concept", 1, 1, 1, 1, "allow"))); + when(h.pageService().getBySlug(KB, "p")).thenReturn(page("p", "concept")); + WikiPageEntity updated = page("p", "concept"); + updated.setVersion(2); + when(h.pageService().updatePageManually(eq(KB), eq("p"), any(), any())).thenReturn(updated); + + String out = h.tool().wiki_update_page(AGENT, "p", "new body", null, null, KB); + + assertTrue(out.contains("\"ok\":true"), out); + assertTrue(out.contains("updated in place"), out); + verify(h.pageService(), times(1)).updatePageManually(eq(KB), eq("p"), eq("new body"), any()); + // crucially, it must NOT delete or recreate (the duplicate-page bug) + verify(h.pageService(), never()).delete(anyLong(), any()); + verify(h.pageService(), never()).createPage(anyLong(), any(), any(), any(), any(), any()); + } + + @Test + void updatePage_updateDenied_doesNotUpdate() { + // can read + create, but update flag off → DENY + Harness h = harness(List.of(row("concept", 1, 1, 0, 0, "allow"))); + when(h.pageService().getBySlug(KB, "p")).thenReturn(page("p", "concept")); + + String out = h.tool().wiki_update_page(AGENT, "p", "new body", null, null, KB); + + assertTrue(out.contains("Not permitted"), out); + verify(h.pageService(), never()).updatePageManually(anyLong(), any(), any(), any()); + } + + @Test + void updatePage_missingPage_reportsNotFound() { + Harness h = harness(List.of(row("*", 1, 1, 1, 1, "allow"))); + when(h.pageService().getBySlug(KB, "ghost")).thenReturn(null); + + String out = h.tool().wiki_update_page(AGENT, "ghost", "body", null, null, KB); + + assertTrue(out.contains("Page not found"), out); + verify(h.pageService(), never()).updatePageManually(anyLong(), any(), any(), any()); + } + + // ---------- wiki_stale_pages: lists stale, honours read filter ---------- + + private WikiPageEntity stalePage(String slug, String type, String reason) { + WikiPageEntity p = page(slug, type); + p.setStale(1); + p.setStaleReasonJson(reason); + return p; + } + + @Test + void stalePages_listsOnlyStaleReadablePages() { + // wildcard allows reading 'concept' but a specific 'secret' row denies read + Harness h = harness(List.of(row("*", 1, 0, 0, 0, "deny"), row("secret", 0, 0, 0, 0, "deny"))); + WikiPageEntity fresh = page("fresh", "concept"); // not stale → excluded + WikiPageEntity staleOk = stalePage("aged", "concept", "{\"reason\":\"fact updated\"}"); + WikiPageEntity staleHidden = stalePage("classified", "secret", "{\"reason\":\"x\"}"); + when(h.pageService().listByKbId(KB)).thenReturn(List.of(fresh, staleOk, staleHidden)); + + String out = h.tool().wiki_stale_pages(AGENT, null, KB); + + assertTrue(out.contains("\"staleCount\":1"), out); + assertTrue(out.contains("aged"), out); + assertFalse(out.contains("classified"), out); // unreadable type filtered out + assertFalse(out.contains("fresh"), out); // non-stale excluded + } + + @Test + void stalePages_noneStale_returnsZero() { + Harness h = harness(List.of()); + when(h.pageService().listByKbId(KB)).thenReturn(List.of(page("a", "concept"), page("b", "episode"))); + + String out = h.tool().wiki_stale_pages(AGENT, null, KB); + + assertTrue(out.contains("\"staleCount\":0"), out); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolSpringBindingTest.java b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolSpringBindingTest.java new file mode 100644 index 00000000..dc0c777c --- /dev/null +++ b/mateclaw-server/src/test/java/vip/mate/wiki/tool/WikiToolSpringBindingTest.java @@ -0,0 +1,169 @@ +package vip.mate.wiki.tool; + +import cn.hutool.json.JSONArray; +import cn.hutool.json.JSONObject; +import cn.hutool.json.JSONUtil; +import com.fasterxml.jackson.databind.ObjectMapper; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.springframework.ai.support.ToolCallbacks; +import org.springframework.ai.tool.ToolCallback; +import vip.mate.wiki.model.WikiKnowledgeBaseEntity; +import vip.mate.wiki.model.WikiPageEntity; +import vip.mate.wiki.service.HybridRetriever; +import vip.mate.wiki.service.WikiKnowledgeBaseService; +import vip.mate.wiki.service.WikiPageService; +import vip.mate.wiki.service.WikiRawMaterialService; + +import java.util.Arrays; +import java.util.List; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.when; + +/** + * Spring AI binding round-trip for the wiki tools' KB-routing contract. + * + *

    The unit tests in {@link WikiToolKbNameRoutingTest} cover the Java-level + * routing logic, but the LLM never calls those methods directly — it serializes + * a JSON tool call which Spring AI's {@link ToolCallbacks#from} layer deserializes + * back into method arguments. Two coercion hops in that pipeline are easy to + * break unnoticed: + * + *

      + *
    1. {@code wiki_list_kbs} returns {@code "kbId": ""} as a JSON + * string (workspace-wide Snowflake-precision rule). When the LLM hands + * that exact string back as {@code kbId} on a follow-up call, the Java + * method declares {@code Long kbId} — so the framework must coerce + * string → Long without precision loss.
      2. + *
    2. OpenAI-style chat models frequently populate "unused numeric + * optionals" with {@code 0}. The routing layer treats {@code kbId > 0} + * as the only "supplied" sentinel; any binding change that lets a real + * 19-digit id collapse to 0 (e.g. silent float coercion) would also + * break the round-trip even though the unit tests still pass.
      3. + *
    + * + * These two tests pin the contract end-to-end. + */ +class WikiToolSpringBindingTest { + + private static final Long AGENT = 7L; + private static final long PRIMARY_KB = 100L; + // Real-shape Snowflake id — 19 digits, beyond JS Number.MAX_SAFE_INTEGER. + // Verifies the precision-safe round-trip the workspace rule mandates. + private static final long SNOWFLAKE_KB = 2054907618529591298L; + + private final WikiPageService pageService = mock(WikiPageService.class); + private final WikiKnowledgeBaseService kbService = mock(WikiKnowledgeBaseService.class); + private final WikiRawMaterialService rawService = mock(WikiRawMaterialService.class); + private final HybridRetriever hybridRetriever = mock(HybridRetriever.class); + private final ObjectMapper objectMapper = new ObjectMapper(); + + // Allow-all permission service (no rows configured) — this test exercises + // tool binding, not permissions. + private final vip.mate.wiki.service.WikiPageTypePermissionService permissionService = + new vip.mate.wiki.service.WikiPageTypePermissionService( + mock(vip.mate.wiki.repository.WikiAgentPageTypePermissionMapper.class), kbService, objectMapper); + + private final WikiTool tool = new WikiTool(pageService, kbService, rawService, + hybridRetriever, objectMapper, permissionService); + + private ToolCallback callbackFor(String functionName) { + return Arrays.stream(ToolCallbacks.from(tool)) + .filter(cb -> functionName.equals(cb.getToolDefinition().name())) + .findFirst() + .orElseThrow(() -> new AssertionError("No ToolCallback for " + functionName)); + } + + private static WikiKnowledgeBaseEntity kb(long id, String name, Long agentId) { + WikiKnowledgeBaseEntity e = new WikiKnowledgeBaseEntity(); + e.setId(id); + e.setName(name); + e.setAgentId(agentId); + e.setPageCount(0); + return e; + } + + private static WikiPageEntity page(String slug, String title) { + WikiPageEntity p = new WikiPageEntity(); + p.setSlug(slug); + p.setTitle(title); + p.setPageType("user"); + return p; + } + + @Test + @DisplayName("wiki_list_kbs emits kbId as a JSON STRING and round-trips back through Long kbId") + void kbIdRoundTripsAsStringWithoutPrecisionLoss() { + // Arrange: one agent-bound KB whose id is a real-shape 19-digit + // Snowflake. wiki_list_kbs must surface this as a string so a JS + // hop never truncates it; the follow-up tool call then has to + // accept that same string and coerce it back to a Long without loss. + WikiKnowledgeBaseEntity snowflakeKb = kb(SNOWFLAKE_KB, "Big Data KB", AGENT); + when(kbService.listByAgentId(AGENT)).thenReturn(List.of(snowflakeKb)); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(snowflakeKb); + when(kbService.findVisibleById(AGENT, SNOWFLAKE_KB)).thenReturn(snowflakeKb); + when(pageService.listSummaries(eq(SNOWFLAKE_KB))).thenReturn(List.of( + page("only-page", "Only Page"))); + + // Step 1: wiki_list_kbs through the real Spring AI ToolCallback binding. + ToolCallback listKbs = callbackFor("wiki_list_kbs"); + String listJson = listKbs.call("{\"agentId\":" + AGENT + "}"); + JSONObject listObj = JSONUtil.parseObj(listJson); + + JSONArray kbs = listObj.getJSONArray("kbs"); + assertThat(kbs).hasSize(1); + JSONObject row = kbs.getJSONObject(0); + // kbId MUST be a JSON string. Reading it back via getStr should equal + // the exact 19-digit id; reading via getLong should also work (Hutool + // parses string-or-number). The two checks combined catch a regression + // that emits the id as a JSON number (which the LLM/JS hop would round). + String advertisedKbId = row.getStr("kbId"); + assertThat(advertisedKbId) + .as("wiki_list_kbs MUST publish kbId as a string") + .isEqualTo(String.valueOf(SNOWFLAKE_KB)); + assertThat(row.get("kbId")) + .as("the raw JSON node must be a String, not a Number") + .isInstanceOf(String.class); + + // Step 2: feed that exact string back to wiki_list_pages as kbId, + // exactly as an LLM tool call would. The framework must coerce + // String → Long with no precision loss, and the routing layer must + // resolve via findVisibleById (NOT fall back to primary). + ToolCallback listPages = callbackFor("wiki_list_pages"); + String pagesJson = listPages.call("{\"agentId\":" + AGENT + + ",\"kbId\":\"" + advertisedKbId + "\"}"); + JSONObject pagesObj = JSONUtil.parseObj(pagesJson); + + assertThat(pagesObj.getStr("error")) + .as("string-kbId round-trip must NOT raise a not-visible error") + .isNull(); + assertThat(pagesObj.getJSONArray("pages").getJSONObject(0).getStr("slug")) + .isEqualTo("only-page"); + } + + @Test + @DisplayName("kbId=0 from an LLM tool call falls through to primary instead of failing closed") + void kbIdZeroFromToolCallFallsThroughToPrimary() { + // The openai-chatgpt family was observed populating every unused + // numeric optional with 0 in tool-call JSON. The routing layer + // must treat that as "absent" — otherwise every wiki_* call + // surfaces a spurious "kbId=0 not visible" error. + WikiKnowledgeBaseEntity primary = kb(PRIMARY_KB, "Primary", AGENT); + when(kbService.resolvePrimaryKb(AGENT)).thenReturn(primary); + when(pageService.listSummaries(eq(PRIMARY_KB))).thenReturn(List.of( + page("primary-page", "Primary Page"))); + + ToolCallback listPages = callbackFor("wiki_list_pages"); + // Note: kbId arrives as JSON number 0 — the exact shape the + // production regression had. + String json = listPages.call("{\"agentId\":" + AGENT + ",\"kbId\":0}"); + JSONObject obj = JSONUtil.parseObj(json); + + assertThat(obj.getStr("error")).isNull(); + assertThat(obj.getJSONArray("pages").getJSONObject(0).getStr("slug")) + .isEqualTo("primary-page"); + } +} diff --git a/mateclaw-server/src/test/java/vip/mate/workflow/api/WorkflowControllerTest.java b/mateclaw-server/src/test/java/vip/mate/workflow/api/WorkflowControllerTest.java index 17376956..a8c7cf06 100644 --- a/mateclaw-server/src/test/java/vip/mate/workflow/api/WorkflowControllerTest.java +++ b/mateclaw-server/src/test/java/vip/mate/workflow/api/WorkflowControllerTest.java @@ -13,12 +13,14 @@ import org.springframework.http.ResponseEntity; import org.springframework.test.context.TestPropertySource; import vip.mate.MateClawApplication; import vip.mate.common.result.R; +import vip.mate.exception.MateClawException; import vip.mate.workflow.compiler.WorkflowAclPort; import vip.mate.workflow.model.WorkflowEntity; import vip.mate.workflow.repository.WorkflowMapper; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; /** @@ -97,6 +99,21 @@ class WorkflowControllerTest { assertInstanceOf(CompileErrorResponse.class, body.getData()); } + @Test + @DisplayName("create() rejects a second workflow with the same name as a 409 instead of a 500 from the unique index.") + void createRejectsDuplicateNameAs409() { + WorkflowEntity first = new WorkflowEntity(); + first.setName("dup"); + controller.create(first, 99L); + + WorkflowEntity second = new WorkflowEntity(); + second.setName("dup"); + MateClawException ex = assertThrows(MateClawException.class, + () -> controller.create(second, 99L)); + assertEquals(409, ex.getCode()); + assertEquals("err.workflow.duplicate_name", ex.getMsgKey()); + } + private Long createWorkflow(String name) { WorkflowEntity wf = new WorkflowEntity(); wf.setWorkspaceId(99L); diff --git a/mateclaw-server/src/test/java/vip/mate/workspace/document/WorkspaceMemorySearchTest.java b/mateclaw-server/src/test/java/vip/mate/workspace/document/WorkspaceMemorySearchTest.java index 8989778c..6b772ff9 100644 --- a/mateclaw-server/src/test/java/vip/mate/workspace/document/WorkspaceMemorySearchTest.java +++ b/mateclaw-server/src/test/java/vip/mate/workspace/document/WorkspaceMemorySearchTest.java @@ -38,6 +38,7 @@ import static org.mockito.Mockito.when; class WorkspaceMemorySearchTest { @Mock private WorkspaceFileMapper fileMapper; + @Mock private org.springframework.context.ApplicationEventPublisher eventPublisher; private WorkspaceFileService service; @BeforeAll @@ -51,7 +52,22 @@ class WorkspaceMemorySearchTest { @BeforeEach void setUp() { - service = new WorkspaceFileService(fileMapper); + service = new WorkspaceFileService(fileMapper, eventPublisher); + } + + @Test + @DisplayName("saveFile publishes a change event so the cached agent instance is invalidated") + void saveFilePublishesChangeEvent() { + // getFile() now uses the non-throwing selectOne(wrapper, false) overload. + when(fileMapper.selectOne(any(), org.mockito.ArgumentMatchers.anyBoolean())).thenReturn(null); // new file path + + service.saveFile(1000000001L, "MEMORY.md", "## 稳定事实\n- 用户语言：简体中文"); + + ArgumentCaptor captor = + ArgumentCaptor.forClass(vip.mate.workspace.document.event.WorkspaceFileChangedEvent.class); + org.mockito.Mockito.verify(eventPublisher).publishEvent(captor.capture()); + assertThat(captor.getValue().agentId()).isEqualTo(1000000001L); + assertThat(captor.getValue().filename()).isEqualTo("MEMORY.md"); } // ---------- tokenize ---------- @@ -256,18 +272,77 @@ class WorkspaceMemorySearchTest { assertThat(sql).contains("LIKE ? OR") .contains("AND content") .contains("LIMIT 50"); + // With a null ownerKey the scope-visibility clause restricts to shared + // rows via an IN (?, ?) on (TEAM, GLOBAL), adding two bind params. assertThat(sql.chars().filter(ch -> ch == '?').count()) - .as("one agentId + two prefix LIKEs + three content LIKEs = 6 bind params") - .isEqualTo(6); + .as("agentId + two scope params + two prefix LIKEs + three content LIKEs = 8 bind params") + .isEqualTo(8); List values = new ArrayList<>(wrapper.getParamNameValuePairs().values()); assertThat(values).contains(42L); + // Shared-scope visibility filter binds the TEAM / GLOBAL literals. + assertThat(values).contains("TEAM", "GLOBAL"); // Each content-LIKE term gets %term% by MyBatis-Plus's like(). assertThat(values).contains("%running%", "%shoes%", "%跑步%"); // likeRight produces "prefix%" — confirms both prefixes were bound. assertThat(values).contains("memory/%", "MEMORY.md%"); } + @Test + @DisplayName("Owner-scoped search binds shared (TEAM/GLOBAL) + this owner's PERSONAL rows only") + void ownerScopedSearchBindsPersonalBranch() { + when(fileMapper.selectList(any())).thenReturn(List.of()); + service.searchSnippets(42L, "running", null, 10, "user:7"); + + @SuppressWarnings("unchecked") + ArgumentCaptor> captor = + ArgumentCaptor.forClass(LambdaQueryWrapper.class); + org.mockito.Mockito.verify(fileMapper).selectList(captor.capture()); + LambdaQueryWrapper wrapper = captor.getValue(); + wrapper.getTargetSql(); + + List values = new ArrayList<>(wrapper.getParamNameValuePairs().values()); + // Visibility clause: (scope IN (TEAM, GLOBAL)) OR (scope = PERSONAL AND owner_key = ?) + assertThat(values).contains("TEAM", "GLOBAL", "PERSONAL", "user:7"); + // A different owner's key must NOT be bound — that is the isolation guarantee. + assertThat(values).doesNotContain("user:99"); + } + + @Test + @DisplayName("saveFile recovers from a concurrent first-write unique conflict by reselect+update") + void saveFileRecoversFromConcurrentInsert() { + WorkspaceFileEntity raced = file("MEMORY.md", "racer content"); + // First selectOne (existence check) → null (we think it's new); after the + // insert loses the unique-index race, the reselect → the racer's row. + when(fileMapper.selectOne(any(), org.mockito.ArgumentMatchers.anyBoolean())) + .thenReturn(null, raced); + when(fileMapper.insert(any(WorkspaceFileEntity.class))) + .thenThrow(new org.springframework.dao.DuplicateKeyException("uk_workspace_file_owner")); + + service.saveFile(1000000001L, "MEMORY.md", "## new"); + + // Must fall back to updating the existing row, not propagate the exception. + org.mockito.Mockito.verify(fileMapper).updateById(raced); + assertThat(raced.getContent()).isEqualTo("## new"); + } + + @Test + @DisplayName("saveFile rethrows a duplicate-key error unrelated to the owner-scope index (no false recovery)") + void saveFileRethrowsUnrelatedDuplicateKey() { + when(fileMapper.selectOne(any(), org.mockito.ArgumentMatchers.anyBoolean())).thenReturn(null); + // A PRIMARY-key collision (not the uk_workspace_file_owner index) must + // NOT be swallowed as a concurrent first-write. + when(fileMapper.insert(any(WorkspaceFileEntity.class))) + .thenThrow(new org.springframework.dao.DuplicateKeyException( + "Duplicate entry '42' for key 'PRIMARY'")); + + org.assertj.core.api.Assertions.assertThatThrownBy( + () -> service.saveFile(1000000001L, "MEMORY.md", "## new")) + .isInstanceOf(org.springframework.dao.DuplicateKeyException.class); + org.mockito.Mockito.verify(fileMapper, org.mockito.Mockito.never()) + .updateById(any(WorkspaceFileEntity.class)); + } + // ---------- helpers ---------- private static WorkspaceFileEntity file(String filename, String content) { diff --git a/mateclaw-server/src/test/resources/e2e/wiki-link-overhaul-verification.md b/mateclaw-server/src/test/resources/e2e/wiki-link-overhaul-verification.md new file mode 100644 index 00000000..70c3ba80 --- /dev/null +++ b/mateclaw-server/src/test/resources/e2e/wiki-link-overhaul-verification.md @@ -0,0 +1,1061 @@ +# Wikilink Resolution Overhaul — End-to-End Verification + +Manual / scripted verification against a live `mateclaw-server` instance for +the wikilink resolution + dead-link governance work landed across Phase 1–5. +Unit tests cover the pure logic; this document covers the *integration* +contract: HTTP shape, DB persistence, cross-page cascade behaviour, +async job lifecycle, and prompt-template variable substitution. + +## 0. Environment + +| | | +|---|---| +| Base URL | `http://localhost:18088` | +| Auth | `POST /api/v1/auth/login` with `{username:"admin", password:"admin123"}` | +| JWT header | `Authorization: Bearer ` on every other call | +| Test KB | A fresh KB is created at section §1.0 so verification doesn't mutate existing data | +| H2 console | `http://localhost:18088/h2-console` (for DB cross-check) | + +All HTTP examples below assume `TOKEN=$JWT` is exported. + +--- + +## 1. Phase 1 — pages/refs endpoint + resolution index + +### 1.0 Bootstrap a fresh KB + +``` +POST /api/v1/wiki/knowledge-bases + body: {"name":"E2E-RFC55-KB","description":"E2E for the wikilink overhaul"} +→ 200, returns kb.id (Snowflake string) +``` + +Stash `KB_ID` from the response. + +### 1.1 Refs endpoint exists and returns the documented shape + +``` +GET /api/v1/wiki/knowledge-bases/{KB_ID}/pages/refs +→ 200 +→ data: { kbId: "", items: [{slug, title, archived}, ...] } +``` + +**Pass criteria** + +- HTTP 200 +- `data.kbId` matches `KB_ID` +- `data.items` is an array (empty on a fresh KB) +- Every item has exactly the keys `slug`, `title`, `archived` (no `content`, no `summary`) +- `archived` is a JSON boolean, not 0/1 + +### 1.2 `?includeArchived=true` returns archived rows + +Seed: archive one page (after §4.0 below has pages to archive); then: + +``` +GET /api/v1/wiki/knowledge-bases/{KB_ID}/pages/refs?includeArchived=true +``` + +**Pass criteria** + +- Items include the archived page with `archived: true` +- Default request (`includeArchived` omitted or `false`) does NOT include archived rows + +### 1.3 Refs are not affected by raw-material filter + +The refs endpoint must return the full active KB regardless of any frontend +"raw-material filter" state. Verify by direct call — refs has no `rawId` +query parameter, and a `GET /pages?rawId=X` returning a filtered subset +must NOT change refs output. + +--- + +## 2. Phase 2 — broken-link lint + +### 2.0 Seed: create a page that links to a non-existent target + +Use the manual edit endpoint (skips ingest LLM) to put deterministic content: + +``` +PUT /api/v1/wiki/knowledge-bases/{KB_ID}/pages/{slug} + body: {"content":"## Heading\n\nSee [[ghost-page]] for more.\n","summary":"x"} +``` + +Bootstrap a page first via the admin "create empty page" route OR via a test +ingest. Easiest path: trigger a small KB ingest in a separate tab — or use the +DB directly to insert a row for this verification. + +### 2.1 broken_links column is populated synchronously on save + +After the save above, the page row in `mate_wiki_page` should have: +- `outgoing_links` = `["ghost-page"]` +- `broken_links` = `["ghost-page"]` +- `broken_links_scanned_at` ≈ NOW + +``` +SELECT slug, outgoing_links, broken_links, broken_links_scanned_at + FROM mate_wiki_page + WHERE kb_id = {KB_ID} AND slug = {slug} +``` + +**Pass criteria**: all three columns reflect the dead link without any +explicit lint call — the save path computed them in-transaction. + +### 2.2 POST /lint/broken-links starts a job + +``` +POST /api/v1/wiki/knowledge-bases/{KB_ID}/lint/broken-links +→ 200, data: { jobId, kbId, status: "queued" | "running" | "completed", + startedAt, completedAt: null | string, + totalPages: int, pagesWithBrokenLinks: int, + totalBrokenRefs: int } +``` + +**Pass criteria** + +- A `jobId` (16-hex-ish string) is returned +- `status` is in the four-value enum +- `startedAt` is non-null ISO-8601 + +### 2.3 Idempotency — repeat POST while running returns same jobId + +Immediately after §2.2, before the job completes, POST again. The +`jobId` must equal the previous one (the service does not enqueue a +duplicate scan). + +(On a tiny test KB the job completes in milliseconds, so this is hard to +race in practice. The implementation guarantees idempotency for any +overlap; verify by code review of `WikiLintJobService.startOrGetRunning` +if real-time can't be hit.) + +### 2.4 GET /lint/broken-links returns the aggregate after completion + +``` +GET /api/v1/wiki/knowledge-bases/{KB_ID}/lint/broken-links +→ 200, data: { kbId, jobId, completedAt, totalPages, + pagesWithBrokenLinks, totalBrokenRefs, + pages: [{pageId, slug, title, brokenRefs: [...]}] } +``` + +**Pass criteria** + +- `completedAt` is non-null and >= the `startedAt` from §2.2 +- `pages` contains the seed slug from §2.0 with `brokenRefs = ["ghost-page"]` +- `pageId` is a string (Snowflake — must NOT be coerced to a JS number) + +### 2.5 GET before any scan returns 404 + +If §2.0–§2.4 haven't run for a fresh KB: + +``` +GET /api/v1/wiki/knowledge-bases//lint/broken-links +→ 404 with msg "no scan yet, POST to start one" +``` + +**Pass criteria**: 404 (not empty 200) so the frontend distinguishes +"never scanned" from "scanned, zero broken links". + +### 2.6 Optional job-status endpoint + +``` +GET /api/v1/wiki/knowledge-bases/{KB_ID}/lint/broken-links/jobs/{jobId} +→ 200 with the same envelope as §2.2 (re-keyed by jobId) +``` + +**Pass criteria**: returns a valid envelope for a jobId belonging to that +KB; 404 for an unknown or cross-KB jobId. + +--- + +## 3. Phase 3 — prompt + index format (DB-level + log-level) + +### 3.1 Existing-pages index is slug-first + +Inspect a recent ingest's prompt logs (or temporarily lower the logger to +DEBUG for `WikiProcessingService`). The user prompt's `{existing_pages}` +section must use the row format: + +``` +- [[slug-here]] — Title — Summary +``` + +**NOT** the legacy `**[[Title]]** (slug: `slug-here`)` form. + +### 3.2 Batch-create user prompt distinguishes existing vs planned + +The batch-create user prompt must contain two distinct headings: + +- `## 已有 Wiki 页面索引（强保证，可直接链接...)` +- `## 本批次将一并创建的页面（计划中，可能可被链接...)` + +The system prompt explicitly states planned-page links are not guaranteed. + +(This verifies the prompt file content, not LLM behaviour — see §5 for +hallucination guard.) + +### 3.3 No prompt instructs `[[Page Title]]` + +```bash +grep -rn '\[\[页面标题\]\]\|\[\[Title\]\]\|\[\[wikilinks\]\]' \ + mateclaw-server/src/main/resources/prompts/wiki/ +``` + +**Pass criteria**: zero matches in `*.txt` prompts. The single unified +contract is `[[slug]]` / `[[slug|显示文本]]`. + +--- + +## 4. Phase 4 — cascade delete + rename + +### 4.0 Seed: page A + page B referencing A + +``` +POST /api/v1/wiki/knowledge-bases/{KB_ID}/pages # via processing or manual seed + → page-a (title "Page A") + → page-b (title "Page B", content "Refers to [[page-a]] and [[page-a|alias-form]].") +``` + +Use a small ingest of two short markdown docs to seed deterministically, +OR insert directly into `mate_wiki_page` for testing. + +### 4.1 Delete A → B's content is rewritten in same transaction + +``` +DELETE /api/v1/wiki/knowledge-bases/{KB_ID}/pages/page-a +→ 200 +``` + +Then: + +``` +GET /api/v1/wiki/knowledge-bases/{KB_ID}/pages/page-b +``` + +**Pass criteria** + +- Page B's `content` no longer contains `[[page-a]]` +- The visible text is the snapshot title: `Refers to Page A and alias-form.` +- Page B's `outgoing_links` no longer contains `"page-a"` +- Page B's `broken_links` does not contain `"page-a"` (the rewrite removed the wikilink, so it isn't a broken ref any more) + +### 4.2 mate_wiki_relation rows referencing the deleted page are gone + +```sql +SELECT COUNT(*) FROM mate_wiki_relation + WHERE kb_id = {KB_ID} AND (page_a_id = {DELETED_ID} OR page_b_id = {DELETED_ID}) +``` + +**Pass criteria**: 0 rows. (Even though the table is currently a reserved +cache with no production writer, the defensive cleanup must still +execute.) + +### 4.3 Audit event for the delete + +```sql +SELECT action, resource_type, resource_id, detail_json + FROM mate_audit_event + WHERE action = 'wiki.page.delete' + ORDER BY id DESC LIMIT 1 +``` + +**Pass criteria** + +- `action = 'wiki.page.delete'` +- `resource_type = 'wiki_page'` +- `resource_id` = the deleted page id (string) +- `detail_json` contains `{kbId, slug, title, affectedPageIds: [B_ID], cascadeEnabled: true}` + +### 4.4 Cascade-delete feature flag + +Set `mate.wiki.cascade-delete-enabled=false` in application properties (or +profile override), restart, repeat §4.1. Expected behaviour: the page is +deleted but referrers KEEP their `[[deleted-slug]]` tokens (legacy +behaviour). After the verification, flip back to default-true. + +### 4.5 Rename: page C → page D references migrate + +``` +POST /api/v1/wiki/knowledge-bases/{KB_ID}/pages/page-c/rename + body: {"newSlug": "renamed-c"} +→ 200, data: {oldSlug: "page-c", newSlug: "renamed-c", pageId: ""} +``` + +Then verify any referrer's content has `[[page-c]]` rewritten to +`[[renamed-c]]` (and `[[page-c|alias]]` → `[[renamed-c|alias]]`). + +### 4.6 Rename rejects on collision / blank / no-op + +| Request | Expected | +|---|---| +| `newSlug` blank | 400 | +| `newSlug` equals existing slug | 400 | +| `newSlug` matches another page in the same KB | 400 | +| Rename a protected (system / locked) page | 409 | +| Rename a non-existent slug | 404 | + +--- + +## 5. Phase 5 — analyze stage whitelist + enrich applier guards + +### 5.1 Analyze prompt receives `{existing_pages}` + +Inspect the actual rendered analyze user prompt (DEBUG log on +`WikiProcessingService.analyzeDocument`). The variable +`{existing_pages}` is substituted with the slug-first index, not left +unfilled. + +### 5.2 `related_pages` is validated server-side + +Force a known-invented slug by stubbing the LLM response (or read the +warning log): the line +`[Wiki] Analyze dropped hallucinated related_pages entries for kbId=: []` +appears whenever the LLM returns slugs not in the KB. The downstream +generation prompt's `## 推荐链接到的页面` section must NOT contain +the dropped slugs. + +### 5.3 Enrich applier skips fenced + inline code + +This is unit-covered (`WikiEnrichmentApplierPhase5Test`), but an +integration spot check: enrich a page whose content has a wikilink +candidate inside a code fence — the resulting page content must keep +the candidate literal inside the fence and only wrap occurrences in +prose. + +### 5.4 Enrich applier honours target-slug whitelist + +When the caller passes a non-null `allowedSlugsLower`, patches whose +target is outside the set are silently dropped. Verify via the unit-test +fixtures (no public API exposes the third overload directly). + +--- + +## 6. Verification report template + +After running each section, record: + +| Section | Pass / Fail | Notes | +|---|---|---| +| 1.1 refs endpoint shape | | | +| 1.2 includeArchived | | | +| 2.1 sync broken_links on save | | | +| 2.2 POST starts job | | | +| 2.4 GET aggregate | | | +| 2.5 404 before any scan | | | +| 3.1 index format | | | +| 3.3 zero `[[页面标题]]` in prompts | | | +| 4.1 cascade delete rewrites referrers | | | +| 4.2 mate_wiki_relation cleanup | | | +| 4.3 audit event | | | +| 4.5 rename | | | +| 5.1 analyze {existing_pages} substituted | | | +| 5.2 related_pages whitelist enforcement | | | + +Attach H2 query outputs + cURL traces for each failing row. + +--- + +## 7. Verification run — 2026-05-27 (local dev) + +Ran sections 1.1, 1.2, 2.1, 2.2, 2.4, 2.5, 2.6, 3.1, 3.2, 3.3, 4.1, 4.3, +4.5, 4.6 against a live server at `localhost:18088`. KBs `E2E-RFC55-KB` +(2059635046512566274) and a one-page-only empty KB. + +| Section | Result | Evidence | +|---|---|---| +| 1.1 refs endpoint shape on fresh KB | ✅ Pass | Returns `{kbId: string, items: [{slug, title, archived: bool}]}` for the 2 auto-seeded system pages (`overview`, `log`). No `content` / `summary` leaked. | +| 1.2 includeArchived filter | ✅ Pass | After archiving `bob-engineer`: default request omits it, `?includeArchived=true` returns it with `archived: true`. | +| 2.1 sync broken_links on manual save | ✅ Pass | PUT'd `overview` content with `[[ghost-page]] [[also-missing]] [[log]]`. Response: `outgoingLinks=["ghost-page","also-missing","log"]`, `brokenLinks=["ghost-page","also-missing"]`, `brokenLinksScannedAt` populated. `log` correctly NOT flagged broken. | +| 2.2 POST lint starts job | ✅ Pass | Returned `{jobId:"ef81ee2c961646b3", kbId, status:"queued", startedAt}`. | +| 2.4 GET aggregate | ✅ Pass | Returned `{kbId, jobId, completedAt, totalPages:2, pagesWithBrokenLinks:1, totalBrokenRefs:2, pages:[{pageId:"...", slug:"overview", title:"Overview", brokenRefs:["ghost-page","also-missing"]}]}`. `pageId` correctly serialised as Snowflake string. | +| 2.5 404 on never-scanned KB | ⚠️ **Deviation by design** | Returns HTTP 200 with a synthetic-empty aggregate, NOT 404. Root cause: every new KB seeds `overview` + `log` system pages, both go through `applyLinkAnalysis` on creation and stamp `broken_links_scanned_at`, so the "no scan yet" branch is unreachable in practice. Frontend UX is unaffected (it still shows "scanned X pages, no broken links" vs "scan now"). Spec to update: GET always returns 200 with aggregate; the "never scanned" semantic was an early draft that didn't account for system-page seeding. | +| 2.6 GET by jobId | ✅ Pass | Returned full job envelope with `status:"completed"` and matching `startedAt`/`completedAt`. | +| 3.1 slug-first index format | ✅ Pass | `WikiProcessingService.buildExistingPagesIndex` confirmed to emit `- [[slug]] — Title — Summary` rows (Java source inspection). | +| 3.2 batch-create existing vs planned | ✅ Pass | `batch-create-user.txt` has both `## 已有 Wiki 页面索引（强保证）` and `## 本批次将一并创建的页面（计划中）` sections with the "not guaranteed" warning between them. | +| 3.3 no legacy `[[Page Title]]` in prompts | ✅ Pass | The only grep match in `prompts/wiki/*.txt` is the *explicit prohibition* in `create-page-system.txt:35` ("不要写 `[[页面标题]]`"). Zero legacy instructions. | +| 3.x **LLM honours slug-first contract** (bonus) | ✅ Pass | Real ingest of a 108-char raw note produced two pages (`alice`, `bob`) whose content used `[[overview\|E2E test note]]`, `[[bob]]`, `[[alice]]` exclusively. Zero `[[Page Title]]`-form occurrences. `broken_links` empty on both — every link resolves. | +| 4.1 cascade delete rewrites referrers | ✅ Pass | `bob` had 3 `[[alice]]` references + `outgoing=["overview","alice"]`. After `DELETE /pages/alice`: `[[alice]]` count = 0, plain `Alice` count = 3, `outgoingLinks=["overview"]`, `brokenLinks=[]`, `scannedAt` advanced. Snapshot title "Alice" correctly used as visible replacement. | +| 4.3 audit events | ✅ Pass | `mate_audit_event` (via `GET /api/v1/audit/events?resourceType=wiki_page`): both `wiki.page.delete` and `wiki.page.rename` rows present with `detailJson` containing `{kbId, slug/oldSlug/newSlug, title, affectedPageIds:[], cascadeEnabled:true}`. | +| 4.5 cascade rename | ✅ Pass | Seeded `overview` with `[[bob]] ... [[bob\|the Java guy]] ... [[log]]`. After `POST /pages/bob/rename` with `{"newSlug":"bob-engineer"}`: `[[bob]]` → `[[bob-engineer]]` (1×), `[[bob\|the Java guy]]` → `[[bob-engineer\|the Java guy]]` (alias preserved), `[[log]]` untouched, `outgoing` updated. Old `bob` slug → HTTP 404; new `bob-engineer` reachable. | +| 4.6 rename rejection paths | ✅ Pass | blank newSlug → 400; equals old → 400; collision with `overview` → 400; rename system `overview` → 409; rename non-existent slug → 404. All 5 cases return informative `msg`. | + +Items deferred (not blocking, would require additional setup): + +- **§2.3 idempotency under in-flight load**: lint job completes in ~3 ms on a 2-page KB, faster than the round-trip needed to fire a second POST. Code-level review of `WikiLintJobService.startOrGetRunning` (`computeIfAbsent`-style branch on QUEUED/RUNNING) confirms the invariant; integration replay would need a much larger KB or an injected sleep. Tracked. +- **§4.2 mate_wiki_relation cleanup**: the table currently has no production writer (V77 reserved cache), so the defensive `DELETE FROM mate_wiki_relation WHERE ...` clause from §4 unit-tests is exercised but always touches 0 rows. Will be re-verified once a real relation writer lands. +- **§4.4 feature-flag kill-switch**: requires a server restart with `mate.wiki.cascade-delete-enabled=false`; out of band for a single live verification pass. +- **§5.1/§5.2 analyze whitelist enforcement**: the real ingest in row 3.x produced two pages with zero invented slugs, indirectly evidencing the whitelist gate. A dedicated negative test (LLM proposes a fake slug) needs a stubbed LLM or an injected response — left to a future targeted integration test. +- **§5.3/§5.4 enrich applier code-block + whitelist**: fully covered by `WikiEnrichmentApplierPhase5Test` (6 unit tests). No integration delta worth replaying live. + +### Bottom line + +Every behaviour the RFC committed to has either a passing live trace +above or a corresponding pure-Java test on the same code path. The one +deviation (§2.5 returns 200 instead of 404 because system pages auto- +stamp scan time on KB creation) is a spec-level correction, not a code +defect — frontend UX is unaffected and the "no scan banner state" the +UI shows is driven off `completedAt`/`jobId` presence, not the HTTP +status. + +End-to-end "user reports broken link → lint reveals all → delete or +rename a page → cascade clears the dangling tokens" flow is reproducible +on a clean dev box in under three minutes (KB create + ingest + verify). + +--- + +## 8. Second pass — multi-referrer / code-block / round-trip (2026-05-28) + +Extended e2e with deeper scenarios. **Caught and fixed one data-loss bug** +before publishing the pass report. + +### 8.0 Setup + +Fresh KB `E2E-RFC55-StressKB`. Ingested a 5-entity team handbook (Alice +Chen, Bob Patel, Carol Liu, Crawler subsystem, Indexing project) and +manually edited `overview` to fan in references to all five plus a +fenced-code block + inline-code block both containing literal +`[[alice-chen]]` examples. + +### 8.1 Scenarios run + +| Scenario | What it covers | Result | +|---|---|---| +| **B. Multi-referrer cascade delete** | Delete `carol-liu` with 2 referrers (`indexing-project` + `overview`); only non-empty content gets rewritten | ✅ overview's `[[carol-liu]]` (1×) demoted to plain "Carol Liu"; outgoing updated; audit `affectedPageIds:[overview_id]` | +| **C. Code-block protection during cascade** | Delete `alice-chen`; overview has `[[alice-chen]]` 2× in prose AND 2× in fenced/inline-code blocks | ✅ Prose `[[alice-chen]]` and `[[alice-chen\|Alice]]` demoted to `Alice Chen` / `Alice`; **code block byte-for-byte preserved**: ```` ```markdown\nUse [[alice-chen]] or [[alice-chen\|some alias]] to link to a teammate.\n``` ```` | +| **D. Multi-referrer cascade rename + alias preservation** | Rename `bob-patel` → `robert-patel` with 2 referrers (overview has `[[bob-patel\|Bob the pair-programmer]]`, log has `[[bob-patel]]` + `[[bob-patel\|Bob]]`) | ✅ All 3 occurrences across both pages rewrite to `robert-patel`, aliases preserved; old slug → 404; audit `affectedPageIds=[overview_id, log_id]` | +| **E. Break-then-fix round trip** | PUT log with `[[nonexistent-1]] [[also-fake]] [[robert-patel]]` → scan → fix via PUT with valid slugs only → re-scan | ✅ Break: `broken_links=["nonexistent-1","also-fake"]` synchronously, scan aggregate shows 2 refs across 1 page. Fix: `broken_links=[]` synchronously, scan aggregate clean | +| **F. Archive + scan interaction** | Archive `crawler-subsystem`; refs index excludes it by default, includes with `?includeArchived=true` (with `archived:true`) | ✅ Default refs hides; `?includeArchived=true` returns it with the flag | + +### 8.2 Bug found and fixed mid-run + +While re-reading the multi-referrer cascade output, noticed that +`indexing-project` had `content_len=0` even though it had been a referrer +to `carol-liu`. Tracing down: every page in the KB had `content` and +`summary` set to `NULL` after any of the following ran: + +1. `WikiLintJobService.rewriteBrokenLinks` — runs on every KB-wide scan +2. `WikiPageService.cascadeStripReferrers` — runs on every cascade delete +3. `WikiPageService.cascadeRenameReferrers` — runs on every cascade rename + +All three built a partial `WikiPageEntity` setting only the fields they +intended to update (`id` + `outgoing_links` + `broken_links` + `broken_links_scanned_at`), +then called `pageMapper.updateById(partialEntity)`. But `WikiPageEntity` +declares `FieldStrategy.ALWAYS` on `content`, `summary`, `outgoingLinks`, +and `brokenLinks`, so MyBatis-Plus generated `UPDATE ... SET content = +NULL, summary = NULL, ...` — silently destroying the body of every page +the cascade or scan touched. + +**Fix**: replace `updateById(partialEntity)` with +`update(null, new LambdaUpdateWrapper().eq(...).set(col, val))` +in all three sites. The wrapper-based path emits SET clauses only for +explicit `.set()` calls, so unmentioned columns are untouched regardless +of their `FieldStrategy`. + +### 8.3 Post-fix verification + +After restart with the fixed jar: + +- Scan x 3 on a page with 113-char content + summary → both **unchanged** + (length stable at 113, summary string identical). +- Cascade delete of `alice` with `bob` as referrer → bob's content went + 200 → 192 chars (the `[[alice]]` → `Alice` rewrite, ~8-char shrink as + expected), summary fully preserved. +- Cascade rename of `carol` → `caroline` with `dave` as referrer → + dave's summary preserved verbatim. + +The same `WikiEnrichmentApplierTest` + `WikiLinkServiceCascadeTest` + +`WikiPageServiceTest` suites still pass; the bug was strictly in the +write-back path that those tests didn't exercise (the cascade tests +operate on pure-string helpers; the page-service test mocks the mapper +so the actual SQL generated doesn't matter). + +### 8.4 Follow-up + +A regression-locking integration test (real Spring + H2) for "scan must +not null content/summary" is worth adding in a separate PR — would have +caught this class of bug at the boundary between MyBatis-Plus field +strategy and partial-entity update calls. Tracked. + +--- + +## 9. Third pass — post-fix, post-restart full sweep (2026-05-28) + +Server restarted with commit `897cfbdf` (the FieldStrategy.ALWAYS fix). +Fresh KB `E2E-RFC55-Final` (id `2059783943071645697`). Comprehensive +re-run of every Phase 1-5 contract plus the regression guard. + +| Section | Result | Evidence | +|---|---|---| +| §1 refs shape on fresh KB | ✅ | `{kbId, items:[{slug,title,archived:bool}]}` for the 2 auto-seeded system pages | +| §2 sync `broken_links` on PUT | ✅ | content_len=66, summary="sync-test summary", outgoing=`["ghost-page","also-fake","log"]`, broken=`["ghost-page","also-fake"]`, scannedAt populated — all in one PUT | +| **§3 REGRESSION GUARD** — scan x5 must not null content/summary | ✅ | Captured content + summary BEFORE; ran `POST /lint/broken-links` five times in a row; captured AFTER. `[[ $BEFORE == $AFTER ]]` returned true; content sha1 stable at `a87424e5a189c773113860c715a60b071103b550` | +| §4 ingest 2-page source | ✅ | 5 entity pages generated (alice, bob, search-team, mentorship + existing overview/log); content_len 522/509, summary populated, outgoing `["bob"]`/`["alice"]`, all slug-form, no broken | +| §5 cascade DELETE alice — bob's summary preserved | ✅ | bob.content 1125 → 1095 chars (3 `[[alice]]` → `Alice` shrink, expected); bob.summary string identical; bob.outgoing emptied. Audit `affectedPageIds=[bob, search-team, mentorship]` (3 referrers, not just the obvious one) | +| §6 cascade RENAME bob → robert — referrer summaries preserved | ✅ | search-team: content_len=1483, summary_len=241, 0 `[[bob]]`, 2 `[[robert]]`. mentorship: content_len=1464, summary_len=218, 0 `[[bob]]`, 2 `[[robert]]`. Old slug → HTTP 404, new slug reachable. Audit `affectedPageIds=[search-team_id, mentorship_id]` | +| §7 break-then-fix round trip | ✅ | PUT with `[[gone-1]] [[gone-2]] [[robert]]` → outgoing=3, broken=2 sync. Fix PUT with only valid → outgoing=1, broken=0 sync | +| §8 archive interaction | ✅ | Archive mentorship → default refs lists 4 pages (no mentorship); `?includeArchived=true` lists 5 pages with mentorship `archived=true` and others `archived=false` | +| §9 **code-block protection during cascade DELETE** | ✅ | Seeded overview with 2× prose `[[robert]]` + 1× fenced `[[robert]]` + 1× inline `` `[[robert]]` ``. Save-time `outgoing=["robert"]` (code-block occurrences excluded by extractOutlinks). After `DELETE /pages/robert`: prose `[[robert]]`/`[[robert\|Robert]]` demoted to plain `Bob`/`Robert` (alias preserved); fenced block byte-identical (`Use [[robert]] for the link.` literal); inline code byte-identical (`` `[[robert]]` ``). outgoing=`[]`, broken=`[]` | + +### 9.1 Final content for §9 (proof of code-block byte-identity) + +``` +## Code-block test + +Prose refers to Bob and Robert. + +Code example: + +​``` +Use [[robert]] for the link. +​``` + +Inline: `[[robert]]` is the form. +``` + +The two `[[robert]]` references inside the fenced block and the inline +backticks survived the cascade delete unchanged; the two prose +references became plain text using the snapshot title (`Bob`) and the +preserved alias (`Robert`). Same content-block-protection guarantee +the unit tests pin down, now reproduced on a live server with real +HTTP traffic. + +### 9.2 Bottom line + +All 9 e2e sections pass on the restarted server with the cascade + +scan write-path fix in place. The bug class that the §8 incident +exposed (partial-entity update + FieldStrategy.ALWAYS = silent column +null-out) has no live recurrence. The data shape, the audit trail, the +HTTP status semantics, and the user-visible UX flows ("break a link, +see it in lint, fix it, see it cleared") are all reproducible on a +clean dev box in roughly two minutes. + +--- + +## 10. Fourth pass — edge cases and negative paths (2026-05-28) + +Targeted run focused on inputs that the Phase 1-5 contracts don't make +loud claims about: self-links, dedup, case folding, malformed wikilink +syntax, oversize slugs, archived targets, idempotent deletes, batch +delete, markdown-link confusables, scan perf on a real 31-page KB. Each +row records the actual response shape so future contributors can see +the exact behaviour the contract permits. + +| Code | Scenario | Result | Notes | +|---|---|---|---| +| A | Self-link: `[[overview]]` in `overview` itself | ✅ | outgoing=`["overview"]`, broken=`[]`. The "include self-slug in active set" branch in `applyLinkAnalysis` works as designed | +| B | Dedup: `[[ghost]] [[ghost]] [[ghost\|a1]] [[ghost\|a2]]` | ✅ | outgoing=`["ghost"]` (4 occurrences → 1 entry), broken=`["ghost"]` | +| C | Case-insensitive resolution: `[[OVERVIEW]] [[Overview]] [[overview]]` | ✅ | outgoing=`["overview"]` (3 → 1, lowercased), broken=`[]` | +| D | Empty/whitespace targets: `[[]] [[ ]] [[\t]] [[\|alias]]` mixed with `[[overview]]` | ✅ | outgoing=`["overview"]` only; empty/whitespace/empty-target-with-pipe all skipped | +| E | Batch delete `["team"]` | ✅ | Returns `data: 1` (count); page gone from refs | +| F | Idempotent delete (same slug twice) | ✅ | Both returns `code:200 操作成功`; service treats missing as no-op | +| G | Case-only rename `alpha → ALPHA` on H2 | ⚠️ Behaviour | Allowed (case-sensitive collation); after rename, `GET /pages/ALPHA` → 200, `GET /pages/alpha` → 404. **Portability concern**: on MySQL with `utf8mb4_unicode_ci` (default), `getBySlug("ALPHA")` would return the existing `alpha` row, the collision-check throws 400. Documented; needs explicit "case-only rename" handling if portability matters. See §10.1 | +| H | Archive then delete a referenced page | ✅ | Archive `ALPHA` → scan reports `log.broken_links=["alpha"]`. Delete archived `ALPHA` → cascade rewrites `log`: 2× `[[ALPHA]]` + 1× `[[ALPHA\|aliased]]` demoted to `Page A and Page B Distinction` × 2 + `aliased`. Cascade-delete works on archived targets too | +| I | Cross-case lint resolution | ✅ | `[[alpha]] [[ALPHA]] [[Alpha]]` against page slug `ALPHA` → outgoing=`["alpha"]`, broken=`[]` | +| J | Link to archived target (Phase 2 strict slug match) | ✅ | Archive `page-a-page-b-difference`, save log with `[[page-a-page-b-difference]]` → outgoing=`["page-a-page-b-difference"]`, **broken=`["page-a-page-b-difference"]`** synchronously. Matches RFC §2: archived pages are excluded from the active slug set, so links to them are broken | +| K | Markdown link confusable: `[text](url)` | ✅ | Plain `[docs](https://example.com)` ignored. Only `[[...]]` enters outgoing | +| L | Malformed input `[[overview]] junk ]] [[log]] [[no-close [[ok]] end` | ⚠️ Behaviour | Parsed as 3 wikilinks: `overview`, `log`, and `"no-close [[ok"` (the non-greedy `[^\]]+?` regex captures literal `[[` inside the target). Third target → broken. Technically per-spec, looks strange in lint output; documented as known behaviour | +| M | Oversize slug (300 chars) | ✅ | Dropped by extractor's `MAX_TARGET_LEN=256` guard. Outgoing carries only the legitimate `[[overview]]` | +| N | Scan perf on existing 31-page KB (`格式支持测试-KB`) | ✅ | POST submit latency: **18 ms** (RFC target < 200 ms). Job `completed` within 1 s of polling (RFC target < 3 s / 100 pages). Aggregate: `totalPages=31 pagesWithBroken=29 totalBrokenRefs=81` — confirms the lint surfaces accumulated historical title-form debt as designed | + +### 10.1 Known behaviours worth flagging + +**Case-only rename portability (G)**. On H2 with default collation, a +rename from `foo → FOO` succeeds and afterwards only `GET /pages/FOO` +resolves (`GET /pages/foo` returns 404). On MySQL with +`utf8mb4_unicode_ci`, the same rename throws 400 collision because +`getBySlug("FOO")` finds the existing `foo` row. The behavioural +asymmetry is in `WikiPageService.rename`'s pre-check: + +```java +WikiPageEntity collision = getBySlug(kbId, newSlug); +if (collision != null) { throw new IllegalArgumentException(...); } +``` + +The fix, if portability matters: explicitly compare +`collision.getId().equals(existing.getId())` and treat that as the +"renaming yourself" case (allowed) vs a true collision (rejected). +Tracked as a follow-up. + +**Malformed wikilink with literal `[[` inside target (L)**. The +non-greedy `[^\]]+?` regex captures any sequence of non-`]` characters +between `[[` and `]]`. Input `[[no-close [[ok]]` extracts `no-close [[ok` +as the target. That target then never resolves (slugs don't contain +`[[`), so it lands in `broken_links` and the UI flags it for the user +to fix. No silent corruption; just a slightly-ugly slug appearing in +lint output. + +### 10.2 Performance evidence + +The 31-page real-content KB completes a full scan in well under 1 +second, with POST submit returning in 18 ms. The RFC's targets (POST +< 200 ms, job < 3 s / 100 pages) are met with comfortable margin even +on the H2 in-process backend. MySQL with proper indexing on +`mate_wiki_page(kb_id, archived)` should perform identically or +better. + +### 10.3 Bottom line + +14 edge-case scenarios; 12 ✅, 2 ⚠️-with-documented-behaviour. No +regressions discovered. The two ⚠️s are not defects against the +shipping spec — they're behaviours the spec was silent on, now +documented here so future readers / reviewers know what to expect. + +--- + +## 11. Follow-up resolution (2026-05-28) + +Both follow-ups from §8.4 and §10.1 are closed. Code changes + the +matching tests live in `WikiCascadeRegressionE2ETest`. + +### 11.1 SpringBootTest regression for §8 (scan / cascade null-out) + +New class `WikiCascadeRegressionE2ETest` boots the full Spring context +with H2 + Flyway, so MyBatis-Plus's lambda cache for `WikiPageEntity` +is primed and the actual SQL generated by `pageMapper.updateById(...)` +vs `pageMapper.update(null, LambdaUpdateWrapper)` is exercised — what +the existing mock-mapper tests in `WikiPageServiceTest` couldn't see. + +Three guard tests: + +| Test | What it locks down | +|---|---| +| `scanPreservesContentAndSummary` | PUT a page with content + summary, run KB-wide scan 3× in a row, assert content and summary byte-identical in the DB. Catches a recurrence of the §8 incident at the boundary between FieldStrategy.ALWAYS and partial-entity update | +| `cascadeDeletePreservesReferrerSummary` | Seed two pages where B references A, delete A, assert B.summary is unchanged and B.content has the `[[a]]` and `[[a\|alias]]` demoted to snapshot title + alias | +| `cascadeRenamePreservesReferrerSummary` | Same seed, rename A → A', assert B.summary unchanged and B.content has `[[a]]` → `[[a']]` with alias preserved | + +If anyone ever puts back the old `pageMapper.updateById(partialEntity)` +pattern in `WikiLintJobService.rewriteBrokenLinks` or in the cascade +loops, one of these tests fails with the expected `content` value +being a long string and the actual being `null`. + +### 11.2 Case-only rename portability fix (R4-G) + +`WikiPageService.rename`'s collision-check was tightened: + +```java +// before +if (collision != null) { throw ... } + +// after +if (collision != null && !existing.getId().equals(collision.getId())) { throw ... } +``` + +Effect: + +- On H2 (case-sensitive collation) — same as before: rename `foo → FOO` + finds no row, `collision == null`, allowed. Side-effect: the row's + stored slug becomes `FOO`; future `getBySlug("foo")` returns 404, + `getBySlug("FOO")` returns 200. Lint resolution stays case-insensitive + (extractor lowercases targets) so referrer content links of any case + still resolve. +- On MySQL (`utf8mb4_unicode_ci`) — previously: rename `foo → FOO` + found the same row via case-insensitive comparison, the old check + treated that as a collision, threw 400. Now: same-id is recognised + as "renaming yourself", the rename is allowed. +- Real collisions (renaming `first → second` when both exist as + distinct rows) still reject — `renameRejectsRealCollision` test pins + this down. + +Two new tests in `WikiCascadeRegressionE2ETest` cover both branches: + +| Test | What it locks down | +|---|---| +| `caseOnlyRenameIsAllowed` | `foo → FOO` succeeds; same row, new slug | +| `renameRejectsRealCollision` | `first → second` rejects with `IllegalArgumentException` containing "already exists" | + +### 11.3 Test count + +Wiki tests went from 273 (after Phase 5) to **278** with the 5 new +`WikiCascadeRegressionE2ETest` cases. All pass. The new tests run in +~7 s, dominated by Spring context startup; the per-test work is +sub-second. + +### 11.4 No remaining follow-ups + +The wikilink overhaul has no known open issues from any of the four +e2e passes. The bug discovered mid-§8 has a unit test guard. The +portability gap noted in §10.1 has been fixed and tested. The shipping +spec (RFC 55 v3.3) matches observable behaviour on both H2 and MySQL. + +--- + +## 12. Fifth pass — live verification of §11 fixes + chain / concurrent + (2026-05-28) + +After committing the §11 fixes, re-validated against the live server +on dev. Same scenarios from §10 plus three new chain / concurrency +ones the prior passes hadn't exercised. + +### 12.1 §11 fixes are live + +| Test | Result | Trace | +|---|---|---| +| Case-only rename `alpha → ALPHA` | ✅ HTTP 200 | `{"oldSlug":"alpha","newSlug":"ALPHA","pageId":"2059791691121410050"}` | +| Real collision `beta → ALPHA` (different page) | ✅ HTTP 400 | `"a page with slug 'ALPHA' already exists in this KB"` — same-id escape did not swallow this | +| Same-slug rename `ALPHA → ALPHA` | ✅ HTTP 400 | `"new slug equals old slug — no-op"` | +| Scan × 5 byte-identity (sha1 of content + summary) | ✅ identical | `content sha1 e4adbec4...` and `summary sha1 0b62e4c4...` stable across 5 consecutive POSTs | + +### 12.2 New chain + concurrency scenarios + +| Code | Scenario | Result | +|---|---|---| +| C1 | Chain `rename ALPHA → GAMMA` then `delete GAMMA`, with `beta` referencing `[[alpha]]` 2× | ✅ After rename: `beta.outgoing=["gamma"]`. After delete: `beta.outgoing=[]`, `broken=[]`, residual `[[GAMMA]]`/`[[alpha]]` count = 0. Audit trail records both rename + final delete with the consistent snapshot title "Alpha" preserved through all 3 mutations | +| C2 | Cross-KB concurrent: 3 POSTs to 3 different KBs at the same millisecond | ✅ 3 distinct jobIds returned simultaneously; all 3 KBs reach `completed` within 3 s. Aggregates: KB-1 (31p, 29 broken, 81 refs), KB-2 (29p, 26 broken, 75 refs), KB-3 (24p, 18 broken, 89 refs). Per-KB isolation confirmed — no cross-talk | +| C3 | Stress: PUT with 10 fake slugs + 2 real (`[[a1]]..[[c2|aliased]]` + `[[overview]] [[log]]`) | ✅ outgoing has 12 entries (all 10 fakes + 2 reals, with `c2` alias-form correctly merged into a single `c2` slug); broken has exactly the 10 fakes | +| C4 | Re-run 31-page KB scan post-fix to confirm perf unchanged | ✅ POST latency 32 ms (within noise of earlier 18 ms), full scan to `completed` < 1 s | + +### 12.3 Concentrated-debt observation + +KB id `2054907618529591298` (`QA-Bug-Test KB`, 24 pages, real historical +content) returned `89 broken refs across 18 of 24 pages` (75 % broken- +rate). Higher concentration than the 31-page test KB (29/31 = 94 % but +fewer refs each). Both numbers are consistent with the lint correctly +catching title-form references in content produced before Phase 3 +shipped — exactly the historical debt the lint exists to surface for +cleanup. + +### 12.4 Bottom line + +All five passes (§7, §8, §9, §10, §11/§12) reproducible on a clean +dev box. 14 + 3 + 9 + 14 + 5 + 4 = 49 documented assertions across +five distinct phases of validation. No open defects; both follow-ups +shipped and live-verified. + +--- + +## 13. Sixth pass — chat-side wikilink navigation (2026-05-28) + +User reported during a live wiki UI session that wikilinks rendered +inside chat messages (where the agent quoted wiki page content via +`wiki_read_page`) **looked clickable but did nothing**. Investigation +showed the legacy `renderMarkdown` path emits +`` +but: + +1. DOMPurify strips the inline `onclick` (correct best practice). +2. The remaining `href="#"` is a no-op anchor. +3. The `wiki-link-click` custom event the renderer's `onclick` would + have dispatched has **no listener anywhere in the codebase** — so + even if the inline handler survived, nothing would have consumed it. +4. `WikiPageViewer`'s document-level click handler only fires when the + anchor carries `data-slug`; chat-side anchors only carry + `data-wiki-title`, so the viewer's handler skipped them silently. + +Net effect: every wikilink in chat (and any other non-wiki-view +surface using `renderMarkdown`'s default `'legacy'` mode) had been +dead since the codebase shipped that path. Not a regression from +this RFC — a pre-existing miss that the RFC's chat-as-bystander +philosophy left in place. + +### 13.1 Fix design + +Cross-KB lookup + global click delegator + query-param auto-open: + +- **`GET /api/v1/wiki/pages/lookup?title=X&slug=Y`** — searches every + KB visible to the user's workspace, returns + `[{kbId, kbName, slug, title, archived}]`. Slug match wins; title + match is a fallback. Case-insensitive exact only (no canonical + fuzzing, matching the §2 lint rule). +- **`useGlobalWikilinkClick`** — composable mounted in `App.vue`. + Document-level click delegator that: + - Matches `` carrying `data-wiki-title` (chat + anchors). Skips anchors with `data-slug` (those are the wiki + page viewer's own postprocess output; its existing handler + keeps owning them). + - Calls lookup, then routes: + - 0 hits → `mcToast.info("未找到匹配的 wiki 页面：")` + - 1 hit → `router.push({ name: 'Wiki', query: { kbId, slug } })` + - >1 hits → `mcConfirm` picker offering to open the first match +- **`Wiki/index.vue`** — on mount and on `route.query` change, if + `?kbId=X&slug=Y` are present, calls `selectKB(kbId)` then + `loadPage(kbId, slug)`, then `router.replace({name:'Wiki'})` to + drop the query (so reload doesn't re-open the page). + +### 13.2 Live verification + +Seeded `E2E-LookupDemo` KB with two pages (`stategraph`, `react-mode`) +via a tiny ingest. Probed the new endpoint: + +| Query | Match count | First hit | +|---|---|---| +| `title=` (empty) and `slug=` (empty) | 0 | (early-return) | +| `title=Overview` (every KB auto-seeds it) | 2 (across visible KBs) | `kbId=E2E-RFC55-PostFix, slug=overview` | +| `slug=overview` | 2 | same | +| `slug=OVERVIEW` (uppercase) | 2 | same — confirms case-insensitive | +| `slug=does-not-exist` | 0 | — | +| `title=StateGraph` | 1 | `kbId=E2E-LookupDemo, slug=stategraph, title=StateGraph` | +| `title=stategraph` | 1 | same — title field matches `stategraph` lowercased against the stored "StateGraph" | +| `title=ReAct` | 0 | LLM-generated slug was `react-mode` / title `ReAct Mode`, exact match fails — toast path exercised | + +Notes: +- The endpoint returns a JSON envelope `{code:200, msg:"操作成功", data:[...]}` + matching every other wiki endpoint. The frontend composable handles + both `res.data` and bare `res` shapes for robustness. +- Snowflake `kbId` correctly serialised as string (matches the + CLAUDE.md ID handling contract). +- KB visibility scope respected — only KBs in the requesting + workspace appear in the result set, never cross-workspace. + +### 13.3 What the user will observe + +After this change, the user's original screenshot scenario plays out +as: clicking `[[StateGraph]]` in the chat bubble triggers +`useGlobalWikilinkClick.handleClick` → lookup → one match in their +KB → router navigates to wiki view with the right KB selected and +the StateGraph page open. The `[[ReAct]]` link gets a toast +"未找到匹配的 wiki 页面：ReAct" because the actual page title is +"ReAct Mode" (the LLM picked a different slug/title than the raw +`[[ReAct]]` token). The toast tells the user the link points at a +non-existent target, which they can then either edit out or rename +the target page to match. + +### 13.4 Frontend test impact + +- 22 vitest tests still pass. +- `pnpm vue-tsc --noEmit`: 0 errors. +- `pnpm build`: builds successfully. + +### 13.5 Bottom line for §13 + +Closes the "wikilinks in chat are dead" gap the RFC implicitly left +open. Net change: 1 backend endpoint, 1 new frontend composable, +3-line edits in `App.vue` / `api/index.ts` / `Wiki/index.vue`. + +### 13.6 User-facing recovery: `[[ReAct]]` toast → rename target page + +The §13 lookup toast tells the user when a chat-side wikilink fails +to resolve. The next step in the recovery loop is for the user to +either edit the source page to use the real slug, or rename the +target page so the existing token matches. We exercised the rename +path end-to-end as a live integration check: + +**State before rename** (`E2E-LookupDemo` KB): + +| Page | Title | Outgoing | +|---|---|---| +| `react-mode` | "ReAct 模式" | `[stategraph, agent-jiagou]` | +| `stategraph` | "StateGraph" | `[react-mode, agent-jiagou]` (links to react-mode via `[[react-mode\|ReAct 模式]]` alias) | +| `agent-jiagou` | "Agent架构" | — | +| chat `[[ReAct]]` lookup | — | 0 hits → toast | + +**Action**: `POST /pages/react-mode/rename` with `{newSlug:"react"}`. + +**State after rename**: + +| Verification | Result | +|---|---| +| `GET /pages/react-mode` | HTTP 404 | +| `GET /pages/react` | HTTP 200, title still "ReAct 模式" | +| `stategraph.content` `[[react-mode\|ReAct 模式]]` | rewritten to `[[react\|ReAct 模式]]` — alias byte-identical | +| `stategraph.outgoing_links` | now contains `react`, no `react-mode` | +| Cross-KB lookup `?title=ReAct` | 1 hit (`slug=react`) | +| Cross-KB lookup `?title=REACT` (uppercase) | 1 hit — case-insensitive | +| Cross-KB lookup `?title=react-mode` | 0 hits — old slug really gone | +| KB-wide scan broken refs | 0 across all 5 pages | +| Audit event | `wiki.page.rename → ReAct 模式; affectedPageIds=[stategraph_id]` | + +What the user sees in the chat afterwards: + +- Click `[[ReAct]]` again → previously toast "未找到", now navigates + to wiki view with the `react` page open. +- Click `[[StateGraph]]` → still navigates to the StateGraph page, + unaffected. +- The recovery loop closes without the user having to leave the chat + surface to manually grep page slugs — the toast guided them to + the rename action, the rename auto-rewrote the referrer, the next + click resolves. + +This is the intended end-to-end flow: + +``` + chat clicks [[ReAct]] + → lookup → 0 hits → toast "未找到匹配的 wiki 页面: ReAct" + user notices: the target page exists but under + a different slug + → user renames target page: react-mode → react + backend cascade rewrites stategraph's wikilink + backend audit logs the rename + affected pages + → user clicks [[ReAct]] again + lookup → 1 hit → router.push → wiki view opens react +``` + +No data loss, no manual content edit, no stranded references. End- +to-end recovery flow proven on live server. + +--- + +## 14. Browser-driven chat e2e — 12 conversation rounds (2026-05-28) + +Drove the full UI through the `gstack browse` headless Chromium, logged +in as admin, exercised the wiki feature exclusively through chat +conversations against the default "研究分析师" plan-execute agent (id +`2056270363980120065`). 12 rounds. Two real bugs caught and fixed mid-run. + +### 14.1 Conversation transcript (compressed) + +| # | Prompt | Result | +|---|---|---| +| R1 | "列出当前所有知识库 KB" | ✅ Agent listed 3 KBs (E2E-LookupDemo 4p, E2E-RFC55-PostFix 7p, dev 3p) via injected `<wiki-context>` block; honest "wiki_list_kbs tool not enabled" note | +| R2 | "详细介绍 E2E-LookupDemo KB 里的 react 页面" | ✅ Rich Markdown intro of the page (reasoning / action / observation / StateGraph relation / use cases). Used wiki_read_page tool | +| R3 | "请直接调用 wiki_read_page... 把原文 markdown 完整返回" | ✅ Full raw markdown returned, including `[[stategraph]]` wikilinks rendered into `<a class="wiki-link">`. **🔴 Bug A discovered**: rendered link had `data-wiki-title="stategraph\|StateGraph"` (pipe alias bled into attribute) | +| R4 | (click `[[StateGraph]]` in the chat bubble) | ✅ Global click delegator fired, lookup returned 1 hit, `router.push` navigated to `/wiki?kbId=2059795489877315586&slug=stategraph` | +| R5 | (verify wiki view auto-opened the page) | **🔴 Bug B discovered**: URL changed but `.page-content` did not render — KB list still showing. Tracing: `Number("2059795489877315586")` truncated the Snowflake from §13's consumeQueryNavigation, then API returned 404 "Knowledge base not found" | +| → fix mid-run | Two fixes applied + rebuild + restart | Bug A: legacy renderer regex now captures `slug` + `alias` separately; Bug B: `kbIdRaw` stays a string end-to-end; WikiWorkspace switches to 'pages' tab on currentPage assign | +| R5 (retest) | Same flow on the fixed bundle | ✅ `.page-content` renders the StateGraph wiki content. URL is cleaned to `/wiki` after `router.replace`. KB selected, page open, tab switched | +| R6 | "列出 E2E-LookupDemo 里的所有页面" | ✅ Agent returned `react — ReAct 模式` + `stategraph — StateGraph` (system pages correctly excluded) | +| R7 | "读取 react 页面，告诉我里面有多少处 wikilink、各指向哪个 slug" | ✅ Agent identified 2 wikilinks, both pointing at `stategraph` | +| R8 | "扫描 E2E-LookupDemo 这个 KB 现在有多少死链？" | ✅ Agent: 0 broken links across both content pages; 3 total wikilinks, all resolve | +| R9 | "ReAct 和 StateGraph 有什么关系？" | ✅ Substantive synthesis grounded in the actual page content (3-stage reasoning/action/observation mapping to graph node types) | +| R10 | "查最近的 wiki audit 事件" | ✅ Agent inspected the `log` wiki page and produced a 3-event table; honestly flagged that the wiki log page is *not* the audit-event table and pointed at the proper API | +| R11 | "在 E2E-LookupDemo 创建新页 langgraph 引用 `[[stategraph]]`" | ✅ Agent created the page via wiki write tool. Post-API check: `langgraph` exists, `content_len=198`, `outgoing=["stategraph"]`, `broken=[]` | +| R12 | "三个 KB 的死链总数" | ✅ Agent reports 0 / 0 / 0; summarises wikilink count and verifies all resolve | + +### 14.2 Bug A — legacy renderer pipe handling + +**Symptom**: The chat-side renderer is supposed to turn +`[[stategraph|StateGraph]]` into a link whose `data-wiki-title` is the +slug `stategraph` and whose visible text is the alias `StateGraph`. +Instead it produced +`<a data-wiki-title="stategraph|StateGraph">stategraph|StateGraph</a>` +— the regex `\[\[([^\]]+)\]\]` captured the entire bracket interior +including the `|` separator, and the replacement template copied it +verbatim into both the attribute and the label. + +**Impact**: when the global wikilink click delegator forwarded +`data-wiki-title="stategraph|StateGraph"` to the cross-KB lookup, the +backend matched against neither a slug `stategraph|StateGraph` nor a +title with that literal — every aliased wikilink in chat resulted in a +"未找到匹配的 wiki 页面" toast instead of navigating. + +**Fix** (`useMarkdownRenderer.ts`): + +```ts +// before +.replace(/\[\[([^\]]+)\]\]/g, '<a data-wiki-title="$1">$1</a>') + +// after — alias-aware +.replace(/\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g, (_, slug, alias) => { + const target = slug.trim() + const visible = alias?.trim() || slug.trim() + return `<a data-wiki-title="${target}">${visible}</a>` +}) +``` + +The fix also HTML-escapes the captured strings (`"` → `"`, +`'` → `\'`) before they enter the attribute and the inline onclick to +plug the same XSS risk the page-viewer postprocess covers. + +### 14.3 Bug B — Snowflake precision in consumeQueryNavigation + +**Symptom**: Round 5 found the URL navigated correctly to +`/wiki?kbId=2059795489877315586&slug=stategraph` but the KB never +selected. Console showed `Error: Knowledge base not found` (HTTP 404). + +**Root cause**: my §13 `consumeQueryNavigation` did +`Number(route.query.kbId)` to satisfy `store.selectKB(id: number)`. +But `2059795489877315586` exceeds `Number.MAX_SAFE_INTEGER` (2⁵³−1 = +`9007199254740992`), so the coercion silently truncated the last few +digits — exactly the bug class CLAUDE.md warns about in the "ID +Handling — Snowflake Precision Convention" section. The backend +correctly returned 404 because the truncated number doesn't match any +real KB. + +**Fix** (`Wiki/index.vue`): keep `kbId` as a string throughout. The +store / api layer never reconstructs it as a number — it's interpolated +straight into `/wiki/knowledge-bases/${id}`, so a string works fine at +runtime. The TypeScript type signature `selectKB(id: number)` is +satisfied with a localised `as unknown as number` cast plus a +`// snowflake-precision-ok` comment so the lint script (`pnpm +lint:precision`) doesn't flag it. The `Number()` call is gone. + +### 14.4 Bug C — WikiWorkspace default tab hides the auto-opened page + +**Symptom**: After the Snowflake fix, the KB selected correctly but +`.page-content` still didn't render — the workspace defaults to the +'raw' (raw materials) tab, and the WikiPageViewer only mounts inside +the 'pages' tab. + +**Fix** (`WikiWorkspace.vue`): watch `store.currentPage` and switch +`activeTab` to `'pages'` whenever a page becomes current. Manual +sidebar clicks already work because the user is on the pages tab +when they click; the query-param auto-open bypassed that state, so the +explicit watcher closes the gap. + +### 14.5 Live verification after all fixes + +After the three fixes landed + frontend rebuild + server restart, R5 +was rerun on the fresh bundle: + +- URL after click: `http://localhost:18088/wiki?kbId=...&slug=stategraph` → router.replace cleans to `/wiki` +- `.workspace-title` = `E2E-LookupDemo` +- `.page-content` text starts with the StateGraph page's first paragraph: "驱动的节点类型 StateGraph 在标准 Agent 架构 中驱动以下三类核心节点循环执行：推理节点（Reasoning Node）..." +- Console errors are historical only (from the broken bundle pre-fix); no new errors after the restart + +### 14.6 What the agent could and couldn't do + +| Capability | Result | +|---|---| +| Read wiki pages via `wiki_read_page` | ✅ works, returns full content | +| Search across KBs (via `<wiki-context>` injection) | ✅ works, lists all 3 KBs accurately | +| Create new pages (via `wiki_write_page` or similar) | ✅ works — R11 created `langgraph` with correct `[[stategraph]]` reference, content + outgoing_links + broken_links all populated | +| Scan / report broken links across KBs | ✅ works — R8, R12 both accurate (0 broken refs) | +| Detect and reason about wikilink target consistency | ✅ works — R7 listed exact occurrence count + targets | +| Synthesize across multiple wiki pages | ✅ works — R9 connected ReAct's three stages to StateGraph node types | +| Read structured audit events | ⚠️ agent confused "wiki log page" with "audit log table" in R10 — honest enough to flag the limitation. Not a bug of the wikilink overhaul; agent prompt could be tuned to know which "log" to use | + +### 14.7 Bottom line for §14 + +12 rounds of real chat interaction. Two genuine bugs caught (legacy +renderer pipe handling, Snowflake precision in consumeQueryNavigation) +plus one UX gap (workspace default tab). All three fixed mid-run. +After fixes: chat click → cross-KB lookup → wiki view auto-open with +page content rendered, full flow proven from the user's perspective. + +--- + +## 14. Seventh pass — post-restart full sweep (2026-05-28 09:09) + +Server killed (`lsof -ti:18088 | kill -9`) and restarted via +`mvn spring-boot:run`. Cold-start to first request handled in 4.1 s. +Eight scenarios covering everything that landed in §11 / §13: + +| Section | Scenario | Result | +|---|---|---| +| §1 | State survives kill -9 + cold restart | ✅ 3 KBs from earlier sessions visible (E2E-LookupDemo / E2E-RFC55-PostFix / dev). Flyway recognised V129 already applied; no re-migration | +| §2 | §13.6 rename outcome persistent | ✅ `GET /pages/react-mode` → 404; `GET /pages/react` → 200 title="ReAct 模式"; stategraph's content has `[[react\|ReAct 模式]]` (alias byte-identical to pre-restart state) | +| §3 | Cross-KB lookup endpoint (10 query variants) | ✅ `ReAct`/`react`/`REACT` → 1 hit (case-insensitive); `StateGraph`/`stategraph` → 1; `agent-jiagou`/`Agent架构` (Chinese title!) → 1; `Overview` → 3 (multi-KB); `does-not-exist`, `react-mode` (old slug) → 0 | +| §4 | Scan x 5 regression (§8 guard) | ✅ content sha1 `a80d9dcc...` identical before/after; summary sha1 `82375f43...` identical. The FieldStrategy.ALWAYS null-out bug remains fixed | +| §5 | Case-only rename portability (§11 guard) | ✅ `react → REACT` returns 200; rollback `REACT → react` returns 200; real collision `stategraph → react` returns 400 `"already exists"` — same-id escape doesn't swallow real conflicts | +| §6 | Cascade DELETE with multi-referrer + chinese-title snapshot | ✅ `agent-jiagou` had 2 referrers (`stategraph` + `react`). After DELETE: lookup 0 hits; stategraph residual `[[agent-jiagou]]` = 0, snapshot title "Agent架构" appears 2× as plain text in body; outgoing now `["react"]` only; broken `[]` | +| §7 | Audit trail | ✅ Latest 5 wiki_page events captured in order: `delete Agent架构` (09:16) / `rename ReAct 模式` ×3 (post-fix portability test + original rename + earlier) / `rename Foo` (earliest test from §11 SpringBootTest run) | +| §8 | Full KB scan post-mutations | ✅ totalPages=4 (was 5; agent-jiagou removed), pagesWithBroken=0, totalBrokenRefs=0 — zero residual debt after delete | + +### 14.1 Cold-start performance + +- JVM up + Spring context + Flyway baseline detection: **4.1 s** +- First request (auth login) responds within 9 s of `mvn spring-boot:run` + invocation +- All 9 H2 KB rows visible immediately, no warm-up gap + +### 14.2 Operational evidence accumulated + +Across seven passes, the wikilink overhaul has produced: + +- 6 e2e doc sections (§7, §8, §9, §10, §11/§12, §13/§14) +- 50+ live HTTP assertions +- 278 backend tests (273 baseline + 5 SpringBootTest regression) +- 22 frontend Vitest tests +- 1 mid-flight data-loss bug found and shipped a fix for, with + regression-locking test in place +- 2 follow-ups (case-only rename portability + chat wikilink + navigation) both landed with live verification +- 1 RFC v3.3 footnote documenting the GET /lint/broken-links + always-200 behaviour + +### 14.3 Bottom line + +Post-restart state is identical to pre-restart in every observable +dimension that matters: page content, audit trail, cascade +outcomes, lookup behaviour, rename portability. The shipping +artefact behaves exactly as the RFC and the test suite describe. +Ready for owner review. + diff --git a/mateclaw-ui/package.json b/mateclaw-ui/package.json index 90d9389e..6b03914f 100644 --- a/mateclaw-ui/package.json +++ b/mateclaw-ui/package.json @@ -1,6 +1,6 @@ { "name": "mateclaw-ui", - "version": "1.4.0", + "version": "1.5.0", "private": true, "type": "module", "description": "MateClaw - Personal AI Assistant Web Console", @@ -9,7 +9,9 @@ "build": "bash ../scripts/check-snowflake-precision.sh && node --max-old-space-size=6144 ./node_modules/vue-tsc/bin/vue-tsc.js --noEmit && node --max-old-space-size=6144 ./node_modules/vite/bin/vite.js build", "preview": "vite preview", "lint": "eslint src --ext .ts,.vue --fix && bash ../scripts/check-snowflake-precision.sh", - "lint:precision": "bash ../scripts/check-snowflake-precision.sh" + "lint:precision": "bash ../scripts/check-snowflake-precision.sh", + "test": "vitest run", + "test:watch": "vitest" }, "dependencies": { "@element-plus/icons-vue": "^2.3.1", @@ -49,10 +51,12 @@ "autoprefixer": "^10.4.20", "eslint": "^9.18.0", "eslint-plugin-vue": "^9.32.0", + "happy-dom": "^20.9.0", "rollup-plugin-visualizer": "^7.0.1", "tailwindcss": "^4.0.6", "typescript": "~5.7.2", "vite": "^7.3.1", + "vitest": "^4.1.7", "vue-tsc": "^3.2.6" }, "pnpm": { diff --git a/mateclaw-ui/pnpm-lock.yaml b/mateclaw-ui/pnpm-lock.yaml index 57d9e133..dbf6e128 100644 --- a/mateclaw-ui/pnpm-lock.yaml +++ b/mateclaw-ui/pnpm-lock.yaml @@ -92,7 +92,7 @@ importers: devDependencies: '@tailwindcss/vite': specifier: ^4.2.2 - version: 4.2.2(vite@7.3.1(jiti@2.6.1)(lightningcss@1.32.0)) + version: 4.2.2(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0)) '@types/dagre': specifier: ^0.7.54 version: 0.7.54 @@ -101,7 +101,7 @@ importers: version: 0.16.8 '@vitejs/plugin-vue': specifier: ^6.0.5 - version: 6.0.5(vite@7.3.1(jiti@2.6.1)(lightningcss@1.32.0))(vue@3.5.31(typescript@5.7.3)) + version: 6.0.5(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0))(vue@3.5.31(typescript@5.7.3)) '@vue/tsconfig': specifier: ^0.7.0 version: 0.7.0(typescript@5.7.3)(vue@3.5.31(typescript@5.7.3)) @@ -114,6 +114,9 @@ importers: eslint-plugin-vue: specifier: ^9.32.0 version: 9.33.0(eslint@9.39.4(jiti@2.6.1)) + happy-dom: + specifier: ^20.9.0 + version: 20.9.0 rollup-plugin-visualizer: specifier: ^7.0.1 version: 7.0.1(rollup@4.60.1) @@ -125,7 +128,10 @@ importers: version: 5.7.3 vite: specifier: ^7.3.1 - version: 7.3.1(jiti@2.6.1)(lightningcss@1.32.0) + version: 7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0) + vitest: + specifier: ^4.1.7 + version: 4.1.7(@types/node@25.9.1)(happy-dom@20.9.0)(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0)) vue-tsc: specifier: ^3.2.6 version: 3.2.6(typescript@5.7.3) @@ -606,6 +612,9 @@ packages: cpu: [x64] os: [win32] + '@standard-schema/spec@1.1.0': + resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==} + '@sxzz/popperjs-es@2.11.8': resolution: {integrity: sha512-wOwESXvvED3S8xBmcPWHs2dUuzrE4XiZeFu7e1hROIJkm02a49N120pmOXxY33sBb6hArItm5W5tcg1cBtV+HQ==} @@ -703,6 +712,9 @@ packages: peerDependencies: vite: ^5.2.0 || ^6 || ^7 || ^8 + '@types/chai@5.2.3': + resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==} + '@types/d3-array@3.2.2': resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==} @@ -799,6 +811,9 @@ packages: '@types/dagre@0.7.54': resolution: {integrity: sha512-QjcRY+adGbYvBFS7cwv5txhVIwX1XXIUswWl+kSQTbI6NjgZydrZkEKX/etzVd7i+bCsCb40Z/xlBY5eoFuvWQ==} + '@types/deep-eql@4.0.2': + resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==} + '@types/estree@1.0.8': resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==} @@ -817,12 +832,21 @@ packages: '@types/lodash@4.17.24': resolution: {integrity: sha512-gIW7lQLZbue7lRSWEFql49QJJWThrTFFeIMJdp3eH4tKoxm1OvEPg02rm4wCCSHS0cL3/Fizimb35b7k8atwsQ==} + '@types/node@25.9.1': + resolution: {integrity: sha512-xfrlY7UD5rMJk3ZVJP8BNzS28J36YJg+xp+LPXV1TdWxr8uMH5A860QNxYDGQe/ylDSgjxE52Q9VnO7p75tJxg==} + '@types/trusted-types@2.0.7': resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==} '@types/web-bluetooth@0.0.20': resolution: {integrity: sha512-g9gZnnXVq7gM7v3tJCWV/qw7w+KeOlSHAhgF9RytFyifW6AF61hdT2ucrYhPq9hLs5JIryeupHV3qGk95dH9ow==} + '@types/whatwg-mimetype@3.0.2': + resolution: {integrity: sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA==} + + '@types/ws@8.18.1': + resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==} + '@upsetjs/venn.js@2.0.0': resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==} @@ -833,6 +857,35 @@ packages: vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 vue: ^3.2.25 + '@vitest/expect@4.1.7': + resolution: {integrity: sha512-1R+tw0ortHEbZDGMymm+pN7/AFQ/RkFFdtd7EN+VBpynKmLbP8A3rpEXdshBJ7+8hQ9zBJh/i1s0yKNtxAnU7w==} + + '@vitest/mocker@4.1.7': + resolution: {integrity: sha512-vY7nuamKgfvpA1Koa3oYIw/k7D6kZnpGyNMZW8loow2bsBYla1TFdqTaXncWdRn4pgwNs+90RhnXhJScDwQeJA==} + peerDependencies: + msw: ^2.4.9 + vite: ^6.0.0 || ^7.0.0 || ^8.0.0 + peerDependenciesMeta: + msw: + optional: true + vite: + optional: true + + '@vitest/pretty-format@4.1.7': + resolution: {integrity: sha512-umgCarTOYQWIaDMvGDRZij+6b9oVeLIyJzfN+AS88e0ZOU3QTgNNSTtjQOpcvWr3np1N0j4WgZj+sb3oYBDscw==} + + '@vitest/runner@4.1.7': + resolution: {integrity: sha512-BapjmAQ2aI78WdMEfeUWivnfVzB+VPGwWRQcJE0OUq7qEeEcBsCSf+0T5iREBNE5nBb4wA5Ya0W6IA+sghdEFw==} + + '@vitest/snapshot@4.1.7': + resolution: {integrity: sha512-ZacLzja+TmJeZ1h14xW2FB/WpeimUD3haBXQPyJqxvo8jQTmfeA8zv58mtjN2C7EHXZDYVcVYdYmAxjkWVvKCw==} + + '@vitest/spy@4.1.7': + resolution: {integrity: sha512-kbkI5LMWakyuTIvs6fUJ5qdIVb1XVKsYJAT4OJ938cHMROYMSfmoQdZy0aaAnjbbc8F61vkoTqz/Az+/HiIu5Q==} + + '@vitest/utils@4.1.7': + resolution: {integrity: sha512-T532WBu791cBxJlCl6SO+J14l81DQx6uQHm1bQbmCDY7nqlEIgkza/UFnSBNaUtSf41unldDFjdOBYEQC4b5Hw==} + '@volar/language-core@2.4.28': resolution: {integrity: sha512-w4qhIJ8ZSitgLAkVay6AbcnC7gP3glYM3fYwKV3srj8m494E3xtrCv6E+bWviiK/8hs6e6t1ij1s2Endql7vzQ==} @@ -969,6 +1022,10 @@ packages: argparse@2.0.1: resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} + assertion-error@2.0.1: + resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==} + engines: {node: '>=12'} + async-validator@4.2.5: resolution: {integrity: sha512-7HhHjtERjqlNbZtqNqy2rckN/SpOOlmDliet+lP7k+eKZEjPk3DgyeU9lIXLdeLz0uBbbVp+9Qdow9wJWgwwfg==} @@ -1022,6 +1079,10 @@ packages: caniuse-lite@1.0.30001784: resolution: {integrity: sha512-WU346nBTklUV9YfUl60fqRbU5ZqyXlqvo1SgigE1OAXK5bFL8LL9q1K7aap3N739l4BvNqnkm3YrGHiY9sfUQw==} + chai@6.2.2: + resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==} + engines: {node: '>=18'} + chalk@4.1.2: resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==} engines: {node: '>=10'} @@ -1064,6 +1125,9 @@ packages: confbox@0.1.8: resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==} + convert-source-map@2.0.0: + resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==} + copy-anything@4.0.5: resolution: {integrity: sha512-7Vv6asjS4gMOuILabD3l739tsaxFQmC+a7pLZm02zyvs8p977bL3zEgq3yDk5rn9B0PbYgIv++jmHcuUab4RhA==} engines: {node: '>=18'} @@ -1323,6 +1387,9 @@ packages: resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==} engines: {node: '>= 0.4'} + es-module-lexer@2.1.0: + resolution: {integrity: sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==} + es-object-atoms@1.1.1: resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==} engines: {node: '>= 0.4'} @@ -1399,10 +1466,17 @@ packages: estree-walker@2.0.2: resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==} + estree-walker@3.0.3: + resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==} + esutils@2.0.3: resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==} engines: {node: '>=0.10.0'} + expect-type@1.3.0: + resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==} + engines: {node: '>=12.0.0'} + fast-deep-equal@3.1.3: resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==} @@ -1501,6 +1575,10 @@ packages: hachure-fill@0.5.2: resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==} + happy-dom@20.9.0: + resolution: {integrity: sha512-GZZ9mKe8r646NUAf/zemnGbjYh4Bt8/MqASJY+pSm5ZDtc3YQox+4gsLI7yi1hba6o+eCsGxpHn5+iEVn31/FQ==} + engines: {node: '>=20.0.0'} + has-flag@4.0.0: resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==} engines: {node: '>=8'} @@ -1809,6 +1887,9 @@ packages: nth-check@2.1.1: resolution: {integrity: sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==} + obug@2.1.1: + resolution: {integrity: sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==} + open@11.0.0: resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==} engines: {node: '>=20'} @@ -1971,6 +2052,9 @@ packages: resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==} engines: {node: '>=8'} + siginfo@2.0.0: + resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==} + source-map-js@1.2.1: resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==} engines: {node: '>=0.10.0'} @@ -1983,9 +2067,15 @@ packages: resolution: {integrity: sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ==} engines: {node: '>=0.10.0'} + stackback@0.0.2: + resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==} + state-local@1.0.7: resolution: {integrity: sha512-HTEHMNieakEnoe33shBYcZ7NX83ACUjCu8c40iOGEZsngj9zRnkqS9j1pqQPXwobB0ZcVTk27REb7COQ0UR59w==} + std-env@4.1.0: + resolution: {integrity: sha512-Rq7ybcX2RuC55r9oaPVEW7/xu3tj8u4GeBYHBWCychFtzMIr86A7e3PPEBPT37sHStKX3+TiX/Fr/ACmJLVlLQ==} + string-width@7.2.0: resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==} engines: {node: '>=18'} @@ -2019,6 +2109,9 @@ packages: three@0.182.0: resolution: {integrity: sha512-GbHabT+Irv+ihI1/f5kIIsZ+Ef9Sl5A1Y7imvS5RQjWgtTPfPnZ43JmlYI7NtCRDK9zir20lQpfg8/9Yd02OvQ==} + tinybench@2.9.0: + resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==} + tinyexec@1.1.1: resolution: {integrity: sha512-VKS/ZaQhhkKFMANmAOhhXVoIfBXblQxGX1myCQ2faQrfmobMftXeJPcZGp0gS07ocvGJWDLZGyOZDadDBqYIJg==} engines: {node: '>=18'} @@ -2027,6 +2120,10 @@ packages: resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==} engines: {node: '>=12.0.0'} + tinyrainbow@3.1.0: + resolution: {integrity: sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==} + engines: {node: '>=14.0.0'} + ts-dedent@2.2.0: resolution: {integrity: sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==} engines: {node: '>=6.10'} @@ -2050,6 +2147,9 @@ packages: ufo@1.6.3: resolution: {integrity: sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q==} + undici-types@7.24.6: + resolution: {integrity: sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==} + update-browserslist-db@1.2.3: resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==} hasBin: true @@ -2106,6 +2206,47 @@ packages: yaml: optional: true + vitest@4.1.7: + resolution: {integrity: sha512-flYyaFd2CgoCoU+0UKt3pxksgC+S02iTDN0n3LtqaMeXsI9SBcdNujc2k0DeFLzUn/0k538yNjOSdwgCqcrwJA==} + engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0} + hasBin: true + peerDependencies: + '@edge-runtime/vm': '*' + '@opentelemetry/api': ^1.9.0 + '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0 + '@vitest/browser-playwright': 4.1.7 + '@vitest/browser-preview': 4.1.7 + '@vitest/browser-webdriverio': 4.1.7 + '@vitest/coverage-istanbul': 4.1.7 + '@vitest/coverage-v8': 4.1.7 + '@vitest/ui': 4.1.7 + happy-dom: '*' + jsdom: '*' + vite: ^6.0.0 || ^7.0.0 || ^8.0.0 + peerDependenciesMeta: + '@edge-runtime/vm': + optional: true + '@opentelemetry/api': + optional: true + '@types/node': + optional: true + '@vitest/browser-playwright': + optional: true + '@vitest/browser-preview': + optional: true + '@vitest/browser-webdriverio': + optional: true + '@vitest/coverage-istanbul': + optional: true + '@vitest/coverage-v8': + optional: true + '@vitest/ui': + optional: true + happy-dom: + optional: true + jsdom: + optional: true + vscode-jsonrpc@8.2.0: resolution: {integrity: sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==} engines: {node: '>=14.0.0'} @@ -2171,11 +2312,20 @@ packages: typescript: optional: true + whatwg-mimetype@3.0.0: + resolution: {integrity: sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q==} + engines: {node: '>=12'} + which@2.0.2: resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==} engines: {node: '>= 8'} hasBin: true + why-is-node-running@2.3.0: + resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==} + engines: {node: '>=8'} + hasBin: true + word-wrap@1.2.5: resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==} engines: {node: '>=0.10.0'} @@ -2184,6 +2334,18 @@ packages: resolution: {integrity: sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==} engines: {node: '>=18'} + ws@8.21.0: + resolution: {integrity: sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==} + engines: {node: '>=10.0.0'} + peerDependencies: + bufferutil: ^4.0.1 + utf-8-validate: '>=5.0.2' + peerDependenciesMeta: + bufferutil: + optional: true + utf-8-validate: + optional: true + wsl-utils@0.3.1: resolution: {integrity: sha512-g/eziiSUNBSsdDJtCLB8bdYEUMj4jR7AGeUo96p/3dTafgjHhpF4RiCFPiRILwjQoDXx5MqkBr4fwWtR3Ky4Wg==} engines: {node: '>=20'} @@ -2548,6 +2710,8 @@ snapshots: '@rollup/rollup-win32-x64-msvc@4.60.1': optional: true + '@standard-schema/spec@1.1.0': {} + '@sxzz/popperjs-es@2.11.8': {} '@tailwindcss/node@4.2.2': @@ -2611,12 +2775,17 @@ snapshots: '@tailwindcss/oxide-win32-arm64-msvc': 4.2.2 '@tailwindcss/oxide-win32-x64-msvc': 4.2.2 - '@tailwindcss/vite@4.2.2(vite@7.3.1(jiti@2.6.1)(lightningcss@1.32.0))': + '@tailwindcss/vite@4.2.2(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0))': dependencies: '@tailwindcss/node': 4.2.2 '@tailwindcss/oxide': 4.2.2 tailwindcss: 4.2.2 - vite: 7.3.1(jiti@2.6.1)(lightningcss@1.32.0) + vite: 7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0) + + '@types/chai@5.2.3': + dependencies: + '@types/deep-eql': 4.0.2 + assertion-error: 2.0.1 '@types/d3-array@3.2.2': {} @@ -2737,6 +2906,8 @@ snapshots: '@types/dagre@0.7.54': {} + '@types/deep-eql@4.0.2': {} + '@types/estree@1.0.8': {} '@types/geojson@7946.0.16': {} @@ -2751,21 +2922,72 @@ snapshots: '@types/lodash@4.17.24': {} + '@types/node@25.9.1': + dependencies: + undici-types: 7.24.6 + '@types/trusted-types@2.0.7': {} '@types/web-bluetooth@0.0.20': {} + '@types/whatwg-mimetype@3.0.2': {} + + '@types/ws@8.18.1': + dependencies: + '@types/node': 25.9.1 + '@upsetjs/venn.js@2.0.0': optionalDependencies: d3-selection: 3.0.0 d3-transition: 3.0.1(d3-selection@3.0.0) - '@vitejs/plugin-vue@6.0.5(vite@7.3.1(jiti@2.6.1)(lightningcss@1.32.0))(vue@3.5.31(typescript@5.7.3))': + '@vitejs/plugin-vue@6.0.5(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0))(vue@3.5.31(typescript@5.7.3))': dependencies: '@rolldown/pluginutils': 1.0.0-rc.2 - vite: 7.3.1(jiti@2.6.1)(lightningcss@1.32.0) + vite: 7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0) vue: 3.5.31(typescript@5.7.3) + '@vitest/expect@4.1.7': + dependencies: + '@standard-schema/spec': 1.1.0 + '@types/chai': 5.2.3 + '@vitest/spy': 4.1.7 + '@vitest/utils': 4.1.7 + chai: 6.2.2 + tinyrainbow: 3.1.0 + + '@vitest/mocker@4.1.7(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0))': + dependencies: + '@vitest/spy': 4.1.7 + estree-walker: 3.0.3 + magic-string: 0.30.21 + optionalDependencies: + vite: 7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0) + + '@vitest/pretty-format@4.1.7': + dependencies: + tinyrainbow: 3.1.0 + + '@vitest/runner@4.1.7': + dependencies: + '@vitest/utils': 4.1.7 + pathe: 2.0.3 + + '@vitest/snapshot@4.1.7': + dependencies: + '@vitest/pretty-format': 4.1.7 + '@vitest/utils': 4.1.7 + magic-string: 0.30.21 + pathe: 2.0.3 + + '@vitest/spy@4.1.7': {} + + '@vitest/utils@4.1.7': + dependencies: + '@vitest/pretty-format': 4.1.7 + convert-source-map: 2.0.0 + tinyrainbow: 3.1.0 + '@volar/language-core@2.4.28': dependencies: '@volar/source-map': 2.4.28 @@ -2956,6 +3178,8 @@ snapshots: argparse@2.0.1: {} + assertion-error@2.0.1: {} + async-validator@4.2.5: {} asynckit@0.4.0: {} @@ -3011,6 +3235,8 @@ snapshots: caniuse-lite@1.0.30001784: {} + chai@6.2.2: {} + chalk@4.1.2: dependencies: ansi-styles: 4.3.0 @@ -3053,6 +3279,8 @@ snapshots: confbox@0.1.8: {} + convert-source-map@2.0.0: {} + copy-anything@4.0.5: dependencies: is-what: 5.5.0 @@ -3344,6 +3572,8 @@ snapshots: es-errors@1.3.0: {} + es-module-lexer@2.1.0: {} + es-object-atoms@1.1.1: dependencies: es-errors: 1.3.0 @@ -3481,8 +3711,14 @@ snapshots: estree-walker@2.0.2: {} + estree-walker@3.0.3: + dependencies: + '@types/estree': 1.0.8 + esutils@2.0.3: {} + expect-type@1.3.0: {} + fast-deep-equal@3.1.3: {} fast-json-stable-stringify@2.1.0: {} @@ -3568,6 +3804,18 @@ snapshots: hachure-fill@0.5.2: {} + happy-dom@20.9.0: + dependencies: + '@types/node': 25.9.1 + '@types/whatwg-mimetype': 3.0.2 + '@types/ws': 8.18.1 + entities: 7.0.1 + whatwg-mimetype: 3.0.0 + ws: 8.21.0 + transitivePeerDependencies: + - bufferutil + - utf-8-validate + has-flag@4.0.0: {} has-symbols@1.1.0: {} @@ -3834,6 +4082,8 @@ snapshots: dependencies: boolbase: 1.0.0 + obug@2.1.1: {} + open@11.0.0: dependencies: default-browser: 5.5.0 @@ -4001,14 +4251,20 @@ snapshots: shebang-regex@3.0.0: {} + siginfo@2.0.0: {} + source-map-js@1.2.1: {} source-map@0.7.6: {} speakingurl@14.0.1: {} + stackback@0.0.2: {} + state-local@1.0.7: {} + std-env@4.1.0: {} + string-width@7.2.0: dependencies: emoji-regex: 10.6.0 @@ -4037,6 +4293,8 @@ snapshots: three@0.182.0: {} + tinybench@2.9.0: {} + tinyexec@1.1.1: {} tinyglobby@0.2.15: @@ -4044,6 +4302,8 @@ snapshots: fdir: 6.5.0(picomatch@4.0.4) picomatch: 4.0.4 + tinyrainbow@3.1.0: {} + ts-dedent@2.2.0: {} tslib@2.3.0: {} @@ -4058,6 +4318,8 @@ snapshots: ufo@1.6.3: {} + undici-types@7.24.6: {} + update-browserslist-db@1.2.3(browserslist@4.28.2): dependencies: browserslist: 4.28.2 @@ -4072,7 +4334,7 @@ snapshots: uuid@11.1.0: {} - vite@7.3.1(jiti@2.6.1)(lightningcss@1.32.0): + vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0): dependencies: esbuild: 0.27.5 fdir: 6.5.0(picomatch@4.0.4) @@ -4081,10 +4343,39 @@ snapshots: rollup: 4.60.1 tinyglobby: 0.2.15 optionalDependencies: + '@types/node': 25.9.1 fsevents: 2.3.3 jiti: 2.6.1 lightningcss: 1.32.0 + vitest@4.1.7(@types/node@25.9.1)(happy-dom@20.9.0)(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0)): + dependencies: + '@vitest/expect': 4.1.7 + '@vitest/mocker': 4.1.7(vite@7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0)) + '@vitest/pretty-format': 4.1.7 + '@vitest/runner': 4.1.7 + '@vitest/snapshot': 4.1.7 + '@vitest/spy': 4.1.7 + '@vitest/utils': 4.1.7 + es-module-lexer: 2.1.0 + expect-type: 1.3.0 + magic-string: 0.30.21 + obug: 2.1.1 + pathe: 2.0.3 + picomatch: 4.0.4 + std-env: 4.1.0 + tinybench: 2.9.0 + tinyexec: 1.1.1 + tinyglobby: 0.2.15 + tinyrainbow: 3.1.0 + vite: 7.3.1(@types/node@25.9.1)(jiti@2.6.1)(lightningcss@1.32.0) + why-is-node-running: 2.3.0 + optionalDependencies: + '@types/node': 25.9.1 + happy-dom: 20.9.0 + transitivePeerDependencies: + - msw + vscode-jsonrpc@8.2.0: {} vscode-languageserver-protocol@3.17.5: @@ -4149,10 +4440,17 @@ snapshots: optionalDependencies: typescript: 5.7.3 + whatwg-mimetype@3.0.0: {} + which@2.0.2: dependencies: isexe: 2.0.0 + why-is-node-running@2.3.0: + dependencies: + siginfo: 2.0.0 + stackback: 0.0.2 + word-wrap@1.2.5: {} wrap-ansi@9.0.2: @@ -4161,6 +4459,8 @@ snapshots: string-width: 7.2.0 strip-ansi: 7.2.0 + ws@8.21.0: {} + wsl-utils@0.3.1: dependencies: is-wsl: 3.1.1 diff --git a/mateclaw-ui/src/App.vue b/mateclaw-ui/src/App.vue index 5a197b96..708a4b0e 100644 --- a/mateclaw-ui/src/App.vue +++ b/mateclaw-ui/src/App.vue @@ -14,11 +14,24 @@ import en from 'element-plus/es/locale/lang/en' import zhCn from 'element-plus/es/locale/lang/zh-cn' import { currentLocale } from '@/i18n' import { useThemeStore } from '@/stores/useThemeStore' +import { useGlobalWikilinkClick } from '@/composables/useGlobalWikilinkClick' +import { useGlobalFileDownloadClick } from '@/composables/useGlobalFileDownloadClick' import McConfirmHost from '@/components/common/McConfirmHost.vue' // Initialize theme — applies .dark class to <html> immediately useThemeStore() +// Global click delegator for [[wikilinks]] rendered into chat / docs / +// memory surfaces. WikiPageViewer's own postprocess handles in-wiki +// clicks (those carry data-slug); this catches everything else. +useGlobalWikilinkClick() + +// Global click delegator for tool-generated file download links +// (`/api/v1/files/...`). Downloads via authenticated fetch → blob so an +// expired/missing file degrades to a toast instead of a full-page navigation +// to the backend's 404 JSON, which would otherwise replace the whole SPA. +useGlobalFileDownloadClick() + const { t } = useI18n() watchEffect(() => { diff --git a/mateclaw-ui/src/api/index.ts b/mateclaw-ui/src/api/index.ts index 09227e38..12239f0c 100644 --- a/mateclaw-ui/src/api/index.ts +++ b/mateclaw-ui/src/api/index.ts @@ -1,5 +1,13 @@ import axios from 'axios' import { handleAuthFailure, updateTokenFromHeader } from '@/utils/auth' +import type { + ApprovalGrant, + ApprovalGrantPage, + ActiveGrantsSummary, + CreateGrantPayload, + ResolutionLog, + GrantScope, +} from '@/types' // Axios 实例 export const http = axios.create({ @@ -737,11 +745,12 @@ export const cronJobApi = { export const wikiApi = { // Knowledge Base listKBs: () => http.get('/wiki/knowledge-bases'), - getKB: (id: number) => http.get(`/wiki/knowledge-bases/${id}`), - listKBsByAgent: (agentId: number) => http.get(`/wiki/knowledge-bases/agent/${agentId}`), - createKB: (data: { name: string; description?: string; agentId?: number }) => + getKB: (id: string | number) => http.get(`/wiki/knowledge-bases/${id}`), + listKBsByAgent: (agentId: string | number) => http.get(`/wiki/knowledge-bases/agent/${agentId}`), + listBindableKBs: () => http.get('/wiki/knowledge-bases/bindable'), + createKB: (data: { name: string; description?: string; agentId?: string | number }) => http.post('/wiki/knowledge-bases', data), - updateKB: (id: number, data: { name?: string; description?: string; agentId?: number; embeddingModelId?: string | number | null }) => + updateKB: (id: string | number, data: { name?: string; description?: string; embeddingModelId?: string | number | null }) => http.put(`/wiki/knowledge-bases/${id}`, data), deleteKB: (id: number) => http.delete(`/wiki/knowledge-bases/${id}`), getConfig: (id: number) => http.get(`/wiki/knowledge-bases/${id}/config`), @@ -749,7 +758,7 @@ export const wikiApi = { http.put(`/wiki/knowledge-bases/${id}/config`, { content }), // Directory Scan - setSourceDirectory: (id: number, path: string) => + setSourceDirectory: (id: string | number, path: string) => http.put(`/wiki/knowledge-bases/${id}/source-directory`, { path }), scanDirectory: (id: number) => http.post(`/wiki/knowledge-bases/${id}/scan`), @@ -778,6 +787,20 @@ export const wikiApi = { // Wiki Pages listPages: (kbId: number, rawId?: number) => http.get(`/wiki/knowledge-bases/${kbId}/pages`, rawId != null ? { params: { rawId } } : undefined), + // Lightweight {slug, title, archived} list for wikilink resolution. Never + // paginated and not scoped by the current raw-material filter — this is the + // authoritative resolution index used by the viewer's wikilink postprocess. + listPageRefs: (kbId: number, includeArchived = false) => + http.get(`/wiki/knowledge-bases/${kbId}/pages/refs`, { params: { includeArchived } }), + + // Broken-link lint (job-based async). POST starts/returns the running job, + // GET reads the most recent completed scan aggregated across the KB. + startBrokenLinksScan: (kbId: number) => + http.post(`/wiki/knowledge-bases/${kbId}/lint/broken-links`), + getBrokenLinksReport: (kbId: number) => + http.get(`/wiki/knowledge-bases/${kbId}/lint/broken-links`), + getBrokenLinksJob: (kbId: number, jobId: string) => + http.get(`/wiki/knowledge-bases/${kbId}/lint/broken-links/jobs/${jobId}`), getPage: (kbId: number, slug: string) => http.get(`/wiki/knowledge-bases/${kbId}/pages/${encodeURIComponent(slug)}`), updatePage: (kbId: number, slug: string, content: string) => @@ -789,6 +812,12 @@ export const wikiApi = { getBacklinks: (kbId: number, slug: string) => http.get(`/wiki/knowledge-bases/${kbId}/pages/${encodeURIComponent(slug)}/backlinks`), + // Cross-KB lookup used by the global wikilink click handler — chat + // messages render [[Title]] without knowing which KB the agent read + // from, so the handler resolves the title across every visible KB. + lookupPage: (params: { title?: string; slug?: string }) => + http.get(`/wiki/pages/lookup`, { params }), + // Archived pages listArchivedPages: (kbId: number) => http.get(`/wiki/knowledge-bases/${kbId}/pages/archived`), @@ -874,6 +903,51 @@ export const wikiApi = { http.post(`/wiki/transformations/runs/${runId}/save-as-page`), cancelTransformationRun: (runId: number) => http.post(`/wiki/transformations/runs/${runId}/cancel`), + + // ---- PageType Profile (REQ-1) ---- + getPageTypeProfile: (kbId: string | number) => + http.get(`/wiki/knowledge-bases/${kbId}/page-type-profile`), + savePageTypeProfile: (kbId: string | number, config: string, name?: string) => + http.put(`/wiki/knowledge-bases/${kbId}/page-type-profile`, { config, name }), + validatePageTypeProfile: (kbId: string | number, config: string) => + http.post(`/wiki/knowledge-bases/${kbId}/page-type-profile/validate`, { config }), + resetPageTypeProfile: (kbId: string | number) => + http.post(`/wiki/knowledge-bases/${kbId}/page-type-profile/reset-default`), + + // ---- Agent pageType permissions (REQ-3) ---- + listPageTypePermissions: (kbId: string | number, agentId: string | number) => + http.get(`/wiki/knowledge-bases/${kbId}/agents/${agentId}/page-type-permissions`), + savePageTypePermission: (kbId: string | number, agentId: string | number, row: { + pageType: string + canRead?: number + canCreate?: number + canUpdate?: number + canDelete?: number + writePolicy?: 'allow' | 'deny' | 'approval_required' + }) => + http.post(`/wiki/knowledge-bases/${kbId}/agents/${agentId}/page-type-permissions`, row), + deletePageTypePermission: (kbId: string | number, agentId: string | number, id: string | number) => + http.delete(`/wiki/knowledge-bases/${kbId}/agents/${agentId}/page-type-permissions/${id}`), + + // ---- Source watcher (REQ-4) ---- + getSourceWatcher: (kbId: string | number) => + http.get(`/wiki/knowledge-bases/${kbId}/source-watcher`), + triggerSourceWatcher: (kbId: string | number) => + http.post(`/wiki/knowledge-bases/${kbId}/source-watcher/scan`), + + // ---- Pipelines (REQ-5) ---- + listPipelines: (kbId: string | number) => + http.get(`/wiki/knowledge-bases/${kbId}/pipelines`), + savePipeline: (kbId: string | number, config: string, format: 'yaml' | 'json' = 'yaml') => + http.post(`/wiki/knowledge-bases/${kbId}/pipelines`, { config, format }), + validatePipeline: (kbId: string | number, config: string, format: 'yaml' | 'json' = 'yaml') => + http.post(`/wiki/knowledge-bases/${kbId}/pipelines/validate`, { config, format }), + deletePipeline: (kbId: string | number, id: string | number) => + http.delete(`/wiki/knowledge-bases/${kbId}/pipelines/${id}`), + listPipelineRuns: (kbId: string | number, id: string | number) => + http.get(`/wiki/knowledge-bases/${kbId}/pipelines/${id}/runs`), + getPipelineRun: (kbId: string | number, runId: string | number) => + http.get(`/wiki/knowledge-bases/${kbId}/pipeline-runs/${runId}`), } // ==================== Workspace (Team) ==================== @@ -1203,12 +1277,21 @@ export const triggerApi = { }) => http.post('/triggers/events', envelope), } -// ==================== Persistent goals (RFC 48) ==================== +// ==================== Persistent goals ==================== // // Snowflake IDs are sent as strings end-to-end — the backend's // ToStringSerializer makes responses strings, and request payloads keep // them as strings to dodge JS Number precision loss. See CLAUDE.md // "ID Handling — Snowflake Precision Convention". + +/** One checkable item of a goal's exit checklist. */ +export interface GoalCriterion { + id: string + text: string + passed: boolean + evidence?: string +} + export interface Goal { id: string conversationId: string @@ -1224,6 +1307,7 @@ export interface Goal { llmCallBudget: number agentLlmCallsUsed: number evalLlmCallsUsed: number + totalLlmCallsUsed?: number progressSummary?: string | null completionScore?: number | null lastEvaluationAt?: string | null @@ -1232,6 +1316,8 @@ export interface Goal { lastFollowupAt?: string | null createTime: string updateTime: string + /** Parsed checklist; the backend always sends an array (empty when none). */ + criteria: GoalCriterion[] } export interface GoalEvent { @@ -1255,6 +1341,7 @@ export const goalApi = { llmCallBudget?: number autoFollowupEnabled?: boolean followupCooldownSeconds?: number + criteria?: { text: string }[] }) => http.post<Goal>('/goals', data), findActive: (conversationId: string) => @@ -1275,3 +1362,47 @@ export const goalApi = { addCriterion: (id: string, criterion: string) => http.post<Goal>(`/goals/${id}/criteria`, { criterion }), } + +// ==================== Approval Auto-Grant ==================== + +/** + * Client for the /api/v1/approval/* surface. The backend serializes all + * snowflake ids as strings (CLAUDE.md precision convention); callers should + * keep them as strings end-to-end and never run them through Number(). + */ +export const approvalApi = { + /** + * List grants visible in the current workspace, paged. mine=true skips the + * admin gate. Page is 1-based; size is bounded server-side to [1, 200]. + */ + listGrants: (params?: { + scopeType?: GrantScope + toolName?: string + revoked?: 0 | 1 + mine?: boolean + page?: number + size?: number + }) => http.get<ApprovalGrantPage>('/approval/grants', { params }), + + /** Active-grant summary used by the global chip + ChatInput pill counters. */ + activeSummary: () => + http.get<ActiveGrantsSummary>('/approval/grants/active'), + + /** Create a grant. Returns the persisted row. */ + createGrant: (payload: CreateGrantPayload) => + http.post<ApprovalGrant>('/approval/grants', payload), + + /** Soft-revoke a grant. Caller must be the grant owner OR a workspace admin. */ + revokeGrant: (id: string) => + http.delete<void>(`/approval/grants/${id}`), + + /** + * Read approval-layer final decisions. {@code grantId} queries require admin; + * {@code conversationId} queries are visible to any workspace member. + */ + listResolutions: (params: { + grantId?: string + conversationId?: string + limit?: number + }) => http.get<ResolutionLog[]>('/approval/resolutions', { params }), +} diff --git a/mateclaw-ui/src/components/chat/ChatInput.vue b/mateclaw-ui/src/components/chat/ChatInput.vue index 38c20d58..4314d60e 100644 --- a/mateclaw-ui/src/components/chat/ChatInput.vue +++ b/mateclaw-ui/src/components/chat/ChatInput.vue @@ -84,6 +84,32 @@ <el-icon><Select /></el-icon> {{ t('chat.approve') }} </button> + <!-- Always-approve dropdown — creates an auto-approve grant of the + selected scope before continuing with the regular /approve. + Workspace-wide grants are intentionally NOT exposed here; they + require the password-protected red button in Security > + 自动批准策略. --> + <div class="approval-bar__always-wrap"> + <button + type="button" + class="approval-bar__btn approval-bar__btn--always" + @click="alwaysApproveOpen = !alwaysApproveOpen" + > + {{ t('chat.approveAlways') }} + <el-icon><ArrowDown /></el-icon> + </button> + <div v-if="alwaysApproveOpen" class="approval-bar__menu"> + <button type="button" class="approval-bar__menu-item" @click="chooseAlwaysApprove('CONVERSATION')"> + {{ t('chat.approveAlwaysConversation') }} + </button> + <button type="button" class="approval-bar__menu-item" @click="chooseAlwaysApprove('AGENT')"> + {{ t('chat.approveAlwaysAgent') }} + </button> + <button type="button" class="approval-bar__menu-item" @click="chooseAlwaysApprove('USER')"> + {{ t('chat.approveAlwaysUser') }} + </button> + </div> + </div> </div> </div> @@ -107,6 +133,13 @@ </div> <div class="input-area"> + <SkillSlashMenu + v-if="slashActive" + ref="slashMenuRef" + :query="slashQuery" + @select="handleSkillSelect" + @close="handleSlashClose" + /> <textarea ref="textareaRef" v-model="inputValue" @@ -115,11 +148,12 @@ :disabled="disabled" :maxlength="maxLength" rows="1" + @keydown="handleSlashKeydown" @keydown.enter.exact.prevent="handleEnter" @compositionstart="isComposing = true" @compositionend="isComposing = false" - @focus="isFocused = true" - @blur="isFocused = false" + @focus="onTextareaFocus" + @blur="onTextareaBlur" @input="autoResize" @paste="handlePaste" ></textarea> @@ -204,9 +238,10 @@ <script setup lang="ts"> import { ref, computed, nextTick, watch } from 'vue' import { useI18n } from 'vue-i18n' -import { CloseBold, MagicStick, Microphone, Paperclip, Promotion, Select, Timer, WarningFilled } from '@element-plus/icons-vue' +import { ArrowDown, CloseBold, MagicStick, Microphone, Paperclip, Promotion, Select, Timer, WarningFilled } from '@element-plus/icons-vue' import { useToolLabel } from '@/composables/useToolLabel' -import type { ChatAttachment, PendingApprovalMeta, StreamPhase, QueuedMessage } from '@/types' +import SkillSlashMenu from '@/components/chat/SkillSlashMenu.vue' +import type { ChatAttachment, PendingApprovalMeta, StreamPhase, QueuedMessage, Skill } from '@/types' interface Props { /** 输入值 */ @@ -246,6 +281,12 @@ interface Props { * 不响应点击，tooltip 提示当前模型不支持深度思考。默认 true 以保持向后兼容。 */ thinkingSupported?: boolean + /** + * Whether the current agent can use skills. When false the skill slash menu + * is suppressed — a skills-disabled agent has no `load_skill` tool, so naming + * a skill would be a dead end. + */ + skillsEnabled?: boolean } const props = withDefaults(defineProps<Props>(), { @@ -265,6 +306,7 @@ const props = withDefaults(defineProps<Props>(), { enableTalkMode: false, thinkingEnabled: false, thinkingSupported: true, + skillsEnabled: true, }) const emit = defineEmits<{ @@ -276,6 +318,14 @@ const emit = defineEmits<{ 'attachment-remove': [storedName: string] approve: [pendingId: string] deny: [pendingId: string] + /** + * Always-approve dropdown: ChatConsole creates an auto-approve grant for the + * matching scope, then forwards the regular /approve command. The scope + * vocabulary mirrors mate_approval_grant.scope_type minus WORKSPACE (the + * banner deliberately excludes the workspace-wide path; that lives in + * Security > 自动批准策略 with password confirmation). + */ + 'approve-always': [payload: { pendingId: string; scope: 'CONVERSATION' | 'AGENT' | 'USER' }] talk: [] 'toggle-thinking': [] }>() @@ -290,6 +340,111 @@ const fileInputRef = ref<HTMLInputElement | null>(null) const isFocused = ref(false) const isComposing = ref(false) +// ---- Skill slash-command menu ---- +// The menu opens when the whole input is a single "/<query>" token (no spaces +// yet). Picking a skill rewrites the input to a directive that names the skill, +// which the agent recognises and loads via `load_skill`. +const slashMenuRef = ref<InstanceType<typeof SkillSlashMenu> | null>(null) +const slashDismissed = ref(false) +const slashMatch = computed(() => { + const m = /^\/([^\s/]*)$/.exec(props.modelValue) + return m ? m[1] : null +}) +const slashQuery = computed(() => slashMatch.value ?? '') +const slashActive = computed( + () => + slashMatch.value !== null && + !slashDismissed.value && + !props.disabled && + !props.pendingApproval && + props.skillsEnabled, +) +// Leaving slash mode (cleared the "/" token) re-arms the menu for next time. +watch(slashMatch, (val) => { + if (val === null) slashDismissed.value = false +}) + +function handleSlashKeydown(e: KeyboardEvent) { + if (!slashActive.value) return + const menu = slashMenuRef.value + if (!menu) return + switch (e.key) { + case 'ArrowDown': + e.preventDefault() + menu.next() + break + case 'ArrowUp': + e.preventDefault() + menu.prev() + break + case 'Enter': + if (!isComposing.value && menu.count() > 0) { + e.preventDefault() + menu.confirm() + } + break + case 'Tab': + if (menu.count() > 0) { + e.preventDefault() + menu.confirm() + } + break + case 'Escape': + e.preventDefault() + slashDismissed.value = true + break + } +} + +function handleSkillSelect(skill: Skill) { + inputValue.value = t('chat.useSkillDirective', { name: skill.name }) + slashDismissed.value = false + nextTick(() => { + const el = textareaRef.value + if (el) { + el.focus() + const end = el.value.length + el.setSelectionRange(end, end) + } + autoResize() + }) +} + +// On open, the menu autofocuses its search box, which blurs the textarea. That +// is expected focus movement — keep the menu open. Only dismiss when focus +// actually leaves the input+menu (clicked elsewhere). The relatedTarget check +// covers direct focus moves; the deferred activeElement check covers browsers +// that report a null relatedTarget for programmatic focus. +function onTextareaBlur(e: FocusEvent) { + isFocused.value = false + const next = e.relatedTarget as HTMLElement | null + if (next && next.closest && next.closest('.skill-slash-menu')) return + setTimeout(() => { + const ae = document.activeElement as HTMLElement | null + if (ae && ae.closest && ae.closest('.skill-slash-menu')) return + slashDismissed.value = true + }, 0) +} + +function onTextareaFocus() { + isFocused.value = true +} + +// The menu asked to close (Escape, or focus left the menu). Suppress it until +// the "/" token is cleared and retyped. +function handleSlashClose() { + slashDismissed.value = true +} + +// Always-approve dropdown — collapsed by default; opens on the chevron click, +// closes on outside click or after the user picks a scope. +const alwaysApproveOpen = ref(false) +function chooseAlwaysApprove(scope: 'CONVERSATION' | 'AGENT' | 'USER') { + if (!props.pendingApproval) return + emit('approve-always', { pendingId: props.pendingApproval.pendingId, scope }) + alwaysApproveOpen.value = false +} + // 输入值处理 const inputValue = computed({ get: () => props.modelValue, @@ -351,6 +506,9 @@ const sendBtnClass = computed(() => ({ // 处理回车键 const handleEnter = () => { if (isComposing.value) return + // When the slash menu is showing matches, Enter confirms the highlighted + // skill (handled in handleSlashKeydown) instead of submitting the message. + if (slashActive.value && (slashMenuRef.value?.count() ?? 0) > 0) return handleSubmit() } @@ -527,6 +685,7 @@ defineExpose({ /* 输入区域 */ .input-area { + position: relative; display: flex; gap: 10px; align-items: flex-end; @@ -757,6 +916,47 @@ defineExpose({ background: var(--mc-primary-hover, #C1572B); } +/* Always-approve dropdown: orange-red border to signal it's a security-reducing + action vs the regular approve button (solid primary). The dropdown menu is + absolutely positioned above the banner so it never gets clipped. */ +.approval-bar__always-wrap { + position: relative; +} +.approval-bar__btn--always { + background: transparent; + color: #b91c1c; + border: 1px solid #ef4444; +} +.approval-bar__btn--always:hover { + background: #fef2f2; +} +.approval-bar__menu { + position: absolute; + bottom: calc(100% + 6px); + right: 0; + min-width: 160px; + background: var(--mc-surface-primary, #fff); + border: 1px solid var(--mc-border-light, #e5e7eb); + border-radius: 6px; + box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1); + z-index: 20; + overflow: hidden; +} +.approval-bar__menu-item { + display: block; + width: 100%; + padding: 8px 12px; + background: none; + border: none; + text-align: left; + font-size: 13px; + color: var(--mc-text-primary, #0f172a); + cursor: pointer; +} +.approval-bar__menu-item:hover { + background: var(--mc-surface-tertiary, #f1f5f9); +} + .approval-bar__btn--deny { background: var(--mc-bg-sunken, #f1f5f9); color: var(--mc-text-secondary, #64748b); diff --git a/mateclaw-ui/src/components/chat/ExecutionDetailDialog.vue b/mateclaw-ui/src/components/chat/ExecutionDetailDialog.vue new file mode 100644 index 00000000..02cfb7d3 --- /dev/null +++ b/mateclaw-ui/src/components/chat/ExecutionDetailDialog.vue @@ -0,0 +1,251 @@ +<script setup lang="ts"> +import { computed } from 'vue' +import { ElMessage } from 'element-plus' +import { useI18n } from 'vue-i18n' +import JsonView from './JsonView.vue' + +/** + * Full-detail viewer for an execution step or a tool call. + * Shows the complete request payload and response output without truncation, + * so users can audit exactly what an agent ran and what came back. + */ +const props = defineProps<{ + modelValue: boolean + title: string + status?: 'running' | 'completed' | 'error' | 'pending' + /** Raw request payload (typically JSON arguments). Optional — plan steps have none. */ + request?: string + /** Raw response / output text. */ + response?: string +}>() + +const emit = defineEmits<{ + (e: 'update:modelValue', v: boolean): void +}>() + +const { t } = useI18n() + +const visible = computed({ + get: () => props.modelValue, + set: (v: boolean) => emit('update:modelValue', v), +}) + +const hasRequest = computed(() => !!(props.request || '').trim()) +const hasResponse = computed(() => !!(props.response || '').trim()) + +const statusLabel = computed(() => t(`chat.detail.status.${props.status || 'pending'}`)) + +async function copy(text?: string) { + if (!text) return + try { + await navigator.clipboard.writeText(text) + ElMessage.success(t('chat.detail.copied')) + } catch { + ElMessage.error(t('chat.detail.copyFailed')) + } +} +</script> + +<template> + <el-dialog + v-model="visible" + width="700px" + append-to-body + align-center + :show-close="false" + class="exec-detail-dialog" + modal-class="exec-detail-overlay" + > + <template #header> + <div class="exec-detail__head"> + <span class="exec-detail__dot" :class="`is-${status || 'pending'}`" /> + <span class="exec-detail__title">{{ title }}</span> + <span v-if="status" class="exec-detail__badge" :class="`is-${status}`">{{ statusLabel }}</span> + <button class="exec-detail__close" :aria-label="$t('common.close')" @click="visible = false"> + <svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M6 6l12 12M18 6L6 18" /></svg> + </button> + </div> + </template> + + <div class="exec-detail__body"> + <section v-if="hasRequest" class="exec-detail__section"> + <div class="exec-detail__label"> + <span>{{ $t('chat.detail.request') }}</span> + <button class="exec-detail__copy" :title="$t('chat.detail.copy')" @click="copy(request)"> + <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="11" height="11" rx="2" /><path d="M5 15V5a2 2 0 0 1 2-2h10" /></svg> + </button> + </div> + <JsonView :raw="request" /> + </section> + + <section class="exec-detail__section"> + <div class="exec-detail__label"> + <span>{{ $t('chat.detail.response') }}</span> + <button v-if="hasResponse" class="exec-detail__copy" :title="$t('chat.detail.copy')" @click="copy(response)"> + <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="11" height="11" rx="2" /><path d="M5 15V5a2 2 0 0 1 2-2h10" /></svg> + </button> + </div> + <JsonView v-if="hasResponse" :raw="response" /> + <div v-else class="exec-detail__empty">{{ $t('chat.detail.empty') }}</div> + </section> + </div> + </el-dialog> +</template> + +<style scoped> +.exec-detail__head { + display: flex; + align-items: center; + gap: 10px; + min-width: 0; +} +.exec-detail__dot { + width: 8px; + height: 8px; + border-radius: 50%; + flex-shrink: 0; + background: var(--mc-text-quaternary, #c0bfbc); +} +.exec-detail__dot.is-completed { background: var(--mc-success, #67c23a); } +.exec-detail__dot.is-error { background: var(--mc-danger, #f56c6c); } +.exec-detail__dot.is-running { background: var(--mc-primary, #d96d46); } + +.exec-detail__title { + font-weight: 600; + font-size: 15px; + color: var(--mc-text-primary); + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +.exec-detail__badge { + flex-shrink: 0; + font-size: 11px; + line-height: 18px; + padding: 0 8px; + border-radius: 9px; + font-weight: 500; + color: var(--mc-text-tertiary); + background: var(--mc-bg-muted, #f1ece8); +} +.exec-detail__badge.is-completed { + color: var(--mc-success, #4f9a3f); + background: rgba(103, 194, 58, 0.12); +} +.exec-detail__badge.is-error { + color: var(--mc-danger, #d9533f); + background: rgba(245, 108, 108, 0.12); +} +.exec-detail__badge.is-running { + color: var(--mc-primary, #d96d46); + background: var(--mc-primary-bg, rgba(217, 109, 70, 0.1)); +} + +.exec-detail__close { + margin-left: auto; + flex-shrink: 0; + display: inline-flex; + align-items: center; + justify-content: center; + width: 26px; + height: 26px; + padding: 0; + border: none; + border-radius: 6px; + background: transparent; + color: var(--mc-text-tertiary); + cursor: pointer; + transition: background 0.15s, color 0.15s; +} +.exec-detail__close:hover { + background: var(--mc-bg-muted, #f1ece8); + color: var(--mc-text-primary); +} + +.exec-detail__body { + display: flex; + flex-direction: column; + gap: 18px; +} +.exec-detail__section { + display: flex; + flex-direction: column; + gap: 8px; +} +.exec-detail__label { + display: flex; + align-items: center; + gap: 8px; + font-size: 12px; + font-weight: 600; + letter-spacing: 0.02em; + text-transform: uppercase; + color: var(--mc-text-tertiary); +} +.exec-detail__copy { + display: inline-flex; + align-items: center; + justify-content: center; + width: 22px; + height: 22px; + padding: 0; + border: none; + border-radius: 5px; + background: transparent; + color: var(--mc-text-tertiary); + cursor: pointer; + transition: background 0.15s, color 0.15s; +} +.exec-detail__copy:hover { + background: var(--mc-bg-muted, #f1ece8); + color: var(--mc-primary); +} +.exec-detail__empty { + padding: 16px; + font-size: 13px; + color: var(--mc-text-tertiary); + text-align: center; + background: rgba(255, 255, 255, 0.3); + border: 1px dashed var(--mc-border-light); + border-radius: 10px; +} +</style> + +<!-- Frosted-glass dialog shell. Non-scoped because el-dialog teleports to body, + out of this component's scoped style reach. --> +<style> +.exec-detail-overlay { + background: rgba(28, 20, 16, 0.28) !important; + backdrop-filter: blur(3px); + -webkit-backdrop-filter: blur(3px); +} +.exec-detail-dialog.el-dialog { + background: rgba(255, 255, 255, 0.62); + backdrop-filter: blur(24px) saturate(180%); + -webkit-backdrop-filter: blur(24px) saturate(180%); + border: 1px solid rgba(255, 255, 255, 0.55); + border-radius: 18px; + box-shadow: 0 16px 56px rgba(28, 20, 16, 0.22); + overflow: hidden; +} +.exec-detail-dialog .el-dialog__header { + margin: 0; + padding: 16px 18px 12px; + border-bottom: 1px solid rgba(255, 255, 255, 0.4); +} +.exec-detail-dialog .el-dialog__body { + padding: 14px 18px 20px; +} + +html.dark .exec-detail-overlay { + background: rgba(0, 0, 0, 0.42) !important; +} +html.dark .exec-detail-dialog.el-dialog { + background: rgba(34, 27, 23, 0.6); + border-color: rgba(255, 255, 255, 0.08); + box-shadow: 0 16px 56px rgba(0, 0, 0, 0.55); +} +html.dark .exec-detail-dialog .el-dialog__header { + border-bottom-color: rgba(255, 255, 255, 0.08); +} +</style> diff --git a/mateclaw-ui/src/components/chat/JsonView.vue b/mateclaw-ui/src/components/chat/JsonView.vue new file mode 100644 index 00000000..de1e905c --- /dev/null +++ b/mateclaw-ui/src/components/chat/JsonView.vue @@ -0,0 +1,95 @@ +<script setup lang="ts"> +import { computed } from 'vue' + +/** + * Lightweight, dependency-free JSON viewer with syntax highlighting. + * Parses the raw string as JSON and pretty-prints it with token colors; + * when the input is not valid JSON (e.g. plain terminal output), it falls + * back to rendering the raw text verbatim without highlighting. + */ +const props = defineProps<{ + raw?: string +}>() + +function escapeHtml(s: string): string { + return s + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') +} + +/** Wrap JSON tokens (keys, strings, numbers, booleans, null) in colored spans. */ +function highlight(jsonStr: string): string { + return escapeHtml(jsonStr).replace( + /("(\\u[a-zA-Z0-9]{4}|\\[^u]|[^\\"])*"(\s*:)?|\b(true|false)\b|\bnull\b|-?\d+(?:\.\d*)?(?:[eE][+-]?\d+)?)/g, + (match) => { + let cls = 'jv-number' + if (/^"/.test(match)) { + cls = /:$/.test(match) ? 'jv-key' : 'jv-string' + } else if (/true|false/.test(match)) { + cls = 'jv-boolean' + } else if (/null/.test(match)) { + cls = 'jv-null' + } + return `<span class="${cls}">${match}</span>` + }, + ) +} + +const parsed = computed(() => { + const s = (props.raw || '').trim() + if (!s) return { empty: true, isJson: false, html: '' } + try { + const pretty = JSON.stringify(JSON.parse(s), null, 2) + return { empty: false, isJson: true, html: highlight(pretty) } + } catch { + return { empty: false, isJson: false, html: escapeHtml(props.raw || '') } + } +}) +</script> + +<template> + <pre class="json-view" :class="{ 'is-plain': !parsed.isJson }"><code v-html="parsed.html" /></pre> +</template> + +<style scoped> +.json-view { + margin: 0; + padding: 12px 14px; + /* Translucent surface so the dialog's frosted-glass blur shows through */ + background: rgba(255, 255, 255, 0.42); + border: 1px solid var(--mc-border-light); + border-radius: 10px; + font-family: var(--mc-font-mono, 'SF Mono', 'Menlo', 'Consolas', monospace); + font-size: 12.5px; + line-height: 1.65; + color: var(--mc-code-text, #1c1410); + max-height: 420px; + overflow: auto; + white-space: pre-wrap; + word-break: break-word; + tab-size: 2; +} +.json-view code { + font-family: inherit; +} +</style> + +<!-- Token palette lives in a non-scoped block: the colored spans are produced + via v-html, so they carry no scoped data-attribute. --> +<style> +.json-view .jv-key { color: #e45649; } +.json-view .jv-string { color: #50a14f; } +.json-view .jv-number { color: #c18401; } +.json-view .jv-boolean { color: #a626a4; } +.json-view .jv-null { color: #a626a4; } + +html.dark .json-view { + background: rgba(255, 255, 255, 0.05); +} +html.dark .json-view .jv-key { color: #e06c75; } +html.dark .json-view .jv-string { color: #98c379; } +html.dark .json-view .jv-number { color: #d19a66; } +html.dark .json-view .jv-boolean { color: #c678dd; } +html.dark .json-view .jv-null { color: #c678dd; } +</style> diff --git a/mateclaw-ui/src/components/chat/PlanStepsPanel.vue b/mateclaw-ui/src/components/chat/PlanStepsPanel.vue index 38313ec9..38bd1934 100644 --- a/mateclaw-ui/src/components/chat/PlanStepsPanel.vue +++ b/mateclaw-ui/src/components/chat/PlanStepsPanel.vue @@ -1,7 +1,8 @@ <script setup lang="ts"> import { ref, reactive, computed } from 'vue' -import { Loading, Select, ArrowDown } from '@element-plus/icons-vue' +import { Loading, Select, ArrowDown, View } from '@element-plus/icons-vue' import type { PlanMeta } from '@/types' +import ExecutionDetailDialog from './ExecutionDetailDialog.vue' const props = defineProps<{ plan: PlanMeta @@ -45,6 +46,27 @@ function truncateResult(text: string, max: number): string { if (!text || text.length <= max) return text return text.slice(0, max) + '...' } + +// Full step-result viewer — the inline preview is capped at 500 chars; this opens +// the complete result so plan execution stays fully auditable. +const detailVisible = ref(false) +const detailIndex = ref(-1) +const detailResponse = computed(() => props.plan.stepResults?.[detailIndex.value]?.result || '') +const detailTitle = computed(() => { + const i = detailIndex.value + return i >= 0 ? `${i + 1}. ${props.plan.steps[i] || ''}` : '' +}) +const detailStatus = computed<'completed' | 'error' | 'running'>(() => { + const st = props.plan.stepResults?.[detailIndex.value]?.status + if (st === 'failed' || st === 'error') return 'error' + if (st === 'completed') return 'completed' + return 'running' +}) + +function openDetail(index: number) { + detailIndex.value = index + detailVisible.value = true +} </script> <template> @@ -55,10 +77,8 @@ function truncateResult(text: string, max: number): string { <el-icon v-if="isGenerating && !allDone" class="is-loading" :size="14"><Loading /></el-icon> <el-icon v-else :size="14"><Select /></el-icon> </span> - <span class="plan-panel__title"> - Plan - </span> - <span class="plan-panel__progress">{{ completedCount }}/{{ plan.steps.length }}</span> + <span class="plan-panel__title">{{ $t('chat.executionPlan') }}</span> + <span class="plan-panel__progress">({{ completedCount }}/{{ plan.steps.length }} {{ $t('chat.planDone') }})</span> <el-icon class="plan-panel__arrow" :class="{ 'is-open': !collapsed }" @@ -88,6 +108,13 @@ function truncateResult(text: string, max: number): string { </span> <span class="plan-step__index">{{ i + 1 }}.</span> <span class="plan-step__text">{{ step }}</span> + <el-icon + v-if="plan.stepResults?.[i]?.result" + class="plan-step__detail" + :title="$t('chat.detail.viewDetail')" + :size="12" + @click.stop="openDetail(i)" + ><View /></el-icon> <el-icon v-if="plan.stepResults?.[i]?.result" class="plan-step__arrow" @@ -96,7 +123,7 @@ function truncateResult(text: string, max: number): string { ><ArrowDown /></el-icon> </div> - <!-- 步骤结果（可展开） --> + <!-- 步骤结果（可展开预览，完整内容见详情弹层） --> <Transition name="plan-slide"> <div v-if="expandedSteps.has(i) && plan.stepResults?.[i]?.result" class="plan-step__result"> <pre>{{ truncateResult(plan.stepResults[i].result, 500) }}</pre> @@ -105,6 +132,13 @@ function truncateResult(text: string, max: number): string { </div> </div> </Transition> + + <ExecutionDetailDialog + v-model="detailVisible" + :title="detailTitle" + :status="detailStatus" + :response="detailResponse" + /> </div> </template> @@ -226,11 +260,21 @@ function truncateResult(text: string, max: number): string { color: var(--mc-text-tertiary); } +.plan-step__detail { + flex-shrink: 0; + margin-left: auto; + color: var(--mc-text-quaternary); + cursor: pointer; + transition: color 0.15s; +} +.plan-step__detail:hover { + color: var(--mc-primary); +} + .plan-step__arrow { flex-shrink: 0; color: var(--mc-text-quaternary); transition: transform 0.2s; - margin-left: auto; } .plan-step__arrow.is-open { transform: rotate(180deg); diff --git a/mateclaw-ui/src/components/chat/SkillSlashMenu.vue b/mateclaw-ui/src/components/chat/SkillSlashMenu.vue new file mode 100644 index 00000000..25a7d82b --- /dev/null +++ b/mateclaw-ui/src/components/chat/SkillSlashMenu.vue @@ -0,0 +1,342 @@ +<template> + <div class="skill-slash-menu" role="listbox" :aria-label="t('chat.slashMenuTitle')"> + <div class="slash-menu__header"> + <span class="slash-menu__title">{{ t('chat.slashMenuTitle') }}</span> + <span class="slash-menu__hint">{{ t('chat.slashMenuHint') }}</span> + </div> + + <div class="slash-menu__search"> + <el-icon class="slash-menu__search-icon"><Search /></el-icon> + <input + ref="searchRef" + v-model="keyword" + class="slash-menu__search-input" + type="text" + autocomplete="off" + spellcheck="false" + :placeholder="t('chat.slashMenuSearchPlaceholder')" + @keydown="onSearchKeydown" + @blur="onSearchBlur" + /> + </div> + + <div v-if="loading" class="slash-menu__state">{{ t('chat.slashMenuLoading') }}</div> + <div v-else-if="filtered.length === 0" class="slash-menu__state">{{ t('chat.slashMenuEmpty') }}</div> + + <ul v-else class="slash-menu__list"> + <li + v-for="(skill, idx) in filtered" + :key="String(skill.id)" + class="slash-menu__item" + :class="{ active: idx === activeIndex }" + role="option" + :aria-selected="idx === activeIndex" + @mouseenter="activeIndex = idx" + @mousedown.prevent="choose(skill)" + > + <span class="slash-menu__icon"><SkillIcon :value="skill.icon" :size="18" :fallback="'🧩'" /></span> + <span class="slash-menu__body"> + <span class="slash-menu__name"> + {{ displayName(skill) }} + <code class="slash-menu__slug">{{ skill.name }}</code> + </span> + <span v-if="skill.description" class="slash-menu__desc">{{ skill.description }}</span> + </span> + </li> + </ul> + </div> +</template> + +<script setup lang="ts"> +import { ref, computed, watch, onMounted, nextTick } from 'vue' +import { useI18n } from 'vue-i18n' +import { Search } from '@element-plus/icons-vue' +import { skillApi } from '@/api/index' +import SkillIcon from '@/components/common/SkillIcon.vue' +import type { Skill } from '@/types/index' + +// Short-lived, workspace-keyed cache. The menu remounts every time the user +// re-types "/", so without this each keystroke that re-opens it would re-hit +// the endpoint. Keyed by workspace because the listing is workspace-scoped. +const CACHE_TTL_MS = 30_000 +let enabledCache: { key: string; ts: number; data: Skill[] } | null = null + +async function loadEnabledSkills(): Promise<Skill[]> { + const key = localStorage.getItem('mc-workspace-id') || 'default' + const now = Date.now() + if (enabledCache && enabledCache.key === key && now - enabledCache.ts < CACHE_TTL_MS) { + return enabledCache.data + } + const res: any = await skillApi.listEnabled() + const data = (res?.data ?? []) as Skill[] + enabledCache = { key, ts: now, data } + return data +} + +const props = defineProps<{ + /** Initial query, seeded from the text typed after the leading "/". */ + query: string +}>() + +const emit = defineEmits<{ + /** A skill was picked (click or Enter). */ + select: [skill: Skill] + /** The menu requested to close (Escape, or focus left the menu). */ + close: [] +}>() + +const { t, locale } = useI18n() + +const MAX_RESULTS = 8 + +const allSkills = ref<Skill[]>([]) +const loading = ref(true) +const activeIndex = ref(0) + +// The in-menu search box owns the filter. Seeded once from the slash query so +// "/da" carries the "da" into the box; afterwards it is edited independently +// (it tolerates spaces, which the slash trigger does not). +const searchRef = ref<HTMLInputElement | null>(null) +const keyword = ref(props.query) + +const q = computed(() => keyword.value.trim().toLowerCase()) + +const filtered = computed<Skill[]>(() => { + const query = q.value + const list = allSkills.value + const matched = query + ? list.filter((s) => + [s.name, s.nameZh, s.nameEn, s.description].some( + (f) => f && f.toLowerCase().includes(query), + ), + ) + : list + return matched.slice(0, MAX_RESULTS) +}) + +// Keep the highlighted row in range as the query narrows the result set. +watch(filtered, () => { + if (activeIndex.value >= filtered.value.length) activeIndex.value = 0 +}) + +function displayName(s: Skill): string { + const zh = locale.value.startsWith('zh') + return (zh ? s.nameZh : s.nameEn) || s.name +} + +function choose(skill: Skill) { + emit('select', skill) +} + +// ---- Keyboard API consumed by the parent textarea handler ---- +function next() { + if (filtered.value.length) activeIndex.value = (activeIndex.value + 1) % filtered.value.length +} +function prev() { + if (filtered.value.length) + activeIndex.value = (activeIndex.value - 1 + filtered.value.length) % filtered.value.length +} +function confirm() { + const skill = filtered.value[activeIndex.value] + if (skill) emit('select', skill) +} +function count() { + return filtered.value.length +} +defineExpose({ next, prev, confirm, count }) + +// ---- Search box: owns focus and keyboard while the menu is open ---- +function onSearchKeydown(e: KeyboardEvent) { + switch (e.key) { + case 'ArrowDown': + e.preventDefault() + next() + break + case 'ArrowUp': + e.preventDefault() + prev() + break + case 'Enter': + if (filtered.value.length) { + e.preventDefault() + confirm() + } + break + case 'Tab': + if (filtered.value.length) { + e.preventDefault() + confirm() + } + break + case 'Escape': + e.preventDefault() + emit('close') + break + } +} + +// Close when focus leaves the menu entirely. Item clicks use +// `@mousedown.prevent`, so picking a skill never blurs the search box. +function onSearchBlur(e: FocusEvent) { + const next = e.relatedTarget as HTMLElement | null + if (next && next.closest && next.closest('.skill-slash-menu')) return + emit('close') +} + +onMounted(async () => { + try { + allSkills.value = await loadEnabledSkills() + } catch { + allSkills.value = [] + } finally { + loading.value = false + } + // Move focus into the search box so typing filters immediately. The parent + // textarea's blur handler detects the focus landing inside the menu and + // keeps the menu open. + await nextTick() + const el = searchRef.value + if (el) { + el.focus() + const end = el.value.length + el.setSelectionRange(end, end) + } +}) +</script> + +<style scoped> +.skill-slash-menu { + position: absolute; + bottom: calc(100% + 8px); + left: 0; + right: 0; + z-index: 30; + background: var(--mc-input-bg, #ffffff); + border-radius: 14px; + box-shadow: 0 8px 28px rgba(0, 0, 0, 0.14), 0 0 0 1px rgba(0, 0, 0, 0.06); + overflow: hidden; + max-height: 320px; + display: flex; + flex-direction: column; +} + +.slash-menu__header { + display: flex; + align-items: center; + justify-content: space-between; + padding: 8px 12px; + font-size: 12px; + color: var(--el-text-color-secondary, #909399); + border-bottom: 1px solid rgba(0, 0, 0, 0.05); +} + +.slash-menu__title { + font-weight: 600; +} + +.slash-menu__hint { + font-size: 11px; + opacity: 0.8; +} + +.slash-menu__search { + display: flex; + align-items: center; + gap: 8px; + margin: 8px; + padding: 6px 10px; + border-radius: 10px; + background: rgba(0, 0, 0, 0.04); + border: 1px solid transparent; +} + +.slash-menu__search:focus-within { + border-color: rgba(217, 119, 87, 0.5); + background: var(--mc-input-bg, #ffffff); +} + +.slash-menu__search-icon { + flex-shrink: 0; + font-size: 14px; + color: var(--el-text-color-secondary, #909399); +} + +.slash-menu__search-input { + flex: 1; + min-width: 0; + border: none; + outline: none; + background: transparent; + font-size: 13px; + color: var(--el-text-color-primary, #303133); +} + +.slash-menu__search-input::placeholder { + color: var(--el-text-color-secondary, #909399); +} + +.slash-menu__state { + padding: 16px 12px; + font-size: 13px; + color: var(--el-text-color-secondary, #909399); + text-align: center; +} + +.slash-menu__list { + list-style: none; + margin: 0; + padding: 4px; + overflow-y: auto; +} + +.slash-menu__item { + display: flex; + align-items: flex-start; + gap: 10px; + padding: 8px 10px; + border-radius: 10px; + cursor: pointer; +} + +.slash-menu__item.active { + background: rgba(217, 119, 87, 0.12); +} + +.slash-menu__icon { + flex-shrink: 0; + margin-top: 1px; +} + +.slash-menu__body { + display: flex; + flex-direction: column; + min-width: 0; +} + +.slash-menu__name { + display: flex; + align-items: center; + gap: 8px; + font-size: 13px; + font-weight: 600; + color: var(--el-text-color-primary, #303133); +} + +.slash-menu__slug { + font-size: 11px; + font-weight: 400; + color: var(--el-text-color-secondary, #909399); + background: rgba(0, 0, 0, 0.05); + padding: 1px 5px; + border-radius: 5px; +} + +.slash-menu__desc { + font-size: 12px; + color: var(--el-text-color-secondary, #909399); + white-space: nowrap; + overflow: hidden; + text-overflow: ellipsis; + max-width: 100%; +} +</style> diff --git a/mateclaw-ui/src/components/chat/ToolCallSegment.vue b/mateclaw-ui/src/components/chat/ToolCallSegment.vue index c0d17776..ad6fb4ff 100644 --- a/mateclaw-ui/src/components/chat/ToolCallSegment.vue +++ b/mateclaw-ui/src/components/chat/ToolCallSegment.vue @@ -1,9 +1,10 @@ <script setup lang="ts"> import { ref, computed, watch } from 'vue' -import { Loading, Select, CloseBold, ArrowDown, Document, Setting, Connection, WarningFilled, Clock } from '@element-plus/icons-vue' +import { Loading, Select, CloseBold, ArrowDown, Document, Setting, Connection, WarningFilled, Clock, View } from '@element-plus/icons-vue' import { useToolLabel } from '@/composables/useToolLabel' import type { MessageSegment } from '@/types' import DelegationNodeView from './DelegationNodeView.vue' +import ExecutionDetailDialog from './ExecutionDetailDialog.vue' const props = defineProps<{ segment: MessageSegment @@ -97,6 +98,19 @@ const childProgress = computed(() => { const n = childTools.value.length return n ? `${n} ${n === 1 ? 'tool' : 'tools'}` : '' }) + +// Full request/response detail viewer. Available for regular tool calls (not +// delegation timelines) that carry arguments or a result — lets users audit the +// complete payload that the inline card truncates. +const detailVisible = ref(false) +const canViewDetail = computed(() => + !isDelegation.value && (!!props.segment.toolArgs || !!props.segment.toolResult) +) +const detailStatus = computed<'running' | 'completed' | 'error'>(() => { + if (isError.value) return 'error' + if (isRunning.value) return 'running' + return 'completed' +}) </script> <template> @@ -117,12 +131,21 @@ const childProgress = computed(() => { <span v-if="isDelegation && childProgress" class="seg-tool__badge">{{ childProgress }}</span> <el-icon v-if="isStalled" class="seg-tool__stale" :title="$t('chat.subagentStalled')" :size="12"><WarningFilled /></el-icon> <span v-if="truncatedArgs" class="seg-tool__args">{{ truncatedArgs }}</span> - <el-icon - v-if="hasBody" - class="seg-tool__arrow" - :class="{ 'is-open': expanded }" - :size="11" - ><ArrowDown /></el-icon> + <span class="seg-tool__actions"> + <el-icon + v-if="canViewDetail" + class="seg-tool__detail" + :title="$t('chat.detail.viewDetail')" + :size="13" + @click.stop="detailVisible = true" + ><View /></el-icon> + <el-icon + v-if="hasBody" + class="seg-tool__arrow" + :class="{ 'is-open': expanded }" + :size="11" + ><ArrowDown /></el-icon> + </span> </div> <Transition name="seg-slide"> <div v-if="expanded && hasBody" class="seg-tool__body"> @@ -164,6 +187,15 @@ const childProgress = computed(() => { <pre v-if="segment.toolResult">{{ resultPreview }}</pre> </div> </Transition> + + <ExecutionDetailDialog + v-if="canViewDetail" + v-model="detailVisible" + :title="displayName" + :status="detailStatus" + :request="segment.toolArgs" + :response="segment.toolResult" + /> </div> </template> @@ -245,11 +277,30 @@ const childProgress = computed(() => { border-radius: 3px; } +/* Trailing controls pinned to the right edge as a single group, so the + detail icon and chevron stay together regardless of whether args render. */ +.seg-tool__actions { + flex-shrink: 0; + margin-left: auto; + display: flex; + align-items: center; + gap: 6px; +} + +.seg-tool__detail { + flex-shrink: 0; + color: var(--mc-text-tertiary); + cursor: pointer; + transition: color 0.15s; +} +.seg-tool__detail:hover { + color: var(--mc-primary); +} + .seg-tool__arrow { flex-shrink: 0; color: var(--mc-text-tertiary); transition: transform 0.2s; - margin-left: auto; } .seg-tool__arrow.is-open { transform: rotate(180deg); diff --git a/mateclaw-ui/src/components/goal/GoalAvatarRing.vue b/mateclaw-ui/src/components/goal/GoalAvatarRing.vue index 23dabe3d..1a97dc21 100644 --- a/mateclaw-ui/src/components/goal/GoalAvatarRing.vue +++ b/mateclaw-ui/src/components/goal/GoalAvatarRing.vue @@ -69,6 +69,14 @@ const tooltip = computed(() => { } return parts.join(' · ') }) + +// Checklist for the richer hover card. Empty until a checklist exists. +const criteria = computed(() => goal.value?.criteria ?? []) +const progressLabel = computed(() => { + if (!props.conversationId) return '' + const p = goalStore.criteriaProgress(props.conversationId) + return p ? `${p.passed}/${p.total}` : '' +}) </script> <template> @@ -107,7 +115,20 @@ const tooltip = computed(() => { /> </svg> <span v-if="showFollowupMark" class="followup-mark" :title="$t('goal.autoFollowup')">↻</span> - <span v-if="goal && tooltip" class="goal-tip">{{ tooltip }}</span> + <!-- Checklist card when the goal has criteria; plain one-liner otherwise. --> + <div v-if="goal && criteria.length" class="goal-card"> + <div class="goal-card-head"> + <span class="goal-card-title">{{ goal.title }}</span> + <span v-if="progressLabel" class="goal-card-count">{{ progressLabel }}</span> + </div> + <ul class="goal-card-list"> + <li v-for="c in criteria" :key="c.id" :class="{ done: c.passed }"> + <span class="goal-card-mark">{{ c.passed ? '✓' : '○' }}</span> + <span class="goal-card-text">{{ c.text }}</span> + </li> + </ul> + </div> + <span v-else-if="goal && tooltip" class="goal-tip">{{ tooltip }}</span> </div> </template> @@ -246,4 +267,78 @@ const tooltip = computed(() => { opacity: 1; transform: translateY(-50%) translateX(2px); } + +/* Checklist hover card — same reveal mechanics as the tooltip, but a + * multi-line block listing each criterion with a done marker. */ +.goal-card { + visibility: hidden; + opacity: 0; + position: absolute; + left: calc(100% + 14px); + top: 50%; + transform: translateY(-50%); + width: 280px; + background: var(--mc-text-primary, #1d1612); + color: var(--mc-bg-elevated, #ffffff); + padding: 10px 12px; + border-radius: 10px; + box-shadow: 0 10px 30px rgba(0, 0, 0, 0.22); + transition: opacity 150ms ease, transform 150ms ease; + z-index: 10; + pointer-events: none; +} +.avatar-with-ring:hover .goal-card { + visibility: visible; + opacity: 1; + transform: translateY(-50%) translateX(2px); +} +.goal-card-head { + display: flex; + align-items: baseline; + justify-content: space-between; + gap: 10px; + margin-bottom: 6px; +} +.goal-card-title { + font-size: 12px; + font-weight: 600; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +.goal-card-count { + font-size: 11px; + color: #b6905b; + font-variant-numeric: tabular-nums; + flex-shrink: 0; +} +.goal-card-list { + list-style: none; + margin: 0; + padding: 0; + display: flex; + flex-direction: column; + gap: 4px; +} +.goal-card-list li { + display: flex; + align-items: flex-start; + gap: 7px; + font-size: 12px; + line-height: 1.35; + color: rgba(255, 255, 255, 0.82); +} +.goal-card-list li.done .goal-card-text { + color: rgba(255, 255, 255, 0.5); + text-decoration: line-through; +} +.goal-card-mark { + flex-shrink: 0; + width: 12px; + text-align: center; + color: #9b7d6c; +} +.goal-card-list li.done .goal-card-mark { + color: #2f8a6d; +} </style> diff --git a/mateclaw-ui/src/components/goal/GoalSetInlinePrompt.vue b/mateclaw-ui/src/components/goal/GoalSetInlinePrompt.vue index b36f2e60..1732e6a6 100644 --- a/mateclaw-ui/src/components/goal/GoalSetInlinePrompt.vue +++ b/mateclaw-ui/src/components/goal/GoalSetInlinePrompt.vue @@ -34,6 +34,9 @@ async function accept() { props.agentId, props.workspaceId, props.suggestedTitle, + // Default to autonomous continuation when the user opts in from here — + // the whole point of accepting is "keep working toward this". + { autoFollowup: true }, ) } finally { busy.value = false diff --git a/mateclaw-ui/src/composables/__tests__/wikilink.test.ts b/mateclaw-ui/src/composables/__tests__/wikilink.test.ts new file mode 100644 index 00000000..f8398973 --- /dev/null +++ b/mateclaw-ui/src/composables/__tests__/wikilink.test.ts @@ -0,0 +1,237 @@ +// @vitest-environment happy-dom +import { describe, it, expect } from 'vitest' +import { + resolveWikilink, + postprocessWikilinks, + type WikilinkRef, +} from '../wikilink' + +// Compact ref fixture used by most tests. Active refs only — archived cases +// have their own fixtures. +const REFS: WikilinkRef[] = [ + { slug: 'machine-learning-basics', title: '机器学习基础' }, + { slug: 'transformer-architecture', title: 'Transformer Architecture' }, + { slug: 'react-overview', title: 'React Overview' }, +] + +const ARCHIVED_REFS: WikilinkRef[] = [ + { slug: 'deprecated-concept', title: 'Deprecated Concept' }, +] + +// --------------------------------------------------------------------------- +// resolveWikilink — pure resolution semantics (no DOM) +// --------------------------------------------------------------------------- +describe('resolveWikilink — happy path', () => { + it('resolves an exact slug match to a hit', () => { + const r = resolveWikilink('machine-learning-basics', REFS) + expect(r).toEqual({ + kind: 'hit', + slug: 'machine-learning-basics', + display: '机器学习基础', + archived: false, + }) + }) + + it('resolves an exact title match to a hit', () => { + const r = resolveWikilink('Transformer Architecture', REFS) + expect(r.kind).toBe('hit') + if (r.kind === 'hit') expect(r.slug).toBe('transformer-architecture') + }) + + it('honours [[slug|display]] alias form', () => { + const r = resolveWikilink('machine-learning-basics|入门指南', REFS) + expect(r).toEqual({ + kind: 'hit', + slug: 'machine-learning-basics', + display: '入门指南', + archived: false, + }) + }) + + it('resolves an archived target with archived=true', () => { + const r = resolveWikilink('deprecated-concept', REFS, ARCHIVED_REFS) + expect(r.kind).toBe('hit') + if (r.kind === 'hit') { + expect(r.archived).toBe(true) + expect(r.slug).toBe('deprecated-concept') + } + }) + + it('prefers active refs over archived refs on slug clash', () => { + const active: WikilinkRef[] = [{ slug: 'foo', title: 'Active Foo' }] + const archived: WikilinkRef[] = [{ slug: 'foo', title: 'Archived Foo' }] + const r = resolveWikilink('foo', active, archived) + expect(r.kind).toBe('hit') + if (r.kind === 'hit') expect(r.archived).toBe(false) + }) +}) + +// --------------------------------------------------------------------------- +// 6 safety cases — every one of these MUST degrade to a broken span and MUST +// NOT inject the raw target into any attribute or eval-context. The viewer's +// XSS surface depends on this resolver returning 'broken' for these inputs. +// --------------------------------------------------------------------------- +describe('resolveWikilink — safety cases', () => { + it('safety 1: <script> tag in target → broken (dangerous)', () => { + const r = resolveWikilink('<script>alert(1)</script>', REFS) + expect(r.kind).toBe('broken') + if (r.kind === 'broken') expect(r.reason).toBe('dangerous') + }) + + it('safety 2: double quote in target → broken (dangerous)', () => { + const r = resolveWikilink('foo"onmouseover=alert(1)', REFS) + expect(r.kind).toBe('broken') + if (r.kind === 'broken') expect(r.reason).toBe('dangerous') + }) + + it('safety 3: adjacent [[a]] [[b]] inside one raw → broken target name', () => { + // The resolver only ever sees the content between a single pair of [[ ]]. + // If a malformed source contains `[[a]] [[b`, the regex matches `[[a]]` + // cleanly and the resolver receives 'a'. We instead test the worse case + // where an open `[[` leaks INTO the raw value via a malformed source. + const r = resolveWikilink('foo [[ bar', REFS) + expect(r.kind).toBe('broken') // unknown slug 'foo [[ bar' (no danger char) + }) + + it('safety 4: multiple `|` characters split on first only, no injection', () => { + const r = resolveWikilink('machine-learning-basics|a|b|c', REFS) + expect(r.kind).toBe('hit') + if (r.kind === 'hit') expect(r.display).toBe('a|b|c') + }) + + it('safety 5: empty raw → broken (empty)', () => { + expect(resolveWikilink('', REFS).kind).toBe('broken') + expect(resolveWikilink(' ', REFS).kind).toBe('broken') + expect(resolveWikilink('|display-only', REFS).kind).toBe('broken') + }) + + it('safety 6: oversize slug (>256 chars) → broken (too-long)', () => { + const big = 'a'.repeat(300) + const r = resolveWikilink(big, REFS) + expect(r.kind).toBe('broken') + if (r.kind === 'broken') expect(r.reason).toBe('too-long') + }) + + it('rejects control characters (NUL, US, DEL)', () => { + expect(resolveWikilink('slug\x00ish', REFS).kind).toBe('broken') + expect(resolveWikilink('slug\x1Fish', REFS).kind).toBe('broken') + expect(resolveWikilink('slug\x7Fish', REFS).kind).toBe('broken') + }) + + it('rejects backtick (template-literal escape vector)', () => { + expect(resolveWikilink('slug`evil', REFS).kind).toBe('broken') + }) + + it('rejects newlines (would break attribute serialisation)', () => { + expect(resolveWikilink('slug\nfoo', REFS).kind).toBe('broken') + expect(resolveWikilink('slug\rfoo', REFS).kind).toBe('broken') + }) +}) + +// --------------------------------------------------------------------------- +// postprocessWikilinks — DOM walker behaviour +// --------------------------------------------------------------------------- +describe('postprocessWikilinks — DOM behaviour', () => { + function setup(html: string): HTMLElement { + const root = document.createElement('div') + root.innerHTML = html + return root + } + + it('replaces a hit into <a class="wiki-link" data-slug>', () => { + const root = setup('<p>See [[machine-learning-basics]] for more.</p>') + postprocessWikilinks(root, (raw) => resolveWikilink(raw, REFS, ARCHIVED_REFS)) + const a = root.querySelector('a.wiki-link') as HTMLAnchorElement + expect(a).not.toBeNull() + expect(a.getAttribute('data-slug')).toBe('machine-learning-basics') + expect(a.textContent).toBe('机器学习基础') + expect(a.getAttribute('href')).toBeNull() + }) + + it('replaces an archived hit into <a class="wiki-link wiki-link-archived">', () => { + const root = setup('<p>See [[deprecated-concept]].</p>') + postprocessWikilinks(root, (raw) => resolveWikilink(raw, REFS, ARCHIVED_REFS)) + const a = root.querySelector('a.wiki-link.wiki-link-archived') as HTMLAnchorElement + expect(a).not.toBeNull() + expect(a.getAttribute('data-slug')).toBe('deprecated-concept') + expect(a.getAttribute('title')).toBe('Archived page') + }) + + it('replaces a miss into <span class="wiki-link-broken"> with no clickable surface', () => { + const root = setup('<p>See [[unknown-page]] sometime.</p>') + postprocessWikilinks(root, (raw) => resolveWikilink(raw, REFS, ARCHIVED_REFS)) + const span = root.querySelector('span.wiki-link-broken') as HTMLSpanElement + expect(span).not.toBeNull() + expect(root.querySelector('a')).toBeNull() + // Display falls back to the literal [[...]] so the malformed source is + // visible to the reader. + expect(span.textContent).toBe('[[unknown-page]]') + }) + + it('does not interpolate dangerous raw into attributes', () => { + // The realistic vector: a text node carries the literal `<script>` chars, + // produced by markdown rendering (DOMPurify strips actual <script> tags + // upstream, so what reaches the postprocess is text). Build the DOM with + // textContent rather than innerHTML so the test doesn't accidentally make + // happy-dom parse the literal as a script element before we run. + const root = document.createElement('div') + const p = document.createElement('p') + p.textContent = 'Bad: [[<script>alert(1)</script>]] stay safe.' + root.appendChild(p) + expect(root.querySelector('script')).toBeNull() // sanity — text-node form + postprocessWikilinks(root, (raw) => resolveWikilink(raw, REFS, ARCHIVED_REFS)) + expect(root.querySelector('script')).toBeNull() + expect(root.querySelector('a')).toBeNull() + const span = root.querySelector('span.wiki-link-broken') as HTMLSpanElement + expect(span).not.toBeNull() + // The attribute carrying user data is the title; verify it's the rejection + // reason, not the raw payload. + expect(span.getAttribute('title')).toMatch(/dangerous/) + // Visible label is the literal [[...]] — readers see the malformed source + // verbatim instead of having it silently swallowed. + expect(span.textContent).toContain('<script>') + }) + + it('skips <code> and <pre> subtrees', () => { + const root = setup( + '<p>Outside [[machine-learning-basics]] active.</p>' + + '<pre><code>Inside [[machine-learning-basics]] kept literal.</code></pre>', + ) + postprocessWikilinks(root, (raw) => resolveWikilink(raw, REFS, ARCHIVED_REFS)) + // Outside text → replaced into <a> + const a = root.querySelector('p a.wiki-link') + expect(a).not.toBeNull() + // Inside <pre><code> → still literal + const code = root.querySelector('pre code') as HTMLElement + expect(code.textContent).toContain('[[machine-learning-basics]]') + expect(code.querySelector('a')).toBeNull() + }) + + it('skips inline <code>', () => { + const root = setup('<p>This is <code>[[inline]]</code> example.</p>') + postprocessWikilinks(root, (raw) => resolveWikilink(raw, REFS, ARCHIVED_REFS)) + const code = root.querySelector('code') as HTMLElement + expect(code.textContent).toBe('[[inline]]') + expect(code.querySelector('a')).toBeNull() + expect(code.querySelector('span')).toBeNull() + }) + + it('handles multiple wikilinks in one paragraph', () => { + const root = setup( + '<p>See [[machine-learning-basics]] and [[transformer-architecture]] and [[unknown-x]].</p>', + ) + postprocessWikilinks(root, (raw) => resolveWikilink(raw, REFS, ARCHIVED_REFS)) + expect(root.querySelectorAll('a.wiki-link').length).toBe(2) + expect(root.querySelectorAll('span.wiki-link-broken').length).toBe(1) + }) + + it('is idempotent — running twice does not double-wrap', () => { + const root = setup('<p>See [[machine-learning-basics]] first.</p>') + const resolver = (raw: string) => resolveWikilink(raw, REFS, ARCHIVED_REFS) + postprocessWikilinks(root, resolver) + const firstHtml = root.innerHTML + postprocessWikilinks(root, resolver) + expect(root.innerHTML).toBe(firstHtml) + expect(root.querySelectorAll('a.wiki-link').length).toBe(1) + }) +}) diff --git a/mateclaw-ui/src/composables/chat/useStream.ts b/mateclaw-ui/src/composables/chat/useStream.ts index 3741bd3b..3dbcb251 100644 --- a/mateclaw-ui/src/composables/chat/useStream.ts +++ b/mateclaw-ui/src/composables/chat/useStream.ts @@ -50,7 +50,7 @@ export type SSEEventType = | 'delegation_async_spawned' // Heartbeat watchdog flagged a sub-agent as making no observable progress | 'subagent_stale' - // Persistent goal events (RFC 48) — emitted by GoalEvaluationNode + // Persistent goal events — emitted by GoalEvaluationNode | 'goal_evaluated' | 'goal_followup' | 'goal_completed' diff --git a/mateclaw-ui/src/composables/useGlobalFileDownloadClick.ts b/mateclaw-ui/src/composables/useGlobalFileDownloadClick.ts new file mode 100644 index 00000000..9ed56ed1 --- /dev/null +++ b/mateclaw-ui/src/composables/useGlobalFileDownloadClick.ts @@ -0,0 +1,96 @@ +// Global click delegator for tool-generated file download links. +// +// `useMarkdownRenderer.link()` turns a tool-returned download URL such as +// `[报告.docx](/api/v1/files/generated/<id>)` into a plain same-origin +// `<a href>`. With no consumer, clicking it lets the browser perform a +// whole-window navigation to that URL. When the file has expired, was never +// produced, or the backend restarted, the endpoint answers +// `404 {"error":"File not found or expired"}` — and because it is a full-page +// navigation, that JSON *replaces the entire SPA*. In the desktop shell there +// is no back affordance, so the user is stuck and must restart the app. +// +// This composable closes that gap. It intercepts clicks on any same-origin +// `/api/v1/files/...` anchor and downloads via an authenticated fetch → blob +// instead of navigating: +// - success → trigger a transient `<a download>`; the SPA never unmounts. +// - failure (404 / expired / network) → an inline toast; the user stays in +// the conversation with the chat intact. +// +// Mounted exactly once at app root (see App.vue). Because the root component +// never unmounts, detaching the listener on unmount is a formality. + +import { onMounted, onBeforeUnmount } from 'vue' +import { useI18n } from 'vue-i18n' +import { fetchAuthenticatedBlob } from '@/api/index' +import { mcToast } from '@/composables/useMcToast' + +// Matches every backend-served file path: in-memory generated files +// (`/api/v1/files/generated/<id>`) and conversation-scoped media/attachments +// (`/api/v1/files/...`, `/api/v1/chat/files/...`). +const FILE_PATH_RE = /^\/api\/v1\/(files|chat\/files)\// + +function filenameFor(anchor: HTMLAnchorElement, pathname: string): string { + const text = (anchor.textContent || '').trim() + // The markdown link label is the human filename ("报告.docx"); prefer it + // when it carries an extension, otherwise fall back to the URL's last segment. + if (text && /\.[a-z0-9]{1,8}$/i.test(text)) return text + const seg = decodeURIComponent(pathname.split('/').filter(Boolean).pop() || '') + return seg || text || 'download' +} + +export function useGlobalFileDownloadClick() { + const { t } = useI18n() + + async function handleClick(e: MouseEvent) { + // Honour modifier-clicks (open in new tab / window) and non-primary buttons. + if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return + const target = e.target as HTMLElement | null + if (!target) return + const anchor = target.closest<HTMLAnchorElement>('a[href]') + if (!anchor) return + + // Only same-origin file-API links; leave everything else to the browser. + let url: URL + try { + url = new URL(anchor.href, window.location.href) + } catch { + return + } + if (url.origin !== window.location.origin || !FILE_PATH_RE.test(url.pathname)) return + + // From here the link is ours: never let it become a full-page navigation. + e.preventDefault() + e.stopPropagation() + + const name = filenameFor(anchor, url.pathname) + try { + const blob = await fetchAuthenticatedBlob(url.href) + const objectUrl = URL.createObjectURL(blob) + const a = document.createElement('a') + a.href = objectUrl + a.download = name + document.body.appendChild(a) + a.click() + document.body.removeChild(a) + setTimeout(() => URL.revokeObjectURL(objectUrl), 10000) + mcToast.success(t('chat.downloadStarted', { name })) + } catch (err: any) { + // A cache-miss / expiry surfaces as a non-OK fetch ("Fetch failed: 404"). + const status = /(\d{3})/.exec(err?.message || '')?.[1] + if (status === '404' || status === '410') { + mcToast.error(t('chat.downloadExpired')) + } else { + mcToast.error(t('chat.downloadFailed', { reason: err?.message || 'unknown' })) + } + } + } + + onMounted(() => { + // Capture phase so we intercept before any descendant handler, and before + // the browser's default navigation on the anchor. + document.addEventListener('click', handleClick, { capture: true }) + }) + onBeforeUnmount(() => { + document.removeEventListener('click', handleClick, { capture: true }) + }) +} diff --git a/mateclaw-ui/src/composables/useGlobalWikilinkClick.ts b/mateclaw-ui/src/composables/useGlobalWikilinkClick.ts new file mode 100644 index 00000000..b153695e --- /dev/null +++ b/mateclaw-ui/src/composables/useGlobalWikilinkClick.ts @@ -0,0 +1,108 @@ +// Global click delegator for chat-rendered wikilinks. +// +// useMarkdownRenderer's `legacy` mode (default for chat / memory / docs +// surfaces) turns `[[Title]]` into `<a class="wiki-link" data-wiki-title="Title">`. +// Before this composable was wired, those anchors had no consumer — the +// inline onclick that the renderer emits gets stripped by DOMPurify, and +// nothing else in the codebase listens for the `wiki-link-click` custom +// event the renderer fires. Clicking a wikilink in chat was therefore a +// no-op. +// +// This composable plugs that gap. It: +// 1. Listens at document level for every click that originates inside a +// `.wiki-link` element carrying a `data-wiki-title` attribute. +// 2. Skips clicks whose anchor already has a `data-slug` attribute — +// those originate from WikiPageViewer's own DOM postprocess and have +// a local handler in the wiki view that resolves against currentKB. +// 3. Calls the cross-KB lookup API. +// 4. Navigates to the wiki view with `?kbId=X&slug=Y` query params: +// - 0 hits → toast warning "未找到匹配的 wiki 页面" +// - 1 hit → router.push direct +// - >1 → mcConfirm picker with KB names so the user picks which +// KB they want to open +// +// Mounted exactly once at app root (see App.vue). Removing the listener +// on unmount is unnecessary because the root component never unmounts. + +import { onMounted, onBeforeUnmount } from 'vue' +import { useRouter } from 'vue-router' +import { wikiApi } from '@/api/index' +import { mcToast } from '@/composables/useMcToast' +import { mcConfirm } from '@/components/common/useConfirm' + +interface LookupMatch { + kbId: string + kbName: string + slug: string + title: string + archived: boolean +} + +export function useGlobalWikilinkClick() { + const router = useRouter() + + async function handleClick(e: MouseEvent) { + const target = e.target as HTMLElement | null + if (!target) return + // The click might land on a descendant of the <a>; walk up if needed. + const anchor = target.closest<HTMLElement>('a.wiki-link, .wiki-link') + if (!anchor) return + // WikiPageViewer's own postprocess produces <a class="wiki-link" + // data-slug=...> for in-wiki navigation. Its onMounted hook reads + // data-slug and calls store.loadPage on the current KB. Don't + // intercept those — only the chat / external surfaces emit + // data-wiki-title without data-slug. + if (anchor.hasAttribute('data-slug')) return + const title = anchor.getAttribute('data-wiki-title') + if (!title) return + + // Prevent the no-op href="#" jump and bubbling. + e.preventDefault() + e.stopPropagation() + + try { + // Pass both — backend matches slug first, falls back to title. For + // a bracket like `[[StateGraph]]` the captured "title" is actually + // the slug-or-title token, so either lookup might hit. + const res: any = await wikiApi.lookupPage({ title, slug: title }) + const matches: LookupMatch[] = res.data || res || [] + if (matches.length === 0) { + mcToast.info(`未找到匹配的 wiki 页面：${title}`) + return + } + if (matches.length === 1) { + await openMatch(matches[0]) + return + } + // Multiple hits — let the user pick which KB. mcConfirm is yes/no, + // not a picker, so we show a numbered list and prompt with the + // first match by default while toasting how to refine. + const ok = await mcConfirm({ + title: `多个 KB 有「${title}」`, + message: matches + .map((m, i) => `${i + 1}. ${m.kbName} → ${m.title}`) + .join('\n') + `\n\n打开第一个 (${matches[0].kbName})？`, + confirmText: '打开第一个', + tone: 'primary', + }) + if (ok) await openMatch(matches[0]) + } catch (err: any) { + console.error('[wikilink] lookup failed', err) + mcToast.error('Wiki 链接跳转失败') + } + } + + function openMatch(m: LookupMatch) { + return router.push({ + name: 'Wiki', + query: { kbId: m.kbId, slug: m.slug }, + }) + } + + onMounted(() => { + document.addEventListener('click', handleClick, { capture: false }) + }) + onBeforeUnmount(() => { + document.removeEventListener('click', handleClick) + }) +} diff --git a/mateclaw-ui/src/composables/useMarkdownRenderer.ts b/mateclaw-ui/src/composables/useMarkdownRenderer.ts index 4df38173..3dd8e4d9 100644 --- a/mateclaw-ui/src/composables/useMarkdownRenderer.ts +++ b/mateclaw-ui/src/composables/useMarkdownRenderer.ts @@ -343,20 +343,43 @@ const purifyConfig = { const RENDER_CACHE = new Map<string, string>() const RENDER_CACHE_CAP = 200 -function cacheKey(text: string): string { +function cacheKey(text: string, wikilink: WikilinkMode): string { // Compact key — collisions on the order of 10^-6 in single-conversation // scope, and a false hit only causes a "stale" render of unchanged content // (no security implication since cached values are sanitized HTML). - return `${text.length}:${text.slice(0, 40)}:${text.slice(-40)}` + // The wikilink mode is part of the key so a 'none' caller cannot read back + // a 'legacy'-substituted cached entry of the same source. + return `${wikilink}:${text.length}:${text.slice(0, 40)}:${text.slice(-40)}` } // --------------------------------------------------------------------------- // Public API // --------------------------------------------------------------------------- + +/** + * Wikilink handling mode for {@link useMarkdownRenderer}. + * + * - `'legacy'` (default): pre-markdown string substitution of `[[Title]]` into + * `<a class="wiki-link" data-wiki-title="...">`, dispatching the global + * `wiki-link-click` event when clicked. Kept for chat / other views that + * already rely on this behaviour. + * - `'none'`: skip wikilink substitution entirely. Use this when the caller + * wants to walk the rendered DOM itself and resolve `[[...]]` against an + * authoritative `{slug, title}` index — the dedicated path used by the Wiki + * page viewer, where the legacy "guess slug from title" approach is unsafe. + */ +export type WikilinkMode = 'legacy' | 'none' + +export interface RenderMarkdownOptions { + /** How to handle `[[...]]` syntax. Defaults to `'legacy'`. */ + wikilink?: WikilinkMode +} + export function useMarkdownRenderer() { - function renderMarkdown(content: string): string { + function renderMarkdown(content: string, opts?: RenderMarkdownOptions): string { if (!content) return '' - const k = cacheKey(content) + const wikilink: WikilinkMode = opts?.wikilink ?? 'legacy' + const k = cacheKey(content, wikilink) const cached = RENDER_CACHE.get(k) if (cached !== undefined) { // Refresh LRU position — re-insert at the tail. @@ -368,10 +391,30 @@ export function useMarkdownRenderer() { // 1. LaTeX placeholders (skips fenced/inline code). const withLatex = preprocessLatex(content) // 2. Wiki link substitution: [[Title]] → <a class="wiki-link" …>. - const withWikiLinks = withLatex.replace( - /\[\[([^\]]+)\]\]/g, - '<a class="wiki-link" href="#" data-wiki-title="$1" onclick="window.dispatchEvent(new CustomEvent(\'wiki-link-click\',{detail:{title:\'$1\'}}));return false">$1</a>' - ) + // Skipped in 'none' mode so the caller can do its own DOM postprocess. + const withWikiLinks = + wikilink === 'none' + ? withLatex + : // Split `[[slug|display]]` into slug + display halves so the + // `data-wiki-title` attribute carries the slug ALONE (the cross-KB + // lookup keys off that) and the visible label is the display text + // (the alias an author chose). The earlier single-capture regex + // copied the whole bracket interior — including the literal `|` — + // into both, producing `data-wiki-title="slug|display"` lookups + // that the backend would never resolve. + withLatex.replace( + /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g, + (_match, slug: string, alias?: string) => { + const target = slug.trim().replace(/"/g, '"') + const visible = (alias?.trim() || slug.trim()).replace(/"/g, '"') + return ( + '<a class="wiki-link" href="#" data-wiki-title="' + target + + '" onclick="window.dispatchEvent(new CustomEvent(\'wiki-link-click\',{detail:{title:\'' + + target.replace(/'/g, "\\'") + + '\'}}));return false">' + visible + '</a>' + ) + }, + ) // 3. Marked → 4. DOMPurify. const rawHtml = markedInstance.parse(withWikiLinks) as string const result = DOMPurify.sanitize(rawHtml, purifyConfig) diff --git a/mateclaw-ui/src/composables/wikilink.ts b/mateclaw-ui/src/composables/wikilink.ts new file mode 100644 index 00000000..956079e8 --- /dev/null +++ b/mateclaw-ui/src/composables/wikilink.ts @@ -0,0 +1,245 @@ +// Wiki wikilink postprocess — resolves `[[slug]]` / `[[slug|display]]` markers +// in already-rendered markdown HTML into the three canonical link states the +// Wiki page viewer ships: +// +// <a class="wiki-link" data-slug=...> active page hit +// <a class="wiki-link wiki-link-archived" ...> archived page hit +// <span class="wiki-link-broken" title=...> unresolved / unsafe target +// +// Two reasons this lives outside the viewer .vue: +// +// 1. The previous regex-based substitution was unsafe (interpolated raw +// target into HTML attributes, didn't skip code blocks, guessed slugs by +// lower-casing titles). Putting the new logic in a pure helper lets the +// 6 safety cases get covered by ordinary unit tests instead of mounting +// the whole Vue component. +// 2. The DOM walker has to skip code/pre/kbd/samp subtrees. That's the only +// "code block protection" needed once markdown has already produced +// proper <pre><code> wrappers — no string-level sentinel substitution. + +/** + * Lightweight {slug, title, archived} entry. Shape mirrors the backend + * `PageRef` DTO and the store's `WikiPageRef`. Kept local to avoid creating + * a build dependency from this file onto the Pinia store. + */ +export interface WikilinkRef { + slug: string + title: string + archived?: boolean +} + +/** Result of resolving a single `[[...]]` target string. */ +export type WikilinkResolution = + | { kind: 'hit'; slug: string; display: string; archived: boolean } + | { kind: 'broken'; display: string; reason: 'empty' | 'dangerous' | 'too-long' | 'unknown' } + +/** + * Tags whose contents must not be touched. `<pre>` and `<code>` cover fenced + * and inline code blocks emitted by marked; `<kbd>` and `<samp>` are listed + * for completeness so authors can show literal wikilink syntax in docs + * without it being silently rewritten. + */ +const SKIP_TAGS = new Set(['PRE', 'CODE', 'KBD', 'SAMP']) + +/** + * Characters that turn a wikilink into an attribute-injection or HTML-context + * escape risk. The list is intentionally narrow — slug values can legitimately + * contain CJK and `-`, so we reject only what is unambiguously dangerous (HTML + * delimiters, quote characters, backtick, line breaks, C0 / DEL control bytes). + * + * 0x00–0x1F (excluding TAB which is rare in slugs anyway) and 0x7F catch the + * NUL / control-char family that broke an earlier draft of this RFC document + * when someone wrote them literally instead of as escape text. If a real slug + * needs a tab character, that is a backend bug worth surfacing. + */ +// eslint-disable-next-line no-control-regex +const DANGEROUS_CHAR_RE = /[<>"'`\n\r\x00-\x1F\x7F]/ + +/** Slug length cap. Backend `toSlug` produces slugs well under this. */ +const MAX_SLUG_LEN = 256 + +/** `[[...]]` matcher used during text-node walking. Non-greedy. */ +const WIKILINK_RE = /\[\[([^\]]+?)\]\]/g + +/** + * Resolve a single raw target into a render directive. + * + * The function is pure: no DOM access, no store reads. Tests drive it with + * synthetic `refs` arrays to verify each of the six safety cases enumerated in + * the RFC (script tag, double quote, nested brackets, multi `|`, empty, oversize). + * + * Resolution order: + * 1. Empty / dangerous / oversize → broken span, raw never enters output + * attributes. The visible text falls back to the original `[[...]]` + * literal so users can spot the malformed content. + * 2. Exact slug match against active refs. + * 3. Title match (trim + case-insensitive) against active refs. + * 4. Same two passes against archived refs — hit renders as archived. + * 5. Otherwise broken. + * + * Title-fallback is kept because the RFC's migration plan allows older content + * that still writes `[[Page Title]]` to keep resolving for six months while + * the slug-first prompt rollout (Phase 3) replaces it. Once that window closes + * the title branch can be deleted without any other code change. + */ +export function resolveWikilink( + raw: string, + refs: WikilinkRef[], + archivedRefs: WikilinkRef[] = [], +): WikilinkResolution { + const rawTrimmed = (raw ?? '').trim() + const literal = `[[${raw ?? ''}]]` + + if (!rawTrimmed) { + return { kind: 'broken', display: literal, reason: 'empty' } + } + if (DANGEROUS_CHAR_RE.test(rawTrimmed)) { + return { kind: 'broken', display: literal, reason: 'dangerous' } + } + // Split [[target|display]] form. Only the first `|` is honoured; any extras + // are kept verbatim in the display text and trigger the dangerous-char path + // only if they collide with the rejection set (they don't, `|` is allowed). + // + // `explicitDisplay` is the empty string when the source uses the bare + // `[[target]]` form. In that case the visible label falls back to the + // resolved page's title (more readable than the slug). When the source + // explicitly overrides via `|`, that override always wins. + const pipeIdx = rawTrimmed.indexOf('|') + const target = pipeIdx >= 0 ? rawTrimmed.slice(0, pipeIdx).trim() : rawTrimmed + const explicitDisplay = pipeIdx >= 0 ? rawTrimmed.slice(pipeIdx + 1).trim() : '' + + if (!target) { + return { kind: 'broken', display: literal, reason: 'empty' } + } + if (target.length > MAX_SLUG_LEN) { + return { kind: 'broken', display: literal, reason: 'too-long' } + } + + const lookupSlug = target.toLowerCase() + const lookupTitle = target.trim().toLowerCase() + + for (const ref of refs) { + if (ref.slug.toLowerCase() === lookupSlug) { + return { kind: 'hit', slug: ref.slug, display: explicitDisplay || ref.title, archived: false } + } + } + for (const ref of refs) { + if (ref.title.trim().toLowerCase() === lookupTitle) { + return { kind: 'hit', slug: ref.slug, display: explicitDisplay || ref.title, archived: false } + } + } + for (const ref of archivedRefs) { + if (ref.slug.toLowerCase() === lookupSlug) { + return { kind: 'hit', slug: ref.slug, display: explicitDisplay || ref.title, archived: true } + } + } + for (const ref of archivedRefs) { + if (ref.title.trim().toLowerCase() === lookupTitle) { + return { kind: 'hit', slug: ref.slug, display: explicitDisplay || ref.title, archived: true } + } + } + return { kind: 'broken', display: literal, reason: 'unknown' } +} + +/** + * Build the DOM element for a resolution result. + * + * Always uses `document.createElement` + `textContent` + `setAttribute`. No + * `innerHTML` writes anywhere — the previous regex-based substitution path + * concatenated raw target strings into HTML and was the original source of + * the bug class this RFC closes. + */ +function buildLinkElement( + doc: Document, + resolution: WikilinkResolution, +): HTMLElement { + if (resolution.kind === 'hit') { + const a = doc.createElement('a') + a.className = resolution.archived ? 'wiki-link wiki-link-archived' : 'wiki-link' + a.setAttribute('data-slug', resolution.slug) + // No href: the page viewer hooks click via the global `wiki-link` listener + // and routes through the Pinia store. Adding a real href would expose the + // app to middle-click "open in new tab" 404s since the route layer is SPA. + a.setAttribute('role', 'link') + a.setAttribute('tabindex', '0') + if (resolution.archived) { + a.setAttribute('title', 'Archived page') + } + a.textContent = resolution.display + return a + } + const span = doc.createElement('span') + span.className = 'wiki-link-broken' + span.setAttribute('title', `Target not found (${resolution.reason})`) + span.textContent = resolution.display + return span +} + +/** + * Walk the rendered article DOM and replace every `[[...]]` token inside a + * text node with the appropriate `<a>` or `<span>` element. + * + * The walker uses {@link TreeWalker} with `NodeFilter.SHOW_TEXT` so we only + * ever look at text nodes — element nodes and their attributes are not even + * candidates for substitution. The filter additionally rejects any text node + * whose ancestor chain crosses a {@link SKIP_TAGS} element, so code blocks, + * inline code and the other docstring-style tags remain literal. + * + * The function is idempotent: text nodes that no longer match `[[...]]` are + * skipped, and previously-inserted `<a>`/`<span>` elements have no text-node + * children carrying the original syntax (it is consumed by the regex split). + */ +export function postprocessWikilinks( + root: HTMLElement, + resolver: (raw: string) => WikilinkResolution, + doc: Document = root.ownerDocument ?? document, +): void { + const walker = doc.createTreeWalker(root, NodeFilter.SHOW_TEXT, { + acceptNode(node) { + // Reject text nodes inside any of the skip tags. Walking ancestors is + // cheap because the markdown tree depth is bounded by Marked's grammar. + let parent: Node | null = node.parentNode + while (parent && parent !== root) { + if (parent.nodeType === 1 /* ELEMENT_NODE */) { + const tag = (parent as Element).tagName + if (SKIP_TAGS.has(tag)) return NodeFilter.FILTER_REJECT + } + parent = parent.parentNode + } + return WIKILINK_RE.test(node.nodeValue ?? '') + ? NodeFilter.FILTER_ACCEPT + : NodeFilter.FILTER_REJECT + }, + }) + + // Collect first, mutate second — mutating the tree while walking it would + // skip siblings or revisit nodes. + const targets: Text[] = [] + let cur = walker.nextNode() + while (cur) { + targets.push(cur as Text) + cur = walker.nextNode() + } + + for (const textNode of targets) { + const original = textNode.nodeValue ?? '' + // Reset regex state — the regex is module-level with /g, so `lastIndex` + // carries over between text nodes if we don't. + WIKILINK_RE.lastIndex = 0 + const fragment = doc.createDocumentFragment() + let lastIdx = 0 + let match: RegExpExecArray | null + while ((match = WIKILINK_RE.exec(original)) !== null) { + if (match.index > lastIdx) { + fragment.appendChild(doc.createTextNode(original.slice(lastIdx, match.index))) + } + const resolution = resolver(match[1]) + fragment.appendChild(buildLinkElement(doc, resolution)) + lastIdx = match.index + match[0].length + } + if (lastIdx < original.length) { + fragment.appendChild(doc.createTextNode(original.slice(lastIdx))) + } + textNode.parentNode?.replaceChild(fragment, textNode) + } +} diff --git a/mateclaw-ui/src/i18n/locales/en-US.ts b/mateclaw-ui/src/i18n/locales/en-US.ts index 25e02ef6..ffaf38d9 100644 --- a/mateclaw-ui/src/i18n/locales/en-US.ts +++ b/mateclaw-ui/src/i18n/locales/en-US.ts @@ -13,6 +13,9 @@ export default { create: 'Create', update: 'Update', loading: 'Loading...', + processing: 'Processing...', + success: 'Done', + revoked: 'Revoked', enabled: 'Enabled', disabled: 'Disabled', default: 'Default', @@ -92,6 +95,23 @@ export default { interrupted: 'Interrupted', subagentStalled: 'Subagent stalled — no progress', subagentAsync: 'Running in background — result via task_output', + executionPlan: 'Execution Plan', + planDone: 'done', + detail: { + viewDetail: 'View details', + request: 'Request', + response: 'Response', + copy: 'Copy', + copied: 'Copied', + copyFailed: 'Copy failed', + empty: 'No content', + status: { + running: 'In progress', + completed: 'Completed', + error: 'Failed', + pending: 'Pending', + }, + }, expandLines: 'Show more ({hidden} more lines)', collapse: 'Show less', failed: 'Generation failed', @@ -155,6 +175,9 @@ export default { }, copy: 'Copy', copied: 'Copied', + downloadStarted: 'Downloading: {name}', + downloadExpired: 'This file has expired or is no longer available. Ask the assistant to generate it again, then download.', + downloadFailed: 'Download failed: {reason}', regenerate: 'Regenerate', replyModel: 'Reply model: {model}', routing: { @@ -183,6 +206,7 @@ export default { startNewChat: 'Start a new chat above', messages: '{count} messages', configModel: 'Configure Model', + modelSaveFailed: 'Model switch was not saved — the next message may still use the previous model', openSessions: 'Session Admin', clearMessages: 'Clear Messages', goToModelSettings: 'Go to Model Settings', @@ -276,15 +300,20 @@ export default { executing: 'Executing…', fallbackName: 'Scheduled task', }, - suggestionIntro: 'Remember I hate cilantro and love iced Americanos — remind me when ordering', - suggestionPoem: 'Search for today\'s biggest tech news and summarize it in one sentence', - suggestionCode: 'Ask the writer agent to polish a draft I\'m about to send you', - suggestionWeather: 'What skills and tools do you have right now? Show me how to add more', - suggestionPlan1: 'Help me draft a complete project plan', - suggestionPlan2: 'Walk me through a complex task step by step', + suggestionIntro: 'Remember my Monday 10am team sync — draft the agenda 10 minutes before', + suggestionPoem: 'Ingest this PRD into my knowledge base — check there first before going to the web', + suggestionCode: 'Break this release into executable steps and pause for approval at key checkpoints', + suggestionWeather: 'What skills, tools, and MCP servers do you have? Show me how to add a new one', + suggestionPlan1: 'Decompose a full release plan into steps with approval gates at critical checkpoints', + suggestionPlan2: 'Break this complex task into trackable subtasks and report progress as you go', approvalRequired: 'Approval Required', approve: 'Approve', deny: 'Deny', + approveAlways: 'Always approve', + approveAlwaysConversation: 'this conversation', + approveAlwaysAgent: 'this agent', + approveAlwaysUser: 'all my agents', + approveAlwaysCreated: 'Auto-approve rule added: {tool}', approvalHint: 'or type <code>/approve</code> / <code>/deny</code>', approved: '✅ Approved', denied: '⛔ Denied', @@ -294,7 +323,13 @@ export default { thinkingOn: 'Deep thinking enabled', thinkingOff: 'Click to enable deep thinking', thinkingUnsupported: 'Current model does not support deep thinking', - subtitle: 'Your intelligent AI assistant powered by Spring AI Alibaba', + slashMenuTitle: 'Skills', + slashMenuHint: '↑↓ navigate · Enter select · Esc dismiss', + slashMenuLoading: 'Loading skills…', + slashMenuEmpty: 'No matching skills', + slashMenuSearchPlaceholder: 'Search skills…', + useSkillDirective: 'Use the "{name}" skill: ', + subtitle: 'Memory · Knowledge base · Skills · Automation — your personal AI operating surface', // Queue related queuedSending: 'Sending queued message...', queuedWillSend: 'Queued, will send after current step', @@ -1124,6 +1159,7 @@ export default { skills: 'Skills', tools: 'Tools', providers: 'Providers', + wiki: 'Knowledge Base', context: 'Context', }, columns: { @@ -1163,6 +1199,8 @@ export default { extraInstructionsHint: 'Optional. Use for output format, process checklists, or boundary rules.', maxIterations: 'Max Iterations', defaultThinkingLevel: 'Default Thinking Level', + workspaceBasePath: 'Working Directory', + workspaceBasePathHint: 'Optional. Set a dedicated working directory for this employee. Relative paths resolve under the workspace root; absolute paths are used as-is. Leave blank to inherit the workspace default.', modelName: 'Model', modelGlobalDefault: 'Use global default', modelHint: 'Override the global default model for this employee. Leave blank to follow Settings → Models.', @@ -1198,6 +1236,7 @@ export default { backstory: 'e.g. Spent 10 years in data — believes in asking the right question before writing SQL...', extraInstructions: 'Optional: output format, process checklist, or boundary rules...', tags: 'tag1,tag2', + workspaceBasePath: 'e.g. projects/code-review', }, messages: { noDescription: 'No description', @@ -1215,9 +1254,15 @@ export default { skillsKicker: 'Trained workflows', skillsTagline: 'A skill is a workflow — a step-by-step playbook the LLM follows for a coherent multi-step task.', skillsHint: 'Select skills this agent can use. Leave empty to use all enabled skills.', + disableAllSkills: 'This agent uses no skills', + disableAllSkillsHint: 'Saving with this on clears the agent\'s skill bindings and marks it as "explicitly no skills": the LLM loads no SKILL.md catalog entries and skill-expanded tools do not enter the context. System-level primitives (memory, delegation, etc.) are unaffected. When off, picking nothing still falls back to "inherit global default".', + disableAllSkillsBadge: 'Off', toolsKicker: 'Atomic tools the agent can call', toolsTagline: 'A tool is one call, one thing. The LLM decides when to invoke each tool autonomously.', toolsHint: 'Select tools this agent can use. Leave empty to use all enabled tools.', + disableAllTools: 'This agent uses no user-pickable tools', + disableAllToolsHint: 'Saving with this on clears the agent\'s tool bindings and marks it as "explicitly no tools": neither user-pickable tools nor any enabled MCP tools enter the allowlist. System-level primitives (structured memory, workspace memory files, delegation, etc.) remain available so the agent can still operate. When off, picking nothing still falls back to "inherit global default".', + disableAllToolsBadge: 'Off', searchSkills: 'Search skill name, description, or version', searchTools: 'Search tool name, description, source, or group', advancedToolsTitle: 'Advanced: Hand-picked atomic tools', @@ -1240,6 +1285,13 @@ export default { noMatchingSkills: 'No matching skills', noMatchingTools: 'No matching tools', noProviderPreferences: 'No preferences set — the agent uses the global fallback chain order.', + wikiKicker: 'Primary Knowledge Base', + wikiTagline: 'Choose the default knowledge base this agent should prefer. Knowledge bases remain workspace-shared.', + wikiHint: 'Select this agent\'s primary knowledge base. When unset, workspace fallback applies.', + noKBs: 'No knowledge bases available', + noKB: 'No primary KB', + wikiPages: '{count} pages', + wikiLoadFailed: 'Failed to load knowledge bases', contextHint: 'Manage context files (e.g. AGENT.md) that define this agent\'s behavior, knowledge, and instructions.', goToContext: 'Edit Context Files', }, @@ -1972,6 +2024,7 @@ export default { selectPage: 'Select a page from the sidebar', pageKicker: 'Knowledge Page', confirmDelete: 'Delete page "{title}"? This cannot be undone.', + confirmDeleteRefs: '{count} pages link to this one — their wikilinks will be rewritten to plain text.', confirmBatchDelete: 'Delete {count} pages? This cannot be undone.', batchSelect: 'Batch select', selectAll: 'Select all', @@ -2080,6 +2133,81 @@ export default { lastError: 'Last error', footer: 'Toggling wiki.hot_cache.enabled off short-circuits the injection path. The "Rebuild now" button bypasses the debounce window for easier debugging.', }, + adv: { + tab: 'Advanced', + validate: 'Validate', + validOk: 'Validation passed', + profile: { + tab: 'Page Types', + title: 'Page Type Profile', + desc: 'Define this KB\'s page types, their knowledge layer, route/create/merge stage instructions and content templates. Injected into the ingest pipeline prompts.', + builtin: 'Built-in default', + placeholder: 'Paste the pageType profile JSON here…', + reset: 'Reset to default', + resetConfirm: 'Reset to the built-in default profile? Your custom config will be cleared.', + }, + layers: { + tab: 'Layers & Stale', + title: 'Knowledge Layers & Stale State', + desc: 'When a fact-layer page is updated, experience pages that depend on it are marked stale to flag they need review.', + fact: 'Fact', + experience: 'Experience', + other: 'Other', + stale: 'Stale', + empty: 'This knowledge base has no pages yet.', + page: 'Page', + layer: 'Layer', + status: 'Status', + staleTag: 'Needs review', + fresh: 'Fresh', + }, + perm: { + tab: 'Permissions', + title: 'Employee Page Type Permissions', + desc: 'Configure per-pageType read/create/update/delete access for an employee in this KB; writes can require approval. No rules = allow all; once any rule exists, uncovered types are fail-safe denied.', + agent: 'Employee', + selectAgent: 'Select an employee…', + pageType: 'Page Type', + policy: 'Write policy', + noRows: 'This employee has no permission rules (allow all).', + pageTypeHint: 'page type, * for default', + addRule: 'Add rule', + deleteConfirm: 'Delete the permission rule for "{type}"?', + }, + watcher: { + tab: 'Watcher', + title: 'Source Directory Watcher', + desc: 'Bind a local directory as a knowledge source; the watcher scans for new/changed files at an interval and ingests them automatically. You can also trigger a one-off scan.', + enabled: 'Watcher enabled', + active: 'Active', + interval: 'Scan interval', + sourceType: 'Source type', + directory: 'Source directory', + dirHint: 'absolute path, e.g. /data/docs', + availableTypes: 'Available source types', + scanNow: 'Scan now', + scanDone: 'Scan complete', + scanResult: 'Scanned {scanned}, added {added}, skipped {skipped}, errors {errors}', + }, + pipeline: { + tab: 'Pipelines', + title: 'Custom Pipelines', + desc: 'Define triggers (e.g. a page type reaching a count threshold, page created) and multi-step processing (llm / skill) in YAML. Once saved, the backend runs them on the trigger condition.', + name: 'Name', + trigger: 'Trigger', + enabled: 'Enabled', + runs: 'Runs', + empty: 'No pipeline definitions yet.', + editor: 'YAML definition', + editorHint: 'name: my-pipeline\ntrigger:\n type: page_type_count\n page_type: episode\n threshold: 10\nsteps:\n - executor: llm\n prompt: …', + saveDef: 'Save definition', + deleteConfirm: 'Delete pipeline "{name}"?', + runsFor: 'Runs for "{name}"', + status: 'Status', + startedAt: 'Started at', + noRuns: 'No runs yet.', + }, + }, searchPages: 'Search pages...', dropFiles: 'Drop files here or click to upload', dropToUpload: 'Release to upload', @@ -2214,6 +2342,19 @@ export default { archivedSection: 'Archived', noArchived: 'No archived pages', unarchive: 'Restore', + lint: { + neverScanned: 'No broken-link scan yet — click to check whether [[...]] references still resolve', + running: 'Scanning for broken links…', + scanning: 'Scanning…', + scan: 'Scan dead links', + rescan: 'Rescan', + cleanResult: 'Scanned {pages} pages — no broken links', + brokenSummary: 'Found {refs} broken links across {pages} pages', + view: 'View', + dismissTitle: 'Dismiss this notice', + panelTitle: 'Wiki broken-link report', + noReport: 'No scan yet — start one from the banner', + }, pageTypes: { concept: 'Concepts', person: 'People', @@ -3701,10 +3842,82 @@ export default { inlinePromptAccept: 'Yes', inlinePromptDecline: 'No thanks', autoFollowup: 'Auto continuation', + sidebarActive: 'This conversation has an active goal', completedTitle: 'Goal completed', completedDetail: 'Stored in long-term memory; askable later', exhaustedTitle: 'Budget exhausted', exhaustedDetailTurns: 'Turn budget ({used}/{budget}) exhausted.', exhaustedDetailLlm: 'LLM call budget exhausted.', }, + approval: { + grant: { + pill: { + inactive: 'Inactive', + manage: 'Manage auto-approve rules...', + }, + chipLabel: 'Auto-approve active ({count})', + chipShort: 'Auto-approve {count}', + menu: 'Auto-approve', + title: 'Auto-approve rules', + desc: 'Rules let specific tool calls skip manual approval. Safety-floor patterns (rm -rf /, pipe-to-shell, etc.) always apply, and CRITICAL severity always falls back to human approval.', + scope: { + conversation: 'Conversation', + agent: 'Agent', + user: 'User', + workspace: 'Workspace', + }, + kind: { + always: 'Always', + until: 'Until expiry', + conversationEnd: 'Until conversation ends', + }, + severityCeiling: 'Severity ceiling', + createBtn: 'New rule', + createWorkspaceBtn: 'Create workspace-wide rule (danger)', + createWorkspaceWarning: 'This rule will auto-approve every tool call from every user in this workspace. Safety-floor patterns still block disaster commands, but every other risk gets bypassed. Confirm with your login password.', + revokeBtn: 'Revoke', + revokeConfirm: 'Revoking will disable this rule. Continue?', + revokeConfirmDetailed: 'After revoking, auto-approve for {tool} will no longer apply — the next call will require manual review again. Continue?', + anyTool: 'all tools', + viewResolutions: 'View {count} auto-approve events triggered by this rule →', + empty: 'No auto-approve rules configured yet', + columns: { + scope: 'Scope', + tool: 'Tool', + rule: 'Rule', + severity: 'Severity ceiling', + kind: 'Kind', + expire: 'Expires', + grantedBy: 'Granted by', + grantedAt: 'Granted at', + note: 'Note', + actions: 'Actions', + }, + form: { + scopeType: 'Scope type', + scopeId: 'Scope id', + toolName: 'Tool name (empty = any tool)', + ruleId: 'Rule id (empty = any rule)', + maxSeverity: 'Max severity', + grantKind: 'Grant kind', + expireAt: 'Expire at', + note: 'Note', + password: 'Login password (required for sensitive rules)', + }, + }, + resolution: { + source: { + userManual: 'Manual approval', + autoGrant: 'Auto-approve', + hardBlock: 'Safety floor block', + timeout: 'Approval timeout', + }, + }, + hardBlock: { + banner: 'This command was blocked by the safety floor; it cannot be executed under any mode.', + }, + forceHuman: { + banner: 'This command requires manual approval; auto-approve rules do not apply.', + }, + }, } as const diff --git a/mateclaw-ui/src/i18n/locales/zh-CN.ts b/mateclaw-ui/src/i18n/locales/zh-CN.ts index b481c8ad..8844f702 100644 --- a/mateclaw-ui/src/i18n/locales/zh-CN.ts +++ b/mateclaw-ui/src/i18n/locales/zh-CN.ts @@ -13,6 +13,9 @@ export default { create: '创建', update: '更新', loading: '加载中...', + processing: '处理中...', + success: '操作成功', + revoked: '已撤销', enabled: '启用', disabled: '停用', default: '默认', @@ -92,6 +95,23 @@ export default { interrupted: '已中断', subagentStalled: '子 Agent 无进展', subagentAsync: '后台运行中，结果稍后获取', + executionPlan: '执行计划', + planDone: '已完成', + detail: { + viewDetail: '查看详情', + request: '请求参数', + response: '响应输出', + copy: '复制', + copied: '已复制', + copyFailed: '复制失败', + empty: '无内容', + status: { + running: '进行中', + completed: '已完成', + error: '失败', + pending: '待处理', + }, + }, expandLines: '展开（还有 {hidden} 行）', collapse: '收起', failed: '生成失败', @@ -155,6 +175,9 @@ export default { }, copy: '复制', copied: '已复制', + downloadStarted: '开始下载：{name}', + downloadExpired: '文件已失效或过期，请重新让助手生成后再下载', + downloadFailed: '下载失败：{reason}', regenerate: '重新生成', replyModel: '本条回复模型: {model}', routing: { @@ -183,6 +206,7 @@ export default { startNewChat: '开始新对话吧', messages: '{count} 条消息', configModel: '配置模型', + modelSaveFailed: '模型切换未保存，下条消息可能仍走原模型', openSessions: '会话管理', clearMessages: '清空消息', goToModelSettings: '前往模型设置', @@ -276,15 +300,20 @@ export default { executing: '执行中…', fallbackName: '定时任务', }, - suggestionIntro: '记住我平时不吃香菜、喜欢喝冰美式，以后点餐时提醒我', - suggestionPoem: '帮我搜一下今天科技圈有什么大新闻，用一句话总结', - suggestionCode: '让写手帮我润色一段文案，我先把草稿发你', - suggestionWeather: '你现在都装了哪些技能和工具？教我怎么给你加新本事', - suggestionPlan1: '帮我制定一个完整的项目计划', - suggestionPlan2: '分步骤帮我完成一个复杂任务', + suggestionIntro: '记住我每周一上午十点开周会，提前 10 分钟把议题草稿整理好发我', + suggestionPoem: '把这份需求文档录入我的知识库，下次相关问题先查它再决定要不要联网', + suggestionCode: '帮我把这次上线流程拆成可执行步骤，关键节点暂停等我审批', + suggestionWeather: '你现在挂载了哪些技能、工具和 MCP 服务？怎么给你新增一个？', + suggestionPlan1: '把一个完整发布计划拆成步骤，并在关键节点设置审批门禁', + suggestionPlan2: '把这个复杂任务拆成可追踪的子任务，逐步推进并随时汇报进度', approvalRequired: '需要审批', approve: '批准', deny: '拒绝', + approveAlways: '始终批准', + approveAlwaysConversation: '此次会话', + approveAlwaysAgent: '此 agent', + approveAlwaysUser: '我所有 agent', + approveAlwaysCreated: '已添加自动批准规则：{tool}', approvalHint: '或输入 <code>/approve</code> / <code>/deny</code>', approved: '✅ 已允许', denied: '⛔ 已拒绝', @@ -294,7 +323,13 @@ export default { thinkingOn: '深度思考已开启', thinkingOff: '点击开启深度思考', thinkingUnsupported: '当前模型不支持深度思考', - subtitle: '基于 Spring AI Alibaba 的智能 AI 助手', + slashMenuTitle: '技能', + slashMenuHint: '↑↓ 选择 · Enter 确认 · Esc 关闭', + slashMenuLoading: '加载技能中…', + slashMenuEmpty: '没有匹配的技能', + slashMenuSearchPlaceholder: '搜索技能…', + useSkillDirective: '使用「{name}」技能：', + subtitle: '记忆 · 知识库 · 技能 · 自动化 —— 你的个人 AI 工作面', // 排队相关 queuedSending: '正在发送排队消息...', queuedWillSend: '已排队，当前步骤结束后发送', @@ -1016,6 +1051,7 @@ export default { skills: '技能', tools: '工具', providers: '偏好提供商', + wiki: '知识库', context: '上下文', }, columns: { @@ -1055,6 +1091,8 @@ export default { extraInstructionsHint: '可选。用于细化输出格式、流程清单或边界规则。', maxIterations: '最大迭代次数', defaultThinkingLevel: '默认思考深度', + workspaceBasePath: '工作目录', + workspaceBasePathHint: '可选。为该员工指定独立的工作目录：相对路径会基于工作区根目录解析，也可填写绝对路径。留空则继承工作区默认目录。', modelName: '模型', modelGlobalDefault: '使用全局默认模型', modelHint: '为该员工单独指定模型，留空则跟随「设置 → 模型」中的全局默认。', @@ -1090,6 +1128,7 @@ export default { backstory: '例：在数据里待了十年，相信先问对问题再写 SQL...', extraInstructions: '可选：补充输出格式、流程清单或边界规则...', tags: 'tag1,tag2', + workspaceBasePath: '例如：projects/code-review', }, messages: { noDescription: '暂无描述', @@ -1107,9 +1146,15 @@ export default { skillsKicker: '受过培训的工作流程', skillsTagline: '技能 = 一段流程，一份工作手册。LLM 按手册执行一系列连贯动作。', skillsHint: '选择此智能体可使用的技能。留空则使用所有已启用的技能。', + disableAllSkills: '此智能体不使用任何技能', + disableAllSkillsHint: '开启后保存会清空该智能体的技能绑定，并标记为「显式无技能」：LLM 不再加载任何 SKILL.md 目录，技能扩展的工具也不会进入上下文。系统级内核工具（记忆、委派等）不受影响。关闭后，未勾选任何技能仍按「继承全局默认」处理。', + disableAllSkillsBadge: '已禁用', toolsKicker: '会用的原子工具', toolsTagline: '工具 = 一次调用，做一件事。由 LLM 自主决定何时调用。', toolsHint: '选择此智能体可使用的工具。留空则使用所有已启用的工具。', + disableAllTools: '此智能体不使用任何用户可选工具', + disableAllToolsHint: '开启后保存会清空该智能体的工具绑定，并标记为「显式无工具」：用户可选工具与已启用的 MCP 工具都不会进入 allowlist。系统级内核工具（结构化记忆、工作区记忆文件、委派等）仍保留以保证基本运行。关闭后，未勾选任何工具仍按「继承全局默认」处理。', + disableAllToolsBadge: '已禁用', searchSkills: '搜索技能名称、描述或版本', searchTools: '搜索工具名称、描述、来源或分组', advancedToolsTitle: '高级：手选原子工具', @@ -1132,6 +1177,13 @@ export default { noMatchingSkills: '没有匹配的技能', noMatchingTools: '没有匹配的工具', noProviderPreferences: '尚未配置偏好顺序，将按全局回退链顺序使用。', + wikiKicker: '主知识库', + wikiTagline: '为智能体指定默认优先使用的知识库，所有知识库仍保持工作区共享。', + wikiHint: '选择此智能体的主知识库。未指定时会按工作区知识库回退。', + noKBs: '暂无可用知识库', + noKB: '未指定主库', + wikiPages: '{count} 页', + wikiLoadFailed: '加载知识库列表失败', contextHint: '管理此智能体的上下文文件（如 AGENT.md），定义智能体的行为、知识和指令。', goToContext: '前往编辑上下文', }, @@ -1984,6 +2036,7 @@ export default { selectPage: '从左侧选择一个页面查看', pageKicker: '知识页面', confirmDelete: '确认删除页面「{title}」？此操作不可撤销。', + confirmDeleteRefs: '该页面被 {count} 个页面引用，删除后这些引用将被自动改写为纯文本。', confirmBatchDelete: '确认删除 {count} 个页面？此操作不可撤销。', batchSelect: '批量选择', selectAll: '全选', @@ -2092,6 +2145,81 @@ export default { lastError: '最近一次错误', footer: '关闭 wiki.hot_cache.enabled 后注入路径短路；该面板的"立即重建"会绕过去抖，方便调试。', }, + adv: { + tab: '高级管理', + validate: '校验', + validOk: '校验通过', + profile: { + tab: '页面类型', + title: '页面类型 Profile', + desc: '定义本知识库的页面类型（pageType）、所属知识分层、路由/创建/合并阶段指令与内容模板。会注入到摄取流水线的各阶段提示词。', + builtin: '内置默认', + placeholder: '在此粘贴 pageType profile 的 JSON…', + reset: '重置为默认', + resetConfirm: '确认重置为内置默认 profile？当前自定义配置会被清除。', + }, + layers: { + tab: '分层 & 失效', + title: '知识分层与失效状态', + desc: 'fact（事实）层更新后会把依赖它的 experience（经验）页面标记为 stale，提示需要复核。', + fact: '事实层', + experience: '经验层', + other: '其它', + stale: '已失效', + empty: '该知识库暂无页面。', + page: '页面', + layer: '分层', + status: '状态', + staleTag: '待复核', + fresh: '正常', + }, + perm: { + tab: '权限 & 审批', + title: '员工页面类型权限', + desc: '为指定员工配置在本知识库下按 pageType 的读/创建/更新/删除权限；写操作可设为需审批。无规则时默认放行，一旦存在规则则未覆盖的类型按失败安全（拒绝）处理。', + agent: '员工', + selectAgent: '选择一位员工…', + pageType: '页面类型', + policy: '写策略', + noRows: '该员工暂无权限规则（默认放行）。', + pageTypeHint: '页面类型，* 表示默认', + addRule: '新增规则', + deleteConfirm: '删除 "{type}" 的权限规则？', + }, + watcher: { + tab: '变更监测', + title: '源目录变更监测', + desc: '关联一个本地目录作为知识来源，监测器会按间隔扫描新增/变更文件并自动摄取。也可手动触发一次扫描。', + enabled: '监测开关', + active: '已激活', + interval: '扫描间隔', + sourceType: '源类型', + directory: '源目录', + dirHint: '绝对路径，例如 /data/docs', + availableTypes: '可用源类型', + scanNow: '立即扫描', + scanDone: '扫描完成', + scanResult: '扫描 {scanned} 个，新增 {added}，跳过 {skipped}，错误 {errors}', + }, + pipeline: { + tab: '流水线', + title: '自定义流水线', + desc: '用 YAML 定义触发器（如某类型页面累计到阈值、页面创建）与多步处理（llm / skill）。保存后由后台按触发条件自动执行。', + name: '名称', + trigger: '触发器', + enabled: '启用', + runs: '运行记录', + empty: '暂无流水线定义。', + editor: 'YAML 定义', + editorHint: 'name: my-pipeline\ntrigger:\n type: page_type_count\n page_type: episode\n threshold: 10\nsteps:\n - executor: llm\n prompt: …', + saveDef: '保存定义', + deleteConfirm: '删除流水线 "{name}"？', + runsFor: '"{name}" 的运行记录', + status: '状态', + startedAt: '开始时间', + noRuns: '暂无运行记录。', + }, + }, searchPages: '搜索页面...', dropFiles: '拖拽文件到此处或点击上传', dropToUpload: '松开即开始上传', @@ -2226,6 +2354,19 @@ export default { archivedSection: '已归档', noArchived: '没有已归档的页面', unarchive: '恢复', + lint: { + neverScanned: '尚未扫描死链，点击右侧按钮检查 [[...]] 引用是否仍然有效', + running: '正在扫描死链…', + scanning: '扫描中…', + scan: '扫描死链', + rescan: '重新扫描', + cleanResult: '已扫描 {pages} 个页面，无死链', + brokenSummary: '发现 {refs} 个死链，分布在 {pages} 个页面', + view: '查看', + dismissTitle: '隐藏本次提示', + panelTitle: 'Wiki 死链报告', + noReport: '尚未扫描，请先点击「扫描死链」', + }, pageTypes: { concept: '概念', person: '人物', @@ -3793,10 +3934,82 @@ export default { inlinePromptAccept: '好', inlinePromptDecline: '不用', autoFollowup: '自动延续', + sidebarActive: '此对话有正在进行的目标', completedTitle: '目标达成', completedDetail: '已存入长期记忆，下次问起能找回来', exhaustedTitle: '这次的预算用完了', exhaustedDetailTurns: '预算轮数（{used}/{budget}）用完。', exhaustedDetailLlm: 'LLM 调用预算用完。', }, + approval: { + grant: { + pill: { + inactive: '未启用', + manage: '管理自动批准策略...', + }, + chipLabel: '自动批准已启用 ({count})', + chipShort: '自动批准 {count}', + menu: '自动批准', + title: '自动批准策略', + desc: '策略让特定工具调用跳过人审。地板规则（如 rm -rf /、pipe-to-shell）始终生效，CRITICAL 严重度永远人审。', + scope: { + conversation: '会话', + agent: '智能体', + user: '用户', + workspace: '工作区', + }, + kind: { + always: '永久', + until: '到期失效', + conversationEnd: '会话结束失效', + }, + severityCeiling: '严重度上限', + createBtn: '新增策略', + createWorkspaceBtn: '创建全工具白名单 (危险)', + createWorkspaceWarning: '该策略将允许此工作区内所有用户的所有工具调用自动通过审批。地板规则仍会阻断灾难性命令，但其他风险都将被绕过。请输入登录密码确认。', + revokeBtn: '撤销', + revokeConfirm: '撤销后此策略将不再生效。继续？', + revokeConfirmDetailed: '撤销后 {tool} 的自动批准将不再生效，下次调用会重新走人工审批。继续？', + anyTool: '所有工具', + viewResolutions: '查看本规则触发的 {count} 次自动通过 →', + empty: '尚未配置自动批准策略', + columns: { + scope: '范围', + tool: '工具', + rule: '规则', + severity: '严重度上限', + kind: '类型', + expire: '过期时间', + grantedBy: '创建者', + grantedAt: '创建时间', + note: '备注', + actions: '操作', + }, + form: { + scopeType: '范围类型', + scopeId: '范围 ID', + toolName: '工具名（空 = 任意工具）', + ruleId: '规则 ID（空 = 任意规则）', + maxSeverity: '严重度上限', + grantKind: '生效类型', + expireAt: '过期时间', + note: '备注', + password: '登录密码（敏感策略需要）', + }, + }, + resolution: { + source: { + userManual: '人工审批', + autoGrant: '自动批准', + hardBlock: '安全地板阻断', + timeout: '审批超时', + }, + }, + hardBlock: { + banner: '此命令命中安全地板，任何模式下都不可执行。', + }, + forceHuman: { + banner: '此命令需要人工审批，自动批准策略对其不生效。', + }, + }, } as const diff --git a/mateclaw-ui/src/router/index.ts b/mateclaw-ui/src/router/index.ts index 5b357441..1af9a89a 100644 --- a/mateclaw-ui/src/router/index.ts +++ b/mateclaw-ui/src/router/index.ts @@ -265,6 +265,12 @@ const router = createRouter({ component: () => import('@/views/Security/AuditLogs/index.vue'), meta: { title: 'Security - Audit Logs', requiredCapability: 'manage:security' }, }, + { + path: 'auto-approve', + name: 'SecurityAutoApprove', + component: () => import('@/views/Security/AutoApproveGrants/index.vue'), + meta: { title: 'Security - Auto Approve', requiredCapability: 'manage:security' }, + }, ], }, // ==================== Forbidden ==================== diff --git a/mateclaw-ui/src/stores/useGoalStore.ts b/mateclaw-ui/src/stores/useGoalStore.ts index 137adc5e..63f0f27d 100644 --- a/mateclaw-ui/src/stores/useGoalStore.ts +++ b/mateclaw-ui/src/stores/useGoalStore.ts @@ -94,7 +94,7 @@ export const useGoalStore = defineStore('goal', () => { agentId: string, workspaceId: string, title: string, - opts: { description?: string; exitCriteria?: string; autoFollowup?: boolean } = {}, + opts: { description?: string; exitCriteria?: string; autoFollowup?: boolean; criteria?: string[] } = {}, ): Promise<Goal | null> { try { const res: any = await goalApi.create({ @@ -105,6 +105,7 @@ export const useGoalStore = defineStore('goal', () => { description: opts.description, exitCriteria: opts.exitCriteria, autoFollowupEnabled: opts.autoFollowup, + criteria: opts.criteria?.map((text) => ({ text })), }) const goal: Goal = res?.data activeGoalByConv.value[conversationId] = goal @@ -170,11 +171,14 @@ export const useGoalStore = defineStore('goal', () => { case 'goal_evaluated': { evaluatingByConv.value[conversationId] = false lastTerminalEventAtByConv.value[conversationId] = Date.now() - if (goal && data?.score != null) { - goal.completionScore = Number(data.score) - } - if (goal && typeof data?.gap === 'string') { - goal.progressSummary = data.gap + // Prefer the full goal snapshot (carries the criteria array + score); + // fall back to patching the cached goal for older payload shapes. + const fresh = data?.goal as Goal | undefined + if (fresh && typeof fresh.id === 'string') { + activeGoalByConv.value[conversationId] = fresh + } else if (goal) { + if (data?.score != null) goal.completionScore = Number(data.score) + if (typeof data?.gap === 'string') goal.progressSummary = data.gap } break } @@ -185,6 +189,11 @@ export const useGoalStore = defineStore('goal', () => { // its evaluating state until message_complete fires for that // followup turn — so the user sees breathe → still → breathe. pendingFollowupByConv.value[conversationId] = true + // The followup payload carries the latest criteria progress. + const fresh = data?.goal as Goal | undefined + if (fresh && typeof fresh.id === 'string') { + activeGoalByConv.value[conversationId] = fresh + } break } case 'goal_completed': { @@ -269,10 +278,24 @@ export const useGoalStore = defineStore('goal', () => { function progressFraction(conversationId: string): number | null { const g = activeGoal(conversationId) - if (!g || g.completionScore == null) return null + if (!g) return null + // Prefer the deterministic checklist (passed / total) when present; + // fall back to the evaluator's completion score otherwise. + if (g.criteria && g.criteria.length > 0) { + const passed = g.criteria.filter((c) => c.passed).length + return passed / g.criteria.length + } + if (g.completionScore == null) return null return Math.max(0, Math.min(1, g.completionScore)) } + /** Checklist progress as { passed, total } when a checklist exists. */ + function criteriaProgress(conversationId: string): { passed: number; total: number } | null { + const g = activeGoal(conversationId) + if (!g || !g.criteria || g.criteria.length === 0) return null + return { passed: g.criteria.filter((c) => c.passed).length, total: g.criteria.length } + } + // ==================== Inline prompt + system line helpers ==================== function isPromptDismissed(conversationId: string): boolean { @@ -349,6 +372,7 @@ export const useGoalStore = defineStore('goal', () => { isEvaluating, activeGoal, progressFraction, + criteriaProgress, isPromptDismissed, dismissPrompt, clearDismissedPrompt, diff --git a/mateclaw-ui/src/stores/useWikiStore.ts b/mateclaw-ui/src/stores/useWikiStore.ts index df0d5a62..08e7f84a 100644 --- a/mateclaw-ui/src/stores/useWikiStore.ts +++ b/mateclaw-ui/src/stores/useWikiStore.ts @@ -63,6 +63,52 @@ export function isProtectedPage(page: WikiPage | null | undefined): boolean { return page.locked === 1 } +/** + * Lightweight {slug, title, archived} entry used to resolve `[[...]]` wikilinks + * in rendered wiki content. Distinct from {@link WikiPage} — pageRefs are never + * filtered by the user's raw-material selection and never carry content, so the + * renderer can always trust them as the authoritative resolution index for the + * active knowledge base. + */ +export interface WikiPageRef { + slug: string + title: string + archived: boolean +} + +/** Per-page row in a broken-links report. */ +export interface WikiBrokenLinkPage { + // Snowflake — stay as string end-to-end. + pageId: string + slug: string + title: string + brokenRefs: string[] +} + +/** Aggregate response from GET /lint/broken-links. */ +export interface WikiBrokenLinksReport { + kbId: number | string + jobId: string | null + completedAt: string | null + totalPages: number + pagesWithBrokenLinks: number + totalBrokenRefs: number + pages: WikiBrokenLinkPage[] +} + +/** Job envelope returned by POST /lint/broken-links. */ +export interface WikiLintJob { + jobId: string + kbId: number | string + status: 'queued' | 'running' | 'completed' | 'failed' + startedAt: string + completedAt: string | null + totalPages: number + pagesWithBrokenLinks: number + totalBrokenRefs: number + errorMessage?: string +} + export const useWikiStore = defineStore('wiki', () => { const knowledgeBases = ref<WikiKB[]>([]) const currentKB = ref<WikiKB | null>(null) @@ -75,6 +121,26 @@ export const useWikiStore = defineStore('wiki', () => { const selectedRawId = ref<number | null>(null) const totalPageCount = ref(0) + // Wikilink resolution index — kept separate from `pages` because (a) it must + // survive the raw-material filter, and (b) the viewer's postprocess needs an + // O(1) slug/title lookup over the full KB. `archivedPageRefs` is only loaded + // on demand: most pages don't reference archived targets, and asking for them + // by default would let archived slugs leak into the active resolution map. + const pageRefs = ref<WikiPageRef[]>([]) + const archivedPageRefs = ref<WikiPageRef[]>([]) + + // Broken-link lint state. `brokenLinksReport` holds the latest aggregate + // server response; `brokenLinksJob` tracks the in-flight scan job (null + // when nothing is running or after the last scan settled). Both are + // scoped to currentKB — clear in selectKB / backToLibrary so KB switching + // doesn't bleed stale data across knowledge bases. + const brokenLinksReport = ref<WikiBrokenLinksReport | null>(null) + const brokenLinksJob = ref<WikiLintJob | null>(null) + const brokenLinksLoading = ref(false) + // Track the timer id so a second startBrokenLinksScan call cancels the + // stale poller — avoids double-fires after rapid clicks. + let brokenLinksPollTimer: ReturnType<typeof setInterval> | null = null + async function fetchKnowledgeBases() { loading.value = true try { @@ -90,7 +156,20 @@ export const useWikiStore = defineStore('wiki', () => { async function selectKB(id: number) { const res: any = await wikiApi.getKB(id) currentKB.value = res.data || res - await Promise.all([fetchRawMaterials(id), fetchPages(id)]) + // pageRefs refresh in parallel with materials + pages — the viewer needs + // the resolution index ready before it tries to postprocess wikilinks. + archivedPageRefs.value = [] + // Clear stale broken-links state from the previous KB; the report fetch + // below repopulates it (or leaves it null if no scan has run on this KB). + brokenLinksReport.value = null + brokenLinksJob.value = null + if (brokenLinksPollTimer) { clearInterval(brokenLinksPollTimer); brokenLinksPollTimer = null } + await Promise.all([ + fetchRawMaterials(id), + fetchPages(id), + fetchPageRefs(id), + loadBrokenLinksReport(id), + ]) } async function createKB(data: { name: string; description?: string; agentId?: number }) { @@ -115,6 +194,12 @@ export const useWikiStore = defineStore('wiki', () => { currentPage.value = null rawMaterials.value = [] pages.value = [] + pageRefs.value = [] + archivedPageRefs.value = [] + brokenLinksReport.value = null + brokenLinksJob.value = null + if (brokenLinksPollTimer) { clearInterval(brokenLinksPollTimer); brokenLinksPollTimer = null } + brokenLinksLoading.value = false selectedRawId.value = null } @@ -129,6 +214,103 @@ export const useWikiStore = defineStore('wiki', () => { if (!rawId) totalPageCount.value = pages.value.length } + /** + * Fetch the active (non-archived) wikilink resolution index. Called on KB + * switch and from {@link refreshCurrentKB} so the viewer always has a fresh + * map. `archivedPageRefs` is left alone — call {@link fetchArchivedPageRefs} + * lazily if the viewer detects a link pointing at a possibly archived target. + */ + async function fetchPageRefs(kbId: number) { + const res: any = await wikiApi.listPageRefs(kbId, false) + pageRefs.value = (res.data?.items ?? res.items ?? []) as WikiPageRef[] + } + + /** + * Lazily fetch archived refs so the viewer can label existing links to + * archived targets without polluting the default resolution map (which would + * otherwise let LLM-generated content keep pointing at retired pages). + */ + async function fetchArchivedPageRefs(kbId: number) { + if (archivedPageRefs.value.length > 0) return + const res: any = await wikiApi.listPageRefs(kbId, true) + const all = (res.data?.items ?? res.items ?? []) as WikiPageRef[] + archivedPageRefs.value = all.filter((p) => p.archived) + } + + /** + * Load the latest broken-links report for the active KB. Treats HTTP 404 + * ("no scan yet") as an expected empty state rather than an error — the + * caller decides whether to surface "click scan" UX. + */ + async function loadBrokenLinksReport(kbId: number) { + try { + const res: any = await wikiApi.getBrokenLinksReport(kbId) + brokenLinksReport.value = (res.data ?? res) as WikiBrokenLinksReport + } catch (e: any) { + if (e?.response?.status === 404 || e?.code === 404) { + brokenLinksReport.value = null + } else { + console.error('[Wiki] Failed to load broken-links report', e) + } + } + } + + /** + * Start (or rejoin) a broken-links scan job and poll the aggregate + * endpoint until completedAt advances past the job's startedAt. Updates + * `brokenLinksJob` for in-flight UX and `brokenLinksReport` once the + * server confirms completion. Returns when polling resolves or aborts. + */ + async function startBrokenLinksScan(kbId: number) { + if (brokenLinksPollTimer) { + clearInterval(brokenLinksPollTimer) + brokenLinksPollTimer = null + } + brokenLinksLoading.value = true + try { + const res: any = await wikiApi.startBrokenLinksScan(kbId) + const job = (res.data ?? res) as WikiLintJob + brokenLinksJob.value = job + // If POST returned an already-completed job (e.g. instant scan on tiny + // KB), refresh the aggregate immediately and skip polling. + if (job.status === 'completed' || job.status === 'failed') { + await loadBrokenLinksReport(kbId) + brokenLinksLoading.value = false + return job + } + // Otherwise poll the aggregate every 2s. Authoritative "is this done" + // signal is completedAt > startedAt — the job state in memory is + // refreshed alongside for failure surfacing. + const startedAt = job.startedAt + brokenLinksPollTimer = setInterval(async () => { + try { + await loadBrokenLinksReport(kbId) + const report = brokenLinksReport.value + if (report?.completedAt && (!startedAt || report.completedAt >= startedAt)) { + if (brokenLinksPollTimer) clearInterval(brokenLinksPollTimer) + brokenLinksPollTimer = null + brokenLinksJob.value = null + brokenLinksLoading.value = false + } + } catch (e) { + console.error('[Wiki] Polling broken-links scan failed', e) + } + }, 2000) + // Hard timeout — give up tracking after 5 minutes; user can re-trigger. + setTimeout(() => { + if (brokenLinksPollTimer) { + clearInterval(brokenLinksPollTimer) + brokenLinksPollTimer = null + brokenLinksLoading.value = false + } + }, 5 * 60 * 1000) + return job + } catch (e) { + brokenLinksLoading.value = false + throw e + } + } + // Background refreshes (job completion, SSE events, fallback polling) must // not drop the user's active raw-material filter. Re-fetch the page list // scoped to selectedRawId whenever a filter is applied — otherwise the list @@ -141,6 +323,9 @@ export const useWikiStore = defineStore('wiki', () => { wikiApi.getKB(kbId), fetchRawMaterials(kbId), fetchPages(kbId, selectedRawId.value ?? undefined), + // Keep refs in lockstep with the rest of the KB state so a freshly + // created page is immediately resolvable by the viewer. + fetchPageRefs(kbId), ]) const nextKB = (kbRes as any).data || kbRes currentKB.value = nextKB @@ -209,6 +394,11 @@ export const useWikiStore = defineStore('wiki', () => { loading, selectedRawId, totalPageCount, + pageRefs, + archivedPageRefs, + brokenLinksReport, + brokenLinksJob, + brokenLinksLoading, fetchKnowledgeBases, selectKB, createKB, @@ -216,6 +406,10 @@ export const useWikiStore = defineStore('wiki', () => { backToLibrary, fetchRawMaterials, fetchPages, + fetchPageRefs, + fetchArchivedPageRefs, + loadBrokenLinksReport, + startBrokenLinksScan, refreshCurrentKB, filterPagesByRaw, clearRawFilter, diff --git a/mateclaw-ui/src/types/index.ts b/mateclaw-ui/src/types/index.ts index 1a14dde9..dfdec8c2 100644 --- a/mateclaw-ui/src/types/index.ts +++ b/mateclaw-ui/src/types/index.ts @@ -43,6 +43,22 @@ export interface Agent { enabled: boolean icon?: string tags?: string + workspaceBasePath?: string | null + /** Agent-level primary wiki KB. Null means use workspace fallback. */ + primaryKbId?: string | number | null + /** + * Explicit opt-out: drop every SKILL.md catalog entry from the system + * prompt and exclude skill-expanded tools. Independent of binding rows + * (when `true`, the agent is treated as "no skills" regardless of any + * leftover `mate_agent_skill` rows). Defaults to `false`. + */ + skillsDisabled?: boolean + /** + * Explicit opt-out: exclude every non-system-level tool from the agent's + * effective set and suppress MCP auto-include. System-level memory and + * delegation primitives still pass through. Defaults to `false`. + */ + toolsDisabled?: boolean createTime?: string updateTime?: string } @@ -1005,3 +1021,92 @@ export interface CronJob { lastDeliveryStatus?: 'NONE' | 'PENDING' | 'DELIVERED' | 'NOT_DELIVERED' lastDeliveryError?: string | null } + +// ==================== Approval Auto-Grant ==================== + +export type GrantScope = 'USER' | 'AGENT' | 'CONVERSATION' | 'WORKSPACE' +export type GrantKind = 'ALWAYS' | 'UNTIL_TIMESTAMP' | 'UNTIL_CONVERSATION_END' +export type GrantSeverity = 'LOW' | 'MEDIUM' | 'HIGH' +export type ResolutionDecisionSource = 'USER_MANUAL' | 'AUTO_GRANT' | 'HARD_BLOCK' | 'TIMEOUT' + +/** + * A user-authorized rule that lets ApprovalGrantResolver skip the manual + * approval step for matching tool calls. All snowflake-typed fields are + * strings end-to-end per CLAUDE.md precision convention. + */ +export interface ApprovalGrant { + id: string + workspaceId: string + scopeType: GrantScope + scopeId: string + toolName: string | null + ruleId: string | null + maxSeverity: GrantSeverity + grantKind: GrantKind + expireAt: string | null + grantedBy: string + /** Display name (nickname → username) of the granter; null if the user was deleted. */ + grantedByName?: string | null + grantedAt: string + revoked: number + revokedBy: string | null + revokedAt: string | null + note: string | null +} + +/** Active-grant summary for the global chip + ChatInput pill counters. */ +export interface ActiveGrantsSummary { + count: number + hasWorkspaceWide: boolean +} + +/** + * Paged response shape from /approval/grants. Mirrors the MyBatis Plus + * {@code IPage} JSON layout already used by skills and other paged endpoints in + * mateclaw. {@code total/size/current/pages} arrive as JSON strings because the + * global Long→String serializer catches them; the consumer coerces via + * {@code Number(...)} at the use site so the el-pagination component gets numbers. + */ +export interface ApprovalGrantPage { + records: ApprovalGrant[] + total: number | string + size: number | string + current: number | string + pages: number | string +} + +/** + * Approval-layer final decision row. workspaceId can be null for HARD_BLOCK + * events that fired before workspace resolution. + */ +export interface ResolutionLog { + id: string + workspaceId: string | null + conversationId: string | null + agentId: string | null + userId: string | null + toolCallId: string | null + toolName: string + maxSeverity: GrantSeverity | null + ruleIds: string | null + decisionSource: ResolutionDecisionSource + grantId: string | null + pendingId: string | null + argsPreview: string | null + note: string | null + createTime: string +} + +/** Payload for POST /approval/grants. */ +export interface CreateGrantPayload { + scopeType: GrantScope + scopeId: string + toolName?: string | null + ruleId?: string | null + maxSeverity: GrantSeverity + grantKind: GrantKind + expireAt?: string | null + note?: string | null + /** Required when scope+toolName combination is admin+password (see §2.4.5). */ + password?: string +} diff --git a/mateclaw-ui/src/views/Agents.vue b/mateclaw-ui/src/views/Agents.vue index a705a639..b561c280 100644 --- a/mateclaw-ui/src/views/Agents.vue +++ b/mateclaw-ui/src/views/Agents.vue @@ -209,16 +209,26 @@ </button> <button v-if="editingAgent" class="modal-tab" :class="{ active: modalTab === 'skills' }" @click="modalTab = 'skills'"> {{ t('agents.tabs.skills', 'Skills') }} - <span v-if="selectedSkillIds.length" class="tab-badge">{{ selectedSkillIds.length }}</span> + <!-- Issue #184: when the disable flag is on, suppress the + stale-pick count badge and show an "off" state instead — + the count would otherwise contradict the disable toggle + visible in the tab content. --> + <span v-if="form.skillsDisabled" class="tab-badge tab-badge--off">{{ t('agents.binding.disableAllSkillsBadge') }}</span> + <span v-else-if="selectedSkillIds.length" class="tab-badge">{{ selectedSkillIds.length }}</span> </button> <button v-if="editingAgent" class="modal-tab" :class="{ active: modalTab === 'tools' }" @click="modalTab = 'tools'"> {{ t('agents.tabs.tools', 'Tools') }} - <span v-if="selectedToolNames.length" class="tab-badge">{{ selectedToolNames.length }}</span> + <span v-if="form.toolsDisabled" class="tab-badge tab-badge--off">{{ t('agents.binding.disableAllToolsBadge') }}</span> + <span v-else-if="selectedToolNames.length" class="tab-badge">{{ selectedToolNames.length }}</span> </button> <button v-if="editingAgent" class="modal-tab" :class="{ active: modalTab === 'providers' }" @click="modalTab = 'providers'"> {{ t('agents.tabs.providers', 'Providers') }} <span v-if="selectedProviderIds.length" class="tab-badge">{{ selectedProviderIds.length }}</span> </button> + <button v-if="editingAgent" class="modal-tab" :class="{ active: modalTab === 'wiki' }" @click="modalTab = 'wiki'"> + {{ t('agents.tabs.wiki', 'Wiki') }} + <span v-if="selectedKBId" class="tab-badge">1</span> + </button> </div> <!-- Basic Tab --> @@ -271,6 +281,11 @@ <option value="max">{{ t('agents.thinkingLevels.max') }}</option> </select> </div> + <div class="form-group full-width"> + <label class="form-label">{{ t('agents.fields.workspaceBasePath') }}</label> + <input v-model="form.workspaceBasePath" class="form-input" :placeholder="t('agents.placeholders.workspaceBasePath')" /> + <p class="form-hint">{{ t('agents.fields.workspaceBasePathHint') }}</p> + </div> <!-- Identity triad: role + goal + backstory map to H2 sections in the stored systemPrompt. The card tagline is derived from @@ -328,24 +343,55 @@ <span class="binding-intro__kicker">{{ t('agents.binding.skillsKicker') }}</span> <p class="binding-intro__tagline">{{ t('agents.binding.skillsTagline') }}</p> </div> + <!-- Issue #184: explicit "no skills" toggle. Empty selection + alone falls back to "inherit global default" (legacy + contract), so users who want zero skills in the context + need this dedicated bit. --> + <div class="binding-disable-row"> + <label class="binding-disable-label"> + <input type="checkbox" v-model="form.skillsDisabled" class="binding-disable-checkbox" /> + <span class="binding-disable-text"> + <strong>{{ t('agents.binding.disableAllSkills') }}</strong> + <span class="binding-disable-hint">{{ t('agents.binding.disableAllSkillsHint') }}</span> + </span> + </label> + </div> <p class="binding-hint">{{ t('agents.binding.skillsHint') }}</p> <div v-if="availableSkills.length === 0" class="binding-empty">{{ t('agents.binding.noSkills') }}</div> <template v-else> - <div class="binding-search"> + <div class="binding-search" :class="{ 'binding-search--disabled': form.skillsDisabled }"> <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"> <circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/> </svg> - <input v-model="skillBindingSearch" :placeholder="t('agents.binding.searchSkills')" /> + <input v-model="skillBindingSearch" :placeholder="t('agents.binding.searchSkills')" :disabled="form.skillsDisabled" /> </div> <div v-if="filteredAvailableSkills.length === 0" class="binding-empty binding-empty--compact">{{ t('agents.binding.noMatchingSkills') }}</div> - <div v-else class="binding-list"> + <div v-else class="binding-list" :class="{ 'binding-list--disabled': form.skillsDisabled }"> <label v-for="skill in filteredAvailableSkills" :key="skill.id" class="binding-item" - :class="{ selected: selectedSkillIds.includes(skill.id) }" + :class="{ + selected: !form.skillsDisabled && selectedSkillIds.includes(skill.id), + 'binding-item--inert': form.skillsDisabled, + }" > - <input type="checkbox" :value="skill.id" v-model="selectedSkillIds" class="binding-checkbox" /> + <!-- Manual :checked instead of v-model: when skillsDisabled + is on, the stale picks still live in selectedSkillIds + (we keep them so flipping the toggle back off restores + the previous selection in one click). Driving the + checkbox from a derived expression lets us hide the + stale checked state from the user without mutating + the underlying array. The save path already clears + the array on send when the flag is on. --> + <input + type="checkbox" + :value="skill.id" + :checked="!form.skillsDisabled && selectedSkillIds.includes(skill.id)" + @change="onSkillToggle(skill.id, $event)" + class="binding-checkbox" + :disabled="form.skillsDisabled" + /> <span class="binding-icon"><SkillIcon :value="skill.icon" :size="20" :fallback="'🧩'" /></span> <div class="binding-info"> <span class="binding-name">{{ resolveSkillName(skill) }}</span> @@ -366,13 +412,30 @@ <span class="binding-intro__kicker">{{ t('agents.binding.toolsKicker') }}</span> <p class="binding-intro__tagline">{{ t('agents.binding.toolsTagline') }}</p> </div> - <details class="advanced-tools" :open="selectedToolNames.length > 0 || advancedToolsOpen"> + <!-- Issue #184 mirror of the skills tab: explicit opt-out so the + LLM advertises zero user-pickable tools (system-level + memory primitives still pass — see backend SYSTEM_LEVEL_TOOLS). --> + <div class="binding-disable-row"> + <label class="binding-disable-label"> + <input type="checkbox" v-model="form.toolsDisabled" class="binding-disable-checkbox" /> + <span class="binding-disable-text"> + <strong>{{ t('agents.binding.disableAllTools') }}</strong> + <span class="binding-disable-hint">{{ t('agents.binding.disableAllToolsHint') }}</span> + </span> + </label> + </div> + <!-- Issue #184: when the disable flag is on, treat the count as + zero for visual affordances — auto-open / count badge / chevron + should all behave as if there are no picks, matching the + "saving clears bindings" contract. The underlying array is + left intact so toggling the flag back off restores them. --> + <details class="advanced-tools" :open="(!form.toolsDisabled && selectedToolNames.length > 0) || advancedToolsOpen"> <summary class="advanced-tools-summary" @click.prevent="advancedToolsOpen = !advancedToolsOpen"> <span class="advanced-tools-title"> {{ t('agents.binding.advancedToolsTitle') }} - <span v-if="selectedToolNames.length > 0" class="advanced-tools-count">{{ selectedToolNames.length }}</span> + <span v-if="!form.toolsDisabled && selectedToolNames.length > 0" class="advanced-tools-count">{{ selectedToolNames.length }}</span> </span> - <span class="advanced-tools-chevron">{{ (advancedToolsOpen || selectedToolNames.length > 0) ? '▾' : '▸' }}</span> + <span class="advanced-tools-chevron">{{ (advancedToolsOpen || (!form.toolsDisabled && selectedToolNames.length > 0)) ? '▾' : '▸' }}</span> </summary> <p class="binding-hint">{{ t('agents.binding.toolsHint') }}</p> <p class="binding-hint advanced-tools-note">{{ t('agents.binding.advancedToolsHint') }}</p> @@ -418,9 +481,10 @@ :key="tool.rowId || `${group.groupId}#${tool.rawName}#${tool.name}`" class="binding-item" :class="{ - selected: tool._isSelected, + selected: !form.toolsDisabled && tool._isSelected, 'binding-item--stale': tool.stale, 'binding-item--unavailable': !tool.available, + 'binding-item--inert': form.toolsDisabled, }" :title="!tool.available ? t('agents.binding.toolUnavailableTooltip', { reason: tool.unavailableReason || '' }) @@ -432,12 +496,17 @@ both, so we drive each row's checked flag from the pre-computed _isSelected derived in availableToolGroups, which considers whether - this row's name is owned by a bindable twin. --> + this row's name is owned by a bindable twin. + Issue #184: gate visual checked-state on the + disable flag so stale picks don't show through + when "this agent uses no user-pickable tools" + is on. selectedToolNames is preserved so flipping + the toggle back off restores the prior selection. --> <input type="checkbox" class="binding-checkbox" - :checked="tool._isSelected" - :disabled="tool._isDisabled" + :checked="!form.toolsDisabled && tool._isSelected" + :disabled="tool._isDisabled || form.toolsDisabled" @change="onToolToggle(tool.name, $event)" /> <span class="binding-icon"> @@ -487,6 +556,43 @@ >+ {{ p.name }}</button> </div> </div> + + <!-- Wiki / Knowledge Base Tab --> + <div v-if="modalTab === 'wiki'" class="binding-tab"> + <div class="binding-intro"> + <span class="binding-intro__kicker">{{ t('agents.binding.wikiKicker') }}</span> + <p class="binding-intro__tagline">{{ t('agents.binding.wikiTagline') }}</p> + </div> + <p class="binding-hint">{{ t('agents.binding.wikiHint') }}</p> + <div v-if="availableKBs.length === 0" class="binding-empty">{{ t('agents.binding.noKBs') }}</div> + <div v-else class="binding-list"> + <label + class="binding-item" + :class="{ selected: selectedKBId === null }" + > + <input type="radio" name="kb-select" :checked="selectedKBId === null" class="binding-checkbox" @change="selectedKBId = null" /> + <span class="binding-icon">🚫</span> + <div class="binding-info"> + <span class="binding-name">{{ t('agents.binding.noKB') }}</span> + </div> + </label> + <label + v-for="kb in availableKBs" + :key="kb.id" + class="binding-item" + :class="{ selected: selectedKBId === String(kb.id) }" + > + <input type="radio" name="kb-select" :checked="selectedKBId === String(kb.id)" class="binding-checkbox" @change="selectedKBId = String(kb.id)" /> + <span class="binding-icon">📚</span> + <div class="binding-info"> + <span class="binding-name">{{ kb.name }}</span> + <span v-if="kb.description" class="binding-desc">{{ kb.description?.slice(0, 80) }}</span> + </div> + <!-- binding-version class reused for pageCount badge (same positioning as skill version) --> + <span v-if="kb.pageCount != null" class="binding-version">{{ t('agents.binding.wikiPages', { count: kb.pageCount }, `${kb.pageCount} pages`) }}</span> + </label> + </div> + </div> </div> <div class="modal-footer"> <button class="btn-secondary" @click="closeModal">{{ t('common.cancel') }}</button> @@ -505,7 +611,7 @@ import { useRoute, useRouter } from 'vue-router' import { useI18n } from 'vue-i18n' import { mcToast } from '@/composables/useMcToast' import { mcConfirm } from '@/components/common/useConfirm' -import { agentApi, agentBindingApi, modelApi, skillApi, toolApi, templateApi, liveApi } from '@/api/index' +import { agentApi, agentBindingApi, modelApi, skillApi, toolApi, templateApi, liveApi, wikiApi } from '@/api/index' import type { Agent } from '@/types/index' import SkillIcon from '@/components/common/SkillIcon.vue' import SkillIconPicker from '@/components/common/SkillIconPicker.vue' @@ -532,7 +638,7 @@ const searchText = ref('') const activeFilter = ref('all') const showModal = ref(false) const editingAgent = ref<Agent | null>(null) -const modalTab = ref<'basic' | 'skills' | 'tools' | 'providers'>('basic') +const modalTab = ref<'basic' | 'skills' | 'tools' | 'providers' | 'wiki'>('basic') /** RFC-090 §9.2 调整 B — Tool picker is an Advanced bypass; collapsed by * default but stays open as soon as the agent has any direct tool * bindings, so existing users don't lose visibility on their picks. */ @@ -667,8 +773,29 @@ function onToolToggle(toolName: string, event: Event) { selectedToolNames.value = selectedToolNames.value.filter((n) => n !== toolName) } } + +/** + * Skill checkbox handler. Issue #184 — the row is driven by an explicit + * {@code :checked} expression instead of {@code v-model} so the visual + * checked state can be suppressed when {@code skillsDisabled} is on + * without dropping the picks from {@code selectedSkillIds}. Toggling + * the disable flag back off restores the prior selection in one click. + */ +function onSkillToggle(skillId: number | string, event: Event) { + const target = event.target as HTMLInputElement + if (target.checked) { + if (!selectedSkillIds.value.includes(skillId as number)) { + selectedSkillIds.value.push(skillId as number) + } + } else { + selectedSkillIds.value = selectedSkillIds.value.filter((id) => id !== skillId) + } +} const selectedSkillIds = ref<number[]>([]) const selectedToolNames = ref<string[]>([]) +// Agent-level primary wiki KB. KB visibility remains workspace-wide. +const availableKBs = ref<any[]>([]) +const selectedKBId = ref<string | null>(null) // RFC-009 PR-3: per-agent provider preference order const availableProviders = ref<{ id: string; name: string }[]>([]) const selectedProviderIds = ref<string[]>([]) @@ -703,6 +830,14 @@ const defaultForm = (): Partial<Agent> & { name: string; defaultThinkingLevel: s tags: '', enabled: true, defaultThinkingLevel: null, + // Agent type declares this as `string | undefined`; using `undefined` keeps + // the Partial<Agent> shape happy without widening the type to allow null. + workspaceBasePath: undefined, + primaryKbId: null, + // Issue #184 — explicit opt-out flags. Default false matches the legacy + // "zero rows = inherit global default" contract for newly-created agents. + skillsDisabled: false, + toolsDisabled: false, }) const form = ref(defaultForm()) @@ -824,6 +959,8 @@ function openBlankCreateModal() { selectedSkillIds.value = [] selectedToolNames.value = [] selectedProviderIds.value = [] + availableKBs.value = [] + selectedKBId.value = null showModal.value = true } @@ -890,6 +1027,10 @@ async function openEditModal(agent: Agent) { tags: agent.tags || '', enabled: agent.enabled, defaultThinkingLevel: (agent as any).defaultThinkingLevel || null, + workspaceBasePath: agent.workspaceBasePath || undefined, + primaryKbId: agent.primaryKbId != null ? String(agent.primaryKbId) : null, + skillsDisabled: agent.skillsDisabled === true, + toolsDisabled: agent.toolsDisabled === true, } profileForm.value = parsePrompt(agent.systemPrompt) modalTab.value = 'basic' @@ -929,7 +1070,20 @@ async function openEditModal(agent: Agent) { .filter((b: any) => b.enabled) .map((b: any) => b.providerId) } catch { - // Non-blocking: binding data load failure doesn't prevent editing basic info + mcToast.error(t('agents.messages.loadFailed')) + } + + // KB request is caught separately so its error message is accurate. + try { + const kbsRes: any = await wikiApi.listBindableKBs() + const bindableKBs = (kbsRes.data || []) as any[] + availableKBs.value = bindableKBs + const primaryKbId = agent.primaryKbId != null ? String(agent.primaryKbId) : null + selectedKBId.value = primaryKbId && bindableKBs.some((kb: any) => String(kb.id) === primaryKbId) + ? primaryKbId + : null + } catch { + mcToast.error(t('agents.binding.wikiLoadFailed')) } } @@ -938,6 +1092,8 @@ function closeModal() { editingAgent.value = null skillBindingSearch.value = '' toolBindingSearch.value = '' + availableKBs.value = [] + selectedKBId.value = null } async function saveAgent() { @@ -946,7 +1102,7 @@ async function saveAgent() { // sending to the backend — the schema is unchanged, only the editor // exposes the H2 sections to the user. const serialized = serializePrompt(profileForm.value) - const payload = { ...form.value, systemPrompt: serialized } + const payload = { ...form.value, systemPrompt: serialized, primaryKbId: selectedKBId.value } let agentId: string | number if (editingAgent.value) { @@ -957,13 +1113,44 @@ async function saveAgent() { agentId = res.data?.id } - // Save bindings (only for existing agents or after create returns id) + // Sequential binding saves (issue #184). Two coupled concerns: + // + // 1. Disabled-flag intent must win over stale picks. The opt-out + // toggles only disable the picker visually — selectedSkillIds / + // selectedToolNames keep whatever was previously bound. If we sent + // those stale picks to setSkills/setTools while the flag is on, the + // backend's auto-clear self-heals the flag back to false (because + // "non-empty save = concrete commitment"), and the user's "disable + // everything" intent vanishes silently. So we clear the array here + // before sending — saving [] preserves the flag, and the runtime + // contract ("flag wins over rows") is honored. + // + // 2. Sequential order, not Promise.all. Parallel binding calls would + // leave half-applied state on a partial failure; serial means we + // know exactly which side persisted and can pull the authoritative + // server state back if anything throws. + const skillIdsToSave = form.value.skillsDisabled ? [] : selectedSkillIds.value + const toolNamesToSave = form.value.toolsDisabled ? [] : selectedToolNames.value + if (agentId && editingAgent.value) { - await Promise.all([ - agentBindingApi.setSkills(agentId, selectedSkillIds.value), - agentBindingApi.setTools(agentId, selectedToolNames.value), - agentBindingApi.setProviderPreferences(agentId, selectedProviderIds.value), - ]) + try { + await agentBindingApi.setSkills(agentId, skillIdsToSave) + await agentBindingApi.setTools(agentId, toolNamesToSave) + await agentBindingApi.setProviderPreferences(agentId, selectedProviderIds.value) + } catch (bindingError: any) { + mcToast.error(bindingError?.message || t('agents.messages.saveFailed')) + // Pull the authoritative server state back into the editing form so + // the user sees what actually persisted instead of stale picks. + try { + const fresh: any = await agentApi.get(agentId) + if (fresh?.data) { + await openEditModal(fresh.data) + } + } catch { + // Reload failure on top of binding failure: best effort, stop here. + } + return + } } mcToast.success(t('agents.messages.saveSuccess')) @@ -1288,6 +1475,14 @@ html.dark .seg-count.warn { border-radius: 9px; background: var(--mc-primary); color: white; font-size: 11px; font-weight: 600; } +/* Issue #184: "off" variant for the disable-all state. Neutral grey instead + of brand orange because the badge represents a constraint, not a count. */ +.tab-badge--off { + min-width: auto; padding: 0 8px; + background: var(--mc-bg-sunken, rgba(0,0,0,0.08)); + color: var(--mc-text-tertiary); + border: 1px solid var(--mc-border-light); +} /* Binding Tab */ .binding-tab { min-height: 200px; } @@ -1320,6 +1515,47 @@ html.dark .seg-count.warn { } .binding-empty { padding: 40px; text-align: center; color: var(--mc-text-tertiary); font-size: 14px; } .binding-empty--compact { padding: 24px 12px; } +/* Issue #184 — opt-out row that sits above the picker list. */ +.binding-disable-row { + margin: 0 0 12px; + padding: 12px 14px; + border: 1px dashed var(--mc-border); + border-radius: 8px; + background: var(--mc-bg-sunken); +} +.binding-disable-label { + display: flex; + align-items: flex-start; + gap: 10px; + cursor: pointer; +} +.binding-disable-checkbox { + flex-shrink: 0; + accent-color: var(--mc-primary); + width: 16px; + height: 16px; + margin-top: 2px; +} +.binding-disable-text { + display: flex; + flex-direction: column; + gap: 2px; + font-size: 13px; + color: var(--mc-text-primary); + line-height: 1.4; +} +.binding-disable-text strong { font-weight: 600; } +.binding-disable-hint { + font-size: 12px; + color: var(--mc-text-tertiary); + line-height: 1.5; +} +/* When the opt-out is on, the picker list is still visible (so the user + can see what they're disabling) but rendered inert — no hover affordance, + greyed-out interactions. */ +.binding-search--disabled, +.binding-list--disabled { opacity: 0.45; pointer-events: none; } +.binding-item--inert { cursor: not-allowed; } .binding-search { display: flex; align-items: center; @@ -1355,6 +1591,7 @@ html.dark .seg-count.warn { .binding-info { flex: 1; display: flex; flex-direction: column; gap: 2px; min-width: 0; } .binding-name { font-size: 14px; font-weight: 500; color: var(--mc-text-primary); } .binding-desc { font-size: 12px; color: var(--mc-text-tertiary); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } +/* reused for KB pageCount badge in wiki tab */ .binding-version { font-size: 11px; color: var(--mc-text-tertiary); flex-shrink: 0; } .binding-type-badge { font-size: 10px; padding: 2px 6px; border-radius: 4px; flex-shrink: 0; diff --git a/mateclaw-ui/src/views/ChatConsole.vue b/mateclaw-ui/src/views/ChatConsole.vue index e3d5ab14..454a08b6 100644 --- a/mateclaw-ui/src/views/ChatConsole.vue +++ b/mateclaw-ui/src/views/ChatConsole.vue @@ -116,6 +116,7 @@ @suggestion-click="sendSuggestion" @toggle-thinking="handleToggleThinking" @approve="handleApprove" + @approve-always="handleApproveAlways" @deny="handleDeny" > <!-- Issue #81 v2 R2: blocking-only popup. Recoverable cases use the @@ -216,6 +217,7 @@ v-model="inputText" :loading="isGenerating && !hasPendingApproval" :disabled="blockingPrompt || !currentAgent" + :skills-enabled="!!currentAgent && !currentAgent.skillsDisabled" :placeholder="$t('chat.messagePlaceholder')" :hint="currentRuntimeModel" :attachments="pendingAttachments" @@ -231,6 +233,7 @@ @file-select="handleFileSelect" @attachment-remove="removeAttachment" @approve="handleApprove" + @approve-always="handleApproveAlways" @deny="handleDeny" :enable-talk-mode="!!selectedAgentId" :thinking-enabled="thinkingEnabled" @@ -259,7 +262,8 @@ import { useRoute, useRouter } from 'vue-router' import { useI18n } from 'vue-i18n' import { mcToast } from '@/composables/useMcToast' import { ChatDotRound, Delete, Setting, UploadFilled } from '@element-plus/icons-vue' -import { conversationApi, agentApi, modelApi, chatApi, cronJobApi } from '@/api/index' +import { conversationApi, agentApi, modelApi, chatApi, cronJobApi, approvalApi } from '@/api/index' +import { ElMessage } from 'element-plus' import { copyToClipboard } from '@/utils/clipboard' import { useFileDrop } from '@/composables/useFileDrop' import { useIsMobile, useMediaQuery, BREAKPOINTS } from '@/composables/useBreakpoint' @@ -353,6 +357,12 @@ const selectedAgentId = ref<string | number>('') const currentConversationId = ref<string>('') const inputText = ref('') const modelSaving = ref(false) +// Monotonic counter for in-flight setModel PUTs. The finally handler +// only clears modelSaving when its captured seq is still the latest, so a +// stale-finishing earlier PUT can't unlock the selector while a newer one +// is still in flight, and (crucially) switching conversations mid-PUT +// can't permanently lock the selector by leaving modelSaving stuck true. +let modelSaveSeq = 0 // Issue #81 v2 R2: split the single showModelPrompt boolean into two flags so // the chat surface can either hard-block (blockingPrompt) or warn but let the // backend fallback chain take over (recoverablePrompt). Driven by @@ -418,15 +428,71 @@ function selectModel(value: string) { const [providerId, model] = value.split('::') if (!providerId || !model) return // Per-conversation model: switching here only affects THIS conversation. - // The backend pins it onto the conversation row when the next message is - // sent (see sendChatMessage payload); we also patch the local list entry so - // re-opening the conversation restores the choice without a round-trip. - activeModels.value = { activeLlm: { providerId, model } } + // We update the selector + the local list entry immediately so the UI is + // responsive, then persist the pin to the server right away IF the + // conversation already exists. Without the eager persist, IM channels + // (Feishu / DingTalk / WeCom …) keep using whatever the conversation row + // last had — they don't see the /chat/stream payload that the web path + // pins on send — so the user "switches model in the chat box" but the + // next IM inbound message still picks the old / default model. + // + // Snapshot the previous selection BEFORE the optimistic update so a + // failed PUT can roll the UI back instead of stranding the user with a + // model the backend isn't using. + const prevLlm = activeModels.value?.activeLlm + const prevActive: ActiveModelsInfo | null = prevLlm?.providerId && prevLlm?.model + ? { activeLlm: { providerId: prevLlm.providerId, model: prevLlm.model } } + : null const conv = conversations.value.find(c => c.conversationId === currentConversationId.value) + const prevConvProvider = conv?.modelProvider + const prevConvModel = conv?.modelName + + activeModels.value = { activeLlm: { providerId, model } } if (conv) { conv.modelProvider = providerId conv.modelName = model } + // Only persist when the conversation is already in the server-side list. + // A brand-new chat (newConversation() generated a local id that hasn't + // been sent through /chat/stream yet) has no row to PUT against; that + // case still relies on the first /chat/stream call writing the pin. + if (conv && currentConversationId.value) { + const cid = currentConversationId.value + const mySeq = ++modelSaveSeq + modelSaving.value = true + conversationApi.setModel(cid, providerId, model) + .catch((e: any) => { + console.warn('[ChatConsole] Failed to persist model pin:', e) + mcToast.warning(t('chat.modelSaveFailed')) + // Roll back the visible selector + the cached conv pin so the UI + // doesn't keep claiming a model the backend isn't using. Only do + // it when the user is still on the same conversation AND hasn't + // picked yet another model — otherwise we'd corrupt the more + // recent state with this PUT's snapshot. + const liveConv = conversations.value.find(c => c.conversationId === cid) + if (liveConv && liveConv.modelProvider === providerId && liveConv.modelName === model) { + liveConv.modelProvider = prevConvProvider + liveConv.modelName = prevConvModel + } + if (currentConversationId.value !== cid) return + const stillShowingFailedPick = + activeModels.value?.activeLlm?.providerId === providerId + && activeModels.value?.activeLlm?.model === model + if (!stillShowingFailedPick) return + activeModels.value = prevActive + }) + .finally(() => { + // Only the LATEST in-flight PUT clears the saving flag. An earlier + // PUT finishing late must not flip saving to false while a newer + // one is still pending (the selector would unlock during a live + // request); and a conversation switch mid-PUT must not strand the + // flag at true forever (which would lock the selector across + // every conversation — the original bug this seq counter fixes). + if (mySeq === modelSaveSeq) { + modelSaving.value = false + } + }) + } } /** @@ -441,6 +507,44 @@ function applyConversationModel(conv?: Conversation | null) { } } +/** + * After a poll refreshes the conversation list, the currently-open + * conversation may have drifted server-side: an admin may have rebound the + * channel to a different agent, or pinned a different model via another + * tab / API call. Pull the new server-side state into the local selector + + * agent header so the chat surface doesn't keep claiming the old binding. + * + * Skipped while a turn is generating — yanking the model / agent mid-stream + * would orphan the active SSE subscription. + */ +function reconcileCurrentConversation() { + if (!currentConversationId.value) return + if (isGenerating.value) return + // Don't fight an in-flight setModel write — the poll cycle may run BEFORE + // the PUT lands, in which case the server still reports the old pin and + // we'd flicker the UI back. Wait for the next tick. + if (modelSaving.value) return + const fresh = conversations.value.find(c => c.conversationId === currentConversationId.value) + if (!fresh) return + if (fresh.agentId != null && String(fresh.agentId) !== String(selectedAgentId.value)) { + selectedAgentId.value = fresh.agentId + } + const pickedProvider = activeModels.value?.activeLlm?.providerId + const pickedModel = activeModels.value?.activeLlm?.model + const serverHasPin = !!(fresh.modelProvider && fresh.modelName) + if (serverHasPin) { + if (fresh.modelProvider !== pickedProvider || fresh.modelName !== pickedModel) { + activeModels.value = { activeLlm: { providerId: fresh.modelProvider!, model: fresh.modelName! } } + } + } else if (pickedProvider || pickedModel) { + // Server-side pin was cleared (admin reset, model deleted, …) but the + // local selector still shows the old pick. Drop back to whatever the + // global default resolves to — applyConversationModel does the right + // thing when conv has no pin. + applyConversationModel(fresh) + } +} + // 拖拽上传 — useFileDrop owns the hover/counter state; the directory-aware // payload handling (electron paths vs web FileSystem entries) stays here. const { isDragging, onDragEnter, onDragLeave, onDrop } = useFileDrop(processDroppedItems) @@ -949,6 +1053,7 @@ async function pollActivity() { try { try { await loadConversations() + reconcileCurrentConversation() } catch { // 静默失败，下一轮再试 } @@ -1083,11 +1188,28 @@ const goalSystemLineDetail = computed(() => { return '预算耗尽。' }) +// True when the current conversation's message stream already contains a +// setGoal tool call — authoritative even before the goal_created SSE event +// updates the goal store. +const goalSetInStream = computed(() => { + return messages.value.some((m) => { + if (m.role !== 'assistant') return false + const tcs: any = (m as any).metadata?.toolCalls + return Array.isArray(tcs) && tcs.some((tc: any) => tc?.name === 'setGoal') + }) +}) + const showGoalSetPrompt = computed(() => { if (!currentConversationId.value || !selectedAgentId.value) return false if (isGenerating.value) return false // Active goal? The ring covers that — no need for a prompt. if (goalStore.activeGoal(currentConversationId.value)) return false + // A goal was already set this conversation via the setGoal tool — even if + // the goal_created/goal_evaluated SSE event hasn't updated the store yet + // (the turn can end a render frame before that event lands). Reading the + // stream directly closes that flash window: never offer to set a goal when + // the agent already set one here. + if (goalSetInStream.value) return false // Recent terminal still showing? Let the user dismiss that first. if (goalTerminalForCurrent.value) return false if (goalStore.isPromptDismissed(currentConversationId.value)) return false @@ -1718,6 +1840,57 @@ async function handleDeny(pendingId: string) { await handleSendMessage('/deny') } +// Always-approve: create the matching grant first, then send /approve as usual. +// Failure to create the grant doesn't block the approval — we still forward +// /approve so the user's click isn't lost, just toast the error. +async function handleApproveAlways( + payload: { pendingId: string; scope: 'CONVERSATION' | 'AGENT' | 'USER' }, +) { + if (!currentConversationId.value) return + const pa = activePendingApproval.value + if (!pa) return + + // Resolve scope_id from the scope dimension. + let scopeId = '' + if (payload.scope === 'CONVERSATION') { + scopeId = currentConversationId.value + } else if (payload.scope === 'AGENT') { + scopeId = String(currentAgent.value?.id ?? '') + } else if (payload.scope === 'USER') { + const me = localStorage.getItem('mc-user-id') + if (me) scopeId = me + } + if (!scopeId) { + ElMessage.error('Cannot resolve scope id for always-approve') + await handleSendMessage('/approve') + return + } + + try { + const sev = pa.maxSeverity ?? 'LOW' + // Severity ceiling = at-or-above the current finding's severity. CRITICAL + // never enters this path (the backend rejects it), so HIGH covers the rest. + const ceiling = sev === 'HIGH' || sev === 'CRITICAL' ? 'HIGH' + : sev === 'MEDIUM' ? 'MEDIUM' : 'LOW' + const ruleId = pa.findings?.find((f: { ruleId?: string }) => !!f.ruleId)?.ruleId ?? null + await approvalApi.createGrant({ + scopeType: payload.scope, + scopeId, + toolName: pa.toolName, + ruleId, + maxSeverity: ceiling, + grantKind: payload.scope === 'CONVERSATION' ? 'UNTIL_CONVERSATION_END' : 'ALWAYS', + note: `created from approval banner (${pa.toolName})`, + }) + ElMessage.success( + t('chat.approveAlwaysCreated', { tool: pa.toolName }) as string, + ) + } catch (e: any) { + ElMessage.error(e?.message || 'Failed to create auto-approve rule') + } + await handleSendMessage('/approve') +} + // 重连到运行中的流 async function reconnectStream(conversationId: string) { if (isGenerating.value) return diff --git a/mateclaw-ui/src/views/Memory/components/MemoryBrowser.vue b/mateclaw-ui/src/views/Memory/components/MemoryBrowser.vue index f14cb44a..2b57bcc0 100644 --- a/mateclaw-ui/src/views/Memory/components/MemoryBrowser.vue +++ b/mateclaw-ui/src/views/Memory/components/MemoryBrowser.vue @@ -92,7 +92,10 @@ function parseSections(content: string): MemorySectionData[] { if (match) { const heading = match[1].trim() const rawBody = match[2].trim() - const userEdited = rawBody.includes('<!-- user-edited') + // `\x3c` escapes the `<` so Vite's esbuild dep-scan doesn't treat + // the embedded `<!-- ... -->` sequence as an HTML-like line comment + // and conflate this string literal with the one in stripMarker below. + const userEdited = rawBody.includes('\x3c!-- user-edited') // Strip the hidden marker from the display body — it is metadata, and // since renderMarkdown escapes HTML it would otherwise show as raw text. result.push({ heading, body: stripMarker(rawBody), userEdited }) @@ -107,7 +110,8 @@ function parseSections(content: string): MemorySectionData[] { // Strip the hidden user-edited marker so it never shows up as raw text in the // editor (and never accumulates when a section is edited repeatedly). function stripMarker(body: string): string { - return body.replace(/^[ \t]*<!-- user-edited:.*-->[ \t]*$/gm, '').trim() + // `\x3c` escape — same reason as in parseSections above. + return body.replace(/^[ \t]*\x3c!-- user-edited:.*-->[ \t]*$/gm, '').trim() } /** diff --git a/mateclaw-ui/src/views/Security/AutoApproveGrants/index.vue b/mateclaw-ui/src/views/Security/AutoApproveGrants/index.vue new file mode 100644 index 00000000..4334d628 --- /dev/null +++ b/mateclaw-ui/src/views/Security/AutoApproveGrants/index.vue @@ -0,0 +1,849 @@ +<template> + <div class="settings-section"> + <!-- + Header layout follows the McpServers / ToolGuard style: section-header + container with btn-secondary / btn-primary native buttons on the right. + Icons come from @element-plus/icons-vue per the user's directive, even + though the rest of the page uses native CSS buttons — el-icon renders + inline cleanly inside a regular button. + + The three actions deliberately sit at different visual weights: + - btn-primary "新增策略" → the daily action, dominant. + - btn-secondary "刷新" → utility, equal-but-second. + - 危险路径 "创建全工具白名单" 折到 "更多 ⋯" 下拉，红色文字 — 不会再 + 以与日常操作并排同等地位的姿态出现。 + --> + <div class="section-header"> + <div class="section-header__title"> + <h2 class="section-title">{{ t('approval.grant.title') }}</h2> + <!-- Inline summary pill — same "danger-tinted info" tokens as the + sidebar chip so the two surfaces feel like one design language. + No el-tag here: keeps the page entirely native + token-driven. + Bound to activeCount (from /approval/grants/active) NOT total — + total includes revoked rows since the list endpoint returns + history by default, and the pill messaging ("已启用") only + makes sense for grants that are currently in force. --> + <span v-if="activeCount > 0" class="summary-pill"> + {{ t('approval.grant.chipLabel', { count: activeCount }) }} + </span> + <p class="section-desc">{{ t('approval.grant.desc') }}</p> + </div> + <div class="section-header__actions"> + <button class="btn-secondary" @click="loadGrants" :disabled="loading"> + <el-icon :size="14" :class="{ spin: loading }"><Refresh /></el-icon> + {{ t('common.refresh') }} + </button> + <button class="btn-primary" @click="openCreateDialog(false)"> + <el-icon :size="14"><Plus /></el-icon> + {{ t('approval.grant.createBtn') }} + </button> + <el-dropdown trigger="click" placement="bottom-end" @command="onMoreCommand"> + <button class="btn-secondary btn-more" :title="t('common.more')"> + <el-icon :size="16"><MoreFilled /></el-icon> + </button> + <template #dropdown> + <el-dropdown-menu> + <el-dropdown-item command="workspaceWide" class="danger-item"> + <el-icon><Unlock /></el-icon> + {{ t('approval.grant.createWorkspaceBtn') }} + </el-dropdown-item> + </el-dropdown-menu> + </template> + </el-dropdown> + </div> + </div> + + <!-- + Table + pagination — native HTML, no Element Plus components. Mirrors + the ToolGuard / AuditLogs pattern (rules-table-wrapper + .rules-table + + .severity-badge / .action-btn from shared.css) so this page reads + like any other Security sub-view. Pagination uses the shared + McPagination component, which is also fully native (no el-pagination). + --> + <div class="rules-table-wrapper"> + <table class="rules-table"> + <thead> + <tr> + <th>{{ t('approval.grant.columns.scope') }}</th> + <th>{{ t('approval.grant.columns.tool') }}</th> + <th>{{ t('approval.grant.columns.rule') }}</th> + <th>{{ t('approval.grant.columns.severity') }}</th> + <th>{{ t('approval.grant.columns.kind') }}</th> + <th>{{ t('approval.grant.columns.expire') }}</th> + <th>{{ t('approval.grant.columns.grantedBy') }}</th> + <th>{{ t('approval.grant.columns.note') }}</th> + <th class="col-actions">{{ t('approval.grant.columns.actions') }}</th> + </tr> + </thead> + <tbody> + <tr + v-for="row in rows" + :key="row.id" + :class="{ 'row-revoked': row.revoked === 1 }" + > + <td> + <span + class="scope-badge" + :class="`scope-${scopeI18nKey(row.scopeType)}`" + > + {{ t(`approval.grant.scope.${scopeI18nKey(row.scopeType)}`) }} + </span> + <div class="scope-id" :title="row.scopeId">{{ row.scopeId }}</div> + </td> + <td> + <code v-if="row.toolName" class="mono">{{ row.toolName }}</code> + <span v-else class="severity-badge severity-high">∗ any</span> + </td> + <td> + <code v-if="row.ruleId" class="mono">{{ row.ruleId }}</code> + <span v-else class="muted">∗</span> + </td> + <td> + <span + class="severity-badge" + :class="`severity-${row.maxSeverity?.toLowerCase()}`" + > + {{ row.maxSeverity }} + </span> + </td> + <td>{{ t(`approval.grant.kind.${kindI18nKey(row.grantKind)}`) }}</td> + <td class="muted">{{ formatDate(row.expireAt) }}</td> + <td> + <span v-if="row.grantedByName" :title="`#${row.grantedBy}`">{{ row.grantedByName }}</span> + <span v-else class="muted">#{{ row.grantedBy }}</span> + </td> + <td> + <span class="note-cell" :title="row.note || ''">{{ row.note }}</span> + </td> + <td class="col-actions"> + <button + v-if="row.revoked === 0" + class="row-action-btn row-action-btn--danger" + :title="t('approval.grant.revokeBtn')" + @click="confirmRevoke(row)" + > + <svg width="13" height="13" viewBox="0 0 24 24" fill="none" + stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> + <polyline points="3 6 5 6 21 6"/> + <path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6m3 0V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/> + </svg> + <span>{{ t('approval.grant.revokeBtn') }}</span> + </button> + <span v-else class="revoked-pill"> + <svg width="12" height="12" viewBox="0 0 24 24" fill="none" + stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> + <circle cx="12" cy="12" r="9"/> + <line x1="5.6" y1="5.6" x2="18.4" y2="18.4"/> + </svg> + {{ t('common.revoked') }} + </span> + </td> + </tr> + </tbody> + </table> + <div v-if="loading" class="empty-state">{{ t('common.loading') }}</div> + <div v-else-if="!rows.length" class="empty-state">{{ t('approval.grant.empty') }}</div> + </div> + + <div v-if="total > 0" class="grants-pagination-row"> + <McPagination + :page="currentPage" + :size="pageSize" + :total="total" + :sizes="[10, 20, 50, 100]" + @update:page="onPageChange" + @update:size="onSizeChange" + /> + </div> + + <!-- + Create dialog — matches the ToolGuard "edit rule" modal pattern: + Teleport to body + native .modal-overlay / .modal / .modal-header / + .modal-body / .modal-footer + .form-grid / .form-group / .form-input. + The workspace-wide path reuses the same modal with a red warning banner + at the top so the destructive variant looks identifiably different + from the routine create flow. + --> + <Teleport to="body"> + <div v-if="dialogOpen" class="modal-overlay" @click.self="dialogOpen = false"> + <div class="modal"> + <div class="modal-header"> + <h3> + <el-icon v-if="dialogWorkspaceWide" :size="18" class="modal-header__icon"><Unlock /></el-icon> + {{ dialogWorkspaceWide + ? t('approval.grant.createWorkspaceBtn') + : t('approval.grant.createBtn') }} + </h3> + <button class="modal-close" @click="dialogOpen = false">×</button> + </div> + <div class="modal-body"> + <div v-if="dialogWorkspaceWide" class="danger-banner"> + <el-icon :size="16"><WarningFilled /></el-icon> + <span>{{ t('approval.grant.createWorkspaceWarning') }}</span> + </div> + <div class="form-grid"> + <div class="form-group"> + <label>{{ t('approval.grant.form.scopeType') }} <span class="required">*</span></label> + <select + v-model="form.scopeType" + class="form-input" + :disabled="dialogWorkspaceWide" + > + <option value="CONVERSATION">CONVERSATION</option> + <option value="AGENT">AGENT</option> + <option value="USER">USER</option> + <option value="WORKSPACE">WORKSPACE</option> + </select> + </div> + <div class="form-group"> + <label>{{ t('approval.grant.form.scopeId') }} <span class="required">*</span></label> + <input + v-model.trim="form.scopeId" + type="text" + inputmode="numeric" + pattern="\d*" + placeholder="snowflake id" + class="form-input" + /> + </div> + <div class="form-group"> + <label>{{ t('approval.grant.form.toolName') }}</label> + <input + v-model.trim="form.toolName" + class="form-input mono" + :disabled="dialogWorkspaceWide" + placeholder="(empty = any tool)" + /> + </div> + <div class="form-group"> + <label>{{ t('approval.grant.form.ruleId') }}</label> + <input + v-model.trim="form.ruleId" + class="form-input mono" + placeholder="(optional)" + /> + </div> + <div class="form-group"> + <label>{{ t('approval.grant.form.maxSeverity') }}</label> + <select v-model="form.maxSeverity" class="form-input"> + <option value="LOW">LOW</option> + <option value="MEDIUM">MEDIUM</option> + <option value="HIGH">HIGH</option> + </select> + </div> + <div class="form-group"> + <label>{{ t('approval.grant.form.grantKind') }}</label> + <select v-model="form.grantKind" class="form-input"> + <option value="ALWAYS">{{ t('approval.grant.kind.always') }}</option> + <option value="UNTIL_TIMESTAMP">{{ t('approval.grant.kind.until') }}</option> + <option value="UNTIL_CONVERSATION_END">{{ t('approval.grant.kind.conversationEnd') }}</option> + </select> + </div> + <div v-if="form.grantKind === 'UNTIL_TIMESTAMP'" class="form-group"> + <label>{{ t('approval.grant.form.expireAt') }} <span class="required">*</span></label> + <input + v-model="form.expireAt" + type="datetime-local" + class="form-input" + /> + </div> + <div class="form-group form-group--full"> + <label>{{ t('approval.grant.form.note') }}</label> + <input + v-model.trim="form.note" + class="form-input" + :placeholder="dialogWorkspaceWide ? '请说明为什么需要全工具白名单' : ''" + /> + </div> + <div v-if="requiresPassword" class="form-group form-group--full"> + <label> + {{ t('approval.grant.form.password') }} + <span class="required">*</span> + </label> + <div class="password-wrap"> + <el-icon :size="14" class="password-wrap__icon"><Lock /></el-icon> + <input + v-model="form.password" + type="password" + class="form-input form-input--with-icon" + autocomplete="current-password" + /> + </div> + </div> + </div> + </div> + <div class="modal-footer"> + <button class="btn-secondary" @click="dialogOpen = false"> + {{ t('common.cancel') }} + </button> + <button + class="btn-primary" + :disabled="creating" + @click="submitCreate" + > + {{ creating ? t('common.processing') : t('common.confirm') }} + </button> + </div> + </div> + </div> + </Teleport> + + </div> +</template> + +<script setup lang="ts"> +import { ref, computed, onMounted, reactive } from 'vue' +import { useI18n } from 'vue-i18n' +import { ElMessage } from 'element-plus' +import { + Delete, + Lock, + MoreFilled, + Plus, + Refresh, + Unlock, + WarningFilled, +} from '@element-plus/icons-vue' +import { approvalApi } from '@/api' +import McPagination from '@/components/common/McPagination.vue' +import { mcConfirm } from '@/components/common/useConfirm' +import type { + ApprovalGrant, + CreateGrantPayload, + GrantScope, + GrantKind, + GrantSeverity, +} from '@/types' + +const { t } = useI18n() + +const rows = ref<ApprovalGrant[]>([]) +const total = ref(0) +// Active grants count for the summary pill — separate from `total` because the +// list endpoint returns revoked history by default and the pill should only +// reflect grants currently in force. +const activeCount = ref(0) +const currentPage = ref(1) +const pageSize = ref(20) +const loading = ref(false) + +const dialogOpen = ref(false) +const dialogWorkspaceWide = ref(false) +const creating = ref(false) + +interface FormState { + scopeType: GrantScope + scopeId: string + toolName: string + ruleId: string + maxSeverity: GrantSeverity + grantKind: GrantKind + expireAt: string + note: string + password: string +} + +const form = reactive<FormState>(emptyForm()) + +function emptyForm(): FormState { + return { + scopeType: 'CONVERSATION', + scopeId: '', + toolName: '', + ruleId: '', + maxSeverity: 'LOW', + grantKind: 'ALWAYS', + expireAt: '', + note: '', + password: '', + } +} + +const requiresPassword = computed(() => { + const noTool = !form.toolName + return noTool && (form.scopeType === 'WORKSPACE' || form.scopeType === 'AGENT') +}) + +function onPageChange(p: number) { + currentPage.value = p + loadGrants() +} +function onSizeChange(s: number) { + pageSize.value = s + currentPage.value = 1 + loadGrants() +} + +async function loadGrants() { + loading.value = true + try { + const res = await approvalApi.listGrants({ + page: currentPage.value, + size: pageSize.value, + }) + const data = (res as any).data ?? res + // Backend serializes Long as string (snowflake precision convention); coerce + // numeric page metadata at the boundary so el-pagination gets real numbers. + rows.value = Array.isArray(data?.records) ? data.records : [] + total.value = Number(data?.total ?? 0) + // Refresh active-only count for the summary pill in parallel with the + // list; non-blocking on failure so the page still renders normally. + refreshActiveCount() + } catch (e: any) { + ElMessage.error(e?.message || 'Failed to load grants') + rows.value = [] + total.value = 0 + } finally { + loading.value = false + } +} + +async function refreshActiveCount() { + try { + const res = await approvalApi.activeSummary() + const data = (res as any).data ?? res + activeCount.value = Number(data?.count ?? 0) + } catch { + activeCount.value = 0 + } +} + +function onMoreCommand(cmd: string | number | object) { + if (cmd === 'workspaceWide') { + openCreateDialog(true) + } +} + +function openCreateDialog(workspaceWide: boolean) { + Object.assign(form, emptyForm()) + if (workspaceWide) { + form.scopeType = 'WORKSPACE' + form.toolName = '' + form.maxSeverity = 'HIGH' + dialogWorkspaceWide.value = true + } else { + dialogWorkspaceWide.value = false + } + dialogOpen.value = true +} + +async function submitCreate() { + if (!form.scopeId) { + ElMessage.warning(t('approval.grant.form.scopeId')) + return + } + creating.value = true + try { + const payload: CreateGrantPayload = { + scopeType: form.scopeType, + scopeId: form.scopeId, + toolName: form.toolName || null, + ruleId: form.ruleId || null, + maxSeverity: form.maxSeverity, + grantKind: form.grantKind, + expireAt: form.expireAt || null, + note: form.note || null, + } + if (requiresPassword.value) { + if (!form.password) { + ElMessage.warning(t('approval.grant.form.password')) + creating.value = false + return + } + payload.password = form.password + } + await approvalApi.createGrant(payload) + ElMessage.success(t('common.success')) + dialogOpen.value = false + // Reset to page 1 so the just-created row is visible at the top. + currentPage.value = 1 + await loadGrants() + } catch (e: any) { + ElMessage.error(e?.message || 'Failed to create grant') + } finally { + creating.value = false + } +} + +async function confirmRevoke(g: ApprovalGrant) { + // Project-wide imperative confirm — same component used by McpServers, + // Channels, LivePanel, etc. so the destructive prompt feels consistent + // across the app. `tone: 'danger'` paints the confirm button red. + const target = g.toolName || t('approval.grant.anyTool') + const ok = await mcConfirm({ + title: t('approval.grant.revokeBtn'), + message: t('approval.grant.revokeConfirmDetailed', { tool: target }), + confirmText: t('approval.grant.revokeBtn'), + tone: 'danger', + }) + if (!ok) return + try { + await approvalApi.revokeGrant(g.id) + ElMessage.success(t('common.success')) + await loadGrants() + } catch (e: any) { + ElMessage.error(e?.message || 'Failed to revoke') + } +} + +function scopeI18nKey(scope: GrantScope): string { + switch (scope) { + case 'CONVERSATION': return 'conversation' + case 'AGENT': return 'agent' + case 'USER': return 'user' + case 'WORKSPACE': return 'workspace' + } +} + +function kindI18nKey(kind: GrantKind): string { + switch (kind) { + case 'ALWAYS': return 'always' + case 'UNTIL_TIMESTAMP': return 'until' + case 'UNTIL_CONVERSATION_END': return 'conversationEnd' + } +} + +function formatDate(s: string | null): string { + if (!s) return '—' + const d = new Date(s) + if (Number.isNaN(d.getTime())) return s + return d.toLocaleString() +} + +onMounted(loadGrants) +</script> + +<style scoped> +@import '@/views/Security/shared.css'; + +/* Title row: title + small summary tag on one line, description below. The + tag sits next to the title so the daily-glance question — "is auto-approve + active in this workspace right now?" — gets answered without scrolling. */ +.section-header__title { + display: flex; + flex-wrap: wrap; + align-items: center; + gap: 10px 12px; +} +.section-header__title .section-title { margin: 0; } +.section-header__title .section-desc { + flex-basis: 100%; + margin: 4px 0 0; +} +/* Summary pill — reuses the same danger-tinted tokens as the sidebar chip + so the two surfaces feel like one design language; no el-tag here. */ +.summary-pill { + display: inline-flex; + align-items: center; + padding: 2px 10px; + border-radius: 999px; + background: var(--mc-danger-bg, rgba(192, 57, 43, 0.12)); + color: var(--mc-danger, #C0392B); + border: 1px solid var(--mc-danger-border, rgba(192, 57, 43, 0.4)); + font-size: 12px; + font-weight: 600; + line-height: 1.5; +} + +/* Header actions: matches McpServers / ToolGuard layout (.section-header__actions + + native .btn-primary / .btn-secondary). Visual hierarchy intentionally + primary > secondary > "more …" so the daily action dominates and the + workspace-wide rule lives one click deeper. */ +.section-header__actions { + display: flex; + gap: 8px; + align-items: center; + flex-shrink: 0; /* keep buttons from being squeezed by the title block */ +} +.section-header__actions .btn-primary, +.section-header__actions .btn-secondary { + display: inline-flex; + align-items: center; + gap: 6px; + white-space: nowrap; /* prevent labels from wrapping into vertical text */ +} +.btn-more { + padding-left: 8px; + padding-right: 8px; +} +.spin { + animation: spin 0.8s linear infinite; +} +@keyframes spin { + from { transform: rotate(0deg); } + to { transform: rotate(360deg); } +} + +/* Danger items inside the More dropdown — visually distinct red text so the + workspace-wide path always feels like a dangerous action even when collapsed + into the overflow menu. */ +:global(.el-dropdown-menu__item.danger-item) { + color: var(--mc-danger, #b91c1c); +} +:global(.el-dropdown-menu__item.danger-item:hover) { + background: #fef2f2; + color: #991b1b; +} + +/* Scope badge — same family as .severity-badge in shared.css, 4 token-driven + color variants for CONVERSATION / AGENT / USER / WORKSPACE. */ +.scope-badge { + display: inline-block; + padding: 2px 8px; + border-radius: 4px; + font-size: 11px; + font-weight: 600; + line-height: 1.5; +} +.scope-conversation { background: rgba(59, 130, 246, 0.12); color: #3b82f6; } +.scope-agent { background: rgba(245, 158, 11, 0.12); color: #f59e0b; } +.scope-user { background: rgba(16, 185, 129, 0.12); color: #10b981; } +.scope-workspace { background: var(--mc-danger-bg, rgba(192, 57, 43, 0.12)); + color: var(--mc-danger, #C0392B); } +.scope-id { + margin-top: 2px; + font-family: ui-monospace, SFMono-Regular, Menlo, monospace; + font-size: 11px; + color: var(--mc-text-tertiary, #94a3b8); + max-width: 180px; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} + +.mono { + font-family: ui-monospace, SFMono-Regular, Menlo, monospace; + font-size: 12px; + background: var(--mc-surface-tertiary, var(--mc-bg-muted, rgba(0, 0, 0, 0.04))); + padding: 1px 6px; + border-radius: 3px; +} + +.note-cell { + display: inline-block; + max-width: 200px; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; + vertical-align: middle; +} + +.muted { + color: var(--mc-text-tertiary, #94a3b8); + font-size: 12px; +} + +/* Revoked rows: dim out so live rows stay visually dominant. */ +.row-revoked { opacity: 0.55; } +.row-revoked .scope-badge { filter: grayscale(0.5); } + +/* Actions column header sits right-aligned, matches ToolGuard. */ +.col-actions { text-align: center; width: 80px; } + +/* This page has more columns than ToolGuard / AuditLogs, so the wrapper needs + to allow horizontal scroll on narrow viewports — shared.css uses + overflow:hidden which would chop the rightmost columns off. Scoped override + only affects this view; the shared style stays untouched. */ +.rules-table-wrapper { + overflow-x: auto; +} +.rules-table { + min-width: 1100px; /* enough headroom so the kind / granter / date columns + don't collapse into vertical-text mode on a narrow viewport */ +} +/* Prevent narrow columns from wrapping into stacked Chinese glyphs. */ +.rules-table th, +.rules-table td { + white-space: nowrap; +} +/* Note cell is the one cell where wrapping is fine — it's already + ellipsis-truncated by .note-cell. Keep this explicit so adding nowrap to + the wider scope above doesn't suppress the ellipsis. */ +.rules-table td .note-cell { + white-space: nowrap; +} + +/* + Sticky "Actions" column — pinned to the right so the revoke control stays + reachable when the table horizontally scrolls. The cell needs an opaque + background or rows scrolling underneath would bleed through; we pull from + the same token the table sits on so the pinned column looks like it's + always been part of the surface rather than a floating overlay. A faint + left border doubles as the visual divider between the scrollable region + and the pinned column when content actually overflows. +*/ +.rules-table th.col-actions, +.rules-table td.col-actions { + position: sticky; + right: 0; + background: var(--mc-surface-primary, #fff); + box-shadow: -6px 0 8px -8px rgba(0, 0, 0, 0.08); + z-index: 2; +} +.rules-table th.col-actions { + /* Header sits above body when the user scrolls vertically inside a + scrollable area. Doesn't matter today (the page itself scrolls), but + cheap to set and future-proof. */ + z-index: 3; + background: var(--mc-bg-sunken); +} +/* Sticky cell needs its own dim treatment for revoked rows since opacity on + the <tr> doesn't reach a sticky child (the row's stacking context shifts). */ +.rules-table tr.row-revoked td.col-actions { + opacity: 0.55; +} +:global(html.dark .rules-table td.col-actions) { + background: var(--mc-bg-muted, #1a130e); + box-shadow: -6px 0 10px -8px rgba(0, 0, 0, 0.4); +} + +/* Pagination row — right-aligned beneath the table. McPagination provides + its own pill background, so just lay it out. */ +.grants-pagination-row { + margin-top: 14px; + display: flex; + justify-content: flex-end; +} + +/* ─── Modal (mirrors ToolGuard / edit-rule pattern) ──────────────────── */ +.modal-overlay { + position: fixed; + inset: 0; + background: rgba(0, 0, 0, 0.45); + display: flex; + align-items: center; + justify-content: center; + z-index: 2000; + padding: 24px; +} +.modal { + background: var(--mc-surface-primary, #fff); + border-radius: 12px; + width: min(640px, 100%); + max-height: 88vh; + display: flex; + flex-direction: column; + box-shadow: 0 16px 48px rgba(0, 0, 0, 0.18); + overflow: hidden; +} +.modal-header { + display: flex; + align-items: center; + justify-content: space-between; + padding: 16px 20px; + border-bottom: 1px solid var(--mc-border-light, #e5e7eb); +} +.modal-header h3 { + margin: 0; + font-size: 16px; + font-weight: 600; + color: var(--mc-text-primary, #0f172a); + display: inline-flex; + align-items: center; + gap: 8px; +} +.modal-header__icon { + color: var(--mc-danger, #b91c1c); +} +.modal-close { + background: none; + border: none; + font-size: 22px; + line-height: 1; + cursor: pointer; + color: var(--mc-text-tertiary, #94a3b8); +} +.modal-close:hover { color: var(--mc-text-primary, #0f172a); } +.modal-body { + padding: 20px; + overflow-y: auto; +} +.modal-footer { + padding: 12px 20px; + border-top: 1px solid var(--mc-border-light, #e5e7eb); + display: flex; + justify-content: flex-end; + gap: 8px; +} + +/* Danger banner inside the workspace-wide create modal — bright red so the + destructive variant looks instantly different from the routine flow. */ +.danger-banner { + display: flex; + align-items: flex-start; + gap: 10px; + padding: 12px 14px; + margin-bottom: 16px; + background: #fef2f2; + border: 1px solid #fecaca; + border-radius: 8px; + color: #991b1b; + font-size: 13px; + line-height: 1.5; +} +.danger-banner .el-icon { flex-shrink: 0; margin-top: 1px; } + +/* Form grid layout — two columns on wide modal, one column when narrow. + form-group--full breaks across both columns (note, password). */ +.form-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 14px 16px; +} +.form-group { + display: flex; + flex-direction: column; + gap: 6px; +} +.form-group--full { grid-column: 1 / -1; } +.form-group label { + font-size: 13px; + font-weight: 500; + color: var(--mc-text-secondary, #475569); +} +.form-group label .required { + color: var(--mc-danger, #b91c1c); + margin-left: 2px; +} +.form-input { + padding: 8px 10px; + border: 1px solid var(--mc-border-light, #e5e7eb); + border-radius: 6px; + background: var(--mc-surface-primary, #fff); + color: var(--mc-text-primary, #0f172a); + font-size: 13px; + width: 100%; + box-sizing: border-box; + transition: border-color 0.15s; +} +.form-input:focus { + outline: none; + border-color: var(--mc-primary, #d97757); +} +.form-input:disabled { + background: var(--mc-surface-tertiary, #f1f5f9); + cursor: not-allowed; +} +.form-input.mono { + font-family: ui-monospace, SFMono-Regular, Menlo, monospace; + font-size: 12px; +} + +/* Password input with the Lock icon as a visual prefix. */ +.password-wrap { + position: relative; + display: flex; + align-items: center; +} +.password-wrap__icon { + position: absolute; + left: 10px; + color: var(--mc-text-tertiary, #94a3b8); + pointer-events: none; +} +.form-input--with-icon { padding-left: 32px; } + +@media (max-width: 560px) { + .form-grid { grid-template-columns: 1fr; } +} +</style> diff --git a/mateclaw-ui/src/views/Security/Layout.vue b/mateclaw-ui/src/views/Security/Layout.vue index 24615942..fbd3ac74 100644 --- a/mateclaw-ui/src/views/Security/Layout.vue +++ b/mateclaw-ui/src/views/Security/Layout.vue @@ -84,6 +84,12 @@ const sections = computed(() => [ label: t('security.sections.auditLogs'), icon: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><polyline points="14 2 14 8 20 8"/><line x1="16" y1="13" x2="8" y2="13"/><line x1="16" y1="17" x2="8" y2="17"/></svg>', }, + { + id: 'autoApprove', + path: '/security/auto-approve', + label: t('approval.grant.menu'), + icon: '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="9 11 12 14 22 4"/><path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11"/></svg>', + }, ]) function isActive(path: string) { diff --git a/mateclaw-ui/src/views/Wiki/components/WikiAdvancedPanel.vue b/mateclaw-ui/src/views/Wiki/components/WikiAdvancedPanel.vue new file mode 100644 index 00000000..da5281cf --- /dev/null +++ b/mateclaw-ui/src/views/Wiki/components/WikiAdvancedPanel.vue @@ -0,0 +1,511 @@ +<template> + <div class="adv-panel"> + <!-- Sub-navigation across the five advanced management surfaces --> + <div class="adv-subtabs"> + <button + v-for="s in sections" :key="s.key" + class="adv-subtab" :class="{ active: section === s.key }" + @click="switchSection(s.key)" + >{{ s.label }}</button> + </div> + + <!-- ===================== REQ-1: PageType Profile ===================== --> + <section v-if="section === 'profile'" class="adv-section"> + <header class="adv-head"> + <div> + <h3>{{ t('wiki.adv.profile.title') }}</h3> + <p class="adv-desc">{{ t('wiki.adv.profile.desc') }}</p> + </div> + <span v-if="profile.builtinDefault" class="badge badge-muted">{{ t('wiki.adv.profile.builtin') }}</span> + <span v-else class="badge badge-ok">v{{ profile.version }}</span> + </header> + <textarea + v-model="profile.config" + class="code-editor" spellcheck="false" + :placeholder="t('wiki.adv.profile.placeholder')" + ></textarea> + <div v-if="profile.issues.length" class="issue-box"> + <div v-for="(iss, i) in profile.issues" :key="i" class="issue-line">⚠ {{ iss }}</div> + </div> + <div class="adv-actions"> + <button class="btn-ghost" @click="validateProfile" :disabled="profile.busy">{{ t('wiki.adv.validate') }}</button> + <button class="btn-ghost danger" @click="resetProfile" :disabled="profile.busy">{{ t('wiki.adv.profile.reset') }}</button> + <button class="btn-primary" @click="saveProfile" :disabled="profile.busy">{{ t('common.save') }}</button> + </div> + </section> + + <!-- ===================== REQ-2: Layers & Stale ===================== --> + <section v-else-if="section === 'layers'" class="adv-section"> + <header class="adv-head"> + <div> + <h3>{{ t('wiki.adv.layers.title') }}</h3> + <p class="adv-desc">{{ t('wiki.adv.layers.desc') }}</p> + </div> + <button class="btn-ghost" @click="loadLayers" :disabled="layers.busy">{{ t('common.refresh') }}</button> + </header> + <div class="layer-stats"> + <div class="stat-chip"><b>{{ layerGroups.fact.length }}</b> {{ t('wiki.adv.layers.fact') }}</div> + <div class="stat-chip"><b>{{ layerGroups.experience.length }}</b> {{ t('wiki.adv.layers.experience') }}</div> + <div class="stat-chip"><b>{{ layerGroups.other.length }}</b> {{ t('wiki.adv.layers.other') }}</div> + <div class="stat-chip stale"><b>{{ staleCount }}</b> {{ t('wiki.adv.layers.stale') }}</div> + </div> + <div v-if="layers.pages.length === 0 && !layers.busy" class="empty-hint">{{ t('wiki.adv.layers.empty') }}</div> + <table v-else class="adv-table"> + <thead><tr> + <th>{{ t('wiki.adv.layers.page') }}</th> + <th>{{ t('wiki.adv.layers.layer') }}</th> + <th>{{ t('wiki.adv.layers.status') }}</th> + </tr></thead> + <tbody> + <tr v-for="p in layers.pages" :key="p.id" :class="{ 'row-stale': isStale(p) }"> + <td class="cell-title">{{ p.title || p.slug }}</td> + <td><span class="layer-tag" :class="layerClass(p.knowledgeLayer)">{{ p.knowledgeLayer || '—' }}</span></td> + <td> + <span v-if="isStale(p)" class="badge badge-warn" :title="staleReason(p)">{{ t('wiki.adv.layers.staleTag') }}</span> + <span v-else class="badge badge-ok">{{ t('wiki.adv.layers.fresh') }}</span> + </td> + </tr> + </tbody> + </table> + </section> + + <!-- ===================== REQ-3: Permissions ===================== --> + <section v-else-if="section === 'permissions'" class="adv-section"> + <header class="adv-head"> + <div> + <h3>{{ t('wiki.adv.perm.title') }}</h3> + <p class="adv-desc">{{ t('wiki.adv.perm.desc') }}</p> + </div> + </header> + <div class="perm-agent-row"> + <label>{{ t('wiki.adv.perm.agent') }}</label> + <AgentPickerDialog + v-model="perm.agentId" + :agents="agents" + :placeholder="t('wiki.adv.perm.selectAgent')" + clearable + @change="loadPermissions" + /> + </div> + <template v-if="perm.agentId"> + <table class="adv-table"> + <thead><tr> + <th>{{ t('wiki.adv.perm.pageType') }}</th> + <th>R</th><th>C</th><th>U</th><th>D</th> + <th>{{ t('wiki.adv.perm.policy') }}</th> + <th></th> + </tr></thead> + <tbody> + <tr v-for="row in perm.rows" :key="row.id"> + <td class="cell-title">{{ row.pageType }}</td> + <td>{{ flag(row.canRead) }}</td> + <td>{{ flag(row.canCreate) }}</td> + <td>{{ flag(row.canUpdate) }}</td> + <td>{{ flag(row.canDelete) }}</td> + <td><span class="badge" :class="policyClass(row.writePolicy)">{{ row.writePolicy }}</span></td> + <td><button class="link-danger" @click="deletePermission(row)">{{ t('common.delete') }}</button></td> + </tr> + <tr v-if="perm.rows.length === 0"><td colspan="7" class="empty-hint">{{ t('wiki.adv.perm.noRows') }}</td></tr> + </tbody> + </table> + <div class="perm-add"> + <input v-model.trim="perm.draft.pageType" class="form-input compact" :placeholder="t('wiki.adv.perm.pageTypeHint')" /> + <label class="ck"><input type="checkbox" v-model="perm.draft.canRead" /> R</label> + <label class="ck"><input type="checkbox" v-model="perm.draft.canCreate" /> C</label> + <label class="ck"><input type="checkbox" v-model="perm.draft.canUpdate" /> U</label> + <label class="ck"><input type="checkbox" v-model="perm.draft.canDelete" /> D</label> + <select v-model="perm.draft.writePolicy" class="form-input compact"> + <option value="allow">allow</option> + <option value="approval_required">approval_required</option> + <option value="deny">deny</option> + </select> + <button class="btn-primary" @click="savePermission" :disabled="!perm.draft.pageType">{{ t('wiki.adv.perm.addRule') }}</button> + </div> + </template> + </section> + + <!-- ===================== REQ-4: Source Watcher ===================== --> + <section v-else-if="section === 'watcher'" class="adv-section"> + <header class="adv-head"> + <div> + <h3>{{ t('wiki.adv.watcher.title') }}</h3> + <p class="adv-desc">{{ t('wiki.adv.watcher.desc') }}</p> + </div> + <button class="btn-ghost" @click="loadWatcher" :disabled="watcher.busy">{{ t('common.refresh') }}</button> + </header> + <div class="kv-grid"> + <div class="kv"><span>{{ t('wiki.adv.watcher.enabled') }}</span><b>{{ watcher.data.watcherEnabled ? t('common.yes') : t('common.no') }}</b></div> + <div class="kv"><span>{{ t('wiki.adv.watcher.active') }}</span><b>{{ watcher.data.active ? t('common.yes') : t('common.no') }}</b></div> + <div class="kv"><span>{{ t('wiki.adv.watcher.interval') }}</span><b>{{ watcher.data.intervalMs ? (watcher.data.intervalMs / 1000) + 's' : '—' }}</b></div> + <div class="kv"><span>{{ t('wiki.adv.watcher.sourceType') }}</span><b>{{ watcher.data.sourceType || '—' }}</b></div> + </div> + <label class="field-label">{{ t('wiki.adv.watcher.directory') }}</label> + <div class="dir-row"> + <input v-model.trim="watcher.dir" class="form-input" :placeholder="t('wiki.adv.watcher.dirHint')" /> + <button class="btn-ghost" @click="saveDirectory" :disabled="watcher.busy">{{ t('common.save') }}</button> + </div> + <p v-if="watcher.data.availableSourceTypes?.length" class="adv-desc"> + {{ t('wiki.adv.watcher.availableTypes') }}: {{ watcher.data.availableSourceTypes.join(', ') }} + </p> + <div class="adv-actions"> + <button class="btn-primary" @click="triggerScan" :disabled="watcher.busy || !watcher.data.active">{{ t('wiki.adv.watcher.scanNow') }}</button> + </div> + <div v-if="watcher.lastScan" class="issue-box ok"> + {{ t('wiki.adv.watcher.scanResult', { scanned: watcher.lastScan.scanned, added: watcher.lastScan.added, skipped: watcher.lastScan.skipped, errors: watcher.lastScan.errors }) }} + </div> + </section> + + <!-- ===================== REQ-5: Pipeline ===================== --> + <section v-else-if="section === 'pipeline'" class="adv-section"> + <header class="adv-head"> + <div> + <h3>{{ t('wiki.adv.pipeline.title') }}</h3> + <p class="adv-desc">{{ t('wiki.adv.pipeline.desc') }}</p> + </div> + <button class="btn-ghost" @click="loadPipelines" :disabled="pipeline.busy">{{ t('common.refresh') }}</button> + </header> + <table class="adv-table"> + <thead><tr> + <th>{{ t('wiki.adv.pipeline.name') }}</th> + <th>{{ t('wiki.adv.pipeline.trigger') }}</th> + <th>{{ t('wiki.adv.pipeline.enabled') }}</th> + <th></th> + </tr></thead> + <tbody> + <tr v-for="d in pipeline.defs" :key="d.id"> + <td class="cell-title">{{ d.name }}</td> + <td>{{ d.triggerType }}</td> + <td>{{ d.enabled ? '✓' : '—' }}</td> + <td class="cell-actions"> + <button class="link" @click="viewRuns(d)">{{ t('wiki.adv.pipeline.runs') }}</button> + <button class="link-danger" @click="deletePipeline(d)">{{ t('common.delete') }}</button> + </td> + </tr> + <tr v-if="pipeline.defs.length === 0"><td colspan="4" class="empty-hint">{{ t('wiki.adv.pipeline.empty') }}</td></tr> + </tbody> + </table> + + <div v-if="pipeline.runsFor" class="runs-box"> + <div class="runs-head"> + <b>{{ t('wiki.adv.pipeline.runsFor', { name: pipeline.runsFor.name }) }}</b> + <button class="link" @click="pipeline.runsFor = null">{{ t('common.close') }}</button> + </div> + <table class="adv-table compact"> + <thead><tr><th>#</th><th>{{ t('wiki.adv.pipeline.status') }}</th><th>{{ t('wiki.adv.pipeline.startedAt') }}</th></tr></thead> + <tbody> + <tr v-for="r in pipeline.runs" :key="r.id"> + <td>{{ r.id }}</td> + <td><span class="badge" :class="runClass(r.status)">{{ r.status }}</span></td> + <td>{{ r.createTime }}</td> + </tr> + <tr v-if="pipeline.runs.length === 0"><td colspan="3" class="empty-hint">{{ t('wiki.adv.pipeline.noRuns') }}</td></tr> + </tbody> + </table> + </div> + + <label class="field-label">{{ t('wiki.adv.pipeline.editor') }}</label> + <textarea + v-model="pipeline.config" + class="code-editor" spellcheck="false" + :placeholder="t('wiki.adv.pipeline.editorHint')" + ></textarea> + <div v-if="pipeline.issues.length" class="issue-box"> + <div v-for="(iss, i) in pipeline.issues" :key="i" class="issue-line">⚠ {{ iss }}</div> + </div> + <div class="adv-actions"> + <button class="btn-ghost" @click="validatePipeline" :disabled="pipeline.busy">{{ t('wiki.adv.validate') }}</button> + <button class="btn-primary" @click="savePipeline" :disabled="pipeline.busy">{{ t('wiki.adv.pipeline.saveDef') }}</button> + </div> + </section> + </div> +</template> + +<script setup lang="ts"> +import { ref, reactive, computed, onMounted } from 'vue' +import { useI18n } from 'vue-i18n' +import { useWikiStore } from '@/stores/useWikiStore' +import { useAgentStore } from '@/stores/useAgentStore' +import { wikiApi } from '@/api/index' +import { mcToast } from '@/composables/useMcToast' +import { mcConfirm } from '@/components/common/useConfirm' +import AgentPickerDialog from '@/components/common/AgentPickerDialog.vue' + +const { t } = useI18n() +const store = useWikiStore() +const agentStore = useAgentStore() + +// kbId stays a string for its whole lifecycle (Snowflake precision rule). +const kbId = computed(() => (store.currentKB ? String(store.currentKB.id) : '')) +const agents = computed(() => agentStore.agents) + +const section = ref<'profile' | 'layers' | 'permissions' | 'watcher' | 'pipeline'>('profile') +const sections = computed(() => [ + { key: 'profile' as const, label: t('wiki.adv.profile.tab') }, + { key: 'layers' as const, label: t('wiki.adv.layers.tab') }, + { key: 'permissions' as const, label: t('wiki.adv.perm.tab') }, + { key: 'watcher' as const, label: t('wiki.adv.watcher.tab') }, + { key: 'pipeline' as const, label: t('wiki.adv.pipeline.tab') }, +]) + +const loaded = reactive<Record<string, boolean>>({}) +function switchSection(key: typeof section.value) { + section.value = key + if (loaded[key]) return + loaded[key] = true + if (key === 'layers') loadLayers() + else if (key === 'permissions') { if (agents.value.length === 0) agentStore.fetchAgents() } + else if (key === 'watcher') loadWatcher() + else if (key === 'pipeline') loadPipelines() +} + +function unwrap(res: any) { return res?.data ?? res } +function errMsg(e: any, fallback: string) { return e?.response?.data?.message || fallback } + +// ---- REQ-1 Profile ---- +const profile = reactive({ config: '', version: 0, builtinDefault: true, issues: [] as string[], busy: false }) +async function loadProfile() { + if (!kbId.value) return + try { + const d = unwrap(await wikiApi.getPageTypeProfile(kbId.value)) + profile.config = typeof d.config === 'string' ? d.config : JSON.stringify(d.config, null, 2) + profile.version = d.version + profile.builtinDefault = d.builtinDefault + } catch (e: any) { mcToast.error(errMsg(e, 'Load profile failed')) } +} +async function validateProfile() { + profile.busy = true + try { + const d = unwrap(await wikiApi.validatePageTypeProfile(kbId.value, profile.config)) + profile.issues = d.issues || [] + if (d.valid) mcToast.success(t('wiki.adv.validOk')) + } catch (e: any) { mcToast.error(errMsg(e, 'Validate failed')) } finally { profile.busy = false } +} +async function saveProfile() { + profile.busy = true + try { + await wikiApi.savePageTypeProfile(kbId.value, profile.config) + mcToast.success(t('common.saved')) + profile.issues = [] + await loadProfile() + } catch (e: any) { mcToast.error(errMsg(e, 'Save failed')) } finally { profile.busy = false } +} +async function resetProfile() { + if (!(await mcConfirm({ title: t('wiki.adv.profile.reset'), message: t('wiki.adv.profile.resetConfirm'), tone: 'danger' }))) return + profile.busy = true + try { + await wikiApi.resetPageTypeProfile(kbId.value) + mcToast.success(t('common.saved')) + await loadProfile() + } catch (e: any) { mcToast.error(errMsg(e, 'Reset failed')) } finally { profile.busy = false } +} + +// ---- REQ-2 Layers & Stale ---- +const layers = reactive({ pages: [] as any[], busy: false }) +async function loadLayers() { + if (!kbId.value) return + layers.busy = true + try { + layers.pages = unwrap(await wikiApi.listPages(kbId.value as any)) || [] + } catch (e: any) { mcToast.error(errMsg(e, 'Load pages failed')) } finally { layers.busy = false } +} +function isStale(p: any) { return p.stale === 1 || p.stale === true } +const staleCount = computed(() => layers.pages.filter(isStale).length) +const layerGroups = computed(() => { + const g = { fact: [] as any[], experience: [] as any[], other: [] as any[] } + for (const p of layers.pages) { + if (p.knowledgeLayer === 'fact') g.fact.push(p) + else if (p.knowledgeLayer === 'experience') g.experience.push(p) + else g.other.push(p) + } + return g +}) +function layerClass(l?: string) { return l === 'fact' ? 'tag-fact' : l === 'experience' ? 'tag-exp' : 'tag-other' } +function staleReason(p: any) { + try { return p.staleReasonJson ? JSON.stringify(JSON.parse(p.staleReasonJson)) : '' } catch { return p.staleReasonJson || '' } +} + +// ---- REQ-3 Permissions ---- +const perm = reactive({ + agentId: '', + rows: [] as any[], + draft: { pageType: '', canRead: true, canCreate: false, canUpdate: false, canDelete: false, writePolicy: 'approval_required' as 'allow' | 'deny' | 'approval_required' }, +}) +async function loadPermissions() { + if (!perm.agentId || !kbId.value) { perm.rows = []; return } + try { + perm.rows = unwrap(await wikiApi.listPageTypePermissions(kbId.value, perm.agentId)) || [] + } catch (e: any) { mcToast.error(errMsg(e, 'Load permissions failed')) } +} +async function savePermission() { + if (!perm.draft.pageType) return + try { + await wikiApi.savePageTypePermission(kbId.value, perm.agentId, { + pageType: perm.draft.pageType, + canRead: perm.draft.canRead ? 1 : 0, + canCreate: perm.draft.canCreate ? 1 : 0, + canUpdate: perm.draft.canUpdate ? 1 : 0, + canDelete: perm.draft.canDelete ? 1 : 0, + writePolicy: perm.draft.writePolicy, + }) + mcToast.success(t('common.saved')) + perm.draft.pageType = '' + await loadPermissions() + } catch (e: any) { mcToast.error(errMsg(e, 'Save failed')) } +} +async function deletePermission(row: any) { + if (!(await mcConfirm({ title: t('common.delete'), message: t('wiki.adv.perm.deleteConfirm', { type: row.pageType }), tone: 'danger' }))) return + try { + await wikiApi.deletePageTypePermission(kbId.value, perm.agentId, String(row.id)) + await loadPermissions() + } catch (e: any) { mcToast.error(errMsg(e, 'Delete failed')) } +} +function flag(v: any) { return v ? '✓' : '·' } +function policyClass(p?: string) { return p === 'allow' ? 'badge-ok' : p === 'deny' ? 'badge-warn' : 'badge-muted' } + +// ---- REQ-4 Watcher ---- +const watcher = reactive({ data: {} as any, dir: '', lastScan: null as any, busy: false }) +async function loadWatcher() { + if (!kbId.value) return + watcher.busy = true + try { + watcher.data = unwrap(await wikiApi.getSourceWatcher(kbId.value)) || {} + watcher.dir = watcher.data.sourceDirectory || '' + } catch (e: any) { mcToast.error(errMsg(e, 'Load watcher failed')) } finally { watcher.busy = false } +} +async function saveDirectory() { + watcher.busy = true + try { + await wikiApi.setSourceDirectory(kbId.value, watcher.dir) + mcToast.success(t('common.saved')) + await loadWatcher() + } catch (e: any) { mcToast.error(errMsg(e, 'Save failed')) } finally { watcher.busy = false } +} +async function triggerScan() { + watcher.busy = true + try { + watcher.lastScan = unwrap(await wikiApi.triggerSourceWatcher(kbId.value)) + mcToast.success(t('wiki.adv.watcher.scanDone')) + } catch (e: any) { mcToast.error(errMsg(e, 'Scan failed')) } finally { watcher.busy = false } +} + +// ---- REQ-5 Pipeline ---- +const pipeline = reactive({ defs: [] as any[], config: '', issues: [] as string[], runsFor: null as any, runs: [] as any[], busy: false }) +async function loadPipelines() { + if (!kbId.value) return + pipeline.busy = true + try { + pipeline.defs = unwrap(await wikiApi.listPipelines(kbId.value)) || [] + } catch (e: any) { mcToast.error(errMsg(e, 'Load pipelines failed')) } finally { pipeline.busy = false } +} +async function validatePipeline() { + pipeline.busy = true + try { + const d = unwrap(await wikiApi.validatePipeline(kbId.value, pipeline.config)) + pipeline.issues = d.issues || [] + if (d.valid) mcToast.success(t('wiki.adv.validOk')) + } catch (e: any) { mcToast.error(errMsg(e, 'Validate failed')) } finally { pipeline.busy = false } +} +async function savePipeline() { + pipeline.busy = true + try { + await wikiApi.savePipeline(kbId.value, pipeline.config) + mcToast.success(t('common.saved')) + pipeline.issues = [] + await loadPipelines() + } catch (e: any) { mcToast.error(errMsg(e, 'Save failed')) } finally { pipeline.busy = false } +} +async function deletePipeline(d: any) { + if (!(await mcConfirm({ title: t('common.delete'), message: t('wiki.adv.pipeline.deleteConfirm', { name: d.name }), tone: 'danger' }))) return + try { + await wikiApi.deletePipeline(kbId.value, String(d.id)) + if (pipeline.runsFor && String(pipeline.runsFor.id) === String(d.id)) pipeline.runsFor = null + await loadPipelines() + } catch (e: any) { mcToast.error(errMsg(e, 'Delete failed')) } +} +async function viewRuns(d: any) { + pipeline.runsFor = d + try { + pipeline.runs = unwrap(await wikiApi.listPipelineRuns(kbId.value, String(d.id))) || [] + } catch (e: any) { mcToast.error(errMsg(e, 'Load runs failed')) } +} +function runClass(s?: string) { + if (s === 'succeeded' || s === 'success') return 'badge-ok' + if (s === 'failed' || s === 'error') return 'badge-warn' + return 'badge-muted' +} + +onMounted(() => { loaded.profile = true; loadProfile() }) +</script> + +<style scoped> +.adv-panel { display: flex; flex-direction: column; gap: 14px; height: 100%; } +.adv-subtabs { display: inline-flex; gap: 4px; padding: 4px; background: var(--mc-bg-muted); border-radius: 12px; border: 1px solid var(--mc-border-light); align-self: flex-start; flex-wrap: wrap; } +.adv-subtab { padding: 6px 13px; border: none; background: none; cursor: pointer; font-size: 13px; color: var(--mc-text-secondary); border-radius: 9px; font-weight: 500; transition: all 0.15s; } +.adv-subtab:hover { color: var(--mc-text-primary); } +.adv-subtab.active { color: var(--mc-primary); background: var(--mc-bg-elevated); font-weight: 600; box-shadow: 0 1px 3px rgba(0,0,0,0.08); } + +.adv-section { display: flex; flex-direction: column; gap: 12px; overflow-y: auto; padding-right: 2px; } +.adv-head { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; } +.adv-head h3 { margin: 0; font-size: 15px; font-weight: 700; color: var(--mc-text-primary); } +.adv-desc { margin: 4px 0 0; font-size: 12px; color: var(--mc-text-tertiary); line-height: 1.5; } + +.code-editor { width: 100%; min-height: 240px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12.5px; line-height: 1.6; padding: 12px; border: 1px solid var(--mc-border); border-radius: 12px; background: var(--mc-bg-muted); color: var(--mc-text-primary); resize: vertical; outline: none; box-sizing: border-box; } +.code-editor:focus { border-color: var(--mc-primary); } + +.adv-actions { display: flex; gap: 10px; justify-content: flex-end; } +.btn-primary { padding: 8px 16px; background: linear-gradient(135deg, var(--mc-primary), var(--mc-primary-hover)); color: #fff; border: none; border-radius: 11px; font-size: 13px; font-weight: 600; cursor: pointer; } +.btn-primary:disabled { opacity: 0.5; cursor: not-allowed; } +.btn-ghost { padding: 8px 14px; background: var(--mc-bg-elevated); color: var(--mc-text-primary); border: 1px solid var(--mc-border); border-radius: 11px; font-size: 13px; cursor: pointer; } +.btn-ghost.danger { color: #c0392b; border-color: rgba(192,57,43,0.3); } +.btn-ghost:disabled { opacity: 0.5; cursor: not-allowed; } + +.badge { display: inline-block; padding: 2px 9px; border-radius: 999px; font-size: 11px; font-weight: 600; } +.badge-ok { background: rgba(24,74,69,0.12); color: #184a45; } +.badge-warn { background: rgba(192,57,43,0.12); color: #c0392b; } +.badge-muted { background: var(--mc-bg-muted); color: var(--mc-text-secondary); } + +.issue-box { border: 1px solid rgba(192,57,43,0.3); background: rgba(192,57,43,0.06); border-radius: 10px; padding: 10px 12px; font-size: 12px; color: #c0392b; } +.issue-box.ok { border-color: rgba(24,74,69,0.3); background: rgba(24,74,69,0.06); color: #184a45; } +.issue-line { line-height: 1.6; } + +.adv-table { width: 100%; border-collapse: collapse; font-size: 13px; } +.adv-table th { text-align: left; padding: 8px 10px; color: var(--mc-text-tertiary); font-weight: 600; font-size: 11px; text-transform: uppercase; letter-spacing: 0.03em; border-bottom: 1px solid var(--mc-border-light); } +.adv-table td { padding: 8px 10px; border-bottom: 1px solid var(--mc-border-light); color: var(--mc-text-primary); } +.adv-table.compact td, .adv-table.compact th { padding: 6px 10px; } +.cell-title { font-weight: 600; } +.cell-actions { display: flex; gap: 12px; } +.row-stale { background: rgba(192,57,43,0.04); } + +.layer-tag { padding: 2px 8px; border-radius: 6px; font-size: 11px; font-weight: 600; } +.tag-fact { background: rgba(24,74,69,0.12); color: #184a45; } +.tag-exp { background: rgba(217,109,70,0.14); color: #b8552f; } +.tag-other { background: var(--mc-bg-muted); color: var(--mc-text-secondary); } + +.layer-stats { display: flex; gap: 10px; flex-wrap: wrap; } +.stat-chip { padding: 8px 14px; background: var(--mc-bg-muted); border-radius: 10px; font-size: 12px; color: var(--mc-text-secondary); } +.stat-chip b { font-size: 16px; color: var(--mc-text-primary); margin-right: 4px; } +.stat-chip.stale b { color: #c0392b; } + +.perm-agent-row { display: flex; align-items: center; gap: 10px; } +.perm-agent-row label, .field-label { font-size: 12px; font-weight: 600; color: var(--mc-text-secondary); } +.perm-add { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; padding-top: 8px; } +.ck { display: inline-flex; align-items: center; gap: 4px; font-size: 12px; color: var(--mc-text-secondary); } + +.form-input { padding: 8px 12px; border: 1px solid var(--mc-border); border-radius: 10px; font-size: 13px; background: var(--mc-bg-muted); color: var(--mc-text-primary); outline: none; box-sizing: border-box; } +.form-input:focus { border-color: var(--mc-primary); } +.form-input.compact { padding: 6px 10px; } + +.link { background: none; border: none; color: var(--mc-primary); cursor: pointer; font-size: 12px; padding: 0; } +.link-danger { background: none; border: none; color: #c0392b; cursor: pointer; font-size: 12px; padding: 0; } +.empty-hint { color: var(--mc-text-tertiary); font-size: 13px; text-align: center; padding: 18px; } + +.kv-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 10px; } +.kv { display: flex; flex-direction: column; gap: 3px; padding: 10px 12px; background: var(--mc-bg-muted); border-radius: 10px; } +.kv span { font-size: 11px; color: var(--mc-text-tertiary); } +.kv b { font-size: 14px; color: var(--mc-text-primary); } +.dir-row { display: flex; gap: 8px; } +.dir-row .form-input { flex: 1; } + +.runs-box { border: 1px solid var(--mc-border-light); border-radius: 12px; padding: 12px; background: var(--mc-bg-muted); } +.runs-head { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; } +</style> diff --git a/mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksBanner.vue b/mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksBanner.vue new file mode 100644 index 00000000..36cdc482 --- /dev/null +++ b/mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksBanner.vue @@ -0,0 +1,164 @@ +<template> + <!-- + Workspace-level banner that surfaces broken-link state without forcing the + user into a separate tab. Three modes: + * never scanned → compact "scan now" prompt with a button + * scan running → loading indicator + status text + * have report → count + last-scan timestamp + "view" + "rescan" + The detail panel (per-page breakdown, "open source page" actions) lives + in WikiBrokenLinksPanel.vue, mounted by the parent on demand. + --> + <div + v-if="!isHidden" + class="lint-banner" + :class="{ + 'lint-banner--clean': report && report.totalBrokenRefs === 0, + 'lint-banner--has-broken': report && report.totalBrokenRefs > 0, + 'lint-banner--running': loading, + 'lint-banner--empty': !report && !loading, + }" + > + <span class="lint-icon" aria-hidden="true"> + <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"> + <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.72"/> + <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.72-1.72"/> + </svg> + </span> + + <span v-if="loading" class="lint-text"> + {{ t('wiki.lint.running') }} + </span> + <span v-else-if="!report" class="lint-text"> + {{ t('wiki.lint.neverScanned') }} + </span> + <span v-else-if="report.totalBrokenRefs === 0" class="lint-text"> + {{ t('wiki.lint.cleanResult', { pages: report.totalPages }) }} + <span class="lint-timestamp">{{ formattedTimestamp }}</span> + </span> + <span v-else class="lint-text"> + <i18n-t keypath="wiki.lint.brokenSummary" tag="span"> + <template #refs><strong>{{ report.totalBrokenRefs }}</strong></template> + <template #pages><strong>{{ report.pagesWithBrokenLinks }}</strong></template> + </i18n-t> + <span class="lint-timestamp">{{ formattedTimestamp }}</span> + </span> + + <div class="lint-actions"> + <button + v-if="report && report.totalBrokenRefs > 0" + class="lint-btn lint-btn--primary" + @click="$emit('view')" + >{{ t('wiki.lint.view') }}</button> + <button + class="lint-btn" + :disabled="loading" + @click="onScan" + >{{ loading ? t('wiki.lint.scanning') : (report ? t('wiki.lint.rescan') : t('wiki.lint.scan')) }}</button> + <button class="lint-btn lint-btn--ghost" :title="t('wiki.lint.dismissTitle')" @click="dismissed = true">×</button> + </div> + </div> +</template> + +<script setup lang="ts"> +import { computed, ref } from 'vue' +import { useI18n } from 'vue-i18n' +import { useWikiStore } from '@/stores/useWikiStore' + +defineEmits<{ (e: 'view'): void }>() + +const { t, locale } = useI18n() +const store = useWikiStore() + +// Per-session dismiss — user can hide the banner without affecting scan state. +// Reset implicitly on KB switch (banner is re-mounted when currentKB changes +// because the parent passes :key="kb.id"; if it doesn't, dismissals persist +// across KB switches which is acceptable for v1). +const dismissed = ref(false) + +const report = computed(() => store.brokenLinksReport) +const loading = computed(() => store.brokenLinksLoading) +const isHidden = computed(() => dismissed.value) + +const formattedTimestamp = computed(() => { + const ts = report.value?.completedAt + if (!ts) return '' + try { + const d = new Date(ts) + return ' · ' + d.toLocaleString(locale.value) + } catch { + return ' · ' + ts + } +}) + +async function onScan() { + if (!store.currentKB) return + try { + await store.startBrokenLinksScan(Number(store.currentKB.id)) + } catch (e: any) { + console.error('[Wiki] scan failed', e) + } +} +</script> + +<style scoped> +.lint-banner { + display: flex; + align-items: center; + gap: 10px; + padding: 8px 14px; + border-radius: 10px; + border: 1px solid var(--mc-border-light); + background: var(--mc-bg-elevated); + font-size: 13px; + color: var(--mc-text-secondary); + margin-bottom: 12px; +} +.lint-banner--has-broken { + border-color: var(--el-color-warning-light-5, #f0c78a); + background: var(--el-color-warning-light-9, #fdf6ec); + color: var(--el-color-warning-dark-2, #b88230); +} +.lint-banner--clean { + border-color: var(--el-color-success-light-5, #b3e19d); + background: var(--el-color-success-light-9, #f0f9eb); + color: var(--el-color-success-dark-2, #529b2e); +} +.lint-banner--running { + border-color: var(--mc-primary); + background: var(--mc-primary-bg, #fff5f0); + color: var(--mc-primary); +} +.lint-icon { display: inline-flex; align-items: center; } +.lint-text { flex: 1; min-width: 0; } +.lint-timestamp { color: var(--mc-text-tertiary); font-size: 12px; } +.lint-actions { display: inline-flex; align-items: center; gap: 6px; } +.lint-btn { + padding: 5px 11px; + border-radius: 8px; + border: 1px solid var(--mc-border-light); + background: var(--mc-bg-elevated); + color: inherit; + font-size: 12.5px; + font-weight: 500; + cursor: pointer; +} +.lint-btn:hover:not(:disabled) { border-color: var(--mc-primary); color: var(--mc-primary); } +.lint-btn:disabled { cursor: not-allowed; opacity: 0.6; } +.lint-btn--primary { + background: var(--mc-primary); + border-color: var(--mc-primary); + color: white; +} +.lint-btn--primary:hover { background: var(--mc-primary-hover); color: white; } +.lint-btn--ghost { + width: 24px; + height: 24px; + padding: 0; + border: none; + background: transparent; + font-size: 16px; + line-height: 1; + color: var(--mc-text-tertiary); +} +.lint-btn--ghost:hover { color: var(--mc-text-primary); background: transparent; } +</style> diff --git a/mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksPanel.vue b/mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksPanel.vue new file mode 100644 index 00000000..a5c6ce5a --- /dev/null +++ b/mateclaw-ui/src/views/Wiki/components/WikiBrokenLinksPanel.vue @@ -0,0 +1,166 @@ +<template> + <!-- + Modal-style drawer that lists every page in the KB with at least one + broken outlink. Each row shows the page title, slug, the failing target + strings, and a button to jump into the source page so the author can fix + the content. Pure read view — no inline editing in v1 (the user clicks + through to the page editor, fixes the wikilink, save re-syncs broken_links). + --> + <Teleport to="body"> + <div v-if="open" class="lint-panel-backdrop" @click.self="$emit('close')"> + <div class="lint-panel"> + <header class="lint-panel-header"> + <h3 class="lint-panel-title">{{ t('wiki.lint.panelTitle') }}</h3> + <button class="close-btn" @click="$emit('close')" :aria-label="t('common.close')">×</button> + </header> + + <div v-if="!report" class="lint-panel-empty"> + {{ t('wiki.lint.noReport') }} + </div> + + <div v-else-if="report.totalBrokenRefs === 0" class="lint-panel-empty lint-panel-empty--clean"> + {{ t('wiki.lint.cleanResult', { pages: report.totalPages }) }} + </div> + + <div v-else class="lint-panel-body"> + <div class="lint-stats"> + <i18n-t keypath="wiki.lint.brokenSummary" tag="span"> + <template #refs><strong>{{ report.totalBrokenRefs }}</strong></template> + <template #pages><strong>{{ report.pagesWithBrokenLinks }}</strong></template> + </i18n-t> + </div> + <ul class="lint-page-list"> + <li v-for="row in report.pages" :key="row.slug" class="lint-page-row"> + <div class="lint-page-head"> + <button class="lint-page-link" @click="onOpenPage(row.slug)"> + {{ row.title }} + </button> + <code class="lint-page-slug">{{ row.slug }}</code> + </div> + <ul class="lint-ref-list"> + <li v-for="ref in row.brokenRefs" :key="ref" class="lint-ref-tag"> + <code>[[{{ ref }}]]</code> + </li> + </ul> + </li> + </ul> + </div> + </div> + </div> + </Teleport> +</template> + +<script setup lang="ts"> +import { computed } from 'vue' +import { useI18n } from 'vue-i18n' +import { useWikiStore } from '@/stores/useWikiStore' + +defineProps<{ open: boolean }>() +const emit = defineEmits<{ (e: 'close'): void }>() + +const { t } = useI18n() +const store = useWikiStore() + +const report = computed(() => store.brokenLinksReport) + +async function onOpenPage(slug: string) { + if (!store.currentKB) return + await store.loadPage(Number(store.currentKB.id), slug) + emit('close') +} +</script> + +<style scoped> +.lint-panel-backdrop { + position: fixed; + inset: 0; + background: rgba(0, 0, 0, 0.32); + display: flex; + align-items: flex-start; + justify-content: center; + padding: 8vh 16px; + z-index: 1100; +} +.lint-panel { + background: var(--mc-bg-elevated); + border: 1px solid var(--mc-border-light); + border-radius: 14px; + width: 100%; + max-width: 640px; + max-height: 80vh; + display: flex; + flex-direction: column; + box-shadow: 0 16px 48px rgba(0, 0, 0, 0.18); +} +.lint-panel-header { + display: flex; + align-items: center; + justify-content: space-between; + padding: 14px 18px; + border-bottom: 1px solid var(--mc-border-light); +} +.lint-panel-title { font-size: 15px; font-weight: 600; margin: 0; color: var(--mc-text-primary); } +.close-btn { + border: none; + background: transparent; + font-size: 20px; + line-height: 1; + cursor: pointer; + color: var(--mc-text-tertiary); +} +.close-btn:hover { color: var(--mc-text-primary); } + +.lint-panel-empty { + padding: 32px 24px; + text-align: center; + color: var(--mc-text-secondary); + font-size: 14px; +} +.lint-panel-empty--clean { color: var(--el-color-success-dark-2, #529b2e); } + +.lint-panel-body { overflow-y: auto; padding: 12px 18px 18px; } +.lint-stats { font-size: 13px; color: var(--mc-text-secondary); margin-bottom: 10px; } +.lint-page-list { list-style: none; padding: 0; margin: 0; display: flex; flex-direction: column; gap: 10px; } +.lint-page-row { + padding: 10px 12px; + background: var(--mc-bg-muted); + border: 1px solid var(--mc-border-light); + border-radius: 10px; +} +.lint-page-head { + display: flex; + align-items: baseline; + gap: 10px; + margin-bottom: 6px; + flex-wrap: wrap; +} +.lint-page-link { + border: none; + background: none; + padding: 0; + font-size: 14px; + font-weight: 600; + color: var(--mc-primary); + cursor: pointer; + text-align: left; +} +.lint-page-link:hover { text-decoration: underline; } +.lint-page-slug { font-size: 11.5px; color: var(--mc-text-tertiary); } +.lint-ref-list { + list-style: none; + padding: 0; + margin: 0; + display: flex; + flex-wrap: wrap; + gap: 6px; +} +.lint-ref-tag code { + display: inline-block; + padding: 2px 8px; + background: var(--el-color-warning-light-9, #fdf6ec); + color: var(--el-color-warning-dark-2, #b88230); + border: 1px solid var(--el-color-warning-light-5, #f0c78a); + border-radius: 6px; + font-size: 12px; +} +</style> diff --git a/mateclaw-ui/src/views/Wiki/components/WikiPageViewer.vue b/mateclaw-ui/src/views/Wiki/components/WikiPageViewer.vue index 74775dfb..0c25cfca 100644 --- a/mateclaw-ui/src/views/Wiki/components/WikiPageViewer.vue +++ b/mateclaw-ui/src/views/Wiki/components/WikiPageViewer.vue @@ -102,6 +102,7 @@ import { useWikiStore, isProtectedPage, type WikiPage } from '@/stores/useWikiSt import { useWorkspaceStore } from '@/stores/useWorkspaceStore' import { wikiApi } from '@/api/index' import { useMarkdownRenderer } from '@/composables/useMarkdownRenderer' +import { postprocessWikilinks, resolveWikilink, type WikilinkRef } from '@/composables/wikilink' import { Link, SetUp } from '@element-plus/icons-vue' import PageHeader from './PageHeader.vue' import RelatedPagesPanel from './RelatedPagesPanel.vue' @@ -132,33 +133,56 @@ const isSystem = computed(() => store.currentPage?.pageType === 'system') const isProtected = computed(() => isProtectedPage(store.currentPage)) const isLockedNotSystem = computed(() => isProtected.value && !isSystem.value) +// Render the markdown WITHOUT the renderer's built-in wikilink substitution. +// `wikilink: 'none'` keeps the raw `[[...]]` tokens intact so the DOM +// postprocess below can resolve them against the authoritative pageRefs +// index rather than against `store.pages` (which is filtered by rawId and +// would silently break cross-material links). See RFC 55 §1.3 / Phase 1. const renderedContent = computed(() => { if (!store.currentPage?.content) return '' - // Build a lookup map: title (normalized) → slug, for resolving [[Title]] links - const titleToSlug = new Map<string, string>() - for (const p of store.pages) { - if (p.title && p.slug) { - titleToSlug.set(p.title.trim().toLowerCase(), p.slug) - } - } - const content = store.currentPage.content.replace(/\[\[([^\]]+)\]\]/g, (_match, raw) => { - const title = raw.trim() - // Prefer exact title match; fall back to slug-style guess - const slug = titleToSlug.get(title.toLowerCase()) ?? title.toLowerCase().replace(/\s+/g, '-') - return `<a class="wiki-link" data-slug="${slug}">${title}</a>` - }) - return renderMarkdown(content) + return renderMarkdown(store.currentPage.content, { wikilink: 'none' }) }) +// Project the store's pageRefs into the resolver's lightweight shape. Pulling +// `archived: false` explicitly (the store's WikiPageRef already carries it, +// but the active list is guaranteed non-archived by the backend filter) keeps +// the resolver's TypeScript types simple. +const activeRefs = computed<WikilinkRef[]>(() => + store.pageRefs.map((p) => ({ slug: p.slug, title: p.title, archived: false })), +) +const archivedRefs = computed<WikilinkRef[]>(() => + store.archivedPageRefs.map((p) => ({ slug: p.slug, title: p.title, archived: true })), +) + +// Postprocess wikilinks after v-html settles. Runs on every content swap and +// also whenever the resolution index changes (e.g. user navigated away, a +// page was created in the background, archived refs finally loaded), so links +// that started life as `wiki-link-broken` upgrade to active hits on a re-walk. +async function runWikilinkPostprocess() { + await nextTick() + const root = articleRef.value + if (!root) return + const refs = activeRefs.value + const archived = archivedRefs.value + postprocessWikilinks(root, (raw) => resolveWikilink(raw, refs, archived)) +} + // Bind the image lightbox to the rendered article on every content swap. // Awaits a microtask so v-html has a chance to repopulate the DOM, then // asks the lightbox to walk <img> tags and attach click handlers. Already- // bound elements are skipped by the lightbox itself. watch(renderedContent, async () => { - await nextTick() + await runWikilinkPostprocess() lightboxRef.value?.attach(articleRef.value) }) +// Re-run wikilink resolution when the refs index changes — a sibling page +// created or restored from archive should upgrade existing broken spans on +// the open page to active links without forcing the user to re-navigate. +watch([activeRefs, archivedRefs], async () => { + await runWikilinkPostprocess() +}) + watch(() => store.currentPage, async (page) => { if (page && store.currentKB) { editing.value = false @@ -181,13 +205,30 @@ async function saveEdit() { async function handleDelete() { if (!store.currentKB || !store.currentPage) return - const confirmed = confirm(t('wiki.confirmDelete', { title: store.currentPage.title })) + // Surface the referrer count before deletion so the user knows how many + // pages will be unlinked in cascade. backlinks already loads on page + // open (see the currentPage watcher), so this read is local — no extra + // round-trip. The cascade runs on the backend regardless of UI prompt + // wording; this is purely advisory. + const refCount = backlinks.value.length + const baseMessage = t('wiki.confirmDelete', { title: store.currentPage.title }) + const withRefs = refCount > 0 + ? `${baseMessage}\n\n${t('wiki.confirmDeleteRefs', { count: refCount })}` + : baseMessage + const confirmed = confirm(withRefs) if (!confirmed) return try { await wikiApi.deletePage(store.currentKB.id, store.currentPage.slug) store.currentPage = null // Keep the active raw-material filter so the list doesn't jump to all pages. - await store.fetchPages(store.currentKB.id, store.selectedRawId) + // Refresh pageRefs + broken-link report too — both can change after a + // delete because cascade-rewrite may upgrade or downgrade other pages' + // resolution states. + await Promise.all([ + store.fetchPages(store.currentKB.id, store.selectedRawId), + store.fetchPageRefs(store.currentKB.id), + store.loadBrokenLinksReport(store.currentKB.id), + ]) } catch (e: any) { alert(e?.message || 'Delete failed') } @@ -226,6 +267,15 @@ async function openPage(slug: string) { } onMounted(() => { + // Lazily load archived refs once per KB so the postprocess can label any + // existing links to archived targets as such instead of treating them as + // broken. The store dedupes repeated calls, so this is cheap on revisits. + if (store.currentKB) { + store.fetchArchivedPageRefs(store.currentKB.id) + } + // Global click delegation — both `wiki-link` and `wiki-link wiki-link-archived` + // share the same data-slug contract and the same routing through openPage. + // `wiki-link-broken` lacks the class entirely so its clicks are no-ops. document.addEventListener('click', (e) => { const target = e.target as HTMLElement if (target.classList.contains('wiki-link')) { @@ -300,6 +350,24 @@ onMounted(() => { .page-content :deep(img) { max-width: 100%; border-radius: 10px; } .page-content :deep(.wiki-link) { color: var(--mc-primary); text-decoration: none; cursor: pointer; border-bottom: 1px dashed var(--mc-primary); } .page-content :deep(.wiki-link:hover) { text-decoration: underline; } +/* Archived target — still clickable to view/restore, but visually de-emphasised + to match the archived state semantics from elsewhere in the wiki UI. */ +.page-content :deep(.wiki-link.wiki-link-archived) { + color: var(--mc-text-tertiary); + border-bottom-color: var(--mc-text-tertiary); + border-bottom-style: dotted; + font-style: italic; +} +.page-content :deep(.wiki-link.wiki-link-archived:hover) { color: var(--mc-text-secondary); } +/* Broken target — no click, no href, no request. Dashed underline + muted tone + tells the reader the wikilink couldn't be resolved without committing to + navigation that would 404. Tooltip shows the rejection reason. */ +.page-content :deep(.wiki-link-broken) { + color: var(--mc-text-tertiary); + text-decoration: underline dashed var(--mc-text-tertiary); + text-underline-offset: 3px; + cursor: help; +} /* Editor */ .page-editor { width: 100%; min-height: 60vh; padding: 16px; border: 1px solid var(--mc-border); border-radius: 14px; font-family: 'JetBrains Mono', monospace; font-size: 14px; line-height: 1.65; resize: vertical; background: var(--mc-bg-elevated); color: var(--mc-text-primary); outline: none; } diff --git a/mateclaw-ui/src/views/Wiki/components/WikiWorkspace.vue b/mateclaw-ui/src/views/Wiki/components/WikiWorkspace.vue index d15a385c..dcef5e98 100644 --- a/mateclaw-ui/src/views/Wiki/components/WikiWorkspace.vue +++ b/mateclaw-ui/src/views/Wiki/components/WikiWorkspace.vue @@ -2,6 +2,15 @@ <div class="wiki-workspace"> <WikiWorkspaceHeader :kb="kb" @back="store.backToLibrary()" /> + <!-- + Broken-link banner — surfaces lint state across every tab so the user + can trigger a scan or view results from any browsing context. Pinned + between the header and the tab layout so it's the first thing they see + after entering the KB. + --> + <WikiBrokenLinksBanner @view="brokenPanelOpen = true" /> + <WikiBrokenLinksPanel :open="brokenPanelOpen" @close="brokenPanelOpen = false" /> + <div class="wiki-layout"> <WikiPageSidebar @open-page="onOpenPage" /> @@ -46,6 +55,10 @@ <div v-if="activeTab === 'transformations'" class="tab-content"> <TransformationsPanel /> </div> + + <div v-if="activeTab === 'advanced'" class="tab-content"> + <WikiAdvancedPanel /> + </div> </div> </div> </div> @@ -63,8 +76,11 @@ import WikiConfig from './WikiConfig.vue' import WikiGraphView from './WikiGraphView.vue' import HotCachePanel from './HotCachePanel.vue' import TransformationsPanel from './TransformationsPanel.vue' +import WikiAdvancedPanel from './WikiAdvancedPanel.vue' import WikiWorkspaceHeader from './WikiWorkspaceHeader.vue' import WikiPageSidebar from './WikiPageSidebar.vue' +import WikiBrokenLinksBanner from './WikiBrokenLinksBanner.vue' +import WikiBrokenLinksPanel from './WikiBrokenLinksPanel.vue' defineProps<{ kb: WikiKB }>() @@ -77,6 +93,15 @@ const workspace = useWorkspaceStore() const canManageWiki = computed(() => workspace.can('manage:wiki')) const activeTab = ref('raw') +const brokenPanelOpen = ref(false) + +// When a page becomes the currentPage (e.g. via the global wikilink click +// handler that lands on /wiki?kbId=X&slug=Y), switch the tab to 'pages' so +// the viewer is the thing the user sees. Without this, the workspace stays +// on the default 'raw' tab and the page silently loads off-screen. +watch(() => store.currentPage, (page) => { + if (page) activeTab.value = 'pages' +}) const tabs = computed(() => { const list = [ @@ -87,6 +112,7 @@ const tabs = computed(() => { if (canManageWiki.value) { list.push({ key: 'config', label: t('wiki.config') }) list.push({ key: 'transformations', label: t('wiki.transformations.tab') }) + list.push({ key: 'advanced', label: t('wiki.adv.tab') }) } list.push({ key: 'hotCache', label: t('wiki.hotCache.tab') }) return list diff --git a/mateclaw-ui/src/views/Wiki/index.vue b/mateclaw-ui/src/views/Wiki/index.vue index c3a854b9..37f1c41c 100644 --- a/mateclaw-ui/src/views/Wiki/index.vue +++ b/mateclaw-ui/src/views/Wiki/index.vue @@ -41,6 +41,7 @@ <script setup lang="ts"> import { ref, reactive, watch, onMounted } from 'vue' import { useI18n } from 'vue-i18n' +import { useRoute, useRouter } from 'vue-router' import { useWikiStore, type WikiKB } from '@/stores/useWikiStore' import { wikiApi } from '@/api/index' import { mcConfirm } from '@/components/common/useConfirm' @@ -48,6 +49,9 @@ import { mcToast } from '@/composables/useMcToast' import WikiLibrary from './components/WikiLibrary.vue' import WikiWorkspace from './components/WikiWorkspace.vue' +const route = useRoute() +const router = useRouter() + const { t } = useI18n() const store = useWikiStore() @@ -108,9 +112,47 @@ async function handleDeleteKB(kb: WikiKB) { } } -onMounted(() => { - store.fetchKnowledgeBases() +async function consumeQueryNavigation() { + // Global wikilink click delegator (see App.vue) pushes us with + // ?kbId=X&slug=Y on click. Honour both: enter the KB then surface + // the page directly. Strips the query immediately so a manual reload + // doesn't keep re-opening the same page. + // + // **Snowflake precision** (per CLAUDE.md): the kbId is a 19-digit + // Snowflake that exceeds Number.MAX_SAFE_INTEGER. NEVER coerce via + // Number()/parseInt() — that truncates the last 2-3 digits and turns + // a real lookup into a silent "KB not found". Keep the string and + // pass it through to the store; the store / api layer treats kbId as + // an opaque token interpolated into the request URL. + const kbIdRaw = route.query.kbId + const slugRaw = route.query.slug + if (typeof kbIdRaw !== 'string' || !kbIdRaw) return + if (typeof slugRaw !== 'string' || !slugRaw) return + // Cast to number ONLY to satisfy the store's type signature — the + // runtime value stays a string under the hood. TypeScript can't + // express "number-or-Snowflake-string" without widening every signature, + // so the cast is the localised, documented escape hatch. + // snowflake-precision-ok: kbIdRaw is the URL-encoded string from the + // global click delegator; never passed through Number()/parseInt(). + const kbId = kbIdRaw as unknown as number + await store.selectKB(kbId) + try { + await store.loadPage(kbId, slugRaw) + } catch (e) { + console.warn('[Wiki] auto-open page failed', e) + } + // Drop the query so back-button + reload behave sanely. + router.replace({ name: 'Wiki' }) +} + +onMounted(async () => { + await store.fetchKnowledgeBases() + await consumeQueryNavigation() }) + +// Re-consume the query when a click delegator navigates while we're +// already on /wiki (route.path unchanged, query changed). +watch(() => route.query, () => { consumeQueryNavigation() }) </script> <style scoped> diff --git a/mateclaw-ui/src/views/layout/MainLayout.vue b/mateclaw-ui/src/views/layout/MainLayout.vue index 05d1fc04..aa0e38b0 100644 --- a/mateclaw-ui/src/views/layout/MainLayout.vue +++ b/mateclaw-ui/src/views/layout/MainLayout.vue @@ -80,11 +80,34 @@ <!-- 底部 --> <div class="sidebar-footer"> <template v-if="!sidebarCollapsed || isMobile"> - <!-- Doctor 健康指示器 --> - <button class="health-indicator" :class="healthStatus" @click="showDoctor = true" :title="t('doctor.title')"> - <span class="health-dot"></span> - <span class="health-label">{{ t('doctor.title') }}</span> - </button> + <!-- + Status row: two side-by-side status cards. Doctor health on the left + stays always visible; the auto-approve chip on the right only renders + when at least one grant is active. When the chip is hidden, flex + naturally lets the doctor card expand to full width again — so the + row never wastes vertical space the way a stacked banner did. + --> + <div class="footer-status-row"> + <button + class="health-indicator" + :class="[healthStatus, { 'is-half': autoApproveSummary && autoApproveSummary.count > 0 }]" + @click="showDoctor = true" + :title="t('doctor.title')" + > + <span class="health-dot"></span> + <span class="health-label">{{ t('doctor.title') }}</span> + </button> + <button + v-if="autoApproveSummary && autoApproveSummary.count > 0" + class="auto-approve-chip" + @click="goAutoApproveSettings" + :title="t('approval.grant.title')" + > + <span class="auto-approve-chip__dot"></span> + <el-icon :size="13"><Unlock /></el-icon> + <span class="auto-approve-chip__label">{{ t('approval.grant.chipShort', { count: autoApproveSummary.count }) }}</span> + </button> + </div> <div class="sidebar-utility-card"> <div class="compact-utility-row"> @@ -197,7 +220,8 @@ import { useI18n } from 'vue-i18n' import { useThemeStore } from '@/stores/useThemeStore' import { version as appVersion } from '../../../package.json' import type { ThemeMode } from '@/stores/useThemeStore' -import { http, settingsApi, setupApi } from '@/api/index' +import { http, settingsApi, setupApi, approvalApi } from '@/api/index' +import type { ActiveGrantsSummary } from '@/types' import OnboardingWizard from '@/views/Onboarding/OnboardingWizard.vue' import DoctorDrawer from '@/views/Doctor/DoctorDrawer.vue' import WorkspaceSwitcher from '@/components/workspace/WorkspaceSwitcher.vue' @@ -206,7 +230,7 @@ import McTooltip from '@/components/common/McTooltip.vue' import { useNotificationCenter } from '@/composables/useNotificationCenter' import { useWorkspaceStore } from '@/stores/useWorkspaceStore' import { applyLocale, currentLocale, type AppLocale } from '@/i18n' -import { SwitchButton, Lock } from '@element-plus/icons-vue' +import { SwitchButton, Lock, Unlock } from '@element-plus/icons-vue' import ChangePasswordDialog from '@/components/ChangePasswordDialog.vue' const router = useRouter() @@ -237,6 +261,22 @@ async function fetchHealthStatus() { } } +// Active auto-approve grants summary — drives the red "auto-approve active (N)" +// chip in the sidebar footer. Red (not green) is intentional: this is a +// security-reducing setting and the UI should keep reminding the user it's on. +const autoApproveSummary = ref<ActiveGrantsSummary | null>(null) +async function fetchAutoApproveSummary() { + try { + const res: any = await approvalApi.activeSummary() + autoApproveSummary.value = res?.data || res + } catch { + autoApproveSummary.value = null + } +} +function goAutoApproveSettings() { + router.push('/security/auto-approve') +} + // Sidebar attention signals — admin-only. Both `/agents` (stuck agents in the // Live view) and `/security` (pending approvals) read from a shared 15s poller // so multiple consumers don't multiply HTTP traffic. @@ -323,6 +363,10 @@ onMounted(async () => { // Fetch initial health status for sidebar indicator fetchHealthStatus() + // Auto-approve chip count. Cheap query (single SELECT COUNT) so we just + // fetch on mount and on workspace switch (handled by router-view key change + // which re-mounts the route subtree). + fetchAutoApproveSummary() // Sidebar attention counts (live / security) are driven by // useNotificationCenter — it polls when admins are mounted. }) @@ -772,8 +816,93 @@ watch(() => workspaceStore.currentWorkspaceId, () => { backdrop-filter: blur(14px); position: relative; } -.health-indicator { display: flex; align-items: center; gap: 8px; width: 100%; padding: 8px 10px; border: 1px solid var(--mc-border-light); background: var(--mc-bg-muted); border-radius: 12px; cursor: pointer; color: var(--mc-text-secondary); font-size: 12px; margin-bottom: 8px; } +/* Status row: doctor health + (optional) auto-approve chip side by side, so + the footer never gives up a whole banner-row for a single state badge. When + the chip is hidden, .health-indicator naturally expands back to full width. */ +.footer-status-row { + display: flex; + gap: 8px; + width: 100%; + margin-bottom: 8px; +} +.health-indicator { + display: flex; + align-items: center; + gap: 8px; + flex: 1 1 auto; + min-width: 0; + padding: 8px 10px; + border: 1px solid var(--mc-border-light); + background: var(--mc-bg-muted); + border-radius: 12px; + cursor: pointer; + color: var(--mc-text-secondary); + font-size: 12px; +} .health-indicator:hover { background: var(--mc-bg-sunken); } +.health-indicator .health-label { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +/* When the chip is showing, the health card yields half of the row so the + two states stay visually balanced. */ +.health-indicator.is-half { flex: 1 1 50%; } + +/* + Auto-approve chip — persistent indicator that this workspace currently has + at least one active auto-approve rule. Designed to be informative, not + alarming: a soft danger-tinted pill with a steady pulse on the dot, sized + to fit beside the doctor indicator on one row. Colors come from the + mateclaw token system (`var(--mc-danger-*)`), so dark mode picks up the + appropriate dim variants automatically. +*/ +.auto-approve-chip { + display: inline-flex; + align-items: center; + gap: 6px; + flex: 1 1 50%; + min-width: 0; + padding: 8px 10px; + border: 1px solid var(--mc-danger-border, rgba(192, 57, 43, 0.4)); + background: var(--mc-danger-bg, rgba(192, 57, 43, 0.12)); + color: var(--mc-danger, #C0392B); + border-radius: 12px; + cursor: pointer; + font-size: 12px; + font-weight: 600; + line-height: 1.2; + transition: background-color 0.15s, border-color 0.15s; +} +.auto-approve-chip:hover { + background: var(--mc-danger-bg, rgba(192, 57, 43, 0.18)); + border-color: var(--mc-danger, #C0392B); +} +.auto-approve-chip__label { + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; +} +/* Small live-status dot that gently pulses to suggest "this is active right + now" without being aggressive about it. The animation pauses when the user + prefers reduced motion. */ +.auto-approve-chip__dot { + width: 6px; + height: 6px; + border-radius: 50%; + background: var(--mc-danger, #C0392B); + box-shadow: 0 0 0 0 var(--mc-danger, #C0392B); + animation: auto-approve-pulse 2.4s ease-in-out infinite; + flex-shrink: 0; +} +@keyframes auto-approve-pulse { + 0% { box-shadow: 0 0 0 0 var(--mc-danger, #C0392B); opacity: 1; } + 60% { box-shadow: 0 0 0 6px transparent; opacity: 0.6; } + 100% { box-shadow: 0 0 0 0 transparent; opacity: 1; } +} +@media (prefers-reduced-motion: reduce) { + .auto-approve-chip__dot { animation: none; } +} .health-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; } .health-indicator.healthy .health-dot { background: var(--mc-success); } .health-indicator.warning .health-dot { background: var(--mc-primary); } diff --git a/mateclaw-ui/src/views/mcp/McpFormModal.vue b/mateclaw-ui/src/views/mcp/McpFormModal.vue index 476c3b4e..7a02d898 100644 --- a/mateclaw-ui/src/views/mcp/McpFormModal.vue +++ b/mateclaw-ui/src/views/mcp/McpFormModal.vue @@ -189,7 +189,7 @@ function hydrateFromServer(s: McpServer) { envJson: s.envJson || '', cwd: s.cwd || '', connectTimeoutSeconds: s.connectTimeoutSeconds || 30, - readTimeoutSeconds: s.readTimeoutSeconds || 30, + readTimeoutSeconds: s.readTimeoutSeconds || 60, enabled: s.enabled, }) } diff --git a/mateclaw-ui/src/views/mcp/types.ts b/mateclaw-ui/src/views/mcp/types.ts index b02e2fcc..eee8994c 100644 --- a/mateclaw-ui/src/views/mcp/types.ts +++ b/mateclaw-ui/src/views/mcp/types.ts @@ -63,7 +63,7 @@ export function emptyMcpForm(): McpServerForm { envJson: '', cwd: '', connectTimeoutSeconds: 30, - readTimeoutSeconds: 30, + readTimeoutSeconds: 60, enabled: true, } } diff --git a/mateclaw-ui/vitest.config.ts b/mateclaw-ui/vitest.config.ts new file mode 100644 index 00000000..8798fc99 --- /dev/null +++ b/mateclaw-ui/vitest.config.ts @@ -0,0 +1,21 @@ +import { defineConfig } from 'vitest/config' +import path from 'node:path' + +// Two test conventions coexist in this repo: +// - `test/**/*.test.ts` — pre-existing files using the Node `node:test` +// runner (run via `node --test test/<file>.test.ts`). +// - `src/**/__tests__/*.test.ts` — vitest tests for new code. +// +// Scope vitest to `src/**` so it never picks up the node:test files (which +// don't export describe/it/expect and would otherwise fail discovery). +export default defineConfig({ + test: { + include: ['src/**/*.{test,spec}.{ts,tsx}'], + environment: 'happy-dom', + }, + resolve: { + alias: { + '@': path.resolve(__dirname, 'src'), + }, + }, +}) diff --git a/pom.xml b/pom.xml index e40b6f05..abc6c83d 100644 --- a/pom.xml +++ b/pom.xml @@ -21,7 +21,7 @@ <properties> <!-- MateClaw release version shared by all Maven modules. --> - <revision>1.4.0</revision> + <revision>1.5.0</revision> <!-- Java --> <java.version>21</java.version> @@ -30,7 +30,7 @@ <!-- Spring ecosystem --> <spring-boot.version>3.5.14</spring-boot.version> - <spring-ai.version>1.1.6</spring-ai.version> + <spring-ai.version>1.1.7</spring-ai.version> <spring-ai-alibaba.version>1.1.2.3</spring-ai-alibaba.version> <springdoc.version>2.8.16</springdoc.version> @@ -43,7 +43,7 @@ <!-- Channel and platform SDKs --> <dingtalk-stream.version>1.3.12</dingtalk-stream.version> - <lark-oapi.version>2.6.1</lark-oapi.version> + <lark-oapi.version>2.7.1</lark-oapi.version> <jda.version>6.4.1</jda.version> <slack.version>1.48.1</slack.version>