| --- |
| title: Privacy Compliance Agent |
| emoji: 🛡️ |
| colorFrom: blue |
| colorTo: green |
| sdk: docker |
| pinned: false |
| --- |
| # 隐私合规协同场景 - 智能体服务层 (Privacy Compliance Agent Services) |
|
|
| 本项目为“银行智能体操作台系统”中的核心组件之一：**同业隐私协议跟踪与客户协议重构协同场景**的智能体服务层。该服务提供 4 个角色智能体（Agent）的标准化 API，专为云端部署的 **Dify** 平台工作流编排而设计。 |
|
|
| ## 🎯 业务目标 |
|
|
| 围绕“同业隐私协议跟踪与客户协议重构”场景，形成以下可执行的自动化能力链： |
| 1. **同业/监管变化摘要** (AGENT-01) |
| 2. **协议重构与建议** (AGENT-02) |
| 3. **合规校验** (AGENT-03) |
| 4. **法务审核包生成** (AGENT-04) |
|
|
| 通过 Dify 调用这些服务，可以完成从客户原始材料（协议、PRD、权限、SDK清单）到最终法务结构化审核包的完整 AI 处理链。 |
|
|
| --- |
|
|
| ## 🚀 核心特性 |
|
|
| - **高度结构化的输出 (JSON Schema)**：所有智能体 API 严格遵循预定义的 JSON Schema 输出数据，确保上下游节点（Dify）能够稳定解析。 |
| - **角色分离的智能体架构**：4 个智能体各司其职，不越权、不混淆（例如：协议重构智能体不负责输出最终合规结论，法务智能体不替代人工审批）。 |
| - **统一的上下文模型**：通过 `CaseContext` 对象贯穿整个生命周期，保证了上下文信息的完整传递。 |
| - **内置容错与 NFR 机制**：包含全局的请求日志追踪（`case_id`）、全局错误码映射（如 `4001` 缺材料、`5001` 推理失败）和重试友好型设计。 |
|
|
| --- |
|
|
| ## 🛠️ 技术栈 |
|
|
| - **Runtime**: [Node.js](https://nodejs.org/) (v16+) |
| - **Language**: [TypeScript](https://www.typescriptlang.org/) |
| - **Framework**: [Express.js](https://expressjs.com/) |
| - **Data Validation**: JSON Schema |
|
|
| --- |
|
|
| ## 📁 项目结构 |
|
|
| ```text |
| /workspace |
| ├── src/ |
| │ ├── index.ts # Express 服务入口与路由定义 |
| │ ├── llm.ts # 大模型调用核心逻辑（含 Prompt 占位与 Mock） |
| │ ├── middlewares.ts # 全局错误处理与日志追踪中间件 |
| │ ├── models/ # TypeScript 数据模型定义 (CaseContext 等) |
| │ └── schemas/ # JSON Schema 文件 (供外部系统校验使用) |
| ├── test.ts # 端到端串联测试脚本 |
| ├── package.json # 项目依赖与 npm 脚本 |
| ├── tsconfig.json # TypeScript 编译配置 |
| └── 方案.md # 原始业务需求与架构设计规格书 |
| ``` |
|
|
| --- |
|
|
| ## 🚦 快速开始 |
|
|
| ### 1. 环境准备 |
| 确保您的机器已安装 Node.js (推荐 v16.x 或以上版本)。 |
|
|
| ### 2. 安装依赖 |
| ```bash |
| npm install |
| ``` |
|
|
| ### 3. 启动服务 (开发模式) |
| ```bash |
| npm run dev |
| ``` |
| 服务默认启动在 `http://localhost:3000`。 |
|
|
| ### 4. 运行端到端测试 |
| 测试脚本会按顺序模拟 Dify 调用 4 个 API，并测试异常处理机制。 |
| ```bash |
| npx ts-node test.ts |
| ``` |
|
|
| --- |
|
|
| ## 🔌 API 接口文档 |
|
|
| 所有接口均采用 `POST` 方法，请求与响应格式均为 `application/json`。 |
|
|
| ### 1. 同业/监管变化摘要 (AGENT-01) |
| - **Endpoint**: `/api/agents/peer-reg-summary` |
| - **描述**: 归纳头部银行隐私协议及监管文件的关键变化。 |
| - **输入**: `peer_updates` (数组), `regulatory_updates` (数组), `app_name`, `business_line` |
| - **输出**: `PeerRegSummary` 对象 (包含 `peer_summary`, `reg_summary`, `reference_clauses` 等) |
|
|
| ### 2. 协议重构 (AGENT-02) |
| - **Endpoint**: `/api/agents/policy-rewrite` |
| - **描述**: 对比客户当前协议与 PRD/权限/SDK 清单的一致性，生成差异分析和修订建议。 |
| - **输入**: `case_context` (统一上下文), `peer_reg_summary` (来自 AGENT-01 的输出) |
| - **输出**: `GapAnalysis` 对象 (包含 `gaps`, `rewrite_suggestions`, `redline_seed` 等) |
|
|
| ### 3. 合规校验 (AGENT-03) |
| - **Endpoint**: `/api/agents/compliance-check` |
| - **描述**: 校验修订建议是否覆盖主要监管要求，并标出高风险项和待确认项。 |
| - **输入**: `case_context`, `gap_analysis` (来自 AGENT-02 的输出) |
| - **输出**: `ComplianceCheck` 对象 (包含风险等级、合规缺口清单、待法务确认项等) |
|
|
| ### 4. 法务审核包生成 (AGENT-04) |
| - **Endpoint**: `/api/agents/legal-pack` |
| - **描述**: 汇总前三个智能体的结果，生成法务可直接阅读的结构化审核包。 |
| - **输入**: `case_context`, `peer_reg_summary`, `gap_analysis`, `compliance_check` |
| - **输出**: `LegalReviewPack` 对象 (包含结构化审核包、审核建议等) |
|
|
| --- |
|
|
| ## 🔗 Dify 接入指南 |
|
|
| 本服务设计为无状态（Stateless）的 HTTP API，极易与 Dify 平台集成。 |
|
|
| 1. **工作流编排**：在 Dify 的 Workflow 中，使用 **HTTP Request** 节点依次串联这 4 个接口。 |
| 2. **上下文透传**：使用 Dify 的 Code 节点将文档解析（Document Extractor）和知识检索（Knowledge Retrieval）的结果组装为 `CaseContext` JSON，并在各 HTTP 节点间透传。 |
| 3. **错误重试**：本服务会在内部大模型推理失败时返回 `5001` 错误码，建议在 Dify 的 HTTP 节点配置 **重试机制（例如重试 1-2 次）**。 |
| 4. **渲染展示**：在 Dify 的尾部节点，使用 **Template (Jinja2)** 节点将 AGENT-04 输出的 JSON 格式化为 Markdown 审核包，最后交给 **Human Input** 节点进行法务人工确认。 |
|
|
| --- |
|
|
| ## 📝 后续开发注意事项 |
|
|
| - **替换真实的 LLM**：当前代码在 `src/llm.ts` 中使用了 Mock 数据（带有 5% 的随机失败率用于测试容错）。对接真实业务时，请在此文件内接入 OpenAI、Claude 或企业内部大模型 API，并填充真实的 System Prompt。 |
| - **扩展 JSON Schema**：如业务字段发生变更，请同步更新 `src/models/` 下的 TypeScript 接口与 `src/schemas/` 下的 JSON Schema 文件。 |
|
|
| --- |
| *版本：V1.0 | 适用范围：本地/服务端智能体服务开发，供云端 Dify 调用* |
