flzxsqc-demo 1.4.3

package/agent-backend/ARCHITECTURE.md

@@ -0,0 +1,768 @@
+# zy-agent-backend Architecture
+
+## 1. Overview
+
+`zy-agent-backend` is now a session-driven vertical agent backend for finance customer-support analysis.
+
+The current runtime no longer uses the old one-shot plan builder or step-loop orchestrator. The active design is:
+
+1. Receive a user request and create or resume an `AgentSession`
+2. Select skills through `LLM skill routing` with `rule fallback`
+3. Assemble a system prompt from runtime metadata, skill markdown, and allowed tools
+4. Let the LLM decide the next action in a turn loop
+5. If the LLM requests tools, execute them through a unified tool pipeline
+6. Feed tool results back into the same transcript
+7. Continue until the LLM returns a final assistant answer or an async tool waits for callback
+8. When a task succeeds, compile the successful tool trajectory into a replayable DSL snapshot
+
+The active runtime entry is:
+
+- `src/main/java/com/example/agent/interfaces/rest/AgentSessionController.java`
+- `src/main/java/com/example/agent/interfaces/rest/AgentRuntimeController.java`
+
+The core orchestrator is:
+
+- `src/main/java/com/example/agent/application/service/AgentTurnRunner.java`
+
+---
+
+## 2. Active API Surface
+
+### 2.1 Agent session APIs
+
+Defined in:
+
+- `src/main/java/com/example/agent/interfaces/rest/AgentSessionController.java`
+
+Endpoints:
+
+#### `POST /api/agent/sessions`
+
+Create a new agent session and immediately start the first turn.
+
+Request body:
+
+```json
+{
+  "message": "请分析最近30天贵金属规则调整相关的客服问题并生成报告",
+  "globalContext": {
+    "tenantId": "finance-demo",
+    "businessLine": "precious-metal",
+    "operator": "alice",
+    "channel": "app"
+  }
+}
+```
+
+Response:
+
+- Full `AgentSession`
+
+#### `POST /api/agent/sessions/{sessionId}/messages`
+
+Append a user message to an existing session and continue the loop.
+
+Request body:
+
+```json
+{
+  "message": "只分析高净值客户，并按渠道拆分"
+}
+```
+
+Response:
+
+- Updated `AgentSession`
+
+#### `POST /api/agent/sessions/{sessionId}/resume`
+
+Resume a session after an async tool has completed or when an external caller explicitly wants to continue.
+
+Response:
+
+- Updated `AgentSession`
+
+#### `GET /api/agent/sessions/{sessionId}`
+
+Load the current session snapshot from persistence.
+
+Response:
+
+- Full `AgentSession`
+
+#### `GET /api/agent/sessions/{sessionId}/events`
+
+SSE event stream for runtime events.
+
+Produced events come from:
+
+- `src/main/java/com/example/agent/domain/model/RuntimeEventType.java`
+
+Current event types:
+
+- `SESSION_STARTED`
+- `TURN_STARTED`
+- `MODEL_DECISION`
+- `TOOL_CALL_REQUESTED`
+- `TOOL_EXECUTION_STARTED`
+- `TOOL_CALLBACK_RECEIVED`
+- `TOOL_EXECUTION_FINISHED`
+- `TOOL_EXECUTION_FAILED`
+- `WAITING_ASYNC_CALLBACK`
+- `ASSISTANT_MESSAGE`
+- `TURN_FINISHED`
+- `DSL_COMPILED`
+
+#### `GET /api/agent/dsl/{dslId}`
+
+Load a compiled DSL snapshot.
+
+Response:
+
+- `ExecutableDslSnapshot`
+
+#### `POST /api/agent/dsl/{dslId}/execute`
+
+Replay a compiled DSL using optional runtime overrides.
+
+Request body:
+
+```json
+{
+  "top_n": 20,
+  "business_line": "precious-metal"
+}
+```
+
+Response:
+
+- DSL replay result with per-step outputs
+
+---
+
+### 2.2 Agent runtime APIs
+
+Defined in:
+
+- `src/main/java/com/example/agent/interfaces/rest/AgentRuntimeController.java`
+
+Endpoints:
+
+#### `POST /api/agent/tool-callback`
+
+Receive an external async tool callback, update the matching tool result, emit callback events, and resume the session.
+
+Request body:
+
+```json
+{
+  "externalJobId": "job-123",
+  "status": "SUCCEEDED",
+  "payload": {
+    "artifacts": {
+      "analysis_job_id": "job-123",
+      "keywords": ["保证金", "交易规则", "手续费"]
+    }
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "ok": true
+}
+```
+
+If no matching async job exists:
+
+```json
+{
+  "error": "async job not found"
+}
+```
+
+#### `GET /api/agent/sessions/{sessionId}/runtime`
+
+Return the persisted session row and event history snapshot.
+
+---
+
+### 2.3 Direct customer-session query API
+
+Defined in:
+
+- `src/main/java/com/example/agent/interfaces/rest/CustomerSessionController.java`
+
+Endpoint:
+
+#### `POST /api/customer-sessions/query`
+
+Request:
+
+```json
+{
+  "keywords": ["保证金", "规则调整"],
+  "businessLine": "precious-metal",
+  "channel": "app",
+  "customerId": "C10001",
+  "startTime": "2026-03-01 00:00:00",
+  "endTime": "2026-03-14 23:59:59",
+  "limit": 20
+}
+```
+
+Response:
+
+```json
+{
+  "total": 2,
+  "records": [
+    {
+      "id": 1,
+      "sessionCode": "CS202603130001",
+      "channel": "app",
+      "customerId": "C10001",
+      "agentId": "A20001",
+      "businessLine": "precious-metal",
+      "userMessage": "...",
+      "agentReply": "...",
+      "tags": "规则调整,保证金",
+      "occurredAt": "2026-03-13T10:00:00"
+    }
+  ]
+}
+```
+
+---
+
+### 2.4 Internal tool APIs
+
+Defined in:
+
+- `src/main/java/com/example/agent/interfaces/rest/ToolsController.java`
+
+These endpoints are internal tool surfaces called by `ToolsApiToolExecutor`.
+
+Endpoints:
+
+- `POST /tools/sample-sessions-by-keywords`
+- `POST /tools/query-sessions-handle`
+- `POST /tools/analyze-keywords-async`
+- `POST /tools/build-keyword-report`
+- `POST /tools/query-customer-sessions-mysql`
+
+---
+
+## 3. Main Planning and Execution Flow
+
+### 3.1 Entry flow
+
+The first request enters through:
+
+- `AgentSessionController.createSession(...)`
+
+This method calls:
+
+- `AgentTurnRunner.startSession(...)`
+
+`startSession(...)` does:
+
+1. Create a new `AgentSession`
+2. Copy `message` into `title` and `query`
+3. Copy `globalContext`
+4. Select skills through `SkillSelector.select(...)`
+5. Build the initial transcript through `PromptAssembler.buildInitialTranscript(...)`
+6. Persist the session through `AgentSessionStore.save(...)`
+7. Publish `SESSION_STARTED`
+8. Enter the execution loop through `runTurn(...)`
+
+### 3.2 Skill selection flow
+
+Relevant classes:
+
+- `src/main/java/com/example/agent/application/service/SkillSelector.java`
+- `src/main/java/com/example/agent/application/service/LlmSkillRouter.java`
+- `src/main/java/com/example/agent/application/service/RuleBasedSkillSelector.java`
+- `src/main/java/com/example/agent/application/service/SkillRegistry.java`
+
+Logic:
+
+1. `SkillRegistry` loads all enabled skills from:
+   - `src/main/resources/skills/*/SKILL.md`
+2. `SkillSelector.select(...)` first calls:
+   - `LlmSkillRouter.route(query, globalContext, allSkills)`
+3. `LlmSkillRouter` sends a lightweight router prompt to `LlmClient`
+4. The model returns JSON:
+
+```json
+{
+  "selectedSkillIds": [
+    "finance-semantic-analysis",
+    "finance-reporting"
+  ],
+  "reason": "analysis and report requested"
+}
+```
+
+5. If routing fails, returns empty, or returns invalid skill ids, `SkillSelector` falls back to:
+   - `RuleBasedSkillSelector.select(...)`
+
+Important point:
+
+- The LLM does not directly open every tool by default
+- It first chooses skills
+- Skills then constrain the allowed tool set
+
+### 3.3 Prompt assembly
+
+Relevant class:
+
+- `src/main/java/com/example/agent/application/service/PromptAssembler.java`
+
+`PromptAssembler.systemPrompt(...)` builds the system prompt from:
+
+1. Base agent instructions
+2. Runtime metadata
+3. Full markdown content of selected `SKILL.md` files
+4. Allowed tool list from `ToolRegistry`
+
+So the active prompt structure is:
+
+1. Base runtime rules
+2. User/tenant/channel metadata
+3. Selected skill markdown
+4. Tool whitelist
+
+### 3.4 Turn loop
+
+Relevant class:
+
+- `src/main/java/com/example/agent/application/service/AgentTurnRunner.java`
+
+Core method:
+
+- `runTurn(AgentSession session, String userMessage, boolean resumed)`
+
+Loop logic:
+
+1. Publish `TURN_STARTED`
+2. Resolve selected skills again for the session
+3. Derive allowed tools from selected skills
+4. Ensure transcript[0] contains the latest system prompt
+5. Call:
+   - `llmClient.chat(session.getTranscript(), allowedTools)`
+6. Publish `MODEL_DECISION`
+7. If the model returned `tool_calls`:
+   - append assistant tool-call message
+   - for each tool call:
+     - publish `TOOL_CALL_REQUESTED`
+     - parse JSON arguments
+     - execute through `ToolExecutionPipeline.execute(...)`
+     - append the tool result as a `tool` message
+     - if async:
+       - mark session `WAITING_ASYNC_CALLBACK`
+       - publish `TURN_FINISHED`
+       - return
+   - otherwise continue next loop round
+8. If the model returned plain assistant content:
+   - append final assistant message
+   - set session status `SUCCEEDED`
+   - publish `ASSISTANT_MESSAGE`
+   - if tool steps exist, compile DSL
+   - publish `DSL_COMPILED`
+   - publish `TURN_FINISHED`
+   - return
+9. If max rounds exceeded:
+   - mark session `FAILED`
+   - publish `TURN_FINISHED`
+
+---
+
+## 4. Tool Execution Logic
+
+### 4.1 Tool registry
+
+Relevant class:
+
+- `src/main/java/com/example/agent/application/service/ToolRegistry.java`
+
+Current registered tools:
+
+- `sample_sessions_by_keywords`
+- `query_customer_sessions_mysql`
+- `query_sessions_handle`
+- `analyze_keywords_async`
+- `build_keyword_report`
+
+Each tool defines:
+
+- `toolId`
+- `description`
+- `endpoint`
+- `resultType`
+- `async`
+- `inputSchema`
+
+### 4.2 Tool execution pipeline
+
+Relevant class:
+
+- `src/main/java/com/example/agent/application/service/ToolExecutionPipeline.java`
+
+Main method:
+
+- `execute(session, turnId, toolCallId, toolName, args, allowedTools)`
+
+Execution steps:
+
+1. Create `ToolExecutionResult`
+2. Publish `TOOL_EXECUTION_STARTED`
+3. Validate that `toolName` is in the allowed tool set
+4. Validate required args from schema
+5. Build a `ToolCommand`
+6. Call `ToolExecutor.execute(...)`
+7. Normalize tool result into a standard payload
+8. Record an `AgentExecutedStep`
+9. If result is async:
+   - insert pending async job into `AsyncJobRepository`
+   - set `session.waitingExternalJobId`
+   - publish `WAITING_ASYNC_CALLBACK`
+10. Else:
+   - publish `TOOL_EXECUTION_FINISHED`
+
+### 4.3 Tool executor implementation
+
+Relevant class:
+
+- `src/main/java/com/example/agent/infrastructure/tool/ToolsApiToolExecutor.java`
+
+This is the active `ToolExecutor`.
+
+Behavior:
+
+1. Resolve tool metadata from `ToolRegistry`
+2. If `tools.base-url=local://tools`
+   - call `ToolsController` directly in-process
+3. Else
+   - call the configured HTTP tool endpoint
+4. Convert the controller response into `ToolResult`
+5. For `analyze_keywords_async`, optionally schedule auto callback in local test/demo mode
+
+### 4.4 Tool controller mapping
+
+Relevant class:
+
+- `src/main/java/com/example/agent/interfaces/rest/ToolsController.java`
+
+Mappings:
+
+- `sample_sessions_by_keywords`
+  - uses `SessionRepository.sampleSessionsByKeywords(...)`
+- `query_customer_sessions_mysql`
+  - uses `CustomerSessionQueryService.query(...)`
+- `query_sessions_handle`
+  - currently generates a mock handle id
+- `analyze_keywords_async`
+  - currently generates a mock async job id
+- `build_keyword_report`
+  - currently generates a mock report id and keyword list
+
+Important note:
+
+- The main planning/execution loop is real
+- Some tools are still demo implementations, especially:
+  - `query_sessions_handle`
+  - `analyze_keywords_async`
+  - `build_keyword_report`
+
+---
+
+## 5. Async Callback and Resume Flow
+
+Relevant classes:
+
+- `src/main/java/com/example/agent/interfaces/rest/AgentRuntimeController.java`
+- `src/main/java/com/example/agent/application/service/AgentTurnRunner.java`
+- `src/main/java/com/example/agent/infrastructure/repository/AsyncJobRepository.java`
+
+Flow:
+
+1. `analyze_keywords_async` returns `ASYNC_JOB`
+2. `ToolExecutionPipeline` stores a pending job in `async_job`
+3. Session status becomes `WAITING_ASYNC_CALLBACK`
+4. External system posts callback to:
+   - `POST /api/agent/tool-callback`
+5. `AgentRuntimeController.toolCallback(...)`:
+   - loads pending job by `externalJobId`
+   - publishes `TOOL_CALLBACK_RECEIVED`
+   - calls `AgentTurnRunner.appendToolObservation(...)`
+   - publishes `TOOL_EXECUTION_FINISHED`
+   - calls `AgentTurnRunner.resumeSession(...)`
+6. `appendToolObservation(...)` updates the existing `tool` message by `toolCallId`
+7. `resumeSession(...)` restarts the same turn loop with updated transcript state
+
+This avoids the invalid message ordering bug where multiple unrelated `tool` messages followed a single assistant tool-call message.
+
+---
+
+## 6. DSL Compilation and Replay
+
+### 6.1 Compilation
+
+Relevant class:
+
+- `src/main/java/com/example/agent/application/service/DslCompilerService.java`
+
+Compilation trigger:
+
+- after a turn succeeds and `session.executedSteps` is not empty
+
+Compilation logic:
+
+1. Create `ExecutableDslSnapshot`
+2. Copy session metadata
+3. Walk `session.executedSteps`
+4. Keep only successful steps
+5. Convert them to ordered `ExecutableDslStep` list
+6. Persist snapshot through:
+   - `DslInstanceRepository`
+   - `DslStepRepository`
+
+### 6.2 Replay
+
+Relevant class:
+
+- `src/main/java/com/example/agent/application/service/DslRuntimeService.java`
+
+Replay logic:
+
+1. Load DSL instance and steps
+2. Create a replay-only `AgentSession`
+3. Execute each DSL step through `ToolExecutionPipeline`
+4. Persist replay execution result through `DslExecutionLogRepository`
+
+Important point:
+
+- DSL replay does not invoke the LLM
+- It directly replays the persisted tool trajectory
+
+---
+
+## 7. Persistence Model
+
+### 7.1 Session and event persistence
+
+Relevant repositories:
+
+- `src/main/java/com/example/agent/infrastructure/repository/AgentSessionRepository.java`
+- `src/main/java/com/example/agent/infrastructure/repository/AgentEventRepository.java`
+- `src/main/java/com/example/agent/infrastructure/repository/AsyncJobRepository.java`
+
+These persist:
+
+- agent session snapshots
+- event history
+- pending async jobs
+
+### 7.2 DSL persistence
+
+Relevant repositories:
+
+- `src/main/java/com/example/agent/infrastructure/repository/DslInstanceRepository.java`
+- `src/main/java/com/example/agent/infrastructure/repository/DslStepRepository.java`
+- `src/main/java/com/example/agent/infrastructure/repository/DslExecutionLogRepository.java`
+
+These persist:
+
+- DSL metadata
+- ordered replay steps
+- replay logs
+
+### 7.3 Customer session data access
+
+Relevant repositories:
+
+- `src/main/java/com/example/agent/infrastructure/repository/CustomerSessionMysqlRepository.java`
+- `src/main/java/com/example/agent/infrastructure/repository/SessionRepository.java`
+
+Split:
+
+- `CustomerSessionMysqlRepository`
+  - real MySQL customer session table
+- `SessionRepository`
+  - current sample-session data source for `sample_sessions_by_keywords`
+
+---
+
+## 8. LLM Layer
+
+Relevant classes:
+
+- `src/main/java/com/example/agent/domain/port/LlmClient.java`
+- `src/main/java/com/example/agent/infrastructure/llm/DummyLlmClient.java`
+
+Despite the class name, `DummyLlmClient` is the real active OpenAI-compatible HTTP client.
+
+It is configured by:
+
+- `src/main/resources/application.yml`
+
+Main config:
+
+```yaml
+llm:
+  provider: deepseek
+  api-key: ${DEEPSEEK_API_KEY:}
+  base-url: https://api.deepseek.com/v1/chat/completions
+  model: deepseek-chat
+  routing:
+    enabled: true
+```
+
+Qwen example:
+
+```yaml
+llm:
+  provider: qwen
+  api-key: ${QWEN_API_KEY:}
+  base-url: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
+  model: qwen3-235b-a22b
+  routing:
+    enabled: true
+```
+
+The same client is used for:
+
+- skill routing
+- main turn planning and tool selection
+
+---
+
+## 9. Current Call Graph
+
+### 9.1 High-level runtime graph
+
+```mermaid
+flowchart TD
+    A["POST /api/agent/sessions"] --> B["AgentSessionController.createSession"]
+    B --> C["AgentTurnRunner.startSession"]
+    C --> D["SkillSelector.select"]
+    D --> E["LlmSkillRouter.route"]
+    D --> F["RuleBasedSkillSelector.select (fallback)"]
+    C --> G["PromptAssembler.buildInitialTranscript"]
+    C --> H["AgentSessionStore.save"]
+    C --> I["AgentTurnRunner.runTurn"]
+    I --> J["LlmClient.chat"]
+    J --> K{"tool_calls?"}
+    K -->|yes| L["ToolExecutionPipeline.execute"]
+    L --> M["ToolsApiToolExecutor.execute"]
+    M --> N["ToolsController / HTTP tools"]
+    L --> O["AsyncJobRepository.insertPendingAgentJob"]
+    L --> P["RuntimeEventBus.publish"]
+    O --> Q{"async?"}
+    Q -->|yes| R["WAITING_ASYNC_CALLBACK"]
+    Q -->|no| I
+    K -->|no| S["Assistant final answer"]
+    S --> T["DslCompilerService.compile"]
+    T --> U["DslInstanceRepository + DslStepRepository"]
+```
+
+### 9.2 Async callback graph
+
+```mermaid
+flowchart TD
+    A["POST /api/agent/tool-callback"] --> B["AgentRuntimeController.toolCallback"]
+    B --> C["AsyncJobRepository.findByExternalJobId"]
+    C --> D["RuntimeEventBus.publish(TOOL_CALLBACK_RECEIVED)"]
+    D --> E["AgentTurnRunner.appendToolObservation"]
+    E --> F["Update existing tool message by toolCallId"]
+    F --> G["AgentTurnRunner.resumeSession"]
+    G --> H["AgentTurnRunner.runTurn"]
+    H --> I["LlmClient.chat with updated transcript"]
+```
+
+### 9.3 DSL replay graph
+
+```mermaid
+flowchart TD
+    A["POST /api/agent/dsl/{dslId}/execute"] --> B["AgentSessionController.executeDsl"]
+    B --> C["DslRuntimeService.execute"]
+    C --> D["DslInstanceRepository.findById"]
+    C --> E["DslStepRepository.findByDslId"]
+    C --> F["Create replay AgentSession"]
+    C --> G["ToolExecutionPipeline.execute (for each step)"]
+    G --> H["ToolsApiToolExecutor.execute"]
+    C --> I["DslExecutionLogRepository.insert"]
+```
+
+---
+
+## 10. Class Responsibilities Summary
+
+### Runtime orchestration
+
+- `AgentTurnRunner`
+  - owns the turn loop
+- `SkillSelector`
+  - chooses skills
+- `PromptAssembler`
+  - builds system prompt and initial transcript
+- `ToolExecutionPipeline`
+  - validates, runs, normalizes, and records tool calls
+- `RuntimeEventBus`
+  - emits and streams runtime events
+
+### Persistence
+
+- `AgentSessionStore`
+  - serializes/deserializes `AgentSession`
+- `PlanRuntimeService`
+  - returns session runtime snapshot
+- `DslCompilerService`
+  - compiles successful sessions into DSL
+- `DslRuntimeService`
+  - replays DSL
+
+### LLM and skill routing
+
+- `DummyLlmClient`
+  - active OpenAI-compatible LLM HTTP client
+- `LlmSkillRouter`
+  - asks the model to choose skills
+- `RuleBasedSkillSelector`
+  - deterministic fallback
+- `SkillRegistry`
+  - loads `SKILL.md`
+
+### Tool access
+
+- `ToolRegistry`
+  - tool metadata and schema
+- `ToolsApiToolExecutor`
+  - actual tool invocation bridge
+- `ToolsController`
+  - local/internal tool endpoints
+- `CustomerSessionQueryService`
+  - real MySQL customer session query service
+
+---
+
+## 11. Known Limitations
+
+1. Tool streaming is event-level, not token-level LLM streaming
+2. `query_sessions_handle`, `analyze_keywords_async`, and `build_keyword_report` are still mock-style business implementations
+3. `DummyLlmClient` is badly named for a real LLM client and should be renamed
+4. `sample_sessions_by_keywords` still uses the demo `session_table`, while `query_customer_sessions_mysql` uses the real MySQL table
+5. DSL replay only replays tools; it does not replay LLM decisions
+
+---
+
+## 12. Recommended Next Refactors
+
+1. Rename `DummyLlmClient` to `OpenAiCompatibleLlmClient`
+2. Replace mock tool implementations with real business services
+3. Unify `sample_sessions_by_keywords` onto the real MySQL or warehouse source
+4. Add token-level LLM streaming and expose it through SSE
+5. Add stronger tool policy controls, timeout policies, and retry policies per tool