内容
# 合规代理
可审计的流水线，用于收集虚拟PIX法规，提取规则，应用防护措施，比较版本，为RAG编制索引，并通过FastAPI发布JSON/PDF报告。默认流程是本地的，确定性的，不需要AWS账户或LLM调用。
## 目录
- [五分钟评估](#五分钟评估)
- [问题与能力](#问题与能力)
- [交付状态](#交付状态)
- [架构与代理](#架构与代理)
- [存储库结构](#存储库结构)
- [先决条件](#先决条件)
- [使用Docker快速入门](#使用docker快速入门)
- [不使用Docker快速入门](#不使用docker快速入门)
- [配置](#配置)
- [MCP](#mcp)
- [FastAPI和示例](#fastapi和示例)
- [RAG和pgvector](#rag和pgvector)
- [Bedrock和AWS](#bedrock和aws)
- [固定装置和报告](#固定装置和报告)
- [测试和开发](#测试和开发)
- [可观察性、安全性和FinOps](#可观察性、安全性和finops)
- [幂等性和部分故障](#幂等性和部分故障)
- [基于规范的方法和AI辅助](#基于规范的方法和ai辅助)
- [证据和演示](#证据和演示)
- [限制和未来工作](#限制和未来工作)
- [故障排除](#故障排除)
- [在挑战中使用](#在挑战中使用
## 五分钟评估
1. 阅读[可追溯性矩阵](docs/evidence/REQUIREMENTS_TRACEABILITY.md)。
2. 查看[五个图表](docs/architecture/system-context.md)和[技能索引](skills/README.md)。
3. 在[`docs/evidence/api`](docs/evidence/api/)中查看实际答案和[可复制的示例](docs/api/EXAMPLES.md)。
4. 验证`report.json`、`report.pdf`和[SHA-256](docs/evidence/hashes/SHA256SUMS.txt)。
5. 查看[最终验证](docs/evidence/FINAL_VALIDATION.md)、截图和[演示视频](https://drive.google.com/file/d/1PQqJEYo3k3EiJL3TsG2mYkkwP8NMccu8/view?usp=sharing)，在[`VIDEO.md`](docs/demo/VIDEO.md)中记录。
执行：
```powershell
$env:UV_CACHE_DIR = "$PWD\.uv-cache"
uv sync --locked
uv run pytest -q
```
如果没有PostgreSQL，pgvector测试将被忽略；如果Compose运行正常，只有两个AWS实时测试将被忽略。
## 问题与能力
该项目演示了如何将不可靠的监管文档转换为结构化和可追溯的证据：
- 包含50项法规和三个虚拟PDF/HTML文档的模拟目录；
- 使用SHA-256和`new`、`modified`和`unchanged`状态进行收集；
- 使用MCP工具和真实SSE传输的Scraper代理；
- 确定性提取12条规则和PII/prompt注入防护措施；
- 差异、差距分析和显式部分结果；
- 本地确定性块、嵌入、搜索和pgvector；
- 源自同一模型、清单和哈希的JSON和PDF报告；
- 具有`/health`、`/normativos`、`/compliance`、`/search`和`/reports`的FastAPI；
- 使用`botocore.stub.Stubber`测试的Bedrock/S3适配器。
## 交付状态
第2-10阶段的实施已经完成。E2E重现通过，Report Consolidator Agent通过其唯一类型化工具在worker持久化JSON/PDF后触发HTTP发布。项目发布在<https://github.com/andmartins7/compliance-agent>的`main`分支上，提交准备就绪。未执行AWS实时操作。请参阅[STATUS.md](docs/project/STATUS.md)。
## 架构与代理
图表：
- [系统上下文](docs/architecture/system-context.md)；
- [容器](docs/architecture/container-diagram.md)；
- [组件](docs/architecture/component-diagram.md)；
- [管道序列](docs/architecture/pipeline-sequence.md)；
- [本地部署](docs/architecture/deployment-local.md)。
端到端流程：
```text
MCP collect → PDF/HTML extract → guardrails → chunks/embeddings/pgvector
→ diff/gap analysis → JSON/PDF → HTTP注册 → FastAPI查询
```
七个代理分别是Orchestrator、Scraper、Extractor、Compliance Analyzer、Conformance Validator、Knowledge Builder和Report Consolidator。每个代理都有Pydantic输出和专属责任。带有`RunContext`的工具委托给端口和确定性用例；在JSON/PDF持久化后，worker执行Report Consolidator，其唯一工具通过`ReportApiClient`注册报告。Scraper在执行时接收`MCPToolset`。请参阅[技能](skills/README.md)。
Docker工作器使用`McpDocumentCollector`通过SSE消费MCP；它不直接实例化Scraper代理对象。特定代理证明在`tests/integration/test_scraper_agent_mcp.py`中。
## 存储库结构
```text
src/compliance_agent/ 域、应用程序、代理、端口、适配器、API
fixtures/ 虚拟目录和文档
specs/ 需求、合同、架构和ADR
skills/ 代理的七个操作合同
tests/ 单元测试、集成测试、E2E测试、Docker测试和文档
docs/ 操作、架构、API、演示和证据
infra/docker/ SQL初始化和环境示例
scripts/ 固定装置生成和演示
```
## 先决条件
- Python 3.12；
- `uv`；
- 用于pgvector/containerized证明的Docker引擎和Docker Compose；
- 用于演示脚本的PowerShell 7或POSIX shell。
确切的Python版本在`pyproject.toml`中受限；依赖项在`uv.lock`中。Docker使用Python 3.12.11精简版、PostgreSQL 16和`pgvector/pgvector:0.8.0-pg16`。
## 使用Docker快速入门
PowerShell：
```powershell
Copy-Item infra/docker/.env.docker.example .env
$env:CA_POSTGRES_PASSWORD = Read-Host "临时本地密码" -MaskInput
docker compose --project-name compliance-demo build
docker compose --project-name compliance-demo up -d
docker compose --project-name compliance-demo --profile worker run --rm worker
Invoke-RestMethod http://127.0.0.1:8000/health
Start-Process http://127.0.0.1:8000/docs
Invoke-RestMethod "http://127.0.0.1:8000/search?query=autenticacao&limit=3"
docker compose --project-name compliance-demo down -v
Remove-Item -LiteralPath .env
```
POSIX shell：
```bash
cp infra/docker/.env.docker.example .env
read -rsp "临时本地密码： " CA_POSTGRES_PASSWORD && echo
export CA_POSTGRES_PASSWORD
docker compose --project-name compliance-demo build
docker compose --project-name compliance-demo up -d
docker compose --project-name compliance-demo --profile worker run --rm worker
curl -fsS http://127.0.0.1:8000/health
curl -fsS 'http://127.0.0.1:8000/search?query=autenticacao&limit=3'
docker compose --project-name compliance-demo down -v
rm .env
```
`.env`文件被忽略。不要在本地环境之外重用密码。
## 不使用Docker快速入门
```powershell
$env:UV_CACHE_DIR = "$PWD\.uv-cache"
uv sync --locked
uv run python -m compliance_agent.cli worker --run-id local-demo
uv run python -m compliance_agent.cli api --host 127.0.0.1 --port 8000
```
如果没有`CA_PGVECTOR_DSN`，worker在启用RAG时使用内存向量存储。API的报告注册表也是内存中的，重启后清空。
## 配置
复制`.env.example`仅供参考。前缀为`CA_`。重要的本地默认值：
| 变量 | 用途 |
|---|---|
| `CA_AWS_ENABLED=false` | 禁止AWS组合 |
| `CA_CHAT_PROVIDER=test` | 替代模型 |
| `CA_EMBEDDING_PROVIDER=local` | 确定性嵌入 |
| `CA_STORAGE_BACKEND=filesystem` | 本地工件 |
| `CA_ENABLE_RAG` | 启用索引 |
| `CA_PGVECTOR_DSN` | pgvector连接；永不记录值 |
| `CA_COLLECTION_BACKEND` | `local`或`mcp` |
| `CA_MCP_SERVER_URL` | SSE端点 |
| `CA_API_PUBLISH_ENABLED` | worker的HTTP注册 |
AWS凭证仅遵循标准SDK链，不属于版本控制文件。
## MCP
FastMCP公开`collect_normatives`。有三个不同的证据：
- 使用`MCPToolset`的Scraper代理对象：`test_scraper_agent_mcp.py`；
- 使用真实SSE的客户端/服务器：`test_mcp_sse_transport.py`；
- 使用`McpDocumentCollector`的Docker工作器：`run_worker.py`、Compose和演示日志。
Scraper代理没有静默回退到本地源。
## FastAPI和示例
Swagger：`http://127.0.0.1:8000/docs`。
| 方法 | 路径 | 目的 |
|---|---|---|
| GET | `/health` | 无外部调用的健康检查 |
| GET | `/normativos` | 分页和过滤规则 |
| GET | `/compliance` | 合规性结果 |
| GET | `/search` | RAG搜索 |
| POST | `/reports` | 幂等注册 |
| GET | `/reports` | 注册列表 |
| GET | `/reports/{report_id}` | 详细信息或404 |
| GET | `/openapi.json` | OpenAPI合同 |
`curl`、PowerShell和Python示例，包括404/409/422/503，位于[EXAMPLES.md](docs/api/EXAMPLES.md)。`X-Request-ID`关联请求；`Idempotency-Key`由HTTP发布客户端发送。搜索的必需合同为`GET /search?query=...`，使用`SearchQuery`/`SearchResponse`实现并在Swagger/OpenAPI中记录。
## RAG和pgvector
`ChunkContent`生成确定性ID和哈希。`IndexContent`重用嵌入，删除过时块，并通过`VectorStore`端口进行更新。`SearchContent`在不使用LLM的情况下返回具有出处和充分性的命中结果。Compose提供PostgreSQL/pgvector；除了它之外，存在`InMemoryVectorStore`。
## Bedrock和AWS
### 无AWS账户执行
无需额外操作：保持`CA_AWS_ENABLED=false`、`CA_CHAT_PROVIDER=test`、`CA_EMBEDDING_PROVIDER=local`和`CA_STORAGE_BACKEND=filesystem`。
`AWSClientFactory`、`ModelFactory`、`BedrockEmbeddingProvider`、`S3RawDocumentStorage`和`S3ReportArtifactStore`是具有可注入客户端的真实适配器。测试使用`Stubber`；没有实际调用Bedrock或S3，并且不声称生产兼容性。实时测试需要显式标志，默认情况下跳过。
OpenSearch、SQS、SNS、EventBridge和AWS部署未实现。
## 固定装置和报告
`fixtures/normative_catalog.json`包含恰好50条模拟记录。清单引用两个HTML和一个PDF，全部为虚拟的，结果为12个`NormativoItem`。代表性报告位于[`docs/evidence/reports`](docs/evidence/reports/)，包含清单、摘要和哈希。
## 测试和开发
```powershell
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest -q
```
在2026-07-27的验证中，Ruff/格式化/锁定通过；`uv run mypy`在测试中失败，出现89个错误，但`uv run mypy src/compliance_agent`通过。请在使用命令作为批准门槛之前查看证据。
使用pgvector：
```powershell
$env:CA_PGVECTOR_DSN = Read-Host "临时本地DSN"
uv run pytest tests/integration/test_pgvector_store.py tests/integration/test_pgvector_search_api.py -q
```
永远不要将DSN记录在日志或证据中。已执行的输出结果在[FINAL_VALIDATION.md](docs/evidence/FINAL_VALIDATION.md)中。
## 可观察性、安全性和FinOps
请参阅[OBSERVABILITY.md](docs/operations/OBSERVABILITY.md)、[FINOPS.md](docs/operations/FINOPS.md)和[最终安全审查](docs/security/FINAL_REVIEW.md)。日志关联`run_id`、`request_id`、阶段、状态和持续时间，无完整内容。防护措施在索引之前检测PII和提示注入。端口是环回的，容器是非根/只读的，示例中不包含机密。
未测量AWS成本；不声称零成本。本地流程避免付费调用，重用哈希/嵌入并强制限制。
## 幂等性和部分故障
保证是分开的：
- 收集：SHA-256标识不变内容；
- 块/嵌入：确定性ID和重用；
- pgvector：按ID更新；
- HTTP：相同的`run_id`和哈希重用注册；不同内容返回409；
- 工件：相同的密钥和字节重用；不同字节冲突；
- 完整管道：重复相同的`run_id`可能因故意冲突的工件存储而终止`PARTIAL`。
因此，不声称完全的幂等性。非致命故障保留结构化警告/错误；防止性防护或不安全工件不会被隐藏。
## 基于规范的方法和AI辅助
工作从`specs/`和`docs/project/`中的需求、验收标准、合同、ADR和决策开始。Codex被用作执行和实现/文档助手。AI辅助代码提交到与预期的人工审查、类型检查和测试相同的测试中；不声称完全手动作者身份。
采用的技术来源是Pydantic AI、AWS SDK/Bedrock/S3、MCP/FastMCP、FastAPI、pgvector、PostgreSQL、Docker和uv的官方文档。工作流程、转换、解析和持久化在确定性代码中；LLM不控制顺序或效果。
## 证据和演示
- [证据索引](docs/evidence/README.md)；
- [需求→实现→测试→证据矩阵](docs/evidence/REQUIREMENTS_TRACEABILITY.md)；
- [环境](docs/evidence/ENVIRONMENT.md)；
- [最终验证](docs/evidence/FINAL_VALIDATION.md)；
- [5-8分钟脚本](docs/demo/DEMO_SCRIPT.md)；
- [演示视频](https://drive.google.com/file/d/1PQqJEYo3k3EiJL3TsG2mYkkwP8NMccu8/view?usp=sharing)及其[验证记录](docs/demo/VIDEO.md)；
- `scripts/demo.ps1`和`scripts/demo.sh`。
截图和视频是真实证据。MP4仍然外部托管，不集成到Git仓库中。
## 限制和未来工作
- 发布在官方仓库的`main`分支上；
- HTTP发布由Report Consolidator Agent执行：其唯一类型化工具委托给`ReportApiClient`，而worker仅组合依赖并在JSON/PDF持久化后启动执行；
- 未执行AWS实时操作；
- 内存HTTP注册表；
- MVP范围外的身份验证/授权；
- OpenSearch、消息传递和AWS部署未实现；
- 本地嵌入是双精度，不衡量Bedrock语义质量；
- 仅当提供者提供时，才有token/成本指标。
可能在本次挑战之外进行的未来工作：持久化注册表、身份验证、AWS基础设施和受控的实时测试。
## 故障排除
- `CA_POSTGRES_PASSWORD必须设置`：在Compose之前导出本地密码。
- `/search`返回503：未组合搜索后端；使用Compose或配置`CA_PGVECTOR_DSN`。
- 跳过pgvector测试：未配置测试DSN。
- worker返回`1`：检查净化日志；重复相同的`run_id`，具有不同工件可能会产生`PARTIAL`。
- Windows上的缓存/权限错误：为可写目录设置`UV_CACHE_DIR`、`TEMP`和`TMP`。
- 端口占用：使用另一个项目/端口或仅删除为演示创建的Compose。
## 在挑战中使用
项目专门为技术评估准备，使用虚拟数据。除挑战上下文外，不声明其他许可证；请在重复使用或分发前确认选择过程的条款。
