Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

TaskGuard_Agent

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 覆盖。

本地 Go 启动

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。

API

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 eval

Ragas 中断后可复用同一份 E2E 报告和逐 Case 检查点:

EVAL_RESUME=true docker compose --profile eval run --rm eval

E2E 强制关闭 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,P95 26393 ms,总 Token 297833。
  • 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.ps1

Windows 本机 MinGW Race 运行时可能以 0xc0000139 无法启动;.github/workflows/ci.yml 在 Linux 执行 go test -race ./... 作为正式门禁。

文档

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages