AfterSaleFlow-Agent：AI Native 履约争端审理系统

核心设计目标#

六站争议旅程#

1
flowchart LR
2
    O[争议办理总览] --> I1[发起方私有接待]
3
    I1 -->|不予受理| N[NOT_ADMISSIBLE]
4
    I1 -->|争议已解决| C[CANCELLED]
5
    I1 -->|确认受理并发传票| I2[相对方私有接待]
6
    I2 -->|完成独立陈述| E[双方私有证据室]
7
    E -->|双方完成或举证到期| H[hearing_flow.v2 智能庭审]
8
    H --> D[V2 非最终裁决草案]
9
    D --> R[平台人工终审]
10
    R -->|批准 / 修改后批准| X[确定性执行链]
11
    X --> U[裁决与执行结果]
12
    R -->|退回补证| E
13
    R -->|拒绝 / 人工升级| M[不自动执行]

hearing_flow.v2 固定 15 阶段#

人工终审决策#

平台审核员可以提交五类决定：

• APPROVE
• MODIFY_AND_APPROVE
• REQUEST_MORE_EVIDENCE
• REJECT
• ESCALATE_MANUAL

其中只有前两类可以生成批准动作快照并进入 Tool Executor；其余决定均不会触发退款、补发或关单。

专业角色#

多维 Critic 合议#

系统提供五个窄职责 Critic，对同一冻结输入独立评估：

• Evidence Critic：证据充分性、引用关系与事实支撑风险
• Rule Critic：规则版本、适用条件与论证完整性
• Risk Critic：案件风险、异常模式与潜在升级点
• Remedy Critic：补救方案、金额约束和可执行性
• Fairness Critic：相似案件一致性、程序公平与偏差风险

合议面板以冻结输入指纹绑定所有报告；任一 Critic 不可用时不会伪装成“无异议”，而是显式转入 MANUAL_REVIEW_REQUIRED。阻断级意见触发 REVISION_REQUIRED，少数意见和失败状态都会保留给审核员。

Agent Harness：把模型调用变成受治理的认知事务#

Python 侧不是任意 Prompt 调用集合，而是由 Harness 统一约束：

1
可信 Invocation Context
2
  -> Context Pack / State Lens
3
  -> Prompt 与不可信案件内容分离
4
  -> LangGraph / LCEL 节点执行
5
  -> Provider JSON Schema
6
  -> Pydantic 校验
7
  -> 引用白名单与业务 Guardrail
8
  -> 可见字段流式投影
9
  -> 结构化 Proposal
10
  -> Java Finalizer

主要治理能力包括：

• 身份与作用域绑定：actor、角色、case、room、audience、Prompt/Model/Tool Profile 均由服务端创建，浏览器不能覆盖。
• 默认拒绝的 Agent Profile：显式声明可运行案件状态、上下文范围、Skill、工具、风险策略和输出 Schema。
• LoopBudget：每个角色拥有独立的迭代、工具调用、模型调用、Token、截止时间、停滞检测和修复预算。
• 上下文最小化：Context Pack 和 State Lens 只选择当前节点需要的字段；私有接待和证据会话不进入共享庭审上下文。
• 多模态授权：图片像素仅能通过内部 EvidenceAssetLoader 按清单加载；模型不能声称看过未加载材料。
• 确定性后处理：稳定 ID、去重、排序、矩阵合并、哈希、权限、截止时间和流程推进不交给模型。
• 隐藏推理保护：不请求、不持久化、不流式暴露 chain-of-thought；公开流仅包含服务端白名单字段。

一次 AgentRun 的正式提交路径#

1
sequenceDiagram
2
    participant UI as Vue Client
3
    participant J as Java API / Domain Ledger
4
    participant T as Temporal / Worker
5
    participant P as Python Agent Runtime
6
    participant L as LiteLLM / Model
7

8
    UI->>J: 授权命令 + Idempotency-Key
9
    J->>J: 写入命令/消息/AgentRun 账本
10
    J->>T: 调度持久任务或当前执行器
11
    T->>P: 受约束的结构化请求
12
    P->>L: Prompt + JSON Schema + Model Profile
13
    L-->>P: 流式模型输出
14
    P-->>J: NDJSON visible_delta / usage / final
15
    J->>J: 持久化流、校验 Schema、引用与版本绑定
16
    J->>J: Finalizer 提交正式消息或工件
17
    J-->>UI: SSE 回放与实时投影

1. 一类状态只有一个权威写入者#

该拆分避免 Java、Temporal 和 LangGraph 同时计算“下一阶段”，也避免模型输出直接覆盖业务账本。

2. Java 领域服务与控制平面#

同一 Java 21 / Spring Boot 镜像通过 Profile 拆为三个独立进程：

Java 内部以领域模块组织案件、接待、证据、庭审、合议、审核、执行、通知、审计和 AgentRun。数据库由 Flyway 管理，Hibernate 使用 ddl-auto=validate，正式消息、动作和审计事实采用追加写与约束保护。

3. Temporal 持久化流程平面#

正式协议队列按故障域拆分：

1
case-control
2
room-control
3
agent-execution
4
notification-and-tools

当前 release/0.1.0 的默认业务路径仍以 Java 状态机为主，Temporal 已实际管理 2 小时举证窗口、双方完成 Signal、提醒与到期 Activity；case-dispute-task-queue 是 EvidenceWindow 的兼容队列。目标架构代码进一步提供 Case/Room Workflow、命令 outbox、单调 revision、fencing、Continue-As-New 与投影 reconciliation，但默认开关保持 fail-closed。

4. Python 认知平面#

Python Agent Service 只暴露内部 FastAPI 接口，承担两类执行：

• 当前正式路径：接待与证据使用受治理的单轮 LangGraph；庭审由四个显式 Hearing Graph Family 承载七个一次调用操作，但 15 阶段 cursor、等待和正式工件提交仍由 Java 管理；另包含 Review Copilot 与离线 Evaluation。
• 目标架构候选：intake.v2、evidence.v2、Outcome Review Graph，以及将现有 Hearing Graph Family 接入持久 Graph Gateway 的运行路径；候选平台增加 PostgreSQL checkpoint、命令账本、lease/fencing、版本注册表和 proposal-only 跨服务协议。

Hearing 认知拓扑按职责拆成四个显式 family：

1
hearing.intake.v1   -> intake questions / intake synthesis
2
hearing.evidence.v1 -> evidence requests / evidence synthesis
3
hearing.judge.v1    -> judge V1 / judge V2
4
hearing.jury.v1     -> jury review

每个拓扑都是显式 typed StateGraph，未知路由失败关闭；证据 fan-out 使用稳定键 reducer 和有界并发，不允许最后写入覆盖冲突。

5. 当前默认路径与目标候选路径#

这一区分是项目可信度的重要组成部分：仓库包含面向生产终态的高强度工程实现和验证合同，但不会把默认关闭的候选能力包装成已经上线的生产事实。

6. Schema-first 跨服务合同#

contracts/agent-platform/v1 将跨服务边界固定为 JSON Schema，包括：

• case-command-ref
• room-graph-command
• room-graph-result
• agent-stream-event
• agent-execution-manifest
• artifact-ref
• process-projection
• graph-reconcile-response
• compatibility matrix 与正反向 fixtures

目标路径使用 RFC 8785 JSON Canonicalization 与 SHA-256 绑定请求、结果和工件；Java 与 Pydantic 类型在接收端再次验证 Schema、ID、版本、作用域和哈希。跨服务接口传递引用和摘要，而不是把完整证据、矩阵或 PII 放进 Temporal History。

可恢复的流式交互#

• Python → Java 使用 NDJSON 流；Java 先持久化，再向浏览器提供 SSE。
• 案件流与 AgentRun 流都支持持久化 cursor、受众过滤、心跳和断线重放。
• 浏览器通过 Last-Event-ID 从 PostgreSQL 高水位继续读取，Redis 仅用于低延迟唤醒。
• visible_delta 只是临时预览；终态必须唯一，终态后禁止继续发送帧。
• raw JSON、工具参数、私有矩阵、内部 A2A 内容和隐藏推理不进入公开流。

幂等、顺序与故障恢复#

• 所有写操作使用 Idempotency-Key 或服务端生成的稳定命令 ID。
• 同一 ID 与同一请求哈希返回既有结果；同一 ID 搭配不同内容返回冲突。
• 案件事件、消息、阶段动作与 Agent 流使用单调 sequence，网络到达顺序不等于业务顺序。
• 当前与目标路径均保留 AgentRun 账本；目标路径进一步拆分 logical run、attempt 和 stream event。
• 正式副作用通过 ActionRecord、外部幂等键、结果查询和补偿/人工恢复路径防止重复执行。
• 系统不宣称网络级 exactly-once，而是通过 at-least-once delivery + idempotency + fencing 获得业务等价的一次提交语义。

审理与副作用双重闸门#

1
Agent Proposal
2
  -> Java Schema / Reference / Policy Finalizer
3
  -> Platform Human Review
4
  -> Approval Policy Engine
5
  -> Tool Executor
6
  -> ActionRecord / External Receipt
7
  -> Read-only Outcome Projection

Tool Executor 不接受“模型建议执行”作为授权。它必须重新验证审批记录、动作快照版本与哈希、有效期、操作者角色、风险策略和幂等键。当前本地环境默认启用模拟执行，不对真实退款或履约系统做生产能力声明。

安全与隐私#

• Java 是唯一外部 API 与授权边界，/internal/** 不经 Nginx 对浏览器开放。
• 当前内部调用要求 service identity/secret；目标候选支持 mTLS 与短时 ES256 签名调用信封。
• 信封绑定 tenant surrogate、case、room epoch、actor scope、command、nonce、capability、profile version 与 payload hash。
• USER/MERCHANT 资源按精确 actor ID 和参与关系校验，不能仅按角色过滤。
• 用户文本、商家文本和证据内容始终作为不可信 Prompt 输入，不能改变 system policy。
• 上传文件校验扩展名、MIME、大小和内容类型；原始与脱敏证据使用不同 Bucket。
• 日志屏蔽服务密钥、数据库密码、API Key 与完整敏感证据；CI 包含 Secret Scan。

可观测性#

系统通过 request ID、trace ID 和 OpenTelemetry context 串联：

1
Browser -> Java Command -> Outbox/Temporal -> AgentRun
2
        -> Python LangGraph -> LCEL -> LiteLLM -> Model Provider

• Langfuse：Prompt、模型、Token、Latency 和 Agent Trace
• Micrometer：Java 指标与 Prometheus 兼容度量
• OpenTelemetry / OTLP：跨 Java、Python、Temporal 与模型网关的 Trace
• LiteLLM：唯一模型路由、认证和 Provider 适配层
• 审计账本：角色、输入快照、版本、引用、结果哈希、审核和动作回执

前置条件#

• Docker Desktop，Linux 容器模式
• Docker Compose v2
• 至少 12 GB 可用内存、25 GB 可用磁盘
• Bash、curl、Python 3
• 有效的阿里云百炼 DASHSCOPE_API_KEY

一键启动完整环境#

1
git clone https://github.com/Jupiter363/AfterSaleFlow-Agent.git
2
cd AfterSaleFlow-Agent
3
git checkout release/0.1.0
4

5
cp .env.example .env
6
./scripts/generate-secrets.sh
7

8
# 编辑本地 .env，写入真实 DASHSCOPE_API_KEY；不要提交该文件
9
./scripts/dev-up.sh

dev-up.sh 会完成配置校验、镜像构建、健康检查和 Smoke Test。完整应用入口：

1
http://localhost:18080

停止服务并保留数据卷：

1
./scripts/dev-down.sh

明确清空本项目数据卷并重建：

1
CONFIRM_RESET=YES ./scripts/dev-reset.sh

Windows 快速开发#

保留数据库、Temporal、Python Agent、OCR 等依赖在 Docker 中，让 Java 与 Vite 直接运行：

1
.\scripts\dev-local.ps1

停止本地 Java/Vite：

1
.\scripts\dev-local.ps1 -Stop

本地 Vite 5173 会代理 Java 8080；Docker 全量环境必须从 Nginx 18080 进入。

公共 API 根#

1
/api/disputes       案件、房间、证据、庭审、草案、结果与事件流
2
/api/notifications  平台信箱、未读数与已读状态
3
/api/reviews        审核队列、冻结 Packet、Copilot 与人工决定

服务间接口统一位于 /internal/**，必须携带服务身份，且不会由 Nginx 暴露给浏览器。

本地完整发布检查#

1
python -m pytest tests/static -q
2

3
cd java-api-service
4
./mvnw -s .mvn/settings.xml -B -ntp test
5
cd ..
6

7
cd python-agent-service
8
python -m pytest -q
9
cd ..
10

11
cd ocr-parser-service
12
python -m pytest -q
13
cd ..
14

15
cd frontend
16
pnpm test
17
pnpm build
18
pnpm test:browser
19
cd ..
20

21
docker compose config --quiet
22
docker compose up -d --build --wait --wait-timeout 360
23
./scripts/smoke-test.sh
24
python -m pytest tests/api tests/e2e tests/load -q