CrossAccess AI / 无碍智检

Important

🏆 OPC 2026 跨境半决赛成果展示与演示指南

项目成果与演示指南详见：👉 COMPETITION_RESULTS.md (半决赛成果展示与演示指南)

基于检测流水线，对网页或小程序的可访问性、适老化、跨境体验以及个人敏感信息保护进行自动检测，并输出整改清单与修复建议。

本项目定位为上线前的辅助检测与预诊断工具，不具有官方认证、法律审查或最终合规认定的效力。

---

快速启动（Docker）

cp backend/.env.example backend/.env   # 首次部署：复制模板并按需修改密码与 API Key
docker compose --env-file backend/.env up -d --build
# 或
make up

服务	地址
前端（Agent Demo）	http://localhost:3000
后端 API	http://localhost:8080/api/v1/health
MCP	POST http://localhost:8080/mcp
任务进度（SSE）	GET /api/v1/tasks/{task_id}/stream
MinIO 控制台	http://localhost:9001（账号见 backend/.env 中 MINIO_ROOT_USER / MINIO_ROOT_PASSWORD）

make health      # 健康检查
make ps          # 容器状态
make demo-check  # 演示链路自检
make logs        # 日志
make restart     # 重启
make down        # 停止
make clean       # 停止并删数据卷

说明

• 环境变量：统一写在 backend/.env；Compose 通过 --env-file backend/.env 读取（make up 已内置）。
• 对象存储：Docker Compose 默认 STORAGE_DRIVER=minio；本地直跑后端时可在 backend/.env 里改为 local + STORAGE_ROOT。
• 大模型：未配置 DEEPSEEK_API_KEY 时走内置规则模板，Demo 可不依赖外部 Key。
• Redis（可选）：docker compose --profile redis up 启用任务队列与查询缓存；未启用时在进程内 goroutine 执行。
• 截图（可选）：SCREENSHOT_DRIVER=playwright 时调用 Playwright CLI，否则用 1×1 占位 PNG。Docker 镜像内未装 Playwright，Compose 环境默认占位图；本地直跑后端且已安装 Playwright 时可启用真截图。
• 数据库：Docker Compose 使用库名 crossaccess_ai；backend/.env.example 里本地默认 wazj，直跑时需与本地 MySQL 一致。

---

演示流程（OPC 2026 跨境半决赛）

1. docker compose up -d --build
2. 打开 http://localhost:3000
3. 选「跨境电商结账页」快捷任务，可填真实 URL，也可留空走内置回退数据
4. 点「开始智能诊断」，等待 Timeline 8 步跑完（7 个 Skill；page_capture 在 Timeline 中展示为场景识别 + 采集两步）
5. 看跨境相关 finding（多语言、支付、币种/关税、配送、退货等）和数据保护 finding（隐私同意、Cookie 等）
6. 在 Agent Chat 里追问，例如：「如何降低跨境支付页面的合规风险？」
7. 勾选问题，导出整改清单 CSV
8. 如需展示 MCP：POST /mcp，method: tools/list

---

主要能力

• 页面分析：HTTP 拉 HTML，goquery 解析 DOM，按规则提取 Selector；支持 CSS 对比度计算（4.5:1）。
• 四类检测 Skill：可访问性、适老化、跨境体验、个人信息/残疾人数据保护（含跨境电商场景 finding 目录）。
• 整改建议：配置了 DeepSeek 时走 LLM；否则用内置模板。
• Agent Chat：基于项目上下文追问，同样支持 LLM / 规则回退。
• 导出：整改清单 CSV，含数据类型、敏感个人信息、残疾人相关字段等列。
• MCP：HTTP JSON-RPC（tools/list、tools/call、resources/read、prompts/get），与 REST 共用 usecase。
• 异步任务：页面采集、Agent 诊断异步执行；可选 Redis 队列。任务进度 API 支持轮询与 SSE；Agent Demo 前端目前用轮询。

---

实现情况

模块	状态
Agent + 7 个 Skill 流水线	可用
REST API	可用
真实 HTML / DOM 分析	可用
对比度检测	可用
跨境 / 数据保护 finding 目录	可用
LLM 整改建议 + 规则回退	可用
CSV 导出	可用
SSE 任务进度	可用
MCP JSON-RPC	可用
Redis 队列与缓存	可选
Playwright 截图	可选
OCR 截图分析	未做
Word / PDF 报告	未做

---

架构

Frontend (React + Vite + Tailwind)
        │  REST / SSE
API (chi)  —  /api/v1/*  +  POST /mcp
        │
UseCase (App + 按领域拆分的接口)
        │
Agent Orchestrator → Pipeline → Skills
        │
Adapters: MySQL · MinIO/本地存储 · DeepSeek/规则 LLM · Redis · Playwright 截图

Skill 顺序：page_capture → accessibility_rule_check → age_friendly_ux_check → cross_border_experience_check → personal_data_protection_check → ai_remediation_suggestion → remediation_export

---

API 一览

REST（前缀 /api/v1）

方法	路径	说明
POST	/agent/diagnose	发起 Agent 诊断，返回 task_id
POST	/agent/chat	诊断后追问
GET	/tasks/{task_id}	查询任务状态
GET	/tasks/{task_id}/stream	SSE 推送进度（轮询 GET 亦可）
GET	/health	健康检查
GET	/mcp/tools	MCP Tool 元数据（JSON，非 JSON-RPC）
*	/projects	项目 CRUD
*	/projects/{id}/pages	页面
*	/projects/{id}/findings	问题
POST	/projects/{id}/scan	规则包扫描
POST	/ai/impact-summary	影响说明生成
POST	/ai/fix-suggestion	修复建议生成
POST	/projects/{id}/reports	生成报告（整改清单 CSV 等）
GET	/reports/{id}/download	下载报告文件

MCP（根路径，无 /api/v1 前缀）

方法	路径	说明
POST	/mcp	JSON-RPC（tools/list、tools/call 等）

完整字段见 docs/API.md。

---

技术栈

层	选型
前端	React、TypeScript、Vite、Tailwind、shadcn/ui
后端	Go 1.24、chi
结构	Domain → UseCase → Adapter → API
数据库	MySQL 8
对象存储	MinIO（S3 兼容）或本地目录
LLM	DeepSeek（可配），无 Key 时规则引擎
队列	Redis 7（可选）
部署	Docker Compose

---

合规边界

本项目输出为预诊断结果与修复建议，上线前需经专业人员复核。

请勿将此工具的检测结果作为已通过官方合规认证、完全消除合规风险、或替代法律及专业审计意见的凭证。

---

文档

• CHECKLIST.md — 演示验收
• RUNBOOK.md — 排障
• DEMO_SCRIPT.md — 演示话术
• docs/API.md — 接口说明
• docs/DB_SCHEMA.md — 库表设计
• backend/internal/mcp/README.md — MCP 用法