TaskGuard_Agent 是一个面向 OnCall 场景的智能运维 Agent。项目使用 GoFrame + CloudWeGo Eino 构建单体 Go 服务,将真实火山方舟模型、Milvus 检索、工具调用、MySQL Trace 和自动评测放进同一条可复现链路。
Request Validation / Bearer Auth
-> Session Memory + Prompt Injection Guard
-> Query Analyzer + Adaptive Strategy
-> Doubao-embedding-vision (text input) + Milvus Retrieval
-> Multi-query / HyDE / Rerank / Corrective Retrieval
-> 简单问题使用 Direct RAG / 多跳与 AIOps 使用受控 Plan-Execute-Evaluate-Replan
-> DeepSeek-V4-flash + Shared Tool Registry
-> Groundedness Check / Repair / Refusal
-> MySQL Persistent Trace
-> Structured Chat / SSE / AIOps Response
Chat、SSE、AIOps 和 E2E 共用 internal/ai/runtime。Demo Mode 只替换 Retriever/Generator 数据源,不维护另一套业务逻辑。
- Chat、Agent、Planner、Replanner、Judge:火山方舟
DeepSeek-V4-flash模型deepseek-v4-flash-260425。 - Embedding:火山方舟
Doubao-embedding-vision推理接入点,使用多模态接口的纯文本输入和 2048 维向量。 - 密钥与接入点只从环境变量读取:
ARK_API_KEY
ARK_CHAT_ENDPOINT_ID
ARK_EMBEDDING_ENDPOINT_ID
TASKGUARD_API_TOKEN
仓库、YAML、Trace 和报告不会保存明文 Key 或 Endpoint ID。报告仅保存 Endpoint 的 SHA256 短摘要。
- 40 篇正式 Runbook、12 篇干扰文档、160 条 E2E Case,全部由受版本控制的 Catalog 生成和校验。
- 文档清洗、去重、多级 Markdown Chunk、Overlap、内容哈希、稳定 Chunk ID、版本和告警元数据。
naive / multi_query / hyde / corrective / adaptive检索策略及 Self-RAG Lite groundedness。- Chat、Stream、AIOps 返回引用、证据、策略、置信度、Loop 摘要、Trace、失败类型、Token 和延迟。
- Prometheus、内部文档、当前时间、MySQL 只读和可选 MCP 日志共享 Tool Registry。
- MySQL SQL AST 白名单、服务端只读 DSN、单语句、强制最多 100 行和 8 秒超时;模型不能传入 DSN 或启用写操作。
- Prompt Injection / 危险 SQL / 高风险执行请求 / 跨会话越权拦截、会话隔离、并发限制、60 秒请求预算、6000 Token 输入预算、最多 3 次 Replan、12 个执行步骤、8 次工具调用、重复调用阻断、429
Retry-After退避和模型熔断;前端在写入 DOM 前清洗模型 Markdown。 - MySQL 持久化
agent_runs / agent_steps / agent_citations,默认 TTL 7 天。 - Go E2E 确定性评测 + Ragas 语义评测 + 自动质量门禁。
- Docker Compose、Linux CI Race、Secret Scan、Fixture 和前端 Trace/AIOps 可视化。
data/
├── runbooks/ # 40 篇正式手册
├── distractors/ # 12 篇检索干扰文档
└── registry/
├── sources.yaml # URL、许可证、日期、变换方式和摘要哈希
└── facts/ # 重新整理的公开技术事实摘要
重新生成并验证:
go run ./cmd/dataassets
go run ./cmd/dataassets -check生成器会安全重建自己的目录,并检查精确数量、Case 分布、必需章节、来源、SHA256 和文档重复度。
先在 Windows 用户环境或当前终端设置四个变量,再执行:
docker compose up --build -d日志 MCP 默认读取 testdata/logs 中 20 套故障场景、50,000 条真实格式脱敏日志。通过 LOG_SOURCE=local 可读取 manifest/docker/volumes/logs,通过 LOG_SOURCE=cls 可查询腾讯云 CLS。完整说明见 docs/DEPLOYMENT.md。
服务:
- Frontend:
http://127.0.0.1:8080 - Backend:
http://127.0.0.1:6872 - Swagger:
http://127.0.0.1:6872/swagger/ - Attu:
http://127.0.0.1:8000(使用docker compose --profile admin up -d attu启动) - Milvus:
127.0.0.1:19530 - MySQL:
127.0.0.1:3307(可通过TASKGUARD_MYSQL_PORT修改,容器内仍使用mysql:3306)
Compose 会先启动 Milvus、MySQL 和 Fixture,再通过 indexer 使用真实 Doubao-embedding-vision 纯文本向量索引 52 个知识文件,最后启动后端和前端。
公网部署使用 Caddy 自动 HTTPS,并收回所有基础设施端口:
docker compose -f manifest/docker/docker-compose.yml -f manifest/docker/docker-compose.prod.yml up --build -d公网部署与 K8s 取舍见 docs/DEPLOYMENT.md 和 docs/KUBERNETES.md。
Windows Docker Desktop 在中文路径下可能触发 Buildx Session Header 问题;Linux CI 使用 ASCII 工作目录执行完整构建。遇到该问题可把仓库放到 ASCII 路径,或临时使用经典 builder。
Go 构建镜像默认使用 https://goproxy.cn,direct 下载模块,可通过 Docker build arg GOPROXY 覆盖。
Demo Mode:
go run .
cd frontend
npm start真实模式需设置:
TASKGUARD_DEMO_ENABLED=false
TASKGUARD_TRACE_DSN
TASKGUARD_OPS_DSN
MILVUS_ADDRESS
PROMETHEUS_BASE_URL
MCP_URL
真实模式未配置持久化 Trace 时启动会失败;Demo 允许降级为 memory_degraded。
| Method | Path | Description |
|---|---|---|
| POST | /api/chat |
真实 RAG + Agent 对话 |
| POST | /api/chat_stream |
message / metadata / done / error SSE |
| POST | /api/upload |
清洗、切分并索引文档 |
| POST | /api/ai_ops |
可传 id/question 的多步告警调查 |
| GET | /api/health |
模型、Milvus、工具和 Trace 状态 |
| GET | /api/trace/{id} |
查询持久化 Agent Trace |
| GET | /api/eval/latest |
读取完整真实评测报告摘要;无报告时不返回样例分数 |
真实模式请求需携带:
Authorization: Bearer <TASKGUARD_API_TOKEN>
前端钥匙按钮会将 Token 仅保存到当前浏览器的 sessionStorage。
快速离线回归:
go run ./eval/offline -golden eval/golden_questions.jsonl -docs data/runbooks它只做本地词法检索,不调用 Milvus、模型或工具,不能称为 Agent 正确率。
真实 E2E:
go run ./cmd/e2e_eval
python eval/ragas/run_ragas.py
go run ./cmd/merge_eval或:
docker compose --profile eval run --rm evalRagas 中断后可复用同一份 E2E 报告和逐 Case 检查点:
EVAL_RESUME=true docker compose --profile eval run --rm evalE2E 强制关闭 Demo,调用真实 HTTP API、DeepSeek、Doubao、Milvus 和工具,并回查持久化 Trace。每条 Case 的工具顺序、健康工具成功率和延迟预算都是确定性断言。Ragas 使用同一个 DeepSeek Endpoint 作为 Judge,温度为 0;每个 Case 运行三次,波动大于 0.15 时补两次,仍不稳定则失败并标记 same_model_judge / judge_unstable。报告保存原始轮次和具体不稳定指标,断点续跑同时校验完整 E2E 输入 SHA256。
报告输出:
eval/reports/e2e_latest.json
eval/reports/e2e_latest.md
eval/reports/e2e_latest.csv
当前真实基线(2026-07-13,数据集 SHA256 b31417da2222c0d39cbdfa3f1da0bd67a5dd422539dec2365e367117005e95e3):
- 160/160 Case 通过确定性 Ground Truth;任务完成率、工具选择/参数/顺序、健康工具成功率、引用 Precision/Recall/F1、groundedness、拒答、安全和 Trace 持久化均为
100%。 - P50
8892 ms,P9526393 ms,总 Token297833。 - 160 个唯一 Trace ID 均从 MySQL 回查成功;68 条多跳/工具回答记录了
answer_repair=verified_evidence_only。 - Ragas 已真实接入并保存原始轮次与波动指标;同模型 Judge 在多跳和工具 Case 上存在明显随机波动,因此当前只作为语义诊断,不宣称 160 条语义门禁全绿。
- 代表性语义结果见
eval/reports/RAGAS_REPRESENTATIVE.md。
如需自动估算人民币调用成本,按方舟控制台当期价格配置:
TASKGUARD_INPUT_CNY_PER_MILLION_TOKENS
TASKGUARD_OUTPUT_CNY_PER_MILLION_TOKENS
未配置单价时报告明确标记成本不可用,不猜测或写死价格。
质量门槛包括 E2E Accuracy、任务完成率、工具选择/参数准确率、groundedness、引用准确率、拒答、安全、工具成功率和 160/160 Trace 持久化。确定性阶段不会提前阻断 Ragas;最终合并始终先生成 JSON、Markdown、CSV 和失败分类,再以非零状态报告门禁失败。Judge 初始化或单 Case 调用失败记为 judge_error,不得跳过或伪造分数。简历基线只引用已完整通过的确定性指标;Ragas 未全量通过时只披露为诊断结果。
go test ./...
go vet ./...
node --check frontend/app.js
go run ./cmd/dataassets -check
docker compose config --quiet
./scripts/secret-scan.ps1Windows 本机 MinGW Race 运行时可能以 0xc0000139 无法启动;.github/workflows/ci.yml 在 Linux 执行 go test -race ./... 作为正式门禁。