# risk-agent-java

**Repository Path**: greycode/risk-agent-java

## Basic Information

- **Project Name**: risk-agent-java
- **Description**: 风险识别智能体 (Risk Deep Agents)
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-25
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 风险识别智能体 (Risk Deep Agents) - Java 版

> **版本**: 1.1 (Java Rewrite)
> **设计目标**: 实现基于 LangChain/Deep Agents 范式的分层式、并行化风控分析系统

这是 Risk Deep Agents 系统的 Java 移植版本，利用 `agent-sdk` 实现了智能体模式 (Agentic patterns) 和工具管理。

## 1. 整体架构 (Architecture)

系统采用 **三层分层架构 (Tiered Architecture)**，通过 `OrchestratorAgent` 作为核心指挥中枢，向下调度专家子智能体，子智能体进一步调度原子工具或更细粒度的执行单元。

### 1.1 架构全景图

```ascii
+---------------------------------------------------------------------------------------------------+
|                                  Risk Deep Agent System (Java)                                    |
+---------------------------------------------------------------------------------------------------+
|                                                                                                   |
|  [用户接口 User Interface]                                                                        |
|  Command Line / API <-------> RiskDeepAgentApp (Entry Point)                                      |
|                                     |                                                             |
|                                     v                                                             |
|  [运行时基础设施 Runtime Infrastructure]                                                          |
|  +--------------------+   +--------------------+   +--------------------+   +-------------------+ |
|  |  WorkflowRuntime   |   |  AsyncTaskManager  |   |    TaskRegistry    |   |  SandboxContext   | |
|  | (State/Persistence)|   | (Thread Pool Exec) |   | (Task Tracking)    |   | (File System)     | |
|  +--------------------+   +--------------------+   +--------------------+   +-------------------+ |
|                                     |                                                             |
|                                     v                                                             |
|  [Tier 1: 核心编排层 Orchestration Layer]                                                         |
|  +---------------------------------------------------------------------------------------------+  |
|  |                              OrchestratorAgent                                              |  |
|  |  (职责: 任务分解, 进度管理, 错误恢复, 最终汇总)                                             |  |
|  |  工具: TodoTools, FileSystemTools, ApprovalTools, *SubAgentTool*                            |  |
|  +---------------------------------------------------------------------------------------------+  |
|               |                             |                             |                       |
|   delegate()  |                 safe_task() |                 delegate()  |            delegate() |
|               v                             v                             v                       |
|  [Tier 2: 专家分析层 Domain Analysis Layer]                                                       |
|  +--------------------+   +-----------------------+   +--------------------+   +----------------+ |
|  |   RiskDiscovery    |   |   RiskPointAnalyst    |   |    RuleGenerator   |   | ReportGenerator| |
|  | (Doc -> Risks JSON)|   | (Risk -> Evidence)    |   | (Report->Groovy)   |   | (JSON -> MD)   | |
|  | Tools: FS, SubAgent|   | Tools: FS, SubAgent   |   | Tools: Rule, FS    |   | Tools: Report  | |
|  +--------------------+   +-----------------------+   +--------------------+   +----------------+ |
|                                     |                                                             |
|                        safe_task()  | (Parallel Execution)                                        |
|                                     v                                                             |
|  [Tier 3: 数据与执行层 Data & Execution Layer]                                                    |
|  +---------------------------------------------------------------------------------------------+  |
|  |                               DataCollector (xN)                                            |  |
|  |  (职责: 执行具体 SQL, API 调用, 日志 Grep, 验证假设)                                        |  |
|  |  工具: DataCollectorTools (JDBC), GrepTools, FileSystemTools                                |  |
|  +---------------------------------------------------------------------------------------------+  |
|                                                                                                   |
|  [外部依赖 External Systems]                                                                      |
|  +------------------+     +------------------+     +------------------+                           |
|  |    User LLM      |     |   Business DBs   |     |   Project Files  |                           |
|  | (Claude/OpenAI)  |     | (MySQL/SQLite)   |     | (Docs/Rules/Rpts)|                           |
|  +------------------+     +------------------+     +------------------+                           |
+---------------------------------------------------------------------------------------------------+
```

### 1.2 核心组件

*   **Tier 1 (Orchestrator)**: 主要负责任务流的编排。它不直接干活，而是通过 `SubAgentTool` 调度下游的专家智能体。
*   **Tier 2 (Domain Agents)**:
    *   `Risk Discovery`: 扫描文档，发现潜在的风险点。
    *   `Risk Point Analyst`: 对具体的风险点进行深度分析和验证。**支持并行执行**。
    *   `Rule Generator`: 针对确认的风险编写 Groovy 规则。
    *   `Report Generator`: 汇总所有的发现和规则，生成 Markdown/HTML 报告。
*   **Tier 3 (Execution Agents)**:
    *   `Data Collector`: 执行具体的数据库查询 (SQL) 或日志分析 (Grep)。

## 2. 核心流程 (Core Workflow)

系统遵循 **"发现 -> 分析 -> 规则 -> 报告"** 的标准作业流程。

```ascii
Start (User Command: "Analyze order_flow.md")
|
v
[OrchestratorAgent 启动]
|
+---> 1. [Risk Discovery] (风险发现)
|     |
|     +-- 读取 markdown 文档
|     +-- 识别风险场景
|     +-- 生成 /analysis/{doc}/risks.json
|     v
|
+---> 2. [Risk Point Analysis] (并行风险分析) <---------------------------+
|     | (Loop over each risk in risks.json)                               |
|     |                                                                   |
|     +-- [RiskAnalyst #1]      [RiskAnalyst #2]      ... [RiskAnalyst #N]|
|         |                     |                                         |
|         v                     v                                         |
|      (思考假设)            (思考假设)                                   |
|         |                     |                                         |
|         v                     v                                         |
|    [DataCollector]       [DataCollector]  (Sub-task Dispatch)           |
|    (SQL/Grep/API)        (SQL/Grep/API)                                 |
|         |                     |                                         |
|         v                     v                                         |
|      (验证结果)            (验证结果)                                   |
|         |                     |                                         |
|         v                     v                                         |
|     Generate              Generate                                      |
|   risk_1_report.json    risk_2_report.json                              |
|                                                                         |
+---> 3. [Rule Generation] (规则生成 - 仅针对高危风险)
|     |
|     +-- 读取 risk_N_report.json
|     +-- 编写 Groovy 规则代码
|     +-- [Human Approval] (人工审批: HITL) --(Reject)--> 修改
|     |           | (Approve)
|     +-----------+-> 保存 .groovy 文件
|     v
|
+---> 4. [Report Generation] (报告汇总)
|     |
|     +-- 聚合所有 .json 报告和 .groovy 规则
|     +-- 生成最终 Summary Report (MD + HTML)
|     v
|
End (Final Response to User)
```

## 3. 关键特性 (Key Features)

*   **并行执行 (Parallel Execution)**: 利用 `AsyncTaskManager` 和 `CompletableFuture` 实现风险点分析的并行处理，大幅缩短长文档的分析时间。
*   **运行时状态管理 (Runtime Infrastructure)**:
    *   `WorkflowRuntime`: 维护全局的状态机，追踪任务进度。
    *   `TaskRegistry`: 记录子任务的执行状态、耗时和结果。
*   **工具权限隔离**: 每个层级的智能体仅能通过 `SubAgentTool` 访问其权限范围内的工具，确保安全。

## 4. 环境准备

- JDK 21+
- Maven 3.9+
- LLM API Key (Demo 模式下可选)：
    - `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` 等。

## 5. 项目结构

- `src/main/java/com/risk/agent`: 源代码。
  - `prompts/`: Prompt 加载逻辑（资源文件在 `src/main/resources/prompts/`）。
  - `tools/`: Python 工具的 Java 实现。
  - `mock/`: 模拟 LLM 实现，用于零成本测试。
  - `runtime/`: 运行时状态管理与异步任务调度。
- `data/`: 智能体的沙盒根目录。
  - `business_docs/`: 输入文档。
  - `analysis/`: 中间分析结果。
  - `rules/`: 生成的规则。
  - `reports/`: 最终生成的报告。

## 6. 如何运行

### 6.1 编译项目
```bash
mvn clean compile
```

### 6.2 运行 Demo (模拟模式)
使用模拟的 LLM 运行完整工作流（无需 API Key）。
```bash
mvn exec:java -Dexec.mainClass="com.risk.agent.RiskDeepAgentApp" -Dexec.args="data/business_docs/test_flow.md demo"
```

### 6.3 使用真实 LLM 运行
设置你的 API Key，运行时不带 `demo` 参数。
```bash
export ANTHROPIC_API_KEY=sk-ant-...
mvn exec:java -Dexec.mainClass="com.risk.agent.RiskDeepAgentApp" -Dexec.args="data/business_docs/test_flow.md"
```

### 6.4 通过代码配置启动
当你需要在代码中显式设置配置时，可以使用 `AppConfig` 构建 overrides 并通过 `RiskDeepAgentApp.run` 启动。配置优先级为：**AppConfig > System Property > 环境变量 > 默认值**。

```java
AppConfig config = AppConfig.builder()
        .set("DATA_ROOT", "data")
        .set("DB_DEMO_MODE", false)
        .set("DB_URL", "jdbc:mysql://localhost:3306/risk_control")
        .set("RUN_STORE", "sqlite")
        .build();

RiskDeepAgentApp.run(config, new String[] { "demo" });
```

### 6.5 Spring Boot Web 运行
默认使用 `application.yml` 作为配置入口，启动后可通过 HTTP 触发任务与查询状态。

启动：
```bash
mvn -DskipTests spring-boot:run
```

触发任务：
```bash
curl -X POST http://localhost:8080/api/runs \
  -H 'Content-Type: application/json' \
  -d '{"task":"Analyze order_flow.md","docName":"order_flow"}'
```

查询状态：
```bash
curl http://localhost:8080/api/runs/{runId}
curl http://localhost:8080/api/runs/{runId}/tasks
curl http://localhost:8080/api/runs/{runId}/events
```

生成简单报告：
```bash
curl -X POST http://localhost:8080/api/reports/simple \
  -H 'Content-Type: application/json' \
  -d '{"docName":"order_flow","outputHtml":true}'
```

## 7. 自定义开发

- **工具**: 在 `src/main/java/com/risk/agent/tools` 中添加新工具。
- **提示词**: 修改 `src/main/resources/prompts/` 或设置 `PROMPT_ROOT` 覆盖。
- **数据库**: 更新 `DatabaseTools.java` 以连接到真实的数据库。
- **配置**: 配置项说明见 `docs/configuration.md`。